Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): session inbox - persist child reply addresses (#3044)

Andrew Barbac48969f759a0
diff --git a/.changeset/known-session-inboxes.md b/.changeset/known-session-inboxes.md
new file mode 100644
index 000000000..84844c23f
--- /dev/null
+++ b/.changeset/known-session-inboxes.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Persist the receiving session's inbox address and wire version with local subagent input requests. Replies can resume the original child directly without reading hook metadata, including after the child's continuation address changes.
diff --git a/e2e/fixtures/agent-subagents-hitl/evals/hitl.eval.ts b/e2e/fixtures/agent-subagents-hitl/evals/hitl.eval.ts
index 5653b5fb4..fcd293128 100644
--- a/e2e/fixtures/agent-subagents-hitl/evals/hitl.eval.ts
+++ b/e2e/fixtures/agent-subagents-hitl/evals/hitl.eval.ts
@@ -16,7 +16,7 @@ type SessionCursor = Pick<
* Parking is server-side.
*/
export default defineEval({
- tags: ["real-model"],
+ tags: ["session-inbox"],
description: "Subagent tool approval proxied through the parent session.",
timeoutMs: 90_000,
diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.ts
index 9f2b60180..cca4a3e8a 100644
--- a/packages/eve/src/channel/types.ts
+++ b/packages/eve/src/channel/types.ts
@@ -1,5 +1,6 @@
import type { UserContent } from "ai";
+import type { SessionInboxAddress } from "#execution/wire/session-inbox-contract.js";
import type { MessageStreamEvent, UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { CancelTurnResult as ProtocolCancelTurnResult } from "#protocol/cancel-turn.js";
import type { RunMode } from "#shared/run-mode.js";
@@ -341,6 +342,7 @@ export interface SubagentInputRequestHookPayload {
readonly callId: string;
readonly childContinuationToken: string;
readonly childSessionId: string;
+ readonly childSessionInbox?: SessionInboxAddress;
readonly event: SubagentInputRequestEvent;
readonly kind: "subagent-input-request";
readonly subagentName: string;
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index d504493f4..e757d051a 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -18,6 +18,10 @@ import type {
SessionTurn,
} from "#channel/types.js";
import { ContextKey } from "#context/key.js";
+import {
+ SESSION_INBOX_CONTEXT_KEY,
+ type SessionInboxAddress,
+} from "#execution/wire/session-inbox-contract.js";
import { SESSION_CALLBACK_CONTEXT_KEY_NAME } from "#context/key-names.js";
import type { InstrumentationChannelDeliveryRef } from "#instrumentation/lifecycle.js";
import type { HandleEventFn } from "#harness/types.js";
@@ -70,6 +74,7 @@ export interface Session {
export const AuthKey = new ContextKey<SessionAuthContext | null>("eve.auth");
export const InitiatorAuthKey = new ContextKey<SessionAuthContext | null>("eve.initiatorAuth");
export const SessionIdKey = new ContextKey<string>("eve.sessionId");
+export const SessionInboxKey = new ContextKey<SessionInboxAddress>(SESSION_INBOX_CONTEXT_KEY);
export const ContinuationTokenKey = new ContextKey<string>("eve.continuationToken");
export const ChannelRequestIdKey = new ContextKey<string>("eve.channelRequestId");
/** Parent-verified local client provenance, valid only for the current dev host secret. */
diff --git a/packages/eve/src/execution/proxied-deliver-step.ts b/packages/eve/src/execution/proxied-deliver-step.ts
index c37c67c08..84bb5f05b 100644
--- a/packages/eve/src/execution/proxied-deliver-step.ts
+++ b/packages/eve/src/execution/proxied-deliver-step.ts
@@ -1,3 +1,4 @@
+import type { SessionInboxAddress } from "#execution/wire/session-inbox-contract.js";
import type { DeliverHookPayload, DeliverPayload, SessionAuthContext } from "#channel/types.js";
import { coalesceDeliverPayloads } from "#execution/deliver-payloads.js";
import {
@@ -46,6 +47,7 @@ type LegacyRoutedDeliverResult =
interface ChildBucket {
readonly answerHook?: AnswerHookRoute;
readonly childContinuationToken: string;
+ readonly childSessionInbox?: SessionInboxAddress;
readonly childResponseUrl?: string;
readonly metadata: NonNullable<DeliverHookPayload["deliveryMetadata"]>[number][];
readonly payloads: DeliverPayload[];
@@ -108,17 +110,16 @@ export async function routeProxiedDeliverStep(
if (routed.forSelf !== undefined) parentPayloads.set(sourcePayloadIndex, routed.forSelf);
for (const [childIndex, forChild] of routed.forChildren.entries()) {
- const key =
- forChild.taskId === undefined
- ? forChild.childContinuationToken
- : [
- forChild.childContinuationToken,
- forChild.childResponseUrl ?? "",
- forChild.taskId,
- ].join("\0");
+ const key = [
+ forChild.childContinuationToken,
+ forChild.childSessionInbox?.sessionId ?? "",
+ forChild.childResponseUrl ?? "",
+ forChild.taskId ?? "",
+ ].join("\0");
const child = children.get(key) ?? {
answerHook: forChild.answerHook,
childContinuationToken: forChild.childContinuationToken,
+ childSessionInbox: forChild.childSessionInbox,
childResponseUrl: forChild.childResponseUrl,
metadata: [],
payloads: [],
@@ -158,6 +159,7 @@ export async function routeProxiedDeliverStep(
payload: {
auth: sourceDelivery.auth,
childContinuationToken: child.childContinuationToken,
+ childSessionInbox: child.childSessionInbox,
childResponseUrl: child.childResponseUrl,
inputResponses: coalesceDeliverPayloads(child.payloads).inputResponses ?? [],
kind: "input-response",
@@ -188,7 +190,10 @@ export async function routeProxiedDeliverStep(
deliveryMetadata: child.metadata.length === 0 ? undefined : child.metadata,
payloads: child.payloads,
};
- await resumeSessionInbox(child.childContinuationToken, childDelivery);
+ await resumeSessionInbox(
+ child.childSessionInbox ?? child.childContinuationToken,
+ childDelivery,
+ );
// Successfully forwarded request IDs are retired so later deliveries
// cannot route through stale entries.
durableSession = retireProxyInputRequests(durableSession, child.retireRequestIds);
diff --git a/packages/eve/src/execution/tasks/child/steps.test.ts b/packages/eve/src/execution/tasks/child/steps.test.ts
index 13ca7ac12..80c950cea 100644
--- a/packages/eve/src/execution/tasks/child/steps.test.ts
+++ b/packages/eve/src/execution/tasks/child/steps.test.ts
@@ -166,6 +166,21 @@ describe("deliverTaskInputResponsesStep", () => {
});
});
+ it("uses the persisted child address after its continuation alias changes", async () => {
+ const childSessionInbox = { sessionId: "original-child", version: 1 };
+ await deliverTaskInputResponsesStep({
+ answer: { ...answer, childSessionInbox },
+ requestIds: ["req-1"],
+ });
+
+ expect(resumeSessionInbox).toHaveBeenCalledWith(
+ childSessionInbox,
+ expect.objectContaining({
+ payload: { inputResponses: [{ optionId: "approve", requestId: "req-1" }] },
+ }),
+ );
+ });
+
it("posts a remote child answer to its narrowed task-input route", async () => {
const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 202 }));
vi.stubGlobal("fetch", fetchMock);
diff --git a/packages/eve/src/execution/tasks/child/steps.ts b/packages/eve/src/execution/tasks/child/steps.ts
index 6d506b709..a79e7cee2 100644
--- a/packages/eve/src/execution/tasks/child/steps.ts
+++ b/packages/eve/src/execution/tasks/child/steps.ts
@@ -329,7 +329,10 @@ export async function deliverTaskInputResponsesStep(input: {
command.payload.inputResponses,
);
} else {
- await resumeSessionInbox(input.answer.childContinuationToken, command);
+ await resumeSessionInbox(
+ input.answer.childSessionInbox ?? input.answer.childContinuationToken,
+ command,
+ );
}
return "delivered";
} catch (error) {
diff --git a/packages/eve/src/execution/tools/subagent/invoke-agent.test.ts b/packages/eve/src/execution/tools/subagent/invoke-agent.test.ts
index f34ab7fa4..a0512d1d6 100644
--- a/packages/eve/src/execution/tools/subagent/invoke-agent.test.ts
+++ b/packages/eve/src/execution/tools/subagent/invoke-agent.test.ts
@@ -307,105 +307,109 @@ describe("background agent invocation routing", () => {
);
});
- it("preserves each child HITL event's coordinates when relaying repeated requests", async () => {
- const childRequest = (input: {
- readonly requestId: string;
- readonly stepIndex: number;
- }): AgentInvocationReply => ({
- callId: "call-1",
- childContinuationToken: "child-continuation",
- childSessionId: "child-1",
- event: {
- requests: [
- {
- action: {
- callId: input.requestId,
- input: {},
- kind: "tool-call",
- toolName: "approval_gate",
+ it.each([false, true])(
+ "preserves child HITL coordinates and routes advertised inboxes: %s",
+ async (advertiseInbox) => {
+ const childRequest = (input: {
+ readonly requestId: string;
+ readonly stepIndex: number;
+ }): AgentInvocationReply => ({
+ callId: "call-1",
+ childContinuationToken: "child-continuation",
+ childSessionId: "child-1",
+ childSessionInbox: advertiseInbox ? { sessionId: "child-1", version: 1 } : undefined,
+ event: {
+ requests: [
+ {
+ action: {
+ callId: input.requestId,
+ input: {},
+ kind: "tool-call",
+ toolName: "approval_gate",
+ },
+ kind: "tool-approval",
+ prompt: "Approve?",
+ requestId: input.requestId,
},
- kind: "tool-approval",
- prompt: "Approve?",
- requestId: input.requestId,
- },
- ],
- sequence: 3,
- stepIndex: input.stepIndex,
- turnId: "turn-child",
- },
- kind: "subagent-input-request",
- subagentName: "research",
- });
- const replies: AgentInvocationReply[] = [
- childRequest({ requestId: "approval-1", stepIndex: 1 }),
- childRequest({ requestId: "approval-2", stepIndex: 2 }),
- {
- kind: "runtime-action-result",
- results: [
- {
- callId: "call-1:research",
- kind: "subagent-result",
- origin: "child",
- output: "done",
- subagentName: "research",
- } as never,
- ],
- },
- ];
- mocks.createHook.mockReturnValue({
- [Symbol.asyncIterator]: () => ({
- next: async () =>
- replies.length > 0
- ? { done: false as const, value: replies.shift()! }
- : { done: true as const, value: undefined },
- }),
- token: "agent-reply",
- });
- mocks.resumeHook.mockImplementation(async () => undefined);
- const from: WorkflowToolRunRef = {
- callId: "call-1",
- execution: "background",
- input: { message: "Find it" },
- runId: "run-1",
- sequence: 0,
- stepIndex: 0,
- toolName: "research",
- turnId: "turn-parent",
- };
- const ctx = { callId: "call-1" } as ToolContext;
- attachWorkflowToolRunContext(ctx, {
- admission: Promise.resolve({ status: "accepted" }),
- from,
- owner: {
- inbox: "owner-inbox",
- },
- });
+ ],
+ sequence: 3,
+ stepIndex: input.stepIndex,
+ turnId: "turn-child",
+ },
+ kind: "subagent-input-request",
+ subagentName: "research",
+ });
+ const replies: AgentInvocationReply[] = [
+ childRequest({ requestId: "approval-1", stepIndex: 1 }),
+ childRequest({ requestId: "approval-2", stepIndex: 2 }),
+ {
+ kind: "runtime-action-result",
+ results: [
+ {
+ callId: "call-1:research",
+ kind: "subagent-result",
+ origin: "child",
+ output: "done",
+ subagentName: "research",
+ } as never,
+ ],
+ },
+ ];
+ mocks.createHook.mockReturnValue({
+ [Symbol.asyncIterator]: () => ({
+ next: async () =>
+ replies.length > 0
+ ? { done: false as const, value: replies.shift()! }
+ : { done: true as const, value: undefined },
+ }),
+ token: "agent-reply",
+ });
+ mocks.resumeHook.mockImplementation(async () => undefined);
+ const from: WorkflowToolRunRef = {
+ callId: "call-1",
+ execution: "background",
+ input: { message: "Find it" },
+ runId: "run-1",
+ sequence: 0,
+ stepIndex: 0,
+ toolName: "research",
+ turnId: "turn-parent",
+ };
+ const ctx = { callId: "call-1" } as ToolContext;
+ attachWorkflowToolRunContext(ctx, {
+ admission: Promise.resolve({ status: "accepted" }),
+ from,
+ owner: {
+ inbox: "owner-inbox",
+ },
+ });
- await expect(
- agent(ctx, { key: "research", message: "Find it", target: "research" }),
- ).resolves.toBe("done");
+ await expect(
+ agent(ctx, { key: "research", message: "Find it", target: "research" }),
+ ).resolves.toBe("done");
- expect(mocks.resumeHook).toHaveBeenNthCalledWith(2, "owner-inbox", {
- kind: "request",
- from,
- replyTo: "child-continuation",
- request: {
- kind: "input-batch",
- requests: [expect.objectContaining({ requestId: "approval-1" })],
- },
- requestCoordinates: { sequence: 3, stepIndex: 1, turnId: "turn-child" },
- });
- expect(mocks.resumeHook).toHaveBeenNthCalledWith(3, "owner-inbox", {
- kind: "request",
- from,
- replyTo: "child-continuation",
- request: {
- kind: "input-batch",
- requests: [expect.objectContaining({ requestId: "approval-2" })],
- },
- requestCoordinates: { sequence: 3, stepIndex: 2, turnId: "turn-child" },
- });
- });
+ expect(mocks.resumeHook).toHaveBeenNthCalledWith(2, "owner-inbox", {
+ kind: "request",
+ from,
+ replyTo: advertiseInbox ? "eve:session:child-1:inbox" : "child-continuation",
+ request: {
+ kind: "input-batch",
+ requests: [expect.objectContaining({ requestId: "approval-1" })],
+ },
+ requestCoordinates: { sequence: 3, stepIndex: 1, turnId: "turn-child" },
+ });
+ expect(mocks.resumeHook).toHaveBeenNthCalledWith(3, "owner-inbox", {
+ kind: "request",
+ from,
+ replyTo: advertiseInbox ? "eve:session:child-1:inbox" : "child-continuation",
+ request: {
+ kind: "input-batch",
+ requests: [expect.objectContaining({ requestId: "approval-2" })],
+ },
+ requestCoordinates: { sequence: 3, stepIndex: 2, turnId: "turn-child" },
+ });
+ },
+ );
it("forwards background authorization as an owner authorization request", async () => {
const replies: AgentInvocationReply[] = [
diff --git a/packages/eve/src/execution/tools/subagent/invoke-agent.ts b/packages/eve/src/execution/tools/subagent/invoke-agent.ts
index 83396e016..123b5ac32 100644
--- a/packages/eve/src/execution/tools/subagent/invoke-agent.ts
+++ b/packages/eve/src/execution/tools/subagent/invoke-agent.ts
@@ -15,6 +15,7 @@ import type { RuntimeSubagentChildResult, RuntimeSubagentResult } from "#shared/
import type { JsonValue } from "#shared/json.js";
import type { JsonObject } from "#shared/json.js";
import { disposeHook } from "#execution/hook-ownership.js";
+import { sessionCommandHookToken } from "#execution/session-command-token.js";
import type { AgentInput } from "#tools/workflow-definition.js";
import type { ToolContext } from "#tools/definition.js";
import type { TaskInboundUpdate } from "#tasks/types.js";
@@ -136,7 +137,10 @@ export async function invokeAgent(
await resumeHookStep(owner.inbox, {
kind: "request",
from: run,
- replyTo: reply.childContinuationToken,
+ replyTo:
+ reply.childSessionInbox?.sessionId === reply.childSessionId
+ ? sessionCommandHookToken(reply.childSessionInbox.sessionId)
+ : reply.childContinuationToken,
request: {
kind: "input-batch",
requests: reply.event.requests,
diff --git a/packages/eve/src/execution/wire/session-inbox-contract.ts b/packages/eve/src/execution/wire/session-inbox-contract.ts
index 3398fc04a..b50fffbb4 100644
--- a/packages/eve/src/execution/wire/session-inbox-contract.ts
+++ b/packages/eve/src/execution/wire/session-inbox-contract.ts
@@ -10,6 +10,28 @@ export const SESSION_INBOX_WIRE_VERSION =
/** Hook metadata field advertising the consumer's inbox wire capability. */
export const SESSION_INBOX_WIRE_VERSION_METADATA_KEY = "sessionInboxWireVersion";
+export const SESSION_INBOX_CONTEXT_KEY = "eve.sessionInbox";
+
+/** Immutable inbox coordinates advertised by the receiving session's driver. */
+export interface SessionInboxAddress {
+ readonly sessionId: string;
+ readonly version: number;
+}
+
+export function isSessionInboxAddress(value: unknown): value is SessionInboxAddress {
+ if (value === null || typeof value !== "object") return false;
+ return (
+ "sessionId" in value &&
+ typeof value.sessionId === "string" &&
+ value.sessionId.length > 0 &&
+ !value.sessionId.includes(":") &&
+ "version" in value &&
+ typeof value.version === "number" &&
+ Number.isSafeInteger(value.version) &&
+ value.version > 0
+ );
+}
+
/**
* The consumer wire selected before a producer persists a payload.
*
diff --git a/packages/eve/src/execution/wire/session-inbox-resume.test.ts b/packages/eve/src/execution/wire/session-inbox-resume.test.ts
index 8eb0aaade..8a2b28bf6 100644
--- a/packages/eve/src/execution/wire/session-inbox-resume.test.ts
+++ b/packages/eve/src/execution/wire/session-inbox-resume.test.ts
@@ -88,6 +88,41 @@ describe("session inbox target resolution", () => {
});
describe("resumeSessionInbox", () => {
+ it.each(SESSION_INBOX_WIRE_VERSIONS)(
+ "uses the persisted consumer version %i without reading hook metadata",
+ async (version) => {
+ await resumeSessionInbox(
+ { sessionId: "child-session", version },
+ { kind: "send", payload: { inputResponses: [{ requestId: "req-1", text: "yes" }] } },
+ );
+
+ expect(getHookByTokenMock).not.toHaveBeenCalled();
+ expect(getRawHookByTokenMock).not.toHaveBeenCalled();
+ expect(resumeHookMock).toHaveBeenCalledWith(
+ sessionCommandHookToken("child-session"),
+ expect.objectContaining({ kind: "deliver", version }),
+ );
+ },
+ );
+
+ it("rejects unsupported saved consumer versions before resuming", async () => {
+ await expect(
+ resumeSessionInbox({ sessionId: "child-session", version: 99 }, { kind: "clear" }),
+ ).rejects.toThrow(/unsupported wire version 99/);
+ expect(getHookByTokenMock).not.toHaveBeenCalled();
+ expect(resumeHookMock).not.toHaveBeenCalled();
+ });
+
+ it("keeps version-sensitive cancellation checks when using a saved address", async () => {
+ await expect(
+ resumeSessionInbox(
+ { sessionId: "child-session", version: 5 },
+ { kind: "cancel", tasks: true },
+ ),
+ ).rejects.toThrow(/Cannot encode session-owned task cancellation/);
+ expect(resumeHookMock).not.toHaveBeenCalled();
+ });
+
it("resumes a compatible stable inbox by token without inspecting metadata", async () => {
const token = sessionCommandHookToken("session-1");
const hook = sessionHook("session-1", token, { sessionInboxWireVersion: 2 });
diff --git a/packages/eve/src/execution/wire/session-inbox-resume.ts b/packages/eve/src/execution/wire/session-inbox-resume.ts
index 60bad8335..aa8908987 100644
--- a/packages/eve/src/execution/wire/session-inbox-resume.ts
+++ b/packages/eve/src/execution/wire/session-inbox-resume.ts
@@ -11,8 +11,10 @@ import {
} from "#execution/session-command-token.js";
import {
SESSION_INBOX_WIRE_VERSION_METADATA_KEY,
+ isSessionInboxAddress,
isSessionInboxWireVersion,
SessionInboxWireError,
+ type SessionInboxAddress,
type SessionInboxWireTarget,
} from "#execution/wire/session-inbox-contract.js";
import { sessionInboxWire } from "#execution/wire/session-inbox-encoder.js";
@@ -23,9 +25,25 @@ type ResumedSessionInboxHook = Awaited<ReturnType<typeof resumeHook>>;
/** Resolves the consumer contract, encodes for it, and resumes that exact hook. */
export async function resumeSessionInbox(
- token: string,
+ address: string | SessionInboxAddress,
command: DeliverHookPayload | SessionCommand | SessionTimeoutHookPayload,
): Promise<ResumedSessionInboxHook> {
+ if (typeof address !== "string") {
+ if (!isSessionInboxAddress(address)) {
+ throw new SessionInboxWireError("Session inbox target has an invalid address.");
+ }
+ if (!isSessionInboxWireVersion(address.version)) {
+ throw new SessionInboxWireError(
+ `Session inbox target declares unsupported wire version ${JSON.stringify(address.version)}.`,
+ );
+ }
+ return await resumeHook(
+ sessionCommandHookToken(address.sessionId),
+ sessionInboxWire.encode(command, { version: address.version }),
+ );
+ }
+
+ const token = address;
if (isStableInboxFastPathCompatible(token, command)) {
return await resumeHook(
token,
diff --git a/packages/eve/src/execution/workflow-entry.test.ts b/packages/eve/src/execution/workflow-entry.test.ts
index ebc081893..0b9eb5ff0 100644
--- a/packages/eve/src/execution/workflow-entry.test.ts
+++ b/packages/eve/src/execution/workflow-entry.test.ts
@@ -28,6 +28,7 @@ import { settleCancelledTurnStep } from "#execution/settle-cancelled-turn-step.j
import { emitTerminalSessionFailureStep } from "#execution/terminal-session-failure-step.js";
import type { SessionInboxPayload } from "#execution/session-command-inbox.js";
import { sessionCommandHookToken } from "#execution/session-command-token.js";
+import { SESSION_INBOX_WIRE_VERSION } from "#execution/wire/session-inbox-contract.js";
import { settleContinuationConflictStep } from "#execution/continuation-conflict-step.js";
vi.mock("#compiled/@workflow/core/index.js", () => ({
@@ -187,7 +188,10 @@ describe("workflowEntry", () => {
const result = await workflowEntry({
input: { message: "hello there" },
- serializedContext: createSerializedContext(),
+ serializedContext: {
+ ...createSerializedContext(),
+ "eve.sessionInbox": { sessionId: "producer-supplied-id", version: 99 },
+ },
});
expect(result).toEqual({ output: "ok" });
@@ -215,6 +219,7 @@ describe("workflowEntry", () => {
"eve.continuationToken": "http:test",
"eve.mode": "conversation",
"eve.sessionId": "wrun_test_123",
+ "eve.sessionInbox": { sessionId: "wrun_test_123", version: SESSION_INBOX_WIRE_VERSION },
}),
sessionState,
}),
diff --git a/packages/eve/src/execution/workflow-entry.ts b/packages/eve/src/execution/workflow-entry.ts
index 1fc490bac..d3cfb0bd3 100644
--- a/packages/eve/src/execution/workflow-entry.ts
+++ b/packages/eve/src/execution/workflow-entry.ts
@@ -45,6 +45,10 @@ import { terminateChildSessionsStep } from "#execution/terminate-child-sessions-
import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
import { attachClientContext, readClientContext } from "#internal/client-context.js";
import { settleContinuationConflictStep } from "#execution/continuation-conflict-step.js";
+import {
+ SESSION_INBOX_CONTEXT_KEY,
+ SESSION_INBOX_WIRE_VERSION,
+} from "#execution/wire/session-inbox-contract.js";
const SAFE_OUTER_WORKFLOW_FAILURE_MESSAGE =
"Agent workflow failed. Inspect the private session trace for details.";
@@ -160,6 +164,11 @@ export async function workflowEntry(input: WorkflowEntryInput): Promise<Workflow
// Seed `eve.sessionId` so the terminal failure emitter can stamp it
// onto `session.failed` even if `createSessionStep` itself throws.
input.serializedContext["eve.sessionId"] = sessionId;
+ // The driver stays pinned while turn steps can move to newer deployments.
+ input.serializedContext[SESSION_INBOX_CONTEXT_KEY] = {
+ sessionId,
+ version: SESSION_INBOX_WIRE_VERSION,
+ };
const driverWritable = getWritable<Uint8Array>();
const crashCleanupState: CrashCleanupState = {
diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.ts
index 1cb809b62..0acc51f1a 100644
--- a/packages/eve/src/execution/workflow-steps.test.ts
+++ b/packages/eve/src/execution/workflow-steps.test.ts
@@ -268,6 +268,46 @@ afterEach(() => {
});
describe("routeProxiedDeliverStep", () => {
+ it("replies to the saved child inbox after its continuation alias changes", async () => {
+ const session = upsertProxyInputRequests({
+ entries: [
+ [
+ "request-1",
+ {
+ childContinuationToken: "stale-alias",
+ childSessionInbox: { sessionId: "original-child", version: 1 },
+ kind: "question",
+ },
+ ],
+ ],
+ forChildContinuationToken: "stale-alias",
+ session: createStubSession({
+ continuationToken: "parent-token",
+ sessionId: "parent-session",
+ }),
+ });
+ installSessionStoreMocks([session]);
+
+ await routeProxiedDeliverStep({
+ parentWritable: createTestWritable(),
+ payload: { inputResponses: [{ requestId: "request-1", text: "yes" }] },
+ sessionState: createStubSessionState({
+ continuationToken: "parent-token",
+ hasProxyInputRequests: true,
+ sessionId: "parent-session",
+ }),
+ });
+
+ expect(resumeHookMock).toHaveBeenCalledWith(
+ "eve:session:original-child:inbox",
+ expect.objectContaining({
+ kind: "deliver",
+ version: 1,
+ payloads: [{ inputResponses: [{ requestId: "request-1", text: "yes" }] }],
+ }),
+ );
+ });
+
it("forwards descendant input responses as session send commands", async () => {
const auth = {
attributes: {},
diff --git a/packages/eve/src/harness/proxy-input-requests.test.ts b/packages/eve/src/harness/proxy-input-requests.test.ts
index d73226e9b..87ab93799 100644
--- a/packages/eve/src/harness/proxy-input-requests.test.ts
+++ b/packages/eve/src/harness/proxy-input-requests.test.ts
@@ -153,6 +153,33 @@ describe("upsertProxyInputRequests", () => {
});
describe("toProxyInputRequestEntries", () => {
+ it("persists the original child's inbox through a session snapshot round trip", () => {
+ const childSessionInbox = { sessionId: "original-child", version: 1 };
+ const entries = toProxyInputRequestEntries({
+ callId: "call-1",
+ childContinuationToken: "reusable-alias",
+ childSessionId: "original-child",
+ childSessionInbox,
+ event: {
+ requests: [createRequest("req-1", "question")],
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "t",
+ },
+ kind: "subagent-input-request",
+ subagentName: "delegate",
+ });
+ const session = upsertProxyInputRequests({
+ entries,
+ forChildContinuationToken: "reusable-alias",
+ session: createSession(),
+ });
+
+ expect(getProxyInputRequests(JSON.parse(JSON.stringify(session.state))).get("req-1")).toEqual(
+ expect.objectContaining({ childSessionInbox }),
+ );
+ });
+
it("records shared batch and approval metadata on every route", () => {
const requests = [
createRequest("question-1", "question"),
diff --git a/packages/eve/src/harness/proxy-input-requests.ts b/packages/eve/src/harness/proxy-input-requests.ts
index 3644c9e87..a6f3fab2b 100644
--- a/packages/eve/src/harness/proxy-input-requests.ts
+++ b/packages/eve/src/harness/proxy-input-requests.ts
@@ -2,6 +2,10 @@ import type { SubagentInputRequestHookPayload } from "#channel/types.js";
import type { HarnessSession, SessionStateMap } from "#harness/types.js";
import type { InputRequestKind } from "#shared/input.js";
import { isLoopbackHostname } from "#shared/network-address.js";
+import {
+ isSessionInboxAddress,
+ type SessionInboxAddress,
+} from "#execution/wire/session-inbox-contract.js";
const PROXY_INPUT_REQUESTS_KEY = "eve.runtime.proxyInputRequests";
@@ -25,6 +29,7 @@ export interface ProxyInputRequest {
/** Batch semantics are optional so sessions written before this field remain routable. */
readonly batch?: ProxyInputRequestBatch;
readonly childContinuationToken: string;
+ readonly childSessionInbox?: SessionInboxAddress;
/** Child-local id restored before forwarding a namespaced task response. */
readonly childRequestId?: string;
/** Trusted parent-derived capability URL for a remote task child. */
@@ -205,6 +210,7 @@ export function toProxyInputRequestEntries(
return payload.event.requests.map((request) => {
const route: {
readonly childContinuationToken: string;
+ childSessionInbox?: SessionInboxAddress;
childResponseUrl?: string;
readonly kind: InputRequestKind;
taskId?: string;
@@ -214,6 +220,9 @@ export function toProxyInputRequestEntries(
kind: request.kind,
};
if (taskId !== undefined) route.taskId = taskId;
+ if (payload.childSessionInbox?.sessionId === payload.childSessionId) {
+ route.childSessionInbox = payload.childSessionInbox;
+ }
return [request.requestId, route] as const;
});
@@ -286,10 +295,14 @@ function parseProxyInputRequest(value: unknown, requestId: string): ProxyInputRe
const batch = "batch" in value ? parseProxyInputRequestBatch(value.batch) : undefined;
const answerHook = "answerHook" in value ? parseAnswerHookRoute(value.answerHook) : undefined;
if ("answerHook" in value && answerHook === undefined) return undefined;
+ const childSessionInbox = "childSessionInbox" in value ? value.childSessionInbox : undefined;
+ if (childSessionInbox !== undefined && !isSessionInboxAddress(childSessionInbox))
+ return undefined;
const request: {
answerHook?: AnswerHookRoute;
batch?: ProxyInputRequestBatch;
readonly childContinuationToken: string;
+ childSessionInbox?: SessionInboxAddress;
childRequestId?: string;
childResponseUrl?: string;
readonly kind: InputRequestKind;
@@ -299,6 +312,7 @@ function parseProxyInputRequest(value: unknown, requestId: string): ProxyInputRe
kind: value.kind,
};
if (answerHook !== undefined) request.answerHook = answerHook;
+ if (childSessionInbox !== undefined) request.childSessionInbox = childSessionInbox;
if (batch !== undefined && batch.requestIds.includes(requestId)) request.batch = batch;
if (typeof childRequestId === "string") request.childRequestId = childRequestId;
if (typeof childResponseUrl === "string") request.childResponseUrl = childResponseUrl;
diff --git a/packages/eve/src/subagents/adapter.test.ts b/packages/eve/src/subagents/adapter.test.ts
index 51547739a..c1d3f2d94 100644
--- a/packages/eve/src/subagents/adapter.test.ts
+++ b/packages/eve/src/subagents/adapter.test.ts
@@ -4,7 +4,7 @@ import { callAdapterEventHandler, type ChannelAdapterContext } from "#channel/ad
import { buildSessionHandle } from "#channel/session.js";
import { type SubagentAdapterState } from "#subagents/adapter-state.js";
import { ContextContainer } from "#context/container.js";
-import { ContinuationTokenKey, SessionIdKey } from "#context/keys.js";
+import { ContinuationTokenKey, SessionIdKey, SessionInboxKey } from "#context/keys.js";
import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import type { InputRequest } from "#shared/input.js";
import { SUBAGENT_ADAPTER } from "#subagents/adapter.js";
@@ -141,6 +141,22 @@ describe("SUBAGENT_ADAPTER authorization handlers", () => {
});
describe("SUBAGENT_ADAPTER input.requested handler", () => {
+ it("advertises the driver version from durable context, even when the adapter is newer", async () => {
+ resumeHookMock.mockClear();
+ const ctx = makeContext();
+ ctx.ctx.set(SessionInboxKey, { sessionId: "child-session", version: 1 });
+
+ await SUBAGENT_INPUT_REQUESTED(
+ { requests: [sampleRequest()], sequence: 0, stepIndex: 0, turnId: "turn-1" },
+ ctx,
+ );
+
+ expect(resumeHookMock).toHaveBeenCalledWith(
+ "parent-token",
+ expect.objectContaining({ childSessionInbox: { sessionId: "child-session", version: 1 } }),
+ );
+ });
+
it("forwards continuation HITL to the newly bound parent turn", async () => {
resumeHookMock.mockClear();
const rebound = await bindTurnCallerContextStep({
diff --git a/packages/eve/src/subagents/adapter.ts b/packages/eve/src/subagents/adapter.ts
index ef834cf02..e325b2aef 100644
--- a/packages/eve/src/subagents/adapter.ts
+++ b/packages/eve/src/subagents/adapter.ts
@@ -6,7 +6,7 @@ import type {
SubagentAuthorizationEventHookPayload,
SubagentInputRequestHookPayload,
} from "#channel/types.js";
-import { ContinuationTokenKey, SessionIdKey } from "#context/keys.js";
+import { ContinuationTokenKey, SessionIdKey, SessionInboxKey } from "#context/keys.js";
import { SUBAGENT_ADAPTER_KIND, isSubagentAdapterState } from "#subagents/adapter-state.js";
import { createErrorId, createLogger } from "#internal/logging.js";
@@ -44,6 +44,7 @@ export const SUBAGENT_ADAPTER: ChannelAdapter = {
callId: state.callId,
childContinuationToken: ctx.ctx.require(ContinuationTokenKey),
childSessionId: ctx.ctx.require(SessionIdKey),
+ childSessionInbox: ctx.ctx.get(SessionInboxKey),
event: {
requests: data.requests,
sequence: data.sequence,
diff --git a/packages/eve/src/subagents/hitl-proxy.test.ts b/packages/eve/src/subagents/hitl-proxy.test.ts
index 64f735f3e..8f87de34e 100644
--- a/packages/eve/src/subagents/hitl-proxy.test.ts
+++ b/packages/eve/src/subagents/hitl-proxy.test.ts
@@ -20,6 +20,54 @@ function createSession(state?: Record<string, unknown>): HarnessSession {
}
describe("routeDeliverPayload", () => {
+ it("keeps original child inboxes separate when they share a continuation alias", () => {
+ const session = upsertProxyInputRequests({
+ entries: [
+ [
+ "req-a",
+ {
+ childContinuationToken: "child-alias",
+ childSessionInbox: { sessionId: "child-a", version: 1 },
+ kind: "question",
+ },
+ ],
+ [
+ "req-b",
+ {
+ childContinuationToken: "child-alias",
+ childSessionInbox: { sessionId: "child-b", version: 1 },
+ kind: "question",
+ },
+ ],
+ ],
+ forChildContinuationToken: "child-alias",
+ session: createSession(),
+ });
+
+ const routed = routeDeliverPayload({
+ payload: {
+ inputResponses: [
+ { requestId: "req-a", text: "A" },
+ { requestId: "req-b", text: "B" },
+ ],
+ },
+ state: session.state,
+ });
+
+ expect(routed.forChildren).toMatchObject([
+ {
+ childContinuationToken: "child-alias",
+ childSessionInbox: { sessionId: "child-a", version: 1 },
+ payload: { inputResponses: [{ requestId: "req-a", text: "A" }] },
+ },
+ {
+ childContinuationToken: "child-alias",
+ childSessionInbox: { sessionId: "child-b", version: 1 },
+ payload: { inputResponses: [{ requestId: "req-b", text: "B" }] },
+ },
+ ]);
+ });
+
it("routes responses to matching descendants and keeps unknown ones on forSelf", () => {
const session = upsertProxyInputRequests({
entries: [["req-a", { childContinuationToken: "child-a", kind: "tool-approval" }]],
diff --git a/packages/eve/src/subagents/hitl-proxy.ts b/packages/eve/src/subagents/hitl-proxy.ts
index c334a709f..9cd3db194 100644
--- a/packages/eve/src/subagents/hitl-proxy.ts
+++ b/packages/eve/src/subagents/hitl-proxy.ts
@@ -1,3 +1,4 @@
+import type { SessionInboxAddress } from "#execution/wire/session-inbox-contract.js";
import type { DeliverPayload, SubagentInputRequestHookPayload } from "#channel/types.js";
import {
emitTurnEpilogue,
@@ -64,6 +65,7 @@ export async function emitProxiedInputRequest(input: {
export interface RoutedChildDelivery {
readonly answerHook?: AnswerHookRoute;
readonly childContinuationToken: string;
+ readonly childSessionInbox?: SessionInboxAddress;
readonly childResponseUrl?: string;
readonly payload: { readonly inputResponses: readonly InputResponse[] };
/** Parent-visible request IDs safe to retire once this bucket is forwarded. */
@@ -87,6 +89,7 @@ export interface RoutedDeliverPayload {
interface ChildResponseBucket {
readonly answerHook?: AnswerHookRoute;
readonly childContinuationToken: string;
+ readonly childSessionInbox?: SessionInboxAddress;
readonly childResponseUrl?: string;
/** Parent-visible request IDs answered in this bucket. */
readonly parentRequestIds: string[];
@@ -120,10 +123,12 @@ export function routeDeliverPayload(input: {
parentAction = { kind: "cancel-turn" };
}
- const bucketKey =
- route.taskId === undefined
- ? route.childContinuationToken
- : `${route.childContinuationToken}\0${route.childResponseUrl ?? "local"}\0${route.taskId}`;
+ const bucketKey = [
+ route.childContinuationToken,
+ route.childSessionInbox?.sessionId ?? "",
+ route.childResponseUrl ?? "local",
+ route.taskId ?? "",
+ ].join("\0");
const existing = responsesByChild.get(bucketKey);
if (existing === undefined) {
@@ -132,6 +137,9 @@ export function routeDeliverPayload(input: {
parentRequestIds: [response.requestId],
responses: [toChildInputResponse(response, route)],
routes: [route],
+ ...(route.childSessionInbox !== undefined && {
+ childSessionInbox: route.childSessionInbox,
+ }),
...(route.answerHook !== undefined && { answerHook: route.answerHook }),
...(route.childResponseUrl !== undefined && { childResponseUrl: route.childResponseUrl }),
...(route.taskId !== undefined && { taskId: route.taskId }),
@@ -147,6 +155,7 @@ export function routeDeliverPayload(input: {
({
answerHook,
childContinuationToken,
+ childSessionInbox,
childResponseUrl,
parentRequestIds,
responses,
@@ -172,6 +181,7 @@ export function routeDeliverPayload(input: {
childContinuationToken,
payload: { inputResponses: responses },
retireRequestIds: [...retireRequestIds],
+ ...(childSessionInbox !== undefined && { childSessionInbox }),
...(answerHook !== undefined && { answerHook }),
...(childResponseUrl !== undefined && { childResponseUrl }),
...(taskId !== undefined && { taskId }),
diff --git a/packages/eve/src/tasks/types.ts b/packages/eve/src/tasks/types.ts
index 17175b596..49516de44 100644
--- a/packages/eve/src/tasks/types.ts
+++ b/packages/eve/src/tasks/types.ts
@@ -3,6 +3,7 @@ import type {
SubagentAuthorizationEventHookPayload,
} from "#channel/types.js";
import type { WorkflowToolAgentRequest } from "#execution/tools/workflow/messages.js";
+import type { SessionInboxAddress } from "#execution/wire/session-inbox-contract.js";
import { jsonValuesEqual, type JsonValue } from "#shared/json.js";
import type { TaskExecutorBinding } from "#tools/task.js";
@@ -171,6 +172,7 @@ export interface TaskInboundInputRequest {
export interface TaskInboundAnswerInput {
readonly auth?: unknown;
readonly childContinuationToken: string;
+ readonly childSessionInbox?: SessionInboxAddress;
readonly childResponseUrl?: string;
readonly inputResponses: readonly {
readonly optionId?: string;
diff --git a/research/session-inbox-wire-schema.md b/research/session-inbox-wire-schema.md
index 6a5239ae3..f657af0f7 100644
--- a/research/session-inbox-wire-schema.md
+++ b/research/session-inbox-wire-schema.md
@@ -1,7 +1,7 @@
---
issue: https://github.com/vercel/eve/issues/1765
status: proposed
-last_updated: "2026-08-31"
+last_updated: "2026-09-04"
---
# Versioned wire schema for the session inbox
@@ -147,11 +147,22 @@ consumer ──decode──────────▶ known version → typed p
consumers. A markerless continuation without the stable inbox identifies eve
≤0.30.4 and receives legacy `deliver`. This tests a concrete historical
capability rather than guessing from deployment or package metadata.
-- **Cost boundary.** Every producer performs one target `getHookByToken`
- before `resumeHook`. Markerless continuation hooks require one additional
- lookup for the stable-inbox capability. `resumeHook` receives the inspected
- hook object, preventing the encoding decision from being applied to a
- different hook that later reused the same token.
+- **Saved receiver addresses.** The pinned driver advertises its canonical
+ session ID and wire version in serialized context. Local subagent input
+ requests save that address with their reply route. A later producer can
+ encode for the original receiver without reading hook metadata, even if a
+ newer deployment handles the reply or the continuation alias changes.
+ Workflow-tool relays carry the stable inbox token in their existing reply
+ field because input answers fit the unversioned `send` contract.
+- **Cost boundary.** Saved receiver addresses and compatible commands to
+ stable inbox tokens skip metadata negotiation and use token-based
+ `resumeHook`, retaining Workflow's backend resume deduplication. Other
+ producers read the target with `getHookByToken`. Markerless continuation
+ hooks require one additional raw ownership lookup for the stable-inbox
+ capability. For these negotiated sends, `resumeHook` receives the inspected
+ hook object so the encoding decision cannot apply to a different hook that
+ later reused the same token. Ownership-only reads use the raw world API;
+ they do not need metadata hydration or an encryption-key lookup.
## Compatibility and payoff timeline