@coral-ai/chat 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -1,38 +1,30 @@
-import React, { ReactNode } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
 import { ChatFontSize, ChatFontFamily } from '@coral-ai/markdown';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
-/** Agent registration — keyed by agent name; `"default"` is the catch-all. */
-type AgentConfig = {
-    handler: AgentHandler;
-};
-interface ChatCanvasProps {
-    /** Name of the agent from the `agents` map. Falls back to `"default"`. */
-    agent?: string;
-    /** Named agent handlers keyed by agent name. Use `"default"` for the catch-all. */
-    agents?: Record<string, AgentConfig>;
-    /** Stable conversation identifier, passed back in onMessageComplete. */
-    conversationId?: string;
-    /** Pre-load conversation history. */
-    initialMessages?: ChatMessage[];
-    /** System prompt prepended to every request (not shown in UI). */
-    systemPrompt?: string;
-    /** Called when the user sends a message. Return a string, async iterable, or ChatResponse. */
-    onSendMessage?: (input: string, history: ChatMessage[], attachments: File[]) => ReturnType<AgentHandler>;
-    /** Called after every completed assistant response. Use to persist messages. */
-    onMessageComplete?: (messages: ChatMessage[], conversationId?: string) => void;
-    /** Called on every message-state update (user append, streaming chunk, final). Use for live persistence. */
-    onMessagesChange?: (messages: ChatMessage[], conversationId?: string) => void;
-    /** Called when an error occurs during send. */
-    onError?: (err: unknown) => void;
-    /** Automatically sends this message once on mount. */
-    autoSendMessage?: string;
-    /** Override the thinking indicator text during generation. */
-    thinkingStatus?: string;
-    /** Called when the user clicks Stop. Use to abort your fetch/API call. */
-    onStop?: () => void;
-    children?: ReactNode;
+type ErrorCategory = "auth_billing" | "rate_limit" | "overloaded" | "bad_input" | "not_found" | "server_error" | "unknown";
+/**
+ * A categorized, user-friendly error. This shape is JSON-serializable so it
+ * can be stored on a `ChatMessage` and survive persistence / rehydration.
+ */
+interface NormalizedChatError {
+    category: ErrorCategory;
+    message: string;
 }
-declare const ChatCanvas: React.FC<ChatCanvasProps>;
+/**
+ * Normalizes raw errors from Anthropic, OpenAI, and Google Gemini into a
+ * common category + user-friendly message. Safe to call with any unknown value.
+ * Idempotent — passing an already-normalized error returns it unchanged.
+ */
+declare function normalizeChatError$1(err: unknown): NormalizedChatError;
+interface ChatErrorProps {
+    /** Raw error thrown by your onSendMessage handler — any provider shape works. */
+    error: unknown;
+    /** Optional retry callback shown as a button. */
+    onRetry?: () => void;
+}
+declare const ChatError: React__default.FC<ChatErrorProps>;
 
 type ChatMessage = {
     /** Stable identifier — generated automatically by Chat.Canvas. Used as React key. */
@@ -43,19 +35,93 @@ type ChatMessage = {
     type?: string;
     /** Arbitrary data passed to the custom renderer for this message. */
     metadata?: Record<string, unknown>;
+    /**
+     * If present, this assistant message carries a structured approval request.
+     * Rendered above Chat.Input as a pinned selector while `answer` is undefined;
+     * once answered, it stays in history with `answer` populated for replay.
+     */
+    approval?: ChatApprovalRequest;
+    /**
+     * If present, this assistant message carries a multi-step task plan.
+     * Rendered inline as a collapsible checklist above the message text and
+     * persists in history for replay. Updated in place as the agent streams.
+     */
+    todos?: ChatTodo[];
+    /**
+     * If present, the turn that produced this assistant message failed. The
+     * message renders as an error card (with a Retry button) instead of normal
+     * content. Persisted with the conversation so the error survives reloads.
+     */
+    error?: NormalizedChatError;
+};
+/**
+ * One option in a human-in-the-loop approval / multiple-choice prompt.
+ * Boolean approval is just two options; N-choice is the same shape with N options.
+ */
+type ApprovalOption = {
+    id: string;
+    label: string;
+    description?: string;
+    appearance?: "primary" | "subtle" | "outline" | "secondary";
+    /**
+     * When true, selecting this option does NOT immediately resolve the approval.
+     * The chat input is unlocked so the user can type a free-text reply, which is
+     * then sent as the resolution payload (carrying this option's id alongside the text).
+     * Convention: a final "Other / something else" choice.
+     */
+    freeform?: boolean;
+};
+/** Structured approval request attached to an assistant message. */
+type ChatApprovalRequest = {
+    /** Stable id used to match the eventual response. */
+    id: string;
+    question: string;
+    description?: string;
+    options: ApprovalOption[];
+    /**
+     * Once the user responds, this is populated and the buttons render in their
+     * "answered" terminal state. Distinct from `freeform` so freeform replies
+     * still record which option was the escape hatch.
+     */
+    answer?: {
+        optionId: string;
+        text?: string;
+    };
+};
+/**
+ * One step in a multi-step task plan. The agent emits the whole list on each
+ * update; the convention is exactly one item `in_progress` at a time.
+ */
+type ChatTodo = {
+    /** Stable id for React key + diffing. Optional; index used as fallback. */
+    id?: string;
+    /** Imperative title shown when pending/completed, e.g. "Optimize images". */
+    content: string;
+    /** Present-tense title shown while in_progress, e.g. "Optimizing images". */
+    activeForm?: string;
+    status: "pending" | "in_progress" | "completed";
 };
 /** A single chunk yielded by a streaming onSendMessage. */
 type ChatChunk = string | {
     type: "reasoning";
     content: string;
-} | {
-    type: "agent";
+}
+/** Sets the thinking-indicator word pool while the handler works. */
+ | {
+    type: "status";
     name: string;
+} | {
+    type: "approval";
+    approval: ChatApprovalRequest;
+} | {
+    type: "todos";
+    todos: ChatTodo[];
 };
 type ChatResponse = string | AsyncIterable<ChatChunk> | {
     content: string;
     type?: string;
     metadata?: Record<string, unknown>;
+    todos?: ChatTodo[];
 };
 /** The typed handler signature engineers implement. */
 type ChatAttachment = {
@@ -71,11 +137,20 @@ type ChatMessageRendererProps = {
     /** Sends a message back into the chat as the user. */
     onReply: (content: string) => void;
 };
-type ChatComponents = Record<string, React.FC<ChatMessageRendererProps>>;
+type ChatComponents = Record<string, React__default.FC<ChatMessageRendererProps>>;
 interface ChatProps {
-    agent?: string;
-    /** Named agent handlers keyed by agent name. Use `"default"` for the catch-all. */
-    agents?: Record<string, AgentConfig>;
+    /**
+     * Backend URL. Coral POSTs `{ text, history, attachments }` here on send and
+     * adapts the response to the existing chat pipeline. Used only when no
+     * `onSendMessage` is provided. Falls back to `useCoralConfig().chat.api`
+     * when omitted.
+     */
+    api?: string;
+    /**
+     * Which entries to render in the chat input's `+` menu. Falls back to
+     * `useCoralConfig().chat.attachments` when omitted.
+     */
+    allowedAttachments?: Array<"files" | "photos">;
     conversationId?: string;
     initialMessages?: ChatMessage[];
     systemPrompt?: string;
@@ -85,7 +160,6 @@ interface ChatProps {
     onMessagesChange?: (messages: ChatMessage[], conversationId?: string) => void;
     onError?: (err: unknown) => void;
     autoSendMessage?: string;
-    onFeedback?: (messageIndex: number, rating: "up" | "down") => void;
     onCopy?: (content: string) => void;
     onNavigate?: (path: string) => void;
     components?: ChatComponents;
@@ -96,20 +170,25 @@ interface ChatProps {
     /** Disables the entire input. */
     disabled?: boolean;
     /** Slot rendered at the left of the input toolbar. */
-    actionsStart?: React.ReactNode;
+    actionsStart?: React__default.ReactNode;
     /** Slot rendered at the right of the input toolbar, just before Send/Stop. */
-    actionsEnd?: React.ReactNode;
-    /** Shown 24px above the input while messages is empty. */
-    emptyState?: React.ReactNode;
+    actionsEnd?: React__default.ReactNode;
     /**
-     * Clickable suggestion chips rendered below the input while the chat is empty.
-     * Clicking a chip sends that string as the user's message. Chips fade out once
-     * any message has been sent.
+     * Shown above the input while messages is empty.
+     * - Pass a `string` to render it as a `Title3` heading that hugs its content.
+     * - Pass any other `ReactNode` to flex-fill the available height (centered).
      */
-    promptStarters?: string[];
+    welcomeMessage?: string | React__default.ReactNode;
+    /**
+     * Slot rendered horizontally centered directly under `Chat.Input`, while
+     * the chat is empty (no user/assistant messages yet). Typical use is a row
+     * of `PromptCard`s as starter prompts. Children can call `useChatContext()`
+     * to invoke `sendMessage(text)` on click.
+     */
+    promptSuggestions?: React__default.ReactNode;
     /**
      * Pass `null` to disable the chat's built-in surface motion (input slide to
-     * bottom + prompt-starter fade). Omit / leave undefined for default motion.
+     * bottom on first message). Omit / leave undefined for default motion.
      */
     surfaceMotion?: null;
     /** Font size for assistant message markdown. */
@@ -117,7 +196,46 @@ interface ChatProps {
     /** Font family for assistant message markdown. */
     fontFamily?: ChatFontFamily;
 }
-declare const Chat$1: React.FC<ChatProps>;
+declare const Chat$1: React__default.FC<ChatProps>;
+
+interface ChatCanvasProps {
+    /**
+     * Backend URL Coral POSTs to on send. Used as the built-in handler when
+     * `onSendMessage` is not set.
+     *
+     * Coral serializes attachments to base64 and sends
+     * `{ text, history, attachments: [{ name, mediaType, data }] }` as JSON. The
+     * response can be `{ type?, reply }` (non-streaming) or a Server-Sent-Events
+     * stream of `ChatChunk` JSON lines. The optional `type` field is matched
+     * against Coral's built-in task vocabulary to pick the thinking-indicator
+     * word pool.
+     */
+    api?: string;
+    /** Which entries to render in the chat input's `+` menu (`Chat.AttachButton`). */
+    allowedAttachments?: Array<"files" | "photos">;
+    /** Stable conversation identifier, passed back in onMessageComplete. */
+    conversationId?: string;
+    /** Pre-load conversation history. */
+    initialMessages?: ChatMessage[];
+    /** System prompt prepended to every request (not shown in UI). */
+    systemPrompt?: string;
+    /** Called when the user sends a message. Return a string, async iterable, or ChatResponse. */
+    onSendMessage?: (input: string, history: ChatMessage[], attachments: File[]) => ReturnType<AgentHandler>;
+    /** Called after every completed assistant response. Use to persist messages. */
+    onMessageComplete?: (messages: ChatMessage[], conversationId?: string) => void;
+    /** Called on every message-state update (user append, streaming chunk, final). Use for live persistence. */
+    onMessagesChange?: (messages: ChatMessage[], conversationId?: string) => void;
+    /** Called when an error occurs during send. */
+    onError?: (err: unknown) => void;
+    /** Automatically sends this message once on mount. */
+    autoSendMessage?: string;
+    /** Override the thinking indicator text during generation. */
+    thinkingStatus?: string;
+    /** Called when the user clicks Stop. Use to abort your fetch/API call. */
+    onStop?: () => void;
+    children?: ReactNode;
+}
+declare const ChatCanvas: React__default.FC<ChatCanvasProps>;
 
 interface ChatMessagesProps {
     /**
@@ -125,8 +243,6 @@ interface ChatMessagesProps {
      * Falls back to default markdown rendering if no match.
      */
     components?: ChatComponents;
-    /** Called when the user clicks thumbs-up on an assistant message. */
-    onFeedback?: (messageIndex: number, rating: "up" | "down") => void;
     /** Called when the user copies an assistant message. */
     onCopy?: (content: string) => void;
     /** Called when the user clicks an internal link (href starts with "/"). */
@@ -136,7 +252,31 @@ interface ChatMessagesProps {
     /** Font family for assistant message markdown. */
     fontFamily?: ChatFontFamily;
 }
-declare const ChatMessages: React.FC<ChatMessagesProps>;
+declare const ChatMessages: React__default.FC<ChatMessagesProps>;
+
+type ChatAttachType = "files" | "photos";
+interface ChatAttachButtonProps {
+    /**
+     * Which entries to render in the `+` menu. Order in the array is the order
+     * shown in the menu. Defaults to `['files', 'photos']`.
+     */
+    types?: ChatAttachType[];
+}
+/**
+ * The "+" button rendered by default to the left of the chat input toolbar.
+ *
+ * Opens a Fluent menu with "Add files" / "Add photos" entries (subset
+ * controlled by `types`). Selecting one opens the native OS file picker via a
+ * hidden `<input type="file">` and pushes the resulting `File[]` through
+ * `addAttachments` on `useChatContext`. From there the existing chat pipeline
+ * stages the files, renders preview tiles above the textarea, and hands the
+ * raw `File[]` to the agent handler on send.
+ *
+ * Engineers don't typically render this directly — `<Chat allowedAttachments>`
+ * does it for them. It's exported so the same component can be dropped into
+ * `actionsStart` for fully custom layouts.
+ */
+declare const ChatAttachButton: React__default.FC<ChatAttachButtonProps>;
 
 interface ChatInputProps {
     /** Current input value. Optional inside Chat.Canvas — auto-wired from context. */
@@ -148,51 +288,91 @@ interface ChatInputProps {
     placeholder?: string;
     /** Disabled state. */
     disabled?: boolean;
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
     /** Slot rendered at the left of the bottom toolbar. */
-    actionsStart?: React.ReactNode;
+    actionsStart?: React__default.ReactNode;
     /** Slot rendered at the right of the bottom toolbar, just before Send/Stop. */
-    actionsEnd?: React.ReactNode;
+    actionsEnd?: React__default.ReactNode;
     /** Override attachments when used outside a Chat.Canvas. */
     attachments?: ChatAttachment[];
     /** Override remove handler when used outside a Chat.Canvas. */
     removeAttachment?: (id: string) => void;
+    /**
+     * Renders the `+` (Chat.AttachButton) menu before `actionsStart` content.
+     * When omitted, falls back to the value in `useChatContext().allowedAttachments`
+     * (set by Chat / Chat.Canvas via the `allowedAttachments` prop). When both are
+     * undefined, no `+` button renders — current behavior preserved.
+     */
+    allowedAttachments?: ChatAttachType[];
 }
-declare const ChatInput: React.ForwardRefExoticComponent<ChatInputProps & React.RefAttributes<HTMLTextAreaElement>>;
+declare const ChatInput: React__default.ForwardRefExoticComponent<ChatInputProps & React__default.RefAttributes<HTMLTextAreaElement>>;
 
-type ErrorCategory = "auth_billing" | "rate_limit" | "overloaded" | "bad_input" | "not_found" | "server_error" | "unknown";
-interface NormalizedError {
-    category: ErrorCategory;
+interface ChatCalloutProps {
     message: string;
-}
-/**
- * Normalizes raw errors from Anthropic, OpenAI, and Google Gemini into a
- * common category + user-friendly message. Safe to call with any unknown value.
- */
-declare function normalizeChatError$1(err: unknown): NormalizedError;
-interface ChatErrorProps {
-    /** Raw error thrown by your onSendMessage handler — any provider shape works. */
-    error: unknown;
-    /** Optional retry callback shown as a button. */
     onRetry?: () => void;
+    className?: string;
 }
-declare const ChatError: React.FC<ChatErrorProps>;
+declare const ChatCallout: React__default.FC<ChatCalloutProps>;
 
-interface ChatCalloutProps {
-    message: string;
-    onRetry?: () => void;
+interface ChatApprovalProps {
+    /**
+     * Override the approval request to render. Defaults to `pendingApproval`
+     * from context. Useful for storybook / standalone previews.
+     */
+    approval?: ChatApprovalRequest | null;
+    /**
+     * Override the resolver. Defaults to `resolveApproval` from context.
+     */
+    onSelect?: (optionId: string) => void;
+    /** Disable all buttons. Defaults to false. */
+    disabled?: boolean;
     className?: string;
+    style?: React__default.CSSProperties;
 }
-declare const ChatCallout: React.FC<ChatCalloutProps>;
+declare const ChatApproval: React__default.FC<ChatApprovalProps>;
+
+interface ChatTodoListProps {
+    /** The current task plan. The whole list is replaced on each agent update. */
+    todos: ChatTodo[];
+    className?: string;
+    style?: React__default.CSSProperties;
+}
+declare const ChatTodoList: React__default.FC<ChatTodoListProps>;
+
+interface ThinkingIndicatorProps {
+    isRetrying?: boolean;
+    /** Override the cycling animation with a static status string. The animated icon is retained. */
+    status?: string;
+    /**
+     * Override the pool of cycling words. Falls back to the default `thinkingMessages`
+     * pool when omitted. Ignored while `isRetrying` is true (retry uses its own pool).
+     */
+    messages?: string[];
+}
+declare const ThinkingIndicator: React__default.FC<ThinkingIndicatorProps>;
 
 type CreateHandlerOptions = {
-    /** Your backend endpoint. Receives POST { input, history, context }. */
+    /** Your backend endpoint. Receives POST { input, history, attachments }. */
     endpoint: string;
     /** Additional headers (e.g. Authorization). */
     headers?: HeadersInit;
 };
 /**
  * Wraps a fetch endpoint into an AgentHandler.
+ *
+ * On send it POSTs JSON to `endpoint`:
+ *
+ * ```json
+ * {
+ *   "input": "the user's latest message",
+ *   "history": [{ "role": "user", "content": "..." }],
+ *   "attachments": [{ "name": "cat.jpg", "mediaType": "image/jpeg", "data": "<base64>" }]
+ * }
+ * ```
+ *
+ * Attached files are base64-encoded with `fileToBase64` (same encoding as
+ * Coral's built-in `api` handler); `attachments` is `[]` when none are staged.
+ *
  * The endpoint should stream newline-delimited responses where each line is either:
  *   - A plain text chunk (yielded as a string)
  *   - A JSON-encoded ChatChunk object (e.g. `{"type":"reasoning","content":"..."}`)
@@ -200,53 +380,282 @@ type CreateHandlerOptions = {
  *   - `[DONE]` to signal end-of-stream
  *
  * @example
- * // main.tsx
- * <CoralProvider agents={{ default: { handler: createHandler({ endpoint: '/api/chat' }) } }}>
+ * <Chat onSendMessage={createHandler({ endpoint: '/api/chat' })} />
  */
 declare function createHandler$1({ endpoint, headers }: CreateHandlerOptions): AgentHandler;
 
+/**
+ * Model-agnostic agent tool-use runner.
+ *
+ * `createAgentHandler` turns a provider-neutral `callModel` adapter into a
+ * Coral `AgentHandler`. Coral owns the tool-use loop, the built-in
+ * `update_todos` / `request_approval` tools, and the approval pause/resume
+ * bridge. The engineer owns exactly one function — `callModel` — which is the
+ * only provider-specific code (Claude, Azure OpenAI, …).
+ */
+/** A tool definition. `parameters` is standard JSON Schema for the tool input. */
+type ToolSpec = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+};
+/** A tool invocation emitted by the model. */
+type ToolCall = {
+    id: string;
+    name: string;
+    input: unknown;
+};
+/**
+ * One message in the neutral agent conversation. `raw` on assistant messages
+ * is an opaque passthrough for provider-native content blocks (e.g. Claude
+ * `thinking` + `tool_use` blocks that must replay verbatim across the loop) —
+ * the runner never inspects it; the adapter prefers it when rebuilding.
+ */
+type AgentMessage = {
+    role: "user";
+    content: string;
+} | {
+    role: "assistant";
+    content: string;
+    toolCalls?: ToolCall[];
+    raw?: unknown;
+} | {
+    role: "tool";
+    toolCallId: string;
+    content: string;
+};
+/** What the runner hands the `callModel` adapter for each model call. */
+type ModelRequest = {
+    system?: string;
+    messages: AgentMessage[];
+    tools: ToolSpec[];
+    /** Present only on the first model call of a turn. */
+    attachments?: File[];
+};
+/** A streamed event from the `callModel` adapter. */
+type ModelStreamEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "reasoning";
+    delta: string;
+} | {
+    type: "tool_call";
+    toolCall: ToolCall;
+}
+/** Opaque provider-native representation of the assistant turn, for replay. */
+ | {
+    type: "raw";
+    raw: unknown;
+};
+/** The one function an engineer implements per provider. */
+type CallModel = (req: ModelRequest) => AsyncIterable<ModelStreamEvent>;
+/** Result of executing a custom tool — fed back to the model. */
+type ToolResult = {
+    content: string;
+};
+/** A custom tool the engineer registers alongside the built-ins. */
+type AgentTool = {
+    spec: ToolSpec;
+    execute: (input: unknown) => ToolResult | Promise<ToolResult>;
+};
+/** Paused-agent state, stashed while waiting for an approval answer. */
+type AgentSnapshot = {
+    messages: AgentMessage[];
+    pendingToolCallId: string;
+};
+/**
+ * Where paused agent state is stored between the approval request and the
+ * user's answer. Defaults to an in-memory Map — for a server handler that
+ * spans processes, supply a Redis/db-backed implementation.
+ */
+type AgentSessionStore = {
+    get(id: string): AgentSnapshot | undefined | Promise<AgentSnapshot | undefined>;
+    set(id: string, snap: AgentSnapshot): void | Promise<void>;
+    delete(id: string): void | Promise<void>;
+};
+/** Built-in tool: render / update the inline task checklist. */
+declare const UPDATE_TODOS_TOOL: ToolSpec;
+/** Built-in tool: pause and ask the user to approve / choose before continuing. */
+declare const REQUEST_APPROVAL_TOOL: ToolSpec;
+type CreateAgentHandlerOptions = {
+    /** Provider adapter — the only provider-specific code. */
+    callModel: CallModel;
+    /** Base system prompt. Merged with any `systemPrompt` Coral injects. */
+    system?: string;
+    /** Custom tools, registered alongside the built-in update_todos / request_approval. */
+    tools?: AgentTool[];
+    /** Max tool-loop iterations per turn. Default 8. */
+    maxSteps?: number;
+    /** Where paused-agent state lives. Default: in-memory Map. */
+    sessionStore?: AgentSessionStore;
+};
+/**
+ * Builds a Coral `AgentHandler` that runs a provider-agnostic tool-use loop.
+ *
+ * @example
+ * <Chat onSendMessage={createAgentHandler({ callModel: claudeCallModel })} />
+ */
+declare function createAgentHandler(options: CreateAgentHandlerOptions): AgentHandler;
+
 interface ChatContextValue {
     sendMessage: (overrideInput?: string) => Promise<void>;
+    /**
+     * Re-runs the assistant turn following the matching user message.
+     * If `messageId` is omitted, regenerates the last assistant message.
+     * If `messageId` targets an assistant message, the matching user prompt is replayed.
+     * If `messageId` targets a user message, the existing assistant reply for that turn is discarded and re-generated.
+     */
+    regenerate: (messageId?: string) => Promise<void>;
+    /**
+     * Replaces the content of an existing user message and re-runs from that point.
+     * Truncates everything after the edited message and re-invokes the handler.
+     */
+    editMessage: (messageId: string, newContent: string) => Promise<void>;
     scrollToBottom: () => void;
     /** Pre-binds navigator.clipboard.writeText + the onCopy prop callback. */
     handleCopy: (content: string) => void;
     messages: ChatMessage[];
-    setMessages: React.Dispatch<React.SetStateAction<ChatMessage[]>>;
+    setMessages: React__default.Dispatch<React__default.SetStateAction<ChatMessage[]>>;
     input: string;
-    setInput: React.Dispatch<React.SetStateAction<string>>;
+    setInput: React__default.Dispatch<React__default.SetStateAction<string>>;
     isTyping: boolean;
     isRetrying: boolean;
     isInterrupted: boolean;
     streamingReasoning: string;
-    streamingAgentName?: string;
+    /** Name from the latest streamed `status` chunk — picks the thinking-indicator word pool. */
+    streamingStatus?: string;
     /** Forwarded from Chat.Canvas thinkingStatus prop so Chat.Messages can read it. */
     thinkingStatus?: string;
-    chatError: unknown | null;
     showScrollButton: boolean;
     /** Called by Chat.Input to report its measured height so Canvas positions the scroll button. */
     setInputHeight: (height: number) => void;
-    messagesContainerRef: React.RefObject<HTMLDivElement | null>;
+    messagesContainerRef: React__default.RefObject<HTMLDivElement | null>;
     /** Called by Chat.Messages on mount/unmount so Canvas can attach scroll listener lazily. */
     registerMessagesContainer: (el: HTMLDivElement | null) => void;
-    bottomRef: React.RefObject<HTMLDivElement | null>;
-    lastUserInputRef: React.MutableRefObject<string>;
-    hasEverSentRef: React.MutableRefObject<boolean>;
-    shouldStopRef: React.MutableRefObject<boolean>;
+    bottomRef: React__default.RefObject<HTMLDivElement | null>;
+    lastUserInputRef: React__default.MutableRefObject<string>;
+    hasEverSentRef: React__default.MutableRefObject<boolean>;
+    shouldStopRef: React__default.MutableRefObject<boolean>;
     attachments: ChatAttachment[];
     addAttachments: (files: File[]) => void;
     removeAttachment: (id: string) => void;
+    /** Declarative list of allowed attachment kinds; renders the `+` menu in Chat.Input when set. */
+    allowedAttachments?: Array<"files" | "photos">;
+    /** Latest unanswered approval request from the assistant, or null. */
+    pendingApproval: ChatApprovalRequest | null;
+    /**
+     * Set when the user clicks an option marked `freeform: true`. While this is
+     * non-null, Chat.Input is unlocked and the next submission resolves the
+     * approval (carrying the typed text) instead of being sent as a normal turn.
+     */
+    awaitingFreeformApproval: {
+        approvalId: string;
+        optionId: string;
+    } | null;
+    /**
+     * Resolves an approval request. If the option is `freeform`, transitions
+     * into the awaiting-freeform state instead of resolving immediately.
+     */
+    resolveApproval: (approvalId: string, optionId: string) => void;
     onStop?: () => void;
 }
 declare function useChatContext(): ChatContextValue;
 
+/**
+ * Reads a browser `File` and returns its raw base64 payload (without the
+ * `data:<mime>;base64,` prefix).
+ *
+ * Used by Coral's built-in `api` handler to serialize attachments before
+ * POSTing them to the engineer's backend, and exported so consumers writing
+ * a custom `onSendMessage` can reuse the same encoding.
+ */
+declare function fileToBase64(file: File): Promise<string>;
+
+/**
+ * Built-in task vocabulary for the thinking indicator's per-task word pools.
+ *
+ * A handler streams a `{ type: "status", name }` chunk to tell the indicator
+ * which pool to cycle while it works. `name` is matched against these keys;
+ * anything unrecognized falls back to the `text` pool.
+ *
+ * - `text`  — default text-only response.
+ * - `photo` — vision / image-reading responses.
+ * - `file`  — document / PDF responses.
+ * - `voice` — audio transcription responses.
+ */
+type CoralTaskType = "text" | "photo" | "file" | "voice";
+declare const DEFAULT_TASK_MESSAGES: Record<CoralTaskType, string[]>;
+/**
+ * Picks the thinking-indicator word pool for a streamed status name. If `name`
+ * matches a built-in task type, its pool is used; otherwise the `text` pool is
+ * the fallback. For bespoke copy, use the `thinkingStatus` prop on `<Chat>`.
+ */
+declare function resolveTaskMessages(name?: string): string[];
+
+/**
+ * A stored conversation. Consumers typically persist this shape via the
+ * adapter they pass to `ChatThreadsProvider`.
+ */
+interface ChatThread {
+    id: string;
+    title: string;
+    messages: ChatMessage[];
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * Storage seam. Implement this against your backend (REST, IndexedDB,
+ * Firestore, etc.). The provider handles in-memory state so UI updates are
+ * synchronous; your adapter only needs to persist.
+ */
+interface ChatThreadsAdapter {
+    list(): Promise<ChatThread[]> | ChatThread[];
+    get?(id: string): Promise<ChatThread | undefined> | ChatThread | undefined;
+    create(initial?: Partial<ChatThread>): Promise<ChatThread> | ChatThread;
+    save(thread: ChatThread): Promise<void> | void;
+    rename(id: string, newTitle: string): Promise<void> | void;
+    remove(id: string): Promise<void> | void;
+}
+interface ChatThreadsContextValue {
+    threads: ChatThread[];
+    activeThreadId?: string;
+    activeThread?: ChatThread;
+    setActiveThreadId: (id: string | undefined) => void;
+    createThread: (initial?: Partial<ChatThread>) => Promise<ChatThread>;
+    renameThread: (id: string, newTitle: string) => Promise<void>;
+    removeThread: (id: string) => Promise<void>;
+    updateThreadMessages: (id: string, messages: ChatMessage[]) => void;
+    isLoading: boolean;
+}
+declare function useChatThreads(): ChatThreadsContextValue;
+/** Default adapter — holds threads in a module-less closure. Use for demos or unit tests. */
+declare function createMemoryThreadsAdapter(initialThreads?: ChatThread[]): ChatThreadsAdapter;
+interface ChatThreadsProviderProps {
+    /** Storage adapter. Defaults to an in-memory adapter if omitted. */
+    adapter?: ChatThreadsAdapter;
+    /** Controlled active thread id. */
+    activeThreadId?: string;
+    /** Uncontrolled initial active thread id. */
+    defaultActiveThreadId?: string;
+    /** Fired when the active thread changes (both controlled and uncontrolled). */
+    onActiveThreadChange?: (id: string | undefined) => void;
+    children?: React.ReactNode;
+}
+declare function ChatThreadsProvider({ adapter: providedAdapter, activeThreadId: controlledId, defaultActiveThreadId, onActiveThreadChange, children, }: ChatThreadsProviderProps): react_jsx_runtime.JSX.Element;
+
 declare const Chat: typeof Chat$1 & {
     Canvas: typeof ChatCanvas;
     Messages: typeof ChatMessages;
     Input: typeof ChatInput;
     Error: typeof ChatError;
     Callout: typeof ChatCallout;
+    Approval: typeof ChatApproval;
+    TodoList: typeof ChatTodoList;
+    AttachButton: typeof ChatAttachButton;
+    ThinkingIndicator: typeof ThinkingIndicator;
 };
 declare const normalizeChatError: typeof normalizeChatError$1;
 declare const createHandler: typeof createHandler$1;
 
-export { type AgentConfig, type AgentHandler, Chat, type ChatAttachment, type ChatCanvasProps, type ChatChunk, type ChatComponents, type ChatErrorProps, type ChatInputProps, type ChatMessage, type ChatMessageRendererProps, type ChatMessagesProps, type ChatResponse, createHandler, normalizeChatError, useChatContext };
+export { type AgentHandler, type AgentMessage, type AgentSessionStore, type AgentSnapshot, type AgentTool, type ApprovalOption, type CallModel, Chat, type ChatApprovalProps, type ChatApprovalRequest, type ChatAttachButtonProps, type ChatAttachType, type ChatAttachment, type ChatCanvasProps, type ChatChunk, type ChatComponents, type ChatErrorProps, type ChatInputProps, type ChatMessage, type ChatMessageRendererProps, type ChatMessagesProps, type ChatResponse, type ChatThread, type ChatThreadsAdapter, type ChatThreadsContextValue, ChatThreadsProvider, type ChatThreadsProviderProps, type ChatTodo, type ChatTodoListProps, type CoralTaskType, type CreateAgentHandlerOptions, DEFAULT_TASK_MESSAGES, type ErrorCategory, type ModelRequest, type ModelStreamEvent, type NormalizedChatError, REQUEST_APPROVAL_TOOL, type ToolCall, type ToolResult, type ToolSpec, UPDATE_TODOS_TOOL, createAgentHandler, createHandler, createMemoryThreadsAdapter, fileToBase64, normalizeChatError, resolveTaskMessages, useChatContext, useChatThreads };