Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): detect stranded session owners and skip their replay (#4479)

prha233c509437ca
diff --git a/packages/eve/src/evals/tool-stubs.integration.test.ts b/packages/eve/src/evals/tool-stubs.integration.test.ts
index 7507b57bd..d1af0b2ac 100644
--- a/packages/eve/src/evals/tool-stubs.integration.test.ts
+++ b/packages/eve/src/evals/tool-stubs.integration.test.ts
@@ -7,12 +7,12 @@ import { createEvalTargetHandle } from "#evals/target.js";
import { workflowEntry } from "#execution/session/entry.js";
import { reportStubFailureStep } from "#execution/tool-stubs/steps.js";
import { dispatchWorkflowSessionCommand } from "#execution/workflow-runtime.js";
-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";
+import { startSessionOwner, waitForHook } from "#internal/testing/workflow-test-helpers.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
import { buildSerializedContext, handoffFollowUp } from "#internal/testing/entry-test-helpers.js";
import { mockAgentRouteArgs } from "#internal/testing/mocks/mock-route-args.js";
import { failingDeployWorkflow } from "#internal/testing/workflow-tool-fixtures.js";
-import { start, type Run } from "#internal/workflow/runtime.js";
+import type { Run } from "#internal/workflow/runtime.js";
import { EVE_MESSAGE_STREAM_VERSION, EVE_STREAM_VERSION_HEADER } from "#protocol/message.js";
import { parseToolStubs } from "#tool-stubs/rules.js";
import { STUB_CONTEXT_KEY } from "#tool-stubs/types.js";
@@ -61,7 +61,7 @@ it.each(["output processing", "failure reporting", "injected error"])(
if (url.origin !== "https://eve.test") return await originalFetch(request, init);
if (url.pathname === "/eve/v1/session") {
const body = JSON.parse(String(init?.body));
- run = await start(workflowEntry, [
+ run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.ts
index d9c508b4f..b29622e02 100644
--- a/packages/eve/src/execution/eve-workflow-attributes.ts
+++ b/packages/eve/src/execution/eve-workflow-attributes.ts
@@ -31,6 +31,10 @@
* - `$eve.trace_id` — sampled trace seed available in the serialized context when
* tagging the run. This is a trace link, not a session-wide trace identity or
* confirmation that a destination retained the trace.
+ * - `$eve.version` — eve version that started the run; handoff successors
+ * and legacy importers re-record their own at boot. Ingress and the stranded
+ * replay guard compare it to decide whether the run can still execute
+ * - `$eve.session` — public session id a handoff successor owner serves
*/
import { CHANNEL_CONTEXT_KEY_NAME } from "#context/key-names.js";
@@ -52,6 +56,21 @@ import {
import { isSampledTrace } from "#tracing/sampled-trace.js";
import { resolveForwardedTraceSeed } from "#shared/forwarded-trace-policy.js";
+/** eve version recorded on every run eve starts; handoff successors and legacy importers re-record it at boot. */
+export const EVE_VERSION_ATTRIBUTE = "$eve.version";
+
+/** Run kind; only runs started as a session or subagent session carry it. */
+export const EVE_TYPE_ATTRIBUTE = "$eve.type";
+
+/**
+ * Public session id recorded on handoff successor owners. Initial owners omit
+ * it: their run id is the session id.
+ */
+export const EVE_SESSION_ATTRIBUTE = "$eve.session";
+
+/** Root session id of a delegated subagent session run. */
+export const EVE_ROOT_ATTRIBUTE = "$eve.root";
+
/**
* Active compiled graph node id for the session's agent. Returned by
* `createSessionStep` so workflow bodies don't have to load the bundle
@@ -282,7 +301,7 @@ export function buildSessionAttributes(input: {
"$eve.is_otel_trace_enabled": isOtelTraceEnabled,
"$eve.is_trace_content_visible": isTraceContentVisible,
"$eve.trace_id": readSessionTraceId(input.serializedContext),
- "$eve.type": "session",
+ [EVE_TYPE_ATTRIBUTE]: "session",
"$eve.trigger": readChannelKind(input.serializedContext),
"$eve.title": readSessionTitle(input.serializedContext),
};
@@ -310,11 +329,11 @@ export function buildSubagentRootAttributes(input: {
"$eve.is_otel_trace_enabled": isWorkflowOtelTraceEnabled(input.serializedContext),
"$eve.is_trace_content_visible": isWorkflowTraceContentVisible(input.serializedContext),
"$eve.trace_id": readSessionTraceId(input.serializedContext),
- "$eve.type": "subagent",
+ [EVE_TYPE_ATTRIBUTE]: "subagent",
"$eve.parent": input.parentSessionId,
"$eve.parent_call": input.parentCallId,
"$eve.parent_turn": input.parentTurnId,
- "$eve.root": input.rootSessionId,
+ [EVE_ROOT_ATTRIBUTE]: input.rootSessionId,
"$eve.subagent": input.identity.nodeId,
"$eve.trigger": readChannelKind(input.serializedContext),
};
diff --git a/packages/eve/src/execution/file-memory.integration.test.ts b/packages/eve/src/execution/file-memory.integration.test.ts
index bf8f35311..fab61c759 100644
--- a/packages/eve/src/execution/file-memory.integration.test.ts
+++ b/packages/eve/src/execution/file-memory.integration.test.ts
@@ -1,9 +1,9 @@
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { describe, expect, it } from "vitest";
import { workflowEntry } from "#execution/session/entry.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";
-import { start } from "#internal/workflow/runtime.js";
import { fileMemory, inMemory } from "#public/memory/file/index.js";
import { defineMemory } from "#public/memory/index.js";
import { byPrincipal } from "#public/memory/scope.js";
@@ -78,7 +78,7 @@ describe("file memory integration", () => {
});
async function runTurn(input: { readonly message: string; readonly principalId: string }) {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/install-workflow-world.ts b/packages/eve/src/execution/install-workflow-world.ts
new file mode 100644
index 000000000..b196bf366
--- /dev/null
+++ b/packages/eve/src/execution/install-workflow-world.ts
@@ -0,0 +1,19 @@
+import { getWorld, setWorld } from "#internal/workflow/runtime.js";
+import { guardStrandedSessionReplay } from "#execution/session-inbox/stranded-replay-guard.js";
+import {
+ validateWorkflowWorld,
+ type ValidateWorkflowWorldInput,
+} from "#internal/workflow/validate-world.js";
+
+/**
+ * Validates a Workflow World, installs it as the runtime singleton, and
+ * starts it. Generated World plugins call this so eve owns what wraps the
+ * World before its queue begins delivering.
+ */
+export async function installWorkflowWorld(input: ValidateWorkflowWorldInput): Promise<void> {
+ validateWorkflowWorld(input);
+ const world = guardStrandedSessionReplay(input.world);
+ setWorld(world);
+ await getWorld();
+ await world.start?.();
+}
diff --git a/packages/eve/src/execution/legacy-remote-agent/protocol.test.ts b/packages/eve/src/execution/legacy-remote-agent/protocol.test.ts
index 734642097..46a90c1d1 100644
--- a/packages/eve/src/execution/legacy-remote-agent/protocol.test.ts
+++ b/packages/eve/src/execution/legacy-remote-agent/protocol.test.ts
@@ -9,6 +9,8 @@ const getHookByTokenMock = vi.fn();
vi.mock("#compiled/@workflow/core/runtime.js", () => ({
getHookByToken: (token: string) => getHookByTokenMock(token),
+ // Vercel-shaped: owners run on their own deployment, so ingress resumes by token.
+ getWorld: async () => ({ capabilities: { deploymentAffinity: true } }),
resumeHook: (token: string, payload: unknown) => resumeHookMock(token, payload),
}));
@@ -34,6 +36,11 @@ describe("legacy task input route", () => {
});
it("delivers answers to the session behind the capability without replacing its principal", async () => {
+ getHookByTokenMock.mockImplementation(async (token: string) => ({
+ hookId: "hook-1",
+ runId: "run-1",
+ token,
+ }));
resumeHookMock.mockResolvedValue({ runId: "run-1" });
const response = await postAnswers(`eve:task-input:${DIGEST}`);
diff --git a/packages/eve/src/execution/legacy-session/authorization.test.ts b/packages/eve/src/execution/legacy-session/authorization.test.ts
index 15c0c92f2..11a87b8e2 100644
--- a/packages/eve/src/execution/legacy-session/authorization.test.ts
+++ b/packages/eve/src/execution/legacy-session/authorization.test.ts
@@ -3,6 +3,10 @@ import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
import { resumeAuthorizationCallback, handleExpiredLegacyAuthorization } from "./authorization.js";
const mocks = vi.hoisted(() => ({ resolve: vi.fn(), resume: vi.fn() }));
vi.mock("#internal/workflow/runtime.js", () => ({ resumeHook: mocks.resume }));
+// Owner classification has its own tests; every owner here is runnable.
+vi.mock("#execution/session-inbox/owner.js", () => ({
+ resumeRunnableHook: (token: string, payload: unknown) => mocks.resume(token, payload),
+}));
vi.mock("./inbox.js", async (original) => ({
...(await original<typeof import("./inbox.js")>()),
resolveLegacyInbox: mocks.resolve,
diff --git a/packages/eve/src/execution/legacy-session/authorization.ts b/packages/eve/src/execution/legacy-session/authorization.ts
index 1989fcd38..4649f44fb 100644
--- a/packages/eve/src/execution/legacy-session/authorization.ts
+++ b/packages/eve/src/execution/legacy-session/authorization.ts
@@ -1,5 +1,6 @@
import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
import type { AuthorizationCallbackPayload } from "#execution/session-inbox/inbox.js";
+import { resumeRunnableHook } from "#execution/session-inbox/owner.js";
import { resumeHook } from "#internal/workflow/runtime.js";
import { isObject } from "#shared/guards.js";
import { encodeLegacyCommand, resolveLegacyInbox } from "./inbox.js";
@@ -15,7 +16,7 @@ export async function resumeAuthorizationCallback(
payload: AuthorizationCallbackPayload,
): Promise<void> {
try {
- await resumeHook(token, payload);
+ await resumeRunnableHook(token, payload);
return;
} catch (error) {
if (!HookNotFoundError.is(error)) throw error;
diff --git a/packages/eve/src/execution/legacy-session/inbox.test.ts b/packages/eve/src/execution/legacy-session/inbox.test.ts
index 8cb38dab4..f91d9b52e 100644
--- a/packages/eve/src/execution/legacy-session/inbox.test.ts
+++ b/packages/eve/src/execution/legacy-session/inbox.test.ts
@@ -5,6 +5,11 @@ import { sessionCommandHookToken } from "#execution/session-inbox/address.js";
import { encodeLegacyCommand, resumeLegacyInbox, UnsupportedLegacySessionError } from "./inbox.js";
const { get, resume } = vi.hoisted(() => ({ get: vi.fn(), resume: vi.fn() }));
vi.mock("#internal/workflow/runtime.js", () => ({ getHookByToken: get, resumeHook: resume }));
+// Owner classification has its own tests; every owner here is runnable.
+vi.mock("#execution/session-inbox/owner.js", () => ({
+ lookupSessionOwnerHook: (token: string) => get(token),
+ resumeRunnableHook: (token: string, payload: unknown) => resume(token, payload),
+}));
beforeEach(() => {
get.mockReset();
resume.mockReset();
diff --git a/packages/eve/src/execution/legacy-session/inbox.ts b/packages/eve/src/execution/legacy-session/inbox.ts
index fccc07cda..5fac939ff 100644
--- a/packages/eve/src/execution/legacy-session/inbox.ts
+++ b/packages/eve/src/execution/legacy-session/inbox.ts
@@ -9,7 +9,8 @@ import {
sessionCommandHookToken,
sessionInboxHookToken,
} from "#execution/session-inbox/address.js";
-import { getHookByToken, resumeHook } from "#internal/workflow/runtime.js";
+import { lookupSessionOwnerHook, resumeRunnableHook } from "#execution/session-inbox/owner.js";
+import { getHookByToken } from "#internal/workflow/runtime.js";
import { isObject } from "#shared/guards.js";
type Command = DeliverHookPayload | SessionCommand | SessionTimeoutHookPayload;
@@ -38,14 +39,16 @@ const MAX_LEGACY_WIRE_VERSION = 7;
export async function resolveLegacyInbox(
token: string,
): Promise<{ hook: Hook; sessionId: string; current: boolean }> {
- const legacy = await getHookByToken(token);
+ const legacy = await lookupSessionOwnerHook(token);
const metadata = await legacy.metadata;
const sessionId =
isObject(metadata) && typeof metadata.sessionId === "string"
? metadata.sessionId
: legacy.runId;
try {
- const hook = await getHookByToken(sessionInboxHookToken(sessionCommandHookToken(sessionId)));
+ const hook = await lookupSessionOwnerHook(
+ sessionInboxHookToken(sessionCommandHookToken(sessionId)),
+ );
return { hook, sessionId, current: true };
} catch (error) {
if (!HookNotFoundError.is(error)) throw error;
@@ -63,7 +66,7 @@ export async function resumeLegacyInbox(token: string, command: Command) {
isObject(metadata) ? metadata.sessionInboxWireVersion : undefined,
);
}
- const hook = await resumeHook(target.hook.token, payload);
+ const hook = await resumeRunnableHook(target.hook.token, payload);
return { ownerRunId: hook.runId, sessionId: Promise.resolve(target.sessionId) };
}
diff --git a/packages/eve/src/execution/legacy-session/turn-workflow.ts b/packages/eve/src/execution/legacy-session/turn-workflow.ts
index 077121e34..4bb5eaaa2 100644
--- a/packages/eve/src/execution/legacy-session/turn-workflow.ts
+++ b/packages/eve/src/execution/legacy-session/turn-workflow.ts
@@ -5,6 +5,7 @@ import { createSessionInbox } from "#execution/session-inbox/inbox.js";
import { failSession, runPreparedSession } from "#execution/session/program.js";
import { sessionTimeoutDeadline } from "#execution/session/timeout.js";
import { createSessionTimeoutControl } from "#execution/session/timeout-control.js";
+import { recordSessionOwnerStep } from "#execution/session/handoff-steps.js";
import { completeLegacyDriverStep } from "./completion-step.js";
import { interruptLegacySessionStep } from "./interrupt-step.js";
import { prepareLegacySessionStep } from "./prepare-step.js";
@@ -20,6 +21,7 @@ export async function turnWorkflow(rawInput: unknown): Promise<void> {
"use workflow";
const prepared = await prepareLegacySessionStep(rawInput);
const { sessionId } = prepared.sessionState;
+ await recordSessionOwnerStep({ sessionId });
const inbox = createSessionInbox(sessionId);
try {
await inbox.claimSessionHook(sessionCommandHookToken(sessionId));
diff --git a/packages/eve/src/execution/session-inbox/address.ts b/packages/eve/src/execution/session-inbox/address.ts
index 6a24c1985..85905765c 100644
--- a/packages/eve/src/execution/session-inbox/address.ts
+++ b/packages/eve/src/execution/session-inbox/address.ts
@@ -30,13 +30,27 @@ export function sessionCommandHookToken(sessionId: string): string {
return `eve:session:${sessionId}:inbox`;
}
+const SESSION_INBOX_HOOK_TOKEN_PREFIX = "eve:inbox:v1:";
+
/**
* Physical hook token for a logical session address. Applied exactly where a
* hook is created or resumed, so current-generation hooks stay disjoint from
* hooks owned by pre-cutover drivers that used the logical token directly.
*/
export function sessionInboxHookToken(token: string): string {
- return `eve:inbox:v1:${token}`;
+ return `${SESSION_INBOX_HOOK_TOKEN_PREFIX}${token}`;
+}
+
+/** Whether a physical hook token addresses a current-generation session inbox. */
+export function isSessionInboxHookToken(token: string): boolean {
+ return token.startsWith(SESSION_INBOX_HOOK_TOKEN_PREFIX);
+}
+
+/** Logical address behind a physical session inbox hook token; `undefined` for any other hook. */
+export function logicalSessionInboxToken(token: string): string | undefined {
+ return isSessionInboxHookToken(token)
+ ? token.slice(SESSION_INBOX_HOOK_TOKEN_PREFIX.length)
+ : undefined;
}
/** Marker a releasing owner leaves so ingress can tell "handoff in progress" from "no session". */
diff --git a/packages/eve/src/execution/session-inbox/inbox.integration.test.ts b/packages/eve/src/execution/session-inbox/inbox.integration.test.ts
index fc80352b6..b09c6cb41 100644
--- a/packages/eve/src/execution/session-inbox/inbox.integration.test.ts
+++ b/packages/eve/src/execution/session-inbox/inbox.integration.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
import { sessionCommandInboxWorkflow } from "#internal/testing/session-inbox-workflow.js";
import { sessionHookPumpWorkflow } from "#internal/testing/session-hook-pump-workflow.js";
-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";
+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { getHookByToken, resumeHook, start } from "#internal/workflow/runtime.js";
import { sessionCommandHookToken } from "#execution/session-inbox/address.js";
import {
@@ -33,7 +33,7 @@ describe("session command inbox integration", () => {
it("stamps the public session id onto every inbox hook", async () => {
const channelToken = "http:session-inbox:session-id";
- const run = await start(sessionCommandInboxWorkflow, [{ token: channelToken }]);
+ const run = await startSessionOwner(sessionCommandInboxWorkflow, [{ token: channelToken }]);
const stableToken = sessionInboxHookToken(sessionCommandHookToken(run.runId));
try {
diff --git a/packages/eve/src/execution/session-inbox/owner.ts b/packages/eve/src/execution/session-inbox/owner.ts
new file mode 100644
index 000000000..0341f0317
--- /dev/null
+++ b/packages/eve/src/execution/session-inbox/owner.ts
@@ -0,0 +1,114 @@
+import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
+import { EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";
+import { isSessionInboxHookToken } from "#execution/session-inbox/address.js";
+import {
+ findRetiredOwnerRun,
+ routesToOwnerDeployment,
+ type OwnerRun,
+} from "#execution/session-inbox/runnable-owner.js";
+import { DevelopmentRunUnavailableError } from "#internal/workflow/development-run-unavailable-error.js";
+import { getHookByToken, getWorld, resumeHook, type Hook } from "#internal/workflow/runtime.js";
+
+/**
+ * The session's owner was built by another eve version, so this build cannot
+ * execute it and ingress refused the command before committing it. Internal:
+ * carries the owner run, which never reaches a client.
+ */
+export class StrandedSessionOwnerError extends Error {
+ /** The owner's hook, when ingress looked it up; its metadata names the session. */
+ readonly hook: Hook | undefined;
+ readonly ownerRun: OwnerRun;
+
+ constructor(ownerRun: OwnerRun, hook?: Hook) {
+ super(`Session owner run "${ownerRun.runId}" is stranded.`);
+ this.name = "StrandedSessionOwnerError";
+ this.hook = hook;
+ this.ownerRun = ownerRun;
+ }
+
+ get ownerRunId(): string {
+ return this.ownerRun.runId;
+ }
+
+ /** eve version that built the owner, when it recorded one. */
+ get eveVersion(): string | undefined {
+ return this.ownerRun.attributes[EVE_VERSION_ATTRIBUTE];
+ }
+}
+
+/**
+ * The single ingress path into a hook: refuses a session inbox whose owner
+ * cannot execute before anything is committed, then resumes by token. Any
+ * other hook resumes unchecked. Resuming by token rather than by the looked-up
+ * hook keeps Workflow's delivery dedup, which a caller-supplied hook disables.
+ */
+export async function resumeRunnableHook(
+ token: string,
+ payload: unknown,
+): Promise<Awaited<ReturnType<typeof resumeHook>>> {
+ if (isSessionInboxHookToken(token)) await assertRunnableSessionInbox(token);
+ return await resumeHook(token, payload);
+}
+
+/**
+ * Throws {@link StrandedSessionOwnerError} when the run holding a physical
+ * session inbox token cannot execute. An unheld token passes: resuming it
+ * reports the absence. Where the World replays each run on its own
+ * deployment, every owner can execute, so nothing is looked up.
+ */
+export async function assertRunnableSessionInbox(token: string): Promise<void> {
+ const world = await getWorld();
+ if (routesToOwnerDeployment(world)) return;
+ const holder = await findSessionHookHolder(token);
+ if (holder !== undefined) await assertRunnableOwner(world, holder.runId, holder.hook);
+}
+
+/** {@link assertRunnableSessionInbox} for a hook the caller already looked up. */
+export async function assertRunnableSessionOwner(hook: Hook): Promise<void> {
+ const world = await getWorld();
+ if (routesToOwnerDeployment(world)) return;
+ await assertRunnableOwner(world, hook.runId, hook);
+}
+
+/**
+ * The run holding a session hook token, or `undefined` when none does. The
+ * `eve dev` World refuses to expose the hooks of a run it will not execute
+ * (a dormant or ineligible generation) and names only the run, so `hook` is
+ * then absent. This is the only place that refusal is interpreted.
+ */
+export async function findSessionHookHolder(
+ token: string,
+): Promise<{ readonly runId: string; readonly hook?: Hook } | undefined> {
+ try {
+ const hook = await getHookByToken(token);
+ return { hook, runId: hook.runId };
+ } catch (error) {
+ if (HookNotFoundError.is(error)) return undefined;
+ if (DevelopmentRunUnavailableError.is(error)) return { runId: error.runId };
+ throw error;
+ }
+}
+
+/**
+ * Looks up a session hook. A run the `eve dev` World refuses to expose is
+ * stranded only when another eve version built it; otherwise a restart with
+ * `--resume` may run it, so the refusal propagates and nothing is ended.
+ */
+export async function lookupSessionOwnerHook(token: string): Promise<Hook> {
+ try {
+ return await getHookByToken(token);
+ } catch (error) {
+ if (!DevelopmentRunUnavailableError.is(error)) throw error;
+ await assertRunnableOwner(await getWorld(), error.runId);
+ throw error;
+ }
+}
+
+async function assertRunnableOwner(
+ world: Awaited<ReturnType<typeof getWorld>>,
+ runId: string,
+ hook?: Hook,
+): Promise<void> {
+ const ownerRun = await findRetiredOwnerRun(world, runId);
+ if (ownerRun !== undefined) throw new StrandedSessionOwnerError(ownerRun, hook);
+}
diff --git a/packages/eve/src/execution/session-inbox/resume.test.ts b/packages/eve/src/execution/session-inbox/resume.test.ts
index 54ae66e67..a2de49a60 100644
--- a/packages/eve/src/execution/session-inbox/resume.test.ts
+++ b/packages/eve/src/execution/session-inbox/resume.test.ts
@@ -1,16 +1,51 @@
-import { sessionInboxHookToken } from "#execution/session-inbox/address.js";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { sessionCommandHookToken } from "#execution/session-inbox/address.js";
-import { resumeSessionInbox } from "#execution/session-inbox/resume.js";
+import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
+import {
+ sessionCommandHookToken,
+ sessionInboxHookToken,
+} from "#execution/session-inbox/address.js";
+import { StrandedSessionOwnerError } from "#execution/session-inbox/owner.js";
+import { resumeSessionInbox, SessionHandoffPendingError } from "#execution/session-inbox/resume.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import { DevelopmentRunUnavailableError } from "#internal/workflow/development-run-unavailable-error.js";
+const getHookByTokenMock = vi.fn();
+const getWorldMock = vi.fn();
const resumeHookMock = vi.fn();
vi.mock("#internal/workflow/runtime.js", () => ({
+ getHookByToken: (...args: unknown[]) => getHookByTokenMock(...args),
+ getWorld: (...args: unknown[]) => getWorldMock(...args),
resumeHook: (...args: unknown[]) => resumeHookMock(...args),
}));
+/** Vercel-shaped: owners run on their own deployment, so ingress resumes by token without a lookup. */
+const vercelWorld = { capabilities: { deploymentAffinity: true } };
+
+/** A World without deployment affinity; owner runs record `ownerEveVersion`. */
+function singleDeploymentWorld(ownerEveVersion: string | undefined) {
+ return {
+ runs: {
+ get: vi.fn(async (runId: string) => ({
+ attributes: ownerEveVersion === undefined ? {} : { "$eve.version": ownerEveVersion },
+ runId,
+ })),
+ },
+ };
+}
+
+beforeEach(() => {
+ getWorldMock.mockResolvedValue(vercelWorld);
+ getHookByTokenMock.mockImplementation(async (token: string) => {
+ if (!token.startsWith(sessionInboxHookToken(""))) throw new HookNotFoundError(token);
+ return sessionHook("owner-2", token, { sessionId: "session-1" });
+ });
+});
+
afterEach(() => {
+ getHookByTokenMock.mockReset();
+ getWorldMock.mockReset();
resumeHookMock.mockReset();
});
@@ -24,6 +59,26 @@ describe("session inbox resume", () => {
expect(receipt.ownerRunId).toBe("owner-2");
await expect(receipt.sessionId).resolves.toBe("session-1");
expect(resumeHookMock).toHaveBeenCalledWith(sessionInboxHookToken(token), { kind: "clear" });
+ expect(getHookByTokenMock).not.toHaveBeenCalled();
+ });
+
+ it("reads a runnable owner's version once per process", async () => {
+ const world = singleDeploymentWorld(resolveInstalledPackageInfo().version);
+ getWorldMock.mockResolvedValue(world);
+ const hook = sessionHook("owner-runnable", "channel:runnable", { sessionId: "session-1" });
+ getHookByTokenMock.mockResolvedValue(hook);
+ resumeHookMock.mockResolvedValue(hook);
+
+ await resumeSessionInbox("channel:runnable", { kind: "clear" });
+ await resumeSessionInbox("channel:runnable", { kind: "compact" });
+
+ expect(world.runs.get).toHaveBeenCalledOnce();
+ expect(resumeHookMock).toHaveBeenNthCalledWith(1, sessionInboxHookToken("channel:runnable"), {
+ kind: "clear",
+ });
+ expect(resumeHookMock).toHaveBeenNthCalledWith(2, sessionInboxHookToken("channel:runnable"), {
+ kind: "compact",
+ });
});
it("resolves a saved public address through the stable token", async () => {
@@ -74,8 +129,90 @@ describe("session inbox resume", () => {
await expect(receipt.sessionId).rejects.toThrow("command accepted");
expect(resumeHookMock).toHaveBeenCalledOnce();
});
+
+ it("refuses a retired owner before committing the command", async () => {
+ getWorldMock.mockResolvedValue(singleDeploymentWorld("0.0.1"));
+
+ const refusal = await resumeSessionInbox("channel:alias", {
+ kind: "send",
+ payload: { message: "Alice follows up." },
+ }).catch((error: unknown) => error);
+
+ expect(refusal).toBeInstanceOf(StrandedSessionOwnerError);
+ expect(refusal).toMatchObject({ eveVersion: "0.0.1", ownerRunId: "owner-2" });
+ await expect((refusal as StrandedSessionOwnerError).hook?.metadata).resolves.toEqual({
+ sessionId: "session-1",
+ });
+ expect(resumeHookMock).not.toHaveBeenCalled();
+ });
+
+ it("refuses an owner that recorded no eve version as retired", async () => {
+ getWorldMock.mockResolvedValue(singleDeploymentWorld(undefined));
+
+ const refusal = await resumeSessionInbox("channel:alias", {
+ kind: "send",
+ payload: { message: "Alice follows up." },
+ }).catch((error: unknown) => error);
+
+ expect(refusal).toBeInstanceOf(StrandedSessionOwnerError);
+ expect(refusal).toMatchObject({ eveVersion: undefined, ownerRunId: "owner-2" });
+ expect(resumeHookMock).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ ["retires a dormant eve dev run another eve version built", "0.0.1", true],
+ ["keeps a dormant eve dev run this eve version built", undefined, false],
+ ])("%s", async (_name, ownerEveVersion, stranded) => {
+ getWorldMock.mockResolvedValue(
+ singleDeploymentWorld(ownerEveVersion ?? resolveInstalledPackageInfo().version),
+ );
+ // The `eve dev` World refuses every hook lookup for a dormant run, including the resume's own.
+ const dormant = async (token: string) => {
+ if (!token.startsWith(sessionInboxHookToken(""))) throw new HookNotFoundError(token);
+ throw new DevelopmentRunUnavailableError({ availability: "dormant", runId: "owner-1" });
+ };
+ getHookByTokenMock.mockImplementation(dormant);
+ resumeHookMock.mockImplementation(dormant);
+
+ const refusal = await resumeSessionInbox(
+ { sessionId: "session-1" },
+ { kind: "send", payload: { message: "Bob checks in." } },
+ ).catch((error: unknown) => error);
+
+ // A same-version dormant run may resume with `eve dev --resume`, so it is never ended.
+ expect(refusal).toBeInstanceOf(
+ stranded ? StrandedSessionOwnerError : DevelopmentRunUnavailableError,
+ );
+ if (stranded) expect(resumeHookMock).not.toHaveBeenCalled();
+ });
+
+ it("does not report a handoff that outlives the retry window as an unowned address", async () => {
+ vi.useFakeTimers();
+ try {
+ resumeHookMock.mockRejectedValue(new HookNotFoundError("inbox"));
+ getHookByTokenMock.mockImplementation(async (token: string) =>
+ sessionHook("releasing-owner", token, {}),
+ );
+
+ const delivery = resumeSessionInbox("channel:alias", {
+ kind: "send",
+ payload: { message: "Alice asks about the release." },
+ }).catch((error: unknown) => error);
+ await vi.advanceTimersByTimeAsync(6_000);
+
+ await expect(delivery).resolves.toBeInstanceOf(SessionHandoffPendingError);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
});
function sessionHook(runId: string, token: string, metadata: Record<string, unknown>) {
- return { metadata: Promise.resolve(metadata), runId, token };
+ return {
+ hookId: `hook-${runId}`,
+ metadata: Promise.resolve(metadata),
+ runId,
+ specVersion: 6,
+ token,
+ };
}
diff --git a/packages/eve/src/execution/session-inbox/resume.ts b/packages/eve/src/execution/session-inbox/resume.ts
index f06778f96..7103abd37 100644
--- a/packages/eve/src/execution/session-inbox/resume.ts
+++ b/packages/eve/src/execution/session-inbox/resume.ts
@@ -18,7 +18,12 @@ import {
sessionInboxHookToken,
type SessionInboxAddress,
} from "#execution/session-inbox/address.js";
-import { getHookByToken, resumeHook } from "#internal/workflow/runtime.js";
+import {
+ assertRunnableSessionOwner,
+ lookupSessionOwnerHook,
+ resumeRunnableHook,
+} from "#execution/session-inbox/owner.js";
+import { getHookByToken, type Hook } from "#internal/workflow/runtime.js";
import { isObject } from "#shared/guards.js";
/** Longest a delivery waits for a mid-handoff successor to claim its hooks. */
@@ -36,20 +41,23 @@ export interface ResumedSessionInboxHook {
* deployment handoff the address is briefly unowned; the releasing owner
* leaves a marker for that interval, so delivery retries instead of
* reporting the session gone and letting a channel start a replacement.
+ * The retry window bounds this request, not the handoff: a marker that
+ * outlives it throws {@link SessionHandoffPendingError}.
*/
export async function resumeSessionInbox(
address: string | SessionInboxAddress,
command: DeliverHookPayload | SessionCommand | SessionTimeoutHookPayload | SessionFailurePayload,
): Promise<ResumedSessionInboxHook> {
- const token = logicalToken(address);
+ const token = logicalSessionToken(address);
+ const knownSessionId = typeof address === "string" ? undefined : address.sessionId;
const deadline = Date.now() + HANDOFF_RETRY_WINDOW_MS;
while (true) {
- let hook;
+ let hook: Awaited<ReturnType<typeof resumeRunnableHook>>;
try {
- hook = await resumeHook(sessionInboxHookToken(token), command);
+ hook = await resumeRunnableHook(sessionInboxHookToken(token), command);
} catch (error) {
if (!HookNotFoundError.is(error)) throw error;
- if (await isHandoffInProgress(token, deadline)) continue;
+ if (await waitWhileHandoffInProgress(token, deadline)) continue;
if (command.kind === "session-failure") throw error;
return await resumeLegacyInbox(token, command).catch(rethrowUnsupportedAsNotFound);
}
@@ -59,9 +67,7 @@ export async function resumeSessionInbox(
get sessionId() {
return (identity ??= (async () => {
try {
- return typeof address === "string"
- ? requireSessionId(await hook.metadata)
- : address.sessionId;
+ return knownSessionId ?? requireSessionId(await hook.metadata);
} catch (cause) {
// A failed identity read must never cause a second delivery.
throw new AcceptedSessionIdentityError(cause);
@@ -72,6 +78,20 @@ export async function resumeSessionInbox(
}
}
+/**
+ * The address's owner is still handing off after the request's retry window.
+ * Nothing was delivered. The address is not unowned, so callers must not start
+ * a session there; the request can be retried.
+ */
+export class SessionHandoffPendingError extends Error {
+ constructor(token: string) {
+ super(
+ `Session address "${token}" is still changing owners. Nothing was delivered; retry the request.`,
+ );
+ this.name = "SessionHandoffPendingError";
+ }
+}
+
export class AcceptedSessionIdentityError extends Error {
constructor(cause: unknown) {
super("Session command accepted, but its session identity could not be resolved.", { cause });
@@ -103,22 +123,31 @@ function rethrowUnsupportedAsNotFound(error: unknown): never {
throw error;
}
-function logicalToken(address: string | SessionInboxAddress): string {
+/** Logical token behind an address: the address itself, or the session's stable command token. */
+export function logicalSessionToken(address: string | SessionInboxAddress): string {
if (typeof address === "string") return address;
if (!isSessionInboxAddress(address))
throw new Error("Session inbox target has an invalid address.");
return sessionCommandHookToken(address.sessionId);
}
-/** Waits one retry interval when a handoff marker exists; false once the window closes or no marker exists. */
-async function isHandoffInProgress(token: string, deadline: number): Promise<boolean> {
- if (Date.now() >= deadline) return false;
+/**
+ * Waits one retry interval when a handoff marker exists; false when no marker
+ * exists. Throws once the window closes with the marker still in place.
+ */
+async function waitWhileHandoffInProgress(token: string, deadline: number): Promise<boolean> {
+ let marker: Hook;
try {
- await getHookByToken(sessionHandoffMarkerToken(token));
+ marker = await lookupSessionOwnerHook(sessionHandoffMarkerToken(token));
} catch (error) {
if (HookNotFoundError.is(error)) return false;
throw error;
}
+ if (Date.now() >= deadline) {
+ // A releasing owner that cannot execute never finishes its handoff.
+ await assertRunnableSessionOwner(marker);
+ throw new SessionHandoffPendingError(token);
+ }
await new Promise<void>((resolve) => setTimeout(resolve, HANDOFF_RETRY_INTERVAL_MS));
return true;
}
diff --git a/packages/eve/src/execution/session-inbox/runnable-owner.ts b/packages/eve/src/execution/session-inbox/runnable-owner.ts
new file mode 100644
index 000000000..379b31abb
--- /dev/null
+++ b/packages/eve/src/execution/session-inbox/runnable-owner.ts
@@ -0,0 +1,49 @@
+import type { World } from "#compiled/@workflow/world/index.js";
+import { EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+
+export type OwnerRun = Awaited<ReturnType<World["runs"]["get"]>>;
+
+/** Bounds the process-wide set; a cleared entry only costs one more run read. */
+const RUNNABLE_OWNER_CACHE_LIMIT = 10_000;
+
+/**
+ * Owner runs this process has seen record the running eve version. A run's
+ * version never changes once it starts, so a positive answer stays true for
+ * the life of the process; retired owners are never cached.
+ */
+const runnableOwnerRunIds = new Set<string>();
+
+/**
+ * Whether the World replays every run on the deployment that started it
+ * (Vercel). There, an owner from another eve version is the normal handoff
+ * case, not a stranded one.
+ */
+export function routesToOwnerDeployment(world: Pick<World, "capabilities">): boolean {
+ return world.capabilities?.deploymentAffinity === true;
+}
+
+/**
+ * Whether this build can replay the owner run. On a World that does not route
+ * each run to its own deployment, only one build serves it, so an owner that
+ * records another eve version, or none, is retired: nothing can execute it again.
+ */
+function isRunnableOwnerRun(run: Pick<OwnerRun, "attributes">): boolean {
+ return run.attributes[EVE_VERSION_ATTRIBUTE] === resolveInstalledPackageInfo().version;
+}
+
+/**
+ * The owner run when it is retired, or `undefined` when this build can run it.
+ * Reads the run only when it is not already known to be runnable.
+ */
+export async function findRetiredOwnerRun(
+ world: Pick<World, "runs">,
+ runId: string,
+): Promise<OwnerRun | undefined> {
+ if (runnableOwnerRunIds.has(runId)) return undefined;
+ const run = await world.runs.get(runId, { resolveData: "none" });
+ if (!isRunnableOwnerRun(run)) return run;
+ if (runnableOwnerRunIds.size >= RUNNABLE_OWNER_CACHE_LIMIT) runnableOwnerRunIds.clear();
+ runnableOwnerRunIds.add(runId);
+ return undefined;
+}
diff --git a/packages/eve/src/execution/session-inbox/stranded-replay-guard.integration.test.ts b/packages/eve/src/execution/session-inbox/stranded-replay-guard.integration.test.ts
new file mode 100644
index 000000000..83aeba52b
--- /dev/null
+++ b/packages/eve/src/execution/session-inbox/stranded-replay-guard.integration.test.ts
@@ -0,0 +1,218 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
+import type { World } from "#compiled/@workflow/world/index.js";
+import { EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";
+import {
+ SESSION_TIMEOUT_WORKFLOW_NAME,
+ WORKFLOW_ENTRY_NAME,
+ WORKFLOW_TOOL_RUN_WORKFLOW_NAME,
+} from "#execution/stable-workflow-names.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import { captureLogRecords } from "#internal/testing/log-records.js";
+import { parkedAnchorWorkflow } from "#internal/testing/session-inbox-workflow.js";
+import { waitForHook } from "#internal/testing/workflow-test-helpers.js";
+import { getWorld, start } from "#internal/workflow/runtime.js";
+import { guardStrandedSessionReplay } from "#execution/session-inbox/stranded-replay-guard.js";
+
+type QueueHandler = Parameters<World["createQueueHandler"]>[1];
+
+const QUEUE_PREFIX = "__eve_test_wkf_workflow_";
+const { name: packageName, version: currentEveVersion } = resolveInstalledPackageInfo();
+const SESSION_QUEUE = `${QUEUE_PREFIX}workflow//${packageName}//${WORKFLOW_ENTRY_NAME}`;
+const TOOL_QUEUE = `${QUEUE_PREFIX}workflow//${packageName}//${WORKFLOW_TOOL_RUN_WORKFLOW_NAME}`;
+
+/** Parks a run on the shared local World, stamped with the given `$eve.version` and attributes. */
+async function parkRun(
+ token: string,
+ eveVersion: string | undefined,
+ attributes: Readonly<Record<string, string>> = {},
+) {
+ const stamped: Record<string, string> = { ...attributes };
+ if (eveVersion !== undefined) stamped[EVE_VERSION_ATTRIBUTE] = eveVersion;
+ const run = await start(parkedAnchorWorkflow, [{ token }], {
+ allowReservedAttributes: true,
+ attributes: stamped,
+ });
+ await waitForHook(run, { token });
+ return run;
+}
+
+/**
+ * Guards a view of the shared World whose queue hands back the wrapped
+ * delivery handler, so the test can deliver messages without a queue.
+ */
+async function guardedDelivery(capabilities?: World["capabilities"]) {
+ const world = Object.create(await getWorld()) as World;
+ if (capabilities !== undefined) world.capabilities = capabilities;
+ let wrapped: QueueHandler | undefined;
+ world.createQueueHandler = (_prefix, handler) => {
+ wrapped = handler;
+ return async () => new Response();
+ };
+ const handler = vi.fn<QueueHandler>(async () => undefined);
+ guardStrandedSessionReplay(world).createQueueHandler(QUEUE_PREFIX, handler);
+ const deliver = async (runId: string, queueName = SESSION_QUEUE) =>
+ await wrapped!(
+ { runId },
+ { attempt: 1, messageId: "msg_1" as never, queueName: queueName as never },
+ );
+ return { deliver, handler, world };
+}
+
+describe("guardStrandedSessionReplay", () => {
+ it.each([{ eveVersion: "0.0.1" }, { eveVersion: undefined }])(
+ "acknowledges a stranded session from eve $eveVersion without replaying it",
+ async ({ eveVersion }) => {
+ const logs = captureLogRecords();
+ const run = await parkRun(`replay-guard:stranded:${eveVersion}`, eveVersion);
+ try {
+ const { deliver, handler } = await guardedDelivery();
+
+ await expect(deliver(run.runId)).resolves.toBeUndefined();
+
+ expect(handler).not.toHaveBeenCalled();
+ await expect(run.status).resolves.toBe("running");
+ expect(logs.records).toContainEqual(
+ expect.objectContaining({
+ level: "warn",
+ message: expect.stringContaining(`stranded session run "${run.runId}"`),
+ }),
+ );
+ } finally {
+ await run.cancel();
+ }
+ },
+ );
+
+ it.each([
+ { kind: "subagent", eveVersion: "0.0.1", queue: SESSION_QUEUE },
+ { kind: "subagent", eveVersion: undefined, queue: SESSION_QUEUE },
+ { kind: "workflow tool", eveVersion: "0.0.1", queue: TOOL_QUEUE },
+ { kind: "workflow tool", eveVersion: undefined, queue: TOOL_QUEUE },
+ ])("retires a $kind from eve $eveVersion without replay", async ({ kind, eveVersion, queue }) => {
+ captureLogRecords();
+ const token = `replay-guard:retire:${kind}:${eveVersion}`;
+ const run = await parkRun(
+ token,
+ eveVersion,
+ kind === "subagent" ? { "$eve.type": "subagent" } : {},
+ );
+ try {
+ const { deliver, handler, world } = await guardedDelivery();
+
+ await expect(deliver(run.runId, queue)).resolves.toBeUndefined();
+
+ expect(handler).not.toHaveBeenCalled();
+ await expect(run.status).resolves.toBe("cancelled");
+ await expect(world.hooks.getByToken(token)).rejects.toSatisfy(HookNotFoundError.is);
+ const events = await world.events.list({ runId: run.runId, resolveData: "all" });
+ expect(events.data).toContainEqual(
+ expect.objectContaining({
+ eventType: "run_cancelled",
+ eventData: { cancelReason: "Run retired: its eve deployment is no longer available" },
+ }),
+ );
+ await expect(deliver(run.runId, queue)).resolves.toBeUndefined();
+ } finally {
+ if ((await run.status) === "running") await run.cancel();
+ }
+ });
+
+ it("retries a delivery whose run cannot be read instead of replaying it", async () => {
+ const run = await parkRun("replay-guard:unreadable", "0.0.1");
+ try {
+ const { deliver, handler, world } = await guardedDelivery();
+ const runs = world.runs;
+ world.runs = {
+ ...runs,
+ get: vi
+ .fn()
+ .mockRejectedValueOnce(new Error("storage unavailable"))
+ .mockImplementation(runs.get.bind(runs)),
+ };
+
+ await expect(deliver(run.runId)).rejects.toThrow("storage unavailable");
+ expect(handler).not.toHaveBeenCalled();
+
+ captureLogRecords();
+ await expect(deliver(run.runId)).resolves.toBeUndefined();
+ expect(handler).not.toHaveBeenCalled();
+ await expect(run.status).resolves.toBe("running");
+ } finally {
+ await run.cancel();
+ }
+ });
+
+ it("retries retirement after a cancellation write fails without replaying the run", async () => {
+ captureLogRecords();
+ const token = "replay-guard:retry-retirement";
+ const run = await parkRun(token, "0.0.1");
+ try {
+ const { deliver, handler, world } = await guardedDelivery();
+ const failure = new Error("storage unavailable");
+ world.events = {
+ ...world.events,
+ create: vi
+ .fn()
+ .mockRejectedValueOnce(failure)
+ .mockImplementation(world.events.create.bind(world.events)),
+ };
+
+ await expect(deliver(run.runId, TOOL_QUEUE)).rejects.toThrow("storage unavailable");
+ expect(handler).not.toHaveBeenCalled();
+ await expect(run.status).resolves.toBe("running");
+ await expect(world.hooks.getByToken(token)).resolves.toMatchObject({ runId: run.runId });
+
+ await expect(deliver(run.runId, TOOL_QUEUE)).resolves.toBeUndefined();
+ await expect(run.status).resolves.toBe("cancelled");
+ expect(handler).not.toHaveBeenCalled();
+ } finally {
+ if ((await run.status) === "running") await run.cancel();
+ }
+ });
+
+ it.each([
+ { case: "a runnable session run", eveVersion: currentEveVersion, queue: SESSION_QUEUE },
+ { case: "a runnable workflow tool run", eveVersion: currentEveVersion, queue: TOOL_QUEUE },
+ {
+ case: "an older session timeout run",
+ eveVersion: "0.0.1",
+ queue: `${QUEUE_PREFIX}workflow//${packageName}//${SESSION_TIMEOUT_WORKFLOW_NAME}`,
+ },
+ {
+ case: "another workflow's run",
+ eveVersion: "0.0.1",
+ queue: `${QUEUE_PREFIX}workflow//${packageName}//turnWorkflow`,
+ },
+ {
+ capabilities: { deploymentAffinity: true },
+ case: "an older session run where the World replays it on its own deployment",
+ eveVersion: "0.0.1",
+ queue: SESSION_QUEUE,
+ },
+ {
+ attributes: { "$eve.type": "subagent" },
+ case: "a runnable subagent session run",
+ eveVersion: currentEveVersion,
+ queue: SESSION_QUEUE,
+ },
+ {
+ capabilities: { deploymentAffinity: true },
+ case: "an older workflow tool run on its own deployment",
+ eveVersion: "0.0.1",
+ queue: TOOL_QUEUE,
+ },
+ ])("delivers $case", async ({ attributes, capabilities, case: name, eveVersion, queue }) => {
+ const run = await parkRun(`replay-guard:${name}`, eveVersion, attributes);
+ try {
+ const { deliver, handler } = await guardedDelivery(capabilities);
+
+ await deliver(run.runId, queue);
+
+ expect(handler).toHaveBeenCalledOnce();
+ } finally {
+ await run.cancel();
+ }
+ });
+});
diff --git a/packages/eve/src/execution/session-inbox/stranded-replay-guard.ts b/packages/eve/src/execution/session-inbox/stranded-replay-guard.ts
new file mode 100644
index 000000000..fbf1096b1
--- /dev/null
+++ b/packages/eve/src/execution/session-inbox/stranded-replay-guard.ts
@@ -0,0 +1,138 @@
+import type { World } from "#compiled/@workflow/world/index.js";
+import { EVE_TYPE_ATTRIBUTE, EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";
+import {
+ findRetiredOwnerRun,
+ routesToOwnerDeployment,
+ type OwnerRun,
+} from "#execution/session-inbox/runnable-owner.js";
+import {
+ WORKFLOW_ENTRY_NAME,
+ WORKFLOW_TOOL_RUN_WORKFLOW_NAME,
+} from "#execution/stable-workflow-names.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import { createLogger } from "#internal/logging.js";
+import {
+ isInactiveWorkflowRunError,
+ isMissingWorkflowRunError,
+} from "#internal/workflow/is-inactive-workflow-run-error.js";
+import { cancelRun } from "#internal/workflow/runtime.js";
+
+const log = createLogger("execution.session-inbox.stranded-replay-guard");
+
+/**
+ * Makes the World acknowledge, without replaying, queue deliveries for
+ * top-level eve session runs that another eve version started. Worlds that
+ * re-enqueue their active runs at startup (local, Postgres) would otherwise
+ * replay such a run on this build's code and fail it as `CORRUPTED_EVENT_LOG`.
+ * A top-level session stays active until ingress replaces it or its timeout
+ * ends it. Subagent sessions and workflow tool runs are cancelled instead:
+ * no later user message can replace their interrupted work. Ingress refuses
+ * the same owners by the same verdict, so preserved owners cannot admit work.
+ * Timeout workflows remain runnable so they can end preserved sessions.
+ *
+ * Mutates and returns `world`; only its `createQueueHandler` changes. Worlds
+ * that replay each run on its own deployment are returned untouched.
+ */
+export function guardStrandedSessionReplay<TWorld extends World>(world: TWorld): TWorld {
+ if (routesToOwnerDeployment(world)) return world;
+ const { name } = resolveInstalledPackageInfo();
+ const guardedWorkflows = new Map<string, GuardedWorkflow>([
+ [`workflow//${name}//${WORKFLOW_ENTRY_NAME}`, "session"],
+ [`workflow//${name}//${WORKFLOW_TOOL_RUN_WORKFLOW_NAME}`, "tool"],
+ ]);
+ const createQueueHandler = world.createQueueHandler.bind(world);
+ world.createQueueHandler = (queueNamePrefix, handler) =>
+ createQueueHandler(queueNamePrefix, async (message, meta) => {
+ const workflow = guardedWorkflows.get(meta.queueName.slice(queueNamePrefix.length));
+ const runId = readRunId(message);
+ if (
+ workflow !== undefined &&
+ runId !== undefined &&
+ (await skipRetiredRun(world, runId, workflow))
+ ) {
+ return undefined;
+ }
+ return await handler(message, meta);
+ });
+ return world;
+}
+
+type GuardedWorkflow = "session" | "tool";
+
+/** Applies {@link strandedReplayAction}; true when the delivery must not replay. */
+async function skipRetiredRun(
+ world: World,
+ runId: string,
+ workflow: GuardedWorkflow,
+): Promise<boolean> {
+ const run = await readRetiredRun(world, runId);
+ if (run === undefined) return false;
+ switch (strandedReplayAction(run, workflow)) {
+ case "replay":
+ return false;
+ case "retire":
+ await retireRun(world, run);
+ return true;
+ case "park":
+ logParkedSession(run);
+ return true;
+ }
+}
+
+/**
+ * What to do with a delivery for a retired run. Only an active run needs a
+ * verdict. A top-level session parks so ingress or its timeout can replace or
+ * end it; a subagent session or workflow tool run is retired, because no
+ * later user message can replace its interrupted work.
+ */
+function strandedReplayAction(
+ run: OwnerRun,
+ workflow: GuardedWorkflow,
+): "park" | "replay" | "retire" {
+ if (run.status !== "pending" && run.status !== "running") return "replay";
+ return workflow === "tool" || run.attributes[EVE_TYPE_ATTRIBUTE] === "subagent"
+ ? "retire"
+ : "park";
+}
+
+/** The run when another eve version started it; `undefined` when this build can replay it. */
+async function readRetiredRun(world: World, runId: string): Promise<OwnerRun | undefined> {
+ try {
+ return await findRetiredOwnerRun(world, runId);
+ } catch (error) {
+ // A resilient start enqueues before its run is readable; such a run is new.
+ if (isMissingWorkflowRunError(error)) return undefined;
+ // Anything else is retried by the queue: replaying a retired run would corrupt it.
+ throw error;
+ }
+}
+
+async function retireRun(world: World, run: OwnerRun): Promise<void> {
+ try {
+ await cancelRun(world, run.runId, {
+ cancelReason: "Run retired: its eve deployment is no longer available",
+ });
+ } catch (error) {
+ // A concurrent cancellation or completion has already retired the run.
+ if (!isInactiveWorkflowRunError(error)) throw error;
+ }
+ log.warn("Retired stranded descendant run", {
+ runId: run.runId,
+ previousEveVersion: run.attributes[EVE_VERSION_ATTRIBUTE] ?? "unknown",
+ currentEveVersion: resolveInstalledPackageInfo().version,
+ });
+}
+
+function logParkedSession(run: OwnerRun): void {
+ log.warn(
+ `Skipping replay of stranded session run "${run.runId}" (owner eve ${run.attributes[EVE_VERSION_ATTRIBUTE] ?? "unknown"}, current ${resolveInstalledPackageInfo().version}). It remains active until an ordinary channel message, an explicit reset, or its session timeout ends it.`,
+ );
+}
+
+function readRunId(message: unknown): string | undefined {
+ if (typeof message !== "object" || message === null || "__healthCheck" in message) {
+ return undefined;
+ }
+ const runId = (message as { readonly runId?: unknown }).runId;
+ return typeof runId === "string" && runId.length > 0 ? runId : undefined;
+}
diff --git a/packages/eve/src/execution/session-limit-cancellation.integration.test.ts b/packages/eve/src/execution/session-limit-cancellation.integration.test.ts
index 552acd5ee..25e5c4371 100644
--- a/packages/eve/src/execution/session-limit-cancellation.integration.test.ts
+++ b/packages/eve/src/execution/session-limit-cancellation.integration.test.ts
@@ -1,6 +1,7 @@
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { sessionInboxHookToken } from "#execution/session-inbox/address.js";
import { describe, expect, it } from "vitest";
-import { resumeHook, start } from "#internal/workflow/runtime.js";
+import { resumeHook } from "#internal/workflow/runtime.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
import {
@@ -88,7 +89,7 @@ describe("session-limit continuation decline integration", () => {
const continuationToken = "http:limit-decline-root";
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/session-reset.integration.test.ts b/packages/eve/src/execution/session-reset.integration.test.ts
index 61f4ce773..be38650a1 100644
--- a/packages/eve/src/execution/session-reset.integration.test.ts
+++ b/packages/eve/src/execution/session-reset.integration.test.ts
@@ -6,9 +6,8 @@ import { SessionKey } from "#context/keys.js";
import { ensureSandboxAccess } from "#execution/sandbox/ensure.js";
import { shutdownActiveSandboxHandles } from "#execution/sandbox/active-handles.js";
import { sessionCommandInboxWorkflow } from "#internal/testing/session-inbox-workflow.js";
-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";
+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
-import { start } from "#internal/workflow/runtime.js";
import { createWorkflowRuntime } from "#execution/workflow-runtime.js";
import { defineSandboxProvider } from "#shared/sandbox-provider.js";
import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
@@ -28,7 +27,9 @@ describe("session reset integration", () => {
compiledArtifactsSource: {} as RuntimeCompiledArtifactsSource,
});
const sandboxes = createSessionSandboxHarness();
- const first = await start(sessionCommandInboxWorkflow, [{ token: continuationToken }]);
+ const first = await startSessionOwner(sessionCommandInboxWorkflow, [
+ { token: continuationToken },
+ ]);
try {
await waitForHook(first, { token: sessionInboxHookToken(continuationToken) });
@@ -44,7 +45,9 @@ describe("session reset integration", () => {
await expect(first.returnValue).resolves.toBeUndefined();
await expect(runtime.resolveContinuation(continuationToken)).resolves.toBeUndefined();
- const second = await start(sessionCommandInboxWorkflow, [{ token: continuationToken }]);
+ const second = await startSessionOwner(sessionCommandInboxWorkflow, [
+ { token: continuationToken },
+ ]);
try {
await expect(
waitForHook(second, { token: sessionInboxHookToken(continuationToken) }),
diff --git a/packages/eve/src/execution/session/entry-authorization.integration.test.ts b/packages/eve/src/execution/session/entry-authorization.integration.test.ts
index 3a1156115..b07372bbf 100644
--- a/packages/eve/src/execution/session/entry-authorization.integration.test.ts
+++ b/packages/eve/src/execution/session/entry-authorization.integration.test.ts
@@ -7,10 +7,10 @@ import { createWorkflowRuntime } from "#execution/workflow-runtime.js";
import { slackChannel } from "#public/channels/slack/slackChannel.js";
import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
-import { resumeHook, start } from "#internal/workflow/runtime.js";
+import { resumeHook } from "#internal/workflow/runtime.js";
import { filterEventsByType } from "#internal/testing/events.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";
+import { startSessionOwner, waitForHook } from "#internal/testing/workflow-test-helpers.js";
import { workflowEntry } from "#execution/session/entry.js";
import {
sessionCommandHookToken,
@@ -139,7 +139,7 @@ describe("workflowEntry integration", () => {
const continuationToken = "http:workflow-entry-auth-followup";
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -579,7 +579,7 @@ function userAuth(principalId: string) {
}
async function startWeatherRun(continuationToken: string) {
- return await start(workflowEntry, [
+ return await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/session/entry-handoff-lifetime.integration.test.ts b/packages/eve/src/execution/session/entry-handoff-lifetime.integration.test.ts
index e0b7abd13..a9f36d62b 100644
--- a/packages/eve/src/execution/session/entry-handoff-lifetime.integration.test.ts
+++ b/packages/eve/src/execution/session/entry-handoff-lifetime.integration.test.ts
@@ -1,6 +1,7 @@
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { DEFAULT_SESSION_TIMEOUT_MS } from "#execution/session/timeout.js";
import { assert, describe, expect, it, vi } from "vitest";
-import { getWorld, resumeHook, start } from "#internal/workflow/runtime.js";
+import { getWorld, resumeHook } from "#internal/workflow/runtime.js";
import { hydrateStepReturnValue, hydrateWorkflowArguments } from "@workflow/core/serialization";
import { captureTurnEvents } from "#internal/testing/events.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
@@ -28,7 +29,7 @@ describe("workflowEntry integration", () => {
const runtime = await createTestRuntime({ agent: { name: "workflow-entry-handoff" } });
await runtime.run(async () => {
- const anchor = await start(workflowEntry, [
+ const anchor = await startSessionOwner(workflowEntry, [
{
kind: "initial",
sessionTimeoutMs,
@@ -221,7 +222,7 @@ describe("workflowEntry integration", () => {
const runtime = await createTestRuntime({ agent: { name: "workflow-entry-compaction" } });
await runtime.run(async () => {
- const anchor = await start(workflowEntry, [
+ const anchor = await startSessionOwner(workflowEntry, [
{
kind: "initial",
sessionTimeoutMs: 60_000,
diff --git a/packages/eve/src/execution/session/entry-handoff.integration.test.ts b/packages/eve/src/execution/session/entry-handoff.integration.test.ts
index f63220009..8d00cb715 100644
--- a/packages/eve/src/execution/session/entry-handoff.integration.test.ts
+++ b/packages/eve/src/execution/session/entry-handoff.integration.test.ts
@@ -1,7 +1,8 @@
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import type { HandoffWorkflowEntryInput } from "#execution/session/entry-input.js";
import type { RunCreatedEventRequest } from "@workflow/world";
import { assert, describe, expect, it, vi } from "vitest";
-import { getWorld, resumeHook, start } from "#internal/workflow/runtime.js";
+import { getWorld, resumeHook } from "#internal/workflow/runtime.js";
import { dehydrateWorkflowArguments, hydrateWorkflowArguments } from "@workflow/core/serialization";
import { captureTurnEvents } from "#internal/testing/events.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
@@ -29,7 +30,7 @@ describe("workflowEntry integration", () => {
const output = captureConsoleOutput();
const runtime = await createTestRuntime({ agent: { name: "handoff-validation" } });
await runtime.run(async () => {
- const anchor = await start(workflowEntry, [
+ const anchor = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_a",
@@ -178,7 +179,7 @@ describe("workflowEntry integration", () => {
const output = captureConsoleOutput();
const runtime = await createTestRuntime({ agent: { name: "handoff-checkpoint-version" } });
await runtime.run(async () => {
- const anchor = await start(workflowEntry, [
+ const anchor = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_a",
@@ -360,7 +361,7 @@ describe("workflowEntry integration", () => {
const output = captureConsoleOutput();
const runtime = await createTestRuntime({ agent: { name: "handoff-eve-066-owner" } });
await runtime.run(async () => {
- const anchor = await start(workflowEntry, [
+ const anchor = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_a",
@@ -462,7 +463,7 @@ describe("workflowEntry integration", () => {
const runtime = await createTestRuntime({ agent: { name: "workflow-entry-handoff" } });
await runtime.run(async () => {
- const anchor = await start(workflowEntry, [
+ const anchor = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_a",
@@ -565,7 +566,7 @@ describe("workflowEntry integration", () => {
const continuationToken = "http:workflow-entry-handoff-alias";
await runtime.run(async () => {
- const anchor = await start(workflowEntry, [
+ const anchor = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_a",
@@ -673,7 +674,7 @@ describe("workflowEntry integration", () => {
const runtime = await createTestRuntime({ agent: { name: "workflow-entry-handoff-busy" } });
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_a",
diff --git a/packages/eve/src/execution/session/entry.integration.test.ts b/packages/eve/src/execution/session/entry.integration.test.ts
index 6b1d70742..4d6eb57cc 100644
--- a/packages/eve/src/execution/session/entry.integration.test.ts
+++ b/packages/eve/src/execution/session/entry.integration.test.ts
@@ -4,7 +4,7 @@ import { hydrateWorkflowArguments } from "@workflow/core/serialization";
import { createChannelAddress } from "#channel/channel-address.js";
import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";
+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
import { workflowEntry } from "#execution/session/entry.js";
import {
@@ -173,7 +173,7 @@ describe("workflowEntry integration", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -256,7 +256,7 @@ describe("workflowEntry integration", () => {
});
try {
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -291,7 +291,7 @@ describe("workflowEntry integration", () => {
const continuationToken = "http:workflow-entry-conversation";
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -519,7 +519,7 @@ describe("workflowEntry integration", () => {
const runtime = await createTestRuntime({ agent: { name: "workflow-entry-id-only" } });
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -549,7 +549,7 @@ describe("workflowEntry integration", () => {
const continuationToken = "http:workflow-entry-event-ids";
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -635,7 +635,7 @@ describe("workflowEntry integration", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -682,7 +682,7 @@ describe("workflowEntry integration", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -748,7 +748,7 @@ describe("workflowEntry integration", () => {
const childContinuationToken = "subagent:parent-session:call-1";
await runtime.run(async () => {
- const child = await start(workflowEntry, [
+ const child = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -848,7 +848,7 @@ describe("workflowEntry integration", () => {
const firstCallerToken = "subagent:parent-session:call-1";
await runtime.run(async () => {
- const child = await start(workflowEntry, [
+ const child = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -1207,7 +1207,7 @@ describe("workflowEntry integration", () => {
const continuationToken = "http:workflow-entry-hook-owner";
await runtime.run(async () => {
- const owner = await start(workflowEntry, [
+ const owner = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -1227,7 +1227,7 @@ describe("workflowEntry integration", () => {
const firstTurn = await ownerStream.nextTurn();
expect(firstTurn.at(-1)?.type).toBe("session.waiting");
- const contender = await start(workflowEntry, [
+ const contender = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -1275,7 +1275,7 @@ describe("workflowEntry integration", () => {
} as const;
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -1634,7 +1634,7 @@ async function withHeldApprovalRun(
};
if (options.auth !== undefined) context.auth = options.auth;
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/session/entry.ts b/packages/eve/src/execution/session/entry.ts
index d22edf42a..b8959e5a0 100644
--- a/packages/eve/src/execution/session/entry.ts
+++ b/packages/eve/src/execution/session/entry.ts
@@ -26,6 +26,7 @@ import {
sessionCommandHookToken,
} from "#execution/session-inbox/address.js";
import {
+ recordSessionOwnerStep,
signalSessionOwnerActivationStep,
stopUntrackedChildSessionsStep,
validateSessionCheckpointStep,
@@ -265,6 +266,7 @@ async function bootHandoffOwner(
}
({ checkpoint, childRunIdsToStop } = migration);
serializedContext = stampSessionIdentity(checkpoint.serializedContext, sessionId);
+ await recordSessionOwnerStep({ sessionId });
await inbox.claimSessionHooks(
sessionHookTokens({ serializedContext, sessionState: checkpoint.sessionState }),
);
diff --git a/packages/eve/src/execution/session/handoff-steps.ts b/packages/eve/src/execution/session/handoff-steps.ts
index 1dba19c70..9abf5fc0c 100644
--- a/packages/eve/src/execution/session/handoff-steps.ts
+++ b/packages/eve/src/execution/session/handoff-steps.ts
@@ -15,6 +15,11 @@ import {
} from "#execution/session/handoff.js";
import { createLogger, logError } from "#internal/logging.js";
import { cancelRun, getWorld, resumeHook } from "#internal/workflow/runtime.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import {
+ EVE_SESSION_ATTRIBUTE,
+ EVE_VERSION_ATTRIBUTE,
+} from "#execution/eve-workflow-attributes.js";
import { getResolvedRuntimeAgentNode } from "#runtime/graph.js";
import { BundleKey } from "#runtime/sessions/runtime-context-keys.js";
import { getSandboxEnvironmentRuntime } from "#shared/sandbox-environment.js";
@@ -184,6 +189,26 @@ export async function reportSessionHandoffRetainedStep(input: {
});
}
+/**
+ * Records the identity of an owner that this deployment's code did not start
+ * (a handoff successor or a legacy importer) before it claims any hook:
+ * ingress reads `$eve.version` to decide whether the owner can run, so a
+ * missing value would strand a healthy session. The value comes from this
+ * step's code, not the previous owner's. Unlike observability attributes, a
+ * failed write fails the boot.
+ */
+export async function recordSessionOwnerStep(input: { readonly sessionId: string }): Promise<void> {
+ "use step";
+ const { setAttributes } = await import("#compiled/@workflow/core/index.js");
+ await setAttributes(
+ {
+ [EVE_SESSION_ATTRIBUTE]: input.sessionId,
+ [EVE_VERSION_ATTRIBUTE]: resolveInstalledPackageInfo().version,
+ },
+ { allowReservedAttributes: true },
+ );
+}
+
export async function signalSessionOwnerActivationStep(input: {
readonly activation: SessionOwnerActivation;
readonly token: string;
diff --git a/packages/eve/src/execution/session/timeout-steps.test.ts b/packages/eve/src/execution/session/timeout-steps.test.ts
index c45575eab..f8fbead61 100644
--- a/packages/eve/src/execution/session/timeout-steps.test.ts
+++ b/packages/eve/src/execution/session/timeout-steps.test.ts
@@ -6,15 +6,19 @@ import {
startSessionTimeoutStep,
} from "#execution/session/timeout-steps.js";
import { sessionTimeoutWorkflowReference } from "#execution/workflow-runtime.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import { sessionInboxHookToken } from "#execution/session-inbox/address.js";
+import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
const cancelRunMock = vi.fn();
+const getHookByTokenMock = vi.fn();
const getWorldMock = vi.fn();
const resumeHookMock = vi.fn();
const startMock = vi.fn();
vi.mock("#compiled/@workflow/core/runtime.js", () => ({
cancelRun: (...args: unknown[]) => cancelRunMock(...args),
- getHookByToken: (...args: unknown[]) => resumeHookMock(...args),
+ getHookByToken: (...args: unknown[]) => getHookByTokenMock(...args),
getWorld: (...args: unknown[]) => getWorldMock(...args),
resumeHook: (...args: unknown[]) => resumeHookMock(...args),
start: (...args: unknown[]) => startMock(...args),
@@ -26,12 +30,27 @@ const TIMEOUT_HOOK = {
token: "session-1:session-timeout",
};
+/** A single-deployment World whose owner runs record the given eve version. */
+function singleDeploymentWorld(ownerEveVersion = resolveInstalledPackageInfo().version) {
+ return {
+ getDeploymentId: async () => "dpl_current",
+ runs: {
+ get: async (runId: string) => ({ attributes: { "$eve.version": ownerEveVersion }, runId }),
+ },
+ };
+}
+
beforeEach(() => {
- getWorldMock.mockResolvedValue({ getDeploymentId: async () => "dpl_current" });
+ getHookByTokenMock.mockImplementation(async (token: string) => {
+ if (!token.startsWith(sessionInboxHookToken(""))) throw new HookNotFoundError(token);
+ return { runId: "session-1", specVersion: 6, token };
+ });
+ getWorldMock.mockResolvedValue(singleDeploymentWorld());
});
afterEach(() => {
cancelRunMock.mockReset();
+ getHookByTokenMock.mockReset();
getWorldMock.mockReset();
resumeHookMock.mockReset();
startMock.mockReset();
@@ -50,6 +69,8 @@ describe("session timeout steps", () => {
await expect(startSessionTimeoutStep(input)).resolves.toEqual({ runId: "timer-run" });
expect(startMock).toHaveBeenCalledWith(sessionTimeoutWorkflowReference, [input], {
+ allowReservedAttributes: true,
+ attributes: { "$eve.version": resolveInstalledPackageInfo().version },
deploymentId: "dpl_current",
});
});
diff --git a/packages/eve/src/execution/session/turn-step.test.ts b/packages/eve/src/execution/session/turn-step.test.ts
index ec3e00bec..804942028 100644
--- a/packages/eve/src/execution/session/turn-step.test.ts
+++ b/packages/eve/src/execution/session/turn-step.test.ts
@@ -233,7 +233,14 @@ vi.mock("../../runtime/sessions/compiled-agent-cache.js", () => ({
}));
vi.mock("#compiled/@workflow/core/runtime.js", () => ({
+ getHookByToken: async (token: string) => {
+ const { HookNotFoundError } = await import("#compiled/@workflow/errors/index.js");
+ if (!token.startsWith("eve:inbox:v1:")) throw new HookNotFoundError(token);
+ return currentSessionHook(token);
+ },
getRun: (...args: unknown[]) => getRunMock(...args),
+ // Vercel-shaped: owners run on their own deployment, so ingress resumes by token.
+ getWorld: async () => ({ capabilities: { deploymentAffinity: true } }),
resumeHook: (...args: unknown[]) => resumeHookMock(...args),
start: (...args: unknown[]) => startMock(...args),
}));
diff --git a/packages/eve/src/execution/tool-stubs/execution.integration.test.ts b/packages/eve/src/execution/tool-stubs/execution.integration.test.ts
index 3b972debc..ff0219ef2 100644
--- a/packages/eve/src/execution/tool-stubs/execution.integration.test.ts
+++ b/packages/eve/src/execution/tool-stubs/execution.integration.test.ts
@@ -1,8 +1,9 @@
import { FatalError } from "#compiled/@workflow/errors/index.js";
import { STUB_FAILURE_NAMESPACE, stubResponseNamespace } from "#tool-stubs/types.js";
import { describe, expect, it, vi } from "vitest";
-import { getWorld, start } from "#internal/workflow/runtime.js";
+import { getWorld } from "#internal/workflow/runtime.js";
import { createTestRuntime } from "#internal/testing/app-harness.js";
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { buildSerializedContext, handoffFollowUp } from "#internal/testing/entry-test-helpers.js";
import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";
import { workflowEntry } from "#execution/session/entry.js";
@@ -60,7 +61,7 @@ describe("tool replacement through the session runtime", () => {
],
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -135,7 +136,7 @@ describe("tool replacement through the session runtime", () => {
});
await runtime.run(async () => {
const message = 'Run deploy_service with service "api"';
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -216,7 +217,7 @@ describe("tool replacement through the session runtime", () => {
],
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -300,7 +301,7 @@ describe("tool replacement through the session runtime", () => {
],
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -355,7 +356,7 @@ describe("tool replacement through the session runtime", () => {
it("replaces the whole agent tool without starting a remote or local agent", async () => {
const runtime = await createTestRuntime();
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -410,7 +411,7 @@ describe("tool replacement through the session runtime", () => {
],
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -491,7 +492,7 @@ describe("tool replacement through the session runtime", () => {
],
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -557,7 +558,7 @@ describe("tool replacement through the session runtime", () => {
toolName: "deploy_service",
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization-close.integration.test.ts b/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization-close.integration.test.ts
index afe6bd77c..963b32f6a 100644
--- a/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization-close.integration.test.ts
+++ b/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization-close.integration.test.ts
@@ -1,5 +1,6 @@
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { describe, expect, it } from "vitest";
-import { getWorld, start } from "#internal/workflow/runtime.js";
+import { getWorld } from "#internal/workflow/runtime.js";
import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";
import { workflowEntry } from "#execution/session/entry.js";
import { sessionCommandHookToken } from "#execution/session-inbox/address.js";
@@ -24,7 +25,7 @@ describe("workflow step authorization failures", () => {
toolName: "deploy_service",
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization.integration.test.ts b/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization.integration.test.ts
index a9bdf3c35..5da3d89f7 100644
--- a/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization.integration.test.ts
+++ b/packages/eve/src/execution/tools/workflow/workflow-tool-run-authorization.integration.test.ts
@@ -1,5 +1,6 @@
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { describe, expect, it } from "vitest";
-import { getRun, getWorld, start } from "#internal/workflow/runtime.js";
+import { getRun, getWorld } from "#internal/workflow/runtime.js";
import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";
import { workflowEntry } from "#execution/session/entry.js";
import { hydrateWorkflowReturnValue } from "@workflow/core/serialization";
@@ -18,7 +19,7 @@ describe("workflow step authorization", () => {
toolName: "deploy_service",
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -63,7 +64,7 @@ describe("workflow step authorization", () => {
toolName: "deploy_service",
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/tools/workflow/workflow-tool-run-cancellation.integration.test.ts b/packages/eve/src/execution/tools/workflow/workflow-tool-run-cancellation.integration.test.ts
index 91cb5455b..d30bb4a28 100644
--- a/packages/eve/src/execution/tools/workflow/workflow-tool-run-cancellation.integration.test.ts
+++ b/packages/eve/src/execution/tools/workflow/workflow-tool-run-cancellation.integration.test.ts
@@ -1,7 +1,7 @@
import { afterEach, describe, expect, it, vi } from "vitest";
-import { getWorld, start } from "#internal/workflow/runtime.js";
+import { getWorld } from "#internal/workflow/runtime.js";
import { captureTurnEvents, filterEventsByType } from "#internal/testing/events.js";
-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";
+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { workflowEntry } from "#execution/session/entry.js";
import { sessionCommandHookToken } from "#execution/session-inbox/address.js";
import { resumeSessionInbox } from "#execution/session-inbox/resume.js";
@@ -27,7 +27,7 @@ describe("workflow tool cancellation", () => {
await runtime.run(async () => {
const before = await listWorkflowToolRunIds();
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/tools/workflow/workflow-tool-run.integration.test.ts b/packages/eve/src/execution/tools/workflow/workflow-tool-run.integration.test.ts
index b697ff753..ed2e45d47 100644
--- a/packages/eve/src/execution/tools/workflow/workflow-tool-run.integration.test.ts
+++ b/packages/eve/src/execution/tools/workflow/workflow-tool-run.integration.test.ts
@@ -1,6 +1,7 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { hydrateStepArguments } from "#compiled/@workflow/core/serialization.js";
-import { getWorld, start } from "#internal/workflow/runtime.js";
+import { getWorld } from "#internal/workflow/runtime.js";
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import {
captureTurnEvents,
containsEventSequence,
@@ -39,7 +40,7 @@ describe("workflow tools", () => {
toolName: "deploy_service",
});
const output = await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -63,7 +64,7 @@ describe("workflow tools", () => {
});
const output = await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -87,7 +88,7 @@ describe("workflow tools", () => {
});
const output = await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -113,7 +114,7 @@ describe("workflow tools", () => {
});
const output = await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -145,7 +146,7 @@ describe("workflow tools", () => {
});
const output = await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -171,7 +172,7 @@ describe("workflow tools", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -259,7 +260,7 @@ describe("workflow tools", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -338,7 +339,7 @@ describe("workflow tools", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -397,7 +398,7 @@ describe("workflow tools", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -463,7 +464,7 @@ describe("workflow tools", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -521,7 +522,7 @@ describe("workflow tools", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -560,7 +561,7 @@ describe("workflow tools", () => {
const earlyNote = "Alice notes that the api rollout window opens at noon.";
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/turn-cancellation.integration.test.ts b/packages/eve/src/execution/turn-cancellation.integration.test.ts
index 1bbde866c..f71fa5c17 100644
--- a/packages/eve/src/execution/turn-cancellation.integration.test.ts
+++ b/packages/eve/src/execution/turn-cancellation.integration.test.ts
@@ -1,6 +1,6 @@
import { sessionInboxHookToken } from "#execution/session-inbox/address.js";
import { describe, expect, it } from "vitest";
-import { getWorld, resumeHook, start } from "#internal/workflow/runtime.js";
+import { getWorld, resumeHook } from "#internal/workflow/runtime.js";
import { createTestRuntime, type TestRuntime } from "#internal/testing/app-harness.js";
import { mockChannelContext } from "#internal/testing/mocks/mock-channel-operations.js";
@@ -9,7 +9,7 @@ import {
containsEventSequence,
filterEventsByType,
} from "#internal/testing/events.js";
-import { waitForHook } from "#internal/testing/workflow-test-helpers.js";
+import { waitForHook, startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";
import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
import { sessionCommandHookToken } from "#execution/session-inbox/address.js";
@@ -345,7 +345,7 @@ describe("turn cancellation integration", () => {
});
await fixture.runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -435,7 +435,7 @@ describe("turn cancellation integration", () => {
});
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -489,7 +489,7 @@ describe("turn cancellation integration", () => {
});
await fixture.runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -545,7 +545,7 @@ describe("turn cancellation integration", () => {
});
await fixture.runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -597,7 +597,7 @@ describe("turn cancellation integration", () => {
const continuationToken = "http:turn-cancel-tool";
await fixture.runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -684,7 +684,7 @@ describe("turn cancellation integration", () => {
status: "no_active_turn",
});
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -778,7 +778,7 @@ describe("turn cancellation integration", () => {
status: "no_active_turn",
});
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -854,7 +854,7 @@ describe("turn cancellation integration", () => {
const continuationToken = "http:turn-cancel-stale-guard";
await fixture.runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -903,7 +903,7 @@ describe("turn cancellation integration", () => {
const continuationToken = "http:turn-cancel-late";
await runtime.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.ts
index cd4f754f6..701be939f 100644
--- a/packages/eve/src/execution/workflow-runtime.test.ts
+++ b/packages/eve/src/execution/workflow-runtime.test.ts
@@ -35,6 +35,8 @@ import { captureLogRecords } from "#internal/testing/log-records.js";
const getHookByTokenMock = vi.fn();
const world = {
+ // Vercel-shaped: owners run on their own deployment, so ingress resumes by token.
+ capabilities: { deploymentAffinity: true },
getDeploymentId: vi.fn(async () => "dpl_current"),
};
const getRunMock = vi.fn();
@@ -188,7 +190,11 @@ describe("session owner starts", () => {
sessionId: "anchor-1",
}),
],
- { deploymentId: "deployment-b" },
+ {
+ deploymentId: "deployment-b",
+ allowReservedAttributes: true,
+ attributes: { "$eve.version": resolveInstalledPackageInfo().version },
+ },
);
});
});
@@ -229,7 +235,6 @@ describe("createWorkflowRuntime command dispatch", () => {
payload: { message: "hello" },
requestId: "req_deliver",
});
- expect(getHookByTokenMock).not.toHaveBeenCalled();
});
it.each(["pending", "running", "completed", "failed", "cancelled"])(
@@ -267,7 +272,6 @@ describe("createWorkflowRuntime command dispatch", () => {
kind: "clear",
},
);
- expect(getHookByTokenMock).not.toHaveBeenCalled();
});
it("does not report an accepted command as missing when metadata hydration fails", async () => {
@@ -310,7 +314,6 @@ describe("createWorkflowRuntime command dispatch", () => {
payload: { message: "hello" },
},
);
- expect(getHookByTokenMock).not.toHaveBeenCalled();
});
it("acknowledges the exact delivery accepted by the session inbox", async () => {
@@ -382,7 +385,6 @@ describe("createWorkflowRuntime command dispatch", () => {
turnId: "turn-2",
},
);
- expect(getHookByTokenMock).not.toHaveBeenCalled();
});
it("maps missing and terminal targets to 'no_active_turn'", async () => {
@@ -425,9 +427,11 @@ describe("createWorkflowRuntime command dispatch", () => {
it("waits for reset to release the stable command inbox", async () => {
const { HookNotFoundError } = await import("#compiled/@workflow/errors/index.js");
resumeHookMock.mockResolvedValue(currentSessionHook("eve:token", "session-1"));
- getHookByTokenMock.mockImplementation(async (token: string) => {
- throw new HookNotFoundError(token);
- });
+ getHookByTokenMock
+ .mockResolvedValueOnce(currentSessionHook(sessionInboxHookToken("eve:token"), "session-1"))
+ .mockImplementation(async (token: string) => {
+ throw new HookNotFoundError(token);
+ });
await expect(
buildRuntime().dispatchContinuation({
@@ -592,6 +596,7 @@ describe("createWorkflowRuntime#createSession", () => {
"$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
+ "$eve.version": resolveInstalledPackageInfo().version,
},
deploymentId: "dpl_current",
},
@@ -763,6 +768,7 @@ describe("createWorkflowRuntime#createSession", () => {
"$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
+ "$eve.version": resolveInstalledPackageInfo().version,
},
deploymentId: "dpl_current",
},
@@ -808,6 +814,7 @@ describe("createWorkflowRuntime#createSession", () => {
"$eve.is_trace_content_visible": "false",
"$eve.trigger": "subagent",
"$eve.type": "subagent",
+ "$eve.version": resolveInstalledPackageInfo().version,
},
deploymentId: "dpl_current",
});
@@ -833,6 +840,7 @@ describe("createWorkflowRuntime#createSession", () => {
"$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
+ "$eve.version": resolveInstalledPackageInfo().version,
},
deploymentId: "dpl_current",
});
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index 64874c6c1..e36490eed 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -23,6 +23,7 @@ import { serializeContext } from "#context/serialize.js";
import {
buildSessionAttributes,
buildSubagentRootAttributes,
+ EVE_VERSION_ATTRIBUTE,
readParentLineage,
} from "#execution/eve-workflow-attributes.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
@@ -66,7 +67,9 @@ import {
AcceptedSessionIdentityError,
resolveSessionInbox,
resumeSessionInbox,
+ SessionHandoffPendingError,
} from "#execution/session-inbox/resume.js";
+import { StrandedSessionOwnerError } from "#execution/session-inbox/owner.js";
import type { SessionInboxAddress } from "#execution/session-inbox/address.js";
import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
import { initializeSessionInstrumentation } from "#instrumentation/runtime.js";
@@ -279,6 +282,10 @@ export async function startSessionOwnerStep(input: SessionOwnerStartInput): Prom
sessionWritable: getRun(anchorRunId).getWritable<Uint8Array>(),
sessionId: anchorRunId,
};
+ // The successor is stamped with this eve version at start, because the
+ // queue guard runs before it boots. Single-build Worlds share this version;
+ // deployment-affine Worlds bypass the guard and the successor records its
+ // own version at boot.
await startWorkflowOnDeployment(
workflowEntryReference,
[workflowInput],
@@ -298,19 +305,20 @@ async function dispatchWorkflowCommand<TCommand extends SessionCommand>(
const resumed = await resumeSessionInbox(token, command);
hook = { runId: resumed.ownerRunId, sessionId: await resumed.sessionId };
} catch (error) {
+ // Each entry point decides what a stranded owner means for its caller.
+ if (error instanceof StrandedSessionOwnerError) throw error;
+ // A send by session id to a session that still exists asks the caller to
+ // retry rather than reporting the session gone.
+ const sendBySessionId = command.kind === "send" && typeof token !== "string";
+ const retryLater = { status: "session_not_active", retryable: true };
+ // The address is owned, so it must never read as absent to a channel.
+ if (error instanceof SessionHandoffPendingError) {
+ if (sendBySessionId) return retryLater as SessionCommandResult<TCommand>;
+ throw error;
+ }
if (isInactiveCommandTarget(error)) {
- if (command.kind === "send" && typeof token !== "string") {
- try {
- const status = await getRun(token.sessionId).status;
- if (status === "pending" || status === "running") {
- return {
- status: "session_not_active",
- retryable: true,
- } as SessionCommandResult<TCommand>;
- }
- } catch (statusError) {
- if (!isInactiveCommandTarget(statusError)) throw statusError;
- }
+ if (sendBySessionId && (await isRunActive(token.sessionId))) {
+ return retryLater as SessionCommandResult<TCommand>;
}
return inactiveCommandResult(command);
}
@@ -376,6 +384,16 @@ export async function requestWorkflowTurnCancellation(
return await dispatchWorkflowCommand({ sessionId: input.sessionId }, command);
}
+async function isRunActive(runId: string): Promise<boolean> {
+ try {
+ const status = await getRun(runId).status;
+ return status === "pending" || status === "running";
+ } catch (error) {
+ if (isInactiveCommandTarget(error)) return false;
+ throw error;
+ }
+}
+
function isInactiveCommandTarget(error: unknown): boolean {
if (error instanceof AcceptedSessionIdentityError) return false;
if (HookNotFoundError.is(error)) return true;
@@ -441,10 +459,10 @@ export async function startWorkflowOnCurrentDeployment<TArgs extends unknown[],
}
/**
- * Starts on the deployment that accepted a delivery when one was stamped,
- * otherwise stays on the deployment executing this call.
+ * Starts a run on an exact deployment. Every run eve starts records the eve
+ * version that started it: ingress and the stranded replay guard read it to
+ * decide whether this build can still execute the run.
*/
-
async function startWorkflowOnDeployment<TArgs extends unknown[], TResult>(
workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata,
args: TArgs,
@@ -455,7 +473,12 @@ async function startWorkflowOnDeployment<TArgs extends unknown[], TResult>(
if (deploymentId.length === 0 || deploymentId === "latest") {
throw new Error("Workflow starts require an exact deployment id.");
}
- return await start(workflow, args, { ...options, deploymentId });
+ return await start(workflow, args, {
+ ...options,
+ allowReservedAttributes: true,
+ attributes: { ...options?.attributes, [EVE_VERSION_ATTRIBUTE]: EVE_PACKAGE_INFO.version },
+ deploymentId,
+ });
});
}
diff --git a/packages/eve/src/internal/application/compiled-artifacts.test.ts b/packages/eve/src/internal/application/compiled-artifacts.test.ts
index 6a05ddb61..d7027e774 100644
--- a/packages/eve/src/internal/application/compiled-artifacts.test.ts
+++ b/packages/eve/src/internal/application/compiled-artifacts.test.ts
@@ -15,17 +15,14 @@ describe("createWorkflowWorldPluginSource", () => {
expect(source).toContain('import "/app/.eve/compile/compiled-artifacts-bootstrap.mjs";');
expect(source).toContain('import * as workflowWorldModule from "@acme/eve-world";');
- expect(source).toContain("import { validateWorkflowWorld } from ");
+ expect(source).toContain("import { installWorkflowWorld } from ");
expect(source).toContain(
"const workflowWorld = await createWorldFromModule(workflowWorldModule);",
);
expect(source).toContain(
- 'validateWorkflowWorld({ packageName: "@acme/eve-world", world: workflowWorld });',
+ 'await installWorkflowWorld({ packageName: "@acme/eve-world", world: workflowWorld });',
);
expect(source).not.toContain("resolveLocalWorkflowWorldDataDirectory");
- expect(source).toContain("setWorld(workflowWorld);");
- expect(source).toContain("await getWorld();");
- expect(source).toContain("await workflowWorld.start?.();");
});
it("configures the vendored local World with eve's app-local data resolver", () => {
@@ -55,7 +52,7 @@ describe("createWorkflowWorldPluginSource", () => {
expect(source).toMatch(/headers: \{ "User-Agent": "eve\/.+" \}/);
expect(source).toContain("applyVercelWorkflowWorldDefaults(workflowWorld);");
expect(source.indexOf("applyVercelWorkflowWorldDefaults(workflowWorld);")).toBeLessThan(
- source.indexOf("setWorld(workflowWorld);"),
+ source.indexOf("await installWorkflowWorld("),
);
});
});
@@ -68,9 +65,10 @@ describe("createDevelopmentWorkflowWorldPluginSource", () => {
});
expect(source).toContain("createDevelopmentWorkflowWorld");
- expect(source).toContain("setWorld(createDevelopmentWorkflowWorld());");
+ expect(source).toContain(
+ "await installWorkflowWorld({ world: createDevelopmentWorkflowWorld() });",
+ );
expect(source).not.toContain("@workflow/world-local");
- expect(source).not.toContain("workflowWorld.start");
});
it("keeps explicitly configured remote Worlds inside the worker", () => {
@@ -80,6 +78,6 @@ describe("createDevelopmentWorkflowWorldPluginSource", () => {
});
expect(source).toContain('import * as workflowWorldModule from "@acme/eve-world";');
- expect(source).toContain("await workflowWorld.start?.();");
+ expect(source).toContain("await installWorkflowWorld({");
});
});
diff --git a/packages/eve/src/internal/application/compiled-artifacts.ts b/packages/eve/src/internal/application/compiled-artifacts.ts
index 4621ea7ee..56548789b 100644
--- a/packages/eve/src/internal/application/compiled-artifacts.ts
+++ b/packages/eve/src/internal/application/compiled-artifacts.ts
@@ -300,19 +300,21 @@ export function createCompiledArtifactsBootstrapSource(input: {
].join("\n");
}
+function resolveInstallWorldImportSpecifier(): string {
+ return resolvePackageSourceFilePath("src/execution/install-workflow-world.ts");
+}
+
interface WorkflowWorldWiring {
/** Import specifier for the `workflowWorldModule` namespace import. */
readonly moduleImportSpecifier: string;
/** Extra import lines the construction source depends on. */
readonly extraImportLines: readonly string[];
- /** Named imports pulled from the workflow core runtime. */
- readonly runtimeImports: string;
/** Statement that assigns `workflowWorld`. */
readonly createWorldSource: string;
}
/**
- * Per-world wiring for the generated workflow-world plugin. The four pieces
+ * Per-world wiring for the generated workflow-world plugin. The pieces
* co-vary and must stay together: a world constructed through an explicit
* `createWorld(config)` call must not import `createWorldFromModule`, and
* only the vendored local World needs the data-directory resolver import.
@@ -339,7 +341,6 @@ const workflowWorld = await workflowWorldModule.createWorld({
return {
moduleImportSpecifier,
extraImportLines: importLines.split("\n"),
- runtimeImports: "getWorld, setWorld",
createWorldSource,
};
}
@@ -361,15 +362,16 @@ applyVercelWorkflowWorldDefaults(workflowWorld);`.trimStart();
extraImportLines: [
`import { applyVercelWorkflowWorldDefaults } from ${defaultsImportSpecifier};`,
],
- runtimeImports: "getWorld, setWorld",
createWorldSource,
};
}
+ const workflowRuntimeImportSpecifier = stringifyEsmImportSpecifier(
+ resolvePackageCompiledFilePath("src/compiled/@workflow/core/runtime.js"),
+ );
return {
moduleImportSpecifier: packageName,
- extraImportLines: [],
- runtimeImports: "createWorldFromModule, getWorld, setWorld",
+ extraImportLines: [`import { createWorldFromModule } from ${workflowRuntimeImportSpecifier};`],
createWorldSource: "const workflowWorld = await createWorldFromModule(workflowWorldModule);",
};
}
@@ -382,26 +384,16 @@ export function createWorkflowWorldPluginSource(input: {
const targetWorld = input.configuredWorld ?? input.defaultWorld;
const packageName = resolveWorkflowWorldImport(targetWorld);
const wiring = resolveWorkflowWorldWiring(packageName);
- const workflowRuntimeImportSpecifier = resolvePackageCompiledFilePath(
- "src/compiled/@workflow/core/runtime.js",
- );
- const workflowWorldValidationImportSpecifier = resolvePackageSourceFilePath(
- "src/internal/workflow/validate-world.ts",
- );
return [
"// Generated by eve. Do not edit by hand.",
`import ${stringifyEsmImportSpecifier(input.compiledArtifactsBootstrapPath)};`,
`import * as workflowWorldModule from ${stringifyEsmImportSpecifier(wiring.moduleImportSpecifier)};`,
...wiring.extraImportLines,
- `import { ${wiring.runtimeImports} } from ${stringifyEsmImportSpecifier(workflowRuntimeImportSpecifier)};`,
- `import { validateWorkflowWorld } from ${stringifyEsmImportSpecifier(workflowWorldValidationImportSpecifier)};`,
+ `import { installWorkflowWorld } from ${stringifyEsmImportSpecifier(resolveInstallWorldImportSpecifier())};`,
"",
wiring.createWorldSource,
- `validateWorkflowWorld({ packageName: ${JSON.stringify(input.configuredWorld)}, world: workflowWorld });`,
- "setWorld(workflowWorld);",
- "await getWorld();",
- "await workflowWorld.start?.();",
+ `await installWorkflowWorld({ packageName: ${JSON.stringify(input.configuredWorld)}, world: workflowWorld });`,
"",
"export default function installWorkflowWorldPlugin() {}",
"",
@@ -427,20 +419,16 @@ export function createDevelopmentWorkflowWorldPluginSource(input: {
defaultWorld: "local",
});
}
- const workflowRuntimeImportSpecifier = resolvePackageCompiledFilePath(
- "src/compiled/@workflow/core/runtime.js",
- );
const developmentWorldImportSpecifier = resolvePackageSourceFilePath(
"src/internal/workflow/development-world-client.ts",
);
return [
"// Generated by eve. Do not edit by hand.",
`import ${stringifyEsmImportSpecifier(input.compiledArtifactsBootstrapPath)};`,
- `import { getWorld, setWorld } from ${stringifyEsmImportSpecifier(workflowRuntimeImportSpecifier)};`,
`import { createDevelopmentWorkflowWorld } from ${stringifyEsmImportSpecifier(developmentWorldImportSpecifier)};`,
+ `import { installWorkflowWorld } from ${stringifyEsmImportSpecifier(resolveInstallWorldImportSpecifier())};`,
"",
- "setWorld(createDevelopmentWorkflowWorld());",
- "await getWorld();",
+ "await installWorkflowWorld({ world: createDevelopmentWorkflowWorld() });",
"",
"export default function installDevelopmentWorkflowWorldPlugin() {}",
"",
diff --git a/packages/eve/src/internal/testing/app-harness.integration.test.ts b/packages/eve/src/internal/testing/app-harness.integration.test.ts
index 07c418541..210b7ae02 100644
--- a/packages/eve/src/internal/testing/app-harness.integration.test.ts
+++ b/packages/eve/src/internal/testing/app-harness.integration.test.ts
@@ -1,5 +1,5 @@
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
import { describe, expect, it } from "vitest";
-import { start } from "#internal/workflow/runtime.js";
import { workflowEntry } from "#execution/session/entry.js";
import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
@@ -48,7 +48,7 @@ describe("AppHarness", () => {
const outputs = await Promise.all([
runtimeA.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
@@ -62,7 +62,7 @@ describe("AppHarness", () => {
return await readFirstTurnReply(run);
}),
runtimeB.run(async () => {
- const run = await start(workflowEntry, [
+ const run = await startSessionOwner(workflowEntry, [
{
kind: "initial",
ownerDeploymentId: "dpl_inline",
diff --git a/packages/eve/src/internal/testing/session-inbox-workflow.ts b/packages/eve/src/internal/testing/session-inbox-workflow.ts
index a488167c9..569204f7a 100644
--- a/packages/eve/src/internal/testing/session-inbox-workflow.ts
+++ b/packages/eve/src/internal/testing/session-inbox-workflow.ts
@@ -1,18 +1,20 @@
-import { getWorkflowMetadata } from "#compiled/@workflow/core/index.js";
+import { createHook, getWorkflowMetadata } from "#compiled/@workflow/core/index.js";
import { createSessionInbox } from "#execution/session-inbox/inbox.js";
import { sessionCommandHookToken } from "#execution/session-inbox/address.js";
export async function sessionCommandInboxWorkflow(input: {
+ /** Session whose stable inbox this owner holds; a handoff successor names its anchor. */
+ readonly sessionId?: string;
readonly token: string;
}): Promise<void> {
"use workflow";
- const { workflowRunId } = getWorkflowMetadata();
- const inbox = createSessionInbox(workflowRunId);
+ const sessionId = input.sessionId ?? getWorkflowMetadata().workflowRunId;
+ const inbox = createSessionInbox(sessionId);
try {
- await inbox.claimSessionHook(sessionCommandHookToken(workflowRunId));
+ await inbox.claimSessionHook(sessionCommandHookToken(sessionId));
await inbox.claimSessionHook(input.token);
while (true) {
const payload = await inbox.next();
@@ -22,3 +24,11 @@ export async function sessionCommandInboxWorkflow(input: {
await inbox.dispose();
}
}
+
+/** Parks like a session anchor after a handoff: it holds no session address of its own. */
+export async function parkedAnchorWorkflow(input: { readonly token: string }): Promise<void> {
+ "use workflow";
+
+ using gate = createHook<void>({ token: input.token });
+ await gate;
+}
diff --git a/packages/eve/src/internal/testing/workflow-test-helpers.ts b/packages/eve/src/internal/testing/workflow-test-helpers.ts
index 8b050ace7..6b3ddc1a9 100644
--- a/packages/eve/src/internal/testing/workflow-test-helpers.ts
+++ b/packages/eve/src/internal/testing/workflow-test-helpers.ts
@@ -1,4 +1,23 @@
-import { getWorld } from "#internal/workflow/runtime.js";
+import { EVE_VERSION_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";
+import { resolveInstalledPackageInfo } from "#internal/application/package.js";
+import { getWorld, start, type WorkflowFunction } from "#internal/workflow/runtime.js";
+
+/**
+ * Starts a session owner run stamped with the running eve version, as
+ * `createSession` does. Ingress on single-deployment Worlds treats an owner
+ * without the stamp as stranded, so a bare `start` would never accept input.
+ */
+export async function startSessionOwner<TArgs extends unknown[], TResult>(
+ workflow: WorkflowFunction<TArgs, TResult>,
+ args: TArgs,
+) {
+ return await start(workflow, args, {
+ allowReservedAttributes: true,
+ attributes: {
+ [EVE_VERSION_ATTRIBUTE]: resolveInstalledPackageInfo().version,
+ },
+ });
+}
interface WorkflowRunLike {
readonly runId: string;
diff --git a/packages/eve/src/internal/workflow/development-run-unavailable-error.ts b/packages/eve/src/internal/workflow/development-run-unavailable-error.ts
new file mode 100644
index 000000000..da33fe707
--- /dev/null
+++ b/packages/eve/src/internal/workflow/development-run-unavailable-error.ts
@@ -0,0 +1,29 @@
+const NAME = "DevelopmentRunUnavailableError";
+
+/**
+ * Raised by the `eve dev` World when a caller looks up a hook whose run
+ * belongs to a generation this dev server will not execute. It crosses the
+ * parent/worker boundary as a plain error, so identity is its name and its
+ * enumerable fields rather than the class.
+ */
+export class DevelopmentRunUnavailableError extends Error {
+ readonly availability: "dormant" | "ineligible";
+ readonly runId: string;
+
+ constructor(input: { readonly availability: "dormant" | "ineligible"; readonly runId: string }) {
+ super(
+ "Local Workflow run was not resumed. Start a new conversation, or restart eve dev with --resume to attempt recovery.",
+ );
+ this.name = NAME;
+ this.availability = input.availability;
+ this.runId = input.runId;
+ }
+
+ static is(value: unknown): value is DevelopmentRunUnavailableError {
+ return (
+ value instanceof Error &&
+ value.name === NAME &&
+ typeof (value as { runId?: unknown }).runId === "string"
+ );
+ }
+}
diff --git a/packages/eve/src/internal/workflow/development-world-server.integration.test.ts b/packages/eve/src/internal/workflow/development-world-server.integration.test.ts
index 4ceced177..c4291c80a 100644
--- a/packages/eve/src/internal/workflow/development-world-server.integration.test.ts
+++ b/packages/eve/src/internal/workflow/development-world-server.integration.test.ts
@@ -1,4 +1,5 @@
import { access, mkdir, rm, writeFile } from "node:fs/promises";
+import { DevelopmentRunUnavailableError } from "#internal/workflow/development-run-unavailable-error.js";
import { join } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
@@ -404,9 +405,17 @@ describe("parent development Workflow World", () => {
await second.start();
expect(startupFetch).not.toHaveBeenCalled();
startupFetch.mockRestore();
- await expect(createDevelopmentWorkflowWorld().hooks.getByToken(token)).rejects.toThrow(
- "Local Workflow run was not resumed",
- );
+ // Ingress reports the session stranded from this error, so its identity
+ // must survive the worker boundary.
+ const refusal = await createDevelopmentWorkflowWorld()
+ .hooks.getByToken(token)
+ .catch((error: unknown) => error);
+ expect(DevelopmentRunUnavailableError.is(refusal)).toBe(true);
+ expect(refusal).toMatchObject({
+ availability: "dormant",
+ message: expect.stringContaining("Local Workflow run was not resumed"),
+ runId,
+ });
for (const message of [
{ runId },
{ workflowRunId: runId },
diff --git a/packages/eve/src/internal/workflow/development-world-server.ts b/packages/eve/src/internal/workflow/development-world-server.ts
index fac0c9d73..1cb0da5a6 100644
--- a/packages/eve/src/internal/workflow/development-world-server.ts
+++ b/packages/eve/src/internal/workflow/development-world-server.ts
@@ -5,6 +5,7 @@ import {
import { listDevelopmentGenerationIds } from "#internal/nitro/dev-runtime-generation-metadata.js";
import { cancelExpiredDevelopmentRun } from "#internal/workflow/cancel-expired-development-run.js";
+import { DevelopmentRunUnavailableError } from "#internal/workflow/development-run-unavailable-error.js";
import type { ValidQueueName, World } from "#compiled/@workflow/world/index.js";
import { createWorld } from "#compiled/@workflow/world-local/index.js";
import { deriveEveWorkflowQueuePrefix } from "#internal/workflow/queue-namespace.js";
@@ -297,9 +298,10 @@ class LocalParentDevelopmentWorkflowWorld implements ParentDevelopmentWorkflowWo
const run = await this.#world.runs.get(hook.runId, { resolveData: "none" });
const availability = await this.#generationAvailability(run.deploymentId);
if (availability.kind === "dormant" || availability.kind === "ineligible") {
- throw new Error(
- "Local Workflow run was not resumed. Start a new conversation, or restart eve dev with --resume to attempt recovery.",
- );
+ throw new DevelopmentRunUnavailableError({
+ availability: availability.kind,
+ runId: hook.runId,
+ });
}
return hook;
}
diff --git a/packages/eve/src/runtime/connections/callback-route.test.ts b/packages/eve/src/runtime/connections/callback-route.test.ts
index ec3a169d5..466074bf3 100644
--- a/packages/eve/src/runtime/connections/callback-route.test.ts
+++ b/packages/eve/src/runtime/connections/callback-route.test.ts
@@ -7,6 +7,9 @@ import { handleConnectionCallbackRequest } from "#execution/connections/callback
const resumeHookMock = vi.fn();
vi.mock("#compiled/@workflow/core/runtime.js", () => ({
+ getHookByToken: async (token: string) => ({ runId: "owner", specVersion: 6, token }),
+ // Vercel-shaped: owners run on their own deployment, so ingress resumes by token.
+ getWorld: async () => ({ capabilities: { deploymentAffinity: true } }),
resumeHook: (token: string, payload: unknown) => resumeHookMock(token, payload),
}));
diff --git a/packages/eve/src/subagents/callback-route.ts b/packages/eve/src/subagents/callback-route.ts
index 775c744d9..a82118628 100644
--- a/packages/eve/src/subagents/callback-route.ts
+++ b/packages/eve/src/subagents/callback-route.ts
@@ -1,5 +1,5 @@
import { renameLegacyTaskCallback } from "#execution/legacy-remote-agent/protocol.js";
-import { resumeHook } from "#internal/workflow/runtime.js";
+import { resumeRunnableHook } from "#execution/session-inbox/owner.js";
import { z } from "#compiled/zod/index.js";
import type { RouteContext } from "#public/definitions/channel.js";
import type { RuntimeSubagentChildResult } from "#shared/action-types.js";
@@ -182,7 +182,7 @@ export async function handleSessionCallbackRequest(
if (result instanceof Response) return result;
try {
- await resumeHook(
+ await resumeRunnableHook(
token,
forwarded?.success ? forwarded.data : { kind: "runtime-action-result", results: [result] },
);