@convex-dev/agent 0.1.14 → 0.1.15-alpha.1

package/dist/client/index.d.ts

@@ -5,19 +5,23 @@ import type { MessageDoc, ThreadDoc } from "../component/schema.js";
 import { type VectorDimension } from "../component/vector/tables.js";
 import { type AIMessageWithoutId } from "../mapping.js";
 import { extractText, isTool } from "../shared.js";
-import { type MessageWithMetadata, type MessageStatus, type ProviderMetadata, type SearchOptions, type StreamArgs, type Usage } from "../validators.js";
+import { type MessageWithMetadata, type MessageStatus, type ProviderMetadata, type StreamArgs, type Usage, type MessageEmbeddings } from "../validators.js";
 import { createTool } from "./createTool.js";
 import { type StreamingOptions } from "./streaming.js";
 import type { AgentComponent, ContextOptions, GenerationOutputMetadata, Options, OurObjectArgs, OurStreamObjectArgs, RawRequestResponseHandler, RunActionCtx, RunMutationCtx, RunQueryCtx, ActionCtx, StorageOptions, StreamingTextArgs, SyncStreamsReturnValue, TextArgs, Thread, UsageHandler } from "./types.js";
 import type { threadFieldsSupportingPatch } from "../component/threads.js";
+import { listMessages } from "./listMessages.js";
+import { syncStreams } from "./streaming.js";
+import { fetchContextMessages } from "./search.js";
 export { storeFile, getFile } from "./files.js";
 export { serializeDataOrUrl } from "../mapping.js";
 export { vMessageDoc, vThreadDoc } from "../component/schema.js";
 export { vAssistantMessage, vContextOptions, vMessage, vPaginationResult, vProviderMetadata, vStorageOptions, vStreamArgs, vSystemMessage, vToolMessage, vUsage, vUserMessage, } from "../validators.js";
 export type { ToolCtx } from "./createTool.js";
-export { createTool, extractText, isTool };
-export type { AgentComponent, ContextOptions, MessageDoc, ProviderMetadata, StorageOptions, StreamArgs, SyncStreamsReturnValue, Thread, ThreadDoc, Usage, UsageHandler, };
-export declare class Agent<AgentTools extends ToolSet> {
+export { filterOutOrphanedToolMessages } from "./search.js";
+export { createTool, extractText, fetchContextMessages, isTool, listMessages, syncStreams, };
+export type { AgentComponent, ContextOptions, MessageDoc, ProviderMetadata, RawRequestResponseHandler, StorageOptions, StreamArgs, SyncStreamsReturnValue, Thread, ThreadDoc, Usage, UsageHandler, };
+export declare class Agent<AgentTools extends ToolSet = ToolSet> {
     component: AgentComponent;
     options: {
         /**
@@ -381,14 +385,7 @@ export declare class Agent<AgentTools extends ToolSet> {
      * You can pass extra metadata alongside the message, e.g. associated fileIds.
      * @returns The messageId of the saved message.
      */
-    saveMessage(ctx: RunMutationCtx, args: {
-        threadId: string;
-        userId?: string;
-        /**
-         * Metadata to save with the messages. Each element corresponds to the
-         * message at the same index.
-         */
-        metadata?: Omit<MessageWithMetadata, "message">;
+    saveMessage(ctx: RunMutationCtx, args: SaveMessageArgs & {
         /**
          * If true, it will not generate embeddings for the message.
          * Useful if you're saving messages in a mutation where you can't run `fetch`.
@@ -396,16 +393,7 @@ export declare class Agent<AgentTools extends ToolSet> {
          * action later that calls `agent.generateAndSaveEmbeddings`.
          */
         skipEmbeddings?: boolean;
-    } & ({
-        prompt?: undefined;
-        /**
-         * The message to save.
-         */
-        message: CoreMessage;
-    } | {
-        prompt: string;
-        message?: undefined;
-    })): Promise<{
+    }): Promise<{
         messageId: string;
         message: {
             id?: string | undefined;
@@ -537,38 +525,13 @@ export declare class Agent<AgentTools extends ToolSet> {
     }>;
     /**
      * Explicitly save messages associated with the thread (& user if provided)
+     * If you have an embedding model set, it will also generate embeddings for
+     * the messages.
      * @param ctx The ctx parameter to a mutation or action.
      * @param args The messages and context to save
      * @returns
      */
-    saveMessages(ctx: RunMutationCtx | RunActionCtx, args: {
-        threadId: string;
-        userId?: string;
-        /**
-         * The message that these messages are in response to. They will be
-         * the same "order" as this message, at increasing stepOrder(s).
-         */
-        promptMessageId?: string;
-        /**
-         * The messages to save.
-         */
-        messages: CoreMessageMaybeWithId[];
-        /**
-         * Metadata to save with the messages. Each element corresponds to the
-         * message at the same index.
-         */
-        metadata?: Omit<MessageWithMetadata, "message">[];
-        /**
-         * If false, it will "commit" the messages immediately.
-         * If true, it will mark them as pending until the final step has finished.
-         * Defaults to false.
-         */
-        pending?: boolean;
-        /**
-         * If true, it will fail any pending steps.
-         * Defaults to false.
-         */
-        failPendingSteps?: boolean;
+    saveMessages(ctx: RunMutationCtx | RunActionCtx, args: SaveMessagesArgs & {
         /**
          * Skip generating embeddings for the messages. Useful if you're
          * saving messages in a mutation where you can't run `fetch`.
@@ -607,6 +570,7 @@ export declare class Agent<AgentTools extends ToolSet> {
     syncStreams(ctx: RunQueryCtx, args: {
         threadId: string;
         streamArgs: StreamArgs | undefined;
+        includeStatuses?: ("streaming" | "finished" | "aborted")[];
     }): Promise<SyncStreamsReturnValue | undefined>;
     /**
      * Fetch the context messages for a thread.
@@ -871,10 +835,6 @@ export declare class Agent<AgentTools extends ToolSet> {
     }>;
     _shouldSaveOutputMessages(storageOpts?: StorageOptions): boolean;
     _mergedContextOptions(opts: ContextOptions | undefined): ContextOptions;
-    _searchOptionsWithEmbeddingAndDefaults(ctx: RunActionCtx, { userId, threadId }: {
-        userId?: string;
-        threadId?: string;
-    }, contextOptions: ContextOptions, messages: CoreMessage[]): Promise<SearchOptions>;
     doEmbed(ctx: RunActionCtx, options: {
         userId: string | undefined;
         threadId: string | undefined;
@@ -1057,12 +1017,13 @@ export declare class Agent<AgentTools extends ToolSet> {
             excludeToolMessages?: boolean | undefined;
             recentMessages?: number | undefined;
             searchOptions?: {
+                textSearch?: boolean | undefined;
+                vectorSearch?: boolean | undefined;
+                vectorScoreThreshold?: number | undefined;
                 messageRange?: {
                     before: number;
                     after: number;
                 } | undefined;
-                textSearch?: boolean | undefined;
-                vectorSearch?: boolean | undefined;
                 limit: number;
             } | undefined;
             searchOtherThreads?: boolean | undefined;
@@ -1183,12 +1144,13 @@ export declare class Agent<AgentTools extends ToolSet> {
             excludeToolMessages?: boolean | undefined;
             recentMessages?: number | undefined;
             searchOptions?: {
+                textSearch?: boolean | undefined;
+                vectorSearch?: boolean | undefined;
+                vectorScoreThreshold?: number | undefined;
                 messageRange?: {
                     before: number;
                     after: number;
                 } | undefined;
-                textSearch?: boolean | undefined;
-                vectorSearch?: boolean | undefined;
                 limit: number;
             } | undefined;
             searchOtherThreads?: boolean | undefined;
@@ -1349,134 +1311,494 @@ export declare class Agent<AgentTools extends ToolSet> {
         messageIds: string[];
     }>>;
 }
-export declare function filterOutOrphanedToolMessages(docs: MessageDoc[]): {
+type CoreMessageMaybeWithId = CoreMessage & {
     id?: string | undefined;
-    userId?: string | undefined;
-    embeddingId?: string | undefined;
-    fileIds?: string[] | undefined;
-    error?: string | undefined;
-    agentName?: string | undefined;
-    model?: string | undefined;
-    provider?: string | undefined;
-    providerOptions?: Record<string, Record<string, any>> | undefined;
-    message?: {
-        providerOptions?: Record<string, Record<string, any>> | undefined;
-        role: "user";
-        content: string | ({
-            providerOptions?: Record<string, Record<string, any>> | undefined;
-            type: "text";
-            text: string;
-        } | {
-            providerOptions?: Record<string, Record<string, any>> | undefined;
-            mimeType?: string | undefined;
-            type: "image";
-            image: string | ArrayBuffer;
+};
+/**
+ * Create a thread to store messages with an Agent.
+ * @param ctx The context from a mutation or action.
+ * @param component The Agent component, usually `components.agent`.
+ * @param args The associated thread metadata.
+ * @returns The id of the created thread.
+ */
+export declare function createThread(ctx: RunMutationCtx, component: AgentComponent, args?: {
+    userId?: string;
+    title?: string;
+    summary?: string;
+}): Promise<string>;
+/**
+ * Get the metadata for a thread.
+ * @param ctx A ctx object from a query, mutation, or action.
+ * @param args.threadId The thread to get the metadata for.
+ * @returns The metadata for the thread.
+ */
+export declare function getThreadMetadata(ctx: RunQueryCtx, component: AgentComponent, args: {
+    threadId: string;
+}): Promise<ThreadDoc>;
+type SaveMessagesArgs = {
+    threadId: string;
+    userId?: string;
+    /**
+     * The message that these messages are in response to. They will be
+     * the same "order" as this message, at increasing stepOrder(s).
+     */
+    promptMessageId?: string;
+    /**
+     * The messages to save.
+     */
+    messages: CoreMessageMaybeWithId[];
+    /**
+     * Metadata to save with the messages. Each element corresponds to the
+     * message at the same index.
+     */
+    metadata?: Omit<MessageWithMetadata, "message">[];
+    /**
+     * If false, it will "commit" the messages immediately.
+     * If true, it will mark them as pending until the final step has finished.
+     * Defaults to false.
+     */
+    pending?: boolean;
+    /**
+     * If true, it will fail any pending steps.
+     * Defaults to false.
+     */
+    failPendingSteps?: boolean;
+    /**
+     * The embeddings to save with the messages.
+     */
+    embeddings?: MessageEmbeddings;
+};
+/**
+ * Explicitly save messages associated with the thread (& user if provided)
+ */
+export declare function saveMessages(ctx: RunMutationCtx, component: AgentComponent, args: SaveMessagesArgs & {
+    /**
+     * The agent name to associate with the messages.
+     */
+    agentName?: string;
+}): Promise<{
+    lastMessageId: string;
+    messages: {
+        _creationTime: number;
+        _id: string;
+        agentName?: string | undefined;
+        embeddingId?: string | undefined;
+        error?: string | undefined;
+        fileIds?: string[] | undefined;
+        finishReason?: "stop" | "length" | "content-filter" | "tool-calls" | "error" | "other" | "unknown" | undefined;
+        id?: string | undefined;
+        message?: {
+            content: string | ({
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                text: string;
+                type: "text";
+            } | {
+                image: string | ArrayBuffer;
+                mimeType?: string | undefined;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                type: "image";
+            } | {
+                data: string | ArrayBuffer;
+                filename?: string | undefined;
+                mimeType: string;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                type: "file";
+            })[];
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            role: "user";
         } | {
-            providerOptions?: Record<string, Record<string, any>> | undefined;
-            filename?: string | undefined;
-            type: "file";
-            mimeType: string;
-            data: string | ArrayBuffer;
-        })[];
-    } | {
-        providerOptions?: Record<string, Record<string, any>> | undefined;
-        role: "assistant";
-        content: string | ({
-            providerOptions?: Record<string, Record<string, any>> | undefined;
-            type: "text";
-            text: string;
+            content: string | ({
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                text: string;
+                type: "text";
+            } | {
+                data: string | ArrayBuffer;
+                filename?: string | undefined;
+                mimeType: string;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                type: "file";
+            } | {
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                signature?: string | undefined;
+                text: string;
+                type: "reasoning";
+            } | {
+                data: string;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                type: "redacted-reasoning";
+            } | {
+                args: any;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                toolCallId: string;
+                toolName: string;
+                type: "tool-call";
+            })[];
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            role: "assistant";
         } | {
-            providerOptions?: Record<string, Record<string, any>> | undefined;
-            filename?: string | undefined;
-            type: "file";
-            mimeType: string;
-            data: string | ArrayBuffer;
+            content: {
+                args?: any;
+                experimental_content?: ({
+                    text: string;
+                    type: "text";
+                } | {
+                    data: string;
+                    mimeType?: string | undefined;
+                    type: "image";
+                })[] | undefined;
+                isError?: boolean | undefined;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                result: any;
+                toolCallId: string;
+                toolName: string;
+                type: "tool-result";
+            }[];
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            role: "tool";
         } | {
-            providerOptions?: Record<string, Record<string, any>> | undefined;
+            content: string;
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            role: "system";
+        } | undefined;
+        model?: string | undefined;
+        order: number;
+        provider?: string | undefined;
+        providerMetadata?: {
+            [x: string]: {
+                [x: string]: any;
+            };
+        } | undefined;
+        providerOptions?: {
+            [x: string]: {
+                [x: string]: any;
+            };
+        } | undefined;
+        reasoning?: string | undefined;
+        reasoningDetails?: ({
             signature?: string | undefined;
-            type: "reasoning";
             text: string;
+            type: "text";
         } | {
-            providerOptions?: Record<string, Record<string, any>> | undefined;
-            type: "redacted-reasoning";
             data: string;
+            type: "redacted";
+        })[] | undefined;
+        sources?: {
+            id: string;
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            sourceType: "url";
+            title?: string | undefined;
+            url: string;
+        }[] | undefined;
+        status: "pending" | "success" | "failed";
+        stepOrder: number;
+        text?: string | undefined;
+        threadId: string;
+        tool: boolean;
+        usage?: {
+            completionTokens: number;
+            promptTokens: number;
+            totalTokens: number;
+        } | undefined;
+        userId?: string | undefined;
+        warnings?: ({
+            details?: string | undefined;
+            setting: string;
+            type: "unsupported-setting";
         } | {
-            providerOptions?: Record<string, Record<string, any>> | undefined;
-            type: "tool-call";
-            toolCallId: string;
-            toolName: string;
-            args: any;
-        })[];
-    } | {
-        providerOptions?: Record<string, Record<string, any>> | undefined;
-        role: "tool";
-        content: {
-            providerOptions?: Record<string, Record<string, any>> | undefined;
-            args?: any;
-            experimental_content?: ({
-                type: "text";
+            details?: string | undefined;
+            tool: any;
+            type: "unsupported-tool";
+        } | {
+            message: string;
+            type: "other";
+        })[] | undefined;
+    }[];
+}>;
+type SaveMessageArgs = {
+    threadId: string;
+    userId?: string;
+    /**
+     * Metadata to save with the messages. Each element corresponds to the
+     * message at the same index.
+     */
+    metadata?: Omit<MessageWithMetadata, "message">;
+    /**
+     * The embedding to save with the message.
+     */
+    embedding?: {
+        vector: number[];
+        model: string;
+    };
+} & ({
+    prompt?: undefined;
+    /**
+     * The message to save.
+     */
+    message: CoreMessage;
+} | {
+    prompt: string;
+    message?: undefined;
+});
+/**
+ * Save a message to the thread.
+ * @param ctx A ctx object from a mutation or action.
+ * @param args The message and what to associate it with (user / thread)
+ * You can pass extra metadata alongside the message, e.g. associated fileIds.
+ * @returns The messageId of the saved message.
+ */
+export declare function saveMessage(ctx: RunMutationCtx, component: AgentComponent, args: SaveMessageArgs & {
+    /**
+     * The agent name to associate with the message.
+     */
+    agentName?: string;
+}): Promise<{
+    messageId: string;
+    message: {
+        _creationTime: number;
+        _id: string;
+        agentName?: string | undefined;
+        embeddingId?: string | undefined;
+        error?: string | undefined;
+        fileIds?: string[] | undefined;
+        finishReason?: "stop" | "length" | "content-filter" | "tool-calls" | "error" | "other" | "unknown" | undefined;
+        id?: string | undefined;
+        message?: {
+            content: string | ({
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
                 text: string;
+                type: "text";
             } | {
+                image: string | ArrayBuffer;
                 mimeType?: string | undefined;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
                 type: "image";
+            } | {
+                data: string | ArrayBuffer;
+                filename?: string | undefined;
+                mimeType: string;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                type: "file";
+            })[];
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            role: "user";
+        } | {
+            content: string | ({
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                text: string;
+                type: "text";
+            } | {
+                data: string | ArrayBuffer;
+                filename?: string | undefined;
+                mimeType: string;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                type: "file";
+            } | {
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                signature?: string | undefined;
+                text: string;
+                type: "reasoning";
+            } | {
                 data: string;
-            })[] | undefined;
-            isError?: boolean | undefined;
-            type: "tool-result";
-            toolCallId: string;
-            toolName: string;
-            result: any;
-        }[];
-    } | {
-        providerOptions?: Record<string, Record<string, any>> | undefined;
-        role: "system";
-        content: string;
-    } | undefined;
-    text?: string | undefined;
-    reasoning?: string | undefined;
-    usage?: {
-        promptTokens: number;
-        completionTokens: number;
-        totalTokens: number;
-    } | undefined;
-    providerMetadata?: Record<string, Record<string, any>> | undefined;
-    sources?: {
-        title?: string | undefined;
-        providerOptions?: Record<string, Record<string, any>> | undefined;
-        id: string;
-        sourceType: "url";
-        url: string;
-    }[] | undefined;
-    reasoningDetails?: ({
-        signature?: string | undefined;
-        type: "text";
-        text: string;
-    } | {
-        type: "redacted";
-        data: string;
-    })[] | undefined;
-    warnings?: ({
-        details?: string | undefined;
-        type: "unsupported-setting";
-        setting: string;
-    } | {
-        details?: string | undefined;
-        type: "unsupported-tool";
-        tool: any;
-    } | {
-        type: "other";
-        message: string;
-    })[] | undefined;
-    finishReason?: "length" | "error" | "other" | "stop" | "content-filter" | "tool-calls" | "unknown" | undefined;
-    _id: string;
-    _creationTime: number;
-    status: "pending" | "success" | "failed";
-    order: number;
-    threadId: string;
-    stepOrder: number;
-    tool: boolean;
-}[];
-type CoreMessageMaybeWithId = CoreMessage & {
-    id?: string | undefined;
-};
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                type: "redacted-reasoning";
+            } | {
+                args: any;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                toolCallId: string;
+                toolName: string;
+                type: "tool-call";
+            })[];
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            role: "assistant";
+        } | {
+            content: {
+                args?: any;
+                experimental_content?: ({
+                    text: string;
+                    type: "text";
+                } | {
+                    data: string;
+                    mimeType?: string | undefined;
+                    type: "image";
+                })[] | undefined;
+                isError?: boolean | undefined;
+                providerOptions?: {
+                    [x: string]: {
+                        [x: string]: any;
+                    };
+                } | undefined;
+                result: any;
+                toolCallId: string;
+                toolName: string;
+                type: "tool-result";
+            }[];
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            role: "tool";
+        } | {
+            content: string;
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            role: "system";
+        } | undefined;
+        model?: string | undefined;
+        order: number;
+        provider?: string | undefined;
+        providerMetadata?: {
+            [x: string]: {
+                [x: string]: any;
+            };
+        } | undefined;
+        providerOptions?: {
+            [x: string]: {
+                [x: string]: any;
+            };
+        } | undefined;
+        reasoning?: string | undefined;
+        reasoningDetails?: ({
+            signature?: string | undefined;
+            text: string;
+            type: "text";
+        } | {
+            data: string;
+            type: "redacted";
+        })[] | undefined;
+        sources?: {
+            id: string;
+            providerOptions?: {
+                [x: string]: {
+                    [x: string]: any;
+                };
+            } | undefined;
+            sourceType: "url";
+            title?: string | undefined;
+            url: string;
+        }[] | undefined;
+        status: "pending" | "success" | "failed";
+        stepOrder: number;
+        text?: string | undefined;
+        threadId: string;
+        tool: boolean;
+        usage?: {
+            completionTokens: number;
+            promptTokens: number;
+            totalTokens: number;
+        } | undefined;
+        userId?: string | undefined;
+        warnings?: ({
+            details?: string | undefined;
+            setting: string;
+            type: "unsupported-setting";
+        } | {
+            details?: string | undefined;
+            tool: any;
+            type: "unsupported-tool";
+        } | {
+            message: string;
+            type: "other";
+        })[] | undefined;
+    };
+}>;
 //# sourceMappingURL=index.d.ts.map