@fondation-io/ai 7.0.0-beta.45

package/src/generate-text/core-events.ts

@@ -0,0 +1,390 @@
+import type { JSONValue, LanguageModelV4ToolChoice } from '@ai-sdk/provider';
+import type {
+  ModelMessage,
+  ProviderOptions,
+  SystemModelMessage,
+} from '@ai-sdk/provider-utils';
+import type { TimeoutConfiguration } from '../prompt/call-settings';
+import type { ToolChoice } from '../types/language-model';
+import type { LanguageModelUsage } from '../types/usage';
+import type { Output } from './output';
+import type { StepResult } from './step-result';
+import type { StopCondition } from './stop-condition';
+import type { TypedToolCall } from './tool-call';
+import type { ToolSet } from './tool-set';
+import { TextStreamPart } from './stream-text-result';
+
+/**
+ * Event passed to the `onStart` callback.
+ *
+ * Called when the generation operation begins, before any LLM calls.
+ */
+export interface OnStartEvent<
+  TOOLS extends ToolSet = ToolSet,
+  OUTPUT extends Output = Output,
+  INCLUDE = { requestBody?: boolean; responseBody?: boolean },
+> {
+  /** Unique identifier for this generation call, used to correlate events. */
+  readonly callId: string;
+
+  /** Identifies the operation type (e.g. 'ai.generateText' or 'ai.streamText'). */
+  readonly operationId: string;
+
+  /** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string;
+
+  /** The specific model identifier (e.g., 'gpt-4o'). */
+  readonly modelId: string;
+
+  /** The system message(s) provided to the model. */
+  readonly system:
+    | string
+    | SystemModelMessage
+    | Array<SystemModelMessage>
+    | undefined;
+
+  /** The prompt string or array of messages if using the prompt option. */
+  readonly prompt: string | Array<ModelMessage> | undefined;
+
+  /** The messages array if using the messages option. */
+  readonly messages: Array<ModelMessage> | undefined;
+
+  /** The tools available for this generation. */
+  readonly tools: TOOLS | undefined;
+
+  /** The tool choice strategy for this generation. */
+  readonly toolChoice: ToolChoice<NoInfer<TOOLS>> | undefined;
+
+  /** Limits which tools are available for the model to call. */
+  readonly activeTools: Array<keyof TOOLS> | undefined;
+
+  /** Maximum number of tokens to generate. */
+  readonly maxOutputTokens: number | undefined;
+  /** Sampling temperature for generation. */
+  readonly temperature: number | undefined;
+  /** Top-p (nucleus) sampling parameter. */
+  readonly topP: number | undefined;
+  /** Top-k sampling parameter. */
+  readonly topK: number | undefined;
+  /** Presence penalty for generation. */
+  readonly presencePenalty: number | undefined;
+  /** Frequency penalty for generation. */
+  readonly frequencyPenalty: number | undefined;
+  /** Sequences that will stop generation. */
+  readonly stopSequences: string[] | undefined;
+  /** Random seed for reproducible generation. */
+  readonly seed: number | undefined;
+  /** Maximum number of retries for failed requests. */
+  readonly maxRetries: number;
+
+  /**
+   * Timeout configuration for the generation.
+   * Can be a number (milliseconds) or an object with totalMs, stepMs, chunkMs.
+   */
+  readonly timeout: TimeoutConfiguration<TOOLS> | undefined;
+
+  /** Additional HTTP headers sent with the request. */
+  readonly headers: Record<string, string | undefined> | undefined;
+
+  /** Additional provider-specific options. */
+  readonly providerOptions: ProviderOptions | undefined;
+
+  /**
+   * Condition(s) for stopping the generation.
+   * When the condition is an array, any of the conditions can be met to stop.
+   */
+  readonly stopWhen:
+    | StopCondition<TOOLS>
+    | Array<StopCondition<TOOLS>>
+    | undefined;
+
+  /** The output specification for structured outputs, if configured. */
+  readonly output: OUTPUT | undefined;
+
+  /** Abort signal for cancelling the operation. */
+  readonly abortSignal: AbortSignal | undefined;
+
+  /**
+   * Settings for controlling what data is included in step results.
+   */
+  readonly include: INCLUDE | undefined;
+
+  /** Whether telemetry is enabled. */
+  readonly isEnabled: boolean | undefined;
+
+  /** Whether to record inputs in telemetry. Enabled by default. */
+  readonly recordInputs: boolean | undefined;
+
+  /** Whether to record outputs in telemetry. Enabled by default. */
+  readonly recordOutputs: boolean | undefined;
+
+  /** Identifier from telemetry settings for grouping related operations. */
+  readonly functionId: string | undefined;
+
+  /** Additional metadata from telemetry settings. */
+  readonly metadata: Record<string, JSONValue> | undefined;
+
+  /**
+   * User-defined context object that flows through the entire generation lifecycle.
+   * Can be accessed and modified in `prepareStep` and tool `execute` functions.
+   */
+  readonly experimental_context: unknown;
+}
+
+/**
+ * Event passed to the `onStepStart` callback.
+ *
+ * Called when a step (LLM call) begins, before the provider is called.
+ * Each step represents a single LLM invocation.
+ */
+export interface OnStepStartEvent<
+  TOOLS extends ToolSet = ToolSet,
+  OUTPUT extends Output = Output,
+  INCLUDE = { requestBody?: boolean; responseBody?: boolean },
+> {
+  /** Unique identifier for this generation call, used to correlate events. */
+  readonly callId: string;
+
+  /** Zero-based index of the current step. */
+  readonly stepNumber: number;
+
+  /** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string;
+
+  /** The specific model identifier (e.g., 'gpt-4o'). */
+  readonly modelId: string;
+
+  /**
+   * The system message for this step.
+   */
+  readonly system:
+    | string
+    | SystemModelMessage
+    | Array<SystemModelMessage>
+    | undefined;
+
+  /**
+   * The messages that will be sent to the model for this step.
+   * Uses the user-facing `ModelMessage` format.
+   * May be overridden by prepareStep.
+   */
+  readonly messages: Array<ModelMessage>;
+
+  /** The tools available for this generation. */
+  readonly tools: TOOLS | undefined;
+
+  /** The tool choice configuration for this step. */
+  readonly toolChoice: LanguageModelV4ToolChoice | undefined;
+
+  /** Limits which tools are available for this step. */
+  readonly activeTools: Array<keyof TOOLS> | undefined;
+
+  /** Array of results from previous steps (empty for first step). */
+  readonly steps: ReadonlyArray<StepResult<TOOLS>>;
+
+  /** Additional provider-specific options for this step. */
+  readonly providerOptions: ProviderOptions | undefined;
+
+  /**
+   * Timeout configuration for the generation.
+   * Can be a number (milliseconds) or an object with totalMs, stepMs, chunkMs.
+   */
+  readonly timeout: TimeoutConfiguration<TOOLS> | undefined;
+
+  /** Additional HTTP headers sent with the request. */
+  readonly headers: Record<string, string | undefined> | undefined;
+
+  /**
+   * Condition(s) for stopping the generation.
+   * When the condition is an array, any of the conditions can be met to stop.
+   */
+  readonly stopWhen:
+    | StopCondition<TOOLS>
+    | Array<StopCondition<TOOLS>>
+    | undefined;
+
+  /** The output specification for structured outputs, if configured. */
+  readonly output: OUTPUT | undefined;
+
+  /** Abort signal for cancelling the operation. */
+  readonly abortSignal: AbortSignal | undefined;
+
+  /**
+   * Settings for controlling what data is included in step results.
+   */
+  readonly include: INCLUDE | undefined;
+
+  /** Identifier from telemetry settings for grouping related operations. */
+  readonly functionId: string | undefined;
+
+  /** Additional metadata from telemetry settings. */
+  readonly metadata: Record<string, unknown> | undefined;
+
+  /**
+   * User-defined context object. May be updated from `prepareStep` between steps.
+   */
+  readonly experimental_context: unknown;
+}
+
+/**
+ * Event passed to the `onToolCallStart` callback.
+ *
+ * Called when a tool execution begins, before the tool's `execute` function is invoked.
+ */
+export interface OnToolCallStartEvent<TOOLS extends ToolSet = ToolSet> {
+  /** Unique identifier for this generation call, used to correlate events. */
+  readonly callId: string;
+
+  /** Zero-based index of the current step where this tool call occurs. */
+  readonly stepNumber: number | undefined;
+
+  /** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string | undefined;
+
+  /** The specific model identifier (e.g., 'gpt-4o'). */
+  readonly modelId: string | undefined;
+
+  /** The full tool call object. */
+  readonly toolCall: TypedToolCall<TOOLS>;
+
+  /** The conversation messages available at tool execution time. */
+  readonly messages: Array<ModelMessage>;
+
+  /** Signal for cancelling the operation. */
+  readonly abortSignal: AbortSignal | undefined;
+
+  /** Identifier from telemetry settings for grouping related operations. */
+  readonly functionId: string | undefined;
+
+  /** Additional metadata from telemetry settings. */
+  readonly metadata: Record<string, unknown> | undefined;
+
+  /** User-defined context object flowing through the generation. */
+  readonly experimental_context: unknown;
+}
+
+/**
+ * Event passed to the `onToolCallFinish` callback.
+ *
+ * Called when a tool execution completes, either successfully or with an error.
+ * Uses a discriminated union on the `success` field.
+ */
+export type OnToolCallFinishEvent<TOOLS extends ToolSet = ToolSet> = {
+  /** Unique identifier for this generation call, used to correlate events. */
+  readonly callId: string;
+
+  /** Zero-based index of the current step where this tool call occurred. */
+  readonly stepNumber: number | undefined;
+
+  /** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string | undefined;
+
+  /** The specific model identifier (e.g., 'gpt-4o'). */
+  readonly modelId: string | undefined;
+
+  /** The full tool call object. */
+  readonly toolCall: TypedToolCall<TOOLS>;
+
+  /** The conversation messages available at tool execution time. */
+  readonly messages: Array<ModelMessage>;
+
+  /** Signal for cancelling the operation. */
+  readonly abortSignal: AbortSignal | undefined;
+
+  /** Execution time of the tool call in milliseconds. */
+  readonly durationMs: number;
+
+  /** Identifier from telemetry settings for grouping related operations. */
+  readonly functionId: string | undefined;
+
+  /** Additional metadata from telemetry settings. */
+  readonly metadata: Record<string, unknown> | undefined;
+
+  /** User-defined context object flowing through the generation. */
+  readonly experimental_context: unknown;
+} & (
+  | {
+      /** Indicates the tool call succeeded. */
+      readonly success: true;
+      /** The tool's return value. */
+      readonly output: unknown;
+      readonly error?: never;
+    }
+  | {
+      /** Indicates the tool call failed. */
+      readonly success: false;
+      readonly output?: never;
+      /** The error that occurred during tool execution. */
+      readonly error: unknown;
+    }
+);
+
+/**
+ * Event passed to the `onChunk` callback.
+ *
+ * Called for each chunk received during streaming (`streamText` only).
+ * The chunk is either a content part (text-delta, tool-call, etc.) or
+ * a stream lifecycle marker (`ai.stream.firstChunk` / `ai.stream.finish`).
+ */
+export interface OnChunkEvent<TOOLS extends ToolSet = ToolSet> {
+  readonly chunk:
+    | Extract<
+        TextStreamPart<TOOLS>,
+        {
+          type:
+            | 'text-delta'
+            | 'reasoning-delta'
+            | 'source'
+            | 'tool-call'
+            | 'tool-input-start'
+            | 'tool-input-delta'
+            | 'tool-result'
+            | 'raw';
+        }
+      >
+    | {
+        readonly type: 'ai.stream.firstChunk' | 'ai.stream.finish';
+        readonly callId: string;
+        readonly stepNumber: number;
+        readonly attributes?: Record<string, unknown>;
+      };
+}
+
+/**
+ * Event passed to the `onStepFinish` callback.
+ *
+ * Called when a step (LLM call) completes.
+ * Includes the StepResult for that step along with the call identifier.
+ */
+export type OnStepFinishEvent<TOOLS extends ToolSet = ToolSet> =
+  StepResult<TOOLS>;
+
+/**
+ * Event passed to the `onFinish` callback.
+ *
+ * Called when the entire generation completes (all steps finished).
+ * Includes the final step's result along with aggregated data from all steps.
+ */
+export type OnFinishEvent<TOOLS extends ToolSet = ToolSet> =
+  StepResult<TOOLS> & {
+    /** Array containing results from all steps in the generation. */
+    readonly steps: StepResult<TOOLS>[];
+
+    /** Aggregated token usage across all steps. */
+    readonly totalUsage: LanguageModelUsage;
+
+    /**
+     * The final state of the user-defined context object.
+     *
+     * Experimental (can break in patch releases).
+     *
+     * @default undefined
+     */
+    experimental_context: unknown;
+
+    /** Identifier from telemetry settings for grouping related operations. */
+    readonly functionId: string | undefined;
+
+    /** Additional metadata from telemetry settings. */
+    readonly metadata: Record<string, unknown> | undefined;
+  };

package/src/generate-text/create-execute-tools-transformation.ts

@@ -0,0 +1,144 @@
+import { IdGenerator, ModelMessage } from '@ai-sdk/provider-utils';
+import { TimeoutConfiguration } from '../prompt/call-settings';
+import type { TelemetryIntegration } from '../telemetry/telemetry-integration';
+import { TelemetrySettings } from '../telemetry/telemetry-settings';
+import { executeToolCall } from './execute-tool-call';
+import { isApprovalNeeded } from './is-approval-needed';
+import {
+  StreamTextOnToolCallFinishCallback,
+  StreamTextOnToolCallStartCallback,
+} from './stream-text';
+import { TypedToolCall } from './tool-call';
+import { ToolSet } from './tool-set';
+import { ModelCallStreamPart } from './stream-model-call';
+
+export function createExecuteToolsTransformation<TOOLS extends ToolSet>({
+  tools,
+  telemetry,
+  callId,
+  messages,
+  abortSignal,
+  timeout,
+  experimental_context,
+  generateId,
+  stepNumber,
+  provider,
+  modelId,
+  onToolCallStart,
+  onToolCallFinish,
+  executeToolInTelemetryContext,
+}: {
+  tools: TOOLS | undefined;
+  telemetry: TelemetrySettings | undefined;
+  callId: string;
+  messages: ModelMessage[];
+  abortSignal: AbortSignal | undefined;
+  timeout?: TimeoutConfiguration<TOOLS>;
+  experimental_context: unknown;
+  generateId: IdGenerator;
+  stepNumber?: number;
+  provider?: string;
+  modelId?: string;
+  onToolCallStart?:
+    | StreamTextOnToolCallStartCallback<TOOLS>
+    | Array<StreamTextOnToolCallStartCallback<TOOLS> | undefined | null>;
+  onToolCallFinish?:
+    | StreamTextOnToolCallFinishCallback<TOOLS>
+    | Array<StreamTextOnToolCallFinishCallback<TOOLS> | undefined | null>;
+  executeToolInTelemetryContext?: TelemetryIntegration['executeTool'];
+}): TransformStream<ModelCallStreamPart<TOOLS>, ModelCallStreamPart<TOOLS>> {
+  const toolCallsToExecute: Array<TypedToolCall<TOOLS>> = [];
+
+  // forward stream
+  return new TransformStream<
+    ModelCallStreamPart<TOOLS>,
+    ModelCallStreamPart<TOOLS>
+  >({
+    async transform(
+      chunk: ModelCallStreamPart<TOOLS>,
+      controller: TransformStreamDefaultController<ModelCallStreamPart<TOOLS>>,
+    ) {
+      // immediately forward all chunks
+      controller.enqueue(chunk);
+
+      const chunkType = chunk.type;
+      switch (chunkType) {
+        case 'tool-call': {
+          if (chunk.invalid) {
+            break;
+          }
+
+          const tool = tools?.[chunk.toolName];
+
+          if (tool == null) {
+            // ignore tool calls for tools that are not available,
+            // e.g. provider-executed dynamic tools
+            break;
+          }
+
+          if (
+            await isApprovalNeeded({
+              tool,
+              toolCall: chunk,
+              messages,
+              experimental_context,
+            })
+          ) {
+            controller.enqueue({
+              type: 'tool-approval-request',
+              approvalId: generateId(),
+              toolCall: chunk,
+            });
+            break;
+          }
+
+          // Only execute tools that are not provider-executed:
+          if (tool.execute != null && chunk.providerExecuted !== true) {
+            toolCallsToExecute.push(chunk);
+          }
+
+          break;
+        }
+
+        case 'model-call-end': {
+          await Promise.all(
+            toolCallsToExecute.map(async toolCall => {
+              try {
+                // Note: we don't await the tool execution here (by leaving out 'await' on recordSpan),
+                // because we want to process the next chunk as soon as possible.
+                // This is important for the case where the tool execution takes a long time.
+                const result = await executeToolCall({
+                  toolCall,
+                  tools,
+                  telemetry,
+                  callId,
+                  messages,
+                  abortSignal,
+                  timeout,
+                  experimental_context,
+                  stepNumber,
+                  provider,
+                  modelId,
+                  onToolCallStart,
+                  onToolCallFinish,
+                  executeToolInTelemetryContext,
+                  onPreliminaryToolResult: result => {
+                    controller.enqueue(result);
+                  },
+                });
+                controller.enqueue(result);
+              } catch (error) {
+                controller.enqueue({
+                  type: 'error',
+                  error,
+                });
+              }
+            }),
+          );
+
+          break;
+        }
+      }
+    },
+  });
+}