The Open Framework for Building Agents
fix(eve): preserve idle subagents across session handoff (#3433)
Ben Pankow5b45f9b0e599
diff --git a/.changeset/idle-subagent-handoff.md b/.changeset/idle-subagent-handoff.mdnew file mode 100644index 000000000..e6736acf6--- /dev/null+++ b/.changeset/idle-subagent-handoff.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Allow idle sessions with resumable subagents to move to a newer deployment. Parked and available child handles now remain usable after the parent session handoff instead of pinning the parent to its previous deployment.diff --git a/e2e/fixtures/agent-self-modification/README.md b/e2e/fixtures/agent-self-modification/README.mdindex c4b29fdc2..18e32b79a 100644--- a/e2e/fixtures/agent-self-modification/README.md+++ b/e2e/fixtures/agent-self-modification/README.md@@ -16,6 +16,7 @@ This exercises the current standard scaffold without duplicating it in the fixtu## Cases+- `create-background-replication-check.eval.ts` creates a ten-second background workflow, calls it on the next turn of the authoring session, and checks its immediate receipt, delayed completion, task identity, typed input, and structured positive result.- `create-incident-triage.eval.ts` creates an incident-triage tool and checks precedence and threshold rules across typed inputs.- `create-shipping-quote.eval.ts` creates a quote calculator and checks destination, started-kilogram, free-shipping, and expedited pricing boundaries.- `offer-repair.eval.ts` reproduces an incorrect reorder recommendation, checks that the parent offers but does not start a repair, confirms it, and verifies the repaired tool.@@ -36,7 +37,7 @@ The harness snapshots the complete `agent/` tree, tracks sessions, and retires tKeep `maxConcurrency: 1`. The harness also serializes cleanup that continues after an eval timeout and acquires a checkout lock before snapshotting source. A concurrent `eve eval` process fails before mutation. If cleanup cannot safely restore source, the lock remains with owner diagnostics; remove it only after inspecting the retained backup and confirming no eval or development server is mutating the fixture.-Forced rebuilds isolate source-authoring and runtime correctness. These cases do not verify automatic hot-reload timing or deployed proposal/merge behavior. Real-model e2e runs belong in CI. The fixture-only cleanup tests need no model or running server:+Forced rebuilds isolate source-authoring and runtime correctness in the other cases. The background replication case instead verifies that automatic rebuilding makes a newly authored capability available on the next turn of the existing session. These cases do not verify deployed proposal/merge behavior. Real-model e2e runs belong in CI. The fixture-only cleanup tests need no model or running server:```shpnpm --filter agent-self-modification test:scenariodiff --git a/e2e/fixtures/agent-self-modification/evals/self-modification/create-background-replication-check.eval.ts b/e2e/fixtures/agent-self-modification/evals/self-modification/create-background-replication-check.eval.tsnew file mode 100644index 000000000..6a0abd5dc--- /dev/null+++ b/e2e/fixtures/agent-self-modification/evals/self-modification/create-background-replication-check.eval.ts@@ -0,0 +1,112 @@+import { randomUUID } from "node:crypto";++import { defineEval, type EveEvalTurn } from "eve/evals";++import { withSelfModification } from "./harness";++const TOOL_NAME = "eval_replication_check";+const TOOL_PATH = `tools/${TOOL_NAME}.ts`;++export default defineEval({+ tags: ["real-model"],+ description:+ "A background workflow tool created through self-modification is callable on the next turn of the same session and later reports its result.",++ async test(t) {+ await withSelfModification(t, async (selfMod) => {+ const authored = await selfMod.request(+ [+ `Alice needs a reusable local background workflow named ${TOOL_NAME} for checking a replicated import in future conversations.`,+ "Accept batchId as a non-empty string and expectedRecords as an integer from 1 through 1000000.",+ "When invoked, start in the background, wait for 10 seconds, and then return structured data containing success set to true, the unchanged batchId and expectedRecords, and status set to ready.",+ "The initial call must return a background task receipt immediately rather than blocking the conversation for the wait.",+ "This workflow only simulates the replication wait. It must not read files, contact external services, or modify data.",+ ].join(" "),+ );+ await selfMod.readSource(TOOL_PATH);+ await selfMod.assertOnlyChanged([TOOL_PATH]);+ // Do not force a rebuild: this case covers automatic next-turn availability.++ const batchId = `batch-${randomUUID()}`;+ const expectedRecords = 137;+ const started = await selfMod.followUp(+ authored.session,+ [+ `Start ${TOOL_NAME} exactly once for batchId ${JSON.stringify(batchId)} and expectedRecords ${expectedRecords}.`,+ "Acknowledge its background task receipt without claiming the check is finished.",+ "When the background task completes, report its returned result.",+ ].join(" "),+ );+ started.expectOk();+ started.calledTool(TOOL_NAME, { count: 1 });+ const call = started.requireToolCall(TOOL_NAME, {+ input: { batchId, expectedRecords },+ });+ const taskId = readWorkingTaskId(call.output);+ if (taskId === undefined) {+ throw new Error(`${TOOL_NAME} did not immediately return a working task receipt.`);+ }++ const receiptAt = actionResultTime(started.events, taskId);+ const completion = await t.target+ .watchTurn(authored.session.sessionId!, {+ startIndex: requireStreamIndex(authored.session),+ })+ .result();+ completion.expectOk();+ completion.messageIncludes(batchId);+ completion.messageIncludes("ready");+ completion.eventsSatisfy(+ "completion reports the positive result after the ten-second wait",+ (events) =>+ events.some((event) => {+ if (event.type !== "message.received") return false;+ const text = messageText(event.data.message);+ return (+ Date.parse(event.meta.at) - receiptAt >= 9_500 &&+ Date.parse(event.meta.at) - receiptAt <= 20_000 &&+ text.includes(`Background task ${taskId} (${TOOL_NAME}) is completed.`) &&+ text.includes(batchId) &&+ text.includes(String(expectedRecords)) &&+ text.includes("true") &&+ text.includes("ready")+ );+ }),+ );+ t.noFailedActions();+ t.succeeded();+ });+ },+});++function readWorkingTaskId(output: unknown): string | undefined {+ if (output === null || typeof output !== "object") return undefined;+ const taskId = Reflect.get(output, "taskId");+ const status = Reflect.get(output, "status");+ return typeof taskId === "string" && status === "working" ? taskId : undefined;+}++function actionResultTime(events: EveEvalTurn["events"], taskId: string): number {+ const result = events.find(+ (event) =>+ event.type === "action.result" &&+ event.data.result.kind === "tool-result" &&+ event.data.result.toolName === TOOL_NAME &&+ readWorkingTaskId(event.data.result.output) === taskId,+ );+ if (result === undefined) throw new Error(`${TOOL_NAME} receipt has no action result event.`);+ return Date.parse(result.meta.at);+}++function requireStreamIndex(session: {+ readonly state?: { readonly streamIndex?: number };+}): number {+ const streamIndex = session.state?.streamIndex;+ if (streamIndex === undefined) throw new Error("Background workflow turn has no stream index.");+ return streamIndex;+}++function messageText(message: unknown): string {+ if (typeof message === "string") return message;+ return JSON.stringify(message);+}diff --git a/packages/eve/src/execution/session/handoff-steps.ts b/packages/eve/src/execution/session/handoff-steps.tsindex 7ebe51b4f..7f1264f8e 100644--- a/packages/eve/src/execution/session/handoff-steps.ts+++ b/packages/eve/src/execution/session/handoff-steps.ts@@ -39,7 +39,11 @@ export function isSessionStateIdleForHandoff(sessionState: DurableSessionState):)return false;return (- (handles?.handles.length ?? 0) === 0 && tasks.every((task) => task.terminalView !== undefined)+ (handles === undefined ||+ handles.handles.every(+ (handle) => handle.phase === "parked" || handle.phase === "available",+ )) &&+ tasks.every((task) => task.terminalView !== undefined));}diff --git a/packages/eve/src/execution/session/state-compatibility.test.ts b/packages/eve/src/execution/session/state-compatibility.test.tsindex b240a0997..29bf97d38 100644--- a/packages/eve/src/execution/session/state-compatibility.test.ts+++ b/packages/eve/src/execution/session/state-compatibility.test.ts@@ -8,6 +8,7 @@ import {} from "#tasks/session-index.js";import { parseActivityWorkIdentityV1 } from "#protocol/activity.js";import type { HarnessSession } from "#harness/types.js";+import type { AgentHandle, AgentHandlePhase } from "#subagents/handles/store.js";const metadata = { kind: "tool", name: "research" };const activity = {@@ -61,6 +62,41 @@ function session(state: Record<string, unknown>): HarnessSession {}const restored = <T>(value: T): T => JSON.parse(JSON.stringify(value));+const identity = { id: "ag_researcher:operation", name: "researcher", nodeId: "agent" };+const address = {+ continuationToken: "subagent:parent:call",+ kind: "agent/local" as const,+ sessionId: "child-session",+};+const startOperation = {+ callId: "call",+ id: "operation",+ kind: "start" as const,+ parentTurnId: "turn",+};++function handle(phase: AgentHandlePhase): AgentHandle {+ switch (phase) {+ case "starting":+ return {+ identity,+ operation: startOperation,+ phase,+ target: { continuationToken: address.continuationToken, kind: "agent/local" },+ };+ case "running":+ return { address, identity, operation: startOperation, phase };+ case "parked":+ return { address, identity, lastStatus: "Research complete", phase };+ case "reserved":+ return { identity, operationId: "operation", ownerId: "task", phase };+ case "claimed":+ return { address, identity, operationId: "operation", ownerId: "task", phase };+ case "available":+ return { address, identity, phase };+ }+}+describe("additive durable state", () => {it("preserves task extensions through parsing, replayed creation and terminal updates", () => {const state = {@@ -135,6 +171,37 @@ describe("handoff state inspection", () => {),).toBe(true);});+ it.each(["parked", "available"] as const)(+ "allows an idle %s agent handle to cross a handoff",+ (phase) => {+ expect(+ isSessionStateIdleForHandoff(+ checkpoint({ "eve.agent.handles": { handles: [handle(phase)] } }),+ ),+ ).toBe(true);+ },+ );+ it.each(["starting", "running", "reserved", "claimed"] as const)(+ "refuses an active %s agent handle",+ (phase) => {+ expect(+ isSessionStateIdleForHandoff(+ checkpoint({ "eve.agent.handles": { handles: [handle(phase)] } }),+ ),+ ).toBe(false);+ },+ );+ it("parses idle handles before accepting them", () => {+ expect(() =>+ isSessionStateIdleForHandoff(+ checkpoint({+ "eve.agent.handles": {+ handles: [{ ...handle("parked"), address: { ...address, sessionId: "" } }],+ },+ }),+ ),+ ).toThrow("Corrupt agent handle store");+ });it("parses settled entries before checking their terminal status", () => {const incompatible = { ...task, taskInboxToken: 42 };expect(() =>diff --git a/research/single-workflow-session-upgrades.md b/research/single-workflow-session-upgrades.mdindex a5b00e4a0..61263c616 100644--- a/research/single-workflow-session-upgrades.md+++ b/research/single-workflow-session-upgrades.md@@ -131,7 +131,7 @@ Idle excludes all of the following:- other pending, buffered, or queued commands or deliveries, including a batched arrival;- an active model or tool step, cancellation rollback, or caller/result settlement;- pending human input or authorization, including waits surfaced by descendants;-- any live task, subagent, or authored workflow tool, including background work;+- any live task, active subagent turn or lease, or authored workflow tool, including background work;- pending coordination, result application, or callback processing for that work.Unknown eligibility means skip. Session-lifetime timeout and activity collection are@@ -143,9 +143,12 @@ re-check when a turn settles or a backlog drains. Only a later delivery that iseligible can trigger an upgrade, so a continuously busy session may stay on old code indefinitely.That rule is the core simplification. Remembering a target and pursuing it later means moving live-waits, callback ownership, and task handles between deployments, which is a cross-version-coordination protocol: the thing this proposal deletes. Deferring to the next idle delivery costs-nothing in protocol and only delays code alignment for busy sessions.+waits, callback ownership, and active task or subagent leases between deployments, which is a+cross-version coordination protocol: the thing this proposal deletes. Idle subagent handles are+not leases: a `parked` conversation handle or `available` task-owned handle retains only the stable+address of an independently owned child session, so those handles move with settled session state.+Deferring to the next idle delivery costs nothing in protocol and only delays code alignment for+busy sessions.HITL responses, tool and subagent results, cancellation, reset, clear, and compact never triggerupgrades. eve never cancels or restarts work to make a session eligible.@@ -168,14 +171,18 @@ context and lifecycle metadata:- event sequence, remaining limits, the complete claimed session-hook set, and original configured timeout duration.The single triggering delivery travels alongside the checkpoint. The checkpoint never carries a-command backlog, live waits, callback ownership, or task/subagent/tool handles; the eligibility rule-guarantees none exist.+command backlog, live waits, callback ownership, active subagent leases, or live task/tool+ownership; the eligibility rule guarantees none exist. It may carry `parked` conversation handles+or `available` task-owned handles, which retain only the stable address of an independently owned+child session. The child session itself does not move with its parent: a later continuation carries+a caller and is therefore not handoff-eligible, so the child keeps executing on the deployment that+owns it.The successor rebuilds instructions, models, tools, skills, and compiled configuration from its ownbundle. Before claiming hooks, it shares the source's idle-state inspection: parse all retained-tasks (including settled entries) and handle state, and require pending-work registries to be absent-or canonically empty. Task and handle readers preserve additive metadata on updates but still-validate known fields and lifecycle rules. An unreadable checkpoint is refused before activation,+tasks (including settled entries) and handle state, require every retained handle to be `parked` or+`available`, and require pending-work registries to be absent or canonically empty. Task and handle+readers preserve additive metadata on updates but still validate known fields and lifecycle rules. An unreadable checkpoint is refused before activation,so the previous owner can recover and process the triggering delivery. Authored state stays opaque. There is no migration chain and no author-facingstate migration API, so raw `defineState` values must remain readable by the target code. Thepublic event stream is not a checkpoint (it omits private history and framework state), and the@@ -433,9 +440,13 @@ claim measured latency or a fixed count for arbitrary authored integrations.- An eligible A→B delivery starts one successor on B and preserves identity, connected stream andcursor, settled state, limits, timeout duration, and every claimed session hook. Owner and authored codereport B. An unreadable checkpoint recovers A's ownership and processes the delivery once.-- Every unsafe category skips: parked HITL, background tasks, batched deliveries, queued commands.- Work stays on A. Settlement and queue draining trigger nothing; only a fresh eligible delivery- does. No remembered target or live handle crosses versions.+- Every unsafe category skips: parked HITL, background tasks, active subagent turns or leases,+ batched deliveries, and queued commands. Work stays on A. Settlement and queue draining trigger+ nothing; only a fresh eligible delivery does. No remembered target or active handle crosses+ versions.+- `parked` conversation handles and `available` task-owned handles cross with settled state. The+ successor can resume them by stable child address, while the child continues on the deployment+ that owns it.- Inject concurrent deliveries and replay failures at every handoff step. Verify FIFO order, nolost accepted commands, no duplicated model/tool work, and one activated owner. Coverdisposal-time arrivals, partial claims, failed starts, and uncertain activation.