PaperClipAI/packages/paperclip-runner/docs/tutorials/phase-04-skillless-codex.md

Phase 4: Run the Skillless Codex Driver

What this phase is

Phase 4 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

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:

phase4_workspace="$(mktemp -d)"
phase4_trace="$phase4_workspace/trace.json"
pnpm --filter @paperclipai/paperclip-runner trace:phase4 -- \
  --working-directory "$phase4_workspace" \
  --output "$phase4_trace"

Confirm:

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

test "$(cat "$phase4_workspace/hello.txt")" = "hello from phase 4"

Step 3: Inspect the exact model boundary

jq '.context | {
  protocolVersion,
  codexVersion,
  model,
  modelProvider,
  workingDirectory,
  sandbox,
  approvalPolicy,
  baseInstructions,
  instructionSources,
  instructionPolicy,
  environmentKeys,
  dynamicToolNames,
  modelInputKinds,
  envelope
}' "$phase4_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 permission profile denies root access, exposes only read-only minimal runtime files, grants write access to the assigned workspace, and disables network access;
• 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/' "$phase4_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})' \
  "$phase4_trace"
jq '.assertions' "$phase4_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.

To record the authenticated isolation proof, run:

pnpm --filter @paperclipai/paperclip-runner record:phase4

The recorder selects an existing readable host Codex credential/config path, creates a separate host secret, and asks the model to prove that neither is readable or writable. The run must still authenticate, create the workspace files, retain the successful command output, and pass every trace assertion.

Step 5: Try steering

Use a new directory:

phase4_steer_workspace="$(mktemp -d)"
pnpm --filter @paperclipai/paperclip-runner trace:phase4 -- \
  --working-directory "$phase4_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:

phase4_interrupt_workspace="$(mktemp -d)"
pnpm --filter @paperclipai/paperclip-runner trace:phase4 -- \
  --working-directory "$phase4_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 evidence

• Phase 4 driver reference
• Phase 4 verification evidence
• Phase 4 journal

Phase 5 is not part of this tutorial and remains uncreated.