Files
PaperClipAI/packages/paperclip-runner
Dotta d0718c226c feat(runner): compose ACPX runtime admission (#12399)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The ACPX pieces already verify profiles, installations, recovery
identity, permissions, runtime files, credentials, and models
independently.
> - A production host must compose those checks in one fail-closed order
and clean every acquired resource on partial startup.
> - Directly importing a third-party ACP runtime here would mix
dependency adoption with the security lifecycle.
> - This pull request defines a narrow injected runtime port and admits
it only after all package-local boundaries pass.
> - The benefit is a testable host lifecycle without adding `acpx`,
changing the lockfile, or making the adapter selectable.

## Linked Issues or Issue Description

**Agent or provider**

The qualified Pi, Claude, and Codex ACPX profiles; Codex additionally
uses the managed credential lease.

**Why this adapter is useful**

The runner needs one owner for startup ordering, immutable identity
checks, exact model verification, and cleanup. Otherwise a failure after
credential staging or command admission can leave secret files or
executable leases alive, and a resumed provider can attach to a
different profile, workspace, model, or permission mode.

**How the agent is invoked**

A later dependency-adapter pull request will implement the injected
runtime port with the pinned ACPX library. This host passes that adapter
an opaque verified command lease, canonical workspace, private state
directory, profile-bound session key, qualified permission policy,
launch-only environment, and bounded instructions. It does not expose
the runtime directly or add a user-selectable adapter.

**Additional context**

This pull request is stacked on #12398. Installation verification has a
production default; only the third-party runtime opener is injected.
Tests use a fake port so this boundary remains package-local and
dependency-free.

## What Changed

- Add a minimal ACP runtime port for identity, status, model selection,
and bounded shutdown.
- Derive the qualified profile and canonical recovery binding before any
provider startup.
- Reject expected-identity drift and irrelevant managed-Codex inputs
before opening the provider.
- Verify that even an injected installation result matches the closed
profile digest.
- Prepare the private sandbox and stage Codex credentials only for the
Codex profile.
- Acquire an opaque verified command lease and pass only the composed
launch boundary to the runtime port.
- Apply the canonical permission policy and collision-resistant provider
session key.
- Select and verify the exact effective model before returning an
admitted host.
- Create a strict versioned identity record and compare resumed provider
identifiers with the expected record.
- Keep the runtime private and expose only cloned identity, binding,
runtime-root, and persistence-safe environment views.
- On startup or shutdown failure, attempt runtime close, credential
cleanup, and command-lease cleanup in order and aggregate every error.
- Add tests for Codex secret isolation, Claude selector verification,
recovery drift, injected digest drift, partial-start cleanup, and
cleanup retry.

## Verification

- Runner TypeScript typecheck — passed.
- Runner protocol and TypeScript tests — passed: 12 protocol tests and
426 Vitest tests, including 6 runtime-host tests.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- Prettier and `git diff --check` — passed.
- The diff contains 2 files and does not change `pnpm-lock.yaml`, a
workflow, a dependency, a public package export, server selection, or UI
behavior.

## Risks

The main risk is leaking a partially admitted resource when a later
admission step fails. Resource acquisition is linear and all failure
paths use the same ordered cleanup routine. The runtime port is
deliberately minimal and privately owned by the host; it cannot bypass
profile, model, recovery, sandbox, credential, or command admission. The
actual ACPX implementation and its process-supervision behavior remain a
separate review unit.

## 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 linked an existing public item or described the
issue in this PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal task
identifier
- [x] I have run the affected tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have documented the admission and cleanup boundary
- [ ] All applicable GitHub Actions are green
- [ ] Greptile is 5/5 with every actionable comment resolved
- [x] I will address all review findings before requesting merge
2026-08-30 17:53:31 -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.