The Open Framework for Building Agents
fix(eve): client - correlate resumed sends with accepted messages (#3096)
Andrew Barbae5d8e7b11d0d
diff --git a/.changeset/correlate-resumed-session-results.md b/.changeset/correlate-resumed-session-results.mdnew file mode 100644index 000000000..8e4b8bc27--- /dev/null+++ b/.changeset/correlate-resumed-session-results.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Match each client `send()` response to the message accepted by the server. Resuming a session with an old stream cursor now skips earlier turns instead of returning an old result.diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.mdindex 18783693f..75df34661 100644--- a/docs/concepts/sessions-runs-and-streaming.md+++ b/docs/concepts/sessions-runs-and-streaming.md@@ -119,6 +119,10 @@ Alongside `type` and `data`, every event carries a `meta` envelope:- **`meta.id`** uniquely identifies the event. It is an `evt_`-prefixed [ULID](https://github.com/ulid/spec): a millisecond timestamp followed by random bits, so ids are broadly time-ordered.- **`meta.at`** is the ISO-8601 time the event was emitted.+- **`meta.deliveryIds`**, when present, identifies the accepted messages that own+ the turn. `POST /eve/v1/session/:sessionId` returns its `deliveryId`, allowing+ clients to skip earlier turns when resuming from an old cursor. Coalesced+ messages share the same turn events.`meta.id` is stable. eve mints it once, when the event is written to the durable stream, and stores it with the event. Reconnecting from a cursor, rewinding to `startIndex=0`, or replaying a finished session all return the same id for the same event.diff --git a/docs/guides/client/continuations.mdx b/docs/guides/client/continuations.mdxindex 8859c67ab..66bb395ed 100644--- a/docs/guides/client/continuations.mdx+++ b/docs/guides/client/continuations.mdx@@ -52,6 +52,17 @@ console.log((await response.result()).message);`attach()` performs no request. Every later operation targets exactly`saved.sessionId`; it never follows or creates a replacement.+`send()` correlates its response with the message accepted by the server. If the+saved cursor is behind, it skips earlier turns and advances past them before+collecting the new result, including when another turn is active or queued. You+do not need to drain the stream before sending. Upgrade the server alongside the+client: a server that omits the accepted delivery identity causes `send()` to+throw instead of returning an ambiguous result.++If a configured reconnect limit ends the stream before the accepted turn reaches+a boundary, collecting its response throws. A partial stream is not a completed+result.+## Waiting, completed, and reset sessionsA session that emits `session.waiting` accepts another message through the samediff --git a/e2e/fixtures/agent-basic-runtime/evals/runtime/stale-client-cursor.eval.ts b/e2e/fixtures/agent-basic-runtime/evals/runtime/stale-client-cursor.eval.tsnew file mode 100644index 000000000..8634ec117--- /dev/null+++ b/e2e/fixtures/agent-basic-runtime/evals/runtime/stale-client-cursor.eval.ts@@ -0,0 +1,21 @@+import { defineEval } from "eve/evals";++export default defineEval({+ description: "A resumed client skips old turns when collecting a newly accepted message.",+ async test(t) {+ const original = t.newSession();+ (await original.send("Reply with first-report-ready.")).expectOk();+ (await original.send("Reply with second-report-ready.")).expectOk();+ const sessionId = original.state?.sessionId;+ if (sessionId === undefined) throw new Error("Expected a started session.");++ // Attachment reads the first boundary, leaving the second turn behind its cursor.+ const resumed = await t.target.attachSession(sessionId, { startIndex: 0 });+ const message = "Reply with current-report-ready.";+ const current = await resumed.send(message);+ current.expectOk();+ current.event("message.received", { count: 1, data: { message } });+ current.event("turn.started", { count: 1, data: { sequence: 2 } });+ current.event("session.waiting", { count: 1 });+ },+});diff --git a/packages/eve/extension-contracts/compatibility/channel/v17.ts b/packages/eve/extension-contracts/compatibility/channel/v17.tsnew file mode 100644index 000000000..9657836a3--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/channel/v17.ts@@ -0,0 +1,10 @@+import { defineChannel, POST } from "#public/channels/index.js";++export default defineChannel({+ routes: [+ POST("/continue/:sessionId", async (_request, { attachSession, params }) => {+ const result = await attachSession(params.sessionId!).send("Continue.", { auth: null });+ return Response.json({ accepted: result.status === "accepted" });+ }),+ ],+});diff --git a/packages/eve/extension-contracts/compatibility/hook/v20.ts b/packages/eve/extension-contracts/compatibility/hook/v20.tsnew file mode 100644index 000000000..0c142b202--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/hook/v20.ts@@ -0,0 +1,9 @@+import { defineHook } from "#public/hooks/index.js";++export default defineHook({+ events: {+ "turn.started"(event, ctx) {+ console.info(event.meta.id, event.data.turnId, ctx.session.id);+ },+ },+});diff --git a/packages/eve/extension-contracts/compatibility/schedule/v9.ts b/packages/eve/extension-contracts/compatibility/schedule/v9.tsnew file mode 100644index 000000000..639fc8dd7--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/schedule/v9.ts@@ -0,0 +1,8 @@+import { defineSchedule } from "#public/schedules/index.js";++export default defineSchedule({+ cron: "0 9 * * *",+ run({ waitUntil, appAuth }) {+ waitUntil(Promise.resolve(appAuth.principalId));+ },+});diff --git a/packages/eve/extension-contracts/reports/channel/v18.json b/packages/eve/extension-contracts/reports/channel/v18.jsonnew file mode 100644index 000000000..887df06cc--- /dev/null+++ b/packages/eve/extension-contracts/reports/channel/v18.json@@ -0,0 +1,21 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "channel",+ "epoch": 18,+ "sha256": "5e25691aa6b46db999a54fdf9f232b7585830f2ba859f2a0ab8ef2064dd24cae",+ "exports": [+ "DELETE",+ "GET",+ "HEAD",+ "OPTIONS",+ "PATCH",+ "POST",+ "PUT",+ "WS",+ "createWebSocketUpgradeServer",+ "defineChannel",+ "disableRoute",+ "isChannel",+ "isDisabledRouteSentinel"+ ]+}diff --git a/packages/eve/extension-contracts/reports/hook/v21.json b/packages/eve/extension-contracts/reports/hook/v21.jsonnew file mode 100644index 000000000..c419fa9fb--- /dev/null+++ b/packages/eve/extension-contracts/reports/hook/v21.json@@ -0,0 +1,7 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "hook",+ "epoch": 21,+ "sha256": "5b019f59f96b3067a1bda66a489d0d2eb1ebcc204c3736b6556b2c822d41dd46",+ "exports": ["defineHook"]+}diff --git a/packages/eve/extension-contracts/reports/schedule/v10.json b/packages/eve/extension-contracts/reports/schedule/v10.jsonnew file mode 100644index 000000000..85fd21574--- /dev/null+++ b/packages/eve/extension-contracts/reports/schedule/v10.json@@ -0,0 +1,14 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "schedule",+ "epoch": 10,+ "sha256": "75dca48d581945d42020a21769529b5480f6957c17a82d377a31292f64e3c752",+ "exports": [+ "ScheduleDefinition",+ "ScheduleHandlerArgs",+ "ScheduleRunHandler",+ "ScheduleToFn",+ "TypedReceiveTarget",+ "defineSchedule"+ ]+}diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.tsindex cca4a3e8a..877bf9186 100644--- a/packages/eve/src/channel/types.ts+++ b/packages/eve/src/channel/types.ts@@ -228,7 +228,7 @@ export type SessionCommand =| { readonly kind: "reset"; readonly reason?: string };export type SessionSendCommandResult =- | { readonly status: "accepted"; readonly sessionId: string }+ | { readonly status: "accepted"; readonly sessionId: string; readonly deliveryId?: string }| { readonly status: "session_not_active" };/** Result of terminally resetting a session. */diff --git a/packages/eve/src/cli/dev/tui/runner.test.ts b/packages/eve/src/cli/dev/tui/runner.test.tsindex 87ad07e61..0022cab84 100644--- a/packages/eve/src/cli/dev/tui/runner.test.ts+++ b/packages/eve/src/cli/dev/tui/runner.test.ts@@ -1286,6 +1286,7 @@ describe("EveTUIRunner development session continuity", () => {const encoder = new TextEncoder();let nextRevision = 0;let nextSession = 0;+ let nextDelivery = 0;vi.stubGlobal("fetch",vi.fn(async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {@@ -1306,7 +1307,7 @@ describe("EveTUIRunner development session continuity", () => {url.pathname === "/eve/v1/session"? `session-${String(++nextSession)}`: (url.pathname.split("/")[4] ?? `session-${String(++nextSession)}`);- return Response.json({ sessionId });+ return Response.json({ sessionId, deliveryId: `delivery-${++nextDelivery}` });}return new Response(@@ -1314,12 +1315,17 @@ describe("EveTUIRunner development session continuity", () => {start(controller) {controller.enqueue(encoder.encode(- `${JSON.stringify(- stampTestEvent({+ `${JSON.stringify({+ ...stampTestEvent({type: "session.waiting",data: { continuationToken: "session-id", wait: "next-user-message" },} as UnstampedMessageStreamEvent),- )}\n`,+ meta: {+ at: new Date().toISOString(),+ id: `event-${nextDelivery}`,+ deliveryIds: [`delivery-${nextDelivery}`],+ },+ })}\n`,),);controller.close();diff --git a/packages/eve/src/client/eve-agent-store.test.ts b/packages/eve/src/client/eve-agent-store.test.tsindex 9eadaa814..cc24ccdfd 100644--- a/packages/eve/src/client/eve-agent-store.test.ts+++ b/packages/eve/src/client/eve-agent-store.test.ts@@ -66,10 +66,18 @@ function streamingTurnEvents(): MessageStreamEvent[] {}function startedResponse(): Response {- return new Response(JSON.stringify({ ok: true, sessionId: "session_1", status: "accepted" }), {- headers: { "content-type": "application/json", [EVE_SESSION_ID_HEADER]: "session_1" },- status: 202,- });+ return new Response(+ JSON.stringify({+ ok: true,+ sessionId: "session_1",+ status: "accepted",+ deliveryId: "delivery_1",+ }),+ {+ headers: { "content-type": "application/json", [EVE_SESSION_ID_HEADER]: "session_1" },+ status: 202,+ },+ );}function versionedStreamResponse<Version extends MessageStreamVersion>(@@ -840,7 +848,10 @@ describe("EveAgentStore steering", () => {turnId: "turn_2",}),createSessionWaitingEvent(),- ] as UnstampedMessageStreamEvent[]);+ ] as UnstampedMessageStreamEvent[]).map((event, index) => ({+ ...event,+ meta: { ...event.meta, deliveryIds: [index < 4 ? "first-delivery" : "delivery_1"] },+ }));const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(startedResponse())diff --git a/packages/eve/src/client/session-correlation-reconnect.test.ts b/packages/eve/src/client/session-correlation-reconnect.test.tsnew file mode 100644index 000000000..5c287157d--- /dev/null+++ b/packages/eve/src/client/session-correlation-reconnect.test.ts@@ -0,0 +1,121 @@+import { afterEach, describe, expect, it, vi } from "vitest";++import { ClientSession } from "#client/session.js";+import { EVE_MESSAGE_STREAM_VERSION, EVE_STREAM_VERSION_HEADER } from "#protocol/message.js";++afterEach(() => vi.restoreAllMocks());++function turn(sequence: number, message: string, deliveryId: string) {+ const data = { sequence, turnId: `turn_${sequence}` };+ return [+ { type: "turn.started", data },+ { type: "message.completed", data: { ...data, message, finishReason: "stop" } },+ { type: "turn.completed", data },+ { type: "session.waiting" },+ ].map((event, index) => ({+ ...event,+ meta: {+ id: `event_${sequence}_${index}`,+ at: new Date().toISOString(),+ deliveryIds: [deliveryId],+ },+ }));+}+function stream(events: readonly unknown[]) {+ return new Response(events.map((event) => JSON.stringify(event)).join("\n") + "\n", {+ headers: { [EVE_STREAM_VERSION_HEADER]: EVE_MESSAGE_STREAM_VERSION },+ });+}+function accepted(deliveryId = "new") {+ return Response.json({ sessionId: "session_1", deliveryId }, { status: 202 });+}+function session(+ resolveHeaders = async (_headers?: Readonly<Record<string, string>>) => new Headers(),+) {+ return new ClientSession(+ { host: "https://eve.test", resolveHeaders },+ { sessionId: "session_1", streamIndex: 0 },+ );+}++describe("delivery correlation across reconnects and concurrent sends", () => {+ it("reconnects past only old history with the same headers and advances all consumed events", async () => {+ const controller = new AbortController();+ const resolveHeaders = vi.fn(+ async (headers?: Readonly<Record<string, string>>) => new Headers(headers),+ );+ const fetch = vi+ .spyOn(globalThis, "fetch")+ .mockResolvedValueOnce(accepted())+ .mockResolvedValueOnce(stream(turn(0, "OLD", "old")))+ .mockResolvedValueOnce(stream(turn(1, "NEW", "new")));+ const resumed = session(resolveHeaders);+ const result = await (+ await resumed.send("new", {+ headers: { authorization: "Bearer fixture" },+ signal: controller.signal,+ streamReconnectPolicy: {+ streamIdleReconnectPolicy: { baseDelayMs: 1, maxDelayMs: 1, maxAttempts: 2 },+ },+ })+ ).result();+ expect(result.message).toBe("NEW");+ expect(resumed.state.streamIndex).toBe(8);+ expect(String(fetch.mock.calls[2]?.[0])).toContain("startIndex=4");+ expect(resolveHeaders).toHaveBeenCalledTimes(3);+ expect(+ resolveHeaders.mock.calls.every(([headers]) => headers?.authorization === "Bearer fixture"),+ ).toBe(true);+ });++ it("does not report success when a bounded reconnect policy ends before the accepted delivery", async () => {+ vi.spyOn(globalThis, "fetch")+ .mockResolvedValueOnce(accepted())+ .mockResolvedValueOnce(stream(turn(0, "OLD", "old")));+ const response = await session().send("new", { streamReconnectPolicy: { reconnect: false } });+ await expect(response.result()).rejects.toThrow();+ });++ it("does not ignore a session-wide failure after observing the accepted turn", async () => {+ const current = turn(1, "PARTIAL", "new");+ vi.spyOn(globalThis, "fetch")+ .mockResolvedValueOnce(accepted())+ .mockResolvedValueOnce(+ stream([+ current[0],+ current[1],+ {+ type: "session.failed",+ data: { code: "FAILED", message: "Session ended" },+ meta: { id: "failed", at: new Date().toISOString(), deliveryIds: ["other"] },+ },+ ]),+ );+ const response = await session().send("new", { streamReconnectPolicy: { reconnect: false } });+ const result = await response.result();+ expect(result.status).toBe("failed");+ expect(result.events.at(-1)?.type).toBe("session.failed");+ });++ it("does not regress the cursor when concurrent sends are consumed out of order", async () => {+ const events = [...turn(1, "FIRST", "first"), ...turn(2, "SECOND", "second")];+ vi.spyOn(globalThis, "fetch")+ .mockResolvedValueOnce(accepted("first"))+ .mockResolvedValueOnce(accepted("second"))+ .mockResolvedValueOnce(stream(events))+ .mockResolvedValueOnce(stream(events));+ const resumed = session();+ const first = await resumed.send("first");+ const second = await resumed.send("second");+ expect((await second.result()).message).toBe("SECOND");+ expect((await first.result()).message).toBe("FIRST");+ expect(resumed.state.streamIndex).toBe(8);+ });++ it("preserves the saved cursor when posting the new request fails", async () => {+ vi.spyOn(globalThis, "fetch").mockRejectedValueOnce(new TypeError("network failed"));+ const resumed = session();+ await expect(resumed.send("new")).rejects.toThrow("network failed");+ expect(resumed.state.streamIndex).toBe(0);+ });+});diff --git a/packages/eve/src/client/session-correlation.test.ts b/packages/eve/src/client/session-correlation.test.tsnew file mode 100644index 000000000..52608b995--- /dev/null+++ b/packages/eve/src/client/session-correlation.test.ts@@ -0,0 +1,99 @@+import { afterEach, describe, expect, it, vi } from "vitest";++import { ClientSession } from "#client/session.js";+import { EVE_MESSAGE_STREAM_VERSION, EVE_STREAM_VERSION_HEADER } from "#protocol/message.js";++afterEach(() => vi.restoreAllMocks());++function turn(sequence: number, message: string, deliveryIds: string[]) {+ const data = { sequence, stepIndex: 0, turnId: `turn_${sequence}` };+ const meta = { at: new Date().toISOString(), id: `event_${sequence}`, deliveryIds };+ return [+ { type: "turn.started", data, meta },+ { type: "message.completed", data: { ...data, message, finishReason: "stop" }, meta },+ { type: "turn.completed", data, meta },+ { type: "session.waiting", meta },+ ];+}++function stream(events: readonly unknown[]) {+ return new Response(events.map((event) => JSON.stringify(event)).join("\n") + "\n", {+ headers: { [EVE_STREAM_VERSION_HEADER]: EVE_MESSAGE_STREAM_VERSION },+ });+}++function session() {+ return new ClientSession(+ { host: "https://eve.test", resolveHeaders: async () => new Headers() },+ { sessionId: "session_1", streamIndex: 0 },+ );+}++function accepted(deliveryId = "new-delivery") {+ return Response.json({ sessionId: "session_1", deliveryId }, { status: 202 });+}++describe("accepted message correlation", () => {+ it.each(["steer", "queue"] as const)(+ "skips completed and in-flight older turns for a %s send from a stale cursor",+ async (turnPolicy) => {+ const events = [+ ...turn(0, "OLD REPORT", ["old-delivery"]),+ ...turn(1, "IN FLIGHT REPORT", ["in-flight-delivery"]),+ ...turn(2, "NEW REPORT", ["new-delivery"]),+ ];+ vi.spyOn(globalThis, "fetch")+ .mockResolvedValueOnce(accepted())+ .mockResolvedValueOnce(stream(events));+ const resumed = session();+ const result = await (await resumed.send("new report", { turnPolicy })).result();+ expect(result.message).toBe("NEW REPORT");+ expect(result.events).toHaveLength(4);+ expect(resumed.state.streamIndex).toBe(events.length);+ },+ );++ it("accepts a delivery coalesced with another message", async () => {+ vi.spyOn(globalThis, "fetch")+ .mockResolvedValueOnce(accepted())+ .mockResolvedValueOnce(stream(turn(2, "COALESCED REPORT", ["other", "new-delivery"])));+ expect((await (await session().send("new report")).result()).message).toBe("COALESCED REPORT");+ });++ it("ignores an older delivery replayed after the accepted turn starts", async () => {+ const current = turn(2, "NEW REPORT", ["new-delivery"]);+ vi.spyOn(globalThis, "fetch")+ .mockResolvedValueOnce(accepted())+ .mockResolvedValueOnce(+ stream([+ current[0],+ ...turn(1, "REPLAYED OLD REPORT", ["old-delivery"]),+ ...current.slice(1),+ ]),+ );+ const result = await (await session().send("new report")).result();+ expect(result.message).toBe("NEW REPORT");+ expect(result.events).toHaveLength(4);+ });++ it("fails explicitly when the server does not identify the accepted message", async () => {+ vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(+ Response.json({ sessionId: "session_1" }, { status: 202 }),+ );+ await expect(session().send("new report")).rejects.toThrow("delivery id");+ });++ it("does not return a successful old result if the session terminates before delivery", async () => {+ vi.spyOn(globalThis, "fetch")+ .mockResolvedValueOnce(accepted())+ .mockResolvedValueOnce(+ stream([+ ...turn(0, "OLD REPORT", ["old-delivery"]),+ { type: "session.failed", data: { code: "FAILED", message: "Session failed." } },+ ]),+ );+ await expect((await session().send("new report")).result()).rejects.toThrow(+ "before the accepted message",+ );+ });+});diff --git a/packages/eve/src/client/session.test.ts b/packages/eve/src/client/session.test.tsindex 9088f319d..578b54af1 100644--- a/packages/eve/src/client/session.test.ts+++ b/packages/eve/src/client/session.test.ts@@ -52,6 +52,7 @@ function createAcceptedResponse() {{ok: true,sessionId: "session_1",+ deliveryId: "delivery_1",},{ status: 202 },);@@ -74,7 +75,11 @@ function createStreamResponse(events: readonly unknown[]) {new ReadableStream<Uint8Array>({start(controller) {for (const event of events) {- controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));+ controller.enqueue(+ encoder.encode(+ `${JSON.stringify({ ...(event as object), meta: { deliveryIds: ["delivery_1"] } })}\n`,+ ),+ );}controller.close();},@@ -642,6 +647,7 @@ describe("ClientSession", () => {encoder.encode(`${JSON.stringify({type: "session.waiting",+ meta: { deliveryIds: ["delivery_1"] },data: { continuationToken: "session-id", wait: "next-user-message" },})}\n`,),@@ -832,11 +838,13 @@ describe("ClientSession", () => {const session = createSession();const eventTypes: string[] = [];- for await (const event of await session.send("first", {- streamReconnectPolicy: { reconnect: false },- })) {- eventTypes.push(event.type);- }+ await expect(async () => {+ for await (const event of await session.send("first", {+ streamReconnectPolicy: { reconnect: false },+ })) {+ eventTypes.push(event.type);+ }+ }).rejects.toThrow("before the accepted message");expect(eventTypes).toEqual(["turn.started"]);expect(fetchMock).toHaveBeenCalledTimes(2);@@ -947,7 +955,9 @@ describe("ClientSession", () => {if (!emitted) {emitted = true;controller.enqueue(- encoder.encode(`${JSON.stringify({ type: "turn.started", data: {} })}\n`),+ encoder.encode(+ `${JSON.stringify({ type: "turn.started", data: {}, meta: { deliveryIds: ["delivery_1"] } })}\n`,+ ),);return;}@@ -1005,7 +1015,9 @@ describe("ClientSession", () => {if (!emitted) {emitted = true;controller.enqueue(- encoder.encode(`${JSON.stringify({ type: "turn.started", data: {} })}\n`),+ encoder.encode(+ `${JSON.stringify({ type: "turn.started", data: {}, meta: { deliveryIds: ["delivery_1"] } })}\n`,+ ),);return;}@@ -1136,14 +1148,14 @@ describe("ClientSession", () => {vi.useFakeTimers();try {- const eventTypes = await collectEventTypes(- await session.send("first", {- streamReconnectPolicy: {- streamIdleReconnectPolicy: { baseDelayMs: 10, maxAttempts: 2 },- },- }),- );- expect(eventTypes).toEqual([]);+ const response = await session.send("first", {+ streamReconnectPolicy: {+ streamIdleReconnectPolicy: { baseDelayMs: 10, maxAttempts: 2 },+ },+ });+ const assertion = expect(response.result()).rejects.toThrow("before the accepted message");+ await vi.runAllTimersAsync();+ await assertion;} finally {vi.useRealTimers();}@@ -1164,7 +1176,9 @@ describe("ClientSession", () => {new ReadableStream<Uint8Array>({start(controller) {controller.enqueue(- encoder.encode(`${JSON.stringify({ type: "turn.started", data: {} })}\n`),+ encoder.encode(+ `${JSON.stringify({ type: "turn.started", data: {}, meta: { deliveryIds: ["delivery_1"] } })}\n`,+ ),);signal?.addEventListener("abort", () => {controller.error(new DOMException("The operation was aborted.", "AbortError"));diff --git a/packages/eve/src/client/session.ts b/packages/eve/src/client/session.tsindex b67960ce6..23f9c7577 100644--- a/packages/eve/src/client/session.ts+++ b/packages/eve/src/client/session.ts@@ -58,7 +58,7 @@ export class ClientSession {input: SendTurnInput<TOutput>,): Promise<{ readonly response: MessageResponse<TOutput>; readonly session: ClientSession }> {const response = await postTurn(context, EVE_SESSION_ROUTE_PATH, input, true);- const sessionId = await readSessionId(response);+ const { sessionId } = await readAcceptedMessage(response);const session = new ClientSession(context, { sessionId, streamIndex: 0 });return {@@ -120,11 +120,24 @@ export class ClientSession {const response = retrySessionNotActive? await postSessionSend(this.#context, path, input): await postTurn(this.#context, path, input, false);- const responseSessionId = await readSessionId(response, this.#state.sessionId);+ const { sessionId: responseSessionId, deliveryId } = await readAcceptedMessage(+ response,+ this.#state.sessionId,+ );if (responseSessionId !== this.#state.sessionId) {throw new Error("Message route returned a different session id.");}- return this.#messageResponse<TOutput>(response, input, initialStreamIndex);+ if (input.message !== undefined && deliveryId === undefined) {+ throw new Error(+ "Message route did not return a delivery id. Update the server before sending with this client.",+ );+ }+ return this.#messageResponse<TOutput>(+ response,+ input,+ initialStreamIndex,+ input.message === undefined ? undefined : deliveryId,+ );}/** Requests cooperative cancellation of this session's active turn and optionally its tasks. */@@ -176,11 +189,12 @@ export class ClientSession {response: Response,input: SendTurnPayload,initialStreamIndex: number,+ deliveryId?: string,): MessageResponse<TOutput> {response.body?.cancel().catch(() => {});return new MessageResponse<TOutput>({cancelTurn: async (turnId) => await this.cancel({ turnId }),- createStream: () => this.#createEventStream(initialStreamIndex, input),+ createStream: () => this.#createEventStream(initialStreamIndex, input, deliveryId),sessionId: this.#state.sessionId,});}@@ -188,8 +202,11 @@ export class ClientSession {async *#createEventStream(initialStreamIndex: number,input: SendTurnPayload,+ deliveryId?: string,): AsyncGenerator<MessageStreamEvent> {let eventCount = 0;+ let started = deliveryId === undefined;+ let reachedBoundary = false;const pendingAuthorizations = new Set<string>();try {for await (const event of this.#readStream({@@ -200,23 +217,40 @@ export class ClientSession {streamReconnectPolicy: input.streamReconnectPolicy,})) {eventCount += 1;+ if (deliveryId !== undefined) {+ const matches = event.meta?.deliveryIds?.includes(deliveryId) === true;+ const terminal = event.type === "session.failed" || event.type === "session.completed";+ if (!matches && terminal && (!started || event.type === "session.completed")) {+ throw new Error(+ "The session ended before the accepted message reached its turn boundary.",+ );+ }+ if (!started && !matches) continue;+ if (!terminal && event.meta?.deliveryIds !== undefined && !matches) continue;+ started = true;+ }if (event.type === "authorization.required" && event.data.webhookUrl !== undefined) {pendingAuthorizations.add(event.data.name);} else if (event.type === "authorization.completed") {pendingAuthorizations.delete(event.data.name);}- yield event;- if (+ reachedBoundary =isCurrentTurnBoundaryEvent(event) &&- (event.type !== "session.waiting" || pendingAuthorizations.size === 0)- ) {+ (event.type !== "session.waiting" || pendingAuthorizations.size === 0);+ yield event;+ if (reachedBoundary) {break;}}+ if (deliveryId !== undefined && !reachedBoundary && !input.signal?.aborted) {+ throw new Error(+ "The response stream ended before the accepted message reached its turn boundary.",+ );+ }} finally {this.#state = {sessionId: this.#state.sessionId,- streamIndex: initialStreamIndex + eventCount,+ streamIndex: Math.max(this.#state.streamIndex, initialStreamIndex + eventCount),};}}@@ -330,14 +364,26 @@ async function postTurn(return response;}-async function readSessionId(response: Response, expected?: string): Promise<string> {+async function readAcceptedMessage(+ response: Response,+ expected?: string,+): Promise<{+ readonly sessionId: string;+ readonly deliveryId?: string;+}> {const payload = (await response.json()) as Record<string, unknown>;const sessionId =(typeof payload.sessionId === "string" ? payload.sessionId : undefined) ??response.headers.get(EVE_SESSION_ID_HEADER)?.trim() ??expected;if (!sessionId) throw new Error("Message route did not return a session id.");- return sessionId;+ return {+ sessionId,+ deliveryId:+ typeof payload.deliveryId === "string" && payload.deliveryId.length > 0+ ? payload.deliveryId+ : undefined,+ };}function createMessageBody(diff --git a/packages/eve/src/client/sessions.test.ts b/packages/eve/src/client/sessions.test.tsindex 8788064fe..e03e2e448 100644--- a/packages/eve/src/client/sessions.test.ts+++ b/packages/eve/src/client/sessions.test.ts@@ -99,7 +99,7 @@ describe("Client.sessions", () => {const path = new URL(url).pathname;if (path === "/eve/v1/session/wrun_A") {return Response.json(- { ok: true, sessionId: "wrun_A", status: "accepted" },+ { ok: true, sessionId: "wrun_A", status: "accepted", deliveryId: "delivery_1" },{ status: 202 },);}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex a126e0edb..3d73e1c0c 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -54,15 +54,15 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},channel: {- current: 17,- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17],+ current: 18,+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18],dropped: {12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",},},schedule: {- current: 9,- supported: [1, 2, 3, 4, 6, 7, 8, 9],+ current: 10,+ supported: [1, 2, 3, 4, 6, 7, 8, 9, 10],dropped: {5: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",},@@ -85,8 +85,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},hook: {- current: 20,- supported: [10, 11, 12, 13, 14, 15, 17, 18, 19, 20],+ current: 21,+ supported: [10, 11, 12, 13, 14, 15, 17, 18, 19, 20, 21],dropped: {1: "Model identity moved from session.started runtime metadata to step.started call attribution.",2: "Model identity moved from session.started runtime metadata to step.started call attribution.",diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.tsindex e757d051a..4d23e9b3a 100644--- a/packages/eve/src/context/keys.ts+++ b/packages/eve/src/context/keys.ts@@ -89,6 +89,8 @@ export const LocalDevRequestKey = new ContextKey<LocalDevRequestProvenance>(/** Authored schedule whose dispatch created this session. */export const ScheduleIdKey = new ContextKey<string>("eve.scheduleId");export const ChannelDeliveryKey = new ContextKey<ChannelDeliveryMetadata>("eve.channelDelivery");+/** Accepted messages whose response owns the current turn's durable stream events. */+export const TurnDeliveryIdsKey = new ContextKey<readonly string[]>("eve.turnDeliveryIds");/** Task-reporting phase for the active root turn. */export const TurnTaskDeliveryKey = new ContextKey<"none" | "initiating" | "pending" | "settled">("eve.turnTaskDelivery",diff --git a/packages/eve/src/evals/runner/execute-task.test.ts b/packages/eve/src/evals/runner/execute-task.test.tsindex be0c66855..04f259ffb 100644--- a/packages/eve/src/evals/runner/execute-task.test.ts+++ b/packages/eve/src/evals/runner/execute-task.test.ts@@ -802,13 +802,16 @@ function createScriptedServer(} = {},) {const pendingTurns = [...turns];- const streamQueues = new Map<string, UnstampedMessageStreamEvent[][]>();+ const streamQueues = new Map<+ string,+ { events: readonly UnstampedMessageStreamEvent[]; deliveryId?: string }[]+ >();const posts: Array<{ body: unknown; method: string; url: string }> = [];const cancels: string[] = [];for (const stream of options.streams ?? []) {const queue = streamQueues.get(stream.sessionId) ?? [];- queue.push([...stream.events]);+ queue.push({ events: stream.events });streamQueues.set(stream.sessionId, queue);}@@ -840,36 +843,42 @@ function createScriptedServer(}posts.push({ body: JSON.parse(String(init?.body)), method, url });+ const deliveryId = `delivery_${posts.length}`;const queue = streamQueues.get(next.sessionId) ?? [];- queue.push([...next.events]);+ queue.push({ events: next.events, deliveryId });streamQueues.set(next.sessionId, queue);return Response.json({ok: true,sessionId: next.sessionId,+ deliveryId,},{ status: posts.length === 1 ? 202 : 200 },);}const sessionId = decodeURIComponent(new URL(url).pathname.split("/").at(-2) ?? "");- const events = streamQueues.get(sessionId)?.shift();- if (events === undefined) {+ const stream = streamQueues.get(sessionId)?.shift();+ if (stream === undefined) {return Response.json({ error: "No stream.", ok: false }, { status: 404 });}- return streamResponse(events);+ return streamResponse(stream.events, stream.deliveryId);},};}-function streamResponse(events: readonly UnstampedMessageStreamEvent[]): Response {+function streamResponse(+ events: readonly UnstampedMessageStreamEvent[],+ deliveryId?: string,+): Response {const encoder = new TextEncoder();return new Response(new ReadableStream<Uint8Array>({start(controller) {for (const event of stampTestEvents(events)) {+ if (deliveryId !== undefined) Object.assign(event.meta, { deliveryIds: [deliveryId] });controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));}controller.close();diff --git a/packages/eve/src/eve-channel/index.ts b/packages/eve/src/eve-channel/index.tsindex e5b41ab91..5b3f0f1c5 100644--- a/packages/eve/src/eve-channel/index.ts+++ b/packages/eve/src/eve-channel/index.ts@@ -358,7 +358,12 @@ export function eveChannel(input: EveChannelInput): EveChannel {}return Response.json(- { ok: true, sessionId: result.sessionId, status: "accepted" },+ {+ ok: true,+ sessionId: result.sessionId,+ status: "accepted",+ deliveryId: result.deliveryId,+ },{headers: {"cache-control": "no-store",diff --git a/packages/eve/src/execution/session-command-inbox.integration.test.ts b/packages/eve/src/execution/session-command-inbox.integration.test.tsindex 30e1415e8..be1e8ec43 100644--- a/packages/eve/src/execution/session-command-inbox.integration.test.ts+++ b/packages/eve/src/execution/session-command-inbox.integration.test.ts@@ -34,7 +34,11 @@ describe("session command inbox integration", () => {},continuationToken: token,}),- ).resolves.toEqual({ sessionId: run.runId, status: "accepted" });+ ).resolves.toEqual({+ sessionId: run.runId,+ status: "accepted",+ deliveryId: "legacy-delivery",+ });await expect(run.returnValue).resolves.toBe("legacy-compatible");} finally {const status = await run.status;@@ -65,7 +69,11 @@ describe("session command inbox integration", () => {},continuationToken: token,}),- ).resolves.toEqual({ sessionId: run.runId, status: "accepted" });+ ).resolves.toEqual({+ sessionId: run.runId,+ status: "accepted",+ deliveryId: "mid-cohort-delivery",+ });await expect(run.returnValue).resolves.toBe("mid-cohort-compatible");} finally {const status = await run.status;diff --git a/packages/eve/src/execution/settle-cancelled-turn-step.ts b/packages/eve/src/execution/settle-cancelled-turn-step.tsindex ede5572c8..da4adf0b4 100644--- a/packages/eve/src/execution/settle-cancelled-turn-step.ts+++ b/packages/eve/src/execution/settle-cancelled-turn-step.ts@@ -1,6 +1,7 @@import { buildAdapterContext } from "#channel/adapter-context.js";import { callAdapterEventHandler } from "#channel/adapter.js";import { dispatchStreamEventHooks } from "#context/hook-lifecycle.js";+import { TurnDeliveryIdsKey } from "#context/keys.js";import { withContextScope } from "#context/run-step.js";import { deserializeContext, serializeContext } from "#context/serialize.js";import { setChannelContext } from "#execution/channel-context.js";@@ -104,7 +105,7 @@ export async function settleCancelledTurnStep(input: {const transformed = await callAdapterEventHandler(adapter, event, adapterCtx);setChannelContext(ctx, { ...adapter, state: { ...adapterCtx.state } });// Stamp once: the persisted chunk and the hooks must agree on the id.- const stamped = stampMessageStreamEvent(transformed);+ const stamped = stampMessageStreamEvent(transformed, ctx.get(TurnDeliveryIdsKey));await writer.write(encodeMessageStreamEvent(stamped));void observeSessionActivity({ ctx, event: stamped, sessionId: session.sessionId });await dispatchStreamEventHooks({diff --git a/packages/eve/src/execution/workflow-entry.integration.test.ts b/packages/eve/src/execution/workflow-entry.integration.test.tsindex 5c3ee3776..f02759124 100644--- a/packages/eve/src/execution/workflow-entry.integration.test.ts+++ b/packages/eve/src/execution/workflow-entry.integration.test.ts@@ -757,12 +757,19 @@ describe("workflowEntry integration", () => {},continuationToken,}),- ).resolves.toEqual({ sessionId: run.runId, status: "accepted" });+ ).resolves.toEqual({+ deliveryId: "delivery-followup",+ sessionId: run.runId,+ status: "accepted",+ });const secondTurn = await stream.nextTurn();expect(secondTurn.at(-1)?.type).toBe("session.waiting");expect(secondTurn.every((event) => typeof event.meta?.at === "string")).toBe(true);+ expect(+ secondTurn.every((event) => event.meta?.deliveryIds?.includes("delivery-followup")),+ ).toBe(true);expect(secondTurn.some((event) =>diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.tsindex 45f619f45..d642c6fe9 100644--- a/packages/eve/src/execution/workflow-runtime.test.ts+++ b/packages/eve/src/execution/workflow-runtime.test.ts@@ -213,6 +213,24 @@ describe("createWorkflowRuntime command dispatch", () => {expect(getHookByTokenMock).not.toHaveBeenCalled();});+ it("acknowledges the exact delivery accepted by the session inbox", async () => {+ resumeHookMock.mockResolvedValue({ runId: "session-1" });+ const delivery = { channelKind: "eve", channelName: "eve", deliveryId: "accepted-delivery" };+ const result = await buildRuntime().dispatchSession({+ command: { kind: "send", payload: { message: "hello" }, delivery },+ sessionId: "session-1",+ });+ expect(result).toEqual({+ sessionId: "session-1",+ status: "accepted",+ deliveryId: delivery.deliveryId,+ });+ expect(resumeHookMock).toHaveBeenCalledWith(+ sessionCommandHookToken("session-1"),+ expect.objectContaining({ delivery }),+ );+ });+it.each([{ command: { kind: "send" as const, payload: {} }, status: "session_not_active" },{ command: { kind: "compact" as const }, status: "no_active_session" },diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.tsindex 493017d0d..03b47463b 100644--- a/packages/eve/src/execution/workflow-runtime.ts+++ b/packages/eve/src/execution/workflow-runtime.ts@@ -369,8 +369,8 @@ function activeCommandResult<TCommand extends SessionCommand>(const result =command.kind === "reset"? { previousSessionId: sessionId, status: "reset" as const }- : command.kind === "cancel"- ? { sessionId, status: "accepted" as const }+ : command.kind === "send" && command.delivery !== undefined+ ? { sessionId, status: "accepted" as const, deliveryId: command.delivery.deliveryId }: { sessionId, status: "accepted" as const };return result as SessionCommandResult<TCommand>;}diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.tsindex 0acc51f1a..590de898f 100644--- a/packages/eve/src/execution/workflow-steps.test.ts+++ b/packages/eve/src/execution/workflow-steps.test.ts@@ -22,6 +22,7 @@ import {SessionDynamicToolRuntimeRevisionKey,SessionIdKey,SessionTraceSeedKey,+ TurnDeliveryIdsKey,TurnTaskDeliveryKey,TurnTaskStateKey,} from "#context/keys.js";@@ -1160,6 +1161,93 @@ describe("dispatchCoordinationStep", () => {});describe("turnStep", () => {+ it("retains coalesced delivery ownership across steps and replaces it for the next message", async () => {+ const session = createStubSession({+ state: {+ "eve.harness.emission": {+ sequence: 1,+ sessionStarted: true,+ stepIndex: 0,+ turnId: "turn_1",+ },+ },+ });+ installSessionStoreMocks([session]);+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue({+ adapterRegistry: {+ adaptersByKind: new Map([[threadContextAdapter.kind, threadContextAdapter]]),+ },+ compiledArtifactsSource: {},+ graph: {+ nodesByNodeId: new Map(),+ root: { sandboxRegistry: { sandbox: null }, turnAgent: TestTurnAgent },+ },+ moduleMap: { nodes: {} },+ hookRegistry: createEmptyHookRegistry(),+ resolvedAgent: { config: {} },+ subagentRegistry: {},+ toolRegistry: {},+ turnAgent: TestTurnAgent,+ } as never);+ vi.mocked(createExecutionNodeStep).mockImplementation((input) => async (stepSession) => {+ await input.handleEvent?.({+ type: "session.waiting",+ data: { continuationToken: "continuation_test", wait: "next-user-message" },+ });+ return { next: null, session: stepSession };+ });+ const delivery = (ids: string[]): Parameters<typeof turnStep>[0]["input"] => ({+ kind: "deliver",+ payloads: ids.map((message) => ({ message })),+ deliveryMetadata: ids.map((deliveryId, payloadIndex) => ({+ channelKind: "eve",+ channelName: "eve",+ deliveryId,+ payloadIndex,+ })),+ });++ const first = await turnStep({+ input: delivery(["delivery-a", "delivery-b"]),+ parentWritable: createTestWritable("first"),+ serializedContext: createSerializedContext(),+ sessionState: createStubSessionState(),+ });+ expect(first.serializedContext[TurnDeliveryIdsKey.name]).toEqual(["delivery-a", "delivery-b"]);+ const resumed = await turnStep({+ input: undefined,+ parentWritable: createTestWritable("resumed"),+ serializedContext: first.serializedContext,+ sessionState: first.sessionState,+ });+ expect(resumed.serializedContext[TurnDeliveryIdsKey.name]).toEqual([+ "delivery-a",+ "delivery-b",+ ]);+ const next = await turnStep({+ input: delivery(["delivery-c"]),+ parentWritable: createTestWritable("next"),+ serializedContext: resumed.serializedContext,+ sessionState: resumed.sessionState,+ });+ expect(next.serializedContext[TurnDeliveryIdsKey.name]).toEqual(["delivery-c"]);+ for (const [namespace, deliveryIds] of [+ ["first", ["delivery-a", "delivery-b"]],+ ["resumed", ["delivery-a", "delivery-b"]],+ ["next", ["delivery-c"]],+ ] as const) {+ const events = (workflowWritesByNamespace.get(namespace) ?? []).map((chunk) =>+ JSON.parse(new TextDecoder().decode(chunk as Uint8Array)),+ );+ expect(events).toEqual([+ expect.objectContaining({+ type: "session.waiting",+ meta: expect.objectContaining({ deliveryIds }),+ }),+ ]);+ }+ });+it("defers before mutation when an inline step reaches another deployment", async () => {vi.stubEnv("VERCEL_DEPLOYMENT_ID", "dpl_driver");const sessionState = createStubSessionState();@@ -1578,15 +1666,27 @@ describe("turnStep", () => {input: {kind: "deliver",payloads: [{ message: "cancel this turn" }],+ deliveryMetadata: [+ {+ channelKind: "eve",+ channelName: "eve",+ deliveryId: "cancelled-delivery",+ payloadIndex: 0,+ },+ ],},parentWritable: createTestWritable(),- serializedContext: createSerializedContext(),+ serializedContext: {+ ...createSerializedContext(),+ [TurnDeliveryIdsKey.name]: ["previous-delivery"],+ },sessionState: createStubSessionState(),});expect(result).toMatchObject({action: "cancelled",serializedContext: {+ [TurnDeliveryIdsKey.name]: ["cancelled-delivery"],[SessionDynamicModelReferenceKey.name]: {id: "anthropic/claude-opus-4.6",contextWindowTokens: 1_000_000,diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.tsindex da9ac49de..57a1fe0ce 100644--- a/packages/eve/src/execution/workflow-steps.ts+++ b/packages/eve/src/execution/workflow-steps.ts@@ -24,11 +24,13 @@ import { dispatchMemoryLifecycleEvent } from "#context/memory-event-lifecycle.jsimport {AuthKey,CapabilitiesKey,+ ChannelDeliveryKey,HandleEventKey,ModeKey,SessionDynamicSubagentRuntimeRevisionKey,SessionDynamicToolRuntimeRevisionKey,TurnTaskDeliveryKey,+ TurnDeliveryIdsKey,TurnTaskStateKey,} from "#context/keys.js";import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";@@ -197,6 +199,18 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu});const initialEmissionState = getHarnessEmissionState(initialSession.state);+ if (+ rawInput.input?.kind === "deliver" &&+ rawInput.input.payloads.some((payload) => payload.message !== undefined)+ ) {+ ctx.set(+ TurnDeliveryIdsKey,+ rawInput.input.deliveryMetadata?.map((entry) => entry.deliveryId) ?? [],+ );+ } else if (!initialEmissionState.sessionStarted && ctx.get(ChannelDeliveryKey) !== undefined) {+ ctx.set(TurnDeliveryIdsKey, [ctx.require(ChannelDeliveryKey).deliveryId]);+ }+if (rawInput.input?.kind === "deliver") {await contextStorage.run(ctx, () =>instrumentation?.instrumentChannelDelivery({@@ -372,7 +386,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResuconst emit = async (event: UnstampedMessageStreamEvent): Promise<MessageStreamEvent> => {const toEmit = await callAdapterEventHandler(adapter, event, adapterCtx);setChannelContext(ctx, { ...adapter, state: { ...adapterCtx.state } });- const stamped = stampMessageStreamEvent(toEmit);+ const stamped = stampMessageStreamEvent(toEmit, ctx.get(TurnDeliveryIdsKey));await writer.write(encodeMessageStreamEvent(stamped));return stamped;};@@ -385,7 +399,9 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu// the task callback and keep them out of the child's local channel;// otherwise two TUIs can present and answer the same request.const forwardedToTaskParent = await forwardTaskEventToSessionCallback(ctx, event);- const emitted = forwardedToTaskParent ? stampMessageStreamEvent(event) : await emit(event);+ const emitted = forwardedToTaskParent+ ? stampMessageStreamEvent(event, ctx.get(TurnDeliveryIdsKey))+ : await emit(event);const lifecycleMessages = await dispatchMemoryLifecycleEvent({abortSignal: input.abortSignal,appRoot: effectiveNode.agent?.metadata?.appRoot ?? "",@@ -571,7 +587,13 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu}),serializedContext: preserveSerializedInstrumentationState(preserveSerializedAgentTraceState(- preserveSerializedSessionDynamicModelSelection(input.serializedContext, interrupted),+ preserveSerializedSessionDynamicModelSelection(+ {+ ...input.serializedContext,+ [TurnDeliveryIdsKey.name]: interrupted[TurnDeliveryIdsKey.name],+ },+ interrupted,+ ),interrupted,),interrupted,diff --git a/packages/eve/src/protocol/message.ts b/packages/eve/src/protocol/message.tsindex fc45f348f..2de65998f 100644--- a/packages/eve/src/protocol/message.ts+++ b/packages/eve/src/protocol/message.ts@@ -61,6 +61,8 @@ export interface StepCompletedProviderMetadata {* or replaying a finished session — yields the same values every time.*/export interface MessageStreamEventMeta {+ /** Server-issued message delivery identities, retained across the turn's workflow steps. */+ readonly deliveryIds?: readonly string[];/** ISO-8601 emission time. */readonly at: string;/**@@ -1693,13 +1695,18 @@ export function createSessionCompletedEvent(): SessionCompletedStreamEvent {* One stamping seam is what makes the persisted stream and authored hooks* observe the same `meta.id`.*/-export function stampMessageStreamEvent(event: UnstampedMessageStreamEvent): MessageStreamEvent {+export function stampMessageStreamEvent(+ event: UnstampedMessageStreamEvent,+ deliveryIds?: readonly string[],+): MessageStreamEvent {+ const meta: { at: string; id: string; deliveryIds?: readonly string[] } = {+ at: new Date().toISOString(),+ id: createEventId(),+ };+ if (deliveryIds !== undefined && deliveryIds.length > 0) meta.deliveryIds = deliveryIds;return {...event,- meta: {- at: new Date().toISOString(),- id: createEventId(),- },+ meta,};}diff --git a/packages/eve/src/public/channels/eve.test.ts b/packages/eve/src/public/channels/eve.test.tsindex 35cfa0f36..b2977e443 100644--- a/packages/eve/src/public/channels/eve.test.ts+++ b/packages/eve/src/public/channels/eve.test.ts@@ -1559,6 +1559,24 @@ describe("eveChannel — uploadPolicy enforcement", () => {});describe("eveChannel — continue session HITL (inputResponses)", () => {+ it("returns the server-issued delivery id in an accepted message acknowledgement", async () => {+ const handler = createEveContinueHandler({ auth: none() });+ handler.send.mockResolvedValue({+ sessionId: "test-session-id",+ status: "accepted",+ deliveryId: "accepted-delivery",+ });+ const response = await handler.fetch(createJsonMessageRequest({ message: "follow-up" }));+ expect(response.status).toBe(202);+ expect(response.headers.get("x-eve-session-id")).toBe("test-session-id");+ await expect(response.json()).resolves.toEqual({+ ok: true,+ sessionId: "test-session-id",+ status: "accepted",+ deliveryId: "accepted-delivery",+ });+ });+it("returns a structured 500 when fixed-session delivery fails", async () => {const handler = createEveContinueHandler({ auth: none() });handler.send.mockRejectedValue(new Error("backing store outage"));diff --git a/packages/eve/src/services/dev-client.test.ts b/packages/eve/src/services/dev-client.test.tsindex e55c32aef..bd82d18fc 100644--- a/packages/eve/src/services/dev-client.test.ts+++ b/packages/eve/src/services/dev-client.test.ts@@ -259,6 +259,7 @@ function createDevFetchMock(input: {let nextRebuildIndex = 0;let nextRevisionIndex = 0;let nextSessionIndex = 0;+ let nextDeliveryIndex = 0;return vi.fn(async (request: Parameters<typeof fetch>[0], init?: RequestInit) => {const url = resolveRequestUrl(request);@@ -289,7 +290,7 @@ function createDevFetchMock(input: {pathname === "/eve/v1/session"? `session-${String(++nextSessionIndex)}`: (pathname.split("/")[4] ?? `session-${String(++nextSessionIndex)}`);- return Response.json({ sessionId });+ return Response.json({ sessionId, deliveryId: `delivery-${++nextDeliveryIndex}` });}return new Response(@@ -300,6 +301,11 @@ function createDevFetchMock(input: {`${JSON.stringify({data: { continuationToken: "session-id", wait: "next-user-message" },type: "session.waiting",+ meta: {+ at: new Date().toISOString(),+ id: `event-${nextDeliveryIndex}`,+ deliveryIds: [`delivery-${nextDeliveryIndex}`],+ },})}\n`,),);diff --git a/packages/eve/test/client.test.ts b/packages/eve/test/client.test.tsindex 39166862e..a796e8e46 100644--- a/packages/eve/test/client.test.ts+++ b/packages/eve/test/client.test.ts@@ -19,6 +19,7 @@ import {createSessionWaitingEvent,createTurnCompletedEvent,createTurnStartedEvent,+ stampMessageStreamEvent,type UnstampedMessageStreamEvent,} from "../src/protocol/message.js";import { createTestAgentInfoResult } from "../src/internal/testing/agent-info-fixture.js";@@ -27,10 +28,10 @@ import { createTestAgentInfoResult } from "../src/internal/testing/agent-info-fi// Helpers// ----------------------------------------------------------------------------function createControlledStreamResponse(): {+function createControlledStreamResponse(deliveryId = "delivery_turn_001"): {close(): void;error(error: Error): void;- pushEvent(event: unknown): void;+ pushEvent(event: UnstampedMessageStreamEvent): void;response: Response;} {const encoder = new TextEncoder();@@ -44,7 +45,9 @@ function createControlledStreamResponse(): {controller?.error(error);},pushEvent(event) {- controller?.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));+ controller?.enqueue(+ encoder.encode(`${JSON.stringify(stampMessageStreamEvent(event, [deliveryId]))}\n`),+ );},response: new Response(new ReadableStream<Uint8Array>({@@ -59,8 +62,11 @@ function createControlledStreamResponse(): {};}-function createStartedMessageResponse(sessionId: string): Response {- return new Response(JSON.stringify({ ok: true, sessionId }), {+function createStartedMessageResponse(+ sessionId: string,+ deliveryId = "delivery_turn_001",+): Response {+ return new Response(JSON.stringify({ ok: true, sessionId, deliveryId }), {headers: {"content-type": "application/json",[EVE_SESSION_ID_HEADER]: sessionId,@@ -69,21 +75,36 @@ function createStartedMessageResponse(sessionId: string): Response {});}-function createResumedMessageResponse(): Response {- return new Response(JSON.stringify({ ok: true }), {+function createResumedMessageResponse(deliveryId = "delivery_turn_002"): Response {+ return new Response(JSON.stringify({ ok: true, deliveryId }), {headers: { "content-type": "application/json" },status: 200,});}-function createEagerStreamResponse(events: readonly unknown[]): Response {+function createEagerStreamResponse(+ events: readonly UnstampedMessageStreamEvent[],+ deliveryId?: string,+): Response {+ let turnId = "turn_001";+ for (const event of events) {+ if ("data" in event && "turnId" in event.data) {+ turnId = event.data.turnId;+ break;+ }+ }+ const acceptedDeliveryId = deliveryId ?? `delivery_${turnId}`;const encoder = new TextEncoder();return new Response(new ReadableStream<Uint8Array>({start(controller) {for (const event of events) {- controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));+ controller.enqueue(+ encoder.encode(+ `${JSON.stringify(stampMessageStreamEvent(event, [acceptedDeliveryId]))}\n`,+ ),+ );}controller.close();},@@ -292,7 +313,7 @@ describe("Session.send (result)", () => {expect(result.message).toBe("Reply: Hello");expect(result.sessionId).toBe("session_001");expect(result.status).toBe("waiting");- expect(result.events).toEqual(events);+ expect(result.events.map(({ meta: _meta, ...event }) => event)).toEqual(events);});it("sends follow-up messages through the fixed session ID", async () => {@@ -307,8 +328,8 @@ describe("Session.send (result)", () => {.spyOn(globalThis, "fetch").mockResolvedValueOnce(createStartedMessageResponse("session_001")).mockResolvedValueOnce(createEagerStreamResponse(firstEvents))- .mockResolvedValueOnce(createResumedMessageResponse())- .mockResolvedValueOnce(createEagerStreamResponse(secondEvents));+ .mockResolvedValueOnce(createResumedMessageResponse("delivery_follow_up"))+ .mockResolvedValueOnce(createEagerStreamResponse(secondEvents, "delivery_follow_up"));const session = new Client({ host: "http://localhost:3000" }).sessions.attach("session_001");await (await session.send("Hello")).result();@@ -349,7 +370,7 @@ describe("Session.send (result)", () => {expect(result.status).toBe("failed");expect(result.message).toBeUndefined();- expect(result.events).toEqual(events);+ expect(result.events.map(({ meta: _meta, ...event }) => event)).toEqual(events);});it("returns status 'completed' when the session completes", async () => {@@ -443,8 +464,8 @@ describe("Session.send (result)", () => {.spyOn(globalThis, "fetch").mockResolvedValueOnce(createStartedMessageResponse("session_001")).mockResolvedValueOnce(createEagerStreamResponse(firstEvents))- .mockResolvedValueOnce(createResumedMessageResponse())- .mockResolvedValueOnce(createEagerStreamResponse(secondEvents));+ .mockResolvedValueOnce(createResumedMessageResponse("delivery_follow_up"))+ .mockResolvedValueOnce(createEagerStreamResponse(secondEvents, "delivery_follow_up"));const session = new Client({ host: "http://localhost:3000" }).sessions.attach("session_001");await (await session.send("Task")).result();@@ -480,7 +501,7 @@ describe("Session.send (stream)", () => {const session = new Client({ host: "http://localhost:3000" }).sessions.attach("session_001");const res = await session.send("Hello");- const collected: UnstampedMessageStreamEvent[] = [];+ const collected: MessageStreamEvent[] = [];const iterationPromise = (async () => {for await (const event of res) {@@ -673,9 +694,9 @@ describe("Session state", () => {});vi.spyOn(globalThis, "fetch")- .mockResolvedValueOnce(createStartedMessageResponse("session_a"))+ .mockResolvedValueOnce(createStartedMessageResponse("session_a", "delivery_turn_a")).mockResolvedValueOnce(createEagerStreamResponse(eventsA))- .mockResolvedValueOnce(createStartedMessageResponse("session_b"))+ .mockResolvedValueOnce(createStartedMessageResponse("session_b", "delivery_turn_b")).mockResolvedValueOnce(createEagerStreamResponse(eventsB));const client = new Client({ host: "http://localhost:3000" });@@ -746,7 +767,7 @@ describe("Session.stream", () => {const client = new Client({ host: "http://localhost:3000" });const session = client.sessions.attach("session_001", { streamIndex: 10 });- const collected: UnstampedMessageStreamEvent[] = [];+ const collected: MessageStreamEvent[] = [];for await (const event of session.stream()) {collected.push(event);// stream() follows the durable log across transport ends; the boundary@@ -756,7 +777,7 @@ describe("Session.stream", () => {}}- expect(collected).toEqual(events);+ expect(collected.map(({ meta: _meta, ...event }) => event)).toEqual(events);const url = String(fetchMock.mock.calls[0]?.[0]);expect(url).toContain("session_001/stream");expect(url).toContain("startIndex=10");diff --git a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.tsindex d6cc8fbed..bbfb38439 100644--- a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts+++ b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts@@ -249,7 +249,7 @@ describe("mounted extension installed under node_modules", () => {);expect(JSON.parse(extensionFiles[`node_modules/${PACKAGE_NAME}/dist/extension/_manifest.json`]!),- ).toMatchObject({ requires: { channel: 17, schedule: 9, subagent: 9 } });+ ).toMatchObject({ requires: { channel: 18, schedule: 10, subagent: 9 } });const app = await scenarioApp({name: "mounted-extension-installed",installDependencies: true,diff --git a/research/accepted-message-correlation.md b/research/accepted-message-correlation.mdnew file mode 100644index 000000000..c3272fd4b--- /dev/null+++ b/research/accepted-message-correlation.md@@ -0,0 +1,28 @@+---+issue: https://github.com/vercel/eve/issues/2461+status: implemented+last_updated: "2026-09-06"+---++# Accepted message correlation++A persisted client cursor may precede completed or active turns. Reading from+that cursor until the first waiting boundary can silently return an old result.+A tail refresh alone still races with an active or queued turn.++Keep the existing client authoring API. The session POST acknowledgement includes+the existing server-issued `deliveryId`; events for the accepted message carry+that identity in optional `meta.deliveryIds`. An array accounts for coalesced+messages. The runtime retains these identities across workflow steps and through+cancellation, replacing them when it applies new message input.++`ClientSession.send()` skips earlier deliveries before collecting its response.+The cursor still advances over skipped events. A missing acknowledgement identity+or a terminal session before the matching delivery is an explicit error. Initial+session creation and input-response routing retain their existing read behavior.++The additional metadata is compatible with persisted events: historical events+need no rewriting, and new messages acquire an identity when accepted. Upgrade+the server with the client; a client must not guess which message an older server+accepted. Event IDs continue to identify individual stored events, independently+of delivery identity.