PaperClipAI/packages/paperclip-runner/docs/codex-driver.md

Codex Skillless Codex Driver

Scope

Codex implements a direct Codex app-server v2 driver behind the package's existing HarnessDriver contract. The driver, mock core, example CLI, tests, and evidence stay inside packages/paperclip-runner/. They do not import or change Paperclip server, UI, database, or production control-plane behavior.

The app-server process is local to the execution environment and uses newline delimited JSON-RPC over stdio. It is not exposed as a network service.

Identity mapping

Runner identity	Codex source	Persistence rule
run ID	mock-core input	Never replaced during recovery.
normalized session ID	controller-owned mock-core input	A distinct identity, independent of the run and provider IDs, that stays stable across transport/process recovery.
driver session ID	thread.id	Resumed by exact ID. A different returned ID fails recovery.
provider session ID	thread.sessionId	Kept separately from the driver thread ID.
turn ID	turn.id	Required by steer and interrupt preconditions.
item ID	item.id, request ID, or deterministic turn/kind key	Preserved on lifecycle and delta events.
source event ID	runner instance + run + source sequence	Source sequence continues from the persisted snapshot.

The persisted session snapshot records run, normalized session, driver session, provider session, the exact active turn, committed semantic-result content/call binding, observed terminal-turn fingerprints, and the last source sequence. Recovery starts a new local app-server transport, reads the exact persisted thread to validate identity and working directory, resumes that thread, and then reads it again for reconciliation. Reconciliation considers only the persisted active turn: it retains that turn when active, terminalizes that turn when terminal, and fails recoverably when it is missing or a different active turn appears. Historical terminal turns never substitute for the persisted active turn, and a terminal already in the durable snapshot is not emitted again.

App-server operations

Driver operation	App-server method	Degradation
initialize	initialize, then initialized	Startup fails visibly.
create	thread/start	Required.
resume	thread/resume	recovered: false with a redacted reason.
read	thread/read	Explicit HarnessCapabilityUnavailableError.
start turn	turn/start	Required.
steer	turn/steer with expectedTurnId	Explicit unsupported diagnostic; no stdin fallback.
interrupt	turn/interrupt	Explicit unsupported diagnostic; session is not killed.
usage	thread/tokenUsage/updated	Returns the last snapshot or explicit unsupported error.
reconcile	thread/read plus session.reconciled	Disabled when read is unavailable.

Capability flags are descriptive and executable. Unsupported operations emit canonical harness.diagnostic events with secret-redacted detail. No harness-specific branch is required in the mock core.

Skillless context boundary

The model receives one text input containing paperclip.skillless_task.v1:

• objective;
• completion-contract revision and criteria;
• task constraints; and
• the expected canonical result schema name.

The thread config explicitly disables automatic skill and app instruction blocks. Codex's built-in collaboration instructions are enabled by default so interactive runs receive native commentary and tool preambles; a driver caller may explicitly disable them for a specialized deterministic fixture. This does not enable skills, apps, plugins, memories, or extra model-input kinds. The model input accepts only text, never a Codex skill input. The driver captures the returned instruction-source list and requires it to be empty for the skillless assertion.

The trusted app-server process has an allowlisted environment. It retains host HOME and CODEX_HOME only so the provider can authenticate. Model-issued commands have a separate boundary: an empty-by-default environment with no HOME or CODEX_HOME, no network, and a named Codex permission profile requesting read-only minimal runtime files, no host-home or Codex-home access, and write access to the assigned workspace. The driver refuses filesystem-root workspaces, workspaces containing host HOME, and any workspace overlapping host CODEX_HOME. A workspace below host HOME is valid, but when PAPERCLIP_WORKSPACE_CWD is present its canonical path must be equal to or below that assigned workspace so sibling and symlink escapes fail before provider startup.

The returned sandbox facts remain authoritative. Codex 0.132.0 may inject a provider-managed writable root such as ~/.codex/memories after a first run, even with features.memories=false and an explicit Codex-home deny. That makes the Codex-home directory discoverable in a warmed environment, so Codex does not claim whole-directory unreadability. Its authenticated proof instead requires each readable auth.json/config.toml file and an unrelated host secret to remain unreadable and unwritable, while recording any injected root in context.sandbox.legacyPolicy.

Paperclip bearer values, OPENAI_API_KEY, arbitrary skill paths, and other inherited variables are not passed. Diagnostics redact bearer/basic credentials, credentialed proxy URLs, secret query parameters, sensitive JSON keys, and common key assignments.

The context snapshot records configuration and environment key names, not secret values.

Semantic completion

The provider-facing structured-output schema covers done and needs_review. It uses the strict OpenAI shape: every object rejects additional properties and the constant schema field includes both type: "string" and const.

Two dynamic semantic tools are registered when supported:

• paperclip_finish accepts done or needs_review;
• paperclip_block accepts blocked and requires a blocker owner, action, reason, and scope.

Both normalize through the canonical paperclip.run_result.v1 validator. The first valid result is proposed. Any canonically identical result retry is idempotent even when the provider assigned a new call ID; the original call binding remains persisted for audit, while changed content is rejected. Tool calls and provider notifications must name the exact opened thread and active turn. Missing, pre-turn, cross-thread, cross-turn, and post-terminal bindings fail the provider session closed. Canonically identical terminal replays are no-ops; conflicting terminal facts are rejected. Process exit or prose alone never implies completion.

The provider cannot commit controller state. It emits run.result.proposed and a provider turn terminal; the mock core validates the proposal against its task envelope, emits run.result.accepted or run.result.rejected, and alone emits run.terminal.

Canonical event mapping

• thread lifecycle -> session.started, session.resumed, session.reconciled;
• turn lifecycle -> turn.submitted, turn.accepted, turn.started, and one terminal turn event;
• messages, reasoning, plans, commands, file changes, dynamic tools, and diffs -> item.started, item.delta, item.completed;
• model selection -> a completed model item;
• app-server decisions -> runtime_request.created and runtime_request.resolved with redacted detail;
• token snapshots -> completed usage items;
• semantic verification rows -> completed verification items;
• provider completion -> at most one run.result.proposed and one turn terminal;
• controller decision -> one run.result.accepted or run.result.rejected, followed by one run.terminal.

The JSON-RPC transport limits each input line, pending client requests, in-flight server requests, queued notification count and bytes, diagnostic lines, and retained provider payloads. Malformed or oversized messages close the transport and reject pending work.

The existing Replay reducer consumes the live stream. Replay crosses a serialized JSONL boundary that validates byte and event counts, line size, schema, run/session binding, unique source event IDs, continuous per-source sequence, and exactly one final run terminal before reducing. The Codex tracer requires byte-equivalent live and replay snapshots.

Runnable example

trace:codex starts a real local codex app-server session through the mock core. Its safe task creates hello.txt with network disabled. The evidence recorder additionally probes all readable host Codex credential/config files and an unrelated host secret, requiring reads and writes to be denied while workspace output and app-server authentication still succeed. It gates output reads on an accepted done result and reports missing files by name rather than surfacing a raw filesystem ENOENT. See the Codex tutorial.

This phase changes no browser surface, so no new browser screenshot applies. The canonical events are proved through the existing reducer/replay path and JSON trace evidence.

Explicit assigned skills in native tasks

A task description can explicitly invoke an assigned skill with /skill-name or $skill-name. The native Codex backend resolves these references against that run's assigned runtime context; assignment alone does not invoke a skill. Selections are recomputed from the current task description on each wake, including approval replies and recovered sessions. Ordinary tasks without an explicit reference receive no structured skill invocation.

The driver sends both the $skill-name text reference and Codex's structured { type: "skill", name, path } input on every requested turn. Runnerd validates the assigned source path, maps it to the provider's isolated codex-home/skills/<name>/SKILL.md (including remote runners), and preserves it through the durable turn.start command. turn.submitted.skillInputs records the controller's selected inputs for inspection; protocol tests separately verify the outgoing provider request and mapped path.

includeSkillInstructions is forwarded to Codex on both thread/start and thread/resume. Old persisted configurations without the field retain their provider default until a fresh, settled run supplies an explicit value. That one-time upgrade reopens the same thread with the new setting. OpenCode does not receive Codex's skill configuration or structured skill inputs.

These are delivery guarantees, not guarantees of model adherence. The onboarding first-task skill uses this generic mechanism; its prompt and persona are not changed by the wiring.