## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Conversations must use the same tasks, controls, and execution
history.
> - Users need an ongoing chat with an agent without managing task
properties.
> - Agents should clarify and plan work, then hand execution to assigned
project tasks.
> - This pull request combines the reviewed Agent Chat stack for one
squash merge.
> - The benefit is persistent conversation with normal task governance
and shared UI.
## Linked Issues or Issue Description
**Subsystem affected**
Task lifecycle, agent runtime tools, shared task UI, and browser/paid
runner tests.
**Problem or motivation**
Users need one persistent conversation with each agent. A separate chat
store or renderer would duplicate task behavior and bypass existing
controls.
**Proposed solution**
Use a task-backed chat per company, user, and agent. Reuse the task
composer and transcript. Clarify and plan in chat, then create assigned
project tasks with the relevant plan. Keep Agent Chat behind its own
disabled-by-default experimental setting.
**Roadmap alignment**
This implements the task-backed direction in [CEO
Chat](https://github.com/paperclipai/paperclip/blob/master/ROADMAP.md#-ceo-chat).
Related proposals: #2504 and #9693. Related request: #7981. The
maintainer requested one squash merge of the complete stack.
Consolidates the reviewed runtime
[#13281](https://github.com/paperclipai/paperclip/pull/13281), backend
[#13282](https://github.com/paperclipai/paperclip/pull/13282), and UI
[#13283](https://github.com/paperclipai/paperclip/pull/13283) layers
with this PR's E2E coverage. All four layers passed CI and received
Greptile 5/5 before consolidation. This PR targets master and includes
the complete feature.
## What Changed
- Add personal canonical chat tasks with ordinary company visibility,
immutable identity, idempotent first sends, and an idle waiting state.
- Process `/new` in queue order. Preserve history, release a chat pause,
and fence old provider context and delayed writes.
- Keep chat lifecycle rules across recovery, finalization, assignment,
task lists, and rollups.
- Support research and plan revision in chat. Hand plans to ordinary
assigned project tasks before execution starts. Reject new chat
subtasks.
- Add repository-aware project creation and discovery tools, including
multiple repository IDs and GitHub URLs, authorization, idempotency, and
durable project-created cards.
- Reuse task UI components for chat, with starred/recent agent
navigation and a separate `enableAgentChat` experimental flag.
- Add deterministic browser tests and 24 paid chat cells across four
Codex/Claude profiles, with validated reports and screenshots.
- Integrate current master recovery, controller lease, queued-message,
and task UI changes. Gate chat interruption and deferred promotion on
ownership/feature policy. Guarantee lease renewal and active controls
are stopped even if teardown fails.
- Preserve master's migration 0273 and generate chat migration 0274 with
idempotent replay for development databases.
## Verification
- Prior exact heads of all four PRs passed Linux CI, including build,
typecheck, general/serialized tests, and browser E2E. Each had Greptile
5/5 and no unresolved findings.
- Integrated local verification passed: full repository typecheck and
production build, Storybook build, token gates, 340 focused UI tests,
all 20 deterministic chat browser tests, two migration replay tests, 88
focused chat/queue/native/controller tests, and provider/session
regressions including real lease expiry. These include the three
lifecycle regressions for the final admission/teardown fixes; server
typecheck also passes. Current head
`1268eda16cc2af892055917e7292f068820be135` has Greptile 5/5 with no
unresolved findings and passing security scans. All final-head CI gates
passed: build, full Runner verification, typecheck/release registry,
canary, all general/serialized test shards, and all browser E2E shards
([CI
run](https://github.com/paperclipai/paperclip/actions/runs/34696739927)).
Local PostgreSQL startup contention required serialized retries; skipped
fixtures do not count as passing coverage.
- The earlier paid campaign passed all 24 chat cells and retained 32
screenshots:
[report](https://d1p6rlowie26tp.cloudfront.net/runner-e2e/campaigns/gha-34648511170-1/index.html?report=agent-chat#suite-agent-chat).
It tested `abacbdfd2f660709ec37312cdb758284c8399d04`; it is prior
evidence, not a paid run of this integrated head.
- Manual check: enable Agent Chat in Experimental settings, open an
agent, clarify and revise a plan, then hand off to an assigned project
task. Stop a reply, send `/new`, and verify fresh context with retained
history. Disable the setting and verify agent shortcuts/new chat turns
are blocked.
## Risks
- Queue/session integration can affect retries and delayed writes. Tests
cover ownership, cancellation, reset boundaries, idle recovery, and
ordinary task behavior.
- Migration 0274 adds conversation fields and constraints. Replay is
idempotent and preserves existing development chat history.
- This combines the previously reviewed stack at the maintainer's
request. Agent Chat remains off by default and is separate from
Conference Room.
## Model Used
OpenAI Codex, GPT-6 Astra (`gpt-6-astra`), with reasoning, code
execution, browser tools, and parallel review. The exact context-window
size is not exposed in this session. Codex and Claude also ran as test
subjects in the linked paid campaign.
## 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
- [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
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip manages AI agents and their work.
> - The new runner gives agents dedicated tools for common tasks.
> - Some API operations and parameters have no dedicated tool.
> - Agents need a controlled way to find and use those operations.
> - This pull request adds API search and calls through the real server
routes.
> - Existing tools remain the preferred path. The new tools are disabled
by default.
> - Paired tests measure correctness, tool choice, cost and time.
## Linked Issues or Issue Description
**Subsystem affected**
Paperclip Runner contracts, production tool authority and the server API
catalog.
**Problem or motivation**
The runner cannot use much of the API described by the old Paperclip
skill. A generic HTTP client would also let agents bypass runner control
rules.
**Proposed solution**
Add `search_api` and `call_api`. Resolve calls from the mounted API
catalog. Use server-held, run-bound credentials. Preserve route checks
and runner lifecycle rules. Keep the tools disabled until an operator
enables selected companies.
**Alternatives considered**
A dedicated tool for every endpoint would add a large initial prompt. An
unrestricted HTTP tool would weaken authorization and replay controls.
**Roadmap alignment**
This extends the native runner tooling. The repository owner requested
this design and implementation. The roadmap and related open PRs were
checked. No duplicate API escape-hatch PR was found.
## What Changed
- Register two compact fallback tools in canonical contracts and
provider projections.
- Build deterministic API discovery from OpenAPI, mounted experimental
routes and the old skill reference.
- Execute bounded JSON, text, file and download requests through
authenticated HTTP routes.
- Recheck active runs, company access and work modes. Block runner
lifecycle, scheduling, credential and approval bypasses. Keep routine
annotation collaboration available.
- Retain mutation receipts. Report uncertain outcomes without blindly
repeating writes.
- Add a company rollout gate and a durable eval worker with complete
cost accounting checks.
- Record child-task creation in the activity log with the agent and run.
- Add contract, authorization, file, replay and real runnerd/PRP/HTTP
tests.
- Document rollout gates and paid coverage limits. The companion eval
repository retains immutable attempts and reports.
## Verification
- Final app commit `da58370524c3626a744eec20164397c5fb6ba9ef`: all 32
checks passed; the unrelated Storybook visual check was skipped.
Greptile 5/5; no unresolved review threads.
- Full Linux build and recursive typecheck passed. Repository tests were
run by project and serialized shard; all 143 serialized server suites
passed.
- Runner TypeScript: 1,599 passed, two skipped. Rust release: 451
passing test reports. Conformance and replay parity passed. The required
API check passed 837 tests, including runnerd → PRP → authority → real
HTTP.
- Bindings cannot enable API tools without the explicit deployment flag.
Unit and real-authority tests prove the default-off boundary.
- The standalone API check builds and stages its own binary. It passed
after existing staged and debug binaries were removed from the test
container.
- UI and CLI tests passed. Initial environment failures (missing jq,
Docker overlay file identity, and parallel linker memory pressure) and
focused passing reruns are retained. The macOS full runner suite has
platform-specific failures; Linux is the qualified full-check platform.
- Eval harness: 27 tests passed; existing CI discovery ran 86 tests with
two unrelated skips. Credential export rejection is tested against the
actual report command.
- Luna and OpenRouter Sonnet each passed 60 common-workflow runs: ten
workflows, three repetitions per arm, zero unnecessary API fallback.
- Sonnet passed 11 selected capability/contract cases after fixes.
Gemini passed three smoke cases. DeepSeek exceeded the 120-second limit
and remains unqualified.
- Luna's two cost flags received focused follow-up. The original flags
and a later n=1 latency flag remain visible. Sonnet had no cost or
latency increase above 20%.
- The catalog contains 785 entries; 58 were exercised across all stages.
Most operation probes remain unrun and some need additional fixtures.
Authored probes do not establish successful coverage.
- Total conservative accounted cost: $9.875960. Active paid-campaign
time: 88.16/90 minutes. No missing accounting. Later security and
harness fixes have provider-free verification; no paid validation is
claimed for those revisions.
- Inspect the [qualification
report](https://github.com/paperclipai/paperclip-evals/blob/codex/seach-call-api-tools/evals/runner-api-tools/reports/2026-09-07-production/READINESS.md)
and [verification
record](https://github.com/paperclipai/paperclip-evals/blob/codex/seach-call-api-tools/evals/runner-api-tools/reports/2026-09-07-production/verification.json).
## Risks
- This is a broad authenticated API surface. Keep the default-off gate
until an operator selects initial rollout companies.
- Paid coverage is incomplete. Small regression samples do not prove all
workflows are unchanged.
- A timeout or server failure can follow a committed mutation. The
result reports an unknown outcome and requires state inspection.
- The new definitions add prompt tokens. The report retains cost flags
and cache variation.
- No database migration is required.
- Repository rules require code-owner approval before merge. Technical
CI and automated review are complete.
## Model Used
OpenAI Codex based on GPT-6 assisted with code, tests and review. The
exact serving model ID and context window are not exposed in this
session. It used reasoning, tool calls and code execution.
Eval models: `gpt-5.6-luna` with low reasoning,
`openrouter/anthropic/claude-sonnet-5`,
`openrouter/google/gemini-3.8-flash`, and
`openrouter/deepseek/deepseek-v4-flash-0731`. Attempts retain runtime
versions, model identity, usage and source provenance.
## 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
- [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
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the control plane for agents that perform work.
> - Paperclip Runner connects durable provider sessions to individual
task runs through PRP.
> - Provider continuity and per-run authority are different lifetimes.
> - The existing implementation mixed those lifetimes and lost event
metadata between provider frames, runnerd, persistence, API
sanitization, and the task thread.
> - That caused failed continuation, missing progress and Plans,
duplicate replies, hidden failures, and unsafe recovery.
> - This repair gives every heartbeat fresh authority, preserves
qualified provider-session continuity, and restores one lossless
presentation path without changing direct adapters.
## Linked Issues or Issue Description
**What happened?**
A second native heartbeat could reuse tickets, leases, command receipts,
sequence state, and run identity from the first heartbeat. Provider
phase and item identity could be lost before the UI read them. Redaction
could corrupt protocol discriminators while still missing malformed
credential tails. The task thread could fold progress into the final
response, hide failures, or show more than one final answer. Native
Codex also exposed approval modes that do not yet have a durable
approval bridge.
**Expected behavior**
Each heartbeat uses a new PRP authority epoch. Codex and OpenCode
preserve exact qualified provider sessions; ACPX emits an explicit
continuity event when its qualified process-replacement policy is used.
Every accepted provider event is presented, classified as internal, or
surfaced as unsupported. The task page shows chronological progress,
reasoning summaries, activity, Plans, interactions, terminal failures,
and exactly one final reply. Direct adapters retain their existing path.
**Steps to reproduce**
1. Enable the unified experimental Paperclip Runner setting.
2. Create a local native Codex, OpenCode, ACPX Claude, or ACPX Codex
agent.
3. Run response, Plan, structured-question/resume, restart,
cancellation, and failure scenarios.
4. Reload the task while active, waiting, failed, and settled.
5. On the old implementation, observe stale run authority, missing
classifications, incomplete output, or duplicated/folded replies.
**Paperclip version or commit**
The repair is based directly on `master` at
`87d05e194b643810d16d20612115acd01d735d43`.
**Deployment mode**
Local development with the embedded database.
Related work: Refs #12616, #12646, #12666, #12685, and #12700.
## What Changed
- Rotates PRP control-plane, outbox, ticket, lease, command, receipt,
and sequence authority for each heartbeat while carrying forward only a
validated provider-session identity.
- Reads `control-plane-state.json`, validates both durable schemas and
lifecycle values, resumes coherent current runs, archives qualified
settled authority, and quarantines malformed or mismatched scoped state
without moving ambiguous live legacy state.
- Preserves Codex provider phase and stable item identities so
commentary remains progress and only `final_answer` becomes final.
- Adds raw OpenCode HTTP/SSE boundary coverage and canonical reasoning
lifecycle mapping.
- Makes ACPX normalization lossless for visible reasoning, tool
lifecycle metadata, stable bounded identities, Plan revisions,
structured requests, failures, and qualified process replacement. Only
the compatible terminal assistant message is promoted as final.
- Applies schema-aware redaction before generic JWT-shaped detection and
scans every diagnostic string leaf. Malformed raw/escaped quoted
credential tails are redacted in both server and durable Rust state.
- Restores snapshot-style chronological task presentation, expandable
tool activity, inline Plan cards, visible waiting/resume/cancel/failure
states, and exactly one final answer.
- Makes `never` the only qualified native Codex permission mode and
rejects unsupported persisted native modes with remediation. OpenCode
and ACPX policies remain intact.
- Keeps the unified experimental Runner setting as the only enablement
flag. Onboarding and direct Codex, Claude, and OpenCode stay on their
legacy execution/finalization paths.
- Adds cross-language goldens, authority/recovery/fault coverage, exact
response/count assertions, and native plus legacy acceptance scenarios.
## Verification
- Pull-request GitHub Actions run Rust formatting/tests, TypeScript
checks, server/UI tests, builds, protocol drift checks, browser E2E, and
security scans.
- A separate workflow-only validation ref is pinned directly on this PR
head and runs the 35-cell paid local matrix: three core scenarios plus
structured-question resume and restart/resume for native Codex, native
OpenCode, ACPX Claude, ACPX Codex, and direct Codex/Claude/OpenCode.
Run: https://github.com/paperclipai/paperclip/actions/runs/33682434315
- Acceptance requires exact single visible replies, monotonic sequences,
matching envelope discriminators, one semantic terminal, one run
terminal, no unresolved interaction, no duplicate mutation, no secret
leakage, provider continuity, and zero native rows for direct adapters.
- Per maintainer direction, tests are running in GitHub Actions rather
than on the slower local host. Only formatters and static diff checks
were run locally.
## Risks
- Recovery from old or partial filesystem state is sensitive. The repair
fails closed, preserves active or unverifiable authority, and
quarantines only state whose scoped ownership is safe to move.
- Provider event formats can change. Closed validators and boundary
goldens turn new or malformed events into visible diagnostics instead of
silent drops.
- Shared task presentation could affect direct adapters. Runtime-fact
gating plus the direct-adapter matrix protect the existing path.
- Managed and remote providers are not qualified here. Shared code
continues to compile and fail safely, but live qualification is
deferred.
> 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 based on GPT-5. The exact deployed snapshot and
context-window size are not exposed to this task. It used agentic
reasoning, repository inspection, code editing, Git, parallel subagents,
and GitHub Actions.
## 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 and contains no internal
Paperclip ticket id
- [ ] I have run tests locally and they pass (intentionally deferred to
GitHub Actions)
- [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 risks above
- [ ] All Paperclip CI gates are green
- [ ] The paid local-provider matrix is 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner needs repeatable evaluation contracts.
> - Evaluation code must stay separate from provider launch and
production orchestration.
> - Offline fixtures need stable compatibility, scoring, traceability,
and report rules.
> - Published Runner consumers need only the supported evaluation
contract surface.
> - This pull request adds offline evaluation tooling and a
workspace-private matrix kernel.
> - The benefit is deterministic evaluation without credentials or paid
provider calls.
## Linked Issues or Issue Description
Refs #11297
This pull request extracts the offline evaluation unit from the earlier
aggregate Runner work.
## What Changed
- Add a workspace-private, provider-neutral evaluation matrix kernel.
- Add the public `@paperclipai/paperclip-runner/evals` compatibility and
native execution contracts.
- Add fail-closed runnerd artifact and protocol compatibility checks.
- Add deterministic workflow catalogs, scoring, traceability, and report
generation.
- Add sanitized Codex, OpenCode, and ACPX fixtures.
- Add package-boundary and clean-consumer checks.
- Add the eval package manifest to the Docker dependency stage.
- Add the generated protocol fixture digest without changing the
lockfile.
## Verification
GitHub Actions must run:
- Runner TypeScript and Rust type checks.
- Runner unit and protocol tests.
- Evaluation kernel tests.
- Workflow traceability checks.
- Clean-consumer and package-boundary checks.
- Repository test, type-check, build, policy, and security gates.
No local test command was run. The repository owner requested
GitHub-only verification.
## Risks
This is a large greenfield review surface with 51 files. The code does
not launch a live provider or load credentials. Package and protocol
drift fail closed. The workspace lockfile remains under the existing
CI-owned process.
## Model Used
OpenAI Codex with the GPT-5 agent model. The work used high reasoning,
repository inspection, tool use, and parallel code review.
## 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
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package already provides the production protocol and
execution spine.
> - Contributors still need stable SDK surfaces, deterministic test
tools, and local inspection tools.
> - Those surfaces share generated contracts and must change as one
package boundary.
> - This pull request adds the package-local SDK, labs, examples, and
drift checks.
> - The benefit is a reviewable developer platform that does not change
application execution selection.
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` — runner SDK, conformance tools, and
developer tooling.
**Problem or motivation**
The production runner spine is present, but package consumers cannot
build deterministic integrations, inspect sessions, or verify
provider-neutral behavior through supported surfaces.
**Proposed solution**
Add browser, React, standalone, live-session, scenario, conformance, and
evaluation surfaces. Add generated contract inventories and
package-local verification scripts. Keep production application routing
unchanged.
**Alternatives considered**
We considered splitting each generated catalog, SDK surface, and demo
into separate pull requests. Those changes share exports, fixtures, and
drift gates. Splitting them would create intermediate package states
that do not build.
**Roadmap alignment**
No overlapping item appears in `ROADMAP.md`. This work extends the
runner package that is already on `master`.
## What Changed
- Add browser, React, standalone, live-session, and issue-thread SDK
surfaces.
- Add deterministic mock control-plane, scenario, conformance, replay,
and evaluation tools.
- Add bounded Codex, OpenCode, and ACPX development transports and
fixtures.
- Keep deferred managed-provider execution fail-closed. Persisted
compatibility data remains readable.
- Add generated capability inventories with their source files and drift
checks.
- Add examples, package documentation, browser checks, and
clean-consumer checks.
- Preserve the reviewed protocol bounds, replay compatibility aliases,
process environment isolation, and semantic redaction limits.
- Update the ACPX package patch that the existing workspace patch
registry already tracks.
- Do not change `pnpm-lock.yaml`, repository workflows, server runtime
selection, or the application UI.
## Verification
GitHub Actions is the verification authority for this pull request. The
repository CI, package TypeScript and Rust checks, package tests,
generated-output drift checks, browser checks, security scans, and
Greptile review must pass on the exact head.
Local test suites were not run because this series uses parallel GitHub
Actions for verification.
## Risks
This is a large greenfield package change. The main risks are public
export drift, generated-output drift, and optional React consumer
compatibility. Package boundary checks, clean-consumer checks, and
browser tests cover those risks. Production adapter selection and server
execution are outside this pull request.
## Stack
1. **This PR:** runner SDK and developer tooling.
2. [Codex production server
integration](https://github.com/paperclipai/paperclip/pull/12616).
3. [Provider-neutral task-thread
UI](https://github.com/paperclipai/paperclip/pull/12617).
## Model Used
OpenAI Codex, GPT-5, high-reasoning mode, with tool use and code
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 described the issue in-PR following the feature request
template
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner provides a durable execution boundary for supported
providers.
> - The current production runtime supports Codex but cannot execute
OpenCode sessions.
> - OpenCode needs a qualified transport, strict input mapping, and
normalized events.
> - This pull request adds the OpenCode runtime as one isolated provider
unit.
> - The benefit is a reviewable provider expansion that does not weaken
the existing Codex path.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting: packages/paperclip-runner and the Codex-local adapter
configuration contract.
**Problem or motivation**
Paperclip Runner has provider-neutral contracts, but the production
backend factory cannot start a qualified OpenCode session. This blocks
OpenCode from using the durable runner path.
**Proposed solution**
Add the qualified OpenCode app-server proxy, driver, MCP bridge,
backend, fixtures, and factory wiring. Keep existing Codex behavior
unchanged.
**Alternatives considered**
Keeping OpenCode only on the direct adapter path would avoid this
runtime work, but it would not provide durable runner recovery or
normalized provider events.
**Roadmap alignment**
ROADMAP.md does not list a conflicting provider-runtime project. This
change extends the existing Paperclip Runner architecture.
## What Changed
- Added the qualified OpenCode app-server proxy and input queue.
- Added collaboration-mode and provider-event normalization.
- Added the OpenCode MCP bridge and native session backend.
- Added strict fixtures and focused unit coverage.
- Added only the package exports and adapter configuration required by
this runtime.
- Kept deferred SDK, lab, eval, and public package surfaces out of this
change.
## Verification
- GitHub Actions is the authoritative verification environment for this
PR.
- Run the package type checks and focused OpenCode tests in CI.
- Run repository typecheck, test, build, security, and policy gates
through the stack-aware workflow.
- Local tests were not run because this checkout is resource
constrained.
## Risks
- OpenCode protocol changes could affect event normalization or
recovery.
- The driver fails closed on malformed input and unsupported runtime
behavior.
- Existing Codex selection remains unchanged unless the stored provider
is OpenCode.
> 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.
## Model Used
OpenAI Codex, GPT-5.6, with repository tools, code execution, and
parallel agent review.
## 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 existing issues or described the issue in-PR
following the relevant issue template
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] I have run tests locally and they pass — GitHub Actions is
authoritative for this resource-constrained checkout
- [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
## Stack
- Position: 1 of 4
- Base: master
- Next: additional qualified provider runtimes
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now owns validated, scoped ACPX reducer events and
safe session suspension
> - Durable PRP transport must receive provider-neutral events rather
than sidecar-native envelopes
> - Semantic calls and questions must retain the exact run, session,
turn, item, and provider-request authority used by the durable command
stream
> - Terminal, result, assistant, process, and diagnostic events also
need one reviewed projection boundary
> - Permission requests remain impossible under the pinned Codex policy
and must fail closed if they reach projection
> - This pull request adds only that package-local projection without
selecting ACPX in runnerd
## Linked Issues or Issue Description
Refs #12422
## What Changed
- Add a validated durable ACPX event projection context bound to one
run, normalized session, turn, and item.
- Pass already normalized activity events through without reintroducing
provider-native envelopes.
- Project authorized tool calls into canonical semantic input receipts
with exact correlation and content digests.
- Project structured questions into provider-neutral
`paperclip.runtime_request.v2` events.
- Preserve both the public projected request identity and the original
provider request identity so responses resolve the exact sidecar
request.
- Project dynamic semantic operation results as `semantic_tool.result`;
only reserved finish/block operations may propose the run result.
- Project semantic completion results into `run.result.proposed`.
- Project terminal-flushed assistant messages on the final channel and
turn terminal states into existing provider-neutral event families.
- Project sanitized process metadata and diagnostics into bounded
harness diagnostics.
- Validate runtime-request origins against their strict durable shape
and fall back from empty optional titles to a valid question prompt.
- Reject invalid identities, projected-identity collisions, unstable
semantic receipt identities, permission requests, and cross-turn
projection fail closed.
- Add integration coverage across reducer event families, correlation,
identity validation, projected question resolution, and pinned-policy
denial.
- Document the durable projection boundary.
- Do not change dependencies, lockfiles, workflows, runnerd selection,
server behavior, UI, or migrations.
## Verification
- Replay base: `80639f4f69c8938eb74bdc0833df93e0ed91dab3` (`master`
after #12422 merged).
- Exact replay head: `3cb29581d2bcbc4b47f8069baffd721c6ce4e444`.
- Stable patch ID: `92910b56575e67ae83960177d467a565019ba282`.
- The exact delta is 22 files, 1,206 additions, and 59 deletions, all in
`packages/paperclip-runner`; it contains no lockfile, workflow, server,
UI, dependency, or migration change.
- `git diff --check` and the Cargo formatting check pass on the replayed
delta.
- Exact-head GitHub Actions run `33372209037` (attempt 2): **PASSED**
with 23/23 jobs passed.
- Greptile reviewed exact head
`3cb29581d2bcbc4b47f8069baffd721c6ce4e444`: **5/5**, with zero
unresolved review threads.
- Superagent, contributor trust, Socket, and Snyk security checks:
**PASSED**.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- This function accepts reducer output, not raw sidecar frames. Callers
must preserve the existing scope-first decode and reduction order.
- Semantic input includes the already sanitized provider input while its
content receipt uses the same canonical digest.
- Structured input preserves the validated provider-neutral question set
and sanitized origin.
- Noncanonical provider request identities are deterministically
projected for PRP while the original identity remains authoritative for
the sidecar resolution command.
- Existing PRP v1 identifiers remain schema-compatible; the only public
ID-schema change widens turn/item limits from 160 to 240 characters. The
internal ACPX sidecar wire schema now mirrors the stable IDs its Rust
transport already enforced.
- The projector verifies event-carried terminal and assistant turn
identifiers against the durable context.
- No production path invokes this projector in this pull request.
Durable command execution remains the next slice.
> 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.6, agentic reasoning, tool use, and code
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 linked the preceding public PR or described the issue in-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
Paperclip ticket id
- [ ] 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
- [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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Rust runner now owns a bounded ACPX session and a fail-closed
turn lifecycle
> - Provider questions pause a turn and must return structured answers
to the same persisted question set
> - JSON Schema validates the wire shape, but it cannot validate
identifiers and constraints across two documents
> - Unknown questions, invalid choices, and malformed custom answers
must fail before any provider receives them
> - This pull request adds only the package-local response validator and
tests
> - The benefit is a small trust boundary that later request-resolution
code can use without changing production selection
## Linked Issues or Issue Description
Refs #12419
## What Changed
- Validate `paperclip.question_response.v1` against its versioned JSON
Schema.
- Bound serialized responses to 768 KiB before validation.
- Require answer identifiers to match the exact persisted question set.
- Require answers for required questions and reject unknown question
identifiers.
- Enforce text, single-select, and multi-select answer modes.
- Match the existing TypeScript numeric syntax, including decimal,
exponent, hexadecimal, octal, and binary input.
- Match ECMAScript trimming exactly, including BOM whitespace while
rejecting Unicode NEL rather than inheriting Rust-specific whitespace
behavior.
- Enforce known options, custom-answer policy, text length, pattern, and
numeric constraints.
- Validate duplicate option IDs, inverted bounds, and dynamic patterns
before answer lookup so malformed optional questions fail closed even
when unanswered.
- Match JavaScript UTF-16 code-unit length semantics for text
constraints and the 100,000-unit response-field bound.
- Preserve the public optional `recommended` question-option field in
the versioned schema, generated schema bundle, and Rust validation path.
- Return typed validation errors for malformed inputs without panics.
- Export the validator from the Rust runner core.
- Add table-driven tests for valid, mismatched, malformed, oversized,
and numeric-boundary responses.
- Document the package-local structured-response boundary.
- Add `num-bigint` 0.4 and `num-traits` 0.2 as direct runner-core
dependencies for exact arbitrary-length radix parsing and one-step
JavaScript Number rounding; update only the package-local runner Cargo
lockfile.
- Do not change the repository PNPM lockfile, workflows, runnerd
selection, server behavior, UI, or migrations.
## Verification
- Replay base: `9a9fdf06ee4142f77427db30efccc4c43056f64b` (`master`
after #12419 merged).
- Exact replay head: `fad92b3fb348b66ddb10dde44b7b060e55c4fe96`.
- Stable patch ID: `4d6ffbd519dd081f7ea530977cd965bd4569fc75`; this is
the prepared two-commit delta plus the focused cross-language parity fix
found during replay review.
- The exact delta is 10 files, 712 additions, and 2 deletions, all in
`packages/paperclip-runner`.
- The package-local `packages/paperclip-runner/runner/Cargo.lock`
records the two direct runner-core dependencies; their already-resolved
versions and checksums are unchanged.
- The question-set schema source, generated TypeScript schema bundle,
and protocol manifest hash are updated together; the schema SHA-256 is
`42b5441a3d388851dacb6e4500dfd4a17d878eded2e724228078b647e7440d3f`.
- GitHub Actions run `33366812025`, attempt 2: **PASSED** on the exact
replay head (23/23 jobs passed; a failed-job-only retry cleared one
unrelated ACPX runtime-host timeout).
- Greptile: **5/5** on the exact replay head with zero unresolved review
threads; Superagent, Socket, Snyk, and contributor-trust checks also
passed.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for this replayed revision.
## Risks
- The validator compiles the embedded response schema for each
submission. Responses are user-paced and bounded, so this keeps the
slice simple without affecting a hot event path.
- The persisted question set is the source of truth for identifiers and
constraints. A malformed persisted set fails closed.
- Numeric input follows the existing structured-question contract,
including JavaScript-prefixed syntax. Optional whitespace-only answers
are rejected instead of being treated as an omitted value.
- Error messages identify the invalid field but do not include answer
text.
- No production path invokes this validator in this pull request.
Request resolution remains the next slice.
> 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.6, agentic reasoning, tool use, and code
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 and contains no internal
Paperclip ticket id or instance-derived details
- [ ] 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
- [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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner maps provider questions to one versioned Paperclip
contract.
> - Codex and ACPX now perform that mapping through separate adapters.
> - Separate adapter tests do not prove that both paths preserve the
same user-visible form.
> - Fixture validation must also match production behavior for optional
answers and unsupported patterns.
> - This pull request adds shared fixtures, validation, and
cross-adapter conformance checks.
> - The benefit is a reusable question contract for later providers
without enabling a new runtime.
## Linked Issues or Issue Description
Refs #12408
This pull request builds on the Codex ACPX question bridge merged in
#12408. It adds fixture and generator checks for the existing Codex and
ACPX question adapters. It does not add another provider or production
execution path.
## What Changed
- Add a canonical ACPX form fixture and native response. Mark the
equivalent Codex fixture field as required.
- Add shared validation for question IDs, option IDs, answer modes,
required answers, text bounds, numeric bounds, and response shapes.
- Evaluate fixture-only regular expressions in a bounded child process.
Reject patterns that cannot finish safely.
- Validate ACPX fixtures against a manifest-side mirror of the
production form projection. Reject free-text ACPX patterns, but ignore
patterns on enumerated option fields.
- Accept explicit empty optional answers and omit them from the
projected ACPX response, which matches the production parser.
- Validate every question fixture during manifest generation and
regenerate the checked-in manifest.
- Add cross-adapter tests that compare user-visible presentation while
preserving provider-owned IDs and provider-specific response conversion.
- Add negative regressions for malformed forms, invalid responses,
unsafe patterns, special property names, and projection drift.
## Verification
- Replay base: `4fe3189f0256873a359d2d53c209076919fd1c3b` (`master`
after #12408 merged).
- Exact replay head: `0532e7dfbb5a246033ffeef55a0c0013fdab07f1`.
- Stable patch ID for the intended seven-file delta:
`28154d86b2c37e0e8d442419e26703584852f67e`.
- The intended pull request delta contains exactly these seven files:
- `packages/paperclip-runner/protocol/fixtures/questions/acpx.json`
- `packages/paperclip-runner/protocol/fixtures/questions/codex.json`
- `packages/paperclip-runner/protocol/manifest.json`
- `packages/paperclip-runner/scripts/generate-protocol-manifest.mjs`
- `packages/paperclip-runner/scripts/protocol-contract.mjs`
-
`packages/paperclip-runner/src/contracts/question-adapter-conformance.test.ts`
- `packages/paperclip-runner/test/protocol-contract.test.mjs`
- The intended combined delta is 1,211 additions and 20 deletions.
- This change does not add a dependency, lockfile update, migration,
workflow, server route, UI change, documentation file, or production
runtime change.
- GitHub Actions run `33352004952` passed the complete matrix on retry
at the unchanged exact head, including protocol/package verification,
build, typecheck/release-registry, general and serialized server suites,
canary, and all e2e shards.
- Superagent, Socket, Snyk, contributor-trust, policy, and PR-review
checks pass on the exact replay head.
- Greptile reviewed the exact replay head at 5/5 with no blocking
finding and zero unresolved review threads.
- No local test result is claimed. GitHub Actions is the authoritative
verification environment for the replayed revision.
## Risks
This change has low runtime risk because it changes fixtures, generator
validation, generated metadata, and tests only. Fixture pattern checks
run in a child process with a one-second timeout and a bounded output
buffer. The ACPX gate intentionally rejects free-text patterns because
the production adapter has no bounded expression engine. It
intentionally permits an explicit empty optional answer because
production omits that answer from the native response. A validation
mismatch can block manifest generation, but it cannot change server
selection, direct adapters, or task-page behavior.
> 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.6, extended reasoning, repository tool use, and
code 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
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] 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
## Thinking Path
> - Paperclip Runner now has a complete guarded Codex vertical slice.
> - The next provider series must not start by importing a provider
implementation or dependency bundle.
> - ACPX needs one bounded, versioned process boundary shared by
TypeScript and Rust.
> - A schema is the authority; checked-in generated inventories keep
both languages in lockstep.
> - Unknown versions, commands, event types, and properties must fail
closed.
> - This pull request therefore lands only the sidecar wire contract and
its drift gate.
> - No ACPX runtime, dependency, executable, package export, or
production selection is added.
## Linked Issues or Issue Description
This is the first package-local unit in the post-Codex provider series.
**What happened?**
The integration branch contains an ACPX provider, but its TypeScript
sidecar and Rust client need a small shared authority before either
implementation can be reviewed safely. Importing the final integration
implementation directly would mix the protocol, runtime, third-party
dependencies, and production wiring.
**Expected behavior**
The schema defines every ACPX sidecar request, response, event, command,
event type, and protocol version. Generated TypeScript and Rust
inventories must drift-check against that schema. No runtime can select
or execute ACPX yet.
**Steps to reproduce**
1. Change the protocol version, command inventory, or event inventory in
the schema.
2. Run the runner protocol type check without regenerating the language
inventories.
3. Observe the drift gate fail.
**Paperclip version or commit**
Stacked on `runner-server-semantic-codex` at `ebd7f9df7`.
## What Changed
- Add the internal ACPX sidecar v2 JSON Schema outside the public PRP v1
schema catalog.
- Generate one TypeScript inventory and one Rust inventory from that
schema.
- Add generate and check hooks to the existing runner protocol-type
workflow.
- Add fail-closed AJV tests for all three message families, version
drift, unknown commands, and extra properties.
- Keep the generated Rust module unregistered until the Rust ACPX
transport exists.
## Compatibility Boundary
- Codex remains the only production runner provider.
- `paperclip_runner` selection and the default-off rollout flag are
unchanged.
- No ACPX package, patch, lockfile, binary entry point, root export,
server file, UI file, workflow, or dependency is added.
- The schema is shipped with the existing `protocol` directory but is
not added to the public PRP manifest.
- Existing direct adapters continue through their current paths.
- Diff against the actual stacked base: 6 files.
## Verification
- Runner TypeScript typecheck and both generated-contract drift gates —
passed.
- Runner TypeScript tests — 37 files and 355 Vitest tests passed; 11
Node contract tests passed.
- Rust provider-bridge regression suite after restacking — 14/14 passed.
- `pnpm -r typecheck` — passed for all applicable workspaces.
- `pnpm build` — passed, including runner binary, server, UI, and
workspace packages.
- `pnpm test:run` — attempted; the local host reproduced unrelated
workspace/Postgres and port-exposure failures in unchanged server
suites. The changed runner contract suites pass, and the repository's
serialized/sharded GitHub checks remain authoritative for those
host-sensitive suites.
- Prettier, rustfmt, generated-source drift checks, and `git diff
--check` — passed.
- `pnpm-lock.yaml` is unchanged.
## Risks
The main risk is allowing schema and generated language inventories to
diverge. Build and typecheck now fail on any drift. The sidecar
implementation and third-party ACPX packages are deliberately absent, so
this PR cannot alter runtime behavior or expand the production attack
surface.
## 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
- [x] I have described the issue and expected behavior 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 compatibility and security 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Codex driver needs a controller-owned oracle for semantic
completion and replay
> - Provider proposals are advisory and must satisfy the exact task
envelope
> - Persisted events must be bounded and validated before deterministic
replay
> - Live provider behaviors also need one checked-in, schema-validated
fixture
> - This pull request adds that test and conformance layer before the
full driver
> - The runner adapter remains disabled and no production execution path
changes
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` Codex trace, result-validation, and replay
conformance.
**Problem or motivation**
A provider-completed turn is not sufficient authority to finalize a
Paperclip run. Results must match the controller-owned completion
contract, and persisted provider events must be validated before they
can rebuild controller state.
**Proposed solution**
Add a bounded Codex trace harness that validates result proposals, emits
controller decisions and terminals, verifies live/replay parity, and
rejects malformed persisted streams. Add a validated fixture for runtime
requests, goals, lineage, controls, reconnect identity, and redaction
cases.
**Alternatives considered**
Embedding these assertions only in the production driver would mix
controller authority with provider transport behavior and make
deterministic replay harder to review.
**Roadmap alignment**
This supports the Codex-first experimental runner. It does not enable
the runner adapter or add another provider.
## What Changed
- Added exact task-envelope result validation.
- Added bounded persisted-event validation and deterministic replay.
- Added a controller-owned Codex trace harness and parity assertions.
- Added and validated the checked-in Live console conformance fixture.
- Updated the generated protocol manifest with the fixture source.
- Added focused result and fixture tests.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- The focused trace-conformance test has 2 passing cases.
## Risks
The main risks are accepting a mismatched semantic result or replaying
corrupted provider history. Validation covers schema, contract revision,
criteria identity, disposition invariants, event identity, uniqueness,
ordering, terminal count, and byte limits.
## Model Used
OpenAI Codex with GPT-5.6 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Semantic tools cross a trust boundary between a provider and the
control plane
> - Durable runs need exact input, result, denial, duplicate, and
reconciliation receipts
> - Replay must reject unsupported required versions and mismatched
receipt pairs
> - This pull request adds the receipt builders and deterministic replay
fixtures
> - It keeps newer sequence and gap safety limits from the current stack
> - The benefit is auditable semantic activity before more providers use
it
## Linked Issues or Issue Description
**Subsystem affected**
packages/paperclip-runner
**Problem or motivation**
Semantic tool calls have basic authorization records, but durable replay
does not yet cover reconciled calls, denial redaction, duplicate
receipts, governance targets, or artifact references.
**Proposed solution**
Add bounded semantic receipt builders, a reconciled phase, strict pair
binding, fail-closed version checks, and generated replay oracles for
the important lifecycle cases.
**Alternatives considered**
The runner could store provider-native tool payloads. That would weaken
protocol portability and make redaction and retry behavior
provider-specific.
**Roadmap alignment**
This supports the existing experimental Paperclip Runner rollout. It
does not enable a production adapter.
## What Changed
- Add semantic input and result receipt builders.
- Add optional reconciliation receipts for pending calls.
- Reject unsupported semantic receipt versions.
- Validate receipt correlation, operation, idempotency, and digest
bindings.
- Add deterministic replay fixtures and generated golden outputs.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- Replay golden and protocol manifest checks pass.
- The branch changes 27 files relative to its declared base.
## Risks
The main risk is accepting a receipt that belongs to another call or
replaying a duplicate as a new mutation. Binding checks compare
correlation, operation, idempotency, and content digest fields. Fixtures
cover denials, duplicates, governance chains, optional fields,
artifacts, and unsupported versions.
> 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, `gpt-5`, with agentic reasoning, tool use, and code
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 linked an existing public issue or described the
issue in-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
Paperclip ticket id
- [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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner package needs one provider-neutral session loop
> - Native execution contracts now define the accepted input and output
> - Backends still need bounded execution, recovery, and control-plane
ports
> - This pull request adds that package-local session runtime
> - It does not change server runtime selection or start the
experimental runner
> - The benefit is a tested execution core for later provider and server
layers
## Linked Issues or Issue Description
**Subsystem affected**
packages/paperclip-runner
**Problem or motivation**
The runner contracts do not yet have a shared session loop. Each backend
would otherwise duplicate event handoff, terminal handling, recovery
cursors, timeouts, and checkpoint behavior.
**Proposed solution**
Add the native session runtime, backend interfaces, control-plane port,
harness driver contract, deterministic conformance helpers, and bounded
tests.
**Alternatives considered**
The server could own this loop. That would mix provider process behavior
with server persistence and authority logic.
**Roadmap alignment**
This is part of the existing experimental Paperclip Runner rollout. It
does not enable a production adapter.
## What Changed
- Add a provider-neutral native session execution loop.
- Add recovery cursor reconciliation and checkpoint hooks.
- Add bounded timeout and governed-wait behavior.
- Add harness driver and control-plane conformance helpers.
- Add deterministic backend and session runtime tests.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- Protocol generation and manifest checks pass.
- The branch changes 14 files relative to its declared base.
## Risks
The main risk is a session that hangs, duplicates an event, or restores
the wrong cursor after reconnect. Tests cover terminal events, timeouts,
durable handoff, duplicate receipts, recovery, continuity breaks, and
checkpoint updates. The change remains package-local.
> 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, `gpt-5`, with agentic reasoning, tool use, and code
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 and contains no internal
Paperclip ticket id
- [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
## Thinking Path
> - The runner already persists PRP events, but provider-native activity
needs one bounded, provider-neutral vocabulary before additional
providers can be added safely.
> - The protocol catalog must describe capabilities without enabling or
authorizing a provider.
> - Provider normalization must not require an ACPX runtime dependency
merely to compile the shared event layer.
> - This pull request adds the event contract and pure normalizers only;
provider transports and production selection remain unchanged.
## Linked Issues or Issue Description
This is the first follow-up stacked on #12321. Codex, OpenCode, and ACP
runtimes expose different activity shapes. Without canonical
normalization, downstream task threads and traces would need
provider-specific branching and could retain unbounded or unsafe
payloads.
## What Changed
- Expand the PRP provider descriptor and canonical activity event
families.
- Add bounded Codex, OpenCode, and ACP event normalizers for plans,
tools, research, delegation, artifacts, review, safety, waits, and
notices.
- Preserve strict schema validation and regenerate the checked-in schema
bundle and manifest.
- Use a structural ACP event input so the provider-neutral layer does
not introduce or authorize an ACPX runtime dependency.
- Export the provider-event contract from the existing package root.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript`
- `pnpm --filter @paperclipai/paperclip-runner test:typescript` — 11
files and 88 tests passed.
- `pnpm -r typecheck`
- `pnpm build`
- `git diff --check`
- The local full repository runner reached unrelated macOS
workspace-path fixture failures; the affected runner suites pass and the
repository CI shards are the handoff authority.
- Diff against the declared base: 8 files.
## Compatibility Boundary
- No provider transport, adapter, server route, feature flag, or runtime
selection changes.
- Catalog presence does not authorize discovery or execution.
- Existing Codex execution continues through its current path.
- No dependency, migration, workflow, or lockfile change.
## Risks
The main risk is accepting malformed or unbounded provider payloads.
Schema validation remains fail-closed, text/output fields are bounded
and redacted, unsafe paths and URLs are discarded, and representative
variants for every declared event family are covered by tests.
## Model Used
OpenAI Codex, GPT-5 family. The client does not expose the exact
deployment ID or context window. Agentic reasoning, tool use, and code
execution were enabled.
## 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 described the issue in-PR following the relevant template
- [x] I have not referenced internal/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 local tests and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated the compatibility notes for this change
- [x] I have considered and documented risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open actionable comments
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The experimental Paperclip Runner can execute a guarded Codex run
and persist provider-neutral events.
> - The task page still reads direct-adapter transcripts and cannot
present those native events.
> - Structured runner questions must also use the existing task
interaction experience.
> - Runtime selection must use the persisted run mode, not an adapter
name or a current feature flag.
> - This pull request projects native events and questions into the
existing task thread.
> - Direct adapters keep their existing transcript, composer,
interaction, and finalization paths.
> - The benefit is a complete native Codex task thread without a
behavior change for existing adapters.
## Linked Issues or Issue Description
Refs #12202. This pull request replaces that stale implementation on
current `master`.
**What happened?**
The server persists native runner events and structured input requests.
The task page only consumes direct-adapter transcripts. A native run
therefore cannot present a complete transcript, usage, or question flow
through the normal task experience.
**Expected behavior**
Native runs project persisted provider-neutral events into the existing
task thread. Native structured questions use the existing interaction
card. Direct adapters retain their current behavior.
**Steps to reproduce**
1. Enable the experimental runner.
2. Start a native Codex run that emits progress, usage, a structured
question, and a final reply.
3. Open the task page.
4. Observe that the direct-adapter transcript path cannot project the
native event records.
**Paperclip version or commit**
`master` at `67f9867bc`.
## What Changed
- Add the canonical structured-question validator and shared contract
exports.
- Materialize native input requests as existing task interactions.
- Validate native answers and deliver them through the durable
question-response receipt.
- Resume the original PRP request with an idempotent `request.resolve`
command.
- Project native messages, tool activity, cumulative usage, and final
replies into the existing transcript model.
- Propagate persisted `runtimeMode` to the task page and select native
handling only for `runtimeMode: "native"`.
- Expire pending interactions through the shared issue service on every
terminal transition, including decisions, stalled reviews, tree control,
and pipeline retry cleanup.
- Queue native run cancellation while a transaction is open and execute
it only after the owning transaction commits.
- Keep nonterminal and non-runner issue paths on their existing service
call shapes and behavior.
## Verification
- `pnpm --filter @paperclipai/server typecheck` — passed, including the
Rust runner release build and protocol/catalog drift gates.
- Focused native-thread and lifecycle suites — 18 files and 481 tests
passed during review.
- `issue-execution-policy-routes.test.ts` — 19/19 passed after the final
transactional-queue expectation update.
- `issue-agent-mutation-ownership-routes.test.ts` — 87/87 passed in the
final isolated compatibility rerun.
- GitHub Actions — policy, build, canary, typecheck/release registry, 5
serialized server shards, 8 general-test shards, 3 browser shards, and
both aggregate gates passed on `7793f3193`.
- Security — Snyk, Socket Project Report, Socket PR Alerts, and
Superagent passed.
- Greptile — 5/5 on `7793f3193`; all actionable review threads resolved.
- `git diff --check` — passed.
- Diff against `master`: 44 files.
## Compatibility Boundary
- Native transcript polling only runs when the persisted run reports
`runtimeMode: "native"`.
- Missing or legacy runtime modes continue through
`useLiveRunTranscripts`.
- Legacy questions keep the existing optional free-text choice.
- Native closed select sets can suppress that legacy fallback.
- Terminal cleanup uses the same issue service for native and legacy
interactions; only a bound native question schedules a native run
cancellation.
- Native cancellation happens after transaction commit, so failed or
rolled-back writes do not cancel a still-valid run.
- The durable delivery service checks the original native request before
it considers a continuation run.
- This pull request adds no migration, dependency, workflow, manifest,
or lockfile change.
## Risks
The main risk is routing a direct-adapter task through native handling
or changing terminal issue behavior. The implementation selects the
native path only from persisted runtime facts, retains the existing
nonterminal call shape, and schedules native cancellation only for a
validated bound native question after commit. Focused and
repository-wide tests cover both paths. Native requests remain bound to
the company, issue, run, and agent; answers are validated, durable, and
idempotent across reconnects.
## Model Used
OpenAI Codex, GPT-5 family. The client does not expose the exact
deployment ID or context window. Agentic reasoning, tool use, and code
execution were enabled.
## 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 and contains no internal
Paperclip ticket id or instance-derived details
- [x] I have run the affected local tests and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated the compatibility notes for this change
- [x] I have considered and documented risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I addressed all Greptile and reviewer comments before requesting
merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner needs a small local process model before it can
connect to a production provider or server.
> - The TypeScript PRP contracts now define the expected replay
behavior.
> - A second language implementation must produce the same result from
the same fixtures.
> - Local child processes also need bounded input, bounded output, and
complete descendant cleanup.
> - This pull request adds a package-local Rust runner, a scripted fake
harness, and deterministic parity checks.
> - The benefit is a testable process boundary with no production
Paperclip behavior change.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting. This pull request adds private test infrastructure to
`packages/paperclip-runner`.
**Problem or motivation**
The PRP contracts have no second implementation on `master`. There is
also no small harness that can prove process cleanup, command
idempotency, terminal reconciliation, or bounded JSONL handling without
a production provider.
**Proposed solution**
Add a minimal Rust workspace. Add a local runner process, a scripted
fake harness, a bounded process supervisor, and Rust conformance and
replay checks. Keep all binaries package-local. Do not connect them to
the Paperclip server.
**Alternatives considered**
The combined runner branch includes provider transports, durable
networking, SDKs, labs, and server behavior. That change is too large
for this review unit. A TypeScript-only harness would not test
cross-language contract parity.
**Roadmap alignment**
This work supports the governed tools and self-healing run direction in
`ROADMAP.md`. It does not add a user-facing runtime, adapter, endpoint,
or rollout flag.
**Additional context**
Refs #12091 and #11962. Pull request #12091 was merged before this
branch opened. This branch is based on the current `master`. Its delta
is 25 files.
## What Changed
- Added a minimal locked Rust workspace with only `serde` and
`serde_json` dependencies.
- Added a package-local `paperclip-runnerd` local mode and a scripted
fake harness.
- Added bounded controller input, harness input, subprocess output
queues, line sizes, log retention, script sizes, script steps, and
command history.
- Added contiguous controller and harness sequence checks and
equivalent-command replay handling.
- Added process-group supervision that cleans up child processes and
remaining descendants after forced or natural harness exit.
- Added runner-owned terminal reconciliation for success, failure,
interruption, cancellation, controller closure, and protocol failure.
- Added Rust conformance output and deterministic replay summaries for
the shared PRP fixtures.
- Added fake scripts for success, failure, interruption, interaction,
duplicate terminal output, process cleanup, and oversized output.
- Added package scripts and documentation for the Rust and
cross-language checks.
- Kept provider transport, server integration, semantic tools, and
production runtime selection out of this pull request.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner check:all` passes.
- TypeScript contract tests pass: 8 Node tests and 44 Vitest tests.
- Rust tests pass: 20 unit tests, 2 local-runner tests, and 3
process-supervisor tests.
- The Rust conformance and replay parity checks pass against the shared
fixtures.
- The natural-exit and forced-exit tests confirm that the harness and
its worker process are stopped.
- The oversized-frame test confirms that a harness frame above the
configured limit is rejected.
- `pnpm -r typecheck` passes after the final rebase to `master`.
- `pnpm build` passes after the final rebase to `master`.
- `pnpm check:token-gates` passes.
- `git diff --check` passes.
- The delta against `master` is 25 files. The package lockfile is
unchanged.
- `pnpm test:run` completed locally with 4,686 passing tests, 19 skipped
tests, and 30 failures in 8 unchanged server test files. The failures
are local macOS path-alias, listener, port-range, and workspace-runtime
baseline failures. No changed-file test failed, and every applicable
Linux CI shard passes.
- Storybook visual regression skipped intentionally because this pull
request changes no UI or story files.
## Risks
Low production risk. No server code invokes the new binaries. The
package remains private. The main risks are process leaks, unbounded
local input, and cross-language drift. Bounded queues and sizes,
process-group cleanup tests, fixture manifests, and parity checks cover
these risks.
I checked `ROADMAP.md`. This change is private test infrastructure for
planned control-plane work. It does not duplicate a shipped or public
product surface.
## Model Used
OpenAI Codex with GPT-5 was used. The exact serving model ID and context
size were not exposed. The model used high reasoning, repository tools,
GitHub tools, and local code 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
- [ ] 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
- [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
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner needs one typed interpretation of the
language-neutral PRP contract.
> - The JSON Schemas and fixtures now exist, but TypeScript consumers
cannot validate or replay them yet.
> - A deterministic reducer must define how duplicate delivery and
source gaps affect the projected session.
> - Result and question contracts must also validate untrusted provider
and user input before later runtime code uses it.
> - This pull request adds those TypeScript contracts and replay oracles
without adding a process, provider, endpoint, or production behavior.
> - The benefit is a reviewable and testable TypeScript foundation for
the local runner and transport pull requests.
## Linked Issues or Issue Description
**Subsystem affected**
This change affects the private `@paperclipai/paperclip-runner` package.
It does not change an existing server or adapter execution path.
**Problem or motivation**
The PRP v1 schemas do not yet provide TypeScript types, runtime
validators, normalized result handling, or a deterministic session
projection. Later Rust, transport, provider, and server work needs one
tested TypeScript oracle instead of separate interpretations.
**Proposed solution**
Generate a checked-in TypeScript schema bundle from the PRP v1 sources.
Add derived types, AJV validation, result and question validation,
deterministic replay, a reducer, and generated golden snapshots. Export
only these implemented root-package surfaces.
**Alternatives considered**
The combined runner branch adds the TypeScript contracts together with
Rust, providers, semantic authorization, SDKs, labs, and server
behavior. That delta is too large for normal review. Handwritten
duplicate protocol types would also create a drift risk.
**Roadmap alignment**
This work supports the governed tool and control-plane direction in
`ROADMAP.md`. It does not enable a new production adapter or endpoint.
**Additional context**
Refs #12087 and #11962. This pull request was prepared on #12087, then
rebased onto its squash merge before opening. The current delta against
`master` is 37 files.
## What Changed
- Added JSON-Schema-derived PRP v1 types and AJV runtime validation.
- Added fail-closed required-version checks and cross-envelope binding
checks.
- Added provider-neutral completion-result and structured-question
contracts.
- Added normalization for accepted legacy provider result aliases before
strict validation.
- Added a deterministic session reducer for replay, duplicate delivery,
source gaps, requests, items, results, and terminal state.
- Added generated replay snapshots and compact parity summaries for six
accepted fixtures.
- Added schema-bundle, manifest, and replay-golden drift gates.
- Added only the root package export. Deferred testing, SDK, evaluation,
lab, provider, and browser entry points remain unavailable.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test` passed with 8
protocol tests and 44 TypeScript tests.
- `pnpm --filter @paperclipai/paperclip-runner typecheck` passed.
- `pnpm --filter @paperclipai/paperclip-runner check:replay-goldens`
passed.
- `pnpm -r typecheck` passed.
- `pnpm build` passed.
- `pnpm check:token-gates` passed.
- `git diff --check` passed.
- The delta against its declared base is 37 files.
- `pnpm test:run` was executed locally. The package tests pass, while
the macOS repository run retains the unchanged local-environment
failures documented on #12087. The complete Linux CI matrix must pass on
this commit.
- A scoped scan found no secret-like values, internal references, or
deferred-provider file names.
- Greptile found an unbounded sequence-gap allocation. Commit `4a405c17`
caps detailed missing IDs at 256, records the full missing count and
truncation state, and rejects sequence values above the exact JavaScript
integer range. The focused tests, workspace typecheck, build, and token
gates pass after this fix.
## Risks
Low production risk. The package remains private. This change adds no
process, network endpoint, provider bridge, server integration, database
change, or execution selection. The main risk is protocol interpretation
drift. Generated schema and replay gates detect that drift. Browser and
CSP-specific validator packaging remains deferred to its later package
boundary.
I checked `ROADMAP.md`. This change defines contracts for planned
control-plane work and does not add overlapping product behavior.
## Model Used
OpenAI Codex with GPT-5 was used. The exact serving model ID and context
size were not exposed. The model used high reasoning, repository tools,
GitHub tools, and local code 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
- [ ] 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
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner needs a language-neutral contract between the
server and the runner process.
> - A shared contract must exist before TypeScript, Rust, transport, or
provider implementations can depend on it.
> - Required protocol versions must fail closed, while safe optional
fields must remain compatible.
> - The contract also needs deterministic fixtures and a drift gate for
later cross-language work.
> - This pull request adds that contract without adding runtime
behavior.
> - The benefit is a small, reviewable source of truth for the next
implementation pull requests.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting. This pull request adds a private package contract for
later server, TypeScript, and Rust work.
**Problem or motivation**
Paperclip Runner does not have a small language-neutral protocol
boundary on `master`. A runtime implementation without this boundary can
drift between languages, accept unsupported required versions, or
silently change canonical fixtures.
**Proposed solution**
Add PRP v1 JSON Schemas, accepted and rejected fixtures, a Codex
structured-question fixture, and a generated SHA-256 manifest. Run
compatibility and manifest checks during the package build. Keep the
package private and export nothing in this pull request.
**Alternatives considered**
The combined runner branch contains schemas together with providers,
SDKs, labs, and server behavior. That change is too large for normal
review. Generating TypeScript validators in this pull request would also
cross into the next review unit.
**Roadmap alignment**
This contract supports the governed tool and control-plane direction in
`ROADMAP.md`. It does not enable a new production adapter or endpoint.
**Additional context**
Refs #12084 and #11962. This pull request was reviewed as a stack on
#12084, then rebased and retargeted to `master` after #12084 merged. The
current delta is 38 files.
## What Changed
- Added 20 PRP v1 JSON Schemas with stable identifiers and resolved
references, including explicit cross-language conformance input and
output schemas.
- Added canonical replay, cross-language, and Codex question fixtures.
- Added accepted cases for additive optional fields and a rejected case
for an unsupported required protocol version.
- Added a deterministic manifest with SHA-256 digests for every schema
and fixture.
- Added package-local schema-instance, schema-reference, compatibility,
question-ID, conformance-pair, and drift checks.
- Added a private workspace package with no public exports and no
production runtime behavior.
- Added the package manifest to the Docker dependency-stage inventory
required for every workspace package. This does not copy or build runner
runtime code into the production image.
- Kept the provider descriptor and question fixture Codex-only. No
deferred provider package or dependency is present.
## Verification
- `pnpm install --frozen-lockfile` passed with Node 24.19.0 and pnpm
9.15.4. No lockfile change is committed.
- `pnpm --filter @paperclipai/paperclip-runner check:protocol` passed
with 8 tests.
- The committed AJV 2020-12 gate accepted every canonical v1 replay,
question, and cross-language conformance fixture. It rejected the
required v2 fixture, a replay fixture with a missing required command
ID, and conformance output with a missing session ID.
- `pnpm -r typecheck` passed.
- `pnpm build` passed and ran the protocol manifest drift check.
- `pnpm check:token-gates` passed.
- `node ./scripts/check-docker-deps-stage.mjs` passed.
- `git diff --check` passed.
- The delta against its declared base is 38 files.
- `pnpm test:run` completed with 4,687 passing tests, 19 skipped tests,
and 29 failures across 9 unchanged server files. The failures reproduce
macOS path aliases, local listener probes, workspace-runtime
assumptions, and one connection-retry timeout. No changed-file test
failed. Linux CI must pass before this pull request is ready.
- `pnpm check:tokens` reports existing personal-name references outside
this pull request. A scoped scan of `packages/paperclip-runner` found no
secret-like values, internal references, or deferred-provider names.
- PR #12084 was squash-merged, and this branch was rebased onto that
merge and retargeted to `master`. The first master-base policy run
correctly caught the missing Docker dependency-stage manifest copy;
commit `4fa1ea7c` fixes that gate, and the complete Linux matrix is
green.
- Serialized server shard 1 initially hit an unchanged heartbeat
test-harness timeout and a later assertion in the same file. Its
isolated rerun passed in 3m57s. All other shards passed on their first
attempt.
- Greptile reviewed the final commit at 5/5 with no blocking failure.
Both earlier actionable validation threads are resolved, and no review
thread remains open.
## Risks
Low production risk. The package is private and has no exports, server
adapter, endpoint, or process. AJV is a package-only development
dependency that the server workspace already uses. The main risk is
contract churn before the TypeScript and Rust consumers land. The
generated manifest and compatibility fixtures make that churn explicit.
I checked `ROADMAP.md`. This change defines a contract for planned
control-plane work and does not add overlapping product behavior.
## Model Used
OpenAI Codex with GPT-5 was used. The exact serving model ID and context
size were not exposed. The model used high reasoning, repository tools,
GitHub tools, and local code 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
- [ ] 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
- [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
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Dotta