mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:35:02 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - An environment plugin can keep a warm task for an agent session. After each turn, Core releases the task's Runner, and the next run of the session resumes it > - #22288 added `resumeIdentityVersion: 1`: for a provider that stops a released Runner, Core rotates the session to the next run and the provider starts the Runner again directly as that run > - Core takes that path only while it still holds the released session in memory. After a Core restart, it recovers the released task through the older hand-off: it resumes the task as the previous run, then switches the Runner's authority to the new run > - So a provider that advertises the capability still has to keep the hand-off for every follow-up after a Core restart, and cannot drop it > - This pull request makes restart recovery take the same path when the provider advertises the capability > - The benefit is that a provider with the capability gets one start shape for a released task, before and after a Core restart, and can retire the hand-off ## Linked Issues or Issue Description Follows #22288. **What existing behavior does this improve?** The first run of a warm plugin session after a Core restart, when its task was released and its provider advertises `resumeIdentityVersion: 1`. **Subsystem affected** The native session executor and the plugin Runner task owner. **Current behavior** After a restart, Core finds the released source on disk (`inspectRemoteWarmSessionRecovery`), creates a backend that adopts the task, and calls `recoverSession`. The task owner calls `resume` without `runner`, the provider starts the Runner as the previous run, and Core hands it to the new run. **Proposed behavior** When the provider advertises the capability, Core recorded the build the task was released on, the process configuration is unchanged, and the session is not moving to another task, Core treats the recovery like a cached released session. It revalidates the recovery, loads the warm checkpoint, and opens a new backend on the same task with `relaunchReleased`. A new task owner takes over the submitted task without adopting a Runner process, prepares the claimant run with the released source as `priorIdentity`, and calls `resume` with `runner`. Every other recovery keeps the hand-off. **Reason and benefit** A provider that advertises the capability no longer needs the hand-off for its own tasks, after a restart or not. ## What Changed - Executor: a remote warm recovery with a released source, a recorded build, a reusable process configuration and no session move, on a provider that advertises the capability, revalidates the recovery and becomes a relaunch: `relaunchReleased` with the released source and build, the warm checkpoint, and no `remoteWarmRecovery` for the backend. The startup context ends as for a cached relaunch. - Executor: the relaunch's task owner can now come from the new backend (`onPluginTaskOwner`), so the unavailable-reuse fallback and the rotation revert work without a retained owner. Without an owner, no relaunch can have started, so the revert applies. - Backend: a relaunch neither stops a resumed task that has no durable binding nor resolves a `resumeFrom` task. - Task owner: an owner created with `relaunch` and the capability takes over an already submitted task, as an adopting owner does, but adopts no process: its prepare sends the released source as `priorIdentity`, and its launcher calls `resume` with `runner`. - `doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md`: Core prepares the claimant run before the resume, also after a restart, and a provider must accept that prepare without state kept in memory. ## Verification - `server`: `npx vitest run src/services/native-runtime/plugin-runner-release-resume.integration.test.ts`: new `adopted restart relaunch` cases for Codex and Claude, with real runnerd processes. Core restarts while the task is released; the next run relaunches the task as itself, with no claim, one inspection and no second submit. The existing `adopted relaunch` case now relaunches both follow-ups, since the idle close also recovers through this path. - `server`: `plugin-runner-task.test.ts`: a new owner relaunches without submitting or adopting, and prepares with the released source; without the capability it prepares a new task. - `server`: `plugin-runner-release-resume.integration.test.ts` and `plugin-runner-eviction.integration.test.ts`: 61 passed. `native-session-executor.test.ts`: 1535 passed, 7 skipped. `plugin-runner-task.test.ts`: 118 passed. - Typecheck: `server` passes. - Red-green: with the executor lane turned off, both `adopted restart relaunch` cases fail. Without the task owner change, the new-owner relaunch test fails. ## Risks - Only providers that advertise `resumeIdentityVersion: 1` see a change. Recovery without a recorded build, with a changed process configuration, or for a session moving to another task keeps the hand-off. - The provider sees a `prepare` for the claimant run on a released task right after a Core restart. A provider that tracked unclaimed released tasks only in memory must handle that prepare (the doc now says so). - A Core restart in the middle of this path is still not qualified, as for the cached relaunch. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use (code search, editing, local test runs). ## 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: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>