Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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.mdx
index 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 handles
Channel 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.
```ts
const 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 an
address'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 routes
A 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.mdx
index 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's
webhook lists each file without its bytes, so eve downloads it from Photon by
its attachment id with the project's credentials. The webhook omits the id
diff --git a/docs/concepts/execution-model-and-durability.mdx b/docs/concepts/execution-model-and-durability.mdx
index 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 metadata
lookup. 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 previous
owner keeps every address until the new run takes all of them over, so a
delivery during a handoff is accepted immediately and is never reported as an
diff --git a/e2e/fixtures/agent-channels/agent/channels/target.ts b/e2e/fixtures/agent-channels/agent/channels/target.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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"] === undefined
diff --git a/packages/eve/src/execution/session/handoff-steps.test.ts b/packages/eve/src/execution/session/handoff-steps.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
new file mode 100644
index 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.