mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-19 20:44:16 +02:00
Dotta
6d358e646d
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The runner package now has a complete Codex session driver > - The driver needs a package-owned construction boundary before server code can use it > - Persisted provider contracts must not make deferred providers executable > - Provider selection must fail closed when an implementation is not included > - This pull request adds a Codex-only native backend and factory > - It does not expose or enable the Paperclip Runner adapter ## Linked Issues or Issue Description **Subsystem affected** `packages/paperclip-runner` native backend construction. **Problem or motivation** The runner needs one normalized backend seam that constructs the reviewed Codex driver. The seam must not route OpenCode, ACPX, Claude Managed, or AWS AgentCore through an incomplete fallback. **Proposed solution** Add a Codex backend constructor and a Codex-first factory. Reject every deferred provider at the factory and provider-specific constructor boundaries. **Alternatives considered** Routing all provider contracts through the Codex protocol facade would give deferred providers runtime behavior before their implementations are reviewed. Including all provider backends would also broaden this pull request beyond the Codex-first series. **Roadmap alignment** This connects reviewed runner package layers. It does not enable a new adapter or change an existing direct adapter path. ## What Changed - Added the Codex native backend constructor. - Added the Codex-first native backend factory. - Preserved the execution contract, runtime instructions, plan constraints, dynamic tools, transport injection, and durable identity requirements. - Rejected every deferred provider with an explicit error. - Added tests for lazy transport construction and both fail-closed boundaries. ## Verification - `pnpm --filter @paperclipai/paperclip-runner test:typescript` (35 files, 340 tests) - `pnpm -r typecheck` - `pnpm build` - The focused native backend factory suite has 3 passing cases. ## Risks The main risk is starting the wrong provider or starting a provider before its runtime is ready. The factory and Codex constructor both reject non-Codex inputs. Existing direct adapters do not call this package-local factory. ## 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