PaperClipAI/packages/paperclip-runner/docs/capability-live-runnerd-codex.md

Capability live runnerd and Codex loop

Reference lab, not the production sandbox topology. This API remains the runner-lab/session implementation used by UI and recovery tests. Production sandbox execution and live protocol evals use the Rust-owned bridge described in the runner architecture: external control plane → PRP → one Rust paperclip-runnerd → provider. The TypeScript dispatcher below does not run in the sandbox.

Capability binds the provider-neutral semantic catalog to a real package-local paperclip-runnerd process and a real Codex app-server session. Paperclip data remains deterministic mock state behind ControlPlanePort; no request reaches the Paperclip API.

Process and authority boundary

The process chain is:

CapabilityLiveSession -> paperclip-runnerd -> codex app-server
                  -> CapabilitySemanticDispatcher -> ControlPlanePort mock

paperclip-runnerd owns the Codex child and proxies newline-delimited JSON-RPC over stdio. The transport starts a dedicated Unix process group. Normal close, stop/reset cleanup, and fatal protocol errors terminate that group with a bounded TERM/KILL sequence so a Codex child is not abandoned.

Only the allowlisted Codex host environment is copied. PAPERCLIP_* variables, provider credentials other than Codex's server-side home, and credentialed proxy URLs are not passed to runnerd or Codex. Model-issued commands still use the separate skillless, network-disabled workspace permission profile.

Stable session API

Production workers import the live entrypoint and bind a durable store to the attempt's immutable authority tuple:

import {
  CapabilityLiveSessionService,
  DurableCapabilityLiveSessionStore,
} from "@paperclipai/paperclip-runner/live";

const binding = { sessionId, runId, companyId, actorId, taskId };
const store = new DurableCapabilityLiveSessionStore({ directory, binding });
const service = new CapabilityLiveSessionService({ store });
const session = await service.create({ ...binding, attemptId, workingDirectory });
const turn = await session.sendMessage("Read the mock task and report progress.");
await session.interrupt(); // only when a turn is active
await service.stop(session.id);

After a worker terminates, a new worker must construct a new service and use the production resume entrypoint. It must not call create again:

const resumed = await new CapabilityLiveSessionService({ store }).resume({
  sessionId,
  attemptId: resumeAttemptId,
  resumeOf: killedAttemptId,
});
await resumed.reconcileActiveTurn();

resume first commits the killed attempt as terminated and the successor as running. Only then does it start runnerd, read the checkpointed provider thread, and resume that exact thread. A missing or corrupt checkpoint, authority binding mismatch, attempt-lineage mismatch, or provider thread/session drift fails closed. The killed attempt and its usage remain immutable.

The handoff surface for later tracks is:

• create(input) starts runnerd, Codex, one mock run, and one dynamic-tool thread.
• sendMessage(text) supports repeated turns on the same provider thread.
• pendingInteractions() and resolveInteraction(input) preserve typed human interactions and return their results to that same thread.
• reconnect(sessionId) closes the old process group, starts a fresh runnerd and Codex app-server, then reads and resumes the persisted provider thread.
• restore(sessionId) recreates mock state, transcript, authority, authorization records, pending interactions, and the provider thread from a stored snapshot.
• resume({ sessionId, attemptId, resumeOf }) is the cross-worker production path and records distinct linked attempts before provider recovery.
• recordUsage(receipt) durably commits an attempt-bound, exactly-once provider response receipt before the caller acknowledges that response. Reusing a receipt with different contents fails closed.
• reconcileActiveTurn() interrupts and records the terminal fact for a turn that was active in the checkpoint when its worker terminated.
• interrupt(reason) cancels only the active turn and retains session authority.
• service.stop(sessionId) clears authority and reaps the process group; reset also deletes the old snapshot and restores the original clean mock seed under new run/session authority.

DurableCapabilityLiveSessionStore writes a checksummed, revisioned checkpoint with atomic rename plus file and directory fsync. It persists provider identity, mock state and semantic idempotency receipts, attempt lineage, active and terminal turn facts, and the usage ledger. The included in-memory store remains limited to tests and single-process consumers.

Every snapshot includes bounded transcript/evidence, serialized mock state, semantic authorization records, runner/Codex PIDs and exit state, and explicit network evidence. Tool calls are admitted only when their thread and turn match the active Codex turn. Their typed CapabilitySemanticToolResult is serialized into the app-server response, allowing Codex to use the resulting state revision in its next response.

Verification

Run the deterministic contract suite:

pnpm --filter @paperclipai/paperclip-runner test:scenarios

Run a real runnerd and Codex app-server smoke:

pnpm --filter @paperclipai/paperclip-runner trace:live-runner -- --json

The smoke requires an authenticated local Codex installation. It checks a real semantic tool mutation, typed-result response, same-thread second turn, process ownership/cleanup, cleared authority, and zero Paperclip network/child-env exposure.