@depup/ai 6.0.116-depup.0

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

@@ -0,0 +1,332 @@
+import type { LanguageModelV3ToolChoice } 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';
+
+/**
+ * Common model information used across callback events.
+ */
+export interface CallbackModelInfo {
+  /** The provider identifier (e.g., 'openai', 'anthropic'). */
+  readonly provider: string;
+  /** The specific model identifier (e.g., 'gpt-4o'). */
+  readonly modelId: string;
+}
+
+/**
+ * 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 },
+> {
+  /** The model being used for generation. */
+  readonly model: CallbackModelInfo;
+
+  /** 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 | 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;
+
+  /** Identifier from telemetry settings for grouping related operations. */
+  readonly functionId: string | undefined;
+
+  /** Additional metadata passed to the generation. */
+  readonly metadata: Record<string, unknown> | 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 },
+> {
+  /** Zero-based index of the current step. */
+  readonly stepNumber: number;
+
+  /** The model being used for this step. */
+  readonly model: CallbackModelInfo;
+
+  /**
+   * 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: LanguageModelV3ToolChoice | 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 | 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> {
+  /** Zero-based index of the current step where this tool call occurs. */
+  readonly stepNumber: number | undefined;
+
+  /** The model being used for this step. */
+  readonly model: CallbackModelInfo | 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> = {
+  /** Zero-based index of the current step where this tool call occurred. */
+  readonly stepNumber: number | undefined;
+
+  /** The model being used for this step. */
+  readonly model: CallbackModelInfo | 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 `onStepFinish` callback.
+ *
+ * Called when a step (LLM call) completes.
+ * This is simply the StepResult for that step.
+ */
+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/collect-tool-approvals.ts

@@ -0,0 +1,116 @@
+import {
+  ModelMessage,
+  ToolApprovalRequest,
+  ToolApprovalResponse,
+} from '@ai-sdk/provider-utils';
+import { InvalidToolApprovalError } from '../error/invalid-tool-approval-error';
+import { ToolCallNotFoundForApprovalError } from '../error/tool-call-not-found-for-approval-error';
+import { TypedToolCall } from './tool-call';
+import { TypedToolResult } from './tool-result';
+import { ToolSet } from './tool-set';
+
+export type CollectedToolApprovals<TOOLS extends ToolSet> = {
+  approvalRequest: ToolApprovalRequest;
+  approvalResponse: ToolApprovalResponse;
+  toolCall: TypedToolCall<TOOLS>;
+};
+
+/**
+ * If the last message is a tool message, this function collects all tool approvals
+ * from that message.
+ */
+export function collectToolApprovals<TOOLS extends ToolSet>({
+  messages,
+}: {
+  messages: ModelMessage[];
+}): {
+  approvedToolApprovals: Array<CollectedToolApprovals<TOOLS>>;
+  deniedToolApprovals: Array<CollectedToolApprovals<TOOLS>>;
+} {
+  const lastMessage = messages.at(-1);
+
+  if (lastMessage?.role != 'tool') {
+    return {
+      approvedToolApprovals: [],
+      deniedToolApprovals: [],
+    };
+  }
+
+  // gather tool calls and prepare lookup
+  const toolCallsByToolCallId: Record<string, TypedToolCall<TOOLS>> = {};
+  for (const message of messages) {
+    if (message.role === 'assistant' && typeof message.content !== 'string') {
+      const content = message.content;
+      for (const part of content) {
+        if (part.type === 'tool-call') {
+          toolCallsByToolCallId[part.toolCallId] = part as TypedToolCall<TOOLS>;
+        }
+      }
+    }
+  }
+
+  // gather approval responses and prepare lookup
+  const toolApprovalRequestsByApprovalId: Record<string, ToolApprovalRequest> =
+    {};
+  for (const message of messages) {
+    if (message.role === 'assistant' && typeof message.content !== 'string') {
+      const content = message.content;
+      for (const part of content) {
+        if (part.type === 'tool-approval-request') {
+          toolApprovalRequestsByApprovalId[part.approvalId] = part;
+        }
+      }
+    }
+  }
+
+  // gather tool results from the last tool message
+  const toolResults: Record<string, TypedToolResult<TOOLS>> = {};
+  for (const part of lastMessage.content) {
+    if (part.type === 'tool-result') {
+      toolResults[part.toolCallId] = part as TypedToolResult<TOOLS>;
+    }
+  }
+
+  const approvedToolApprovals: Array<CollectedToolApprovals<TOOLS>> = [];
+  const deniedToolApprovals: Array<CollectedToolApprovals<TOOLS>> = [];
+
+  const approvalResponses = lastMessage.content.filter(
+    part => part.type === 'tool-approval-response',
+  );
+  for (const approvalResponse of approvalResponses) {
+    const approvalRequest =
+      toolApprovalRequestsByApprovalId[approvalResponse.approvalId];
+
+    if (approvalRequest == null) {
+      throw new InvalidToolApprovalError({
+        approvalId: approvalResponse.approvalId,
+      });
+    }
+
+    if (toolResults[approvalRequest.toolCallId] != null) {
+      continue;
+    }
+
+    const toolCall = toolCallsByToolCallId[approvalRequest.toolCallId];
+    if (toolCall == null) {
+      throw new ToolCallNotFoundForApprovalError({
+        toolCallId: approvalRequest.toolCallId,
+        approvalId: approvalRequest.approvalId,
+      });
+    }
+
+    const approval: CollectedToolApprovals<TOOLS> = {
+      approvalRequest,
+      approvalResponse,
+      toolCall,
+    };
+
+    if (approvalResponse.approved) {
+      approvedToolApprovals.push(approval);
+    } else {
+      deniedToolApprovals.push(approval);
+    }
+  }
+
+  return { approvedToolApprovals, deniedToolApprovals };
+}

package/src/generate-text/content-part.ts

@@ -0,0 +1,25 @@
+import { ProviderMetadata } from '../types';
+import { Source } from '../types/language-model';
+import { GeneratedFile } from './generated-file';
+import { ToolApprovalRequestOutput } from './tool-approval-request-output';
+import { ReasoningOutput } from './reasoning-output';
+import { TypedToolCall } from './tool-call';
+import { TypedToolError } from './tool-error';
+import { TypedToolResult } from './tool-result';
+import { ToolSet } from './tool-set';
+
+export type ContentPart<TOOLS extends ToolSet> =
+  | { type: 'text'; text: string; providerMetadata?: ProviderMetadata }
+  | ReasoningOutput
+  | ({ type: 'source' } & Source)
+  | { type: 'file'; file: GeneratedFile; providerMetadata?: ProviderMetadata } // different because of GeneratedFile object
+  | ({ type: 'tool-call' } & TypedToolCall<TOOLS> & {
+        providerMetadata?: ProviderMetadata;
+      })
+  | ({ type: 'tool-result' } & TypedToolResult<TOOLS> & {
+        providerMetadata?: ProviderMetadata;
+      })
+  | ({ type: 'tool-error' } & TypedToolError<TOOLS> & {
+        providerMetadata?: ProviderMetadata;
+      })
+  | ToolApprovalRequestOutput<TOOLS>;

package/src/generate-text/execute-tool-call.ts

@@ -0,0 +1,197 @@
+import { executeTool, ModelMessage } from '@ai-sdk/provider-utils';
+import { Tracer } from '@opentelemetry/api';
+import { notify } from '../util/notify';
+import { assembleOperationName } from '../telemetry/assemble-operation-name';
+import { recordErrorOnSpan, recordSpan } from '../telemetry/record-span';
+import { selectTelemetryAttributes } from '../telemetry/select-telemetry-attributes';
+import { TelemetrySettings } from '../telemetry/telemetry-settings';
+import { now } from '../util/now';
+import {
+  GenerateTextOnToolCallFinishCallback,
+  GenerateTextOnToolCallStartCallback,
+} from './generate-text';
+import { TypedToolCall } from './tool-call';
+import { ToolOutput } from './tool-output';
+import { ToolSet } from './tool-set';
+import { TypedToolResult } from './tool-result';
+import { TypedToolError } from './tool-error';
+
+/**
+ * Executes a single tool call and manages its lifecycle callbacks.
+ *
+ * This function handles the complete tool execution flow:
+ * 1. Invokes `onToolCallStart` callback before execution
+ * 2. Executes the tool's `execute` function with proper context
+ * 3. Handles streaming outputs via `onPreliminaryToolResult`
+ * 4. Invokes `onToolCallFinish` callback with success or error result
+ *
+ * @returns The tool output (result or error), or undefined if the tool has no execute function.
+ */
+export async function executeToolCall<TOOLS extends ToolSet>({
+  toolCall,
+  tools,
+  tracer,
+  telemetry,
+  messages,
+  abortSignal,
+  experimental_context,
+  stepNumber,
+  model,
+  onPreliminaryToolResult,
+  onToolCallStart,
+  onToolCallFinish,
+}: {
+  toolCall: TypedToolCall<TOOLS>;
+  tools: TOOLS | undefined;
+  tracer: Tracer;
+  telemetry: TelemetrySettings | undefined;
+  messages: ModelMessage[];
+  abortSignal: AbortSignal | undefined;
+  experimental_context: unknown;
+  stepNumber?: number;
+  model?: { provider: string; modelId: string };
+  onPreliminaryToolResult?: (result: TypedToolResult<TOOLS>) => void;
+  onToolCallStart?:
+    | GenerateTextOnToolCallStartCallback<TOOLS>
+    | Array<GenerateTextOnToolCallStartCallback<TOOLS> | undefined | null>;
+  onToolCallFinish?:
+    | GenerateTextOnToolCallFinishCallback<TOOLS>
+    | Array<GenerateTextOnToolCallFinishCallback<TOOLS> | undefined | null>;
+}): Promise<ToolOutput<TOOLS> | undefined> {
+  const { toolName, toolCallId, input } = toolCall;
+  const tool = tools?.[toolName];
+
+  if (tool?.execute == null) {
+    return undefined;
+  }
+
+  const baseCallbackEvent = {
+    stepNumber,
+    model,
+    toolCall,
+    messages,
+    abortSignal,
+    functionId: telemetry?.functionId,
+    metadata: telemetry?.metadata as Record<string, unknown> | undefined,
+    experimental_context,
+  };
+
+  return recordSpan({
+    name: 'ai.toolCall',
+    attributes: selectTelemetryAttributes({
+      telemetry,
+      attributes: {
+        ...assembleOperationName({
+          operationId: 'ai.toolCall',
+          telemetry,
+        }),
+        'ai.toolCall.name': toolName,
+        'ai.toolCall.id': toolCallId,
+        'ai.toolCall.args': {
+          output: () => JSON.stringify(input),
+        },
+      },
+    }),
+    tracer,
+    fn: async span => {
+      let output: unknown;
+
+      await notify({ event: baseCallbackEvent, callbacks: onToolCallStart });
+
+      const startTime = now();
+
+      try {
+        const stream = executeTool({
+          execute: tool.execute!.bind(tool),
+          input,
+          options: {
+            toolCallId,
+            messages,
+            abortSignal,
+            experimental_context,
+          },
+        });
+
+        for await (const part of stream) {
+          if (part.type === 'preliminary') {
+            onPreliminaryToolResult?.({
+              ...toolCall,
+              type: 'tool-result',
+              output: part.output,
+              preliminary: true,
+            });
+          } else {
+            output = part.output;
+          }
+        }
+      } catch (error) {
+        const durationMs = now() - startTime;
+
+        await notify({
+          event: {
+            ...baseCallbackEvent,
+            success: false as const,
+            error,
+            durationMs,
+          },
+          callbacks: onToolCallFinish,
+        });
+
+        recordErrorOnSpan(span, error);
+        return {
+          type: 'tool-error',
+          toolCallId,
+          toolName,
+          input,
+          error,
+          dynamic: tool.type === 'dynamic',
+          ...(toolCall.providerMetadata != null
+            ? { providerMetadata: toolCall.providerMetadata }
+            : {}),
+        } as TypedToolError<TOOLS>;
+      }
+
+      const durationMs = now() - startTime;
+
+      await notify({
+        event: {
+          ...baseCallbackEvent,
+          success: true as const,
+          output,
+          durationMs,
+        },
+        callbacks: onToolCallFinish,
+      });
+
+      try {
+        span.setAttributes(
+          await selectTelemetryAttributes({
+            telemetry,
+            attributes: {
+              'ai.toolCall.result': {
+                output: () => JSON.stringify(output),
+              },
+            },
+          }),
+        );
+      } catch (ignored) {
+        // JSON stringify might fail if the result is not serializable,
+        // in which case we just ignore it. In the future we might want to
+        // add an optional serialize method to the tool interface and warn
+        // if the result is not serializable.
+      }
+
+      return {
+        type: 'tool-result',
+        toolCallId,
+        toolName,
+        input,
+        output,
+        dynamic: tool.type === 'dynamic',
+        ...(toolCall.providerMetadata != null
+          ? { providerMetadata: toolCall.providerMetadata }
+          : {}),
+      } as TypedToolResult<TOOLS>;
+    },
+  });
+}

package/src/generate-text/extract-reasoning-content.ts

@@ -0,0 +1,17 @@
+import {
+  LanguageModelV3Content,
+  LanguageModelV3Reasoning,
+} from '@ai-sdk/provider';
+
+export function extractReasoningContent(
+  content: LanguageModelV3Content[],
+): string | undefined {
+  const parts = content.filter(
+    (content): content is LanguageModelV3Reasoning =>
+      content.type === 'reasoning',
+  );
+
+  return parts.length === 0
+    ? undefined
+    : parts.map(content => content.text).join('\n');
+}

package/src/generate-text/extract-text-content.ts

@@ -0,0 +1,15 @@
+import { LanguageModelV3Content, LanguageModelV3Text } from '@ai-sdk/provider';
+
+export function extractTextContent(
+  content: LanguageModelV3Content[],
+): string | undefined {
+  const parts = content.filter(
+    (content): content is LanguageModelV3Text => content.type === 'text',
+  );
+
+  if (parts.length === 0) {
+    return undefined;
+  }
+
+  return parts.map(content => content.text).join('');
+}