Paperclip Native Runner
This workspace is the standalone development boundary for Paperclip's native
runner protocol, harness drivers, and normalized session backends. The
production runner direction is Rust; runner/ is its Cargo workspace. The
TypeScript surface remains a control-plane/client reference implementation.
Phase 0 runs both implementations against one language-neutral fixture. Phase 1
adds executable PRP schemas, a cross-language conformance corpus, deterministic
static replay, and a standalone browser reference page. Phase 2 adds the Rust
runner process, process-group supervision, a scripted fake harness over stdio
JSONL, a TypeScript mock core, and validated live browser replay. Phase 3 adds
the Rust outbound WebSocket client, private durable state, replay and restart
recovery, and safe CLI/browser diagnostics. Phase 4 adds a direct, skillless
Codex app-server driver, semantic completion tools, canonical event tracing,
and a real-model example against the mock core. These phases do not import or
start Paperclip's server, UI, CLI, or production database.
Phase 0–4 quick start
From the repository root:
pnpm install --filter @paperclipai/paperclip-runner --lockfile=false --offline --ignore-scripts --dev
pnpm --filter @paperclipai/paperclip-runner verify
The verification command requires a stable Rust toolchain with cargo on
PATH, in addition to Node.js 20+ and pnpm 9+.
Minimal Debian/Ubuntu hosts without root access can extract the required Playwright browser libraries into a user-owned cache and run the same acceptance sequence with:
pnpm --filter @paperclipai/paperclip-runner verify:rootless
The tracer's final line is stable:
{"schemaVersion":"paperclip.runner.phase0.output.v1","runIdentity":{"runId":"run_phase0_0001","sessionId":"session_phase0_0001"},"result":{"status":"succeeded","summary":"Standalone Phase 0 fixture accepted."}}
Run only the tracer with:
pnpm --filter @paperclipai/paperclip-runner trace:phase0
Replay the Phase 1 happy path, run a Phase 2 local session, or open the browser devtool:
pnpm --filter @paperclipai/paperclip-runner replay:phase1
pnpm --filter @paperclipai/paperclip-runner trace:phase2 -- --scenario happy-path
pnpm --filter @paperclipai/paperclip-runner trace:phase3 -- --fault lost-ack
pnpm --filter @paperclipai/paperclip-runner trace:phase4
pnpm --filter @paperclipai/paperclip-runner browser:dev --host 127.0.0.1 --port 4179
Package-owned commands
| Command | Purpose |
|---|---|
build |
Compile the TypeScript public surface, Rust workspace, and browser devtool. |
typecheck |
Check TypeScript, Rust, generated schema sources, and browser types. |
test |
Run Rust/TypeScript fixture, supervisor, fake-driver, live/replay, and boundary tests. |
check:forbidden-imports |
Reject TypeScript imports and Cargo path dependencies that cross into Paperclip core. |
check:phase0-parity |
Require byte-for-byte equivalent Rust and TypeScript tracer output. |
check:phase1-goldens |
Require all reducer snapshots and cross-language summaries to match checked goldens. |
check:phase1-parity |
Run TypeScript and Rust against the same Phase 1 fixture summaries. |
check:browser-tokens |
Reject component-local visual literals and require the standalone token layer. |
docs:validate |
Validate local documentation links and the OKF v0.2 bundle. |
trace:phase0 |
Run the Rust mock-core tracer, print the stable result, and exit. |
trace:phase0:typescript |
Run the TypeScript reference tracer directly. |
replay:phase1 |
Validate and reduce a fixture to a final snapshot. |
trace:phase2 |
Run one native local session through the Rust runner and fake harness. |
record:phase2 |
Capture a validated happy-path live trace as a replay fixture. |
trace:phase3 |
Run the Rust runner against the mock core with a selected recovery fault. |
record:phase3 |
Regenerate the complete Phase 3 fault matrix and exact per-fault traces. |
trace:phase4 |
Run the mock core with a real, local skillless Codex app-server session. |
record:phase4 |
Run the safe Codex task and record its validated, normalized trace. |
browser:dev |
Start the standalone live/replay/recovery browser devtool. |
test:browser |
Exercise static replay and live scenarios, then capture temporary screenshots under ignored test output. |
verify |
Run the complete deterministic Phase 0 through Phase 4 acceptance sequence. |
verify:rootless |
Extract Debian/Ubuntu browser libraries without root, then run verify. |
Navigate
- Architecture and dependency boundary
- Tutorial index
- Phase 0 hand-run tutorial
- Phase 1 hand-run tutorial
- Phase 2 hand-run tutorial
- Phase 2 local protocol reference
- Phase 3 break-it-on-purpose tutorial
- Phase 3 durable transport reference
- Phase 4 skillless Codex tutorial
- Phase 4 skillless Codex driver reference
- PRP compatibility/versioning policy
- Cumulative end-to-end tutorial
- Journal guide
- OKF knowledge bundle
- Implementation plan
- Normative spike specification
Phase 4 adds the package-local real-model reference driver. Production Paperclip integration and Phase 5 remain deferred.