mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 04:02:18 +01:00
Dotta
397de98193
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The Paperclip Runner now has protocol, provider, tool, package, persistence, and hidden server boundaries. > - The server still cannot select that path for a real agent heartbeat. > - A new runtime must not change any existing direct adapter. > - An experimental runtime must fail closed when its rollout flag is off. > - This pull request adds one guarded Codex vertical slice through runnerd. > - The benefit is a production-built runner path that users cannot start by default. ## Linked Issues or Issue Description Refs #11962 Refs #12111 Refs #12169 Refs #12176 **Subsystem affected** Cross-cutting. The change affects the runner package, server orchestration, shared settings, and adapter configuration UI. **Problem or motivation** The hidden PRP coordinator cannot execute a real heartbeat. The application also needs an explicit rollout boundary before it can expose the experimental runner. Existing direct adapters must keep their current execution and finalization behavior. **Proposed solution** Add `paperclip_runner` as a Codex-only adapter behind the default-off `enableNativeRunner` instance flag. Select the native runtime only for that adapter. Persist the run binding before runnerd starts. Wait for the durable PRP result and terminal event. Resume the real Codex provider thread on later heartbeats. Keep persisted native runs readable and recoverable after the flag changes. **Alternatives considered** The server could route `codex_local` through runnerd. That option would change an existing adapter and weaken rollback safety. The server could expose all providers now. That option would add unreviewed provider behavior. The build could depend on a prebuilt runner binary. That option would make source builds architecture-dependent and difficult to verify. **Roadmap alignment** This work supports the shipped enforced-outcomes, governed-tool, and self-healing-run milestones. It does not add a new roadmap surface. It is the guarded execution step after the merged hidden runner boundaries. **Additional context** This is the next replacement for the closed large runner pull request. Task-thread presentation remains a separate follow-up so this change can preserve the current direct-adapter UI. ## What Changed - Add `paperclip_runner` as an explicit Codex-only adapter. - Add the default-off `enableNativeRunner` instance flag. - Reject fresh create, hire, import, switch, and execution requests while the flag is off. - Allow edits to persisted runner agents while the flag is off. - Recover an already persisted native run even after the flag is disabled. - Keep every built-in direct adapter on its existing runtime path. - Persist an immutable native run binding and revisioned completion contract before runnerd starts. - Execute server to PRP to runnerd to Codex to server through the hidden coordinator. - Validate the durable result against the terminal event and exact completion criteria before finalization. - Preserve the Codex provider thread ID and use `thread/resume` on the next heartbeat. - Strip unsupported Codex configuration fields from the experimental adapter. - Build a target-native release runner binary from source and vendor it into the server distribution. - Install Rust only in the Docker build stage. Do not add a workflow or lockfile change. - Stop the runner process group on completion, cancellation, and forced shutdown. ## Verification - Run `pnpm --filter @paperclipai/paperclip-runner check:all`. All 69 TypeScript tests and 58 Rust tests pass. Protocol, conformance, replay, formatting, and generated-file checks pass. - Run the 12 focused adapter, settings, runtime-selection, coordinator, direct-isolation, and real Codex integration test files. All 186 tests pass. - The real integration test uses PostgreSQL, HTTP, WebSocket, runnerd, and a fake Codex app server. It proves one `thread/start` followed by one `thread/resume`. - Run `pnpm -r typecheck`. - Run `pnpm build`. - Run `pnpm check:token-gates`. - Build the Docker `build` target from a clean context. Confirm that the server distribution contains an executable `paperclip-runnerd` built with Debian Rust 1.85. - Start the server through the source-mode tsx entry point with the package `dist` directory absent. Confirm the vendor shim resolves source exports and the server boots. - Run `pnpm test:run` twice. On this macOS host, 405 files pass and 1 file skips. Eight untouched workspace and loopback tests fail because macOS resolves `/tmp` and `/var` through `/private` and because PID-derived test ports exceed 65535. Linux CI must pass the full suite. - Confirm that the diff contains 52 files. Confirm that it contains no `.github` or `pnpm-lock.yaml` change. ## Risks - The feature flag is off by default. A fresh native start fails with a stable error while the flag is off. - A persisted native run remains recoverable after the flag changes. This prevents rollout changes from corrupting recorded work. - Only local Codex execution is accepted. Other providers and remote work modes fail closed. - Existing direct adapters do not start runnerd, create native rows, use native status arbitration, or enter native finalization. - The runner receives its one-use bootstrap ticket through the child environment. The server does not put the ticket in command arguments or logs. - The server validates the company, task, agent, run, runner, session, completion contract, result, and terminal binding before it accepts completion. - The build compiles a target-native Rust binary. Cross-platform release packaging remains a later concern. Source builds and Docker builds compile for their current target. - Docker needs enough build memory for the existing server TypeScript compile. The Docker build stage sets a 4 GB V8 heap limit. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex with GPT-5. The exact deployment ID and context-window size are not exposed. The model used agentic reasoning, repository tools, code execution, and test execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and applicable tests pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
76 lines
4.3 KiB
Markdown
76 lines
4.3 KiB
Markdown
# Durable PRP transport
|
|
|
|
This layer gives `paperclip-runnerd` a provider-neutral PRP v1 transport. The
|
|
Paperclip server invokes durable mode only for a selected, flag-enabled
|
|
`paperclip_runner` agent or recovery of its persisted native run. Codex is the
|
|
only installed provider; other providers remain unavailable.
|
|
|
|
## Trust boundary
|
|
|
|
- The runner accepts only `ws://` destinations whose complete DNS result is
|
|
loopback. Resolution happens once and reconnects reuse the pinned addresses.
|
|
- A bootstrap ticket is read from `PAPERCLIP_RUNNER_BOOTSTRAP_TICKET`, removed
|
|
from the environment immediately, and never sent over the socket. Both peers
|
|
prove possession through HMAC-SHA-256.
|
|
- A successful bootstrap exchanges the one-use ticket for a connection-bound,
|
|
expiring lease held only in memory. Once authentication starts, a failed
|
|
bootstrap attempt is not replayed automatically.
|
|
- Post-authentication frames use AES-256-GCM with direction-specific keys,
|
|
monotonically increasing counters, and session-bound associated data.
|
|
Plaintext, replayed, out-of-order, oversized, or incorrectly bound frames
|
|
fail closed.
|
|
- Cross-language authentication primitives use the UTF-8 domain bytes followed
|
|
by a NUL byte, then each input as an unsigned 64-bit big-endian byte length
|
|
and its raw bytes. Challenge proofs cover the lexicographically key-sorted,
|
|
compact JSON challenge payload. The server-to-runner integration test is the
|
|
parity gate for these TypeScript and Rust encodings.
|
|
- The durable state directory is private, symlinks are rejected, and updates
|
|
use a private temporary file, file sync, atomic rename, and directory sync.
|
|
Credentials and lease tokens are never written to this state.
|
|
|
|
## Recovery contract
|
|
|
|
Events enter the outbox before delivery. A cumulative ACK may advance only to a
|
|
source sequence the runner has produced; acknowledged prefixes are removed
|
|
atomically from durable state. After disconnect, every remaining event is sent
|
|
again with the same identity and source sequence.
|
|
|
|
Executors retain polled events until runnerd acknowledges each event after its
|
|
outbox commit. Batches commit one event at a time, so a later oversized event or
|
|
capacity failure cannot roll back the accepted prefix or discard the
|
|
unacknowledged suffix. Each retained executor event has a stable identity that
|
|
runnerd derives into its PRP `sourceEventId`. If the process stops after the
|
|
outbox commit but before the executor acknowledgement, a bounded durable
|
|
receipt journal recognizes and byte-validates the retained copy without
|
|
appending a second event. Receipts outlive transport ACK removal; because the
|
|
provider queue is ordered and bounded, a possibly retained front event cannot
|
|
be evicted while later events advance the journal.
|
|
|
|
Commands require a contiguous controller sequence. The runner journals a
|
|
pending command before invoking its executor and persists its result afterward.
|
|
An exact duplicate returns the stored result without repeating the effect. If
|
|
the process dies inside the effect window, recovery records an indeterminate
|
|
result and refuses to execute that command again. Recent results are bounded;
|
|
commands older than the compacted controller cursor fail closed.
|
|
|
|
State written before complete-command fingerprints existed is migrated by
|
|
compacting its legacy command journal through the last recorded controller
|
|
sequence. The runner can recover, but it rejects redelivery of those older
|
|
commands instead of guessing an identity or repeating an uncertain effect.
|
|
|
|
The outbox has separate hard and reserved limits. P1/P2 events cannot consume
|
|
the P0 reserve. When the soft limit is reached, the runner enters backpressure
|
|
and rejects the new non-P0 event rather than silently losing it. Exhausting the
|
|
P0 reserve is an explicit unrecoverable condition.
|
|
|
|
## Current boundary
|
|
|
|
Durable mode is selected only when `paperclip-runnerd` receives
|
|
`--connect-url`. Its executor accepts a Codex app-server descriptor and bound
|
|
completion contract through `run.prepare`, owns the provider process group,
|
|
resumes the persisted Codex thread after runner restart, and translates
|
|
provider notifications to PRP events. The server supplies the bootstrap ticket
|
|
only through the child environment, stores the process identity for bounded
|
|
cancellation, and waits for the durable result and terminal pair. The existing
|
|
local fake-runner mode remains unchanged.
|