mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-24 01:41:42 +02:00
Dotta
08b5d6bd9b
## 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