From 0ab73d4e3004572e3a2debcb4bf7e76e57c56dd6 Mon Sep 17 00:00:00 2001 From: Nicky Leach Date: Sat, 14 Nov 2026 13:10:20 -0800 Subject: [PATCH] feat(native-runtime): ask the Runner for provider-started turns on native ACPX Claude runs (#21456) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 can keep Claude while a background shell is running and give the cycle of Claude to the controller as a turn that the provider started. Core can wait for that turn. The transport can ask for it (#21607), and a controller restart during it is safe (#21612). > - No run does this yet, because Core does not ask the Runner for it. > - This pull request makes the native runtime of Core ask, for ACPX Claude. It is the only part that changes what a production run does. > - The benefit is the goal of the whole work: a run with a background command that is still running continues when the command finishes, and does not fail with `native_finalization_missing`. ## Linked Issues or Issue Description No public issue exists. The issue is described here. This pull request turned the behavior on and had grown too large to review. It is now three stacked pull requests: 1. #21607 (merged): the transport can ask the Runner for provider-started turns. No caller asks. 2. #21612: the recovery after a controller restart during a wait or during a provider-started turn. 3. **This pull request:** Core sets the option for native ACPX Claude runs. This is part 3. Its base branch is `fix/provider-turn-restart-recovery`. Refs #19912 (design). **What existing behavior does this improve?** What a native ACPX Claude run does after a turn that ends with no result while a background command is still running. **Subsystem affected** Core, the native runtime: `server/src/services/native-runtime/native-session-executor.ts` and `native-provider-turn-wait.ts`. ACPX Claude only. **Current behavior** - The run ends at the end of the turn. The Runner restarts Claude, the background command stops, and the run fails with `native_finalization_missing`. **Proposed behavior** - The native runtime sets `providerStartedTurns: true` in the transport options for ACPX Claude, at the two places that build those options. One function, `nativeProviderStartedTurns`, decides this and also decides if the consumer gets the wait options, so the two cannot be different. - A turn that ends with no result while a background command is still running now waits, for a maximum of 10 minutes, for the turn that Claude starts by itself. That turn is consumed as the next turn of the same run, and its result settles the run. - Other providers and other ACPX agents do the same as today. - Limit of the Runner (see #21421): after a follow-up turn, the Runner waits again only while a background command is still running. A command that finishes while Claude reports on an earlier command gets no follow-up. **Reason and benefit** - The opt-in is in the last part, so each earlier part can merge with no change for a production run. ## What Changed - `server/src/services/native-runtime/native-provider-turn-wait.ts` (5 lines added, 1 removed): `nativeProviderStartedTurns`. - `server/src/services/native-runtime/native-session-executor.ts` (4 added, 2 removed): the option at the two places that build the transport options, and the same function for the wait options. - `server/src/services/native-runtime/native-session-executor.test.ts` (4 added, 2 removed): the two native paths set the option for ACPX Claude and not for other providers. ## State saved by the previous release - No persisted state changes in this part. - **A Runner that does not know the field** ignores it, and the run does the same as today. - **A deploy during a run:** a turn that started before the deploy has no opt-in and ends as today. The next turn has the opt-in. - **Rollback of Core:** the previous Core does not set the option, so the Runner does not wait. ## Verification The items below were run on the tree that was verified before the split into three parts (commit `1b15ded1c4` has that tree, byte for byte). The head of this branch (`23e2c13ad3`) is that commit on the new head of #21612; its three server files are the same. - `pnpm typecheck` and `node scripts/verify-runner-vendor-dependencies.mjs` in `server`; `npx tsc --noEmit -p tsconfig.json`, `npx tsc --noEmit -p tsconfig.test.json`, `pnpm run typecheck:typescript` and `pnpm run build:typescript` in `packages/paperclip-runner`: all passed. - `server/src/services/native-runtime/native-session-executor.test.ts` and `native-runner-restart-recovery.integration.test.ts`: 1,732 passed, 21 skipped. - The end-to-end behavior is tested in parts 1 and 2 with the real `paperclip-runnerd`, where the test sets the option in the way that this part does. - Live run with a real Claude account, not in CI, at the adapter level of the Runner (see #21316): the cycle of Claude was given as a turn with its own usage, and each Paperclip tool call was admitted. Not run: a live run through Core, `paperclip-runnerd` and the real sidecar with a real Claude account (that path needs an API key, not a local sign-in); a remote sandbox; the full suite. CI supplies the broad coverage. ## Risks - **This part turns the behavior on for each native ACPX Claude run.** A run with no background command is not changed: the Runner waits only when a shell is still running at the end of a turn that has no result. - **This part must not merge before #21612.** Without #21612, a controller restart during a wait or during a provider-started turn fails the run. - **A run can now stay open up to 10 minutes longer** when the background command does not finish or Claude does not start a turn. The agent computer stays active for that time. - **A waiting run can show as "suspicious" after 5 minutes of silence** in the run watchdog. The watchdog only labels a native run; it does not stop it. - **Follow-ups that the Runner cannot wait for are lost,** as the limit above says. ## 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. ## 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 Fable 5.2 --- .../services/native-runtime/native-provider-turn-wait.ts | 6 +++++- .../services/native-runtime/native-session-executor.test.ts | 6 ++++-- .../src/services/native-runtime/native-session-executor.ts | 6 ++++-- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/server/src/services/native-runtime/native-provider-turn-wait.ts b/server/src/services/native-runtime/native-provider-turn-wait.ts index d933ac46589..1e0e8e136f4 100644 --- a/server/src/services/native-runtime/native-provider-turn-wait.ts +++ b/server/src/services/native-runtime/native-provider-turn-wait.ts @@ -3,7 +3,7 @@ import { agentWakeupRequests, heartbeatRunEvents, heartbeatRuns, issueComments, import type { createDeliveryWorkCoordinator } from "../delivery-work-coordinator.js"; import { DELIVERY_QUEUES, subscribeDeliveryWork } from "../delivery-work-notifications.js"; -import type { ProviderTurnWaitOptions } from "../../vendor/paperclip-runner/index.js"; +import type { NativeExecutionInput, ProviderTurnWaitOptions } from "../../vendor/paperclip-runner/index.js"; type NativeRunScope = { companyId: string; runId: string; issueId: string; agentId: string }; @@ -101,6 +101,10 @@ export function awaitPersonCommentDuringNativeRun(db: Db, scope: NativeRunScope, }); } +export function nativeProviderStartedTurns(provider: NativeExecutionInput["provider"]) { + return provider.kind === "acpx" && provider.agent === "claude"; +} + export async function nativeProviderTurnWaitOptions(db: Db, scope: NativeRunScope): Promise { return { startedAtMs: await nativeProviderTurnWaitStartedAt(db, scope), diff --git a/server/src/services/native-runtime/native-session-executor.test.ts b/server/src/services/native-runtime/native-session-executor.test.ts index cb08e585392..685c85c9f8b 100644 --- a/server/src/services/native-runtime/native-session-executor.test.ts +++ b/server/src/services/native-runtime/native-session-executor.test.ts @@ -17325,7 +17325,7 @@ describe("runnerd provider runtime wiring", () => { state.createBackend.mock.calls.at(-1)![1].codexTransportFactory!(); expect(state.createTransport.mock.calls.at(-1)![0]).toMatchObject({ provider: "acpx", acpxAgent: "claude", acpxPermissionMode: "approve-all", - acpxPermissionModePinned: true, claudeEffort: "high", homeMode, + acpxPermissionModePinned: true, claudeEffort: "high", homeMode, providerStartedTurns: true, }); }); @@ -17346,6 +17346,7 @@ describe("runnerd provider runtime wiring", () => { provider: "acpx", acpxAgent: "grok", acpxPermissionMode: "approve-all", acpxPermissionModePinned: true, grokEffort: "high", grokDisableWebSearch: disableWebSearch, homeMode, }); + expect(state.createTransport.mock.calls.at(-1)![0]).not.toHaveProperty("providerStartedTurns"); }); it("requires explicit Grok credentials before v10 daemon startup", async () => { @@ -18894,7 +18895,8 @@ describe("runnerd provider runtime wiring", () => { expect(owner.mock.results.at(-1)!.value.credentialsUpdated).toHaveBeenCalledWith(notification); expect(options).toMatchObject({ ...driver, runnerArtifact: { version: "fixture" }, prpIdentity: { environmentLeaseId: "plugin-task-lease" } }); - if (kind === "acpx") expect(options).toMatchObject({ acpxAgent: "claude", claudeEffort: "high" }); + if (kind === "acpx") expect(options).toMatchObject({ acpxAgent: "claude", claudeEffort: "high", providerStartedTurns: true }); + else expect(options).not.toHaveProperty("providerStartedTurns"); for (const key of ["environment", "codexCommand", "codexArgs", "runnerRuntimePaths", "readRunnerState", "archiveExternalRunnerState"]) { expect(options).not.toHaveProperty(key); } diff --git a/server/src/services/native-runtime/native-session-executor.ts b/server/src/services/native-runtime/native-session-executor.ts index 914ceded34a..7dfc7a616ad 100644 --- a/server/src/services/native-runtime/native-session-executor.ts +++ b/server/src/services/native-runtime/native-session-executor.ts @@ -31,7 +31,7 @@ import { prepareRemoteOpenCodeArtifacts, type OpenCodeLaunchArtifacts } from "./ import { prepareRuntimeContextSource, rehydratePinnedInstructionAsset } from "./runtime-context.js"; import { createNativeUsageDelivery } from "./native-usage-delivery.js"; import { createNativeRecoveryUsageDelivery } from "./native-recovery-usage-delivery.js"; -import { nativeProviderTurnWaitOptions } from "./native-provider-turn-wait.js"; +import { nativeProviderStartedTurns, nativeProviderTurnWaitOptions } from "./native-provider-turn-wait.js"; import { createNativeTurnAccounting, NATIVE_LOST_TURN_USAGE_EVIDENCE, nativeUsageCostUsd, nativeUsageBiller, normalizeNativeUsage, usesNativeUsageDelivery, isNativeUsageAccountingEvent, isNativeUsageDeliveryEvent } from "./native-usage-accounting.js"; import { crashPoint } from "@paperclipai/shared/crash-points"; export { nativeUsageCostUsd, nativeUsageBiller, normalizeNativeUsage } from "./native-usage-accounting.js"; @@ -12412,7 +12412,7 @@ async function executePaperclipNativeSessionAttempt( startedAtMs: nativeSessionExecuteStartedAtMs, }); trace.activate(runnerSessionStartupScope); - const providerTurnWait = input.execution.provider.kind === "acpx" && input.execution.provider.agent === "claude" + const providerTurnWait = nativeProviderStartedTurns(input.execution.provider) ? await nativeProviderTurnWaitOptions(input.db, input.execution.binding) : undefined; const runExecution = () => executeNativeSession({ @@ -16724,6 +16724,7 @@ async function createRunnerdBackendWithinSessionClaim( grokEffort: "grokEffort" in provider ? provider.grokEffort : undefined, grokDisableWebSearch: "grokDisableWebSearch" in provider ? provider.grokDisableWebSearch : undefined, acpxPermissionModePinned: true } : {}), + ...(nativeProviderStartedTurns(provider) ? { providerStartedTurns: true } : {}), ...(provider.kind === "opencode" ? { opencodePermissionMode: provider.permissionMode } : {}), runnerReconnectGraceMs: REMOTE_RUNNER_RECONNECT_GRACE_MS, runnerProcessReconnectGraceMs: null, lifecyclePolicy: input.execution.session.lifecyclePolicy, @@ -18481,6 +18482,7 @@ async function createRunnerdBackendWithinSessionClaim( ), } : {}), + ...(nativeProviderStartedTurns(input.execution.provider) ? { providerStartedTurns: true } : {}), ...(input.execution.provider.kind === "cursor_cloud" ? { cursorCloud: input.execution.provider.cursorCloud } : {}), ...(input.execution.provider.kind === "opencode" ? {