@convex-dev/agent 0.5.0-alpha.1 → 0.6.0-alpha.1

package/src/validators.ts

@@ -1,10 +1,5 @@
-import {
-  v,
-  type Infer,
-  type ObjectType,
-  type Validator,
-  type Value,
-} from "convex/values";
+import type { Infer, Validator, Value } from "convex/values";
+import { v } from "convex/values";
 import { vVectorDimension } from "./component/vector/tables.js";
 
 // const deprecated = v.optional(v.any()) as unknown as VNull<unknown, "optional">;
@@ -42,11 +37,14 @@ export const vTextPart = v.object({
   type: v.literal("text"),
   text: v.string(),
   providerOptions,
+  providerMetadata,
 });
 
 export const vImagePart = v.object({
   type: v.literal("image"),
   image: v.union(v.string(), v.bytes()),
+  mediaType: v.optional(v.string()),
+  /** @deprecated Use `mediaType` instead. */
   mimeType: v.optional(v.string()),
   providerOptions,
 });
@@ -55,8 +53,11 @@ export const vFilePart = v.object({
   type: v.literal("file"),
   data: v.union(v.string(), v.bytes()),
   filename: v.optional(v.string()),
-  mimeType: v.string(),
+  mediaType: v.optional(v.string()),
+  /** @deprecated Use `mediaType` instead. */
+  mimeType: v.optional(v.string()),
   providerOptions,
+  providerMetadata,
 });
 
 export const vUserContent = v.union(
@@ -69,13 +70,14 @@ export const vReasoningPart = v.object({
   text: v.string(),
   signature: v.optional(v.string()),
   providerOptions,
-  state: v.optional(v.union(v.literal("streaming"), v.literal("done"))),
+  providerMetadata,
 });
 
 export const vRedactedReasoningPart = v.object({
   type: v.literal("redacted-reasoning"),
   data: v.string(),
   providerOptions,
+  providerMetadata,
 });
 
 export const vReasoningDetails = v.array(
@@ -86,41 +88,65 @@ export const vReasoningDetails = v.array(
       text: v.string(),
       signature: v.optional(v.string()),
     }),
-    v.object({
-      type: v.literal("redacted"),
-      data: v.string(),
-    }),
+    v.object({ type: v.literal("redacted"), data: v.string() }),
   ),
 );
 
-export const vToolCallPart = v.object({
-  type: v.literal("tool-call"),
-  toolCallId: v.string(),
-  toolName: v.string(),
-  args: v.any(),
-  providerOptions,
-  providerExecuted: v.optional(v.boolean()),
-});
+export const vSourcePart = v.union(
+  v.object({
+    type: v.literal("source"),
+    sourceType: v.literal("url"),
+    id: v.string(),
+    url: v.string(),
+    title: v.optional(v.string()),
+    providerOptions,
+    providerMetadata,
+  }),
+  v.object({
+    type: v.literal("source"),
+    sourceType: v.literal("document"),
+    id: v.string(),
+    mediaType: v.string(),
+    title: v.string(),
+    filename: v.optional(v.string()),
+    providerOptions,
+    providerMetadata,
+  }),
+);
+export type SourcePart = Infer<typeof vSourcePart>;
 
-export const vAssistantContent = v.union(
-  v.string(),
-  v.array(
-    v.union(
-      vTextPart,
-      vFilePart,
-      vReasoningPart,
-      vRedactedReasoningPart,
-      vToolCallPart,
-    ),
-  ),
+// Union type to support both old (args) and new (input) formats
+// Both include input for type hint support
+export const vToolCallPart = v.union(
+  // New format: input is primary, args is optional for backwards compat
+  v.object({
+    type: v.literal("tool-call"),
+    toolCallId: v.string(),
+    toolName: v.string(),
+    input: v.any(),
+    /** @deprecated Use `input` instead. */
+    args: v.optional(v.any()),
+    providerExecuted: v.optional(v.boolean()),
+    providerOptions,
+    providerMetadata,
+  }),
+  // Legacy format: args is present, input is optional
+  v.object({
+    type: v.literal("tool-call"),
+    toolCallId: v.string(),
+    toolName: v.string(),
+    /** @deprecated Use `input` instead. */
+    args: v.any(),
+    input: v.optional(v.any()),
+    providerExecuted: v.optional(v.boolean()),
+    providerOptions,
+    providerMetadata,
+  }),
 );
 
 const vToolResultContent = v.array(
   v.union(
-    v.object({
-      type: v.literal("text"),
-      text: v.string(),
-    }),
+    v.object({ type: v.literal("text"), text: v.string() }),
     v.object({
       type: v.literal("image"),
       data: v.string(),
@@ -129,22 +155,193 @@ const vToolResultContent = v.array(
   ),
 );
 
+export const vToolResultOutput = v.union(
+  v.object({ type: v.literal("text"), value: v.string(), providerOptions }),
+  v.object({ type: v.literal("json"), value: v.any(), providerOptions }),
+  v.object({
+    type: v.literal("error-text"),
+    value: v.string(),
+    providerOptions,
+  }),
+  v.object({ type: v.literal("error-json"), value: v.any(), providerOptions }),
+  v.object({
+    type: v.literal("execution-denied"),
+    reason: v.optional(v.string()),
+    providerOptions,
+  }),
+  v.object({
+    type: v.literal("content"),
+    value: v.array(
+      v.union(
+        v.object({
+          type: v.literal("text"),
+          text: v.string(),
+          providerOptions,
+        }),
+        /** @deprecated Use `image-data` or `file-data` instead. */
+        v.object({
+          type: v.literal("media"),
+          data: v.string(),
+          mediaType: v.string(),
+        }),
+        v.object({
+          type: v.literal("file-data"),
+          /** Base-64 encoded */
+          data: v.string(),
+          /**
+           * IANA media type.
+           * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+           */
+          mediaType: v.string(),
+          filename: v.optional(v.string()),
+          providerOptions,
+        }),
+        v.object({
+          type: v.literal("file-url"),
+          url: v.string(),
+          providerOptions,
+        }),
+        v.object({
+          type: v.literal("file-id"),
+          /**
+           * ID of the file.
+           *
+           * If you use multiple providers, you need to
+           * specify the provider specific ids using
+           * the Record option. The key is the provider
+           * name, e.g. 'openai' or 'anthropic'.
+           */
+          fileId: v.union(v.string(), v.record(v.string(), v.string())),
+          providerOptions,
+        }),
+        v.object({
+          type: v.literal("image-data"),
+          data: v.string(),
+          /**
+           * IANA media type.
+           * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+           */
+          mediaType: v.string(),
+          providerOptions,
+        }),
+        v.object({
+          type: v.literal("image-url"),
+          url: v.string(),
+          providerOptions,
+        }),
+        v.object({
+          /**
+           * Images that are referenced using a provider file id.
+           */
+          type: v.literal("image-file-id"),
+          /**
+           * Image that is referenced using a provider file id.
+           *
+           * If you use multiple providers, you need to
+           * specify the provider specific ids using
+           * the Record option. The key is the provider
+           * name, e.g. 'openai' or 'anthropic'.
+           */
+          fileId: v.union(v.string(), v.record(v.string(), v.string())),
+          providerOptions,
+        }),
+        v.object({
+          /**
+           * Custom content part. This can be used to implement
+           * provider-specific content parts.
+           */
+          type: v.literal("custom"),
+          providerOptions,
+        }),
+      ),
+    ),
+  }),
+);
+
+/**
+ * Tool approval request prompt part.
+ */
+export const vToolApprovalRequest = v.object({
+  type: v.literal("tool-approval-request"),
+  /**
+   * ID of the tool approval.
+   */
+  approvalId: v.string(),
+  /**
+   * ID of the tool call that the approval request is for.
+   */
+  toolCallId: v.string(),
+  /** @todo Should we continue to include? */
+  providerMetadata,
+  /** @todo Should we continue to include? */
+  providerOptions,
+});
+
+/**
+ * Tool approval response prompt part.
+ */
+export const vToolApprovalResponse = v.object({
+  type: v.literal("tool-approval-response"),
+  /**
+   * ID of the tool approval.
+   */
+  approvalId: v.string(),
+  /**
+   * Flag indicating whether the approval was granted or denied.
+   */
+  approved: v.boolean(),
+  /**
+   * Optional reason for the approval or denial.
+   */
+  reason: v.optional(v.string()),
+  /**
+   * Flag indicating whether the tool call is provider-executed.
+   * Only provider-executed tool approval responses should be sent to the model.
+   */
+  providerExecuted: v.optional(v.boolean()),
+  /** @todo Should we continue to include? */
+  providerMetadata,
+  /** @todo Should we continue to include? */
+  providerOptions,
+});
+
 export const vToolResultPart = v.object({
   type: v.literal("tool-result"),
   toolCallId: v.string(),
   toolName: v.string(),
-  result: v.any(),
+  output: v.optional(vToolResultOutput),
+
   providerOptions,
+  providerMetadata,
   providerExecuted: v.optional(v.boolean()),
 
   // Deprecated in ai v5
+  result: v.optional(v.any()), // either this or output will be present
   isError: v.optional(v.boolean()),
   // This is only here b/c steps include it in toolResults
   // Normal ModelMessage doesn't have this
   args: v.optional(v.any()),
   experimental_content: v.optional(vToolResultContent),
 });
-export const vToolContent = v.array(vToolResultPart);
+export const vToolContent = v.array(
+  v.union(vToolResultPart, vToolApprovalResponse),
+);
+
+export const vAssistantContent = v.union(
+  v.string(),
+  v.array(
+    v.union(
+      vTextPart,
+      vFilePart,
+      vReasoningPart,
+      vRedactedReasoningPart,
+      vToolCallPart,
+      vToolResultPart,
+      vSourcePart,
+      vToolApprovalRequest,
+    ),
+  ),
+);
 
 export const vContent = v.union(vUserContent, vAssistantContent, vToolContent);
 export type Content = Infer<typeof vContent>;
@@ -181,14 +378,27 @@ export const vMessage = v.union(
 );
 export type Message = Infer<typeof vMessage>;
 
+export type MessageContentParts =
+  | Infer<typeof vTextPart>
+  | Infer<typeof vImagePart>
+  | Infer<typeof vFilePart>
+  | Infer<typeof vReasoningPart>
+  | Infer<typeof vRedactedReasoningPart>
+  | Infer<typeof vToolCallPart>
+  | Infer<typeof vToolResultPart>
+  | Infer<typeof vSourcePart>
+  | Infer<typeof vToolApprovalRequest>
+  | Infer<typeof vToolApprovalResponse>;
+
 export const vSource = v.union(
   v.object({
     type: v.optional(v.literal("source")),
     sourceType: v.literal("url"),
     id: v.string(),
-    url: v.optional(v.string()),
+    url: v.string(),
     title: v.optional(v.string()),
     providerOptions,
+    providerMetadata,
   }),
   v.object({
     type: v.literal("source"),
@@ -197,6 +407,7 @@ export const vSource = v.union(
     mediaType: v.string(),
     title: v.string(),
     filename: v.optional(v.string()),
+    providerOptions,
     providerMetadata,
   }),
 );
@@ -209,29 +420,6 @@ export const vRequest = v.object({
   url: v.optional(v.string()),
 });
 
-const vMessageWithFileAndId = v.object({
-  id: v.optional(v.string()),
-  message: vMessage,
-  fileId: v.optional(v.id("files")),
-});
-
-export const vResponse = v.object({
-  id: v.string(),
-  timestamp: v.number(),
-  modelId: v.string(),
-  headers: v.optional(v.record(v.string(), v.string())), // clear these?
-  messages: v.array(vMessageWithFileAndId),
-  body: v.optional(v.any()),
-});
-
-export const vResponseWithoutMessages = v.object({
-  id: v.string(),
-  timestamp: v.number(),
-  modelId: v.string(),
-  headers: v.optional(v.record(v.string(), v.string())), // clear these?
-  body: v.optional(v.any()),
-});
-
 export const vFinishReason = v.union(
   v.literal("stop"),
   v.literal("length"),
@@ -262,17 +450,14 @@ export const vLanguageModelCallWarning = v.union(
     tool: v.any(),
     details: v.optional(v.string()),
   }),
-  v.object({
-    type: v.literal("other"),
-    message: v.string(),
-  }),
+  v.object({ type: v.literal("other"), message: v.string() }),
 );
 
 export const vMessageWithMetadataInternal = v.object({
-  id: v.optional(v.string()), // external id, e.g. from Vercel AI SDK
   message: vMessage,
   text: v.optional(v.string()),
   fileIds: v.optional(v.array(v.id("files"))),
+  status: v.optional(vMessageStatus),
   // metadata
   finishReason: v.optional(vFinishReason),
   model: v.optional(v.string()),
@@ -285,30 +470,29 @@ export const vMessageWithMetadataInternal = v.object({
   warnings: v.optional(v.array(vLanguageModelCallWarning)),
   error: v.optional(v.string()),
 });
+export type MessageWithMetadataInternal = Infer<
+  typeof vMessageWithMetadataInternal
+>;
 export const vMessageWithMetadata = v.object({
   ...vMessageWithMetadataInternal.fields,
   fileIds: v.optional(v.array(v.string())),
 });
 export type MessageWithMetadata = Infer<typeof vMessageWithMetadata>;
 
-export const vMessageEmbeddings = v.object({
+export const vMessageEmbeddingsWithDimension = v.object({
   model: v.string(),
   dimension: vVectorDimension,
   vectors: v.array(v.union(v.array(v.number()), v.null())),
 });
-export type MessageEmbeddings = Infer<typeof vMessageEmbeddings>;
+export type MessageEmbeddingsWithDimension = Infer<
+  typeof vMessageEmbeddingsWithDimension
+>;
 
-export const vObjectResult = v.object({
-  request: vRequest,
-  response: vResponseWithoutMessages,
-  finishReason: vFinishReason,
-  usage: v.optional(v.any()),
-  object: v.any(),
-  error: v.optional(v.string()),
-  warnings: v.optional(v.array(vLanguageModelCallWarning)),
-  providerMetadata,
+export const vMessageEmbeddings = v.object({
+  model: v.string(),
+  vectors: v.array(v.union(v.array(v.number()), v.null())),
 });
-export type ObjectResult = Infer<typeof vObjectResult>;
+export type MessageEmbeddings = Infer<typeof vMessageEmbeddings>;
 
 export const vContextOptionsSearchOptions = v.object({
   limit: v.number(),
@@ -338,18 +522,19 @@ const vPromptFields = {
   promptMessageId: v.optional(v.string()),
 };
 
-export const vCallSettingsFields = {
-  maxTokens: v.optional(v.number()),
+export const vCallSettings = v.object({
+  maxOutputTokens: v.optional(v.number()),
   temperature: v.optional(v.number()),
   topP: v.optional(v.number()),
   topK: v.optional(v.number()),
   presencePenalty: v.optional(v.number()),
   frequencyPenalty: v.optional(v.number()),
+  stopSequences: v.optional(v.array(v.string())),
   seed: v.optional(v.number()),
   maxRetries: v.optional(v.number()),
   headers: v.optional(v.record(v.string(), v.string())),
-};
-export type CallSettings = ObjectType<typeof vCallSettingsFields>;
+});
+export type CallSettings = Infer<typeof vCallSettings>;
 
 const vCommonArgs = {
   userId: v.optional(v.string()),
@@ -357,7 +542,7 @@ const vCommonArgs = {
   contextOptions: v.optional(vContextOptions),
   storageOptions: v.optional(vStorageOptions),
   providerOptions,
-  ...vCallSettingsFields,
+  callSettings: v.optional(vCallSettings),
   ...vPromptFields,
 };
 
@@ -369,10 +554,7 @@ export const vTextArgs = v.object({
       v.literal("auto"),
       v.literal("none"),
       v.literal("required"),
-      v.object({
-        type: v.literal("tool"),
-        toolName: v.string(),
-      }),
+      v.object({ type: v.literal("tool"), toolName: v.string() }),
     ),
   ),
   maxSteps: v.optional(v.number()),
@@ -408,93 +590,6 @@ export function vPaginationResult<
   });
 }
 
-export const vTextStreamPartV4 = v.union(
-  v.object({
-    type: v.literal("text-delta"),
-    textDelta: v.string(),
-  }),
-  v.object({
-    type: v.literal("reasoning"),
-    textDelta: v.string(),
-  }),
-  v.object({
-    type: v.literal("source"),
-    source: v.object({
-      sourceType: v.literal("url"),
-      id: v.string(),
-      url: v.optional(v.string()),
-      title: v.optional(v.string()),
-      providerOptions,
-    }),
-  }),
-  vToolCallPart,
-  vToolResultPart,
-  v.object({
-    type: v.literal("tool-call-streaming-start"),
-    toolCallId: v.string(),
-    toolName: v.string(),
-  }),
-  v.object({
-    type: v.literal("tool-call-delta"),
-    toolCallId: v.string(),
-    toolName: v.string(),
-    argsTextDelta: v.string(),
-  }),
-);
-export const vTextStreamPartV5 = v.union(
-  v.object({
-    type: v.literal("text-delta"),
-    id: v.string(),
-    text: v.string(),
-    providerMetadata,
-  }),
-  v.object({
-    type: v.literal("reasoning-delta"),
-    id: v.string(),
-    text: v.string(),
-    providerMetadata,
-  }),
-  vSource,
-  v.object({
-    type: v.literal("tool-call"),
-    toolCallId: v.string(),
-    toolName: v.string(),
-    input: v.any(),
-    providerExecuted: v.optional(v.boolean()),
-    dynamic: v.optional(v.boolean()),
-    providerMetadata,
-  }),
-  v.object({
-    type: v.literal("tool-input-start"),
-    id: v.string(),
-    toolName: v.string(),
-    providerMetadata,
-    providerExecuted: v.optional(v.boolean()),
-    dynamic: v.optional(v.boolean()),
-  }),
-  v.object({
-    type: v.literal("tool-input-delta"),
-    id: v.string(),
-    delta: v.string(),
-    providerMetadata,
-  }),
-  v.object({
-    type: v.literal("tool-result"),
-    toolCallId: v.string(),
-    toolName: v.string(),
-    input: v.optional(v.any()),
-    output: v.optional(v.any()),
-    providerExecuted: v.optional(v.boolean()),
-    dynamic: v.optional(v.boolean()),
-  }),
-  v.object({
-    type: v.literal("raw"),
-    rawValue: v.any(),
-  }),
-);
-export const vTextStreamPart = v.union(vTextStreamPartV4, vTextStreamPartV5);
-export type TextStreamPart = Infer<typeof vTextStreamPart>;
-
 export const vStreamCursor = v.object({
   streamId: v.string(),
   cursor: v.number(),
@@ -503,14 +598,8 @@ export type StreamCursor = Infer<typeof vStreamCursor>;
 
 export const vStreamArgs = v.optional(
   v.union(
-    v.object({
-      kind: v.literal("list"),
-      startOrder: v.optional(v.number()),
-    }),
-    v.object({
-      kind: v.literal("deltas"),
-      cursors: v.array(vStreamCursor),
-    }),
+    v.object({ kind: v.literal("list"), startOrder: v.optional(v.number()) }),
+    v.object({ kind: v.literal("deltas"), cursors: v.array(vStreamCursor) }),
   ),
 );
 export type StreamArgs = Infer<typeof vStreamArgs>;
@@ -522,6 +611,9 @@ export const vStreamMessage = v.object({
     v.literal("finished"),
     v.literal("aborted"),
   ),
+  format: v.optional(
+    v.union(v.literal("UIMessageChunk"), v.literal("TextStreamPart")),
+  ),
   order: v.number(),
   stepOrder: v.number(),
   // metadata
@@ -529,7 +621,7 @@ export const vStreamMessage = v.object({
   agentName: v.optional(v.string()),
   model: v.optional(v.string()),
   provider: v.optional(v.string()),
-  providerOptions: v.optional(vProviderOptions), // Sent to model
+  providerOptions, // Sent to model
 });
 export type StreamMessage = Infer<typeof vStreamMessage>;
 
@@ -537,6 +629,54 @@ export const vStreamDelta = v.object({
   streamId: v.string(),
   start: v.number(), // inclusive
   end: v.number(), // exclusive
-  parts: v.array(vTextStreamPart),
+  parts: v.array(v.any()),
 });
 export type StreamDelta = Infer<typeof vStreamDelta>;
+
+export const vMessageDoc = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  userId: v.optional(v.string()), // useful for searching across threads
+  threadId: v.string(),
+  order: v.number(),
+  stepOrder: v.number(),
+  embeddingId: v.optional(v.string()),
+  fileIds: v.optional(v.array(v.string())),
+  error: v.optional(v.string()),
+  status: vMessageStatus,
+
+  // Context on how it was generated
+  agentName: v.optional(v.string()),
+  model: v.optional(v.string()),
+  provider: v.optional(v.string()),
+  providerOptions, // Sent to model
+
+  // The result
+  message: v.optional(vMessage),
+  // Convenience fields extracted from the message
+  tool: v.boolean(), // either tool call (assistant) or tool result (tool)
+  text: v.optional(v.string()),
+
+  // Result metadata
+  usage: v.optional(vUsage),
+  providerMetadata: v.optional(vProviderMetadata), // Received from model
+  sources: v.optional(v.array(vSource)),
+  warnings: v.optional(v.array(vLanguageModelCallWarning)),
+  finishReason: v.optional(vFinishReason),
+  // Likely deprecated soon
+  reasoning: v.optional(v.string()),
+  reasoningDetails: v.optional(vReasoningDetails),
+  // Deprecated
+  id: v.optional(v.string()), // external id, e.g. from Vercel AI SDK
+});
+export type MessageDoc = Infer<typeof vMessageDoc>; // Public
+
+export const vThreadDoc = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  userId: v.optional(v.string()), // Unset for anonymous
+  title: v.optional(v.string()),
+  summary: v.optional(v.string()),
+  status: vThreadStatus,
+});
+export type ThreadDoc = Infer<typeof vThreadDoc>;

package/dist/client/_generated/_ignore.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=_ignore.d.ts.map

package/dist/client/_generated/_ignore.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"_ignore.d.ts","sourceRoot":"","sources":["../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":""}

package/dist/client/_generated/_ignore.js

@@ -1,3 +0,0 @@
-"use strict";
-// This is only here so convex-test can detect a _generated folder
-//# sourceMappingURL=_ignore.js.map