@convex-dev/agent/dist/client/messages.d.ts

A agent component for Convex.

import type { ModelMessage } from "ai";
import type { PaginationOptions, PaginationResult } from "convex/server";
import type { MessageDoc } from "../validators.js";
import { type Message, type MessageEmbeddings, type MessageStatus, type MessageWithMetadata } from "../validators.js";
import { type UIMessage } from "../UIMessages.js";
import type { AgentComponent, MutationCtx, QueryCtx, ActionCtx } from "./types.js";
/**
 * List messages from a thread.
 * @param ctx A ctx object from a query, mutation, or action.
 * @param component The agent component, usually `components.agent`.
 * @param args.threadId The thread to list messages from.
 * @param args.paginationOpts Pagination options (e.g. via usePaginatedQuery).
 * @param args.excludeToolMessages Whether to exclude tool messages.
 *   False by default.
 * @param args.statuses What statuses to include. All by default.
 * @returns The MessageDoc's in a format compatible with usePaginatedQuery.
 */
export declare function listMessages(ctx: QueryCtx | MutationCtx | ActionCtx, component: AgentComponent, { threadId, paginationOpts, excludeToolMessages, statuses, }: {
    threadId: string;
    paginationOpts: PaginationOptions;
    excludeToolMessages?: boolean;
    statuses?: MessageStatus[];
}): Promise<PaginationResult<MessageDoc>>;
export declare function listUIMessages(ctx: QueryCtx | MutationCtx | ActionCtx, component: AgentComponent, args: {
    threadId: string;
    paginationOpts: PaginationOptions;
}): Promise<PaginationResult<UIMessage>>;
export type SaveMessagesArgs = {
    threadId: string;
    userId?: string | null;
    /**
     * 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: (ModelMessage | Message)[];
    /**
     * Metadata to save with the messages. Each element corresponds to the
     * message at the same index.
     */
    metadata?: Omit<MessageWithMetadata, "message">[];
    /**
     * If true, it will fail any pending steps.
     * Defaults to false.
     */
    failPendingSteps?: boolean;
    /**
     * The embeddings to save with the messages.
     */
    embeddings?: MessageEmbeddings;
    /**
     * A pending message ID to replace when adding messages.
     */
    pendingMessageId?: string;
};
/**
 * Explicitly save messages associated with the thread (& user if provided)
 */
export declare function saveMessages(ctx: MutationCtx | ActionCtx, component: AgentComponent, args: SaveMessagesArgs & {
    /**
     * The agent name to associate with the messages.
     */
    agentName?: string;
}): Promise<{
    messages: MessageDoc[];
}>;
export type SaveMessageArgs = {
    threadId: string;
    userId?: string | null;
    /**
     * The message that these messages are in response to. They will be
     * the same "order" as this message, at increasing stepOrder(s).
     */
    promptMessageId?: 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;
    };
    /**
     * A pending message ID to replace with this message.
     */
    pendingMessageId?: string;
} & ({
    prompt?: undefined;
    /**
     * The message to save.
     */
    message: ModelMessage | Message;
} | {
    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: MutationCtx | ActionCtx, component: AgentComponent, args: SaveMessageArgs & {
    /**
     * The agent name to associate with the message.
     */
    agentName?: string;
}): Promise<{
    messageId: string;
    message: {
        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;
                providerMetadata?: 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;
            } | {
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: 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;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                type: "text";
                text: string;
            } | {
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                filename?: string | undefined;
                type: "file";
                mimeType: string;
                data: string | ArrayBuffer;
            } | {
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                signature?: string | undefined;
                type: "reasoning";
                text: string;
            } | {
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                type: "redacted-reasoning";
                data: string;
            } | {
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                providerExecuted?: boolean | undefined;
                type: "tool-call";
                toolCallId: string;
                toolName: string;
                args: any;
            } | {
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                args?: any;
                providerExecuted?: boolean | undefined;
                output?: {
                    type: "text";
                    value: string;
                } | {
                    type: "json";
                    value: any;
                } | {
                    type: "error-text";
                    value: string;
                } | {
                    type: "error-json";
                    value: any;
                } | {
                    type: "content";
                    value: ({
                        type: "text";
                        text: string;
                    } | {
                        type: "media";
                        data: string;
                        mediaType: string;
                    })[];
                } | undefined;
                result?: any;
                isError?: boolean | undefined;
                experimental_content?: ({
                    type: "text";
                    text: string;
                } | {
                    mimeType?: string | undefined;
                    type: "image";
                    data: string;
                })[] | undefined;
                type: "tool-result";
                toolCallId: string;
                toolName: string;
            } | {
                title?: string | undefined;
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                id: string;
                type: "source";
                sourceType: "url";
                url: string;
            } | {
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                filename?: string | undefined;
                id: string;
                title: string;
                type: "source";
                mediaType: string;
                sourceType: "document";
            })[];
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            role: "tool";
            content: {
                providerOptions?: Record<string, Record<string, any>> | undefined;
                providerMetadata?: Record<string, Record<string, any>> | undefined;
                args?: any;
                providerExecuted?: boolean | undefined;
                output?: {
                    type: "text";
                    value: string;
                } | {
                    type: "json";
                    value: any;
                } | {
                    type: "error-text";
                    value: string;
                } | {
                    type: "error-json";
                    value: any;
                } | {
                    type: "content";
                    value: ({
                        type: "text";
                        text: string;
                    } | {
                        type: "media";
                        data: string;
                        mediaType: string;
                    })[];
                } | undefined;
                result?: any;
                isError?: boolean | undefined;
                experimental_content?: ({
                    type: "text";
                    text: string;
                } | {
                    mimeType?: string | undefined;
                    type: "image";
                    data: string;
                })[] | undefined;
                type: "tool-result";
                toolCallId: string;
                toolName: string;
            }[];
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            role: "system";
            content: string;
        } | undefined;
        text?: string | undefined;
        providerMetadata?: Record<string, Record<string, any>> | undefined;
        reasoning?: string | undefined;
        usage?: {
            reasoningTokens?: number | undefined;
            cachedInputTokens?: number | undefined;
            promptTokens: number;
            completionTokens: number;
            totalTokens: number;
        } | undefined;
        sources?: ({
            title?: string | undefined;
            type?: "source" | undefined;
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            id: string;
            sourceType: "url";
            url: string;
        } | {
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            filename?: string | undefined;
            id: string;
            title: string;
            type: "source";
            mediaType: string;
            sourceType: "document";
        })[] | 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;
        reasoningDetails?: ({
            providerOptions?: Record<string, Record<string, any>> | undefined;
            providerMetadata?: Record<string, Record<string, any>> | undefined;
            signature?: string | undefined;
            type: "reasoning";
            text: string;
        } | {
            signature?: string | undefined;
            type: "text";
            text: string;
        } | {
            type: "redacted";
            data: string;
        })[] | undefined;
        _id: string;
        _creationTime: number;
        status: "pending" | "success" | "failed";
        order: number;
        threadId: string;
        stepOrder: number;
        tool: boolean;
    };
}>;
//# sourceMappingURL=messages.d.ts.map