paperclip/packages/paperclip-runner/docs/tutorials/end-to-end.md

Native Runner Cumulative End-to-End Tutorial

What this tutorial is

This tutorial combines each implemented Native Runner phase into one procedure. It currently includes Conformance through the Standalone Paperclip adapter tracer.

What this tutorial proves

This tutorial proves that the standalone package boundary, static replay path, local live-run path, durable transport, and direct Codex driver work together. It does not use the Paperclip control plane. Codex uses a real local Codex session through the mock core.

The current system includes the Rust mock-core tracer, shared protocol fixtures, the Rust supervisor, a scripted fake harness, CLI live runs, and browser live and replay modes. It also includes the Rust outbound WebSocket client and durable outbox. The final phase adds a skillless task envelope, direct app-server driver, semantic completion tools, and the same reducer/replay proof used by fixtures. SDK freezes that browser transport and reducer projection as public SDK subpaths, then proves them with a reference console and a second consumer. Standalone consumes the public runner contract from Paperclip behind a default-off flag while preserving server-owned workspace, governance, and status authority.

Current end-to-end path

1. Follow Conformance: Run the Standalone Tracer.
2. Confirm the final JSON contains run_conformance_0001, session_conformance_0001, and succeeded.
3. Confirm the cross-language parity check passes.
4. Confirm the shell prompt returns and no Paperclip service was started.
5. Follow Replay: Validate and Replay a PRP Fixture.
6. Compare the happy-path CLI snapshot with the browser page and exercise the duplicate, gap, unknown-field, and unsupported-version fixtures.
7. Follow Local runner: Run the Local Runner and Fake Harness.
8. Run the happy, permission/input, interruption, error, and duplicate-terminal scenarios.
9. Open the browser live mode and confirm the completed run says Match for live and replay output.
10. Follow Codex: Run the Skillless Codex Driver.
11. Inspect the exact model-context snapshot and confirm that it has no Paperclip instructions, bearer credentials, or unrelated skills.
12. Run the safe task, then steer and interrupt separate sessions. Confirm stable session identities and exactly one result and terminal event.
13. Follow Live console: Run the Protocol Demo Server.
14. Confirm requests stay pending for a typed browser decision, stale steering is rejected, and reconnect keeps the same run and session identities.
15. Follow SDK: Run the SDK Console and Mini Consumer.
16. Run the fake lifecycle in both consumers, then confirm the mini consumer reaches Replay parity: match after reconnect and replay.
17. Run the safe real-Codex browser smoke.
18. Follow Standalone: Run the Thin Paperclip Adapter.
19. Run the unchanged port conformance suite against mock and database-backed Paperclip ports, then inspect one local feature-flagged task.
20. Disable the flag and confirm a fresh task selects legacy while persisted native finalization remains native.

The one-command form after installation is:

pnpm --filter @paperclipai/paperclip-runner verify

On a minimal Debian or Ubuntu host without root access, use the rootless browser dependency path:

pnpm --filter @paperclipai/paperclip-runner verify:rootless

Cumulative guarantees

• the fixture is validated before any mock-core mutation;
• event sequence and run identity agree through the terminal result;
• Rust and TypeScript printed output is covered by exact string and parity assertions;
• deliberate TypeScript and Cargo references to Paperclip core are rejected;
• documentation and journal indexes are machine checked;
• the package remains runnable without Paperclip core;
• JSON Schema remains the language-neutral authority for TypeScript and Rust;
• replay is deterministic and idempotent under duplicate delivery;
• source gaps are visible and never synthesized away;
• CLI and browser paths use the same validator/reducer module;
• browser components keep visual values in the package-local token layer.
• the Rust supervisor owns the fake harness process group and cleans it up when the controller closes;
• command IDs are idempotent and controller sequence numbers stay contiguous;
• runtime permission and input requests round-trip over the local protocol;
• process exit is recorded separately from the structured semantic result;
• bounded logs retain only their configured tail;
• exactly one terminal event closes every completed local trace;
• every live browser event passes the Replay validator and reducer before display;
• replaying the completed live event list produces the same final snapshot.
• a lost cumulative ACK replays the same durable event ID without a second logical event;
• repeated commands return the stored result and cause one logical effect;
• runner and harness restarts preserve runner, session, turn, and item IDs;
• backpressure bounds local storage without dropping P0 events;
• lease expiry, drain, revoke, and unrecoverable storage outcomes are explicit;
• CLI and browser diagnostics do not expose bootstrap or connection-lease tokens.
• the Codex child receives an allowlisted environment without Paperclip or OpenAI bearer credentials;
• automatic skill and app instruction blocks are disabled, while Codex's built-in collaboration instructions are enabled by default and remain explicitly removable for controlled eval baselines;
• direct app-server create, resume, read, turn, steer, interrupt, usage, and reconciliation operations preserve stable identities;
• provider events normalize to canonical lifecycle, model, tool, file, request, usage, verification, result, and terminal events;
• the first validated semantic completion wins, identical duplicates are idempotent, and a changed duplicate is rejected;
• unsupported capabilities degrade through explicit redacted diagnostics;
• the real trace and its replay reduce to the same final snapshot.
• supported provider requests wait for one typed browser resolution and clean up exactly once;
• same-turn steering is acknowledged while stale and direct-child steering are rejected;
• pre-start interrupts queue until the provider turn ID exists and terminal races return already_terminal;
• goal controls are capability probed and disabled precisely when unavailable;
• parent/child activity derives from provider thread identities;
• the demo server fixes the workspace and keeps Codex authentication out of browser JSON, events, and diagnostics;
• refresh/reconnect replays canonical events and resumes the exact persisted provider thread.
• the browser console renders only reducer state and canonical events, with no second event model and no client-side session cache;
• steering resolves to exactly one of acknowledged, stale-rejected, or failed, and rejected text stays recoverable;
• interrupt before start, during generation, and during a tool call each end in a distinct visible state, and the session is never replaced;
• request cards offer only the actions the upstream request offers and lock on the first click until the canonical resolved event arrives;
• unsupported capabilities render disabled controls carrying the exact upstream diagnostic, never hidden and never emulated;
• a transport drop, a page refresh, and replay all reproduce the same transcript from the durable cursor;
• no provider credential reaches the browser DOM, and adapted components add no new runtime dependency.
• the browser and React contracts are versioned package subpaths with React as a peer and no new runtime dependency;
• the reference console and mini consumer import public APIs only;
• exactly five extension points cover item bodies, request details, Composer actions, token theming, and transport injection;
• duplicate canonical events reach the shared reducer unchanged;
• both consumers preserve identity through reconnect and reduce replay to the same final state.

Step 6: Chat with a live session in the browser

pnpm --filter @paperclipai/paperclip-runner console:live-console

Open http://127.0.0.1:4180/ and press Live console. Work through the Live console tutorial to reach every state above from the eleven deterministic demo chats. Add PAPERCLIP_LIVE_CONSOLE_DRIVER=codex to run the identical screens against a real Codex session.

Step 7: Run the reusable SDK consumers

pnpm --filter @paperclipai/paperclip-runner console:sdk

Open http://127.0.0.1:4181/reference-console/ and http://127.0.0.1:4181/mini-consumer/. Follow the SDK tutorial for the deterministic lifecycle, real-Codex smoke, keyboard checks, and package acceptance command.