mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 07:23:08 +02:00
Dotta
fd7cb77d8e
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The runner package now has a Codex-only native backend > - A native Codex process needs an isolated runtime context before it can start safely > - Assigned skills, local authentication, and MCP bindings cross separate trust boundaries > - Runtime materialization must reject symlink escapes and unsafe remote bindings > - This pull request adds the package-local Codex runtime context boundary > - It does not start runnerd or enable the Paperclip Runner adapter ## Linked Issues or Issue Description **Subsystem affected** `packages/paperclip-runner` Codex runtime context materialization. **Problem or motivation** The runner needs a private Codex home for each native session. It must stage only assigned skills, copy local Codex authentication safely, and validate native MCP bindings before it exposes them to the child process. **Proposed solution** Create an isolated runtime directory. Validate the skill tree before and after copying it. Make staged skill files read-only. Read authentication through a no-follow file descriptor with a size bound. Accept only HTTPS or loopback MCP endpoints and bounded tokens. **Alternatives considered** Using the operator Codex home directly would expose unrelated state and skills. Following symlinks while copying skills or authentication could escape the assigned source. Accepting arbitrary MCP URLs could send a bearer token to an untrusted endpoint. **Roadmap alignment** This adds a package-local safety boundary for the reviewed Codex runner path. It does not enable a new adapter or change an existing direct adapter path. ## What Changed - Added the native MCP binding contract and strict validation. - Added isolated Codex home materialization with shell snapshots disabled. - Added assigned-skill staging with lexical containment and two-pass symlink checks. - Added read-only permissions for staged skill trees. - Added owner-only authentication staging with no-follow reads and a size bound. - Added cleanup for complete and partially materialized runtime directories. ## Verification - The focused runtime context suite has 7 passing cases. - `pnpm --filter @paperclipai/paperclip-runner test:typescript` (36 files, 351 tests) - `pnpm -r typecheck` - `pnpm build` ## Risks The main risks are filesystem escape, secret exposure, and token delivery to an unsafe endpoint. The materializer rejects symlinks before and after skill copying, resolves existing source paths, reads authentication with `O_NOFOLLOW`, applies private permissions, and restricts MCP URLs to HTTPS or loopback hosts. Existing direct adapters do not use this package-local runtime context. ## 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 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