The Open Framework for Building Agents
fix(eve): align internal AI SDK step lifecycle hooks with the current `onStepStart` and `onStepEnd` callback names (#3274)
Felix Arntzc5bb66f7edd8
diff --git a/.changeset/quiet-step-hooks.md b/.changeset/quiet-step-hooks.mdnew file mode 100644index 000000000..2eea10038--- /dev/null+++ b/.changeset/quiet-step-hooks.md@@ -0,0 +1,5 @@+---+"eve": patch+---++fix(eve): align internal AI SDK step lifecycle hooks with the current `onStepStart` and `onStepEnd` callback namesdiff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.tsindex eb178c256..f1b492940 100644--- a/packages/eve/src/execution/node-step.test.ts+++ b/packages/eve/src/execution/node-step.test.ts@@ -61,20 +61,31 @@ function setupMockAgentForToolExecution(toolName: string, args: unknown): void {const prepareStep = settings.prepareStep as| ((...args: unknown[]) => Promise<unknown>)| undefined;- const onStepFinish = settings.onStepFinish as+ const onStepStart = settings.onStepStart as| ((...args: unknown[]) => Promise<unknown>)| undefined;+ const onStepEnd = settings.onStepEnd as ((...args: unknown[]) => Promise<unknown>) | undefined;this.generate = vi.fn().mockImplementation(async (options: { messages: unknown[] }) => {+ let preparedMessages = options.messages;if (prepareStep) {- await prepareStep({+ const prepared = await prepareStep({messages: options.messages,steps: [],stepNumber: 0,model: {},context: undefined,});+ if (+ prepared !== null &&+ typeof prepared === "object" &&+ "messages" in prepared &&+ Array.isArray(prepared.messages)+ ) {+ preparedMessages = prepared.messages;+ }}+ if (onStepStart) await onStepStart({ messages: preparedMessages });const tools = (settings as {@@ -106,7 +117,7 @@ function setupMockAgentForToolExecution(toolName: string, args: unknown): void {usage: undefined,};- if (onStepFinish) await onStepFinish(result);+ if (onStepEnd) await onStepEnd(result);return { ...result, responseMessages: result.response.messages };});diff --git a/packages/eve/src/harness/step-hooks.test.ts b/packages/eve/src/harness/step-hooks.test.tsnew file mode 100644index 000000000..b07c8b729--- /dev/null+++ b/packages/eve/src/harness/step-hooks.test.ts@@ -0,0 +1,65 @@+import type { ModelMessage } from "ai";+import { describe, expect, it, vi } from "vitest";+import { buildStepHooks } from "#harness/step-hooks.js";+import type { HarnessEmissionState } from "#harness/emission.js";+import type { HarnessSession } from "#harness/types.js";++const emissionState: HarnessEmissionState = {+ sequence: 0,+ sessionStarted: true,+ stepIndex: 0,+ turnId: "turn_0",+};++function createSession(): HarnessSession {+ return {+ agent: {+ modelReference: { id: "test-model" },+ system: "test",+ tools: [],+ },+ compaction: { recentWindowSize: 10, threshold: 100_000 },+ continuationToken: "http:test",+ history: [],+ sessionId: "session-test",+ };+}++describe("buildStepHooks", () => {+ it("emits step.started from onStepStart, not prepareStep", async () => {+ const emit = vi.fn(async () => {});+ const hooks = buildStepHooks({+ cachePath: { kind: "none" },+ emit,+ emissionState,+ marker: undefined,+ session: createSession(),+ });+ const messages: ModelMessage[] = [{ content: "hello", role: "user" }];++ await hooks.prepareStep({+ messages,+ model: {} as never,+ instructions: undefined,+ initialInstructions: undefined,+ initialMessages: [],+ responseMessages: [],+ runtimeContext: {},+ toolsContext: {},+ experimental_sandbox: undefined,+ stepNumber: 0,+ steps: [],+ });+ expect(emit).not.toHaveBeenCalled();++ await Reflect.apply(hooks.onStepStart, null, [{ messages }]);++ expect(emit).toHaveBeenCalledWith(+ {+ data: { modelId: "test-model", sequence: 0, stepIndex: 0, turnId: "turn_0" },+ type: "step.started",+ },+ messages,+ );+ });+});diff --git a/packages/eve/src/harness/step-hooks.ts b/packages/eve/src/harness/step-hooks.tsindex e771d8199..325b01ad8 100644--- a/packages/eve/src/harness/step-hooks.ts+++ b/packages/eve/src/harness/step-hooks.ts@@ -1,5 +1,6 @@import type {ContentPart,+ GenerateTextOnStepStartCallback,LanguageModelUsage,ModelMessage,PrepareStepFunction,@@ -56,7 +57,7 @@ import { AuthKey } from "#context/keys.js";/*** The subset of `StepResult` that the harness reads after a step completes.*- * Used by both the streaming (`onStepFinish` callback) and non-streaming+ * Used by both the streaming (`onStepEnd` callback) and non-streaming* (`generateText` result) code paths.*/export type HarnessStepResult = Pick<@@ -86,7 +87,7 @@ interface StepHooksInput {readonly emit?: HarnessEmitFn;readonly emissionState: HarnessEmissionState;/**- * When `false`, `prepareStep` skips the `step.started` emission.+ * When `false`, `onStepStart` skips the `step.started` emission.* Used by the harness recovery path to avoid emitting `step.started`* twice when retrying the same step with a degraded toolset.*@@ -102,23 +103,30 @@ interface StepHooksInput {*/interface StepHooks {/**- * `ToolLoopAgent` `onStepFinish` callback.+ * `ToolLoopAgent` `onStepStart` callback.+ *+ * Emits the `step.started` event from the prepared step input.+ */+ readonly onStepStart: GenerateTextOnStepStartCallback<ToolSet>;++ /**+ * `ToolLoopAgent` `onStepEnd` callback.** Emits `actions.requested`, `action.result`, and `step.completed` events* from the captured step result.*/- readonly onStepFinish: (step: StepResult<ToolSet>) => Promise<void>;+ readonly onStepEnd: (step: StepResult<ToolSet>) => Promise<void>;/*** `ToolLoopAgent` `prepareStep` callback.*- * Handles `step.started` emission and cache/provider metadata. Compaction- * happens in the tool-loop before `agent.stream()`.+ * Handles cache/provider metadata. Compaction happens in the tool-loop+ * before `agent.stream()`.*/readonly prepareStep: PrepareStepFunction<ToolSet>;/**- * Promise that resolves when `onStepFinish` has completed.+ * Promise that resolves when `onStepEnd` has completed.** Await this after consuming the stream to ensure all step events* have been emitted before proceeding to post-step handling.@@ -130,7 +138,7 @@ interface StepHooks {** Never settles when the step does not finish — e.g. the AI SDK's* incomplete-stream rejection (`NoOutputGeneratedError`) skips- * `onStepFinish` entirely. Consumers must surface stream errors as+ * `onStepEnd` entirely. Consumers must surface stream errors as* throws before awaiting this promise (`emitStreamContent` does), or* the await hangs.*/@@ -142,7 +150,7 @@ interface StepHooks {// ---------------------------------------------------------------------------/**- * Builds composable `prepareStep` and `onStepFinish` closures that+ * Builds composable `onStepStart`, `prepareStep`, and `onStepEnd` closures that* own all step-internal work: emission, compaction, and prompt caching.** The harness passes these hooks to `ToolLoopAgent` and reads the@@ -160,8 +168,8 @@ export function buildStepHooks(input: StepHooksInput): StepHooks {// -------------------------------------------------------------------------// prepareStep//- // Only handles step.started emission and cache/provider metadata. Compaction- // runs in the tool-loop before `agent.stream()` so the compacted messages+ // Only handles cache/provider metadata. Compaction runs in the tool-loop+ // before `agent.stream()` so the compacted messages// flow through the same `messages` variable the harness uses to rebuild// session history — no prepareStep snapshot required.// -------------------------------------------------------------------------@@ -169,15 +177,6 @@ export function buildStepHooks(input: StepHooksInput): StepHooks {const prepareStep: PrepareStepFunction<ToolSet> = async ({ messages }) => {let processed = messages;- if (emit && input.emitStepStarted !== false) {- await emitStepStarted(- emit,- input.emissionState,- requireSessionModelReference(session).id,- messages,- );- }-if (input.cachePath.kind === "anthropic-direct" && input.marker) {processed = applyConversationCacheControl([...messages], input.marker);}@@ -205,10 +204,22 @@ export function buildStepHooks(input: StepHooksInput): StepHooks {return stepResult;};+ const onStepStart: GenerateTextOnStepStartCallback<ToolSet> = async ({ messages }) => {+ if (emit && input.emitStepStarted !== false) {+ await emitStepStarted(+ emit,+ input.emissionState,+ requireSessionModelReference(session).id,+ messages,+ );+ }+ };+return {- onStepFinish: async (step: StepResult<ToolSet>): Promise<void> => {+ onStepEnd: async (step: StepResult<ToolSet>): Promise<void> => {resolveStep(step);},+ onStepStart,prepareStep,stepResult,};diff --git a/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts b/packages/eve/src/harness/tool-loop-compaction-accounting.test.tsindex 262e860d1..0254d47a9 100644--- a/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts+++ b/packages/eve/src/harness/tool-loop-compaction-accounting.test.ts@@ -59,7 +59,8 @@ function createTestConfig(overrides?: Partial<ToolLoopHarnessConfig>): ToolLoopH}type MockAgentSettings = {- onStepFinish?: (step: unknown) => Promise<void> | void;+ onStepStart?: (input: unknown) => Promise<void> | void;+ onStepEnd?: (step: unknown) => Promise<void> | void;prepareStep?: (input: unknown) => Promise<unknown> | unknown;};@@ -88,7 +89,7 @@ function setupMockAgentSequence(results: readonly Record<string, unknown>[]): vothis: Record<string, unknown>,settings: MockAgentSettings,) {- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, onStepStart, prepareStep } = settings;this.generate = vi.fn().mockImplementation(async (options: { messages: unknown[] }) => {const result = queue.shift();@@ -96,8 +97,9 @@ function setupMockAgentSequence(results: readonly Record<string, unknown>[]): vothrow new Error("No mock ToolLoopAgent result available.");}+ let preparedMessages = options.messages;if (prepareStep) {- await prepareStep({+ const prepared = await prepareStep({messages: options.messages,model: {},runtimeContext: {},@@ -105,10 +107,19 @@ function setupMockAgentSequence(results: readonly Record<string, unknown>[]): vosteps: [],toolsContext: {},});+ if (+ prepared !== null &&+ typeof prepared === "object" &&+ "messages" in prepared &&+ Array.isArray(prepared.messages)+ ) {+ preparedMessages = prepared.messages;+ }}+ await onStepStart?.({ messages: preparedMessages });- if (onStepFinish) {- await onStepFinish(result);+ if (onStepEnd) {+ await onStepEnd(result);}return { ...result, responseMessages: getMockResponseMessages(result) };diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.tsindex 9a4148a7d..0e1337a5f 100644--- a/packages/eve/src/harness/tool-loop.test.ts+++ b/packages/eve/src/harness/tool-loop.test.ts@@ -547,7 +547,8 @@ async function* createMockFullStream(}type MockAgentSettings = {- onStepFinish?: (step: unknown) => Promise<void> | void;+ onStepStart?: (input: unknown) => Promise<void> | void;+ onStepEnd?: (step: unknown) => Promise<void> | void;output?: unknown;prepareStep?: (input: unknown) => Promise<unknown> | unknown;};@@ -558,42 +559,51 @@ type MockAgentConstructor =: never;type MockAgentInstance = ToolLoopAgent & Record<string, unknown>;+async function invokeMockStepStart(+ settings: MockAgentSettings,+ options: { readonly messages: unknown[] },+): Promise<void> {+ let preparedMessages = options.messages;+ if (settings.prepareStep) {+ const prepared = await settings.prepareStep({+ messages: options.messages,+ steps: [],+ stepNumber: 0,+ model: {},+ context: undefined,+ });+ if (+ prepared !== null &&+ typeof prepared === "object" &&+ "messages" in prepared &&+ Array.isArray(prepared.messages)+ ) {+ preparedMessages = prepared.messages;+ }+ }+ await settings.onStepStart?.({ messages: preparedMessages });+}+function setupMockAgent(result: Record<string, unknown>): void {vi.mocked(ToolLoopAgent).mockImplementation(function (this: Record<string, unknown>,settings: MockAgentSettings,) {- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd } = settings;this.generate = vi.fn().mockImplementation(async (options: { messages: unknown[] }) => {- if (prepareStep) {- await prepareStep({- messages: options.messages,- steps: [],- stepNumber: 0,- model: {},- context: undefined,- });- }- if (onStepFinish) await onStepFinish(result);+ await invokeMockStepStart(settings, options);+ if (onStepEnd) await onStepEnd(result);return createMockGenerateResult(result);});this.stream = vi.fn().mockImplementation(async (options: { messages: unknown[] }) => {- if (prepareStep) {- await prepareStep({- messages: options.messages,- steps: [],- stepNumber: 0,- model: {},- context: undefined,- });- }+ await invokeMockStepStart(settings, options);const mockResult = createMockStreamResult(result);- // Schedule onStepFinish to fire after a microtask so the stream+ // Schedule onStepEnd to fire after a microtask so the stream// can start being consumed first by emitStreamContent.- if (onStepFinish) {- void Promise.resolve().then(() => onStepFinish(result));+ if (onStepEnd) {+ void Promise.resolve().then(() => onStepEnd(result));}return mockResult;});@@ -612,18 +622,10 @@ function setupMockAgentSequence(results: readonly Record<string, unknown>[]): voif (result === undefined) {throw new Error("ToolLoopAgent mock exhausted its scripted results.");}- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd } = settings;this.generate = vi.fn().mockImplementation(async (options: { messages: unknown[] }) => {- if (prepareStep) {- await prepareStep({- messages: options.messages,- steps: [],- stepNumber: 0,- model: {},- context: undefined,- });- }- if (onStepFinish) await onStepFinish(result);+ await invokeMockStepStart(settings, options);+ if (onStepEnd) await onStepEnd(result);return createMockGenerateResult(result);});return this;@@ -4318,7 +4320,7 @@ describe("createToolLoopHarness", () => {});});- it("propagates streamed cancellation without waiting for onStepFinish or emitting failures", async () => {+ it("propagates streamed cancellation without waiting for onStepEnd or emitting failures", async () => {const abortController = new AbortController();const abortReason = new TurnCancelledError();@@ -4411,7 +4413,7 @@ describe("createToolLoopHarness", () => {this: ToolLoopAgent,settings: MockAgentSettings,) {- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, prepareStep } = settings;this.generate = modelCallMock.mockImplementation(async (options: { messages: unknown[] }) => {if (prepareStep) {await prepareStep({@@ -4425,8 +4427,8 @@ describe("createToolLoopHarness", () => {if (modelCallMock.mock.calls.length === 1) {throw timeout;}- if (onStepFinish) {- void Promise.resolve().then(() => onStepFinish(success));+ if (onStepEnd) {+ void Promise.resolve().then(() => onStepEnd(success));}return createMockGenerateResult(success);});@@ -4919,7 +4921,7 @@ describe("createToolLoopHarness", () => {this: Record<string, unknown>,settings: MockAgentSettings,) {- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, prepareStep } = settings;const isFirst = constructionIndex === 0;constructionIndex += 1;if (isFirst) {@@ -4963,7 +4965,7 @@ describe("createToolLoopHarness", () => {context: undefined,});}- if (onStepFinish) await onStepFinish(input.successResult);+ if (onStepEnd) await onStepEnd(input.successResult);return input.successResult;});this.stream = vi.fn().mockImplementation(async (options: { messages: unknown[] }) => {@@ -4977,8 +4979,8 @@ describe("createToolLoopHarness", () => {});}const mockResult = createMockStreamResult(input.successResult);- if (onStepFinish) {- void Promise.resolve().then(() => onStepFinish(input.successResult));+ if (onStepEnd) {+ void Promise.resolve().then(() => onStepEnd(input.successResult));}return mockResult;});@@ -7517,7 +7519,7 @@ describe("createToolLoopHarness", () => {});/*- * Override the agent mock so `onStepFinish` receives a class+ * Override the agent mock so `onStepEnd` receives a class* instance — matching the AI SDK runtime shape — instead of the* plain object produced by `setupMockAgent`. This is what makes* the getter trap reachable from the test.@@ -7526,7 +7528,7 @@ describe("createToolLoopHarness", () => {this: Record<string, unknown>,settings: MockAgentSettings,) {- const { onStepFinish } = settings;+ const { onStepEnd } = settings;this.stream = vi.fn().mockImplementation(async () => {const stepInstance = new FakeStepResult();const fullStream = createExplicitMockFullStream([@@ -7539,8 +7541,8 @@ describe("createToolLoopHarness", () => {{ id: "text-1", text: "`/workspace`", type: "text-delta" },{ finishReason: "stop", type: "finish-step" },]);- if (onStepFinish) {- void Promise.resolve().then(() => onStepFinish(stepInstance as unknown));+ if (onStepEnd) {+ void Promise.resolve().then(() => onStepEnd(stepInstance as unknown));}return {fullStream,@@ -8264,7 +8266,7 @@ describe("createToolLoopHarness", () => {>;},) {- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, prepareStep } = settings;const executeStatus = settings.tools?.["status"]?.execute;if (executeStatus === undefined) {throw new Error("status tool was not executable.");@@ -8309,7 +8311,7 @@ describe("createToolLoopHarness", () => {toolCalls: [toolCall],toolResults: [toolResult],};- if (onStepFinish) await onStepFinish(result);+ if (onStepEnd) await onStepEnd(result);return createMockGenerateResult(result);});return this;@@ -8430,7 +8432,7 @@ describe("createToolLoopHarness", () => {if (result === undefined) {throw new Error("ToolLoopAgent mock exhausted its scripted results.");}- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, prepareStep } = settings;this.generate = vi.fn().mockImplementation(async (input: { messages: unknown[] }) => {if (prepareStep) {await prepareStep({@@ -8442,7 +8444,7 @@ describe("createToolLoopHarness", () => {});}generateCalls.push(input.messages as Array<{ role: string; content: unknown }>);- if (onStepFinish) await onStepFinish(result);+ if (onStepEnd) await onStepEnd(result);return createMockGenerateResult(result);});return this;@@ -8567,7 +8569,7 @@ describe("createToolLoopHarness", () => {this: MockAgentInstance,settings: MockAgentSettings,) {- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, prepareStep } = settings;this.generate = vi.fn().mockImplementation(async (input: { messages: unknown[] }) => {if (prepareStep) {await prepareStep({@@ -8579,7 +8581,7 @@ describe("createToolLoopHarness", () => {});}generateCalls.push(input.messages as Array<{ role: string; content: unknown }>);- if (onStepFinish) await onStepFinish(stillHere);+ if (onStepEnd) await onStepEnd(stillHere);return createMockGenerateResult(stillHere);});return this;@@ -8663,7 +8665,7 @@ describe("createToolLoopHarness", () => {this: Record<string, unknown>,settings: MockAgentSettings,) {- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, prepareStep } = settings;this.generate = vi.fn().mockImplementation(async (input: { messages: unknown[] }) => {if (prepareStep) {await prepareStep({@@ -8682,7 +8684,7 @@ describe("createToolLoopHarness", () => {toolCalls: [],toolResults: [],};- if (onStepFinish) await onStepFinish(result);+ if (onStepEnd) await onStepEnd(result);return createMockGenerateResult(result);});return this as unknown as ToolLoopAgent;@@ -8943,7 +8945,7 @@ describe("createToolLoopHarness", () => {if (result === undefined) {throw new Error("ToolLoopAgent mock exhausted its scripted results.");}- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, prepareStep } = settings;this.generate = vi.fn().mockImplementation(async (input: { messages: unknown[] }) => {if (prepareStep) {await prepareStep({@@ -8955,7 +8957,7 @@ describe("createToolLoopHarness", () => {});}generateCalls.push(input.messages as Array<{ role: string; content: unknown }>);- if (onStepFinish) await onStepFinish(result);+ if (onStepEnd) await onStepEnd(result);return createMockGenerateResult(result);});return this as unknown as ToolLoopAgent;@@ -9135,7 +9137,7 @@ describe("createToolLoopHarness", () => {) {const result = agentResults[resultIndex++];if (result === undefined) throw new Error("ToolLoopAgent mock exhausted its results.");- const { onStepFinish, prepareStep } = settings;+ const { onStepEnd, prepareStep } = settings;this.generate = vi.fn().mockImplementation(async (input: { messages: unknown[] }) => {if (prepareStep) {await prepareStep({@@ -9147,7 +9149,7 @@ describe("createToolLoopHarness", () => {});}generateCalls.push(input.messages as Array<{ content: unknown; role: string }>);- if (onStepFinish) await onStepFinish(result);+ if (onStepEnd) await onStepEnd(result);return createMockGenerateResult(result);});return this;diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.tsindex d34b86ab4..ae20716ee 100644--- a/packages/eve/src/harness/tool-loop.ts+++ b/packages/eve/src/harness/tool-loop.ts@@ -1472,7 +1472,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {if (summarizeKnownError(event.error)?.tags.includes("config") === true) return;logError(log, "tool-loop stream error", event.error);},- onStepFinish: hooks.onStepFinish,+ onStepEnd: hooks.onStepEnd,+ onStepStart: hooks.onStepStart,prepareStep: hooks.prepareStep,reasoning: session.agent.reasoning,runtimeContext: telemetryRuntimeContext,@@ -2332,7 +2333,7 @@ function isEmptyModelResponse(step: HarnessStepResult): boolean {* (vercel/ai#15938) a stream that closes after metadata without output or* a finish chunk rejects — the SDK enqueues the error onto `fullStream`* (so `emitStreamContent` throws it) and never emits `finish-step`, so- * `onStepFinish` does not fire and the step hooks' `stepResult` promise+ * `onStepEnd` does not fire and the step hooks' `stepResult` promise* would never settle. The same condition previously completed as an empty* step caught by {@link isEmptyModelResponse}; normalizing here funnels* both shapes into the one-shot empty-response reissue.