The Open Framework for Building Agents
fix(channels): deduplicate keyed deliveries at durable admission (#5104)
Chad Hietalaa9f5065bb1b3
diff --git a/.changeset/fresh-delivery-keys.md b/.changeset/fresh-delivery-keys.mdnew file mode 100644index 000000000..77a2d5340--- /dev/null+++ b/.changeset/fresh-delivery-keys.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Channel and session sends and responses now accept `idempotencyKey` to ignore retries across replay and owner handoffs. Photon supplies message IDs automatically; deduplication requires a shared Workflow World and only covers keys in the session's recent-key window.diff --git a/docs/channels/chat-sdk.mdx b/docs/channels/chat-sdk.mdxindex 2cd6b2aa0..27c09b0e2 100644--- a/docs/channels/chat-sdk.mdx+++ b/docs/channels/chat-sdk.mdx@@ -53,6 +53,11 @@ export default channel;`adapters` is a map of adapter name to adapter instance; each entry mounts its own webhook (see below). `state` takes any Chat SDK state adapter: `createMemoryState()` is fine for local development, but use a durable adapter (Redis, Upstash, etc.) in production so thread subscriptions and inbound deduplication survive restarts. `send` accepts a plain string or an AI SDK `UserContent` array, and must be called from inside a Chat SDK handler — it dispatches the turn on the webhook that is currently running.+Pass `idempotencyKey: message.id` to `send` to prevent duplicate agent input+within the session's [recent-key window](./custom#retried-deliveries). Chat SDK's+separate duplicate check can mark a message as seen before eve accepts it, so+a shared state adapter alone does not guarantee delivery.+Deploy once the channel file is in place:```bash@@ -104,7 +109,7 @@ bot.onNewMention(async (thread, message) => {});```-`options` accepts `thread` and `adapterName`, plus the channel send options `auth`, `context`, `outputSchema`, `title`, `callback`, and `turnPolicy`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn. `auth` defaults to `null`.+`options` accepts `thread` and `adapterName`, plus the channel send options `auth`, `context`, `outputSchema`, `title`, `callback`, `turnPolicy`, and `idempotencyKey`. `title` sets the eve session's display title without changing the model message; `auth` attaches an authenticated principal to the turn. `auth` defaults to `null`.To answer pending input requests from a handler you render yourself, call `respond(inputResponses, { thread, auth?, context? })`. Like a channel's `respond()`, it never creates a session. This example answers a custom button whose `value` carries the eve request id:diff --git a/docs/channels/custom.mdx b/docs/channels/custom.mdxindex 6f5a166d2..38e7fa132 100644--- a/docs/channels/custom.mdx+++ b/docs/channels/custom.mdx@@ -104,11 +104,11 @@ part of the authored channel API.## Channel operations and session handlesChannel operations are dynamic: every call targets whichever session currently-owns the address. Only `send()` can create a session when the address is unowned.-Cold-start sends return their accepted candidate without waiting for address-ownership. If simultaneous sends race, eve forwards the losing candidate's-message to the winner; resolve the address after startup when you need a fixed-handle to the canonical owner.+owns the address. `create()` and `send()` can create a session when the address is unowned.+Without an [idempotency key](#retried-deliveries), a new session's handle can+return before it claims the address. If another send wins the address, eve+forwards the message to that session. Call `resolveSession(address)` after+startup to get the winning session's handle.```tsconst source = from(threadId);@@ -206,6 +206,38 @@ Attaching does no lookup. The first operation reports whether the ID is active.Call `resolveSession(address)` only when you explicitly need to snapshot anaddress's current owner as a fixed handle.+## Retried deliveries++After verifying a webhook, pass its stable event ID as `idempotencyKey`. Reuse the key+when retrying a failed or timed-out send:++```ts+const session = await from(conversationId).send(message, {+ auth,+ idempotencyKey: providerEventId,+});+```++Channel and fixed-session `send()` and `respond()` calls accept this option,+as does the Chat SDK bridge. Keys must contain 1–256 characters and identify one+delivery. Prefix IDs with the provider or event type if they can overlap.+Reusing a retained key ignores the new input, even if the message changed.++Each session remembers its last 1,024 distinct keys. Retries do not extend+retention and can run again after eviction. Aliases share this window; replay+and owner handoffs preserve it. Other sessions have separate windows, including+those created after reset, expiration, or replacement. Replicas must share the+same durable Workflow World.++A known duplicate does not interrupt generation, call `deliver`, or start a+turn. A keyed send that creates a session waits up to 30 seconds for the winning+session's handle. Sends to existing sessions return after eve stores the+delivery, without waiting for a turn or reporting whether it was a duplicate.++Await `send()` before acknowledging a webhook when the provider allows it.+Acknowledging sooner can lose work. This does not make tool calls, outbound+posts, or work done before `send()` exactly once.+## Wrap an existing channel's routesA channel value can be spread into a new object with replaced `routes`. eve keeps the channel's adapter, events, and build metadata (such as the Slack app manifest) on the spread copy, so `{ ...channel, routes }` compiles and runs like the original.@@ -374,7 +406,7 @@ Before sending:- Verify the provider's signature and validate the payload, including size limits. Derive `event.source` from the verified sender, not an untrusted payload field.- Filter out events that should not reach the agent.-- Deduplicate retried events in your application if duplicates would cause unwanted sessions or posts. `send(...)` does not deduplicate them.+- Deduplicate retries in your application unless the destination's `receive` hook passes a [delivery key](#retried-deliveries) to `from(address).send()`.The supplied `auth` identifies who started the session, available to tools and event handlers as `session.auth.initiator`.diff --git a/docs/channels/photon.mdx b/docs/channels/photon.mdxindex 08c86d559..76023b784 100644--- a/docs/channels/photon.mdx+++ b/docs/channels/photon.mdx@@ -32,6 +32,10 @@ boundary. See [Overlapping messages](./overview#overlapping-messages).Set `turnPolicy: "queue"` when every response should finish before Photon starts the next message.+Photon uses inbound message IDs as [delivery idempotency keys](./custom#retried-deliveries).+Replicas that share a durable Workflow World ignore retries while the ID remains+in the session's recent-key window.+Images and other files people send reach the agent as file parts. Photon'swebhook lists each file without its bytes, so eve downloads it from Photon byits attachment id with the project's credentials. The webhook omits the iddiff --git a/docs/concepts/execution-model-and-durability.mdx b/docs/concepts/execution-model-and-durability.mdxindex d24423b2c..cb8255be4 100644--- a/docs/concepts/execution-model-and-durability.mdx+++ b/docs/concepts/execution-model-and-durability.mdx@@ -260,6 +260,12 @@ the returned handle. That identity lookup does not block workflow resumption.ID-addressed delivery already knows the session ID and needs no hook metadatalookup. An ambiguous delivery failure does not trigger session creation.+Pass a [delivery idempotency key](../channels/custom#retried-deliveries) to prevent+retried input from interrupting generation or starting another turn. Each session+remembers its last 1,024 distinct keys across replay and owner handoffs. Keyed+cold-start sends wait for the winning session's ID; sends without a key can+return a candidate ID before ownership is settled.+A handoff never leaves the session's addresses without an owner. The previousowner keeps every address until the new run takes all of them over, so adelivery during a handoff is accepted immediately and is never reported as andiff --git a/e2e/fixtures/agent-channels/agent/channels/target.ts b/e2e/fixtures/agent-channels/agent/channels/target.tsindex 163880caa..dfceb41d2 100644--- a/e2e/fixtures/agent-channels/agent/channels/target.ts+++ b/e2e/fixtures/agent-channels/agent/channels/target.ts@@ -11,7 +11,18 @@ export default defineChannel({? "private": "unknown";},- routes: [POST("/target", async () => new Response("ok"))],+ routes: [+ POST("/target", async () => new Response("ok")),+ POST("/deliveries/:conversationId", async (request, { from, params }) => {+ const body = (await request.json()) as { message: string; idempotencyKey?: string };+ const session = await from(params.conversationId).send(body.message, {+ auth: null,+ idempotencyKey: body.idempotencyKey,+ turnPolicy: "queue",+ });+ return Response.json({ sessionId: session.id });+ }),+ ],async receive(input, { from }) {const sessionRef =typeof input.target.sessionRef === "string" ? input.target.sessionRef : "default";diff --git a/e2e/fixtures/agent-channels/evals/custom-channels/delivery-idempotency.eval.ts b/e2e/fixtures/agent-channels/evals/custom-channels/delivery-idempotency.eval.tsnew file mode 100644index 000000000..106061d1b--- /dev/null+++ b/e2e/fixtures/agent-channels/evals/custom-channels/delivery-idempotency.eval.ts@@ -0,0 +1,62 @@+import { defineEval } from "eve/evals";+import { equals } from "eve/evals/expect";+import { postChannel } from "./shared";++export default defineEval({+ description: "Retries of a channel delivery keep one session and one copy of agent input.",+ async test(t) {+ const path = `/deliveries/${crypto.randomUUID()}`;+ const first = {+ message: "Alice opens a conversation about preparing a report. Acknowledge her request.",+ idempotencyKey: "alice-report",+ };+ const send = (body: { message: string; idempotencyKey?: string }) =>+ postChannel<{ sessionId: string }>(t.target, path, body);+ const [accepted, retry] = await Promise.all([send(first), send(first)]);+ await t.require(retry.sessionId, equals(accepted.sessionId));+ const initial = await t.target.watchTurn(accepted.sessionId).result();+ initial.succeeded();++ const next = t.target.watchTurn(accepted.sessionId, { startIndex: initial.events.length });+ const followup = {+ message: "Bob joins Alice and asks for a brief outline of the report.",+ idempotencyKey: "bob-outline",+ };+ await Promise.all([send(first), send(followup), send(followup)]);+ const reply = await next.result();+ reply.succeeded();+ await t.require(+ reply.events+ .filter((event) => event.type === "message.received")+ .map((event) => event.data.message),+ equals([followup.message]),+ );++ const barrier = t.target.watchTurn(accepted.sessionId, {+ startIndex: initial.events.length + reply.events.length,+ });+ const sentinel = {+ message:+ "Alice and Bob finish reviewing the outline. Acknowledge that the review is complete.",+ };+ await send(sentinel);+ const drained = await barrier.result();+ drained.succeeded();+ await t.require(+ drained.events+ .filter((event) => event.type === "message.received")+ .map((event) => event.data.message),+ equals([sentinel.message]),+ );+ const response = await t.target.fetch(+ `/eve/v1/session/${accepted.sessionId}/stream?follow=false`,+ );+ await t.require(response.status, equals(200));+ const events = (await response.text())+ .trim()+ .split("\n")+ .filter(Boolean)+ .map((line) => JSON.parse(line) as { type: string });+ await t.require(events.filter((event) => event.type === "turn.started").length, equals(3));+ },+});diff --git a/packages/eve/extension-contracts/compatibility/channel/v63.ts b/packages/eve/extension-contracts/compatibility/channel/v63.tsnew file mode 100644index 000000000..4ba75d5f0--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/channel/v63.ts@@ -0,0 +1,14 @@+import { defineChannel, POST } from "#public/channels/index.js";++export default defineChannel({+ routes: [+ POST("/reports", async (_request, { from }) => {+ const { session } = await from("reports").create({+ auth: null,+ history: [{ role: "user", text: "Alice requested a report." }],+ });+ await session.send("Include Bob's notes.", { auth: null });+ return Response.json({ sessionId: session.id });+ }),+ ],+});diff --git a/packages/eve/extension-contracts/compatibility/connection/v52.ts b/packages/eve/extension-contracts/compatibility/connection/v52.tsnew file mode 100644index 000000000..6aa809638--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/connection/v52.ts@@ -0,0 +1,10 @@+import { defineMcpClientConnection } from "#public/connections/index.js";++export default defineMcpClientConnection({+ description: "Read reports from the tracker.",+ url: "https://tracker.example.com/mcp",+ auth: {+ principalType: "app",+ getToken: async () => ({ token: "service-credential" }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/schedule/v35.ts b/packages/eve/extension-contracts/compatibility/schedule/v35.tsnew file mode 100644index 000000000..bdad2c77c--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/schedule/v35.ts@@ -0,0 +1,20 @@+import { defineChannel } from "#public/channels/index.js";+import { defineSchedule } from "#public/schedules/index.js";++const reports = defineChannel({+ routes: [],+ receive(input, { from }) {+ return from("reports").send(input.message, { auth: input.auth });+ },+});++export default defineSchedule({+ cron: "0 2 * * *",+ async run({ to, appAuth }) {+ const session = await to(reports, {}).send("Prepare Alice's report.", { auth: appAuth });+ await session.send("Include Bob's notes.", {+ auth: appAuth,+ history: [{ role: "user", text: "Bob reviewed the earlier draft." }],+ });+ },+});diff --git a/packages/eve/extension-contracts/compatibility/tool/v94.ts b/packages/eve/extension-contracts/compatibility/tool/v94.tsnew file mode 100644index 000000000..d1c4bdc1a--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/tool/v94.ts@@ -0,0 +1,9 @@+import { defineTool } from "#public/tools/index.js";++export default defineTool({+ description: "Identify the report's session.",+ inputSchema: {},+ execute(_input, ctx) {+ return { sessionId: ctx.session.id };+ },+});diff --git a/packages/eve/extension-contracts/reports/channel/v64.json b/packages/eve/extension-contracts/reports/channel/v64.jsonnew file mode 100644index 000000000..0984ebddb--- /dev/null+++ b/packages/eve/extension-contracts/reports/channel/v64.json@@ -0,0 +1,24 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "channel",+ "epoch": 64,+ "sha256": "dce0709791a1d2e4c2d11f0f118abba82720194e02f18cf8788ae918e5767553",+ "exports": [+ "DELETE",+ "GET",+ "HEAD",+ "InvalidSessionHistoryError",+ "OPTIONS",+ "PATCH",+ "POST",+ "PUT",+ "SessionStrandedError",+ "WS",+ "attachmentError",+ "createWebSocketUpgradeServer",+ "defineChannel",+ "disableRoute",+ "isChannel",+ "isDisabledRouteSentinel"+ ]+}diff --git a/packages/eve/extension-contracts/reports/connection/v53.json b/packages/eve/extension-contracts/reports/connection/v53.jsonnew file mode 100644index 000000000..0214b832b--- /dev/null+++ b/packages/eve/extension-contracts/reports/connection/v53.json@@ -0,0 +1,16 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "connection",+ "epoch": 53,+ "sha256": "6a1eb3f7c46486cf85af5858bd719f97f119be0a5d9d39b7882710db688b442d",+ "exports": [+ "ConnectionAuthorizationFailedError",+ "ConnectionAuthorizationRequiredError",+ "defineDynamic",+ "defineInteractiveAuthorization",+ "defineMcpClientConnection",+ "defineOpenAPIConnection",+ "isConnectionAuthorizationFailedError",+ "isConnectionAuthorizationRequiredError"+ ]+}diff --git a/packages/eve/extension-contracts/reports/schedule/v36.json b/packages/eve/extension-contracts/reports/schedule/v36.jsonnew file mode 100644index 000000000..432595b35--- /dev/null+++ b/packages/eve/extension-contracts/reports/schedule/v36.json@@ -0,0 +1,15 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "schedule",+ "epoch": 36,+ "sha256": "509d691b60d9caf02295adabfec7744174fd63a1dfd8fbbbce5cf9f20fb192ac",+ "exports": [+ "ScheduleDefinition",+ "ScheduleHandlerArgs",+ "ScheduleRunHandler",+ "ScheduleToFn",+ "TypedReceiveTarget",+ "defineSchedule",+ "isScheduleAuth"+ ]+}diff --git a/packages/eve/extension-contracts/reports/tool/v95.json b/packages/eve/extension-contracts/reports/tool/v95.jsonnew file mode 100644index 000000000..4d6917aca--- /dev/null+++ b/packages/eve/extension-contracts/reports/tool/v95.json@@ -0,0 +1,29 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "tool",+ "epoch": 95,+ "sha256": "d3894ddc377461b3d097011519d25c8e606031d6586124448ca26c3865092c8d",+ "exports": [+ "AgentRouterInput",+ "AgentRouterTool",+ "WorkflowStepToolContext",+ "WorkflowTool",+ "WorkflowToolDefinition",+ "WorkflowToolInput",+ "WorkflowToolOptions",+ "agentRouter",+ "decide",+ "defaultWebSearch",+ "defineTool",+ "defineWorkflowTool",+ "disableTool",+ "isDisabledToolSentinel",+ "isWebSearchToolDefinition",+ "serializeModelInputSchema",+ "toolOutput",+ "toolOutputPart",+ "toolResultFrom",+ "webSearch",+ "workflow"+ ]+}diff --git a/packages/eve/src/channel/channel-address.test.ts b/packages/eve/src/channel/channel-address.test.tsindex 949f15cd2..2e756fb0d 100644--- a/packages/eve/src/channel/channel-address.test.ts+++ b/packages/eve/src/channel/channel-address.test.ts@@ -15,6 +15,24 @@ function createRuntime(): Runtime {}describe("createChannelAddress", () => {+ it.each(["", "x".repeat(257)])(+ "rejects an invalid idempotency key before accepting a delivery",+ async (idempotencyKey) => {+ const runtime = createRuntime();+ const address = createChannelAddress({+ adapter: { kind: "http" },+ channelName: "webhook",+ continuationToken: "thread",+ runtime,+ });+ await expect(+ address.send("Alice asks for a report.", { auth: null, idempotencyKey }),+ ).rejects.toThrow("idempotencyKey");+ expect(runtime.dispatchContinuation).not.toHaveBeenCalled();+ expect(runtime.createSession).not.toHaveBeenCalled();+ },+ );+it("rejects channel addresses in the framework-reserved session namespace", () => {expect(() =>createChannelAddress({diff --git a/packages/eve/src/channel/channel-address.ts b/packages/eve/src/channel/channel-address.tsindex fa6450a46..980ee6fa0 100644--- a/packages/eve/src/channel/channel-address.ts+++ b/packages/eve/src/channel/channel-address.ts@@ -1,6 +1,7 @@import type { UserContent } from "ai";import type { ChannelAdapter } from "#channel/adapter.js";+import { validateDeliveryIdempotencyKey } from "#channel/delivery-idempotency.js";import {createChannelDeliveryMetadata,type ChannelDeliverySource,@@ -38,6 +39,7 @@ type ChannelAddressCreateOptions<TState = undefined> = [TState] extends [undefin: BaseChannelAddressCreateOptions & { readonly state?: Partial<TState> };interface BaseChannelAddressDeliveryOptions {+ readonly idempotencyKey?: string;readonly auth: SessionAuthContext | null;readonly callback?: SessionCallback;readonly initiatorAuth?: SessionAuthContext | null;@@ -106,6 +108,7 @@ export function createChannelAddress<TState = undefined>(input: {return {continuationToken: input.continuationToken,async deliver(sendInput, options) {+ validateDeliveryIdempotencyKey(options.idempotencyKey);const delivery =metadata.channelKind !== undefined && metadata.channelName !== undefined? createChannelDeliveryMetadata(metadata as ChannelDeliverySource)@@ -113,6 +116,7 @@ export function createChannelAddress<TState = undefined>(input: {const payload = withValidatedHistory(normalizeSendInput(sendInput));const caller = sessionCallbackToTurnCaller(options.callback);const commandWithoutCaller = {+ idempotencyKey: options.idempotencyKey,auth: options.auth,delivery,kind: "send" as const,@@ -137,6 +141,7 @@ export function createChannelAddress<TState = undefined>(input: {state: { ...input.adapter.state, ...(state as Record<string, unknown>) },};const runInput: RunInput = {+ idempotencyKey: options.idempotencyKey,adapter,auth: options.auth,capabilities: { requestInput: true },diff --git a/packages/eve/src/channel/channel-operations.ts b/packages/eve/src/channel/channel-operations.tsindex b6a647ebf..5b68c6018 100644--- a/packages/eve/src/channel/channel-operations.ts+++ b/packages/eve/src/channel/channel-operations.ts@@ -26,6 +26,8 @@ import type { SessionHistoryMessage } from "#shared/session-history.js";import { attachInputText, readInputText } from "#internal/input-text.js";interface BaseChannelSendOptions {+ /** Stable delivery identity, deduplicated within this session's recent-key window. */+ readonly idempotencyKey?: string;readonly auth: SessionAuthContext | null;readonly callback?: SessionCallback;readonly context?: readonly string[];@@ -48,6 +50,8 @@ export type ChannelSendOptions<TState = undefined> = [TState] extends [undefined: BaseChannelSendOptions & { readonly state: TState };interface BaseChannelRespondOptions<TState = undefined> {+ /** Stable delivery identity, with the same scope and retention as `send()`. */+ readonly idempotencyKey?: string;readonly auth: SessionAuthContext | null;readonly context?: readonly string[];readonly state?: Partial<TState>;diff --git a/packages/eve/src/channel/delivery-idempotency.ts b/packages/eve/src/channel/delivery-idempotency.tsnew file mode 100644index 000000000..059bf9153--- /dev/null+++ b/packages/eve/src/channel/delivery-idempotency.ts@@ -0,0 +1,16 @@+/** Maximum number of distinct delivery keys remembered by one logical session. */+export const DELIVERY_IDEMPOTENCY_WINDOW = 1024;+export const MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH = 256;++export function validateDeliveryIdempotencyKey(key: unknown): asserts key is string | undefined {+ if (+ key !== undefined &&+ (typeof key !== "string" ||+ key.length === 0 ||+ key.length > MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH)+ ) {+ throw new Error(+ `idempotencyKey must be a nonempty string of at most ${MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH} characters.`,+ );+ }+}diff --git a/packages/eve/src/channel/session.ts b/packages/eve/src/channel/session.tsindex 5434436a3..0c4b98bec 100644--- a/packages/eve/src/channel/session.ts+++ b/packages/eve/src/channel/session.ts@@ -1,4 +1,5 @@import type { ContextAccessor } from "#context/key.js";+import { validateDeliveryIdempotencyKey } from "#channel/delivery-idempotency.js";import {createChannelDeliveryMetadata,type ChannelDeliverySource,@@ -73,6 +74,8 @@ export interface Session {}interface SessionDeliveryOptions {+ /** Stable delivery identity, deduplicated within this session's recent-key window. */+ readonly idempotencyKey?: string;readonly auth: SessionAuthContext | null;/** Public callback destination for a delegated continuation turn. */readonly callback?: SessionCallback;@@ -117,6 +120,7 @@ export function createSession(return {id,async send(message, options) {+ validateDeliveryIdempotencyKey(options.idempotencyKey);const delivery = createDelivery(metadata);const caller = sessionCallbackToTurnCaller(options.callback);const history = validateSessionHistory(options.history);@@ -130,6 +134,7 @@ export function createSession(if (history !== undefined) payload.history = history;if (options.outputSchema !== undefined) payload.outputSchema = options.outputSchema;const commandWithoutCaller = {+ idempotencyKey: options.idempotencyKey,auth: options.auth,delivery,kind: "send" as const,@@ -144,6 +149,7 @@ export function createSession(});},async respond(inputResponses, options) {+ validateDeliveryIdempotencyKey(options.idempotencyKey);if (inputResponses.length === 0) {throw new Error("respond() requires at least one input response.");}@@ -158,6 +164,7 @@ export function createSession(if (options.context !== undefined) payload.context = options.context;if (options.outputSchema !== undefined) payload.outputSchema = options.outputSchema;const commandWithoutCaller = {+ idempotencyKey: options.idempotencyKey,auth: options.auth,delivery,kind: "send" as const,diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.tsindex 5c348d35c..53db8b927 100644--- a/packages/eve/src/channel/types.ts+++ b/packages/eve/src/channel/types.ts@@ -193,6 +193,7 @@ export const DEFAULT_TURN_POLICY: TurnPolicy = "steer";/** One command accepted by a durable session inbox. */export type SessionCommand =| {+ readonly idempotencyKey?: string;readonly auth?: SessionAuthContext | null;readonly caller?: TurnCaller;/** Initial workflow title when delivering to a prewarmed session. */@@ -262,6 +263,7 @@ export interface DispatchSessionInput<TCommand extends SessionCommand = SessionC* metadata so both cross the durable hook boundary outside adapter-owned data.*/export interface DeliverHookPayload {+ readonly idempotencyKey?: string;readonly schedule?: import("#context/session-schedule.js").SessionSchedule;/** Initial workflow title; ignored once session initialization has run. */readonly title?: string;@@ -442,6 +444,8 @@ export interface SessionCapabilities {* subagent tool wrapper).*/export interface RunInput {+ /** Optional stable identity of the initial delivery, scoped to this logical session. */+ readonly idempotencyKey?: string;/*** @internal Set by the server after it authorizes tool stubs.* Local subagents match rules qualified by their full path, such as researcher/list_tasks.diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex a7abd4d48..a1171c976 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -22,10 +22,10 @@ interface ExtensionCapabilityContract {const EXTENSION_CAPABILITY_CONTRACTS = {extension: { current: 1, supported: [1], dropped: {} },tool: {- current: 94,+ current: 95,supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 76, 77, 78, 80, 81, 82, 84,- 85, 86, 87, 88, 89, 90, 91, 92, 93, 94,+ 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95,],dropped: {14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",@@ -134,10 +134,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},channel: {- current: 63,+ current: 64,supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 31, 36, 37, 38, 39, 40, 41, 42,- 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63,+ 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64,],dropped: {12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -160,10 +160,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},schedule: {- current: 35,+ current: 36,supported: [1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28,- 29, 30, 31, 32, 33, 34, 35,+ 29, 30, 31, 32, 33, 34, 35, 36,],dropped: {5: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -189,10 +189,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},connection: {- current: 52,+ current: 53,supported: [1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24, 26, 32, 33, 34,- 35, 36, 37, 38, 39, 40, 41, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52,+ 35, 36, 37, 38, 39, 40, 41, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53,],dropped: {9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",diff --git a/packages/eve/src/execution/legacy-session/turn-workflow.ts b/packages/eve/src/execution/legacy-session/turn-workflow.tsindex 4bb5eaaa2..dff923081 100644--- a/packages/eve/src/execution/legacy-session/turn-workflow.ts+++ b/packages/eve/src/execution/legacy-session/turn-workflow.ts@@ -46,8 +46,10 @@ export async function turnWorkflow(rawInput: unknown): Promise<void> {});}const timeoutDeadline = sessionTimeoutDeadline(prepared.sessionTimeoutMs, Date.now());+ const initialDeliveryKey = prepared.input.delivery?.idempotencyKey;await runPreparedSession({+ admittedDeliveryKeys: initialDeliveryKey === undefined ? [] : [initialDeliveryKey],anchor: {kind: "self",notify: (result) =>diff --git a/packages/eve/src/execution/session-inbox/protocol.test.ts b/packages/eve/src/execution/session-inbox/protocol.test.tsindex aa8e8b6db..1b2243a7d 100644--- a/packages/eve/src/execution/session-inbox/protocol.test.ts+++ b/packages/eve/src/execution/session-inbox/protocol.test.ts@@ -33,5 +33,10 @@ describe("session inbox payloads", () => {expect(() => decodeSessionInboxPayload({ kind: "legacy-send" })).toThrowError(SessionInboxPayloadError,);+ for (const idempotencyKey of ["", "x".repeat(257), 1]) {+ expect(() =>+ decodeSessionInboxPayload({ kind: "send", idempotencyKey, payload: { message: "hello" } }),+ ).toThrowError(SessionInboxPayloadError);+ }});});diff --git a/packages/eve/src/execution/session-inbox/protocol.ts b/packages/eve/src/execution/session-inbox/protocol.tsindex f2264e04b..a6b303c42 100644--- a/packages/eve/src/execution/session-inbox/protocol.ts+++ b/packages/eve/src/execution/session-inbox/protocol.ts@@ -3,6 +3,7 @@ import type {SessionCommand,SessionTimeoutHookPayload,} from "#channel/types.js";+import { validateDeliveryIdempotencyKey } from "#channel/delivery-idempotency.js";type DecodedSessionInbox =| DeliverHookPayload@@ -23,6 +24,13 @@ export function decodeSessionInboxPayload(value: unknown): DecodedSessionInbox {throw new SessionInboxPayloadError("Session inbox payload must be an object with a kind.");}const payload = value as Record<string, unknown>;+ if (payload.kind === "send" || payload.kind === "deliver") {+ try {+ validateDeliveryIdempotencyKey(payload.idempotencyKey);+ } catch (error) {+ throw new SessionInboxPayloadError((error as Error).message);+ }+ }switch (payload.kind) {case "send": {if (payload.payload === null || typeof payload.payload !== "object") {@@ -30,6 +38,7 @@ export function decodeSessionInboxPayload(value: unknown): DecodedSessionInbox {}const command = value as Extract<SessionCommand, { readonly kind: "send" }>;return {+ idempotencyKey: command.idempotencyKey,auth: command.auth,schedule: command.schedule,title: command.title,diff --git a/packages/eve/src/execution/session/active-turn.ts b/packages/eve/src/execution/session/active-turn.tsindex 451df3437..54e5821b2 100644--- a/packages/eve/src/execution/session/active-turn.ts+++ b/packages/eve/src/execution/session/active-turn.ts@@ -95,6 +95,7 @@ export class ActiveTurn {}if (delivery.kind === "deliver" &&+ !this.input.queue.isDuplicate(delivery) &&isSteeringMessage(delivery, this.identity) &&!this.input.cursor.sessionState.hasProxyInputRequests)diff --git a/packages/eve/src/execution/session/admission.ts b/packages/eve/src/execution/session/admission.tsindex 85e3502df..421d0f730 100644--- a/packages/eve/src/execution/session/admission.ts+++ b/packages/eve/src/execution/session/admission.ts@@ -52,8 +52,10 @@ export async function admitSessionInboxPayload(}switch (command.kind) {- case "deliver":- return { admission: input.queue.enqueueDelivery(command), kind: "delivery" };+ case "deliver": {+ const admission = input.queue.enqueueDelivery(command);+ return admission === undefined ? { kind: "consumed" } : { admission, kind: "delivery" };+ }case "clear":case "compact":input.queue.enqueueControl(command.kind);diff --git a/packages/eve/src/execution/session/checkpoint-migrations.test.ts b/packages/eve/src/execution/session/checkpoint-migrations.test.tsindex 90600c4c7..e4e9fd8ff 100644--- a/packages/eve/src/execution/session/checkpoint-migrations.test.ts+++ b/packages/eve/src/execution/session/checkpoint-migrations.test.ts@@ -13,6 +13,7 @@ describe("migrateSessionCheckpoint", () => {kind: "current",childRunIdsToStop: ["child-local"],checkpoint: {+ admittedDeliveryKeys: [],history: [{ content: "Alice asks for a report.", kind: "user", role: "user" },{ content: [{ text: "Started the report.", type: "text" }], role: "assistant" },@@ -164,6 +165,23 @@ describe("migrateSessionCheckpoint", () => {});});+ it.each([+ undefined,+ ["alice", 1],+ [""],+ ["x".repeat(257)],+ Array.from({ length: 1025 }, (_, index) => `delivery-${index}`),+ ])(+ "refuses a current checkpoint with an invalid delivery-key window (%#)",+ (admittedDeliveryKeys) => {+ const checkpoint = {+ ...savedCheckpoint(SESSION_CHECKPOINT_VERSION, {}),+ admittedDeliveryKeys,+ };+ expect(migrateSessionCheckpoint(checkpoint)).toMatchObject({ kind: "incompatible" });+ },+ );+it.each([12, 13, 14])("loads a saved version %s session's approvals, sign-ins and relays from the requests key",(version) => {diff --git a/packages/eve/src/execution/session/checkpoint-migrations.ts b/packages/eve/src/execution/session/checkpoint-migrations.tsindex 7537c88d9..ff89467d8 100644--- a/packages/eve/src/execution/session/checkpoint-migrations.ts+++ b/packages/eve/src/execution/session/checkpoint-migrations.ts@@ -1,4 +1,8 @@import { SESSION_CHECKPOINT_VERSION, type SessionCheckpoint } from "#execution/session/handoff.js";+import {+ DELIVERY_IDEMPOTENCY_WINDOW,+ MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH,+} from "#channel/delivery-idempotency.js";import { isObject } from "#shared/guards.js";import { initialSessionProjection } from "#protocol/session-projection.js";import { getBlockingWorkflowToolRuns } from "#harness/workflow-tool-runs.js";@@ -110,6 +114,8 @@ const CHECKPOINT_UPGRADES: Readonly<sessionState: { ...sessionState, snapshot: { ...snapshot, session: { ...session, state } } },};},+ // Older owners have never admitted keyed deliveries.+ 15: (checkpoint) => ({ ...checkpoint, admittedDeliveryKeys: [] }),};/**@@ -235,6 +241,14 @@ function isCurrentCheckpoint(value: unknown): value is SessionCheckpoint {return (isObject(value) &&value.version === SESSION_CHECKPOINT_VERSION &&+ Array.isArray(value.admittedDeliveryKeys) &&+ value.admittedDeliveryKeys.length <= DELIVERY_IDEMPOTENCY_WINDOW &&+ value.admittedDeliveryKeys.every(+ (key) =>+ typeof key === "string" &&+ key.length > 0 &&+ key.length <= MAX_DELIVERY_IDEMPOTENCY_KEY_LENGTH,+ ) &&Array.isArray(value.history) &&isObject(value.serializedContext) &&isObject(value.sessionState)diff --git a/packages/eve/src/execution/session/delivery-idempotency.integration.test.ts b/packages/eve/src/execution/session/delivery-idempotency.integration.test.tsnew file mode 100644index 000000000..4d310018c--- /dev/null+++ b/packages/eve/src/execution/session/delivery-idempotency.integration.test.ts@@ -0,0 +1,81 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { createChannelOperations } from "#channel/channel-operations.js";+import { createSession } from "#channel/session.js";+import { createTestRuntime } from "#internal/testing/app-harness.js";+import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";+import { createWorkflowRuntime } from "#execution/workflow-runtime.js";+import { getRun, getWorld } from "#internal/workflow/runtime.js";+import { captureTurnEvents } from "#internal/testing/events.js";+import { waitForParkedTurnStep } from "#internal/testing/session-test-helpers.js";+import { defineHook } from "#public/definitions/hook.js";++afterEach(() => vi.unstubAllEnvs());++describe("delivery idempotency", () => {+ it("deduplicates racing initial and follow-up sends across addresses and replay", async () => {+ vi.stubEnv("VERCEL_DEPLOYMENT_ID", await (await getWorld()).getDeploymentId());+ const messages: string[] = [];+ const app = await createTestRuntime({+ agent: { name: "keyed-delivery", limits: { sessionTimeoutMs: false } },+ modules: [+ {+ logicalPath: "hooks/record.ts",+ loadNamespace: async () => ({+ default: defineHook({+ events: {+ "turn.started"() {+ messages.push("turn");+ },+ },+ }),+ }),+ },+ ],+ });+ await app.run(async () => {+ const runtime = createWorkflowRuntime({+ compiledArtifactsSource: createBundledRuntimeCompiledArtifactsSource(),+ });+ const operations = () =>+ createChannelOperations({ adapter: { kind: "http" }, channelName: "test", runtime });+ const address = crypto.randomUUID();+ const send = () =>+ operations()+ .from(address)+ .send("Alice asks for a report.", { auth: null, idempotencyKey: "initial" });+ const initial = await Promise.all([send(), send()]);+ expect(initial[0]!.id).toBe(initial[1]!.id);+ const session = initial[0]!;+ const stream = captureTurnEvents(getRun(session.id));+ let completed = false;+ try {+ await stream.nextTurn();+ await waitForParkedTurnStep(session.id);+ // Each hook resume replays the owner from its recorded history.+ await send();+ const fixed = createSession(session.id, runtime);+ const followUp = () =>+ fixed.send("Bob asks for the next step.", {+ auth: null,+ idempotencyKey: "followup",+ turnPolicy: "queue",+ });+ await Promise.all([followUp(), followUp()]);+ await stream.nextTurn();+ await waitForParkedTurnStep(session.id, 2);+ await followUp();+ await fixed.send("Alice thanks Bob.", { auth: null, turnPolicy: "queue" });+ await stream.nextTurn();+ await waitForParkedTurnStep(session.id, 3);+ await fixed.reset();+ completed = true;+ expect(messages).toHaveLength(3);+ } finally {+ stream.dispose();+ if (!completed && ["pending", "running"].includes(await getRun(session.id).status)) {+ await getRun(session.id).cancel();+ }+ }+ });+ }, 60_000);+});diff --git a/packages/eve/src/execution/session/entry-handoff.integration.test.ts b/packages/eve/src/execution/session/entry-handoff.integration.test.tsindex 20972f81a..cbf44d597 100644--- a/packages/eve/src/execution/session/entry-handoff.integration.test.ts+++ b/packages/eve/src/execution/session/entry-handoff.integration.test.ts@@ -31,6 +31,45 @@ const HANDOFF_LOG = "[eve:execution.handoff]";describe("workflowEntry integration", () => {describe("deployment handoff", () => {+ it("remembers admitted delivery keys when the logical session changes owners", async () => {+ const runtime = await createTestRuntime({ agent: { name: "handoff-keyed-delivery" } });+ await runtime.run(async () => {+ const { anchor, stream, workflowRuntime } = await openSession({+ idempotencyKey: "opening",+ });+ try {+ await stream.nextTurn();+ await waitForParkedTurnStep(anchor.runId);+ const command = {+ ...handoffFollowUp("dpl_b", "Bob requests a report.", "keyed-report"),+ idempotencyKey: "report",+ };+ await workflowRuntime.dispatchSession({ command, sessionId: anchor.runId });+ const successor = await waitForNewOwner(anchor.runId, anchor.runId);+ await waitForUserMessages(successor.runId, "Bob requests a report.");+ await waitForParkedTurnStep(successor.runId);+ await workflowRuntime.dispatchSession({+ command: {+ ...handoffFollowUp("dpl_b", "Alice opens a research session.", "opening-retry"),+ idempotencyKey: "opening",+ },+ sessionId: anchor.runId,+ });+ await workflowRuntime.dispatchSession({ command, sessionId: anchor.runId });+ await workflowRuntime.dispatchSession({+ command: handoffFollowUp("dpl_b", "Alice reviews the report.", "review"),+ sessionId: anchor.runId,+ });+ const history = await waitForUserMessages(successor.runId, "Alice reviews the report.");+ expect(countOf(history, "Bob requests a report.")).toBe(1);+ expect(countOf(history, "Alice opens a research session.")).toBe(1);+ } finally {+ stream.dispose();+ await anchor.cancel();+ }+ });+ });+it("processes what the owner accepted during the move on the successor, after the trigger", async () => {const runtime = await createTestRuntime({ agent: { name: "handoff-accepted-during-move" } });await runtime.run(async () => {@@ -600,10 +639,13 @@ function rebindCheckpoint(};}-async function openSession(options: { readonly continuationToken?: string } = {}) {+async function openSession(+ options: { readonly continuationToken?: string; readonly idempotencyKey?: string } = {},+) {const anchor = await startSessionOwner(workflowEntry, [{kind: "initial",+ idempotencyKey: options.idempotencyKey,ownerDeploymentId: "dpl_a",sessionTimeoutMs: false,input: { message: "Alice opens a research session." },diff --git a/packages/eve/src/execution/session/entry-input.ts b/packages/eve/src/execution/session/entry-input.tsindex ed7b0656d..65972ce72 100644--- a/packages/eve/src/execution/session/entry-input.ts+++ b/packages/eve/src/execution/session/entry-input.ts@@ -16,6 +16,7 @@ export const SESSION_HANDOFF_VERSION = 3;* and deserialized at each `"use step"` boundary.*/export interface InitialWorkflowEntryInput {+ readonly idempotencyKey?: string;readonly continuationConflictCommand?: Extract<SessionCommand, { readonly kind: "send" }>;readonly input: RunInput["input"];readonly kind: "initial";diff --git a/packages/eve/src/execution/session/entry.ts b/packages/eve/src/execution/session/entry.tsindex 308682417..a1d8eaf61 100644--- a/packages/eve/src/execution/session/entry.ts+++ b/packages/eve/src/execution/session/entry.ts@@ -224,6 +224,7 @@ export async function bootInitialOwner(return {inbox,session: {+ admittedDeliveryKeys: input.idempotencyKey === undefined ? [] : [input.idempotencyKey],anchor: { kind: "self" },caller,capabilities: serializedContext["eve.capabilities"] as SessionCapabilities | undefined,@@ -447,6 +448,7 @@ async function startSuccessor(inbox,session: {anchor: { kind: "successor" },+ admittedDeliveryKeys: checkpoint.admittedDeliveryKeys,caller: input.delivery?.caller,capabilities: checkpoint.capabilities,deploymentId: input.ownerDeploymentId,@@ -472,6 +474,7 @@ function createInitialDelivery(): DeliverHookPayload | undefined {if (input.input.message === undefined) return undefined;return {+ idempotencyKey: input.idempotencyKey,schedule: readSerializedSessionSchedule(serializedContext),deliveryMetadata:serializedContext["eve.channelDelivery"] === undefineddiff --git a/packages/eve/src/execution/session/handoff-steps.test.ts b/packages/eve/src/execution/session/handoff-steps.test.tsindex f724a59b2..75042c6b9 100644--- a/packages/eve/src/execution/session/handoff-steps.test.ts+++ b/packages/eve/src/execution/session/handoff-steps.test.ts@@ -306,6 +306,7 @@ function validate(checkpoint: SessionCheckpoint) {function createCheckpoint(): SessionCheckpoint {return {+ admittedDeliveryKeys: [],version: SESSION_CHECKPOINT_VERSION,history: [],sessionTimeoutMs: false,diff --git a/packages/eve/src/execution/session/handoff.test.ts b/packages/eve/src/execution/session/handoff.test.tsindex 9c149c620..76ad1631a 100644--- a/packages/eve/src/execution/session/handoff.test.ts+++ b/packages/eve/src/execution/session/handoff.test.ts@@ -501,6 +501,7 @@ function selection(acceptedDeploymentId: string): TurnSelection {function state() {return {+ admittedDeliveryKeys: [],history: [],serializedContext: {},sessionState: {diff --git a/packages/eve/src/execution/session/handoff.ts b/packages/eve/src/execution/session/handoff.tsindex 42fbc99e1..29eb9cd42 100644--- a/packages/eve/src/execution/session/handoff.ts+++ b/packages/eve/src/execution/session/handoff.ts@@ -41,10 +41,11 @@ import { isObject } from "#shared/guards.js";* A newer successor must always accept older checkpoints: every bump adds the* upgrade from the previous version in `checkpoint-migrations.ts`.*/-export const SESSION_CHECKPOINT_VERSION = 15;+export const SESSION_CHECKPOINT_VERSION = 16;/** Everything a successor needs to continue an idle session. Hooks are derived from the state. */export interface SessionCheckpoint {+ readonly admittedDeliveryKeys: readonly string[];readonly version: typeof SESSION_CHECKPOINT_VERSION;readonly capabilities?: SessionCapabilities;readonly history: HarnessModelMessage[];@@ -83,7 +84,7 @@ export type SessionOwnerActivation =interface SessionHandoffInput {readonly checkpoint: Omit<SessionCheckpoint,- "history" | "serializedContext" | "sessionState" | "version"+ "admittedDeliveryKeys" | "history" | "serializedContext" | "sessionState" | "version">;readonly deploymentId: string;readonly inbox: SessionInboxHandle;@@ -127,7 +128,7 @@ export interface CompactionHandoff {type SessionTransferState = Pick<SessionCheckpoint,- "history" | "serializedContext" | "sessionState"+ "admittedDeliveryKeys" | "history" | "serializedContext" | "sessionState">;type AttemptSettlement =diff --git a/packages/eve/src/execution/session/input-queue.test.ts b/packages/eve/src/execution/session/input-queue.test.tsindex e5e690942..1f07bde27 100644--- a/packages/eve/src/execution/session/input-queue.test.ts+++ b/packages/eve/src/execution/session/input-queue.test.ts@@ -13,8 +13,53 @@ function signInCallback(attemptId: string) {}describe("SessionInputQueue", () => {+ it("admits a keyed delivery once, even after its turn has consumed it", () => {+ const queue = new SessionInputQueue([]);+ const delivery = {+ idempotencyKey: "provider-1",+ kind: "deliver" as const,+ payloads: [{ message: "Alice asks for a report." }],+ };+ expect(queue.enqueueDelivery(delivery)).toBeDefined();+ expect(queue.takeNext()?.kind).toBe("turn");+ expect(queue.enqueueDelivery(delivery)).toBeUndefined();+ expect(queue.takeNext()).toBeUndefined();+ });++ it("retains the most recent 1024 distinct keys without refreshing duplicates", () => {+ const queue = new SessionInputQueue([]);+ const delivery = (idempotencyKey: string) => ({+ idempotencyKey,+ kind: "deliver" as const,+ payloads: [{ message: idempotencyKey }],+ });+ for (let index = 0; index < 1024; index++) {+ queue.enqueueDelivery(delivery(String(index)));+ queue.takeNext();+ }+ expect(queue.enqueueDelivery(delivery("0"))).toBeUndefined();+ queue.enqueueDelivery(delivery("1024"));+ queue.takeNext();+ expect(queue.enqueueDelivery(delivery("1"))).toBeUndefined();+ expect(queue.enqueueDelivery(delivery("0"))).toBeDefined();+ });++ it("keeps unkeyed deliveries independent and scopes keys to each session", () => {+ const delivery = {+ kind: "deliver" as const,+ payloads: [{ message: "Alice asks for a report." }],+ };+ const first = new SessionInputQueue([]);+ expect(first.enqueueDelivery(delivery)).toBeDefined();+ expect(first.enqueueDelivery(delivery)).toBeDefined();+ expect(first.enqueueDelivery({ ...delivery, idempotencyKey: "shared" })).toBeDefined();+ expect(+ new SessionInputQueue([]).enqueueDelivery({ ...delivery, idempotencyKey: "shared" }),+ ).toBeDefined();+ });+it("resumes a turn holding several sign-ins only once every one has called back", () => {- const queue = new SessionInputQueue();+ const queue = new SessionInputQueue([]);const held = new Set(["linear-1", "notion-1"]);queue.enqueueAuthorization([signInCallback("linear-1")]);@@ -29,14 +74,14 @@ describe("SessionInputQueue", () => {});it("lets a queued message steer a held turn only when it arrived after the hold", () => {- const queue = new SessionInputQueue();+ const queue = new SessionInputQueue([]);const turn = { callerCallId: undefined, principal: "user:test:alice" };const send = (message: string) =>queue.enqueueDelivery({kind: "deliver",payloads: [{ message }],turnPolicy: "queue",- }).sequence;+ })!.sequence;const before = send("approve");const heldSince = queue.nextAdmission;diff --git a/packages/eve/src/execution/session/input-queue.ts b/packages/eve/src/execution/session/input-queue.tsindex 6d5d75ecd..118846a6d 100644--- a/packages/eve/src/execution/session/input-queue.ts+++ b/packages/eve/src/execution/session/input-queue.ts@@ -1,4 +1,5 @@import type { DeliverHookPayload, DeliverPayload } from "#channel/types.js";+import { DELIVERY_IDEMPOTENCY_WINDOW } from "#channel/delivery-idempotency.js";import { coalesceDeliveries } from "#harness/messages.js";import { ANONYMOUS_PRINCIPAL, principalOf } from "#execution/session/principal.js";@@ -52,8 +53,21 @@ export type SessionInputSelection =*/export class SessionInputQueue {private readonly entries: QueuedSessionInput[] = [];+ private readonly admittedKeys: Set<string>;private nextSequence = 0;+ constructor(admittedDeliveryKeys: readonly string[]) {+ this.admittedKeys = new Set(admittedDeliveryKeys);+ }++ get admittedDeliveryKeys(): readonly string[] {+ return [...this.admittedKeys];+ }++ isDuplicate(delivery: DeliverHookPayload): boolean {+ return delivery.idempotencyKey !== undefined && this.admittedKeys.has(delivery.idempotencyKey);+ }+get pendingCount(): number {return this.entries.length;}@@ -63,7 +77,14 @@ export class SessionInputQueue {return this.nextSequence;}- enqueueDelivery(delivery: DeliverHookPayload): DeliveryAdmission {+ enqueueDelivery(delivery: DeliverHookPayload): DeliveryAdmission | undefined {+ if (this.isDuplicate(delivery)) return undefined;+ if (delivery.idempotencyKey !== undefined) {+ this.admittedKeys.add(delivery.idempotencyKey);+ if (this.admittedKeys.size > DELIVERY_IDEMPOTENCY_WINDOW) {+ this.admittedKeys.delete(this.admittedKeys.values().next().value!);+ }+ }const admission = { delivery, sequence: this.nextSequence++ };this.entries.push({ ...admission, kind: "delivery" });return admission;diff --git a/packages/eve/src/execution/session/next-input.test.ts b/packages/eve/src/execution/session/next-input.test.tsindex bef8ba714..07ec1f4e7 100644--- a/packages/eve/src/execution/session/next-input.test.ts+++ b/packages/eve/src/execution/session/next-input.test.ts@@ -92,7 +92,7 @@ function waitInput(inbox: SessionInbox): WaitInput {hasWorkingTasks: () => false,inbox: inbox,cursor,- queue: new SessionInputQueue(),+ queue: new SessionInputQueue([]),};}@@ -110,7 +110,7 @@ function createCursor(}function queueOf(...deliveries: DeliverHookPayload[]): SessionInputQueue {- const queue = new SessionInputQueue();+ const queue = new SessionInputQueue([]);for (const delivery of deliveries) queue.enqueueDelivery(delivery);return queue;}diff --git a/packages/eve/src/execution/session/program.ts b/packages/eve/src/execution/session/program.tsindex e937270ac..5bdf8f8af 100644--- a/packages/eve/src/execution/session/program.ts+++ b/packages/eve/src/execution/session/program.ts@@ -59,6 +59,7 @@ export type SessionStart =| { readonly kind: "parked" };export interface SessionBoot {+ readonly admittedDeliveryKeys: readonly string[];readonly anchor: SessionAnchor;readonly caller: TurnCaller | undefined;readonly capabilities?: SessionCapabilities;@@ -218,7 +219,7 @@ async function runSessionLoop(},): Promise<SessionLoopOutcome> {const { cursor, handoff, inbox, progress } = deps;- const queue = new SessionInputQueue();+ const queue = new SessionInputQueue(boot.admittedDeliveryKeys);const execution = new SessionExecution({capabilities: boot.capabilities,cursor,@@ -267,6 +268,7 @@ async function runSessionLoop(return outcome;};const transferState = () => ({+ admittedDeliveryKeys: queue.admittedDeliveryKeys,history: cursor.history,serializedContext: cursor.serializedContext,sessionState: cursor.sessionState,diff --git a/packages/eve/src/execution/session/turn.test.ts b/packages/eve/src/execution/session/turn.test.tsindex 1656697f6..b1762d272 100644--- a/packages/eve/src/execution/session/turn.test.ts+++ b/packages/eve/src/execution/session/turn.test.ts@@ -228,6 +228,45 @@ describe("SessionExecution checkpoints", () => {await createExecution({ inbox, sessionState: state("") }).runTurn(undefined, { caller });expect(callers).toEqual([caller, undefined]);});+ it("does not interrupt generation for an already admitted delivery key", async () => {+ let deliver: (payload: SessionInboxPayload) => void = () => {};+ const inbox: SessionInbox = {+ ...idleInbox(),+ onDelivery(handler) {+ deliver = handler;+ return () => {};+ },+ };+ vi.mocked(turnStep)+ .mockReset()+ .mockImplementationOnce(+ turnStepWork(async (input) => {+ deliver({+ kind: "send",+ idempotencyKey: "accepted",+ payload: { message: "Alice's earlier message." },+ });+ expect(input.steeringSignal?.aborted).toBe(false);+ deliver({+ kind: "send",+ idempotencyKey: "new",+ payload: { message: "Alice corrects the report." },+ });+ expect(input.steeringSignal?.aborted).toBe(true);+ return {+ action: "park",+ serializedContext: input.serializedContext,+ sessionState: input.sessionState,+ };+ }),+ );+ await createExecution({+ inbox,+ queue: new SessionInputQueue(["accepted"]),+ sessionState: state(""),+ }).runTurn(undefined);+ });+it.each(["cancel", "reset"] as const)("gives %s precedence over generation steering",async (kind) => {@@ -573,7 +612,7 @@ describe("SessionExecution checkpoints", () => {it("consumes the cancelling command while retaining accepted follow-ups", async () => {const sessionState = state("");- const queue = new SessionInputQueue();+ const queue = new SessionInputQueue([]);const followUp: DeliverHookPayload = {kind: "deliver",payloads: [{ message: "Continue after cancellation." }],@@ -696,7 +735,7 @@ describe("SessionExecution checkpoints", () => {kind: "deliver",payloads: [{ message: "One more thing." }],};- const queue = new SessionInputQueue();+ const queue = new SessionInputQueue([]);const inbox: SessionInbox = {claimedTokens: [],takeLeading: () => [],@@ -806,7 +845,7 @@ describe("SessionExecution checkpoints", () => {};const cancel = { kind: "cancel", turnId: "turn_0" } as const;let interrupt: (payload: SessionInboxPayload) => void = () => {};- const queue = new SessionInputQueue();+ const queue = new SessionInputQueue([]);const inbox: SessionInbox = {claimedTokens: [],takeLeading: () => [],@@ -856,7 +895,7 @@ describe("SessionExecution checkpoints", () => {payloads: [{ inputResponses: [{ requestId: "child-request", text: "blue" }] }],};const runtimePayloads = [answer, { kind: "cancel" as const }];- const queue = new SessionInputQueue();+ const queue = new SessionInputQueue([]);const inbox: SessionInbox = {claimedTokens: [],takeLeading: () => [],@@ -1147,7 +1186,7 @@ describe("SessionExecution checkpoints", () => {const execution = new SessionExecution({cursor,inbox,- queue: new SessionInputQueue(),+ queue: new SessionInputQueue([]),sessionId: sessionState.sessionId,});@@ -1709,7 +1748,7 @@ function createExecution(input: {capabilities: input.capabilities,cursor,inbox: input.inbox,- queue: input.queue ?? new SessionInputQueue(),+ queue: input.queue ?? new SessionInputQueue([]),sessionId: input.sessionState.sessionId,});}diff --git a/packages/eve/src/execution/tasks/task-run-usage.test.ts b/packages/eve/src/execution/tasks/task-run-usage.test.tsindex d7077085f..fe9743755 100644--- a/packages/eve/src/execution/tasks/task-run-usage.test.ts+++ b/packages/eve/src/execution/tasks/task-run-usage.test.ts@@ -87,7 +87,7 @@ function sessionWithTask(input: {const execution = new SessionExecution({cursor,inbox,- queue: new SessionInputQueue(),+ queue: new SessionInputQueue([]),sessionId: base.sessionId,});const from: WorkflowToolRunRef = {diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.tsindex cd8f8db7f..cbe910cba 100644--- a/packages/eve/src/execution/workflow-runtime.ts+++ b/packages/eve/src/execution/workflow-runtime.ts@@ -1,4 +1,5 @@import { validateToolStubTargets } from "#tool-stubs/validate-targets.js";+import { validateDeliveryIdempotencyKey } from "#channel/delivery-idempotency.js";import { context, trace } from "#compiled/@opentelemetry/api/index.js";import {EntityConflictError,@@ -141,6 +142,7 @@ export function createWorkflowRuntime(config: {input: RunInput,predecessor?: SessionPredecessor,): Promise<RunHandle> => {+ validateDeliveryIdempotencyKey(input.idempotencyKey);const bundle = await getCompiledRuntimeAgentBundle({compiledArtifactsSource: config.compiledArtifactsSource,nodeId: config.nodeId,@@ -173,6 +175,7 @@ export function createWorkflowRuntime(config: {const workflowInput: {-readonly [K in keyof InitialWorkflowEntryInput]: InitialWorkflowEntryInput[K];} = {+ idempotencyKey: input.idempotencyKey,kind: "initial",input: input.input,ownerDeploymentId: await resolveCurrentWorkflowDeploymentId(),@@ -228,9 +231,23 @@ export function createWorkflowRuntime(config: {throw error;}+ let sessionId = run.runId;+ if (input.idempotencyKey !== undefined && input.continuationToken !== undefined) {+ // Keyed contenders must return the winning session, not their discarded candidate.+ const owner = await pollUntil(+ () => resolveContinuation(input.continuationToken!),+ SESSION_HOOK_HANDOVER_TIMEOUT_MS,+ );+ if (owner === undefined) {+ throw new Error(+ "Delivery accepted, but its session identity is not ready. Retry with the same idempotencyKey.",+ );+ }+ sessionId = owner.sessionId;+ }let events: ReadableStream<MessageStreamEvent> | undefined;const getEvents = () => {- events ??= readSessionEventStream(run.runId);+ events ??= readSessionEventStream(sessionId);return events;};@@ -238,7 +255,7 @@ export function createWorkflowRuntime(config: {get events() {return getEvents();},- sessionId: run.runId,+ sessionId,};};diff --git a/packages/eve/src/public/channels/photon/photonIMessageChannel.test.ts b/packages/eve/src/public/channels/photon/photonIMessageChannel.test.tsindex 7c0ef7df8..acaf1bf6c 100644--- a/packages/eve/src/public/channels/photon/photonIMessageChannel.test.ts+++ b/packages/eve/src/public/channels/photon/photonIMessageChannel.test.ts@@ -56,6 +56,7 @@ describe("photonIMessageChannel", () => {await handler(thread, message);expect(send).toHaveBeenCalledWith("Steer this response", {+ idempotencyKey: "message-id",auth: null,context: [],thread,@@ -84,6 +85,7 @@ describe("photonIMessageChannel", () => {await handler(thread, message);expect(send).toHaveBeenCalledWith("Hello Photon", {+ idempotencyKey: "message-id",auth: {attributes: { user_name: "user" },authenticator: "photon-imessage",@@ -145,6 +147,7 @@ describe("photonIMessageChannel", () => {await handler(thread, message);expect(send).toHaveBeenCalledWith("Hello group", {+ idempotencyKey: "message-id",auth: {attributes: { user_name: "user" },authenticator: "photon-imessage",diff --git a/packages/eve/src/public/channels/photon/photonIMessageChannel.ts b/packages/eve/src/public/channels/photon/photonIMessageChannel.tsindex e6d618ff3..2b54a04f4 100644--- a/packages/eve/src/public/channels/photon/photonIMessageChannel.ts+++ b/packages/eve/src/public/channels/photon/photonIMessageChannel.ts@@ -150,6 +150,7 @@ async function dispatchMessage(const content = photonInboundContent(message);if (content === undefined) return;await bridge.send(content, {+ idempotencyKey: message.id,auth: result.auth,context: [...(result.context ?? [])],history: result.history,diff --git a/research/channel-delivery-idempotency.md b/research/channel-delivery-idempotency.mdnew file mode 100644index 000000000..fa463e864--- /dev/null+++ b/research/channel-delivery-idempotency.md@@ -0,0 +1,39 @@+---+issue: https://github.com/vercel/eve/issues/1842+status: implemented+last_updated: "2026-10-20"+---++# Channel delivery idempotency++Channel and fixed-session `send()` and `respond()` calls accept an optional+`idempotencyKey`. The Chat SDK bridge forwards it, and Photon supplies its+message ID.++```ts+await from(conversationId).send(message, { auth, idempotencyKey: providerEventId });+```++The channel verifies the event and selects its ID. The session owner ignores+duplicates before routing, coalescing, or executing input. Known duplicates+cannot interrupt generation. Unkeyed sends behave as before.++Keys contain 1–256 characters. Each session remembers its last 1,024 distinct+keys in admission order; retries do not extend retention. Aliases share this+window. Reset, expiration, or replacement starts a new one. Reusing a retained+key ignores the new input, even if its contents changed. Replicas must share+the same durable Workflow World.++Initial input records its key in the workflow arguments. A losing creation+candidate forwards its command to the winning session. Keyed creation waits up+to 30 seconds for that session's ID. Existing-session sends return after durable+acceptance, without waiting for a turn or reporting whether input was a duplicate.+Callers retry ambiguous failures with the same key.++The admission queue rebuilds its key set on replay and saves it in the handoff+checkpoint. Checkpoint version 16 prevents older owners from dropping the set;+older checkpoints upgrade with an empty set.++This does not guarantee exactly-once external effects, webhook acknowledgements,+or ordering between distinct deliveries. Other built-in channels can adopt+provider IDs separately. HTTP session creation keeps its `operationId` contract.