## 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
> - 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
> - The runner action catalog defines what scenario tools can exist
> - A catalog entry must not grant authority by itself
> - Scenario runs need run-scoped discovery and invocation checks
> - Observable results must not expose protected values
> - This pull request adds an authorized package-local scenario tool
runtime
> - The benefit is deterministic tool testing without production service
authority
## Linked Issues or Issue Description
**Subsystem affected**
`packages/paperclip-runner` scenario tool runtime.
**Problem or motivation**
Scenario tests need to expose only authorized actions. They also need
stable denial records, redaction, and idempotent command handling.
**Proposed solution**
Project the canonical scenario contracts into a visible catalog. Recheck
policy at invocation. Dispatch allowed operations through the mock
control-plane port and return redacted receipts.
**Alternatives considered**
Direct production bindings are outside this pull request. The runtime
uses only the package-local mock port.
**Roadmap alignment**
This supports runner conformance and scenario testing. It does not
enable an adapter or production service call.
## What Changed
- Added run-scoped scenario tool discovery.
- Added claim, role, task-mode, and policy authorization.
- Added input validation, redaction, and authorization records.
- Added fake-agent and Codex definition projections.
- Added deterministic mock dispatch and idempotency coverage.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- The focused semantic runtime test has 10 passing cases.
## Risks
Low risk. The runtime is package-local and uses the mock control-plane
port. It creates no production binding.
## 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 operations need a control plane that owns authorization and
state changes
> - Conformance tests need this authority without a live server or
database
> - The existing in-memory port covers transport facts but not
capability-governed domains
> - This pull request adds a deterministic capability-aware control
plane for tests
> - It keeps the implementation behind the package testing entry point
> - The benefit is repeatable authorization and mutation tests before
production wiring lands
## Linked Issues or Issue Description
**Subsystem affected**
packages/paperclip-runner testing and semantic capability contracts
**Problem or motivation**
Later semantic action slices need deterministic company, actor, task,
governance, workspace, secret, budget, routine, and audit state. A live
Paperclip server would make those tests slow and environment-dependent.
**Proposed solution**
Add serializable capability fixture types and an in-memory control-plane
adapter. Enforce company scope, claims, roles, idempotency, redaction,
faults, and audit records. Export the adapter only from the testing
entry point.
**Alternatives considered**
The tests could mock each action separately. That would duplicate
authorization rules and would not verify state transitions across
multiple actions.
**Roadmap alignment**
This supports the existing experimental Paperclip Runner rollout. It
does not enable production semantic operations or change app execution.
## What Changed
- Add deterministic capability fixture types and seed state.
- Add an in-memory capability control-plane adapter.
- Enforce run, company, actor, claim, role, and idempotency boundaries.
- Model governed task, document, interaction, workspace, secret,
routine, and audit changes.
- Add deterministic tests and testing-entry-point exports.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- The branch changes 5 files relative to its declared base.
## Risks
The main risk is a permissive mock that hides a production authorization
error. The adapter fails closed for missing claims, wrong roles,
cross-company access, duplicate mutations, invalid state, and restricted
secret access. Tests cover each fixture domain and serialized restore
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, `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 runner needs repeatable tests at the provider and control-plane
boundaries
> - Network services and live providers cannot produce deterministic
conformance results
> - Small in-memory adapters can exercise the same public contracts
without production side effects
> - This pull request adds a deterministic harness driver, control-plane
adapter, and fixture runner
> - It exposes these helpers only from the testing entry point
> - The benefit is stable cross-boundary verification for later runtime
changes
## Linked Issues or Issue Description
**Subsystem affected**
packages/paperclip-runner testing and conformance support
**Problem or motivation**
The public runner contracts have unit tests, but later provider and
server slices need a deterministic way to exercise session, event,
replay, checkpoint, and result behavior together.
**Proposed solution**
Add in-memory implementations of the harness-driver and control-plane
ports. Add a canonical conformance fixture and runner. Export these
utilities only from `@paperclipai/paperclip-runner/testing`.
**Alternatives considered**
The tests could start a real provider or server. That would make the
conformance gate slower, less portable, and dependent on credentials or
network state.
**Roadmap alignment**
This supports the existing experimental Paperclip Runner rollout. It
does not enable a production adapter or change current app execution.
## What Changed
- Add a deterministic harness-driver implementation.
- Add an in-memory control-plane adapter with replay and checkpoint
support.
- Add a canonical provider-neutral conformance fixture.
- Add a reusable conformance runner and contract tests.
- Export the helpers from the package testing entry point only.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- The branch changes 10 files relative to its declared base.
## Risks
Low risk. This pull request adds test-only adapters and conformance
helpers. It does not select a runtime or change production behavior.
Contract tests verify event identity, replay, checkpoints, and
deterministic results.
> 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
Dotta