The Open Framework for Building Agents
fix(eve): decouple subagent event publication from model preparation (#3683)
Rui23dda94b05b1
diff --git a/.changeset/fresh-hooks-publish.md b/.changeset/fresh-hooks-publish.mdnew file mode 100644index 000000000..a46c6ebb7--- /dev/null+++ b/.changeset/fresh-hooks-publish.md@@ -0,0 +1,5 @@+---+"eve": patch+---++`subagent.called` and `subagent.completed` hooks can now call `ctx.getSandbox()` for the parent session, and sandbox changes they make are kept for the parent's next turn.diff --git a/docs/guides/hooks.md b/docs/guides/hooks.mdindex 982098144..7c4c98695 100644--- a/docs/guides/hooks.md+++ b/docs/guides/hooks.md@@ -88,7 +88,8 @@ failed stop, follows the normalFor `subagent.called` and `subagent.completed`, `ctx.session.id` identifies theparent session. Typed handlers and `*` handlers receive this context even when-the subagent event arrives between parent turns.+the subagent event arrives between parent turns. These hooks can use+`ctx.getSandbox()` against the parent session.### Narrowing tool results@@ -174,13 +175,15 @@ When a stream event fires, three things happen in order:1. Emit. The channel adapter handler runs, the event is stamped with its `meta` envelope, then it is written to the durable stream.2. Hooks. Stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.-3. Dynamic tool resolvers. Resolvers subscribed to the event type run and update the tool set.+3. Model preparation, for model lifecycle events. Dynamic resolvers subscribed to those events update the model context. Subagent notifications do not run model preparation.Hooks always run after the event is durably recorded, so if a hook throws, the stream stays consistent. The persisted event and every hook observe the same `meta.id`.## What happens when a hook throws-A thrown handler propagates through the emit composer and surfaces as `turn.failed`. In a conversation session, this includes handlers for `turn.started` and the first `step.started` of a model call: the failed turn ends with `session.waiting`, and the next message can start another turn. Task-mode boundary failures remain terminal. If a hook subscribed to a failure-cascade event also throws, it escalates to `session.failed`. For belt-and-suspenders semantics inside a hook, wrap the body in `try`/`catch`. eve treats a thrown hook as a real failure.+A thrown handler during a model turn propagates through turn execution and surfaces as `turn.failed`. In a conversation session, this includes handlers for `turn.started` and the first `step.started` of a model call: the failed turn ends with `session.waiting`, and the next message can start another turn. Task-mode boundary failures remain terminal. If a hook subscribed to a failure-cascade event also throws, it escalates to `session.failed`. For belt-and-suspenders semantics inside a hook, wrap the body in `try`/`catch`. eve treats a thrown hook as a real failure.++For `subagent.called` and `subagent.completed`, a thrown handler fails the notification step and follows the workflow runtime's step retry policy. A retry can publish the event again before rerunning its hooks. Parent execution waits for the notification step to finish or exhaust its retries.## Subagent isolationdiff --git a/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.ts b/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.tsindex ded69e8eb..a12a0eddc 100644--- a/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.ts+++ b/e2e/fixtures/agent-workflow-tools/agent/tools/read_subagent_hooks.ts@@ -5,5 +5,15 @@ 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(),+ async execute(_input, ctx) {+ const sandbox = await ctx.getSandbox();+ return await Promise.all(+ subagentHookAudit.get().map(async (record) => ({+ ...record,+ sandboxCallId: await sandbox.readTextFile({+ path: `subagent-hook-${record.eventId}-${record.subscriber}.txt`,+ }),+ })),+ );+ },});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.tsindex 2b10b6455..d6b177e1f 100644--- a/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts+++ b/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts@@ -3,7 +3,7 @@ import type { SubagentHookObservation } from "../subagent-hook-audit";export default (["direct", "waiting", "background"] as const).map((mode) =>defineEval({- description: `${mode} subagent delegation preserves dynamic skills and delivers hooks with the parent session context.`,+ description: `${mode} subagent hooks preserve parent context, skills, and sandbox writes.`,async test(t) {const initial = await t.send(`Alice asks Bob to review a short report and return his result. SUBAGENT-HOOKS:${mode}`,@@ -68,6 +68,23 @@ export default (["direct", "waiting", "background"] as const).map((mode) =>);},);+ t.eventsSatisfy(+ "hooks receive the exact published event IDs",+ (events) =>+ Array.isArray(observations) &&+ observations.every((record: SubagentHookObservation) =>+ events.some((event) => event.meta.id === record.eventId && event.type === record.type),+ ),+ );+ t.eventsSatisfy(+ "hooks persist parent sandbox files for the next turn",+ () =>+ Array.isArray(observations) &&+ observations.every(+ (record: SubagentHookObservation & { sandboxCallId: string | null }) =>+ record.sandboxCallId === record.callId,+ ),+ );t.event("subagent.called", { data: { name: "workflow-marker" }, count: 1 });t.event("subagent.completed", { data: { subagentName: "workflow-marker" }, count: 1 });t.notEvent("session.failed");diff --git a/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.ts b/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.tsindex dc955b90e..22424a390 100644--- a/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.ts+++ b/e2e/fixtures/agent-workflow-tools/subagent-hook-audit.ts@@ -5,6 +5,7 @@ export interface SubagentHookObservation {readonly subscriber: "typed" | "wildcard";readonly type: "subagent.called" | "subagent.completed";readonly callId: string;+ readonly eventId: string;readonly sessionId: string;readonly output?: string;}@@ -14,21 +15,27 @@ export const subagentHookAudit = defineState<SubagentHookObservation[]>(() => [],);-export function recordSubagentHook(+export async function recordSubagentHook(subscriber: SubagentHookObservation["subscriber"],event: HookEvent,ctx: HookContext,-): void {+): Promise<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.");}+ const sandbox = await ctx.getSandbox();+ await sandbox.writeTextFile({+ path: `subagent-hook-${event.meta.id}-${subscriber}.txt`,+ content: event.data.callId,+ });subagentHookAudit.update((observations) => [...observations,{subscriber,type: event.type,callId: event.data.callId,+ eventId: event.meta.id,sessionId: ctx.session.id,output: event.type === "subagent.completed" ? event.data.output : undefined,},diff --git a/packages/eve/src/execution/route-child-delivery.ts b/packages/eve/src/execution/route-child-delivery.tsindex b88de482c..9fb145772 100644--- a/packages/eve/src/execution/route-child-delivery.ts+++ b/packages/eve/src/execution/route-child-delivery.ts@@ -116,6 +116,7 @@ export async function routeDeliverToChildren(input: {sessionState,});serializedContext = emitted.serializedContext;+ sessionState = emitted.sessionState;}}diff --git a/packages/eve/src/execution/session/event-sink.ts b/packages/eve/src/execution/session/event-sink.tsindex e4034cd0c..41d0f6cba 100644--- a/packages/eve/src/execution/session/event-sink.ts+++ b/packages/eve/src/execution/session/event-sink.ts@@ -1,65 +1,55 @@import { buildAdapterContext } from "#channel/adapter-context.js";import { callAdapterEventHandler, type ChannelAdapter } from "#channel/adapter.js";import type { ContextContainer } from "#context/container.js";-import { dispatchDynamicInstructionEvent } from "#context/dynamic-instruction-lifecycle.js";-import { dispatchDynamicModelEvent } from "#context/dynamic-model-lifecycle.js";-import { dispatchDynamicSkillEvent } from "#context/dynamic-skill-lifecycle.js";-import { dispatchDynamicSubagentEvent } from "#context/dynamic-subagent-lifecycle.js";-import { dispatchDynamicToolEvent } from "#context/dynamic-tool-lifecycle.js";-import { dispatchStreamEventHooks } from "#context/hook-lifecycle.js";import { ScheduleIdKey, TurnDeliveryIdsKey, TurnTaskDeliveryKey } from "#context/keys.js";-import { dispatchMemoryLifecycleEvent } from "#context/memory-event-lifecycle.js";import * as activityCohort from "#execution/activity-cohort.js";import { setChannelContext } from "#execution/channel-context.js";-import { bindDynamicConnections } from "#execution/dynamic-connections.js";-import type { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";import { observeSessionActivity } from "#execution/session-activity-projection.js";import { scheduledLaunchDeliveryEvent } from "#execution/scheduled-launch-delivery.js";import { forwardTaskEventToSessionCallback } from "#execution/task-event-callback.js";-import type { HandleEventFn } from "#harness/types.js";-import type { ExecutionInstrumentation } from "#instrumentation/runtime.js";import {encodeMessageStreamEvent,type MessageStreamEvent,stampMessageStreamEvent,type UnstampedMessageStreamEvent,} from "#protocol/message.js";-import type { CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";export interface SessionEventSinkInput {- readonly abortSignal: AbortSignal | undefined;readonly adapter: ChannelAdapter;- readonly bundle: CompiledBundle;readonly ctx: ContextContainer;- readonly effectiveAgent: ReturnType<typeof resolveEffectiveAgentRuntime>;- readonly instrumentation: ExecutionInstrumentation | undefined;readonly isFirstTurn: boolean;readonly sessionWritable: WritableStream<Uint8Array>;readonly sessionId: string;}+export interface PublishedSessionEvent {+ readonly event: MessageStreamEvent;+ readonly suppressed: boolean;+}+export interface SessionEventSink {readonly adapterCtx: ReturnType<typeof buildAdapterContext>;- readonly dynamicConnections: ReturnType<typeof bindDynamicConnections>;- readonly effectiveNode: CompiledBundle["graph"]["root"];- readonly handleEvent: HandleEventFn;+ emit(event: UnstampedMessageStreamEvent): Promise<PublishedSessionEvent>;/** Closes the parent stream; only a terminal `done` step does this. */close(): Promise<void>;/** Releases the writer lock so the next step can acquire it. Safe after `close()`. */release(): void;}-/** Binds adapter context, dynamic connections, and event fan-out to one step's stream writer. */+/** Publishes events without executing hooks or preparing model context. */export function createSessionEventSink(input: SessionEventSinkInput): SessionEventSink {- const { adapter, bundle, ctx, effectiveAgent, instrumentation } = input;+ const { adapter, ctx } = input;const adapterCtx = buildAdapterContext(adapter, ctx);- const dynamicConnections = bindDynamicConnections(ctx, bundle.resolvedAgent);- const effectiveNode = { ...bundle.graph.root, turnAgent: effectiveAgent.turnAgent };const writer = input.sessionWritable.getWriter();- const emit = async (- event: UnstampedMessageStreamEvent,- ): Promise<{ readonly event: MessageStreamEvent; readonly suppressed: boolean }> => {+ const deliver = async (event: UnstampedMessageStreamEvent): Promise<PublishedSessionEvent> => {+ const forwardedToTaskParent = await forwardTaskEventToSessionCallback(ctx, event);+ if (forwardedToTaskParent) {+ return {+ event: stampMessageStreamEvent(event, ctx.get(TurnDeliveryIdsKey)),+ suppressed: false,+ };+ }const deliverableEvent = scheduledLaunchDeliveryEvent(event, {isFirstTurn: input.isFirstTurn,isScheduled: ctx.get(ScheduleIdKey) !== undefined,@@ -77,62 +67,6 @@ export function createSessionEventSink(input: SessionEventSinkInput): SessionEveawait writer.write(encodeMessageStreamEvent(stamped));return { event: stamped, suppressed: false };};- const handleEvent: HandleEventFn = async (event, messages): Promise<void> => {- activityCohort.updateActivityBlockers(ctx, event);- const forwardedToTaskParent = await forwardTaskEventToSessionCallback(ctx, event);- const emitted = forwardedToTaskParent- ? { event: stampMessageStreamEvent(event, ctx.get(TurnDeliveryIdsKey)), suppressed: false }- : await emit(event);- const lifecycleMessages = await dispatchMemoryLifecycleEvent({- abortSignal: input.abortSignal,- appRoot: effectiveNode.agent?.metadata?.appRoot ?? "",- ctx,- event,- instrumentation: instrumentation?.memory,- memories: effectiveNode.agent?.memories ?? [],- messages,- nodeId: bundle.nodeId ?? "__root__",- });- void observeSessionActivity({ ctx, event: emitted.event, sessionId: input.sessionId });- if (!emitted.suppressed) {- await dispatchStreamEventHooks({ ctx, registry: bundle.hookRegistry, event: emitted.event });- }- if (emitted.event.type !== "step.started") {- await dispatchDynamicModelEvent({- abortSignal: input.abortSignal,- ctx,- dynamicModel: effectiveAgent.turnAgent.dynamicModel,- event: emitted.event,- messages: lifecycleMessages,- scope: { moduleMap: bundle.moduleMap, nodeId: bundle.nodeId },- });- }- await dynamicConnections.dispatch(emitted.event);- await dispatchDynamicSubagentEvent({- ctx,- resolvers: bundle.subagentRegistry.dynamicResolvers ?? [],- event: emitted.event,- messages: lifecycleMessages,- });- await dispatchDynamicToolEvent({- ctx,- resolvers: bundle.resolvedAgent.dynamicToolResolvers ?? [],- event: emitted.event,- messages: lifecycleMessages,- });- await dispatchDynamicSkillEvent({- ctx,- resolvers: bundle.resolvedAgent.dynamicSkillResolvers ?? [],- event: emitted.event,- messages: lifecycleMessages,- });- await dispatchDynamicInstructionEvent({- ctx,- resolvers: bundle.resolvedAgent.dynamicInstructionsResolvers ?? [],- event: emitted.event,- messages: lifecycleMessages,- });- };let released = false;const release = (): void => {@@ -142,13 +76,16 @@ export function createSessionEventSink(input: SessionEventSinkInput): SessionEve};return {adapterCtx,+ async emit(event) {+ activityCohort.updateActivityBlockers(ctx, event);+ const emitted = await deliver(event);+ void observeSessionActivity({ ctx, event: emitted.event, sessionId: input.sessionId });+ return emitted;+ },close: async () => {await writer.close();release();},- dynamicConnections,- effectiveNode,- handleEvent,release,};}diff --git a/packages/eve/src/execution/session/task-settlement.integration.test.ts b/packages/eve/src/execution/session/task-settlement.integration.test.tsindex 57dc942ca..616d59762 100644--- a/packages/eve/src/execution/session/task-settlement.integration.test.ts+++ b/packages/eve/src/execution/session/task-settlement.integration.test.ts@@ -1,7 +1,9 @@import { routeDeliverToChildren } from "#execution/route-child-delivery.js";import { emitSubagentEventStep } from "#execution/tools/subagent/emit-event-step.js";-vi.mock("#execution/tools/subagent/emit-event-step.js", () => ({ emitSubagentEventStep: vi.fn() }));+vi.mock("#execution/tools/subagent/emit-event-step.js", () => ({+ emitSubagentEventStep: vi.fn(),+}));import { expect, it, vi } from "vitest";@@ -24,7 +26,12 @@ import type { TaskView } from "#tasks/types.js";it.each(["completed", "failed", "cancelled"] as const)("records a parked parent's %s task and removes its question before reporting the cohort",async (status) => {- vi.mocked(emitSubagentEventStep).mockReset().mockResolvedValue({ serializedContext: {} });+ vi.mocked(emitSubagentEventStep)+ .mockReset()+ .mockImplementation(async (input) => ({+ serializedContext: {},+ sessionState: input.sessionState,+ }));let state = createTestSessionState();let session = state.snapshot.session;for (const taskId of ["A", "B"]) {@@ -163,7 +170,10 @@ it.each(["completed", "failed", "cancelled"] as const)(findBackgroundWorkflowToolRun(input.sessionState.snapshot.session.state, "task")?.task.outcome,).toEqual({ status: view.status, lastOutput: view.lastOutput, usage: view.usage });- return { serializedContext: input.serializedContext };+ return {+ serializedContext: input.serializedContext,+ sessionState: input.sessionState,+ };});const deliver = async (outcome: TaskView) => {const result = await routeDeliverToChildren({diff --git a/packages/eve/src/execution/session/turn-step.ts b/packages/eve/src/execution/session/turn-step.tsindex 67c946ef2..1529e9567 100644--- a/packages/eve/src/execution/session/turn-step.ts+++ b/packages/eve/src/execution/session/turn-step.ts@@ -1,14 +1,24 @@+import { dispatchDynamicModelEvent } from "#context/dynamic-model-lifecycle.js";+import { dispatchDynamicSkillEvent } from "#context/dynamic-skill-lifecycle.js";+import { dispatchStreamEventHooks } from "#context/hook-lifecycle.js";+import { dispatchMemoryLifecycleEvent } from "#context/memory-event-lifecycle.js";+import { bindDynamicConnections } from "#execution/dynamic-connections.js";import { deriveSessionTitle } from "#execution/eve-workflow-attributes.js";import { setEveAttributes } from "#runtime/attributes/emit.js";import { defaultDeliverResult } from "#channel/adapter.js";-import { contextStorage } from "#context/container.js";+import { contextStorage, type ContextContainer } from "#context/container.js";import {+ dispatchDynamicInstructionEvent,drainDynamicInstructionUserMessages,prepareDynamicInstructionPreamble,} from "#context/dynamic-instruction-lifecycle.js";-import { refreshDynamicSessionSubagentsForRuntimeRevision } from "#context/dynamic-subagent-lifecycle.js";+import {+ dispatchDynamicSubagentEvent,+ refreshDynamicSessionSubagentsForRuntimeRevision,+} from "#context/dynamic-subagent-lifecycle.js";import { drainMemoryCommit, prepareMemoryPreamble } from "#context/memory-lifecycle.js";import {+ dispatchDynamicToolEvent,rebindMissingCompiledDynamicToolCallbacks,refreshDynamicSessionToolsForRuntimeRevision,} from "#context/dynamic-tool-lifecycle.js";@@ -28,7 +38,11 @@ import {TaskDeliveryPolicyKey,TurnDeliveryIdsKey,} from "#context/keys.js";-import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";+import {+ BundleKey,+ ChannelKey,+ type CompiledBundle,+} from "#runtime/sessions/runtime-context-keys.js";import { deserializeContext, serializeContext } from "#context/serialize.js";import {emitTurnPreamble,@@ -36,7 +50,10 @@ import {isHarnessBetweenTurns,setHarnessEmissionState,} from "#harness/emission.js";-import { bindSessionInstrumentation } from "#instrumentation/runtime.js";+import {+ bindSessionInstrumentation,+ type ExecutionInstrumentation,+} from "#instrumentation/runtime.js";import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";import * as agentTraceState from "#tracing/agent-trace-context-store.js";import { matchAuthorizationCallbacks } from "#execution/authorization-callback-match.js";@@ -50,10 +67,10 @@ import {type UserModelMessage,} from "#harness/messages.js";import { consumeDeferredStepInput } from "#harness/pending-input-batches.js";-import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";+import type { HandleEventFn, HarnessSession, StepInput, StepResult } from "#harness/types.js";import type { DurableStepResult, TurnStepInput } from "#execution/session/turn-step-types.js";import { resolveSessionStepResult } from "#execution/session/turn-step-result.js";-import { createSessionEventSink } from "#execution/session/event-sink.js";+import { createSessionEventSink, type SessionEventSink } from "#execution/session/event-sink.js";import { derivePendingState } from "#execution/session/pending-turn-state.js";import {createAuthorizationCompletedEvent,@@ -235,18 +252,26 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>await instrumentation?.flush();};const sink = createSessionEventSink({- abortSignal: input.abortSignal,adapter,- bundle,ctx,- effectiveAgent,- instrumentation,isFirstTurn: initialEmissionState.sequence === 0,sessionWritable: input.sessionWritable,sessionId: initialSession.sessionId,});- const { adapterCtx, dynamicConnections, effectiveNode, handleEvent } = sink;+ const { adapterCtx } = sink;try {+ const dynamicConnections = bindDynamicConnections(ctx, bundle.resolvedAgent);+ const effectiveNode = { ...bundle.graph.root, turnAgent: effectiveAgent.turnAgent };+ const handleEvent = createTurnEventHandler({+ abortSignal: input.abortSignal,+ bundle,+ ctx,+ dynamicConnections,+ effectiveAgent,+ effectiveNode,+ instrumentation,+ sink,+ });const previousAdapterState =delivery !== undefined && !isHarnessBetweenTurns(initialSession)? structuredClone(adapterCtx.state)@@ -600,3 +625,68 @@ async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult>sink.release();}}++/** Publishes one turn event, then runs memory, hooks, and model preparation for it. */+function createTurnEventHandler(input: {+ readonly abortSignal: AbortSignal | undefined;+ readonly bundle: CompiledBundle;+ readonly ctx: ContextContainer;+ readonly dynamicConnections: ReturnType<typeof bindDynamicConnections>;+ readonly effectiveAgent: ReturnType<typeof resolveEffectiveAgentRuntime>;+ readonly effectiveNode: CompiledBundle["graph"]["root"];+ readonly instrumentation: ExecutionInstrumentation | undefined;+ readonly sink: SessionEventSink;+}): HandleEventFn {+ const { abortSignal, bundle, ctx, effectiveAgent, effectiveNode } = input;+ return async (event, messages) => {+ const emitted = await input.sink.emit(event);+ const lifecycleMessages = await dispatchMemoryLifecycleEvent({+ abortSignal,+ appRoot: effectiveNode.agent?.metadata?.appRoot ?? "",+ ctx,+ event,+ instrumentation: input.instrumentation?.memory,+ memories: effectiveNode.agent?.memories ?? [],+ messages,+ nodeId: bundle.nodeId ?? "__root__",+ });+ if (!emitted.suppressed) {+ await dispatchStreamEventHooks({ ctx, registry: bundle.hookRegistry, event: emitted.event });+ }+ if (emitted.event.type !== "step.started") {+ await dispatchDynamicModelEvent({+ abortSignal,+ ctx,+ dynamicModel: effectiveAgent.turnAgent.dynamicModel,+ event: emitted.event,+ messages: lifecycleMessages,+ scope: { moduleMap: bundle.moduleMap, nodeId: bundle.nodeId },+ });+ }+ await input.dynamicConnections.dispatch(emitted.event);+ await dispatchDynamicSubagentEvent({+ ctx,+ resolvers: bundle.subagentRegistry.dynamicResolvers ?? [],+ event: emitted.event,+ messages: lifecycleMessages,+ });+ await dispatchDynamicToolEvent({+ ctx,+ resolvers: bundle.resolvedAgent.dynamicToolResolvers ?? [],+ event: emitted.event,+ messages: lifecycleMessages,+ });+ await dispatchDynamicSkillEvent({+ ctx,+ resolvers: bundle.resolvedAgent.dynamicSkillResolvers ?? [],+ event: emitted.event,+ messages: lifecycleMessages,+ });+ await dispatchDynamicInstructionEvent({+ ctx,+ resolvers: bundle.resolvedAgent.dynamicInstructionsResolvers ?? [],+ event: emitted.event,+ messages: lifecycleMessages,+ });+ };+}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 8cf5a2758..7bcdcb93e 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,6 +1,6 @@import { beforeEach, expect, it, vi } from "vitest";-import { ContextContainer, loadContext } from "#context/container.js";+import { ContextContainer, contextStorage, loadContext } from "#context/container.js";import {AuthKey,DynamicSkillManifestKey,@@ -10,7 +10,10 @@ import {SessionTitleKey,} from "#context/keys.js";import { deserializeContext, serializeContext } from "#context/serialize.js";+import { createEmptyHookRegistry } from "#runtime/hooks/registry.js";import { emitSubagentEventStep } from "#execution/tools/subagent/emit-event-step.js";+import { createSessionEventSink } from "#execution/session/event-sink.js";+import { createStubSandboxRegistry } from "#internal/testing/stub-sandbox-registry.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";@@ -88,6 +91,9 @@ it.each(expect(received.type).toBe(event.type);if (received.type === "subagent.completed") expect(received.data.output).toBe("done");expect(loadContext()).toBe(ctx);+ expect(stream.locked).toBe(false);+ expect(received).toEqual(JSON.parse(new TextDecoder().decode(chunks[0])));+ expect(ctx.has(SandboxKey)).toBe(true);calls.push(kind);if (fails) throw new Error("subagent subscriber failed");ctx.set(SessionTitleKey, "Research event received");@@ -105,13 +111,22 @@ it.each(events: handlers,},]);- ctx.set(BundleKey, {- graph: { root: {} },- resolvedAgent: { config: {} },- turnAgent: { id: "parent" },- subagentRegistry: {},+ const bundle: Partial<CompiledBundle> = {+ graph: {+ root: { nodeId: "__root__", sandboxRegistry: createStubSandboxRegistry() },+ } as CompiledBundle["graph"],+ resolvedAgent: { config: {} } as CompiledBundle["resolvedAgent"],+ turnAgent: {+ id: "parent",+ model: { id: "openai/gpt-5.5" },+ tools: [],+ instructions: [],+ workspaceSpec: { rootEntries: [] },+ },+ compiledArtifactsSource: { kind: "bundled" },hookRegistry,- } as CompiledBundle);+ };+ ctx.set(BundleKey, bundle as CompiledBundle);vi.mocked(deserializeContext).mockResolvedValue(ctx);vi.mocked(serializeContext).mockImplementation((context) =>Object.fromEntries([...context.entries()].map(([key, value]) => [key.name, value])),@@ -119,15 +134,18 @@ it.each(const chunks: Uint8Array[] = [];const stream = new WritableStream<Uint8Array>({write(chunk) {+ expect(ctx.has(SessionKey)).toBe(true);+ expect(ctx.has(SandboxKey)).toBe(true);calls.push("stream");chunks.push(chunk);},});+ const sessionState = createTestSessionState({ sessionId: "parent" });const emitted = emitSubagentEventStep({event,sessionWritable: stream,serializedContext: {},- sessionState: createTestSessionState({ sessionId: "parent" }),+ sessionState,});const firstHandler = subscription === "wildcard" ? "wildcard" : "typed";if (fails) {@@ -137,6 +155,8 @@ it.each(const result = await emitted;expect(result.serializedContext[SessionTitleKey.name]).toBe("Research event received");expect(result.serializedContext[SessionKey.name]).toBeUndefined();+ expect(result.serializedContext[SandboxKey.name]).toBeUndefined();+ expect(result.sessionState.snapshot.session.sandboxState).toEqual({ session: null });expect(result.serializedContext[DynamicSkillManifestKey.name]).toEqual(ctx.require(DynamicSkillManifestKey),);@@ -153,3 +173,124 @@ it.each(expect(stream.locked).toBe(false);},);++it.each(events)(+ "the event sink publishes $type without preparing hook or model context",+ async (event) => {+ const ctx = new ContextContainer();+ ctx.set(SessionIdKey, "parent");+ ctx.set(AuthKey, null);+ ctx.set(ChannelKey, { kind: "test" });+ const hook = vi.fn(() => {+ throw new Error("publication invoked a hook");+ });+ const bundle: Partial<CompiledBundle> = {+ get graph(): never {+ throw new Error("publication read model configuration");+ },+ hookRegistry: createRuntimeHookRegistry([+ {+ slug: "audit",+ logicalPath: "hooks/audit.ts",+ sourceId: "hooks/audit.ts",+ sourceKind: "module",+ exportName: undefined,+ events: { "*": hook },+ },+ ]),+ };+ ctx.set(BundleKey, bundle as CompiledBundle);+ const chunks: Uint8Array[] = [];+ const stream = new WritableStream<Uint8Array>({+ write(chunk) {+ chunks.push(chunk);+ },+ });+ const sink = createSessionEventSink({+ adapter: ctx.require(ChannelKey),+ ctx,+ isFirstTurn: false,+ sessionWritable: stream,+ sessionId: "parent",+ });+ try {+ await contextStorage.run(ctx, () => sink.emit(event));+ } finally {+ sink.release();+ }+ expect(hook).not.toHaveBeenCalled();+ expect(ctx.has(SessionKey)).toBe(false);+ expect(ctx.has(SandboxKey)).toBe(false);+ expect(chunks).toHaveLength(1);+ expect(stream.locked).toBe(false);+ },+);++it("fails hook context setup before publishing so a retry cannot duplicate the event", async () => {+ const ctx = new ContextContainer();+ ctx.set(SessionIdKey, "parent");+ ctx.set(AuthKey, null);+ ctx.set(ChannelKey, { kind: "test" });+ const hook = vi.fn();+ const bundle: Partial<CompiledBundle> = {+ resolvedAgent: { config: {} } as CompiledBundle["resolvedAgent"],+ turnAgent: { id: "parent" } as CompiledBundle["turnAgent"],+ hookRegistry: createRuntimeHookRegistry([+ {+ slug: "audit",+ logicalPath: "hooks/audit.ts",+ sourceId: "hooks/audit.ts",+ sourceKind: "module",+ exportName: undefined,+ events: { "*": hook },+ },+ ]),+ };+ ctx.set(BundleKey, bundle as CompiledBundle);+ vi.mocked(deserializeContext).mockResolvedValue(ctx);+ const chunks: Uint8Array[] = [];+ const stream = new WritableStream<Uint8Array>({+ write(chunk) {+ chunks.push(chunk);+ },+ });+ await expect(+ emitSubagentEventStep({+ event: events[0]!,+ sessionWritable: stream,+ serializedContext: {},+ sessionState: { ...createTestSessionState({ sessionId: "parent" }), version: 0 as never },+ }),+ ).rejects.toThrow("Unsupported session checkpoint");+ expect(chunks).toHaveLength(0);+ expect(hook).not.toHaveBeenCalled();+ expect(stream.locked).toBe(false);+});++it("does not prepare context when no hook subscribes to the published event", async () => {+ const ctx = new ContextContainer();+ ctx.set(SessionIdKey, "parent");+ ctx.set(AuthKey, null);+ ctx.set(ChannelKey, { kind: "test" });+ const bundle: Partial<CompiledBundle> = {+ hookRegistry: createEmptyHookRegistry(),+ get turnAgent(): never {+ throw new Error("unsubscribed event prepared runtime context");+ },+ };+ ctx.set(BundleKey, bundle as CompiledBundle);+ vi.mocked(deserializeContext).mockResolvedValue(ctx);+ vi.mocked(serializeContext).mockReturnValue({ channel: true });+ const input = {+ event: events[0]!,+ sessionWritable: new WritableStream<Uint8Array>(),+ serializedContext: { channel: true },+ sessionState: createTestSessionState({ sessionId: "parent" }),+ };+ expect(await emitSubagentEventStep(input)).toEqual({+ serializedContext: input.serializedContext,+ sessionState: input.sessionState,+ });+ expect(ctx.has(SessionKey)).toBe(false);+ expect(ctx.has(SandboxKey)).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 f2f3fdd83..464e19b70 100644--- a/packages/eve/src/execution/tools/subagent/emit-event-step.ts+++ b/packages/eve/src/execution/tools/subagent/emit-event-step.ts@@ -1,40 +1,79 @@-import { sessionProvider } from "#context/providers/session.js";+import { dispatchStreamEventHooks } from "#context/hook-lifecycle.js";+import { withContextScope } from "#context/run-step.js";+import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";+import { hydrateDurableSession } from "#execution/session.js";+import { reconcileSessionContinuationToken } from "#execution/reconcile-session-continuation-token.js";import { contextStorage } from "#context/container.js";import { deserializeContext, serializeContext } from "#context/serialize.js";-import { readDurableSession, type DurableSessionState } from "#execution/durable-session-store.js";-import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";-import { createSessionEventSink } from "#execution/session/event-sink.js";+import {+ createDurableSessionState,+ readDurableSession,+ type DurableSessionState,+} from "#execution/durable-session-store.js";+import {+ createSessionEventSink,+ type PublishedSessionEvent,+} from "#execution/session/event-sink.js";import type { UnstampedMessageStreamEvent } from "#protocol/message.js";import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";-/** Emits an agent invocation event on the parent stream. */+/** Publishes a subagent notification, then runs its hooks without model preparation. */export async function emitSubagentEventStep(input: {readonly event: UnstampedMessageStreamEvent;readonly sessionWritable: WritableStream<Uint8Array>;readonly serializedContext: Record<string, unknown>;readonly sessionState: DurableSessionState;-}): Promise<{ readonly serializedContext: Record<string, unknown> }> {+}): Promise<{+ readonly serializedContext: Record<string, unknown>;+ readonly sessionState: DurableSessionState;+}> {"use step";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),- bundle,- ctx,- effectiveAgent: resolveEffectiveAgentRuntime(bundle, ctx),- instrumentation: undefined,- isFirstTurn: input.sessionState.emissionState.sequence === 0,- sessionWritable: input.sessionWritable,- sessionId: session.sessionId,- });- try {- await contextStorage.run(ctx, () => sink.handleEvent(input.event, session.history));- } finally {- sink.release();+ const publish = async (): Promise<PublishedSessionEvent> => {+ const sink = createSessionEventSink({+ adapter: ctx.require(ChannelKey),+ ctx,+ isFirstTurn: input.sessionState.emissionState.sequence === 0,+ sessionWritable: input.sessionWritable,+ sessionId: input.sessionState.sessionId,+ });+ try {+ return await contextStorage.run(ctx, () => sink.emit(input.event));+ } finally {+ sink.release();+ }+ };+ // Decided before publishing to prevent duplicate events: subscribed events+ // prepare hook context before the write, so a setup failure retries this step+ // without having published. Unsubscribed events skip that setup entirely.+ const registry = bundle.hookRegistry;+ if (+ (registry.streamEventsByType.get(input.event.type)?.length ?? 0) === 0 &&+ registry.streamEventsWildcard.length === 0+ ) {+ await publish();+ return { serializedContext: serializeContext(ctx), sessionState: input.sessionState };}- return { serializedContext: serializeContext(ctx) };++ const effectiveAgent = resolveEffectiveAgentRuntime(bundle, ctx);+ const session = hydrateDurableSession({+ durable: readDurableSession(input.sessionState),+ turnAgent: effectiveAgent.turnAgent,+ compactionOverrides: { thresholdPercent: effectiveAgent.thresholdPercent },+ });+ const scoped = await withContextScope(ctx, session, async (enriched) => {+ const emitted = await publish();+ if (!emitted.suppressed) {+ await dispatchStreamEventHooks({ ctx, registry, event: emitted.event });+ }+ return { result: undefined, session: enriched };+ });+ return {+ serializedContext: serializeContext(ctx),+ sessionState: createDurableSessionState({+ session: reconcileSessionContinuationToken(ctx, scoped.session),+ }),+ };}diff --git a/packages/eve/src/execution/tools/subagent/task-agent-requests.test.ts b/packages/eve/src/execution/tools/subagent/task-agent-requests.test.tsindex 4331a745e..728e61b40 100644--- a/packages/eve/src/execution/tools/subagent/task-agent-requests.test.ts+++ b/packages/eve/src/execution/tools/subagent/task-agent-requests.test.ts@@ -34,7 +34,7 @@ const result: RuntimeSubagentChildResult = {subagentName: "research",};-beforeEach(() => vi.clearAllMocks());+beforeEach(() => vi.resetAllMocks());describe("workflow-owned agent requests", () => {it("reuses the settlement step's flushed trace context during workflow replay", async () => {@@ -65,33 +65,50 @@ describe("workflow-owned agent requests", () => {expect(replay).toEqual(settled);});- it("emits completion and acknowledges only after settlement", async () => {- const updatedState = { sessionId: "updated" } as never;- vi.mocked(settleTaskAgentInvocationStep).mockResolvedValue({- settled: true,- completion: {- type: "subagent.completed",+ it.each([false, true])(+ "waits for notification hooks before acknowledgement and retains their state (fails: %s)",+ async (fails) => {+ const updatedState = { sessionId: "updated" } as never;+ const hookState = { sessionId: "hooked" } as never;+ const completion = {+ type: "subagent.completed" as const,data: { callId: "nested", subagentName: "research", output: "done" },- },- serializedContext: {},- sessionState: updatedState,- });- const publication = Promise.withResolvers<{ serializedContext: Record<string, unknown> }>();- vi.mocked(emitSubagentEventStep).mockReturnValue(publication.promise);- const applying = applyTaskAgentRequest(- { ownerId: "workflow-run", replyTo: "reply", request: { kind: "agent-settled", result } },- { sessionWritable: {} as never, serializedContext: {}, sessionState },- );- await vi.waitFor(() => expect(emitSubagentEventStep).toHaveBeenCalledOnce());- expect(resumeHookStep).not.toHaveBeenCalled();- publication.resolve({ serializedContext: {} });- expect((await applying).sessionState).toBe(updatedState);- expect(resumeHookStep).toHaveBeenCalledExactlyOnceWith(- "reply",- { kind: "agent-settled", callId: "nested" },- { ifPresent: true },- );- });+ };+ vi.mocked(settleTaskAgentInvocationStep).mockResolvedValue({+ settled: true,+ completion,+ serializedContext: {},+ sessionState: updatedState,+ });+ const notification =+ Promise.withResolvers<Awaited<ReturnType<typeof emitSubagentEventStep>>>();+ vi.mocked(emitSubagentEventStep).mockReturnValue(notification.promise);+ const applying = applyTaskAgentRequest(+ { ownerId: "workflow-run", replyTo: "reply", request: { kind: "agent-settled", result } },+ { sessionWritable: {} as never, serializedContext: {}, sessionState },+ );+ await vi.waitFor(() => expect(emitSubagentEventStep).toHaveBeenCalledOnce());+ expect(resumeHookStep).not.toHaveBeenCalled();+ if (fails) {+ const rejected = expect(applying).rejects.toThrow("hook failed");+ notification.reject(new Error("hook failed"));+ await rejected;+ expect(emitSubagentEventStep).toHaveBeenCalledOnce();+ expect(resumeHookStep).not.toHaveBeenCalled();+ } else {+ notification.resolve({ serializedContext: { hook: true }, sessionState: hookState });+ expect(await applying).toEqual({+ serializedContext: { hook: true },+ sessionState: hookState,+ });+ expect(resumeHookStep).toHaveBeenCalledExactlyOnceWith(+ "reply",+ { kind: "agent-settled", callId: "nested" },+ { ifPresent: true },+ );+ }+ },+ );it("does not acknowledge a failed settlement", async () => {vi.mocked(settleTaskAgentInvocationStep).mockRejectedValue(new Error("write failed"));@@ -123,7 +140,10 @@ describe("workflow-owned agent requests", () => {kind: "dispatched",sessionState,});- vi.mocked(emitSubagentEventStep).mockResolvedValue({ serializedContext });+ vi.mocked(emitSubagentEventStep).mockResolvedValue({+ sessionState,+ serializedContext,+ });const applied = await applyTaskAgentRequest({diff --git a/packages/eve/src/execution/tools/subagent/task-agent-requests.ts b/packages/eve/src/execution/tools/subagent/task-agent-requests.tsindex 80ad967fe..8f24d94cd 100644--- a/packages/eve/src/execution/tools/subagent/task-agent-requests.ts+++ b/packages/eve/src/execution/tools/subagent/task-agent-requests.ts@@ -45,6 +45,7 @@ export async function applyTaskAgentRequest(taskId: delivery.taskId,});let serializedContext = settled.serializedContext;+ let sessionState = settled.sessionState;if (settled.completion !== undefined) {const emitted = await emitSubagentEventStep({event: settled.completion,@@ -53,6 +54,7 @@ export async function applyTaskAgentRequest(sessionState: settled.sessionState,});serializedContext = emitted.serializedContext;+ sessionState = emitted.sessionState;}await resumeHookStep(delivery.replyTo,@@ -61,7 +63,7 @@ export async function applyTaskAgentRequest();return {serializedContext,- sessionState: settled.sessionState,+ sessionState,};}case "agent-invoke": {@@ -75,16 +77,12 @@ export async function applyTaskAgentRequest(});switch (dispatched.kind) {case "dispatched": {- const emitted = await emitSubagentEventStep({+ return await emitSubagentEventStep({event: dispatched.event,sessionWritable: ctx.sessionWritable,serializedContext: dispatched.serializedContext ?? ctx.serializedContext,sessionState: dispatched.sessionState,});- return {- serializedContext: emitted.serializedContext,- sessionState: dispatched.sessionState,- };}case "failed":await resumeHookStep(delivery.replyTo, {