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

Codex: Run the Skillless Codex Driver

What this phase is

Codex connects the mock core to a real Codex app-server session.

Codex gets one small task envelope. Codex does not get the Paperclip skill. Codex does not get a Paperclip API key or API instructions.

What this phase proves

This phase proves that a real Codex session can create a file, stream typed events, return one checked result, and replay the same result.

It also proves that steer, interrupt, resume, and unsupported-operation paths keep clear session identities and safe diagnostics.

Before you start

• Run commands from the repository root.
• Install Node.js 20+, pnpm 9+, Rust, and the codex CLI.
• Sign in to Codex with the normal local Codex setup.
• Do not add a Paperclip or OpenAI API key for this tutorial.

Check the installed harness:

codex --version
codex app-server --help

Run the real-Codex steps from an ordinary operator shell with a workspace that has no AGENTS.md in that directory or any ancestor. A child directory of this repository is not skillless because Codex discovers the repository AGENTS.md. In a Paperclip-managed agent run, PAPERCLIP_WORKSPACE_CWD also prevents mktemp -d from selecting a directory outside the assigned workspace; use a separate clean operator workspace rather than bypassing that guard.

Step 1: Run the focused conformance checks

pnpm --filter @paperclipai/paperclip-runner typecheck:typescript
pnpm --filter @paperclipai/paperclip-runner exec vitest run \
  src/drivers/codex/app-server-transport.test.ts \
  src/drivers/codex/codex-app-server-driver.test.ts
pnpm --filter @paperclipai/paperclip-runner check:forbidden-imports

Confirm that the driver tests pass and the package boundary check says Standalone boundary check passed.

Step 2: Run the safe real Codex task

Choose a temporary directory and trace file:

codex_workspace="$(mktemp -d)"
codex_trace="$codex_workspace/trace.json"
pnpm --filter @paperclipai/paperclip-runner trace:codex -- \
  --working-directory "$codex_workspace" \
  --output "$codex_trace"

Confirm:

• the result is done;
• every printed assertion says PASS;
• the file has the exact text:

test "$(cat "$codex_workspace/hello.txt")" = "hello from Codex runner"

Step 3: Inspect the exact model boundary

Paperclip sends its runtime instructions as additive developerInstructions on Codex thread start and resume. Codex retains its stock base instructions. The historical context.baseInstructions trace field contains the Paperclip fragment, not the full Codex base prompt. The driver option with the same name also supplies this additive fragment.

Threads created before this change retain their saved replacement base prompt when resumed. Reset those provider sessions to apply the stock base instructions; adding developer instructions does not repair an already saved base prompt. This change does not alter session recovery or reset active sessions automatically.

jq '.context | {
  protocolVersion,
  codexVersion,
  model,
  modelProvider,
  workingDirectory,
  sandbox,
  approvalPolicy,
  baseInstructions,
  instructionSources,
  instructionPolicy,
  environmentKeys,
  dynamicToolNames,
  modelInputKinds,
  envelope
}' "$codex_trace"

Confirm:

• instructionSources is empty;
• all three instruction-policy values are false;
• modelInputKinds contains only text;
• the semantic tools are paperclip_finish and paperclip_block;
• no environment value is present;
• the requested permission profile denies root and host-home access, exposes read-only minimal runtime files, grants write access to the assigned workspace, and disables network access;
• the returned legacy sandbox facts are inspected separately because Codex may add provider-managed state roots such as ~/.codex/memories even when memory instructions are disabled;
• command HOME and CODEX_HOME are absent;
• the envelope contains only this safe task and its completion criteria.

Check that no control-plane route or bearer credential appears:

if rg -ni 'authorization: bearer|paperclip_api_key|/api/issues/' "$codex_trace"; then
  echo "FAIL: forbidden control-plane context found"
  exit 1
fi

Step 4: Inspect canonical events and replay

jq '[.events[].eventType] | group_by(.) | map({type: .[0], count: length})' \
  "$codex_trace"
jq '.assertions' "$codex_trace"

Confirm:

• session and turn lifecycle events exist;
• model, command/tool, usage, verification, result, and terminal events exist;
• exactlyOneTerminalResult is true;
• liveReplayParity is true;
• source sequence and item identity assertions are true.

The focused test suite supplies deterministic file-change and runtime-request events because a real model may choose a shell command instead of a file patch and may not need human input for this small task.

Step 5: Try steering

Use a new directory:

codex_steer_workspace="$(mktemp -d)"
pnpm --filter @paperclipai/paperclip-runner trace:codex -- \
  --working-directory "$codex_steer_workspace" \
  --steer "Keep the answer short and verify the exact file text."

Confirm that the same driver and provider session IDs are printed and the task still returns one result.

Step 6: Try interruption

Use a new directory:

codex_interrupt_workspace="$(mktemp -d)"
pnpm --filter @paperclipai/paperclip-runner trace:codex -- \
  --working-directory "$codex_interrupt_workspace" \
  --interrupt

An interrupt can win before the file is created. That is expected. Confirm that the trace still has one session identity, one semantic result, and one terminal event. It must not create a replacement session.

Step 7: Run the package verification path

pnpm --filter @paperclipai/paperclip-runner verify

This command is the package acceptance path. The real Codex example remains a separate command because automated environments may not have a signed-in Codex session.

Step 8: Read the driver reference

• Codex driver reference