doc/architecture/paperclip-runner.md
Paperclip is a control plane. It owns companies, agents, issues, budgets, approvals, and durable workflow state. Agent providers remain execution services. Existing adapters invoke those services directly from the Paperclip server.
Paperclip Runner introduces a separate execution process for provider sessions. This process needs durable delivery, restart recovery, and governed access to Paperclip actions. It must not become a second control plane. It must also land without changing the behavior of existing adapters.
The initial implementation is intentionally narrow. It supports Codex through an explicit, experimental adapter. Other providers and developer tools remain outside this decision.
Add a standalone package named @paperclipai/paperclip-runner. The package owns
the language-neutral Paperclip Runner Protocol (PRP), the Rust runner process,
provider drivers, deterministic replay, and semantic action dispatch contracts.
Add one explicit adapter named paperclip_runner. The adapter is available only
when an instance-level, default-off rollout flag is enabled. Its first supported
provider is Codex.
Do not route existing adapters through Paperclip Runner. A direct adapter keeps its current invocation, transcript, interaction, cancellation, and finalization paths.
The initial local topology is:
Paperclip server
| authenticated PRP v1 WebSocket
v
paperclip-runnerd
| Codex app-server protocol
v
Codex
The server opens a native run and launches a verified runnerd artifact in the realized execution environment. Runnerd opens the outbound PRP connection. It then owns the provider process group and the durable transport state for that run.
The browser does not connect to runnerd. It reads projections from the existing Paperclip APIs and task-thread models.
The runner package must build and test without importing Paperclip server, UI, CLI, database, or other private workspace implementation modules.
JSON Schema and fixtures
|
+------------------+
v v
TypeScript contracts Rust runner core
| |
+--------+---------+
v
deterministic parity
Paperclip server ----implements----> runner public ports
The dependency points from an implementation to a contract. The Paperclip server may implement a public runner port. The runner package must not import the server implementation.
The initial public package surfaces are:
@paperclipai/paperclip-runner for runtime contracts and clients.@paperclipai/paperclip-runner/testing for deterministic fakes and
conformance helpers.Every export must have an implementation and a clean-consumer test before it is published. Later SDK, eval, and lab surfaces require separate decisions.
PRP v1 uses a WebSocket at:
/api/runner/v1/connect/:runId
JSON Schema is the language-neutral protocol authority. TypeScript and Rust use the same canonical fixtures and must produce the same replay result.
Protocol rules are fail closed:
Provider-native messages do not cross this boundary. Drivers translate them to provider-neutral PRP events, results, usage, cancellations, and structured input.
The Paperclip server is authoritative for:
Runnerd is authoritative only for its local responsibilities:
Runnerd receives a short-lived, one-use bootstrap ticket. The ticket is bound to the company, agent, issue, run, runner, session, turn, and verified artifact. The server exchanges it for a short-lived connection lease. Raw tickets are never stored. Runnerd never receives a broad Paperclip API key.
The server rejects expired, replayed, revoked, cross-company, mismatched, malformed, oversized, or protocol-incompatible connections. Cancellation, timeout, supersession, and environment-lease loss revoke runner authority.
Runnerd persists an event before it sends the event. The server acknowledges a cumulative source cursor. Runnerd removes acknowledged data only after it validates that cursor.
A reconnect reports the last processed command, the next source sequence, the last acknowledged source sequence, and the unacknowledged range. The server may then replay one pending command and accept byte-equivalent event retries.
Command identity is idempotent. Reusing a command ID with the same canonical input returns the stored result. Reusing the ID with different input fails closed. A repeated semantic tool call cannot repeat an application effect.
Recovery is bounded. Exhausted storage, reconnect, command, or time limits end the run with a classified failure instead of an unbounded loop.
PRP carries provider-neutral semantic operation IDs. The package may define an operation catalog, but catalog presence does not grant authority.
For each run, the server projects only operations that have a production binding and that the current actor may discover. An unbound or unauthorized operation is absent from discovery. The server validates inputs, executes the existing application authority, and returns a redacted receipt.
This keeps these invariants in one place:
Runnerd cannot forge identity through tool input. Identity and scope come from the authenticated connection binding.
Questions use paperclip.question_set.v1. Responses use the matching canonical
response contract. Drivers translate between these provider-neutral records and
provider-native input APIs.
The server validates a response at the untrusted API edge and again against the persisted question set before delivery. A process loss may materialize a durable task-thread interaction, but cancellation and an already resolved request must not create a second interaction or continuation.
Native run records are additive. Existing heartbeat and issue records remain readable. A runner result is an untrusted claim. It does not directly update an issue status.
The server validates the result, classifies durable evidence, applies status policy, commits workflow effects, and records finalization. Each phase is idempotent and recoverable. Existing direct adapters keep their existing finalization paths and do not invoke native status arbitration.
Disabling the rollout flag blocks fresh runner starts. It does not make an already persisted native run unreadable or prevent bounded recovery and finalization of that run.
The rollout has three gates:
paperclip_runner.codex.The adapter is hidden from creation and selection surfaces while the flag is off. Server validation also rejects a fresh runner selection or start while the flag is off. UI hiding is not the security boundary.
Runtime selection is persisted before launch. Later setting changes cannot silently move an in-flight run between the direct and native execution paths.
The detailed compatibility rules are in Paperclip Runner compatibility and rollout.
The server records structured runner, provider, semantic action, interaction, usage, and terminal events. Logs and receipts must not contain bootstrap tickets, leases, provider credentials, secret values, complete environments, or private host paths.
The task page may project these records through existing thread components. A runner-only control must depend on persisted runtime facts. It must not depend only on the agent adapter profile.
This design adds process, protocol, and recovery complexity. In return, it gives provider sessions a durable and testable execution boundary without moving Paperclip governance into the runner.
The default-off, explicit-adapter rollout duplicates some provider configuration during the experiment. This is intentional. It keeps comparison and rollback simple and prevents a global migration of existing agents.
The standalone package boundary requires generated artifacts, clean-consumer tests, and cross-language parity gates. These checks add build cost, but they prevent server implementation details from becoming accidental public API.