mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 20:34:57 +02:00
Dotta
10cf68295d
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Rust runner now has bounded ACPX transport, scope, payload, normalization, and state-reduction layers > - A live provider needs a lifecycle owner that starts the sidecar and proves it opened the exact requested session > - The initial production slice is Codex-only and must fail closed on capability, model, identity, policy, or catalog drift > - Failed bootstraps must not leak a child process, and ordinary shutdown must preserve resumable provider state > - This pull request adds that package-local lifecycle without selecting ACPX in runnerd > - The benefit is a reviewable bootstrap/recovery boundary before turn commands and production selection are connected ## Linked Issues or Issue Description Refs #12417 Refs #12416 ## What Changed - Add a package-local ACPX provider session configuration and lifecycle owner. - Reject non-UTF-8 runtime and working directories before spawning so JSON path serialization cannot panic. - Validate the sidecar launch contract, Codex-only agent, model, run and session identifiers, absolute directories, positive JSON-safe catalog revision, pinned permission mode, bounded instructions, and canonical authorized tool catalog before spawning. - Verify the initialization protocol version, child PID, persistent-session support, exact-model support, runner-owned permission policy, semantic-tool bridge, and structured-input contract. - Open an identity-bound session and require the requested and effective models, permission mode, session identifier, digests, and optional recovery identity to match exactly. - Attach the run and require the sidecar to confirm the exact run identifier and catalog revision. - Retry failed transport cleanup while retaining lifecycle ownership; terminate the sidecar after every failed bootstrap and on an unclosed session drop. - Close sessions without discarding persistent state and make explicit shutdown idempotent. - Extend the package-local fake sidecar with deterministic bootstrap, wrong-model, and wrong-run responses. - Add five integration tests covering successful bootstrap/shutdown, pre-spawn policy validation, model mismatch, run mismatch, and recovery identity matching. - Document the session bootstrap boundary. - Do not change dependencies, lockfiles, workflows, runnerd selection, server behavior, UI, or migrations. ## Verification - Replay base: `f038633bf5b04163ff985ef0542876bd9f455379` (`master` after #12417 merged). - Exact replay head: `a6d9ad62f20fdb47a1dbc76aa4baa9d8fa6dae53`. - Stable patch ID: `82b6f2551749598a688c3f44a1a3714516030429`, identical to the reviewed `e6e550f9..d51a8855` delta. - The exact delta is 5 files and 609 additions, all in `packages/paperclip-runner`; it contains no lockfile, workflow, server, UI, or migration change. - Focused Rust lifecycle, package, repository, security, and Greptile checks: **PASSED** on the replayed exact head. Full CI run `33362799786` is green; its failed-job retry passed one unrelated flaky server shard without a patch change. Greptile is exact-head 5/5, all security checks pass, and no review threads remain unresolved. - No local test result is claimed. GitHub Actions is the authoritative verification environment for this replayed revision. ## Risks - This lifecycle owns a child process and session identity. Configuration is fully validated before spawning, every bootstrap response is checked against the child PID and requested identity, and failed bootstrap always terminates the process. - Recovery identity matching is exact so a persisted native record cannot silently attach to another session, model, workspace, profile, or permission policy. - Explicit shutdown preserves persistent provider state; a dropped unclosed session still terminates its process group as a safety fallback. - The package exports a new Rust module, but no production path constructs it in this pull request. - Turn commands, event polling, request resolution, and runnerd selection remain later slices. > 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 with GPT-5.6, 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 (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