The Open Framework for Building Agents
fix(eve): restore parent session context for subagent hooks (#3565)
Ruiffb12769fd43
diff --git a/.changeset/tidy-subagent-hook-context.md b/.changeset/tidy-subagent-hook-context.mdnew file mode 100644index 000000000..c50f131f6--- /dev/null+++ b/.changeset/tidy-subagent-hook-context.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Fix background subagent calls failing the parent session when typed or wildcard hooks subscribe to subagent events. These hooks now receive the parent session context after workflow step boundaries.diff --git a/docs/guides/hooks.md b/docs/guides/hooks.mdindex 070cdf06b..982098144 100644--- a/docs/guides/hooks.md+++ b/docs/guides/hooks.md@@ -86,6 +86,10 @@ handle can also automatically resume on later I/O. A hook failure, including afailed stop, follows the normal[hook failure behavior](#what-happens-when-a-hook-throws).+For `subagent.called` and `subagent.completed`, `ctx.session.id` identifies the+parent session. Typed handlers and `*` handlers receive this context even when+the subagent event arrives between parent turns.+### Narrowing tool results`toolResultFrom` narrows an `action.result` event to a specific authored tool or MCP connection and returns typed output. Import it from `eve/tools`:diff --git a/e2e/fixtures/agent-workflow-tools/agent/agent.ts b/e2e/fixtures/agent-workflow-tools/agent/agent.tsindex 5b4c6c537..41e189991 100644--- a/e2e/fixtures/agent-workflow-tools/agent/agent.ts+++ b/e2e/fixtures/agent-workflow-tools/agent/agent.ts@@ -7,6 +7,42 @@ import { mockModel, type MockModelRequest, type MockModelResponse } from "eve/ev* service "api"; once the turn holds a tool result the reply echoes it.*/function respond(request: MockModelRequest): MockModelResponse | string {+ const hookScenario = request.userMessages.find((entry) => entry.includes("SUBAGENT-HOOKS:"));+ if (hookScenario !== undefined) {+ const mode = /SUBAGENT-HOOKS:(direct|waiting|background)/u.exec(hookScenario)?.[1];+ if (request.lastUserMessage?.includes("SUBAGENT-HOOKS:AUDIT")) {+ const audit = request.toolResults.find((entry) => entry.name === "read_subagent_hooks");+ return audit === undefined+ ? { toolCalls: [{ name: "read_subagent_hooks", input: {} }] }+ : JSON.stringify(audit.output);+ }+ const tool =+ mode === "direct"+ ? "workflow-marker"+ : mode === "waiting"+ ? "blocking_agent"+ : "background_agent";+ if (!request.toolResults.some((entry) => entry.name === tool)) {+ return {+ toolCalls: [+ {+ name: tool,+ input:+ mode === "direct" ? { message: "Alice's hook audit" } : { service: "hook-audit" },+ },+ ],+ };+ }+ const delivery = [...request.userMessages]+ .reverse()+ .find((entry) => entry.startsWith("[Task state]\n") || entry.startsWith("Background task "));+ const result = request.toolResults.find((entry) => entry.name === tool);+ return (+ delivery ??+ (typeof result?.output === "string" ? result.output : JSON.stringify(result?.output))+ );+ }+const message =[...request.userMessages].reverse()diff --git a/e2e/fixtures/agent-workflow-tools/agent/hooks/subagent-audit.ts b/e2e/fixtures/agent-workflow-tools/agent/hooks/subagent-audit.tsnew file mode 100644index 000000000..cc1a6ddd0--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/agent/hooks/subagent-audit.ts@@ -0,0 +1,10 @@+import { defineHook } from "eve/hooks";+import { recordSubagentHook } from "../../subagent-hook-audit";++export default defineHook({+ events: {+ "subagent.called": (event, ctx) => recordSubagentHook("typed", event, ctx),+ "subagent.completed": (event, ctx) => recordSubagentHook("typed", event, ctx),+ "*": (event, ctx) => recordSubagentHook("wildcard", event, ctx),+ },+});diff --git a/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.ts b/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.tsnew file mode 100644index 000000000..ded69e8eb--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.ts@@ -0,0 +1,9 @@+import { defineTool } from "eve/tools";+import { z } from "zod";+import { subagentHookAudit } from "../../subagent-hook-audit";++export default defineTool({+ description: "Read the parent session's durable subagent hook observations.",+ inputSchema: z.strictObject({}),+ execute: () => subagentHookAudit.get(),+});diff --git a/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts b/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.tsnew file mode 100644index 000000000..f0e8907b7--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts@@ -0,0 +1,69 @@+import { defineEval } from "eve/evals";+import type { SubagentHookObservation } from "../subagent-hook-audit";++export default (["direct", "waiting", "background"] as const).map((mode) =>+ defineEval({+ description: `${mode} subagent delegation delivers typed and wildcard hooks with the parent session context.`,+ async test(t) {+ const initial = await t.send(+ `Alice asks Bob to review a short report and return his result. SUBAGENT-HOOKS:${mode}`,+ );+ initial.expectOk();+ const marker =+ mode === "direct"+ ? "Alice's hook audit"+ : `hook-audit:${mode === "waiting" ? "blocking" : "background"}`;+ const completed =+ mode === "waiting"+ ? initial+ : await t.target+ .watchTurn(initial.sessionId, { startIndex: initial.session.state.streamIndex })+ .result();+ completed.expectOk();+ completed.messageIncludes(marker);++ const audit = await completed.session.send(+ "Alice reviews the recorded hook observations for Bob's completed report. SUBAGENT-HOOKS:AUDIT",+ );+ audit.expectOk();+ audit.calledTool("read_subagent_hooks", { count: 1, status: "completed" });+ const observations = audit.toolCalls.find(+ (call) => call.name === "read_subagent_hooks",+ )?.output;+ t.eventsSatisfy(+ "both hook subscriptions receive the parent's exact child result once",+ (events) => {+ if (!Array.isArray(observations) || observations.length !== 4) return false;+ const completion = events.find((event) => event.type === "subagent.completed");+ if (completion?.type !== "subagent.completed") return false;+ if (!completion.data.output.startsWith("WORKFLOW-CHILD:")) return false;+ if (!completed.message?.includes(completion.data.output)) return false;+ const records = observations as SubagentHookObservation[];+ return (+ records.every(+ (record) =>+ record.sessionId === initial.sessionId && record.callId === completion.data.callId,+ ) &&+ (["typed", "wildcard"] as const).every(+ (subscriber) =>+ records.filter(+ (record) => record.subscriber === subscriber && record.type === "subagent.called",+ ).length === 1 &&+ records.filter(+ (record) =>+ record.subscriber === subscriber &&+ record.type === "subagent.completed" &&+ record.output === completion.data.output,+ ).length === 1,+ )+ );+ },+ );+ t.event("subagent.called", { data: { name: "workflow-marker" }, count: 1 });+ t.event("subagent.completed", { data: { subagentName: "workflow-marker" }, count: 1 });+ t.notEvent("session.failed");+ t.noFailedActions();+ t.succeeded();+ },+ }),+);diff --git a/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.ts b/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.tsnew file mode 100644index 000000000..dc955b90e--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.ts@@ -0,0 +1,36 @@+import { defineState } from "eve/context";+import type { HookContext, HookEvent } from "eve/hooks";++export interface SubagentHookObservation {+ readonly subscriber: "typed" | "wildcard";+ readonly type: "subagent.called" | "subagent.completed";+ readonly callId: string;+ readonly sessionId: string;+ readonly output?: string;+}++export const subagentHookAudit = defineState<SubagentHookObservation[]>(+ "workflow-fixture.subagent-hook-audit",+ () => [],+);++export function recordSubagentHook(+ subscriber: SubagentHookObservation["subscriber"],+ event: HookEvent,+ ctx: HookContext,+): void {+ if (event.type !== "subagent.called" && event.type !== "subagent.completed") return;+ if (event.type === "subagent.called" && ctx.session.id !== event.data.sessionId) {+ throw new Error("Subagent hook received a different parent session.");+ }+ subagentHookAudit.update((observations) => [+ ...observations,+ {+ subscriber,+ type: event.type,+ callId: event.data.callId,+ sessionId: ctx.session.id,+ output: event.type === "subagent.completed" ? event.data.output : undefined,+ },+ ]);+}diff --git a/packages/eve/src/context/providers/session.ts b/packages/eve/src/context/providers/session.tsindex c446429bc..67566560e 100644--- a/packages/eve/src/context/providers/session.ts+++ b/packages/eve/src/context/providers/session.ts@@ -6,12 +6,14 @@ import {SessionIdKey,SessionKey,} from "#context/keys.js";+import type { ContextReader } from "#context/key.js";+import type { HarnessSession } from "#harness/types.js";import type { FrameworkContextProvider } from "#context/provider.js";import { getHarnessEmissionState } from "#harness/emission.js";-export const sessionProvider: FrameworkContextProvider<Session> = {+export const sessionProvider = {key: SessionKey,- create(ctx, session) {+ create(ctx: ContextReader, session: Pick<HarnessSession, "state">) {const currentAuth = ctx.require(AuthKey);const emission = getHarnessEmissionState(session.state);const turnId = emission.turnId.length > 0 ? emission.turnId : `turn_${emission.sequence}`;@@ -28,4 +30,4 @@ export const sessionProvider: FrameworkContextProvider<Session> = {}),};},-};+} satisfies FrameworkContextProvider<Session>;diff --git a/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts b/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.tsindex 13c78ea6b..1d9a2207c 100644--- a/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts+++ b/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts@@ -1,10 +1,12 @@import { beforeEach, expect, it, vi } from "vitest";import { ContextContainer, loadContext } from "#context/container.js";-import { SessionIdKey, SessionKey, SessionTitleKey } from "#context/keys.js";+import { AuthKey, SessionIdKey, SessionKey, SessionTitleKey } from "#context/keys.js";import { deserializeContext, serializeContext } from "#context/serialize.js";import { emitSubagentEventStep } from "#execution/tools/subagent/emit-event-step.js";import { createTestSessionState } from "#internal/testing/session-state.js";+import type { MessageStreamEvent, UnstampedMessageStreamEvent } from "#protocol/message.js";+import type { HookContext, HookEvent, StreamEventHook } from "#public/definitions/hook.js";import { createRuntimeHookRegistry } from "#runtime/hooks/registry.js";import {BundleKey,@@ -19,46 +21,71 @@ vi.mock("#context/serialize.js", () => ({beforeEach(() => vi.resetAllMocks());-it.each([false, true])(- "delivers completion to typed and wildcard hooks and releases the writer (hook fails: %s)",- async (fails) => {+const events: UnstampedMessageStreamEvent[] = [+ {+ type: "subagent.called",+ data: {+ callId: "call",+ name: "research",+ toolName: "research",+ sessionId: "parent",+ childSessionId: "child",+ childStreamPath: "/child",+ workflowId: "workflow",+ turnId: "turn",+ sequence: 0,+ },+ },+ {+ type: "subagent.completed",+ data: { callId: "call", subagentName: "research", output: "done" },+ },+];++it.each(+ events.flatMap((event) =>+ (["typed", "wildcard", "both"] as const).flatMap((subscription) =>+ [false, true].map((fails) => ({ event, subscription, fails })),+ ),+ ),+)(+ "restores parent context for $event.type ($subscription, hook fails: $fails)",+ async ({ event, subscription, fails }) => {const calls: string[] = [];const ctx = new ContextContainer();ctx.set(SessionIdKey, "parent");- ctx.set(SessionKey, {- sessionId: "parent",- auth: { current: null, initiator: null },- turn: { id: "turn", sequence: 0 },- });+ ctx.set(AuthKey, null);+ // SessionKey is virtual: a production deserializer cannot restore it.+ expect(ctx.has(SessionKey)).toBe(false);ctx.set(ChannelKey, {kind: "test",state: {},- "subagent.completed"(_data, adapterCtx) {+ [event.type](_data: unknown, adapterCtx: { state: unknown }) {calls.push("adapter");- adapterCtx.state = { completed: true };+ adapterCtx.state = { delivered: true };},});+ const handler = (kind: string) => async (received: HookEvent, hookCtx: HookContext) => {+ expect(hookCtx.session.id).toBe("parent");+ expect(hookCtx.session.auth).toEqual({ current: null, initiator: null });+ expect(received.type).toBe(event.type);+ if (received.type === "subagent.completed") expect(received.data.output).toBe("done");+ expect(loadContext()).toBe(ctx);+ calls.push(kind);+ if (fails) throw new Error("subagent subscriber failed");+ ctx.set(SessionTitleKey, "Research event received");+ };+ const handlers: Record<string, StreamEventHook<MessageStreamEvent>> = {};+ if (subscription !== "wildcard") handlers[event.type] = handler("typed");+ if (subscription !== "typed") handlers["*"] = handler("wildcard");const hookRegistry = createRuntimeHookRegistry([{- slug: "completion",- logicalPath: "hooks/completion.ts",- sourceId: "hooks/completion.ts",+ slug: "subagent-events",+ logicalPath: "hooks/subagent-events.ts",+ sourceId: "hooks/subagent-events.ts",sourceKind: "module",exportName: undefined,- events: {- "subagent.completed": async (event, hookCtx) => {- expect(hookCtx.session.id).toBe("parent");- if (event.type !== "subagent.completed") throw new Error("Unexpected event type");- expect(event.data.output).toBe("done");- expect(loadContext()).toBe(ctx);- calls.push("typed");- if (fails) throw new Error("completion subscriber failed");- ctx.set(SessionTitleKey, "Completed research");- },- "*": async (event) => {- calls.push(`wildcard:${event.type}`);- },- },+ events: handlers,},]);ctx.set(BundleKey, {@@ -69,10 +96,9 @@ it.each([false, true])(hookRegistry,} as CompiledBundle);vi.mocked(deserializeContext).mockResolvedValue(ctx);- vi.mocked(serializeContext).mockImplementation((context) => ({- title: context.get(SessionTitleKey),- channelState: context.get(ChannelKey)?.state,- }));+ vi.mocked(serializeContext).mockImplementation((context) =>+ Object.fromEntries([...context.entries()].map(([key, value]) => [key.name, value])),+ );const chunks: Uint8Array[] = [];const stream = new WritableStream<Uint8Array>({write(chunk) {@@ -81,25 +107,29 @@ it.each([false, true])(},});const emitted = emitSubagentEventStep({- event: {- type: "subagent.completed",- data: { callId: "call", subagentName: "research", output: "done" },- },+ event,sessionWritable: stream,serializedContext: {},sessionState: createTestSessionState({ sessionId: "parent" }),});+ const firstHandler = subscription === "wildcard" ? "wildcard" : "typed";if (fails) {- await expect(emitted).rejects.toThrow("completion subscriber failed");- expect(calls).toEqual(["adapter", "stream", "typed"]);+ await expect(emitted).rejects.toThrow("subagent subscriber failed");+ expect(calls).toEqual(["adapter", "stream", firstHandler]);} else {- await expect(emitted).resolves.toEqual({- serializedContext: { title: "Completed research", channelState: { completed: true } },- });- expect(calls).toEqual(["adapter", "stream", "typed", "wildcard:subagent.completed"]);+ const result = await emitted;+ expect(result.serializedContext[SessionTitleKey.name]).toBe("Research event received");+ expect(result.serializedContext[SessionKey.name]).toBeUndefined();+ expect(ctx.require(ChannelKey).state).toEqual({ delivered: true });+ expect(calls).toEqual([+ "adapter",+ "stream",+ firstHandler,+ ...(subscription === "both" ? ["wildcard"] : []),+ ]);}expect(chunks).toHaveLength(1);- expect(new TextDecoder().decode(chunks[0])).toContain('"type":"subagent.completed"');+ expect(new TextDecoder().decode(chunks[0])).toContain(`"type":"${event.type}"`);expect(stream.locked).toBe(false);},);diff --git a/packages/eve/src/execution/tools/subagent/emit-event-step.ts b/packages/eve/src/execution/tools/subagent/emit-event-step.tsindex 5ac31aede..f2f3fdd83 100644--- a/packages/eve/src/execution/tools/subagent/emit-event-step.ts+++ b/packages/eve/src/execution/tools/subagent/emit-event-step.ts@@ -1,3 +1,4 @@+import { sessionProvider } from "#context/providers/session.js";import { contextStorage } from "#context/container.js";import { deserializeContext, serializeContext } from "#context/serialize.js";import { readDurableSession, type DurableSessionState } from "#execution/durable-session-store.js";@@ -18,6 +19,7 @@ export async function emitSubagentEventStep(input: {const ctx = await deserializeContext(input.serializedContext);const bundle = ctx.require(BundleKey);const session = readDurableSession(input.sessionState);+ ctx.setVirtualContext(sessionProvider.key, sessionProvider.create(ctx, session).value);const sink = createSessionEventSink({abortSignal: undefined,adapter: ctx.require(ChannelKey),