@fondation-io/ai 7.0.0-beta.45

package/src/ui-message-stream/ui-message-chunks.ts

@@ -0,0 +1,372 @@
+import { z } from 'zod/v4';
+import {
+  ProviderMetadata,
+  providerMetadataSchema,
+} from '../types/provider-metadata';
+import { FinishReason } from '../types/language-model';
+import {
+  InferUIMessageData,
+  InferUIMessageMetadata,
+  UIDataTypes,
+  UIMessage,
+} from '../ui/ui-messages';
+import { ValueOf } from '../util/value-of';
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+
+export const uiMessageChunkSchema = lazySchema(() =>
+  zodSchema(
+    z.union([
+      z.strictObject({
+        type: z.literal('text-start'),
+        id: z.string(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('text-delta'),
+        id: z.string(),
+        delta: z.string(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('text-end'),
+        id: z.string(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('error'),
+        errorText: z.string(),
+      }),
+      z.strictObject({
+        type: z.literal('tool-input-start'),
+        toolCallId: z.string(),
+        toolName: z.string(),
+        providerExecuted: z.boolean().optional(),
+        providerMetadata: providerMetadataSchema.optional(),
+        dynamic: z.boolean().optional(),
+        title: z.string().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('tool-input-delta'),
+        toolCallId: z.string(),
+        inputTextDelta: z.string(),
+      }),
+      z.strictObject({
+        type: z.literal('tool-input-available'),
+        toolCallId: z.string(),
+        toolName: z.string(),
+        input: z.unknown(),
+        providerExecuted: z.boolean().optional(),
+        providerMetadata: providerMetadataSchema.optional(),
+        dynamic: z.boolean().optional(),
+        title: z.string().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('tool-input-error'),
+        toolCallId: z.string(),
+        toolName: z.string(),
+        input: z.unknown(),
+        providerExecuted: z.boolean().optional(),
+        providerMetadata: providerMetadataSchema.optional(),
+        dynamic: z.boolean().optional(),
+        errorText: z.string(),
+        title: z.string().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('tool-approval-request'),
+        approvalId: z.string(),
+        toolCallId: z.string(),
+      }),
+      z.strictObject({
+        type: z.literal('tool-output-available'),
+        toolCallId: z.string(),
+        output: z.unknown(),
+        providerExecuted: z.boolean().optional(),
+        providerMetadata: providerMetadataSchema.optional(),
+        dynamic: z.boolean().optional(),
+        preliminary: z.boolean().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('tool-output-error'),
+        toolCallId: z.string(),
+        errorText: z.string(),
+        providerExecuted: z.boolean().optional(),
+        providerMetadata: providerMetadataSchema.optional(),
+        dynamic: z.boolean().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('tool-output-denied'),
+        toolCallId: z.string(),
+      }),
+      z.strictObject({
+        type: z.literal('reasoning-start'),
+        id: z.string(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('reasoning-delta'),
+        id: z.string(),
+        delta: z.string(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('reasoning-end'),
+        id: z.string(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('custom'),
+        kind: z.string().transform(value => value as `${string}.${string}`),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('source-url'),
+        sourceId: z.string(),
+        url: z.string(),
+        title: z.string().optional(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('source-document'),
+        sourceId: z.string(),
+        mediaType: z.string(),
+        title: z.string(),
+        filename: z.string().optional(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('file'),
+        url: z.string(),
+        mediaType: z.string(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.literal('reasoning-file'),
+        url: z.string(),
+        mediaType: z.string(),
+        providerMetadata: providerMetadataSchema.optional(),
+      }),
+      z.strictObject({
+        type: z.custom<`data-${string}`>(
+          (value): value is `data-${string}` =>
+            typeof value === 'string' && value.startsWith('data-'),
+          { message: 'Type must start with "data-"' },
+        ),
+        id: z.string().optional(),
+        data: z.unknown(),
+        transient: z.boolean().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('start-step'),
+      }),
+      z.strictObject({
+        type: z.literal('finish-step'),
+      }),
+      z.strictObject({
+        type: z.literal('start'),
+        messageId: z.string().optional(),
+        messageMetadata: z.unknown().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('finish'),
+        finishReason: z
+          .enum([
+            'stop',
+            'length',
+            'content-filter',
+            'tool-calls',
+            'error',
+            'other',
+          ] as const satisfies readonly FinishReason[])
+          .optional(),
+        messageMetadata: z.unknown().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('abort'),
+        reason: z.string().optional(),
+      }),
+      z.strictObject({
+        type: z.literal('message-metadata'),
+        messageMetadata: z.unknown(),
+      }),
+    ]),
+  ),
+);
+
+export type DataUIMessageChunk<DATA_TYPES extends UIDataTypes> = ValueOf<{
+  [NAME in keyof DATA_TYPES & string]: {
+    type: `data-${NAME}`;
+    id?: string;
+    data: DATA_TYPES[NAME];
+    transient?: boolean;
+  };
+}>;
+
+export type UIMessageChunk<
+  METADATA = unknown,
+  DATA_TYPES extends UIDataTypes = UIDataTypes,
+> =
+  | {
+      type: 'text-start';
+      id: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'text-delta';
+      delta: string;
+      id: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'text-end';
+      id: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'reasoning-start';
+      id: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'reasoning-delta';
+      id: string;
+      delta: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'reasoning-end';
+      id: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'custom';
+      kind: `${string}.${string}`;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'error';
+      errorText: string;
+    }
+  | {
+      type: 'tool-input-available';
+      toolCallId: string;
+      toolName: string;
+      input: unknown;
+      providerExecuted?: boolean;
+      providerMetadata?: ProviderMetadata;
+      dynamic?: boolean;
+      title?: string;
+    }
+  | {
+      type: 'tool-input-error';
+      toolCallId: string;
+      toolName: string;
+      input: unknown;
+      providerExecuted?: boolean;
+      providerMetadata?: ProviderMetadata;
+      dynamic?: boolean;
+      errorText: string;
+      title?: string;
+    }
+  | {
+      type: 'tool-approval-request';
+      approvalId: string;
+      toolCallId: string;
+    }
+  | {
+      type: 'tool-output-available';
+      toolCallId: string;
+      output: unknown;
+      providerExecuted?: boolean;
+      providerMetadata?: ProviderMetadata;
+      dynamic?: boolean;
+      preliminary?: boolean;
+    }
+  | {
+      type: 'tool-output-error';
+      toolCallId: string;
+      errorText: string;
+      providerExecuted?: boolean;
+      providerMetadata?: ProviderMetadata;
+      dynamic?: boolean;
+    }
+  | {
+      type: 'tool-output-denied';
+      toolCallId: string;
+    }
+  | {
+      type: 'tool-input-start';
+      toolCallId: string;
+      toolName: string;
+      providerExecuted?: boolean;
+      providerMetadata?: ProviderMetadata;
+      dynamic?: boolean;
+      title?: string;
+    }
+  | {
+      type: 'tool-input-delta';
+      toolCallId: string;
+      inputTextDelta: string;
+    }
+  | {
+      type: 'source-url';
+      sourceId: string;
+      url: string;
+      title?: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'source-document';
+      sourceId: string;
+      mediaType: string;
+      title: string;
+      filename?: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'file';
+      url: string;
+      mediaType: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | {
+      type: 'reasoning-file';
+      url: string;
+      mediaType: string;
+      providerMetadata?: ProviderMetadata;
+    }
+  | DataUIMessageChunk<DATA_TYPES>
+  | {
+      type: 'start-step';
+    }
+  | {
+      type: 'finish-step';
+    }
+  | {
+      type: 'start';
+      messageId?: string;
+      messageMetadata?: METADATA;
+    }
+  | {
+      type: 'finish';
+      finishReason?: FinishReason;
+      messageMetadata?: METADATA;
+    }
+  | {
+      type: 'abort';
+      reason?: string;
+    }
+  | {
+      type: 'message-metadata';
+      messageMetadata: METADATA;
+    };
+
+export function isDataUIMessageChunk(
+  chunk: UIMessageChunk,
+): chunk is DataUIMessageChunk<UIDataTypes> {
+  return chunk.type.startsWith('data-');
+}
+
+export type InferUIMessageChunk<T extends UIMessage> = UIMessageChunk<
+  InferUIMessageMetadata<T>,
+  InferUIMessageData<T>
+>;

package/src/ui-message-stream/ui-message-stream-headers.ts

@@ -0,0 +1,7 @@
+export const UI_MESSAGE_STREAM_HEADERS = {
+  'content-type': 'text/event-stream',
+  'cache-control': 'no-cache',
+  connection: 'keep-alive',
+  'x-vercel-ai-ui-message-stream': 'v1',
+  'x-accel-buffering': 'no', // disable nginx buffering
+};

package/src/ui-message-stream/ui-message-stream-on-finish-callback.ts

@@ -0,0 +1,32 @@
+import { FinishReason } from '../types/language-model';
+import { UIMessage } from '../ui/ui-messages';
+
+export type UIMessageStreamOnFinishCallback<UI_MESSAGE extends UIMessage> =
+  (event: {
+    /**
+     * The updated list of UI messages.
+     */
+    messages: UI_MESSAGE[];
+
+    /**
+     * Indicates whether the response message is a continuation of the last original message,
+     * or if a new message was created.
+     */
+    isContinuation: boolean;
+
+    /**
+     * Indicates whether the stream was aborted.
+     */
+    isAborted: boolean;
+
+    /**
+     * The message that was sent to the client as a response
+     * (including the original message if it was extended).
+     */
+    responseMessage: UI_MESSAGE;
+
+    /**
+     * The reason why the generation finished.
+     */
+    finishReason?: FinishReason;
+  }) => PromiseLike<void> | void;

package/src/ui-message-stream/ui-message-stream-on-step-finish-callback.ts

@@ -0,0 +1,25 @@
+import { UIMessage } from '../ui/ui-messages';
+
+/**
+ * Callback that is called when a step finishes during streaming.
+ * This is useful for persisting intermediate UI messages during multi-step agent runs.
+ */
+export type UIMessageStreamOnStepFinishCallback<UI_MESSAGE extends UIMessage> =
+  (event: {
+    /**
+     * The updated list of UI messages at the end of this step.
+     */
+    messages: UI_MESSAGE[];
+
+    /**
+     * Indicates whether the response message is a continuation of the last original message,
+     * or if a new message was created.
+     */
+    isContinuation: boolean;
+
+    /**
+     * The message that was sent to the client as a response
+     * (including the original message if it was extended).
+     */
+    responseMessage: UI_MESSAGE;
+  }) => PromiseLike<void> | void;

package/src/ui-message-stream/ui-message-stream-response-init.ts

@@ -0,0 +1,14 @@
+/**
+ * Options for creating a UI message stream response.
+ * Extends the standard `ResponseInit` with additional streaming options.
+ */
+export type UIMessageStreamResponseInit = ResponseInit & {
+  /**
+   * Optional callback to consume a copy of the SSE stream independently.
+   * This is useful for logging, debugging, or processing the stream in parallel.
+   * The callback receives a tee'd copy of the stream and does not block the response.
+   */
+  consumeSseStream?: (options: {
+    stream: ReadableStream<string>;
+  }) => PromiseLike<void> | void;
+};

package/src/ui-message-stream/ui-message-stream-writer.ts

@@ -0,0 +1,24 @@
+import { UIMessage } from '../ui';
+import { ErrorHandler } from '../util/error-handler';
+import { InferUIMessageChunk } from './ui-message-chunks';
+
+export interface UIMessageStreamWriter<
+  UI_MESSAGE extends UIMessage = UIMessage,
+> {
+  /**
+   * Appends a data stream part to the stream.
+   */
+  write(part: InferUIMessageChunk<UI_MESSAGE>): void;
+
+  /**
+   * Merges the contents of another stream to this stream.
+   */
+  merge(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>): void;
+
+  /**
+   * Error handler that is used by the data stream writer.
+   * This is intended for forwarding when merging streams
+   * to prevent duplicated error masking.
+   */
+  onError: ErrorHandler | undefined;
+}

package/src/util/as-array.ts

@@ -0,0 +1,3 @@
+export function asArray<T>(value: T | T[] | undefined): T[] {
+  return value === undefined ? [] : Array.isArray(value) ? value : [value];
+}

package/src/util/async-iterable-stream.ts

@@ -0,0 +1,94 @@
+/**
+ * A type that combines AsyncIterable and ReadableStream.
+ * This allows a ReadableStream to be consumed using for-await-of syntax.
+ */
+export type AsyncIterableStream<T> = AsyncIterable<T> & ReadableStream<T>;
+
+/**
+ * Wraps a ReadableStream and returns an object that is both a ReadableStream and an AsyncIterable.
+ * This enables consumption of the stream using for-await-of, with proper resource cleanup on early exit or error.
+ *
+ * @template T The type of the stream's chunks.
+ * @param source The source ReadableStream to wrap.
+ * @returns An AsyncIterableStream that can be used as both a ReadableStream and an AsyncIterable.
+ */
+export function createAsyncIterableStream<T>(
+  source: ReadableStream<T>,
+): AsyncIterableStream<T> {
+  // Pipe through a TransformStream to ensure a fresh, unlocked stream.
+  const stream = source.pipeThrough(new TransformStream<T, T>());
+
+  /**
+   * Implements the async iterator protocol for the stream.
+   * Ensures proper cleanup (cancelling and releasing the reader) on completion, early exit, or error.
+   */
+  (stream as AsyncIterableStream<T>)[Symbol.asyncIterator] = function (
+    this: ReadableStream<T>,
+  ): AsyncIterator<T> {
+    const reader = this.getReader();
+
+    let finished = false;
+
+    /**
+     * Cleans up the reader by cancelling and releasing the lock.
+     */
+    async function cleanup(cancelStream: boolean) {
+      if (finished) return;
+
+      finished = true;
+      try {
+        if (cancelStream) {
+          await reader.cancel?.();
+        }
+      } finally {
+        try {
+          reader.releaseLock();
+        } catch {}
+      }
+    }
+
+    return {
+      /**
+       * Reads the next chunk from the stream.
+       * @returns A promise resolving to the next IteratorResult.
+       */
+      async next(): Promise<IteratorResult<T>> {
+        if (finished) {
+          return { done: true, value: undefined };
+        }
+
+        const { done, value } = await reader.read();
+
+        if (done) {
+          await cleanup(true);
+          return { done: true, value: undefined };
+        }
+
+        return { done: false, value };
+      },
+
+      /**
+       * May be called on early exit (e.g., break from for-await) or after completion.
+       * Ensures the stream is cancelled and resources are released.
+       * @returns A promise resolving to a completed IteratorResult.
+       */
+      async return(): Promise<IteratorResult<T>> {
+        await cleanup(true);
+        return { done: true, value: undefined };
+      },
+
+      /**
+       * Called on early exit with error.
+       * Ensures the stream is cancelled and resources are released, then rethrows the error.
+       * @param err The error to throw.
+       * @returns A promise that rejects with the provided error.
+       */
+      async throw(err: unknown): Promise<IteratorResult<T>> {
+        await cleanup(true);
+        throw err;
+      },
+    };
+  };
+
+  return stream as AsyncIterableStream<T>;
+}

package/src/util/consume-stream.ts

@@ -0,0 +1,31 @@
+/**
+ * Consumes a ReadableStream until it's fully read.
+ *
+ * This function reads the stream chunk by chunk until the stream is exhausted.
+ * It doesn't process or return the data from the stream; it simply ensures
+ * that the entire stream is read.
+ *
+ * @param options - The options for consuming the stream.
+ * @param options.stream - The ReadableStream to be consumed.
+ * @param options.onError - Optional callback to handle errors that occur during consumption.
+ * @returns A promise that resolves when the stream is fully consumed.
+ */
+export async function consumeStream({
+  stream,
+  onError,
+}: {
+  stream: ReadableStream;
+  onError?: (error: unknown) => void;
+}): Promise<void> {
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done } = await reader.read();
+      if (done) break;
+    }
+  } catch (error) {
+    onError?.(error);
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/util/cosine-similarity.ts

@@ -0,0 +1,46 @@
+import { InvalidArgumentError } from '../error/invalid-argument-error';
+
+/**
+ * Calculates the cosine similarity between two vectors. This is a useful metric for
+ * comparing the similarity of two vectors such as embeddings.
+ *
+ * @param vector1 - The first vector.
+ * @param vector2 - The second vector.
+ *
+ * @returns The cosine similarity between vector1 and vector2, or 0 if either vector is the zero vector.
+ *
+ * @throws {InvalidArgumentError} If the vectors do not have the same length.
+ */
+export function cosineSimilarity(vector1: number[], vector2: number[]): number {
+  if (vector1.length !== vector2.length) {
+    throw new InvalidArgumentError({
+      parameter: 'vector1,vector2',
+      value: { vector1Length: vector1.length, vector2Length: vector2.length },
+      message: `Vectors must have the same length`,
+    });
+  }
+
+  const n = vector1.length;
+
+  if (n === 0) {
+    return 0; // Return 0 for empty vectors if no error is thrown
+  }
+
+  let magnitudeSquared1 = 0;
+  let magnitudeSquared2 = 0;
+  let dotProduct = 0;
+
+  for (let i = 0; i < n; i++) {
+    const value1 = vector1[i];
+    const value2 = vector2[i];
+
+    magnitudeSquared1 += value1 * value1;
+    magnitudeSquared2 += value2 * value2;
+    dotProduct += value1 * value2;
+  }
+
+  return magnitudeSquared1 === 0 || magnitudeSquared2 === 0
+    ? 0
+    : dotProduct /
+        (Math.sqrt(magnitudeSquared1) * Math.sqrt(magnitudeSquared2));
+}

package/src/util/create-resolvable-promise.ts

@@ -0,0 +1,30 @@
+import { ErrorHandler } from './error-handler';
+
+/**
+ * Creates a Promise with externally accessible resolve and reject functions.
+ *
+ * @template T - The type of the value that the Promise will resolve to.
+ * @returns An object containing:
+ *   - promise: A Promise that can be resolved or rejected externally.
+ *   - resolve: A function to resolve the Promise with a value of type T.
+ *   - reject: A function to reject the Promise with an error.
+ */
+export function createResolvablePromise<T = any>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: ErrorHandler;
+} {
+  let resolve: (value: T) => void;
+  let reject: ErrorHandler;
+
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return {
+    promise,
+    resolve: resolve!,
+    reject: reject!,
+  };
+}