Files
PaperClipAI/packages/paperclip-runner
Dotta fd7cb77d8e feat(runner): isolate Codex runtime context (#12376)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The runner package now has a Codex-only native backend
> - A native Codex process needs an isolated runtime context before it
can start safely
> - Assigned skills, local authentication, and MCP bindings cross
separate trust boundaries
> - Runtime materialization must reject symlink escapes and unsafe
remote bindings
> - This pull request adds the package-local Codex runtime context
boundary
> - It does not start runnerd or enable the Paperclip Runner adapter

## Linked Issues or Issue Description

**Subsystem affected**

`packages/paperclip-runner` Codex runtime context materialization.

**Problem or motivation**

The runner needs a private Codex home for each native session. It must
stage only assigned skills, copy local Codex authentication safely, and
validate native MCP bindings before it exposes them to the child
process.

**Proposed solution**

Create an isolated runtime directory. Validate the skill tree before and
after copying it. Make staged skill files read-only. Read authentication
through a no-follow file descriptor with a size bound. Accept only HTTPS
or loopback MCP endpoints and bounded tokens.

**Alternatives considered**

Using the operator Codex home directly would expose unrelated state and
skills. Following symlinks while copying skills or authentication could
escape the assigned source. Accepting arbitrary MCP URLs could send a
bearer token to an untrusted endpoint.

**Roadmap alignment**

This adds a package-local safety boundary for the reviewed Codex runner
path. It does not enable a new adapter or change an existing direct
adapter path.

## What Changed

- Added the native MCP binding contract and strict validation.
- Added isolated Codex home materialization with shell snapshots
disabled.
- Added assigned-skill staging with lexical containment and two-pass
symlink checks.
- Added read-only permissions for staged skill trees.
- Added owner-only authentication staging with no-follow reads and a
size bound.
- Added cleanup for complete and partially materialized runtime
directories.

## Verification

- The focused runtime context suite has 7 passing cases.
- `pnpm --filter @paperclipai/paperclip-runner test:typescript` (36
files, 351 tests)
- `pnpm -r typecheck`
- `pnpm build`

## Risks

The main risks are filesystem escape, secret exposure, and token
delivery to an unsafe endpoint. The materializer rejects symlinks before
and after skill copying, resolves existing source paths, reads
authentication with `O_NOFOLLOW`, applies private permissions, and
restricts MCP URLs to HTTPS or loopback hosts. Existing direct adapters
do not use this package-local runtime context.

## Model Used

OpenAI Codex with GPT-5 and repository tool use.

## 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 they 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
2026-08-30 03:18:12 -05:00
..

Paperclip Runner

This private workspace package contains the staged Paperclip Runner work.

The package currently exposes the language-neutral PRP v1 TypeScript contract, provider-neutral structured questions and responses, deterministic fixture validation/replay, structured-result normalization, and the session reducer oracle. It also contains a package-local Rust runner, scripted fake harness, bounded process supervisor, cross-language replay oracle, and durable PRP transport. The transport authenticates and encrypts loopback WebSocket sessions, persists an ACK-driven outbox and command journal, and reconnects with a short-lived lease. The Rust runner now includes a Codex-only app-server provider bridge with durable thread resume, cancellation, structured questions, and provider-neutral event normalization. The root surface now also exposes an authenticated durable PRP authority for server-side use. It stores only bootstrap and reconnect credential digests, validates immutable run identity on every connection and event, and persists commands and cumulative event ACK state across server restarts. The package also publishes the canonical semantic action declarations and their input and output schemas. Its package-local dispatcher projects only bound, run-authorized actions and emits redacted semantic receipts.

The first and only installed provider is Codex. Dynamic semantic tools remain undiscoverable unless the hidden server coordinator projects one of the five same-task read bindings for an already persisted native Codex run. Catalog membership alone does not grant authority. The server can now create and start a Codex-backed native run only through the default-off paperclip_runner adapter. See SEMANTIC_ACTIONS.md for the catalog boundary.

The package has two initial public surfaces:

  • @paperclipai/paperclip-runner contains runtime contracts, validation, replay/reducer logic, the semantic catalog, the authorization dispatcher, and the Node-only durable server authority.
  • @paperclipai/paperclip-runner/testing adds Node-only fixture loading and a provider-neutral semantic conformance kit for deterministic test adapters.

No SDK, browser, React, eval, live-console, lab, or provider-experiment entry point is exported. The package remains private in this wave. The server route at /api/runner/v1/connect/:runId has no authority until the hidden coordinator registers an exact existing run binding. Fresh native starts are rejected unless the instance enableNativeRunner flag is enabled. Existing direct adapters keep their original execution path.

The package build compiles the release paperclip-runnerd executable and stages it under dist/bin. The normal server build vendors that directory, so an installed server does not depend on a separate system Rust installation or a manually copied binary. pnpm-lock.yaml remains under the repository's existing lockfile process.

Run the complete contract gate with:

pnpm --filter @paperclipai/paperclip-runner check:protocol

Run the Rust runner gate with:

pnpm --filter @paperclipai/paperclip-runner check:runner

This command checks Rust formatting, builds and tests the minimal workspace in release mode, verifies bounded process cleanup, launches the real paperclip-runnerd binary through the fake harness, and compares the Rust conformance and replay summaries with the shared fixtures. The checked-in Cargo lock and pinned Rust toolchain keep this verification reproducible.

Durability and failure semantics are documented in runner/DURABLE_TRANSPORT.md. The fault suite drops a connection before its event ACK, reconnects with the bound lease, replays the same event, and proves the duplicated command effect ran once. Codex launch, resume, cancellation, and normalization behavior is documented in runner/CODEX_PROVIDER.md.

Use generate:protocol-manifest after a schema or fixture change, generate:protocol-types after a schema change, and generate:replay-goldens after an intentional reducer change. Commit generated outputs with their sources; do not edit them by hand.

Use generate:semantic-action-catalog after changing a semantic action declaration. Its checked-in JSON inventory must land with the source change.

The gate compiles every schema with AJV 2020-12, validates accepted fixtures, rejects unsupported required versions, checks generated TypeScript schema drift, runs the TypeScript contract tests, and compares reducer snapshots and parity summaries byte-for-byte with their checked-in golden files.