Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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, not
the session ID or stream. Stream namespaces belong to a run; eve does not support
caller-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 addresses
whichever session currently owns a platform conversation, such as a Slack thread.
That identity stays behind the channel boundary and is never accepted or returned
diff --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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.mjs
index 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.mjs
index 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 ex
assert.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 ex
assert.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 [