Agent Airlock

Transactional middleware that lets AI agents explore safely and makes only validated outcomes real.

Comment

The problem

A disposable Agent container is not the same as disposable Agent state.

Persistent coding Agents also mutate workspaces, conversation memory, databases, and external-action queues that outlive one Runtime. If execution fails after only some of those resources change, the next Run can inherit a split and unsafe reality. Logs can explain the damage afterward, but they cannot stop partial Agent work from becoming accepted state.

What Agent Airlock does

Agent Airlock adds a transactional execution boundary around the CodeJam starter kit's shared AgentRunner seam.

Every Agent Run receives isolated Candidate State across its workspace, Codex session, SQLite snapshot, and typed-action outbox. The Runtime never receives a mutable Canonical State path.

After execution, a versioned Outcome Contract evaluates the complete Candidate with deterministic, bounded, and redacted Validations:

  • A passing Candidate is installed as one immutable version, and an atomic canonical manifest makes it accepted reality.
  • An invalid Candidate is quarantined with evidence while Canonical State remains unchanged.
  • A bounded Repair Run can continue from retained work using the exact failure evidence, original contract, verified Canonical reference, and a fresh outbox.
  • Supported external effects become claimable only after Promotion and carry stable idempotency keys.

Why this is Track 1 middleware

Airlock is one reusable platform-level capability applied to every Agent Run, not custom logic for one Agent and not a UI-only simulation.

It preserves the starter kit's Agent CRUD, lifecycle controls, Playground chat, persistent workspaces, persistent Codex sessions, model execution, Fastify control plane, and disposable local Runtime. It extends the narrow shared seam where AgentService delegates to AgentRunner.

The proof exercises the capability end to end through the production React UI, Fastify backend, real Codex process, disposable container, file and SQLite data paths, Validation, Promotion, Quarantine, Repair, and durable evidence.

What is innovative

Most Agent safety layers try to predict or block individual commands before execution. Agent Airlock instead evaluates the resulting Whole-Agent future before it becomes accepted reality.

One disposition covers files, Agent memory, SQLite data, and supported external effects, so a Run cannot promote a file while silently retaining rejected memory or data. Quarantine remains useful state because exact failure evidence can seed a bounded Repair child without contaminating Canonical State.

A Promotion journal makes an approved decision recoverable after interruption. Signed portable receipts and an offline browser verifier prove the rejected-parent to promoted-Repair lineage and the exact Canonical State handoff. Signatures remain evidence and never become Promotion authority.

Working end-to-end demo

The demo starts with a runnable Real Runtime Proof Agent in the starter-kit Playground. One production UI action creates three fresh persisted Runs:

  1. The first Run mutates an isolated file and SQLite row, prepares a deferred notification, passes every required Validation, promotes all four transactional resources together, advances the Canonical fingerprint, and releases the effect only after Promotion.
  2. The second Run creates an unsafe Candidate. Its required content Validation fails, so the full Candidate is quarantined, zero effects are delivered, and the Canonical fingerprint remains identical.
  3. The third Run repairs the retained Candidate, passes every required Validation, promotes the repaired state, and delivers a fresh idempotent effect after Promotion.

The final view opens the exact signed decision chain in a browser-local verifier. It makes zero API calls, verifies both signatures and the parent digest, and proves the Canonical State handoff. The Agent remains READY and can continue in the Playground after recovery.

Technical execution

Agent Airlock uses:

  • TypeScript 5.9 and Node.js 22
  • React 19.2 and Vite 7.2
  • Fastify 5.6
  • Zod 4.1
  • SQLite through Node.js node:sqlite
  • Docker, Colima, or Podman for the disposable Runtime
  • OpenAI Codex CLI 0.111.0 pinned inside the Runtime image
  • SHA-256 commitments and Ed25519 receipt verification
  • Playwright, Vitest, and GitHub Actions
  • Repository-owned Transactional Resource SDK, HTTP Object Resource, and Portable Promotion Receipt packages

Automated coverage includes success, rejection, Repair, restart reconciliation, interruption, tampering, redaction, stale evidence, exact Run binding, effect ordering, signed lineage, and fail-closed proof publication.

Feasibility and reproducibility

The complete proof runs locally on a laptop with Node.js, Chrome, and Docker, Colima, or Podman:

git clone https://github.com/Kk120306/agent-airlock.git
cd agent-airlock
npm install
npm run prove:runtime -- --reset --json
npm run prove:runtime -- --reset --headed

The canonical path is credential-free and deterministic because only remote inference is replaced by a local Responses-protocol fixture. The React UI, Fastify server, AgentService, AgentRunner, pinned Codex CLI, disposable container, file and SQLite mutations, persistent session, outbox, Validation, Promotion, Quarantine, Repair, and verification paths remain real.

BytePlus ModelArk's Responses-compatible API is supported as an optional conformance path when free capacity is available. No paid inference, wallet, RPC request, or public blockchain transaction is required for the core proof.

Impact

Agent builders gain a reusable safety boundary without rewriting every Agent or forcing operators to approve every low-level command. Operators can inspect rejected futures, understand the decisive Validation, recover useful work, and prove accepted state did not change.

Platform teams can add new Transactional Resource Providers behind the same lifecycle contract instead of building resource-specific rollback logic into every Agent. The approach applies to coding Agents today and generalizes to persistent Agents coordinating documents, records, queues, and supported external actions.

Deliberate limitations

  • Exactly-once delivery ends at the supported atomic local consumer and is not a distributed transaction with arbitrary providers.
  • Unrestricted Runtime traffic outside the typed outbox is not transactionally controlled.
  • The Promotion journal targets one local control-plane process and does not claim distributed consensus or power-loss durability.
  • Ordinary containers are not hardened multi-tenant isolation.
  • The core demo proves transactional Agent execution and recovery, not model quality or current provider availability.

Links

Built With

Share this project:

Updates