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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.jimport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): ProxyInputReconst 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): ProxyInputRekind: 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.tsindex 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/adimport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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/1765status: 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 pconsumers. A markerless continuation without the stable inbox identifies eve≤0.30.4 and receives legacy `deliver`. This tests a concrete historicalcapability 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