mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip Runner runs Claude Code through the ACPX sidecar. > - Claude can start a shell command in the background and end its turn. When the command finishes, Claude Code starts a cycle of its own to continue. Today the Runner stops Claude at the end of the turn, so the command stops and the run fails with `native_finalization_missing`. > - A stack of pull requests lets the Runner accept that cycle as a new turn of the same run, when a controller asks for it. > - Claude Code starts a cycle of its own when a background task finishes and no prompt is in flight. The Runner sees the raw messages of that cycle. > - #21293 only marks the background state as unknown when it sees such activity. > - This pull request gives each such cycle to the caller of the adapter as one ordered stream: started, its events, ended with its result. Nothing reads the stream yet. > - The benefit is one place that knows where a cycle starts and ends, with cycles that cannot overlap. ## Linked Issues or Issue Description No public issue exists. The issue is described here. This pull request is one part of a change that was first opened as one large pull request (#21316). The parts, in stack order after #21311: 1. #21419: sidecar preparation (a refactor). 2. #21420: converter for raw ACP session updates. 3. #21421: cycle stream at the adapter. 4. #21422: contract for provider-started turns. 5. #21423: `paperclip-runnerd` waits for a provider-started turn. 6. #21316: the sidecar adopts a cycle. This is part 3. Its base branch is `feat/acp-session-update-event-converter`. After each part, a production run does the same as today, because no controller sends the opt-in. Refs #19912 (design). **What existing behavior does this improve?** Nothing in production yet. How the ACPX adapter sees the cycles that Claude starts by itself. **Subsystem affected** Paperclip Runner: `src/drivers/acpx` (the adapter, the runtime host, the Claude background task tracker). Claude only. **Current behavior** - The raw ACP observer gives each message to the background task tracker. - Activity of Claude with no client request in flight makes the background state unknown. The messages of that cycle are not kept. **Proposed behavior** - `ClaudeProviderCycles` puts each cycle on one ordered stream. A cycle starts at the first update of the own session with no client request and no prompt in flight. It ends at the `usage_update` that has `_meta._claude/origin`. - A caller gets the stream with `providerCycles()`, reads it with `next()`, and calls `adopt()` or `drop()` for each cycle. A permission request waits for the decision of its own cycle. The stream records the cycle of each tool call, and `decisionFor(toolCallId)` gives that decision. The binding that a caller gives to `adopt()` can also carry `onPlanProposal`, so a plan that an adopted cycle proposes goes to the caller as it does for a normal turn. - With no caller, a cycle is declined and the background state becomes unknown, as before. The sidecar does not call `providerCycles()` in this pull request, so production does the same as today. - The tracker reports `{ live: N }` only while N shells are running, `{ live: 0 }` only if the process never had a background task and Claude never acted between prompts, and unknown in each other case. A dropped, failed or cancelled cycle makes the state unknown. - An empty result that directly follows the end of a cycle (zero usage, same context use and cost) is ignored. Claude Code sometimes sends it. It must not become a cycle, and its usage must not be reported two times. **Reason and benefit** - One producer and one reader make the order of cycles a property of the structure. - The tracker does not read the order of messages to decide which finished task a cycle reported on. Captures showed that Claude Code can put two notifications in one cycle, start a second cycle, or give a notification to a cycle in progress, and the ACP stream does not say which. ## What Changed - `src/drivers/acpx/claude-provider-turns.ts` (new, 303 lines): `ClaudeProviderCycles`. - `acpx-runtime-adapter.ts` (78 added, 8 removed) and `runtime-host.ts` (24 added): `providerCycles()` and `providerTurnsAvailable()`, and the permission path that waits for the decision. - `claude-background-tasks.ts` (16 added, 7 removed): the rule above. - Tests (764 lines): `claude-provider-turns.test.ts`, `claude-provider-turn-tasks.test.ts`, `claude-background-tasks.test.ts`, a permission test in `acpx-runtime-adapter.test.ts`, two tests with the real `claude-agent-acp` (`acpx-runtime-adapter.claude-provider-turn.test.ts`, `acpx-runtime-adapter.claude-overlapping-shells.test.ts`), and a captured raw stream as a fixture. ## Verification At the head of this branch, from `packages/paperclip-runner`: - `npx tsc --noEmit -p tsconfig.json`, `npx tsc --noEmit -p tsconfig.test.json`, `pnpm run typecheck:typescript`, `pnpm run build:typescript`, `node --test test/acpx-sidecar-contract.test.mjs test/protocol-contract.test.mjs`, the server check `node scripts/verify-runner-vendor-dependencies.mjs`, `node --test scripts/__tests__/runner-release-crate-cache.test.mjs`, `cargo fmt --check` and `cargo build -p paperclip-runner-core --bins` (no new warning): all passed. - 10 test files, 294 passed. This includes the test of #21293 with the real `claude-agent-acp`, not changed: with no caller of the stream it still gets `{ live: 1 }` at the end of the turn and an unknown state after the cycle of Claude. - Real `claude-agent-acp` with a local fake Anthropic API: a background shell finishes, and the stream gives one cycle with its own usage. With two shells where the second finishes before the first cycle sends its first update, the first cycle ends with an unknown state. - Mutation checks, each made the named tests fail: an end item before the last message of a cycle; a drop that does not make the state unknown; a finished task that reports `{ live: 0 }`; the empty result not ignored; a permission request that does not wait. - Live run with a real Claude account, not in CI, on the full change: one background shell gave `{ live: 1 }`, one cycle, then unknown. Two shells of 8 s and 28 s gave `{ live: 2 }`, `{ live: 1 }`, then unknown. Not run: the full suite. CI supplies that coverage. ## Risks - **The time at which the state becomes unknown changes a little.** With no caller, a cycle makes the state unknown at its first message. Before, it was at the first message of an activity kind. The result for the Runner is the same: a restart at the end of the turn. - **Limit, by design.** After a cycle, `{ live: N }` counts only running shells. A command that finishes while Claude already reports on an earlier one gets no cycle that the Runner waits for. - **The rule for the empty result is narrow** and comes from captures of one Claude Code version. The reason that Claude Code sends it is not known. - **A queue of 4,096 messages for one cycle.** A cycle that is larger fails, and the state becomes unknown. > 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 - Claude Fable 5.2 (`claude-fable-5-2`) in Claude Code planned the change and the split, reviewed the diff, and ran a part of the verification again. - Claude Opus 5.5 (`claude-opus-5-5`), as a Claude Code subagent with tool use (shell, file edits, local test runs), wrote the change and the tests and cut this slice from the full change. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>