## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Runner tools need stable provider-neutral action contracts
> - Core task work must use the same names, policy metadata, schemas,
and examples on every provider surface
> - A single large 41-action review would hide contract drift
> - This pull request adds only the 14 always-present core action
definitions
> - It does not grant discovery or execution authority
> - The benefit is a reviewable immutable contract base for later
authorization wiring
## Linked Issues or Issue Description
**Subsystem affected**
packages/paperclip-runner protocol action contracts
**Problem or motivation**
The runner has an older compact catalog, but it does not single-source
the full policy metadata, documentation, live shape, scenario shape, and
examples for each core action.
**Proposed solution**
Add one immutable definition module per core action. Add an internal
core aggregate and validate every input and output example against its
declared JSON Schema. Keep all production authorization and execution
unavailable.
**Alternatives considered**
All 41 action definitions could land in one pull request. That would
create more than 7,000 changed lines and reduce useful review depth.
**Roadmap alignment**
This supports the existing experimental Paperclip Runner rollout. It
does not enable the adapter or expose any new production tool.
## What Changed
- Add 14 core protocol action definitions.
- Add immutable policy, schema, documentation, and example data for each
action.
- Add a deep-freeze helper and a core-only aggregate.
- Validate all core examples with JSON Schema.
## Verification
- `pnpm --filter @paperclipai/paperclip-runner test:typescript`
- `pnpm --filter @paperclipai/paperclip-runner typecheck:typescript`
- `pnpm -r typecheck`
- `pnpm build`
- The branch changes 17 files relative to its declared base.
## Risks
Low production risk. These declarations do not contain executable
authorization or service bindings. The main risk is schema drift. Tests
validate operation identity, placement, immutability, and canonical
examples.
> 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
- [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
08b5d6bd9b