Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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.mdx
index 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 sessions
A session that emits `session.waiting` accepts another message through the same
diff --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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.js
import {
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<DurableStepResu
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
new file mode 100644
index 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.