Skip to content
coreyjames-aiPublic

About

A governed work-order control plane for teams of AI engineering agents · cost attribution for AI work, C++ and native ports with parity proof, evidence-gated acceptance, separation of duties for AI work

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AgentOS

A governed work-order control plane for teams of AI engineering agents

Canonical: https://coreyjames.ai/systems/agentos/
Author: Corey James · Published: 2026-10-28 · Kind: system
DOI: https://doi.org/10.5281/zenodo.23735120
Technologies: Agent Client Protocol (ACP) · Bash · Budget enforcement and cost governance · Cargo · Contract-first interface design · Cost attribution for AI work · Credential brokering and secrets management · Declarative tool and agent definition · Docker · Git · Governed AI-assisted software engineering · Grafana · Idempotency, exactly-once effects and crash recovery · Independent verification and adversarial review · JSON Schema · JSON Web Token (JWT) · Large-scale refactoring with parity proof · Linux security primitives · Model Context Protocol (MCP) · Multi-agent system architecture and orchestration · Network egress confinement · Observability and alerting · Policy-as-code enforcement · PostgreSQL · Prometheus · Python · Redis · Rust · SQL · Schema and migration discipline · Site reliability engineering · State-machine design for multi-agent workflows · Static analysis as tests · Tokio · Unix domain sockets · Vendor-integration reverse engineering · YAML · systemd · tmux
Skills: cost attribution for AI work · agent orchestration · multi-agent governance · separation of duties for AI work

AgentOS

Result

Figure What it measures
246 work orders governed, including the programs that built most of this site
106 hook modules across eleven lifecycle events, each a refusal
31,811 metered usage entries tied to the work that spent them
< 5 s for another worker to resume a failed one from the graph

AgentOS: overview

What was built

My long autonomous coding runs all failed the same way. The lead agent had to hold the operating procedure, the plan, every teammate's state and every piece of evidence in its context, and past some horizon it dropped one of them. The work then diverged quietly. I stopped treating that as a prompting problem. It is working-memory overflow, and the cure is to take the memory out of the model. AgentOS is the control plane I built on that diagnosis. The authoritative state of every engineering program lives in a PostgreSQL work graph. Each agent receives a small, freshly rendered, contract-bound job. Policy is enforced by machinery that refuses forbidden actions. Work closes only when an independent reviewer has the evidence. The agents that built AgentOS worked under it.

The idea

A relational work graph is the only source of truth: systems, projects, work orders, acceptance criteria, tasks, evidence, review findings, amendments and cost. Every Markdown view is a generated projection of that graph, and edits to projections are discarded, because two sources of truth give drift a place to hide.

Every agent job is small, rendered at dispatch time from exactly the slice of state it needs, and bound to a schema that says what must come back. Nothing is carried from job to job inside a model's head, so models are swappable and a crash loses nothing that matters.

Rules are enforced by hooks on the agent runtime. A lead agent cannot re-type or edit an artifact; it routes files and renders decisions. A hook may never report an operation that did not happen. Those are refusals, and no prompt has to remember them.

Judgment is independent. Delivered work is checked by quality reviewers, accepted by a gatekeeper that takes only delivered facts, and challenged by an adversarial reviewer on a different vendor's model. The builder never judges its own work.

Figure 1

What I built

A deterministic transition runtime advances work-order state only through compiled transitions, so the same inputs produce the same state and every move leaves a receipt.

A hook layer over the coding agents' own command-line tools turns policy into refusals.

An independent review stack separates builders, quality reviewers, the gatekeeper and the adversarial reviewer into distinct seats, with follow-up review bound to a frozen set of findings so it converges instead of re-litigating forever. The design is in Separation of duties for AI work.

Recovery machinery rebuilds an agent's working picture from the graph after a crash or a context compaction, and replaces a broken session without losing the work order's state.

A managed team runtime launches provider-neutral agent seats in containers through my agent runtime, with signed events and per-seat cost attribution, exposed to agents and operators as MCP tools.

Around those: cost attribution per work order; runtime observability; a helpdesk channel for defects in the harness itself; long-running standing work orders fed by inbound events; and provider adapters that run real interactive sessions of vendors' authenticated command-line tools under my own logins.

Seven questions

An organisation that runs AI workers has to be able to answer, for any piece of work: who did it, why was it allowed, what grounding was used, what changed, what evidence exists, what did it cost, and can you trust it. AgentOS answers all seven from the work graph in seconds, because each answer is a query over rows the system wrote rather than a reconstruction after the fact. A conversation with the platform compiles into two things, a governed execution system and the governance around it: the work order is the source program and the governed execution is the compiled program.

Who did it

One real program on this platform shows what that graph holds. One work order has been stood down and resumed eight times with the same state producing the same bytes. The economics of that program are in What the work cost, to the penny.

One program, as the graph holds it

Reacting to the world

Every team lead and seat has a mailbox, scoped to its team, with identities derived on the server from the authenticated participant. External systems register as event sources against a work order, so a signed webhook from a payments, email or social-publishing provider becomes a governed event in the owning lead's mailbox and then a finite task. A work order can keep an open-ended envelope, a standing lead that admits tasks as events arrive and brings specialists online on demand, so continuous operation is composed from the same machinery as a bounded program. The idea is Agents that react to the world.

Figure 4

The judgment in it

I made Markdown a projection on purpose, because agents and humans both like editing a plan file and that is exactly where two truths come from.

Figure 5

It made the lead feel slower and removed a whole class of silent corruption.

I spent weeks stabilising the control plane when a prompt-only approach would have worked for a day at a time. Several of my written rulings from that period, such as anchoring quality checks to lifecycle state and treating prose as a medium for behaviour only, are still the doctrine it runs on.

I held a platform build open for two weeks against the agents' own "done" until every close item had an independent verdict. That one is Closed by evidence.

What it demonstrates

Control-plane and state-machine architecture, PostgreSQL schema design at scale, and the judgment to turn a recurring failure of AI agents into rules a platform enforces. The programs AgentOS has run are the proof: a native port, bit-identical in every parity cell, in under three weeks, an API platform closed all 23 of its close items under independent review, a fine-tuned model with a frozen evaluation.

Stories

Why long agent runs fail · Closed by evidence · Separation of duties for AI work · Directing AI coding agents at program scale · What the work cost, to the penny

Technologies

Rust · PostgreSQL · JSON Schema · Model Context Protocol · Agent runtime hook systems · Multi-agent orchestration · Separation-of-duties review design · systemd

I forbade the most capable agent in the system from touching deliverables.

What was verified

Each line is a claim the canonical page supports, with the figure as the page states it.

  • Agent orchestration: a PostgreSQL work graph as the only source of truth for teams of AI coding agents, each given a small contract-bound job rendered at dispatch, across 246 work orders.
  • Multi-agent governance: policy turned into refusals by 106 hook modules across eleven lifecycle events on the coding agents' own command-line tools, so a lead agent cannot edit an artifact.
  • Separation of duties for AI work: builders, quality reviewers, a gatekeeper and an adversarial reviewer on a different vendor's model in distinct seats; an API platform closed all 23 of its close items under independent review.
  • Cost attribution for AI work: 31,811 metered usage entries tied to the work that spent them, and in one program 3.197 billion tokens attributed to the penny across 11,193 priced model calls.
  • Control-plane and state-machine architecture: a 546,000-line Rust control plane whose transition runtime gives the same state from the same inputs; a failed worker is resumed from the graph in under 5 s.
  • Event-driven agent systems: per-seat mailboxes scoped to the team, with signed webhooks from payments, email or social-publishing providers turned into governed events and finite tasks for the owning lead.

Related

Skills demonstrated

Decided at build time against every page in this system, strongest first; each links to the page that earns it.

Engineering stories in AgentOS (5)

Story Result Figure
Why long agent runs fail Diagnosing agent drift as working-memory overflow, and building the control plane that holds the state instead 246
Closed by evidence Building an API integration platform through gated AI work orders, and refusing to close it until every item had independent proof 23 of 23
Separation of duties for AI work Independent gatekeepers, reviewers from a different vendor, and failures that stay failures 27
Directing AI coding agents at program scale How I run engineering programs with teams of frontier and open-source models, and why evidence, not the agents, decides 3
What the work cost, to the penny One real engineering program, attributed to the penny, and a cache discipline that returned four-fifths of the bill 11,193

Part of Corey James's portfolio: research, technologies, skills and the other systems. Canonical site: https://coreyjames.ai/

Citation

Corey James. "AgentOS." coreyjames.ai, 2026. https://coreyjames.ai/systems/agentos/ In: the AgentOS technical report, doi:10.5281/zenodo.23735120.

@misc{coreyjames-agentos,
  author = {Corey James},
  title = {AgentOS},
  year = {2026},
  howpublished = {\url{https://coreyjames.ai/systems/agentos/}},
  note = {GitHub copy: https://github.com/coreyjames-ai/agentos},
  doi = {10.5281/zenodo.23735120}
}

Part of AgentOS and Corey James's portfolio · site: https://coreyjames.ai/ · MCP server: https://coreyjames.ai/mcp · agent card: https://coreyjames.ai/.well-known/agent.json

About

A governed work-order control plane for teams of AI engineering agents · cost attribution for AI work, C++ and native ports with parity proof, evidence-gated acceptance, separation of duties for AI work

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors