## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip Runner now has a durable PRP transport and a Codex
provider bridge.
> - Codex must use stable, provider-neutral action contracts before
Paperclip can grant run-scoped tool access.
> - A catalog must describe actions without granting permission to
discover or invoke them.
> - Generated inventory must stay synchronized with its TypeScript
source.
> - This pull request adds the canonical Codex-spine semantic action
catalog inside the runner package.
> - The benefit is a small review unit for schemas and inventory before
authorization and dispatch land.
## Linked Issues or Issue Description
**Subsystem affected**
Cross-cutting. This pull request extends private runner infrastructure
in `packages/paperclip-runner`.
**Problem or motivation**
The Codex provider bridge has no canonical description of the Paperclip
actions that a later authorization layer can project into a run.
Independent operation lists can drift in names, claims, task modes,
effects, and input bounds.
**Proposed solution**
Add one immutable v1 catalog for the first 27 Codex-spine actions. Give
each action a stable identifier, placement, effect, required claims,
supported task modes, and JSON Schema input and output contracts.
Generate a deterministic JSON inventory from that source and fail
package checks on drift.
**Alternatives considered**
The combined runner branch contains larger live and scenario catalogs
with authorization, bindings, labs, and other providers. That change is
too large for this review unit. A generic API escape hatch would also
bypass the operation-level boundary, so this catalog excludes it.
**Roadmap alignment**
This work supports the governed tool access direction in `ROADMAP.md`.
It does not add a tool gateway, application binding, server endpoint, or
production authorization decision.
**Additional context**
Refs #12111 and #11962. Pull request #12111 was squash-merged first.
This branch starts at the resulting `master` commit. Its delta is 10
files.
## What Changed
- Added 27 versioned, provider-neutral semantic action declarations for
the Codex spine.
- Added bounded JSON Schema input contracts and normalized operation
receipt output contracts.
- Added placement, effect, claim, mode, and role metadata.
- Added a deeply frozen public catalog and an operation lookup helper.
- Added a deterministic checked-in JSON inventory and generation
commands.
- Added a byte-for-byte drift gate to the package build.
- Added AJV schema compilation, mutation-bound, forged-field,
immutability, inventory, and non-executable-boundary tests.
- Exported only the catalog types and declarations from the existing
package root.
- Documented that catalog membership does not grant discovery,
authorization, dispatch, or application binding.
- Kept server code, UI code, other providers, scenario-only actions,
labs, generic API access, authorization, dispatch, and receipts
processing out of this pull request.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner check:all` passes.
- TypeScript protocol tests pass: 8 Node tests and 49 Vitest tests.
- All package Rust tests and conformance and replay parity checks pass.
- `pnpm --filter @paperclipai/paperclip-runner
check:semantic-action-catalog` passes.
- `pnpm -r typecheck` passes.
- `pnpm build` passes.
- `pnpm check:token-gates` passes.
- Prettier and `git diff --check` pass for the changed source and
documentation files.
- The generated catalog matches its source byte for byte.
- The secret scan is clean.
- The delta against `master` is 10 files. `pnpm-lock.yaml` is unchanged.
- `pnpm test:run` completed locally with 4,692 passing tests, 19 skipped
tests, and 24 failures in 8 unchanged server test files. The failures
reproduce the established local macOS path-alias, listener, and
workspace-runtime baseline. No changed-file test failed. Linux CI
remains the repository handoff authority.
- The full Linux PR workflow passes, including the aggregate `verify`
gate.
- Snyk, Socket, Superagent security, and supply-chain checks pass.
- Greptile is 5/5 with no actionable comments, recommendations, or
follow-ups.
- Storybook visual regression skipped by design because this pull
request changes no UI file.
- Browser and migration tests are not applicable because this pull
request changes no server, UI, database, or migration file.
## Risks
Production behavior is unchanged because no consumer projects this
catalog into a provider run. The main risks are contract drift,
unbounded mutation input, forged scope fields, accidental executable
authority, and generated inventory drift. Closed input schemas, explicit
bounds, a frozen catalog, tests, and the byte drift gate cover these
risks. The later authorization layer must still bind every action to the
active run and company before discovery or invocation.
I checked `ROADMAP.md`. This change is private contract infrastructure
for the governed tool access direction. 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>
23048f1219