@camelai/run 0.0.0-stage → 0.11.0

package/dist/clients/chat.d.ts

@@ -0,0 +1,237 @@
+/**
+ * A chat with one agent, for any UI framework: the agent's messages as simple typed parts, its status,
+ * the input it waits on, and the actions (send, answer, stop, loadOlder), over your server's agent
+ * handler (`createAgentHandler`) and the browser watcher. No dependencies and no Node APIs.
+ *
+ *   const chat = createAgentChat({ endpoint: "/api/agent" });
+ *   chat.subscribe(() => render(chat.getSnapshot()));
+ *   await chat.send("Where is my order?");
+ *
+ * The snapshot is immutable, and a message or part that did not change is the same object from one
+ * snapshot to the next, so a UI re-renders only what changed (and keys rows by `id`: a sent message
+ * keeps its id when the agent's copy of it arrives).
+ */
+import { type WatchOptions } from "./watch.ts";
+import type { AgentInput, Sender } from "./typescript.ts";
+import type { AgentEvent, AssistantMessage, ImageContent, Message, TextContent } from "./types.ts";
+export type { AgentInput, Sender };
+export type ChatStatus = "connecting" | "ready" | "submitted" | "streaming" | "input_required" | "error";
+/** A failure: `code` is stable (the handler's or the runtime's), `message` is for people. */
+export interface ChatError {
+    code: string;
+    message: string;
+    status?: number;
+}
+export interface TextPart {
+    type: "text";
+    id: string;
+    text: string;
+    streaming: boolean;
+}
+export interface ReasoningPart {
+    type: "reasoning";
+    id: string;
+    text: string;
+    streaming: boolean;
+    redacted?: boolean;
+}
+export interface ImagePart {
+    type: "image";
+    id: string;
+    url: string;
+    mimeType: string;
+}
+/**
+ * A file the agent handed over (`present_file`). `url` is a signed link while one is known; else get
+ * one with `chat.fileUrl(path)`.
+ */
+export interface FilePart {
+    type: "file";
+    id: string;
+    path: string;
+    name: string;
+    contentType?: string;
+    size?: number;
+    caption?: string;
+    url?: string;
+    toolCallId: string;
+}
+export type ToolState = "input_streaming" | "running" | "input_required" | "done" | "error";
+export interface ToolProgress {
+    progress?: number;
+    total?: number;
+    message?: string;
+    text?: string;
+}
+/** A tool call: its arguments (partial while `input_streaming`), and its result once there is one. */
+export interface ToolPart {
+    type: "tool";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    state: ToolState;
+    /** The result's text, its content blocks, `details`, and `data`: the text parsed, when it is JSON. */
+    result?: {
+        text: string;
+        content: (TextContent | ImageContent)[];
+        details?: unknown;
+        data?: unknown;
+    };
+    progress?: ToolProgress;
+    /** What the call waits on from a person, while `input_required`. */
+    input?: ChatInput;
+}
+export type UserPart = TextPart | ImagePart;
+export type AssistantPart = TextPart | ReasoningPart | ToolPart | FilePart;
+export interface UserChatMessage {
+    id: string;
+    role: "user";
+    parts: UserPart[];
+    text: string;
+    from?: Sender;
+    metadata?: Record<string, string>;
+    createdAt: number;
+    /** sending: on its way; sent: the agent has it; failed: see `error` (and `chat.retry(id)`). */
+    status: "sending" | "sent" | "failed";
+    error?: ChatError;
+    /** Its index in the agent's history, once there. */
+    index?: number;
+}
+export interface AssistantChatMessage {
+    id: string;
+    role: "assistant";
+    parts: AssistantPart[];
+    createdAt: number;
+    /** The agent is writing it now. */
+    streaming: boolean;
+    /** How its last response ended: stopped (by `stop()`) or failed (`error`). */
+    stopReason?: "stop" | "aborted" | "error";
+    error?: string;
+}
+export type ChatMessage = UserChatMessage | AssistantChatMessage;
+/** Human input the agent waits on, as the runtime lists it, and whether an answer is on its way. */
+export type ChatInput = AgentInput & {
+    answering: boolean;
+    error?: ChatError;
+};
+export interface ChatSnapshot {
+    status: ChatStatus;
+    messages: ChatMessage[];
+    /** Everything the agent waits on (each is also on its tool part, where the call is shown). */
+    inputs: ChatInput[];
+    /** The latest failure to connect, send or act; null once things work again. */
+    error: ChatError | null;
+    hasOlder: boolean;
+    connected: boolean;
+    agentId: string | null;
+}
+/** An answer's value: approval or url: true/false; question: the label chosen (or labels, or own words), or a map of question to answer; form: its fields. */
+export type InputValue = boolean | string | string[] | Record<string, unknown>;
+export interface InputAnswer {
+    action: "accept" | "decline" | "cancel";
+    content?: unknown;
+}
+export interface AgentChatOptions {
+    /** Your agent handler's URL (`createAgentHandler`), e.g. "/api/agent". */
+    endpoint: string;
+    /** Which of the user's conversations (the handler maps it to their agent). Default: their one agent. */
+    thread?: string;
+    /** Headers for every call to the handler (an Authorization header for an API that does not use cookies). */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /** Default "same-origin": cookies go with the calls. */
+    credentials?: RequestCredentials;
+    /** What a message sent while the agent works does: "queue" (default) waits for the turn; "steer" joins it. */
+    whileRunning?: "queue" | "steer";
+    /** Connect at once (default true). false: call `connect()` (a React provider does, in an effect). */
+    autoConnect?: boolean;
+    /** Passed to the watcher: `transport`, `pageSize`, `hiddenGraceMs`, `stallMs`. */
+    watch?: Pick<WatchOptions, "transport" | "pageSize" | "hiddenGraceMs" | "stallMs">;
+    /** Every event of the agent's stream, as it arrives. */
+    onEvent?: (event: AgentEvent) => void;
+    onError?: (error: ChatError) => void;
+    fetch?: typeof globalThis.fetch;
+}
+export interface SendOptions {
+    /** JSON for your handler's `onSend` (the page the user is on, say); the agent sees it only if you pass it on. */
+    data?: unknown;
+    whileRunning?: "queue" | "steer";
+}
+export interface AgentChat {
+    getSnapshot(): ChatSnapshot;
+    /** Listen for new snapshots; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Send a message: it shows at once (status "sending"), keyed by its id, which it keeps. */
+    send(text: string, options?: SendOptions): Promise<{
+        id: string;
+    }>;
+    /** Send a failed message again (the same id, so it is never sent twice). */
+    retry(messageId: string): Promise<void>;
+    /** Answer an input, with a value (see InputValue) or an answer. */
+    answer(input: ChatInput | string, value: InputValue | InputAnswer): Promise<void>;
+    decline(input: ChatInput | string): Promise<void>;
+    /** Stop the agent's running turn. */
+    stop(): Promise<void>;
+    /** Load the page of history before the oldest message shown; false when there is none. */
+    loadOlder(): Promise<boolean>;
+    /** A signed download link for a file of the agent's (a FilePart's `path`). */
+    fileUrl(path: string): Promise<string>;
+    connect(): void;
+    /** Close the stream; the state stays, and `connect()` opens it again. */
+    disconnect(): void;
+    /** Disconnect for good. */
+    destroy(): void;
+}
+/** An answer to `input` from a plain value (see InputValue). */
+export declare function answerValue(input: Pick<AgentInput, "kind" | "detail">, value: InputValue): InputAnswer;
+/** A message this client sent that is not in the agent's history (yet). */
+export interface LocalSend {
+    id: string;
+    text: string;
+    createdAt: number;
+    status: "sending" | "sent" | "failed";
+    error?: ChatError;
+    data?: unknown;
+    whileRunning?: "queue" | "steer";
+}
+export interface ProjectInput {
+    messages: readonly (Message & {
+        requestId?: string;
+        metadata?: Record<string, string>;
+        from?: Sender;
+    })[];
+    indexes: readonly number[];
+    partial: AssistantMessage | null;
+    progress?: ReadonlyMap<string, unknown>;
+    running: boolean;
+    inputs?: readonly ChatInput[];
+    local?: readonly LocalSend[];
+    /** Signed links to presented files, by path. */
+    files?: ReadonlyMap<string, string>;
+}
+/** What the last projection built, to reuse what did not change. */
+export type ProjectMemo = Map<string, {
+    sources: readonly unknown[];
+    value: unknown;
+    children: string[];
+}>;
+/**
+ * The chat's messages from the agent's (a watcher's view) and the ones sent from here:
+ * - a user message is one message, with the id it was sent with (its `requestId`), so the bubble
+ *   shown when it was sent is the same row once it arrives;
+ * - everything the agent did between two user messages is one assistant message, each tool result
+ *   folded into its call's part;
+ * - a running turn continues the last one only when that one called tools; otherwise it is a new
+ *   message at the index its first message will take, from its first token (never an empty row);
+ * - a message or part whose sources did not change is the same object as last time (`memo`).
+ */
+export declare function projectMessages(input: ProjectInput, memo?: ProjectMemo): ChatMessage[];
+/**
+ * Where the watcher reads the agent: the runtime (with the browser token), or, when the handler proxies
+ * reads, the handler itself (under the thread's path), with the chat's own headers and credentials.
+ */
+export declare function readsFrom(minted: {
+    url?: string;
+    proxy?: boolean;
+}, endpoint: string, thread: string | null | undefined, doFetch: typeof globalThis.fetch, headers?: AgentChatOptions["headers"], credentials?: RequestCredentials): Pick<WatchOptions, "url" | "fetch">;
+/** A chat with the user's agent, through your agent handler: see `AgentChatOptions` and `ChatSnapshot`. */
+export declare function createAgentChat(options: AgentChatOptions): AgentChat;