Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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 names
diff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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>[]): vo
this: 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>[]): vo
throw 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>[]): vo
steps: [],
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.ts
index 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>[]): vo
if (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.ts
index 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.