The Open Framework for Building Agents
Reduce the wait when sessions move between deployments (#4719)
Karthik Kalyan94784e18e27a
diff --git a/.changeset/faster-session-handoff.md b/.changeset/faster-session-handoff.mdnew file mode 100644index 000000000..53102480b--- /dev/null+++ b/.changeset/faster-session-handoff.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Validate idle session state inside the workflow before starting a deployment handoff, avoiding unnecessary successor starts when durable work is still pending. Preserve inbox ownership and the original session stream throughout the move.diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.mdindex 88971b289..955288426 100644--- a/docs/concepts/sessions-runs-and-streaming.md+++ b/docs/concepts/sessions-runs-and-streaming.md@@ -16,6 +16,12 @@ event stream. A deployment or compaction handoff changes the executing run, notthe session ID or stream. Stream namespaces belong to a run; eve does not supportcaller-assigned session IDs or globally addressed streams.+Before handoff, eve validates that the saved session state has no pending work+inside the workflow. The current owner keeps its inbox while the successor+starts and validates the checkpoint. Once the successor takes over the session+hooks, the original owner forwards messages it accepted during the move and+parks on the stream anchor until the final owner reports the session result.+Authored channels also have channel-local continuation tokens. A token addresseswhichever session currently owns a platform conversation, such as a Slack thread.That identity stays behind the channel boundary and is never accepted or returneddiff --git a/e2e/fixtures/agent-tools-hitl/evals/hitl/continuation/provider-result.eval.ts b/e2e/fixtures/agent-tools-hitl/evals/hitl/continuation/provider-result.eval.tsindex 1050f629f..b96e1af2e 100644--- a/e2e/fixtures/agent-tools-hitl/evals/hitl/continuation/provider-result.eval.ts+++ b/e2e/fixtures/agent-tools-hitl/evals/hitl/continuation/provider-result.eval.ts@@ -20,7 +20,9 @@ export default defineEval({const session = parked.session;// When the user asks the provider to look up the draft.- const live = await session.start("Look up the draft with the provider and report its status.");+ const live = await session.start("Look up the draft with the provider and report its status.", {+ turnPolicy: "steer",+ });// Then the reply reports provider-ready and completes; the message cancelled A, which never runs.await expectToolResult(t, live, "read-draft");diff --git a/packages/eve/src/execution/session/handoff-state.ts b/packages/eve/src/execution/session/handoff-state.tsnew file mode 100644index 000000000..f4899374d--- /dev/null+++ b/packages/eve/src/execution/session/handoff-state.ts@@ -0,0 +1,36 @@+import { queuedInput, storedProjection } from "#harness/session-machine/view.js";+import { openInputs, openSignIns } from "#protocol/session-projection.js";+import { getBlockingWorkflowToolRuns } from "#harness/workflow-tool-runs.js";+import { holdsHitlRequests } from "#harness/hitl/view.js";+import { readDurableSession } from "#execution/durable-session-read.js";+import type { DurableSessionState } from "#execution/durable-session-store.js";++/** Parses retained work with this deployment's code before deciding whether it can move. */+export function isSessionStateIdleForHandoff(input: {+ readonly sessionState: DurableSessionState;+}): boolean {+ const { state } = readDurableSession(input.sessionState);+ // Decoding the run registry rejects corrupt state before any busy-work shortcut.+ const workflowToolRuns = getBlockingWorkflowToolRuns(state);++ // These registries are deleted when work settles. Their ordinary readers+ // tolerate malformed values as absent; that must not authorize a handoff.+ if (holdsHitlRequests(state)) return false;+ const pendingKeys = [+ "eve.runtime.pendingInputBatch",+ "eve.runtime.pendingCoordinationBatch",+ "eve.runtime.deferredStepInput",+ "eve.harness.pendingWorkflowInterrupt",+ ];+ if (pendingKeys.some((key) => state?.[key] !== undefined)) return false;+ const batches = state?.["eve.runtime.pendingInputBatches"];+ if (batches !== undefined && (!Array.isArray(batches) || batches.length > 0)) return false;+ const projection = storedProjection(state);+ return (+ workflowToolRuns.length === 0 &&+ projection.activeTurnId === undefined &&+ openInputs(projection).length === 0 &&+ openSignIns(projection).length === 0 &&+ queuedInput(state) === undefined+ );+}diff --git a/packages/eve/src/execution/session/handoff-steps.test.ts b/packages/eve/src/execution/session/handoff-steps.test.tsindex a38375c4e..4b9d6778a 100644--- a/packages/eve/src/execution/session/handoff-steps.test.ts+++ b/packages/eve/src/execution/session/handoff-steps.test.ts@@ -35,7 +35,7 @@ vi.mock("#context/serialize.js", async (importOriginal) => ({...(await importOriginal()),deserializeContext: (...args: unknown[]) => deserializeContextMock(...args),}));-vi.mock("#execution/durable-session-store.js", async (importOriginal) => ({+vi.mock("#execution/durable-session-read.js", async (importOriginal) => ({...(await importOriginal()),readDurableSession: (...args: unknown[]) => readDurableSessionMock(...args),}));diff --git a/packages/eve/src/execution/session/handoff-steps.ts b/packages/eve/src/execution/session/handoff-steps.tsindex df1319789..99d10ccdc 100644--- a/packages/eve/src/execution/session/handoff-steps.ts+++ b/packages/eve/src/execution/session/handoff-steps.ts@@ -1,7 +1,3 @@-import { queuedInput, storedProjection } from "#harness/session-machine/view.js";-import { openInputs, openSignIns } from "#protocol/session-projection.js";-import { getBlockingWorkflowToolRuns } from "#harness/workflow-tool-runs.js";-import { holdsHitlRequests } from "#harness/hitl/index.js";import {EntityConflictError,HookNotFoundError,@@ -17,7 +13,8 @@ import {} from "#execution/session-inbox/address.js";import { deserializeContext, IncompatibleStateLayoutError } from "#context/serialize.js";import type { SessionCheckpointMigration } from "#execution/session/checkpoint-migrations.js";-import { readDurableSession, type DurableSessionState } from "#execution/durable-session-store.js";+import { readDurableSession } from "#execution/durable-session-read.js";+import { isSessionStateIdleForHandoff } from "#execution/session/handoff-state.js";import {SESSION_CHECKPOINT_VERSION,type SessionCheckpoint,@@ -52,36 +49,6 @@ import { walkCauseChain } from "#shared/errors.js";const log = createLogger("execution.handoff");-/** Parses retained work with this deployment's code before deciding whether it can move. */-export function isSessionStateIdleForHandoff(input: {- readonly sessionState: DurableSessionState;-}): boolean {- const { state } = readDurableSession(input.sessionState);- // Decoding the run registry rejects corrupt state before any busy-work shortcut.- const workflowToolRuns = getBlockingWorkflowToolRuns(state);-- // These registries are deleted when work settles. Their ordinary readers- // tolerate malformed values as absent; that must not authorize a handoff.- if (holdsHitlRequests(state)) return false;- const pendingKeys = [- "eve.runtime.pendingInputBatch",- "eve.runtime.pendingCoordinationBatch",- "eve.runtime.deferredStepInput",- "eve.harness.pendingWorkflowInterrupt",- ];- if (pendingKeys.some((key) => state?.[key] !== undefined)) return false;- const batches = state?.["eve.runtime.pendingInputBatches"];- if (batches !== undefined && (!Array.isArray(batches) || batches.length > 0)) return false;- const projection = storedProjection(state);- return (- workflowToolRuns.length === 0 &&- projection.activeTurnId === undefined &&- openInputs(projection).length === 0 &&- openSignIns(projection).length === 0 &&- queuedInput(state) === undefined- );-}-export type SuccessorStartInput = SessionHandoffStart & {readonly activationToken: string;/** Original run whose stream stays the public session stream. */diff --git a/packages/eve/src/execution/session/handoff.test.ts b/packages/eve/src/execution/session/handoff.test.tsindex 86f25b336..3d0f1aa33 100644--- a/packages/eve/src/execution/session/handoff.test.ts+++ b/packages/eve/src/execution/session/handoff.test.ts@@ -1,7 +1,7 @@import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import type { DeliverHookPayload } from "#channel/types.js";-import type { DurableSessionState } from "#execution/durable-session-store.js";+import { createTestSessionState } from "#internal/testing/session-state.js";import {SESSION_CHECKPOINT_VERSION,SessionHandoff,@@ -152,6 +152,20 @@ describe("SessionHandoff", () => {expect(startSuccessorStepMock).not.toHaveBeenCalled();});+ it("retains ownership when durable state still holds work", async () => {+ const inbox = createInbox();+ await expect(+ createHandoff(inbox).tryTransfer(selection("deployment-b"), {+ ...state(),+ sessionState: createTestSessionState(+ { sessionId: "session-1" },+ { sequence: 0, turnId: "turn_0" },+ ),+ }),+ ).resolves.toEqual({ kind: "retained", reason: "not-idle" });+ expect(startSuccessorStepMock).not.toHaveBeenCalled();+ });+it("retains ownership without a handover when the start step finds work", async () => {installActivation();startSuccessorStepMock.mockResolvedValue({ kind: "not-idle" });@@ -501,10 +515,10 @@ function state() {admittedDeliveryKeys: [],history: [],serializedContext: {},- sessionState: {+ sessionState: createTestSessionState({continuationToken: "channel:current",sessionId: "session-1",- } as DurableSessionState,+ }),};}diff --git a/packages/eve/src/execution/session/handoff.ts b/packages/eve/src/execution/session/handoff.tsindex 90e1373e5..3e885e30f 100644--- a/packages/eve/src/execution/session/handoff.ts+++ b/packages/eve/src/execution/session/handoff.ts@@ -30,6 +30,7 @@ import {watchRunEnd,type RunWatch,} from "#execution/session/run-watch.js";+import { isSessionStateIdleForHandoff } from "#execution/session/handoff-state.js";import type { AgentWorkflowRetentionDefinition } from "#shared/agent-definition.js";import { isObject } from "#shared/guards.js";@@ -281,6 +282,7 @@ export class SessionHandoff {if (this.worldUnsupported) return { kind: "retained", reason: "unsupported-world" };// The previous attempt's payloads have not come back yet.if (inbox.awaitingHandover) return { kind: "retained", reason: "busy" };+ if (!isSessionStateIdleForHandoff(state)) return { kind: "retained", reason: "not-idle" };const ownerRunId = getWorkflowMetadata().workflowRunId;const attempt = this.attempts++;const attemptKey = `${ownerRunId}:${String(attempt)}`;diff --git a/packages/eve/src/execution/session/state-compatibility.test.ts b/packages/eve/src/execution/session/state-compatibility.test.tsindex b7aefac3d..f38c67cbc 100644--- a/packages/eve/src/execution/session/state-compatibility.test.ts+++ b/packages/eve/src/execution/session/state-compatibility.test.ts@@ -1,6 +1,6 @@import { describe, expect, it } from "vitest";-import { isSessionStateIdleForHandoff } from "#execution/session/handoff-steps.js";+import { isSessionStateIdleForHandoff } from "#execution/session/handoff-state.js";import { createTestSessionState } from "#internal/testing/session-state.js";import {positionState,@@ -75,6 +75,34 @@ describe("handoff state inspection", () => {expect(isSessionStateIdleForHandoff(checkpoint(asked))).toBe(false);});+ it.each([+ ["eve.runtime.pendingInputBatch", {}],+ ["eve.runtime.pendingCoordinationBatch", {}],+ ["eve.runtime.deferredStepInput", {}],+ ["eve.harness.pendingWorkflowInterrupt", {}],+ ["eve.runtime.pendingInputBatches", [null]],+ ["eve.runtime.pendingInputBatches", "corrupt"],+ ["eve.runtime.hitl.requests", { signIns: false }],+ ["eve.runtime.hitl.requests", { relays: { request: {} } }],+ ["eve.runtime.hitl.requests", { relays: null }],+ ["eve.runtime.hitl.requests", []],+ ] as const)("refuses retained or malformed work in %s", (key, value) => {+ expect(isSessionStateIdleForHandoff(checkpoint({ state: { [key]: value } }))).toBe(false);+ });++ it("rejects corrupt run state before a pending-work shortcut", () => {+ expect(() =>+ isSessionStateIdleForHandoff(+ checkpoint({+ state: {+ "eve.workflowTool": { version: 4, runs: [null] },+ "eve.runtime.pendingInputBatch": {},+ },+ }),+ ),+ ).toThrow("Corrupt workflow tool run registry");+ });+it("refuses input the session holds until it can run", () => {const queued = withQueuedInput(betweenTurns(), { message: "Alice asks for a summary." });expect(isSessionStateIdleForHandoff(checkpoint(queued))).toBe(false);diff --git a/packages/eve/src/harness/hitl/index.ts b/packages/eve/src/harness/hitl/index.tsindex 8e879cf08..9dd8f5cc3 100644--- a/packages/eve/src/harness/hitl/index.ts+++ b/packages/eve/src/harness/hitl/index.ts@@ -206,4 +206,5 @@ export function takeDeferredMessage<T extends HarnessSessionBase>(};}-export { readHitlState, holdsHitlRequests } from "./requests.js";+export { readHitlState } from "./requests.js";+export { holdsHitlRequests } from "./view.js";diff --git a/packages/eve/src/harness/hitl/view.ts b/packages/eve/src/harness/hitl/view.tsnew file mode 100644index 000000000..0f6c3bc25--- /dev/null+++ b/packages/eve/src/harness/hitl/view.ts@@ -0,0 +1,2 @@+// Workflow bodies inspect retained requests without importing the lifecycle's Node runtime.+export { holdsHitlRequests } from "./requests.js";diff --git a/packages/eve/test/setup/workflow-teardown.integration.test.ts b/packages/eve/test/setup/workflow-teardown.integration.test.tsnew file mode 100644index 000000000..46a4a5756--- /dev/null+++ b/packages/eve/test/setup/workflow-teardown.integration.test.ts@@ -0,0 +1,17 @@+import { expect, it } from "vitest";++import { getWorld } from "#internal/workflow/runtime.js";++it("keeps the Workflow World installed while the local queue closes", async () => {+ const world = await getWorld();+ const close = world.close?.bind(world);+ world.close = async () => {+ try {+ // Shutdown can finish pending work that still resolves its stream's World.+ await expect(getWorld()).resolves.toBe(world);+ } finally {+ await close?.();+ }+ };+ await world.close();+});diff --git a/scripts/guard-invariants.mjs b/scripts/guard-invariants.mjsindex 9c32e596c..30225465f 100644--- a/scripts/guard-invariants.mjs+++ b/scripts/guard-invariants.mjs@@ -126,8 +126,9 @@* rule 50 — The human-in-the-loop lifecycle in `harness/hitl/` is* reached only through its `index.ts`, its request vocabulary* (`approval-prompt`, `budget-request`, `relays`, `sign-ins`) and- * read surface via index.ts. Only commit.ts and checkpoint-migrations.ts- * import requests.ts for saving and legacy upgrades.+ * read surface via index.ts or the Workflow-safe view.ts.+ * Only commit.ts and checkpoint-migrations.ts import requests.ts+ * for saving and legacy upgrades.* rule 51 — Only the session machine (`harness/session-machine/`) and the* human-in-the-loop lifecycle it delegates to* (`harness/hitl/`) build lifecycle events and read the@@ -553,7 +554,7 @@ function checkRule47(posix, lines, violations) {const HUMAN_INPUT_DIR = "packages/eve/src/harness/hitl/";const HUMAN_INPUT_PRIVATE_IMPORT_RE =- /["'](?:#harness\/|(?:\.\.?\/)+)hitl\/(?!(?:index|approval-prompt|budget-request|relays|sign-ins)\.js["'])/;+ /["'](?:#harness\/|(?:\.\.?\/)+)hitl\/(?!(?:index|view|approval-prompt|budget-request|relays|sign-ins)\.js["'])/;/** @param {string} posix @param {string[]} lines @param {Violation[]} violations */function checkRule50(posix, lines, violations) {@@ -577,7 +578,7 @@ function checkRule50(posix, lines, violations) {file: posix,line: idx + 1,message:- "imports the human-in-the-loop lifecycle's internals. Reach it through `#harness/hitl/index.js`, the one seam the rest of eve meets it at.",+ "imports the human-in-the-loop lifecycle's internals. Reach it through `#harness/hitl/index.js`, or use the read-only `#harness/hitl/view.js` from workflow bodies.",});});}diff --git a/scripts/hitl-state-readers.test.mjs b/scripts/hitl-state-readers.test.mjsindex 85b248bee..9a5871841 100644--- a/scripts/hitl-state-readers.test.mjs+++ b/scripts/hitl-state-readers.test.mjs@@ -20,6 +20,7 @@ test("rule 50 keeps requests storage private with only the save and migration exassert.ok(pattern.test('from "#harness/hitl/requests.js"'));assert.ok(pattern.test('from "../hitl/requests.js"'));assert.ok(!pattern.test('from "#harness/hitl/index.js"'));+ assert.ok(!pattern.test('from "#harness/hitl/view.js"'));assert.ok(rule.includes('posix === "packages/eve/src/harness/session-machine/commit.ts"'));assert.ok(rule.includes('posix === "packages/eve/src/execution/session/checkpoint-migrations.ts"'),@@ -43,6 +44,7 @@ test("rule 50 keeps requests storage private with only the save and migration exassert.equal(violations[0].rule, 50);const readers = [];check(file, ['import { readHitlState } from "#harness/hitl/index.js";'], readers);+ check(file, ['import { holdsHitlRequests } from "#harness/hitl/view.js";'], readers);assert.equal(readers.length, 0);}for (const file of [