@fondation-io/ai 7.0.0-beta.45

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

@@ -0,0 +1,190 @@
+import { executeTool, ModelMessage } from '@ai-sdk/provider-utils';
+import { notify } from '../util/notify';
+import {
+  getToolTimeoutMs,
+  TimeoutConfiguration,
+} from '../prompt/call-settings';
+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,
+  telemetry,
+  callId,
+  messages,
+  abortSignal,
+  timeout,
+  experimental_context,
+  stepNumber,
+  provider,
+  modelId,
+  onPreliminaryToolResult,
+  onToolCallStart,
+  onToolCallFinish,
+  executeToolInTelemetryContext = async ({ execute }) => execute(),
+}: {
+  toolCall: TypedToolCall<TOOLS>;
+  tools: TOOLS | undefined;
+  telemetry: TelemetrySettings | undefined;
+  callId: string;
+  messages: ModelMessage[];
+  abortSignal: AbortSignal | undefined;
+  timeout?: TimeoutConfiguration<TOOLS>;
+  experimental_context: unknown;
+  stepNumber?: number;
+  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>;
+  executeToolInTelemetryContext?: <T>(params: {
+    callId: string;
+    toolCallId: string;
+    execute: () => PromiseLike<T>;
+  }) => PromiseLike<T>;
+}): Promise<ToolOutput<TOOLS> | undefined> {
+  const { toolName, toolCallId, input } = toolCall;
+  const tool = tools?.[toolName];
+
+  if (tool?.execute == null) {
+    return undefined;
+  }
+
+  const baseCallbackEvent = {
+    callId,
+    stepNumber,
+    provider,
+    modelId,
+    toolCall,
+    messages,
+    abortSignal,
+    functionId: telemetry?.functionId,
+    metadata: telemetry?.metadata as Record<string, unknown> | undefined,
+    experimental_context,
+  };
+
+  let output: unknown;
+
+  await notify({ event: baseCallbackEvent, callbacks: onToolCallStart });
+
+  const toolTimeoutMs = getToolTimeoutMs<TOOLS>(timeout, toolName);
+
+  const toolAbortSignal =
+    toolTimeoutMs != null
+      ? abortSignal != null
+        ? AbortSignal.any([abortSignal, AbortSignal.timeout(toolTimeoutMs)])
+        : AbortSignal.timeout(toolTimeoutMs)
+      : abortSignal;
+
+  const startTime = now();
+
+  try {
+    // In order to correctly nest telemetry spans within tool calls spans, telemetry integrations need
+    // to be able to execute the tool call in a telemetry-integration-specific context.
+    //
+    // The call id and the tool call id are provided to the telemetry integration so that it can correctly
+    // identify the parent span.
+    await executeToolInTelemetryContext({
+      callId,
+      toolCallId,
+      execute: async () => {
+        const stream = executeTool({
+          execute: tool.execute!.bind(tool),
+          input,
+          options: {
+            toolCallId,
+            messages,
+            abortSignal: toolAbortSignal,
+            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,
+    });
+
+    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,
+  });
+
+  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 {
+  LanguageModelV4Content,
+  LanguageModelV4Reasoning,
+} from '@ai-sdk/provider';
+
+export function extractReasoningContent(
+  content: LanguageModelV4Content[],
+): string | undefined {
+  const parts = content.filter(
+    (content): content is LanguageModelV4Reasoning =>
+      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 { LanguageModelV4Content, LanguageModelV4Text } from '@ai-sdk/provider';
+
+export function extractTextContent(
+  content: LanguageModelV4Content[],
+): string | undefined {
+  const parts = content.filter(
+    (content): content is LanguageModelV4Text => content.type === 'text',
+  );
+
+  if (parts.length === 0) {
+    return undefined;
+  }
+
+  return parts.map(content => content.text).join('');
+}

package/src/generate-text/generate-text-result.ts

@@ -0,0 +1,168 @@
+import { CallWarning, FinishReason, ProviderMetadata } from '../types';
+import { Source } from '../types/language-model';
+import { LanguageModelRequestMetadata } from '../types/language-model-request-metadata';
+import { LanguageModelResponseMetadata } from '../types/language-model-response-metadata';
+import { LanguageModelUsage } from '../types/usage';
+import { ContentPart } from './content-part';
+import { GeneratedFile } from './generated-file';
+import { Output } from './output';
+import { InferCompleteOutput } from './output-utils';
+import { ReasoningOutput, ReasoningFileOutput } from './reasoning-output';
+import { ResponseMessage } from './response-message';
+import { StepResult } from './step-result';
+import { DynamicToolCall, StaticToolCall, TypedToolCall } from './tool-call';
+import {
+  DynamicToolResult,
+  StaticToolResult,
+  TypedToolResult,
+} from './tool-result';
+import { ToolSet } from './tool-set';
+
+/**
+ * The result of a `generateText` call.
+ * It contains the generated text, the tool calls that were made during the generation, and the results of the tool calls.
+ */
+export interface GenerateTextResult<
+  TOOLS extends ToolSet,
+  OUTPUT extends Output,
+> {
+  /**
+   * The content that was generated in the last step.
+   */
+  readonly content: Array<ContentPart<TOOLS>>;
+
+  /**
+   * The text that was generated in the last step.
+   */
+  readonly text: string;
+
+  /**
+   * The full reasoning that the model has generated in the last step.
+   */
+  readonly reasoning: Array<ReasoningOutput | ReasoningFileOutput>;
+
+  /**
+   * The reasoning text that the model has generated in the last step. Can be undefined if the model
+   * has only generated text.
+   */
+  readonly reasoningText: string | undefined;
+
+  /**
+   * The files that were generated in the last step.
+   * Empty array if no files were generated.
+   */
+  readonly files: Array<GeneratedFile>;
+
+  /**
+   * Sources that have been used as references in the last step.
+   */
+  readonly sources: Array<Source>;
+
+  /**
+   * The tool calls that were made in the last step.
+   */
+  readonly toolCalls: Array<TypedToolCall<TOOLS>>;
+
+  /**
+   * The static tool calls that were made in the last step.
+   */
+  readonly staticToolCalls: Array<StaticToolCall<TOOLS>>;
+
+  /**
+   * The dynamic tool calls that were made in the last step.
+   */
+  readonly dynamicToolCalls: Array<DynamicToolCall>;
+
+  /**
+   * The results of the tool calls from the last step.
+   */
+  readonly toolResults: Array<TypedToolResult<TOOLS>>;
+
+  /**
+   * The static tool results that were made in the last step.
+   */
+  readonly staticToolResults: Array<StaticToolResult<TOOLS>>;
+
+  /**
+   * The dynamic tool results that were made in the last step.
+   */
+  readonly dynamicToolResults: Array<DynamicToolResult>;
+
+  /**
+   * The unified reason why the generation finished.
+   */
+  readonly finishReason: FinishReason;
+
+  /**
+   * The raw reason why the generation finished (from the provider).
+   */
+  readonly rawFinishReason: string | undefined;
+
+  /**
+   * The token usage of the last step.
+   */
+  readonly usage: LanguageModelUsage;
+
+  /**
+   * The total token usage of all steps.
+   * When there are multiple steps, the usage is the sum of all step usages.
+   */
+  readonly totalUsage: LanguageModelUsage;
+
+  /**
+   * Warnings from the model provider (e.g. unsupported settings)
+   */
+  readonly warnings: CallWarning[] | undefined;
+
+  /**
+   * Additional request information.
+   */
+  readonly request: LanguageModelRequestMetadata;
+
+  /**
+   * Additional response information.
+   */
+  readonly response: LanguageModelResponseMetadata & {
+    /**
+     * The response messages that were generated during the call. It consists of an assistant message,
+     * potentially containing tool calls.
+     *
+     * When there are tool results, there is an additional tool message with the tool results that are available.
+     * If there are tools that do not have execute functions, they are not included in the tool results and
+     * need to be added separately.
+     */
+    messages: Array<ResponseMessage>;
+
+    /**
+     * Response body (available only for providers that use HTTP requests).
+     */
+    body?: unknown;
+  };
+
+  /**
+   * Additional provider-specific metadata. They are passed through
+   * from the provider to the AI SDK and enable provider-specific
+   * results that can be fully encapsulated in the provider.
+   */
+  readonly providerMetadata: ProviderMetadata | undefined;
+
+  /**
+   * Details for all steps.
+   * You can use this to get information about intermediate steps,
+   * such as the tool calls or the response headers.
+   */
+  readonly steps: Array<StepResult<TOOLS>>;
+
+  /**
+   * The generated structured output. It uses the `output` specification.
+   *
+   * @deprecated Use `output` instead.
+   */
+  readonly experimental_output: InferCompleteOutput<OUTPUT>;
+
+  /**
+   * The generated structured output. It uses the `output` specification.
+   *
+   */
+  readonly output: InferCompleteOutput<OUTPUT>;
+}