mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Core runs Claude Code through Paperclip Runner. 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 run ends when the turn ends. The command stops, and the run fails with `native_finalization_missing`. > - The Runner part of this work is complete in #21316 and the pull requests below it: when a controller sends `providerStartedTurns` on `turn.start`, the Runner keeps Claude while a background shell is running, and gives the cycle of Claude to the controller as a turn that the provider started. > - Part 2 gave the consumer a wait with a limit and two inputs: a hook that ends the wait early, and a start time. > - This pull request gives both from the server for a native ACPX Claude run. A new comment from a person ends the wait. The start time comes from an event that is already saved, so a restart of Core does not make the wait longer. > - The benefit is that a person who comments does not wait up to 10 minutes for the agent to see it. ## Linked Issues or Issue Description No public issue exists. The issue is described here. This pull request is one of four parts on the Core side. They are stacked on #21316: 1. The driver admits a turn that the provider started. 2. The consumer waits for that turn, for a limited time. 3. The server ends the wait when a person comments, and keeps the clock across a restart. 4. The transport sends the opt-in. Only this part changes what a production run does. This is part 3. Its base branch is `feat/core-provider-turn-consumer`. Refs #19912 (design). **What existing behavior does this improve?** Nothing visible yet. What Core gives to the consumer of a native ACPX Claude run. **Subsystem affected** Server: `server/src/services/native-runtime`. **Current behavior** - A comment from a person during a run is queued as a deferred wake. The next run delivers it. This does not change. - Core has no wait for a provider-started turn. **Proposed behavior** - For a native ACPX Claude run, Core gives `executeNativeSession` the option `providerTurnWait`. - One delivery worker does the person-comment check for all runs that wait. The server registers it at startup with the shared delivery work coordinator, as it registers the cost accounting worker. The worker listens to the existing notification for deferred wakes. On each notice it runs one query for each run that waits: a comment from a person on this issue, made after the start of the run, that a deferred wake of this agent names. A comment that the query finds ends the wait of that run. The run then takes the path of today, and the next wake delivers the comment as today. - If a database read fails, that run stays owed a check, and the coordinator runs the worker again after 5 seconds, as for each other delivery worker. A read that fails for one run does not stop the check of the other runs. When no run is owed a check, the worker has no deadline and does no query. - The start time of the wait is the time of the first saved `turn.completed` event of the run that has `awaitingProviderTurn`. With no such event it is empty. - Each query has the company id in its condition. **Reason and benefit** - The comment window starts at the start of the run, not at the start of the wait. A comment made during the prompt turn must not wait for the limit. ## What Changed - `server/src/services/native-runtime/native-provider-turn-wait.ts` (new, 109 lines) and 4 lines in `native-session-executor.ts`. - `server/src/index.ts` (4 lines): the registration of the worker, its stop at server close, and its place in the list of delivery workers that must be ready. `delivery-work-notifications.ts` (1 line): the queue key of the worker. The key needs no database change, because each topic uses the one shared channel. - `server/src/vendor/paperclip-runner/index.ts`: one type export. - Tests: `native-provider-turn-wait.test.ts` (new, 252 lines) and one case in `native-usage-accounting.test.ts` (25 lines). ## State saved by the previous release - No new persisted state and no schema change. The start time is read from `heartbeat_run_events`. - **A run that the previous release started:** it has no waiting terminal, so the start time is empty. - **Core restarts during a wait:** the new process reads the start time, so the limit is the original one. The consumer then continues the wait (#21454), and the worker checks the comments again from the start of the run, so a comment that was made before the restart still ends the wait. - **Rollback of Core during a wait:** the previous Core stops at the waiting terminal and finalizes the run as `native_finalization_missing`, as today. ## Verification At the head of this branch: - `npx tsc --noEmit -p tsconfig.json`, `npx tsc --noEmit -p tsconfig.test.json` and `pnpm run build:typescript` in `packages/paperclip-runner`; `node scripts/verify-runner-vendor-dependencies.mjs` and `pnpm typecheck` in `server`; `node --test scripts/__tests__/runner-release-crate-cache.test.mjs`: all passed. - `native-provider-turn-wait.test.ts`, 10 tests on embedded Postgres with the real coordinator: a comment from a person in a deferred wake ends the wait; a comment from an agent, a comment before the run, and a comment of a different company do not; the start time comes from the first waiting terminal, and a run of the previous release has none. - The 6 new tests: a read that fails one time is tried again after 5 seconds and finds a comment that is already saved, with no new notice; a notice during a read that fails gives a new check; a read that fails for one run does not hold back a second run, and each run ends only for its own comment; a run that starts to wait during a check is checked; a wait that is aborted is removed, nothing checks it again and no deadline stays; with no run owed a check there is no deadline and no query in one hour of test time. - The test helper now registers the wake intent before it writes the deferred wake, in the same transaction. This is the order of each production writer (`modules/wake-queue/adapters/postgres.ts` and `services/heartbeat/queue.ts`). Production code did not change for this. - Mutation checks: a read that fails clears the owed check (3 tests fail); an aborted wait is not removed (the abort test fails). - Also run, unchanged and green: `delivery-work-coordinator.test.ts`, `budget-enforcement-worker.test.ts`, `server-startup-feedback-export.test.ts`, `startup-timeline.test.ts`. The 7 files together: 1,699 passed, 7 skipped. - `native-usage-accounting.test.ts`: a prompt turn and the provider-started turn after it are each counted one time, with the events as the executor receives them. The cost of the provider-started turn is the session total in the cumulative channel, and it is not added two times. The accounting code is not changed. Not run: a run through the executor with a database; the full suite. CI supplies the broad coverage. ## Risks - **One more query at each start of a native ACPX Claude run,** on `heartbeat_run_events` by company and run. - **The worker is registered in each server process, and it is idle with no wait.** A notice with no run that waits does no query. No wait starts before part 4. - **After an abort during a retry, the 5 second retry of the coordinator runs one more time.** It finds nothing owed and does no query. The coordinator has no call to cancel the retry of one worker. - **A process that does not register the worker does no comment check.** The server registers it with no condition at startup, and native runs execute only in that process. Only a unit test can be in this state. - **A comment ends the wait but does not interrupt a turn that is running.** That is the rule of part 2. > 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 - [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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>