feat(ai): unify onFinish callback types into shared TextOnFinishCallback

.changeset/mighty-birds-attend.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+Extract common callback structure from GenerateTextOnFinishCallback, StreamTextOnFinishCallback, and ToolLoopAgentOnFinishCallback into a shared TextOnFinishEvent base type. This prepares the codebase for adding output/outputError support to callbacks.

packages/ai/src/agent/tool-loop-agent-on-finish-callback.ts

@@ -1,31 +1,11 @@
-import { StepResult } from '../generate-text/step-result';
+import { TextOnFinishEvent } from '../generate-text/text-on-finish-callback';
 import { ToolSet } from '../generate-text/tool-set';
-import { LanguageModelUsage } from '../types/usage';
 
 /**
  * Callback that is set using the `onFinish` option.
  *
  * @param event - The event that is passed to the callback.
  */
 export type ToolLoopAgentOnFinishCallback<TOOLS extends ToolSet = {}> = (
-  event: StepResult<TOOLS> & {
-    /**
-     * Details for all steps.
-     */
-    readonly steps: StepResult<TOOLS>[];
-
-    /**
-     * Total usage for all steps. This is the sum of the usage of all steps.
-     */
-    readonly totalUsage: LanguageModelUsage;
-
-    /**
-     * Context that is passed into tool calls.
-     *
-     * Experimental (can break in patch releases).
-     *
-     * @default undefined
-     */
-    experimental_context?: unknown;
-  },
+  event: TextOnFinishEvent<TOOLS>,
 ) => PromiseLike<void> | void;

packages/ai/src/generate-text/generate-text.ts

@@ -76,6 +76,7 @@ import { ToolCallRepairFunction } from './tool-call-repair-function';
 import { TypedToolError } from './tool-error';
 import { ToolOutput } from './tool-output';
 import { TypedToolResult } from './tool-result';
+import { TextOnFinishEvent } from './text-on-finish-callback';
 import { ToolSet } from './tool-set';
 import { mergeAbortSignals } from '../util/merge-abort-signals';
 
@@ -99,26 +100,7 @@ export type GenerateTextOnStepFinishCallback<TOOLS extends ToolSet> = (
  * @param event - The event that is passed to the callback.
  */
 export type GenerateTextOnFinishCallback<TOOLS extends ToolSet> = (
-  event: StepResult<TOOLS> & {
-    /**
-     * Details for all steps.
-     */
-    readonly steps: StepResult<TOOLS>[];
-
-    /**
-     * Total usage for all steps. This is the sum of the usage of all steps.
-     */
-    readonly totalUsage: LanguageModelUsage;
-
-    /**
-     * Context that is passed into tool execution.
-     *
-     * Experimental (can break in patch releases).
-     *
-     * @default undefined
-     */
-    experimental_context: unknown;
-  },
+  event: TextOnFinishEvent<TOOLS>,
 ) => PromiseLike<void> | void;
 
 /**

packages/ai/src/generate-text/index.ts

@@ -56,3 +56,7 @@ export type {
   TypedToolResult,
 } from './tool-result';
 export type { ToolSet } from './tool-set';
+export type {
+  TextOnFinishCallback,
+  TextOnFinishEvent,
+} from './text-on-finish-callback';

packages/ai/src/generate-text/stream-text.ts

@@ -108,6 +108,7 @@ import { TypedToolCall } from './tool-call';
 import { ToolCallRepairFunction } from './tool-call-repair-function';
 import { ToolOutput } from './tool-output';
 import { StaticToolOutputDenied } from './tool-output-denied';
+import { TextOnFinishEvent } from './text-on-finish-callback';
 import { ToolSet } from './tool-set';
 
 const originalGenerateId = createIdGenerator({
@@ -172,26 +173,7 @@ export type StreamTextOnChunkCallback<TOOLS extends ToolSet> = (event: {
  * @param event - The event that is passed to the callback.
  */
 export type StreamTextOnFinishCallback<TOOLS extends ToolSet> = (
-  event: StepResult<TOOLS> & {
-    /**
-     * Details for all steps.
-     */
-    readonly steps: StepResult<TOOLS>[];
-
-    /**
-     * Total usage for all steps. This is the sum of the usage of all steps.
-     */
-    readonly totalUsage: LanguageModelUsage;
-
-    /**
-     * Context that is passed into tool execution.
-     *
-     * Experimental (can break in patch releases).
-     *
-     * @default undefined
-     */
-    experimental_context: unknown;
-  },
+  event: TextOnFinishEvent<TOOLS>,
 ) => PromiseLike<void> | void;
 
 /**

packages/ai/src/generate-text/text-on-finish-callback.test-d.ts

@@ -0,0 +1,55 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import { GenerateTextOnFinishCallback } from './generate-text';
+import { StreamTextOnFinishCallback } from './stream-text';
+import {
+  TextOnFinishCallback,
+  TextOnFinishEvent,
+} from './text-on-finish-callback';
+import { ToolSet } from './tool-set';
+import { ToolLoopAgentOnFinishCallback } from '../agent/tool-loop-agent-on-finish-callback';
+
+describe('TextOnFinishCallback types', () => {
+  it('GenerateTextOnFinishCallback should be assignable to TextOnFinishCallback', () => {
+    type Tools = ToolSet;
+    expectTypeOf<GenerateTextOnFinishCallback<Tools>>().toMatchTypeOf<
+      TextOnFinishCallback<Tools>
+    >();
+  });
+
+  it('StreamTextOnFinishCallback should be assignable to TextOnFinishCallback', () => {
+    type Tools = ToolSet;
+    expectTypeOf<StreamTextOnFinishCallback<Tools>>().toMatchTypeOf<
+      TextOnFinishCallback<Tools>
+    >();
+  });
+
+  it('ToolLoopAgentOnFinishCallback should be assignable to TextOnFinishCallback', () => {
+    type Tools = ToolSet;
+    expectTypeOf<ToolLoopAgentOnFinishCallback<Tools>>().toMatchTypeOf<
+      TextOnFinishCallback<Tools>
+    >();
+  });
+
+  it('TextOnFinishEvent should have required experimental_context', () => {
+    type Tools = ToolSet;
+    type EventContext = TextOnFinishEvent<Tools>['experimental_context'];
+    expectTypeOf<EventContext>().toEqualTypeOf<unknown>();
+  });
+
+  it('callback types should be interchangeable', () => {
+    type Tools = ToolSet;
+    const generateCallback: GenerateTextOnFinishCallback<Tools> = () => {};
+    const streamCallback: StreamTextOnFinishCallback<Tools> = () => {};
+    const agentCallback: ToolLoopAgentOnFinishCallback<Tools> = () => {};
+
+    // All should be assignable to the base type
+    const base1: TextOnFinishCallback<Tools> = generateCallback;
+    const base2: TextOnFinishCallback<Tools> = streamCallback;
+    const base3: TextOnFinishCallback<Tools> = agentCallback;
+
+    // Suppress unused variable warnings
+    void base1;
+    void base2;
+    void base3;
+  });
+});

packages/ai/src/generate-text/text-on-finish-callback.ts

@@ -0,0 +1,36 @@
+import { LanguageModelUsage } from '../types/usage';
+import { StepResult } from './step-result';
+import { ToolSet } from './tool-set';
+
+/**
+ * Event that is passed to the `onFinish` callback.
+ */
+export type TextOnFinishEvent<TOOLS extends ToolSet> = StepResult<TOOLS> & {
+  /**
+   * Details for all steps.
+   */
+  readonly steps: StepResult<TOOLS>[];
+
+  /**
+   * Total usage for all steps. This is the sum of the usage of all steps.
+   */
+  readonly totalUsage: LanguageModelUsage;
+
+  /**
+   * Context that is passed into tool execution.
+   *
+   * Experimental (can break in patch releases).
+   *
+   * @default undefined
+   */
+  experimental_context: unknown;
+};
+
+/**
+ * Callback that is set using the `onFinish` option.
+ *
+ * @param event - The event that is passed to the callback.
+ */
+export type TextOnFinishCallback<TOOLS extends ToolSet> = (
+  event: TextOnFinishEvent<TOOLS>,
+) => PromiseLike<void> | void;