@depup/ai 6.0.116-depup.0

package/src/ui/validate-ui-messages.ts

@@ -0,0 +1,506 @@
+import { TypeValidationContext, TypeValidationError } from '@ai-sdk/provider';
+import {
+  FlexibleSchema,
+  lazySchema,
+  StandardSchemaV1,
+  Tool,
+  validateTypes,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { InvalidArgumentError } from '../error';
+import { providerMetadataSchema } from '../types/provider-metadata';
+import {
+  DataUIPart,
+  InferUIMessageData,
+  InferUIMessageTools,
+  ToolUIPart,
+  UIMessage,
+} from './ui-messages';
+
+const uiMessagesSchema = lazySchema(() =>
+  zodSchema(
+    z
+      .array(
+        z.object({
+          id: z.string(),
+          role: z.enum(['system', 'user', 'assistant']),
+          metadata: z.unknown().optional(),
+          parts: z
+            .array(
+              z.union([
+                z.object({
+                  type: z.literal('text'),
+                  text: z.string(),
+                  state: z.enum(['streaming', 'done']).optional(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('reasoning'),
+                  text: z.string(),
+                  state: z.enum(['streaming', 'done']).optional(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('source-url'),
+                  sourceId: z.string(),
+                  url: z.string(),
+                  title: z.string().optional(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('source-document'),
+                  sourceId: z.string(),
+                  mediaType: z.string(),
+                  title: z.string(),
+                  filename: z.string().optional(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('file'),
+                  mediaType: z.string(),
+                  filename: z.string().optional(),
+                  url: z.string(),
+                  providerMetadata: providerMetadataSchema.optional(),
+                }),
+                z.object({
+                  type: z.literal('step-start'),
+                }),
+                z.object({
+                  type: z.string().startsWith('data-'),
+                  id: z.string().optional(),
+                  data: z.unknown(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('input-streaming'),
+                  input: z.unknown().optional(),
+                  providerExecuted: z.boolean().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  approval: z.never().optional(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('input-available'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.never().optional(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('approval-requested'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.never().optional(),
+                    reason: z.never().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('approval-responded'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.boolean(),
+                    reason: z.string().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('output-available'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.unknown(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  preliminary: z.boolean().optional(),
+                  approval: z
+                    .object({
+                      id: z.string(),
+                      approved: z.literal(true),
+                      reason: z.string().optional(),
+                    })
+                    .optional(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('output-error'),
+                  input: z.unknown(),
+                  rawInput: z.unknown().optional(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.string(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z
+                    .object({
+                      id: z.string(),
+                      approved: z.literal(true),
+                      reason: z.string().optional(),
+                    })
+                    .optional(),
+                }),
+                z.object({
+                  type: z.literal('dynamic-tool'),
+                  toolName: z.string(),
+                  toolCallId: z.string(),
+                  state: z.literal('output-denied'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.literal(false),
+                    reason: z.string().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('input-streaming'),
+                  providerExecuted: z.boolean().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  input: z.unknown().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  approval: z.never().optional(),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('input-available'),
+                  providerExecuted: z.boolean().optional(),
+                  input: z.unknown(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.never().optional(),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('approval-requested'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.never().optional(),
+                    reason: z.never().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('approval-responded'),
+                  input: z.unknown(),
+                  providerExecuted: z.boolean().optional(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.boolean(),
+                    reason: z.string().optional(),
+                  }),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('output-available'),
+                  providerExecuted: z.boolean().optional(),
+                  input: z.unknown(),
+                  output: z.unknown(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  preliminary: z.boolean().optional(),
+                  approval: z
+                    .object({
+                      id: z.string(),
+                      approved: z.literal(true),
+                      reason: z.string().optional(),
+                    })
+                    .optional(),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('output-error'),
+                  providerExecuted: z.boolean().optional(),
+                  input: z.unknown(),
+                  rawInput: z.unknown().optional(),
+                  output: z.never().optional(),
+                  errorText: z.string(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z
+                    .object({
+                      id: z.string(),
+                      approved: z.literal(true),
+                      reason: z.string().optional(),
+                    })
+                    .optional(),
+                }),
+                z.object({
+                  type: z.string().startsWith('tool-'),
+                  toolCallId: z.string(),
+                  state: z.literal('output-denied'),
+                  providerExecuted: z.boolean().optional(),
+                  input: z.unknown(),
+                  output: z.never().optional(),
+                  errorText: z.never().optional(),
+                  callProviderMetadata: providerMetadataSchema.optional(),
+                  approval: z.object({
+                    id: z.string(),
+                    approved: z.literal(false),
+                    reason: z.string().optional(),
+                  }),
+                }),
+              ]),
+            )
+            .nonempty('Message must contain at least one part'),
+        }),
+      )
+      .nonempty('Messages array must not be empty'),
+  ),
+);
+
+export type SafeValidateUIMessagesResult<UI_MESSAGE extends UIMessage> =
+  | {
+      success: true;
+      data: Array<UI_MESSAGE>;
+    }
+  | {
+      success: false;
+      error: Error;
+    };
+
+/**
+ * Validates a list of UI messages like `validateUIMessages`,
+ * but instead of throwing it returns `{ success: true, data }`
+ * or `{ success: false, error }`.
+ */
+export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
+  messages,
+  metadataSchema,
+  dataSchemas,
+  tools,
+}: {
+  messages: unknown;
+  metadataSchema?: FlexibleSchema<UIMessage['metadata']>;
+  dataSchemas?: {
+    [NAME in keyof InferUIMessageData<UI_MESSAGE> & string]?: FlexibleSchema<
+      InferUIMessageData<UI_MESSAGE>[NAME]
+    >;
+  };
+  tools?: {
+    [NAME in keyof InferUIMessageTools<UI_MESSAGE> & string]?: Tool<
+      InferUIMessageTools<UI_MESSAGE>[NAME]['input'],
+      InferUIMessageTools<UI_MESSAGE>[NAME]['output']
+    >;
+  };
+}): Promise<SafeValidateUIMessagesResult<UI_MESSAGE>> {
+  try {
+    if (messages == null) {
+      return {
+        success: false,
+        error: new InvalidArgumentError({
+          parameter: 'messages',
+          value: messages,
+          message: 'messages parameter must be provided',
+        }),
+      };
+    }
+
+    const validatedMessages = await validateTypes({
+      value: messages,
+      schema: uiMessagesSchema,
+    });
+
+    if (metadataSchema) {
+      for (const [msgIdx, message] of validatedMessages.entries()) {
+        await validateTypes({
+          value: message.metadata,
+          schema: metadataSchema,
+          context: {
+            field: `messages[${msgIdx}].metadata`,
+            entityId: message.id,
+          },
+        });
+      }
+    }
+
+    if (dataSchemas || tools) {
+      for (const [msgIdx, message] of validatedMessages.entries()) {
+        for (const [partIdx, part] of message.parts.entries()) {
+          // Data part validation
+          if (dataSchemas && part.type.startsWith('data-')) {
+            const dataPart = part as DataUIPart<InferUIMessageData<UI_MESSAGE>>;
+            const dataName = dataPart.type.slice(5);
+            const dataSchema = dataSchemas[dataName];
+
+            if (!dataSchema) {
+              return {
+                success: false,
+                error: new TypeValidationError({
+                  value: dataPart.data,
+                  cause: `No data schema found for data part ${dataName}`,
+                  context: {
+                    field: `messages[${msgIdx}].parts[${partIdx}].data`,
+                    entityName: dataName,
+                    entityId: dataPart.id,
+                  },
+                }),
+              };
+            }
+
+            await validateTypes({
+              value: dataPart.data,
+              schema: dataSchema,
+              context: {
+                field: `messages[${msgIdx}].parts[${partIdx}].data`,
+                entityName: dataName,
+                entityId: dataPart.id,
+              },
+            });
+          }
+
+          // Tool part validation
+          if (tools && part.type.startsWith('tool-')) {
+            const toolPart = part as ToolUIPart<
+              InferUIMessageTools<UI_MESSAGE>
+            >;
+            const toolName = toolPart.type.slice(5);
+            const tool = tools[toolName];
+
+            // TODO support dynamic tools
+            if (!tool) {
+              return {
+                success: false,
+                error: new TypeValidationError({
+                  value: toolPart.input,
+                  cause: `No tool schema found for tool part ${toolName}`,
+                  context: {
+                    field: `messages[${msgIdx}].parts[${partIdx}].input`,
+                    entityName: toolName,
+                    entityId: toolPart.toolCallId,
+                  },
+                }),
+              };
+            }
+
+            // Tool input validation
+            if (
+              toolPart.state === 'input-available' ||
+              toolPart.state === 'output-available' ||
+              (toolPart.state === 'output-error' &&
+                toolPart.input !== undefined)
+            ) {
+              await validateTypes({
+                value: toolPart.input,
+                schema: tool.inputSchema,
+                context: {
+                  field: `messages[${msgIdx}].parts[${partIdx}].input`,
+                  entityName: toolName,
+                  entityId: toolPart.toolCallId,
+                },
+              });
+            }
+
+            // Tool output validation
+            if (toolPart.state === 'output-available' && tool.outputSchema) {
+              await validateTypes({
+                value: toolPart.output,
+                schema: tool.outputSchema,
+                context: {
+                  field: `messages[${msgIdx}].parts[${partIdx}].output`,
+                  entityName: toolName,
+                  entityId: toolPart.toolCallId,
+                },
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      success: true,
+      data: validatedMessages as Array<UI_MESSAGE>,
+    };
+  } catch (error) {
+    const err = error as Error;
+
+    return {
+      success: false,
+      error: err,
+    };
+  }
+}
+
+/**
+ * Validates a list of UI messages.
+ *
+ * Metadata, data parts, and generic tool call structures are only validated if
+ * the corresponding schemas are provided. Otherwise, they are assumed to be
+ * valid.
+ */
+export async function validateUIMessages<UI_MESSAGE extends UIMessage>({
+  messages,
+  metadataSchema,
+  dataSchemas,
+  tools,
+}: {
+  messages: unknown;
+  metadataSchema?: FlexibleSchema<UIMessage['metadata']>;
+  dataSchemas?: {
+    [NAME in keyof InferUIMessageData<UI_MESSAGE> & string]?: FlexibleSchema<
+      InferUIMessageData<UI_MESSAGE>[NAME]
+    >;
+  };
+  tools?: {
+    [NAME in keyof InferUIMessageTools<UI_MESSAGE> & string]?: Tool<
+      InferUIMessageTools<UI_MESSAGE>[NAME]['input'],
+      InferUIMessageTools<UI_MESSAGE>[NAME]['output']
+    >;
+  };
+}): Promise<Array<UI_MESSAGE>> {
+  const response = await safeValidateUIMessages({
+    messages,
+    metadataSchema,
+    dataSchemas,
+    tools,
+  });
+
+  if (!response.success) throw response.error;
+
+  return response.data;
+}

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

@@ -0,0 +1,44 @@
+import { prepareHeaders } from '../util/prepare-headers';
+import { JsonToSseTransformStream } from './json-to-sse-transform-stream';
+import { UI_MESSAGE_STREAM_HEADERS } from './ui-message-stream-headers';
+import { UIMessageChunk } from './ui-message-chunks';
+import { UIMessageStreamResponseInit } from './ui-message-stream-response-init';
+
+/**
+ * Creates a Response object from a UI message stream.
+ * The stream is transformed to Server-Sent Events (SSE) format.
+ *
+ * @param options.status - The HTTP status code for the response.
+ * @param options.statusText - The HTTP status text for the response.
+ * @param options.headers - Additional HTTP headers to include in the response.
+ * @param options.stream - The UI message chunk stream to send.
+ * @param options.consumeSseStream - Optional callback to consume a copy of the SSE stream independently.
+ *
+ * @returns A `Response` object with the UI message stream as the body.
+ */
+export function createUIMessageStreamResponse({
+  status,
+  statusText,
+  headers,
+  stream,
+  consumeSseStream,
+}: UIMessageStreamResponseInit & {
+  stream: ReadableStream<UIMessageChunk>;
+}): Response {
+  let sseStream = stream.pipeThrough(new JsonToSseTransformStream());
+
+  // when the consumeSseStream is provided, we need to tee the stream
+  // and send the second part to the consumeSseStream function
+  // so that it can be consumed by the client independently
+  if (consumeSseStream) {
+    const [stream1, stream2] = sseStream.tee();
+    sseStream = stream1;
+    consumeSseStream({ stream: stream2 }); // no await (do not block the response)
+  }
+
+  return new Response(sseStream.pipeThrough(new TextEncoderStream()), {
+    status,
+    statusText,
+    headers: prepareHeaders(headers, UI_MESSAGE_STREAM_HEADERS),
+  });
+}

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

@@ -0,0 +1,145 @@
+import {
+  generateId as generateIdFunc,
+  getErrorMessage,
+  IdGenerator,
+} from '@ai-sdk/provider-utils';
+import { UIMessage } from '../ui/ui-messages';
+import { handleUIMessageStreamFinish } from './handle-ui-message-stream-finish';
+import { InferUIMessageChunk } from './ui-message-chunks';
+import { UIMessageStreamOnFinishCallback } from './ui-message-stream-on-finish-callback';
+import { UIMessageStreamOnStepFinishCallback } from './ui-message-stream-on-step-finish-callback';
+import { UIMessageStreamWriter } from './ui-message-stream-writer';
+
+/**
+ * Creates a UI message stream that can be used to send messages to the client.
+ *
+ * @param options.execute - A function that is called with a writer to write UI message chunks to the stream.
+ * @param options.onError - A function that extracts an error message from an error. Defaults to `getErrorMessage`.
+ * @param options.originalMessages - The original messages. If provided, persistence mode is assumed
+ *   and a message ID is provided for the response message.
+ * @param options.onStepFinish - A callback that is called when each step finishes. Useful for persisting intermediate messages.
+ * @param options.onFinish - A callback that is called when the stream finishes.
+ * @param options.generateId - A function that generates a unique ID. Defaults to the built-in ID generator.
+ *
+ * @returns A `ReadableStream` of UI message chunks.
+ */
+export function createUIMessageStream<UI_MESSAGE extends UIMessage>({
+  execute,
+  onError = getErrorMessage,
+  originalMessages,
+  onStepFinish,
+  onFinish,
+  generateId = generateIdFunc,
+}: {
+  execute: (options: {
+    writer: UIMessageStreamWriter<UI_MESSAGE>;
+  }) => Promise<void> | void;
+  onError?: (error: unknown) => string;
+
+  /**
+   * The original messages. If they are provided, persistence mode is assumed,
+   * and a message ID is provided for the response message.
+   */
+  originalMessages?: UI_MESSAGE[];
+
+  /**
+   * Callback that is called when each step finishes during multi-step agent runs.
+   */
+  onStepFinish?: UIMessageStreamOnStepFinishCallback<UI_MESSAGE>;
+
+  onFinish?: UIMessageStreamOnFinishCallback<UI_MESSAGE>;
+
+  generateId?: IdGenerator;
+}): ReadableStream<InferUIMessageChunk<UI_MESSAGE>> {
+  let controller!: ReadableStreamDefaultController<
+    InferUIMessageChunk<UI_MESSAGE>
+  >;
+
+  const ongoingStreamPromises: Promise<void>[] = [];
+
+  const stream = new ReadableStream({
+    start(controllerArg) {
+      controller = controllerArg;
+    },
+  });
+
+  function safeEnqueue(data: InferUIMessageChunk<UI_MESSAGE>) {
+    try {
+      controller.enqueue(data);
+    } catch (error) {
+      // suppress errors when the stream has been closed
+    }
+  }
+
+  try {
+    const result = execute({
+      writer: {
+        write(part: InferUIMessageChunk<UI_MESSAGE>) {
+          safeEnqueue(part);
+        },
+        merge(streamArg) {
+          ongoingStreamPromises.push(
+            (async () => {
+              const reader = streamArg.getReader();
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                safeEnqueue(value);
+              }
+            })().catch(error => {
+              safeEnqueue({
+                type: 'error',
+                errorText: onError(error),
+              } as InferUIMessageChunk<UI_MESSAGE>);
+            }),
+          );
+        },
+        onError,
+      },
+    });
+
+    if (result) {
+      ongoingStreamPromises.push(
+        result.catch(error => {
+          safeEnqueue({
+            type: 'error',
+            errorText: onError(error),
+          } as InferUIMessageChunk<UI_MESSAGE>);
+        }),
+      );
+    }
+  } catch (error) {
+    safeEnqueue({
+      type: 'error',
+      errorText: onError(error),
+    } as InferUIMessageChunk<UI_MESSAGE>);
+  }
+
+  // Wait until all ongoing streams are done. This approach enables merging
+  // streams even after execute has returned, as long as there is still an
+  // open merged stream. This is important to e.g. forward new streams and
+  // from callbacks.
+  const waitForStreams: Promise<void> = new Promise(async resolve => {
+    while (ongoingStreamPromises.length > 0) {
+      await ongoingStreamPromises.shift();
+    }
+    resolve();
+  });
+
+  waitForStreams.finally(() => {
+    try {
+      controller.close();
+    } catch (error) {
+      // suppress errors when the stream has been closed
+    }
+  });
+
+  return handleUIMessageStreamFinish<UI_MESSAGE>({
+    stream,
+    messageId: generateId(),
+    originalMessages,
+    onStepFinish,
+    onFinish,
+    onError,
+  });
+}