agentic-ui-kit 0.0.0-stage → 0.1.0

package/dist/types/react/src/components/attachments.d.ts

@@ -0,0 +1,78 @@
+import type { AttachmentPart } from "../../../core/src/index.js";
+/** An attachment in the composer, before it is sent. */
+export interface DraftAttachment {
+    id: string;
+    kind: "text" | "image" | "file";
+    name: string;
+    mime: string;
+    size: number;
+    /** Pasted text. */
+    text?: string;
+    /** Local object URL for image thumbnails. */
+    previewUrl?: string;
+    status: "uploading" | "ready" | "error";
+    fileId?: string;
+    url?: string;
+    error?: string;
+}
+export interface UploadResult {
+    fileId: string;
+    url?: string;
+}
+export interface UseAttachmentsOptions {
+    /** Uploads a file. Without it files are kept locally and count as ready at once. */
+    upload?: (file: File, signal: AbortSignal) => Promise<UploadResult>;
+}
+export interface UseAttachments {
+    attachments: DraftAttachment[];
+    /** True while any file uploads; sending waits for it. */
+    uploading: boolean;
+    addFiles(files: Iterable<File>): void;
+    addText(text: string): void;
+    updateText(id: string, text: string): void;
+    remove(id: string): void;
+    clear(): void;
+    /** Ready attachments as message parts, for `send`. */
+    toParts(): AttachmentPart[];
+}
+/** Composer attachments: pasted text, images with thumbnails, files, each uploading on its own. */
+export declare function useAttachments({ upload }?: UseAttachmentsOptions): UseAttachments;
+/** What a card needs; both composer drafts and sent attachment parts fit. */
+export interface AttachmentCardData {
+    name: string;
+    mime: string;
+    text?: string;
+    /** Image thumbnail. */
+    url?: string;
+    status?: "uploading" | "ready" | "error" | string;
+    error?: string;
+}
+export interface AttachmentCardProps {
+    attachment: AttachmentCardData;
+    /** Shows the remove button (on hover and focus; always on touch). */
+    onRemove?: () => void;
+    /** Pasted text: opens it to view or edit. */
+    onOpen?: () => void;
+    size?: "md" | "sm";
+    className?: string;
+}
+/** A square card: pasted text preview with a PASTED badge, an image thumbnail, or a file with its type. */
+export declare function AttachmentCard({ attachment: a, onRemove, onOpen, size, className }: AttachmentCardProps): import("react").JSX.Element;
+export interface AttachmentRowProps {
+    attachments: DraftAttachment[];
+    onRemove: (id: string) => void;
+    /** Saves edited pasted text. Without it pasted text opens read-only. */
+    onEditText?: (id: string, text: string) => void;
+}
+/** The composer's row of cards above the text. Renders nothing when empty. */
+export declare function AttachmentRow({ attachments, onRemove, onEditText }: AttachmentRowProps): import("react").JSX.Element | null;
+export interface PastedTextDialogProps {
+    /** Open while set. */
+    text: string | undefined;
+    onClose: () => void;
+    /** Makes the text editable. */
+    onSave?: (text: string) => void;
+    title?: string;
+}
+/** Shows pasted text in a modal, editable when `onSave` is set. */
+export declare function PastedTextDialog({ text, onClose, onSave, title }: PastedTextDialogProps): import("react").JSX.Element;

package/dist/types/react/src/components/chat-header.d.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+export interface ChatHeaderProps {
+    title: ReactNode;
+    /** Opens from the title, e.g. `<ChatTitleMenu>`. Without it the title is plain text. */
+    menu?: ReactNode;
+    /** Left of the title, e.g. a project breadcrumb or the sidebar toggle on small screens. */
+    leading?: ReactNode;
+    /** Right side, e.g. Share or a context button. */
+    actions?: ReactNode;
+    className?: string;
+}
+/** The bar above a chat: breadcrumb and title with its menu, actions on the right. */
+export declare function ChatHeader({ title, menu, leading, actions, className }: ChatHeaderProps): import("react").JSX.Element;
+export interface ChatTitleMenuProps {
+    pinned?: boolean;
+    onPin?: () => void;
+    onRename?: () => void;
+    projects?: {
+        id: string;
+        name: string;
+    }[];
+    onAddToProject?: (projectId: string) => void;
+    onCreateProject?: () => void;
+    onShare?: () => void;
+    onDelete?: () => void;
+    /** Extra items, placed before Delete. */
+    children?: ReactNode;
+}
+/** Pin, Rename, Add to project (searchable), Share, Delete. Each shows only when its handler is set. */
+export declare function ChatTitleMenu({ pinned, onPin, onRename, projects, onAddToProject, onCreateProject, onShare, onDelete, children }: ChatTitleMenuProps): import("react").JSX.Element;

package/dist/types/react/src/components/chat-list.d.ts

@@ -0,0 +1,47 @@
+import { type ReactNode } from "react";
+export interface ChatSummary {
+    id: string;
+    title: string;
+    /** A reply is streaming in this chat. */
+    running?: boolean;
+    /** Something new since the user last opened it. */
+    unread?: boolean;
+    /** Link target. Rows render as links when set (middle-click, open in new tab), else as buttons. */
+    href?: string;
+}
+export interface ProjectSummary {
+    type: "project";
+    id: string;
+    name: string;
+    chats: ChatSummary[];
+    defaultExpanded?: boolean;
+    href?: string;
+}
+export type ChatListItem = ChatSummary | ProjectSummary;
+export interface ChatListSection {
+    id: string;
+    /** "Pinned", "Chats and tasks". Without a title the section has no header and cannot collapse. */
+    title?: string;
+    items: ChatListItem[];
+    defaultExpanded?: boolean;
+    /** Next to the title, e.g. "10 new". */
+    badge?: ReactNode;
+    /** Right side of the header, e.g. a filter button. */
+    action?: ReactNode;
+    /** Shows a "View all" row after the items. */
+    onViewAll?: () => void;
+}
+export interface ChatListProps {
+    sections: ChatListSection[];
+    activeId?: string;
+    onSelect?: (chatId: string) => void;
+    /** Opens from a row's "…" button, e.g. `<ChatTitleMenu>` for that chat. */
+    rowMenu?: (chat: ChatSummary) => ReactNode;
+    "aria-label"?: string;
+    className?: string;
+}
+/**
+ * The chat picker: sections of chats and projects, collapsible, with an active row, running and unread
+ * markers and a per-row menu. Usable on its own (in a host's own sidebar) or inside `Sidebar`.
+ */
+export declare function ChatList({ sections, activeId, onSelect, rowMenu, className, ...props }: ChatListProps): import("react").JSX.Element;

package/dist/types/react/src/components/composer.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from "react";
+import type React from "react";
+export interface ComposerProps {
+    onSubmit: (text: string) => void;
+    /** Shown as a stop button while `busy`. */
+    onStop?: () => void;
+    /** A reply is streaming: the send button becomes stop, and Enter does not send. */
+    busy?: boolean;
+    /** Controlled text. Leave both unset to let the composer keep its own. */
+    value?: string;
+    onChange?: (text: string) => void;
+    placeholder?: string;
+    /**
+     * "docked": under a chat in progress. "centered": the empty state, taller. "compact": one row, for
+     * panels and inline use.
+     */
+    variant?: "docked" | "centered" | "compact";
+    /** Left of the toolbar, e.g. `<AttachButton>` and toggles. */
+    leading?: ReactNode;
+    /** Right of the toolbar before send, e.g. `<ModelPicker>`. */
+    trailing?: ReactNode;
+    /** Above the text, e.g. attachment chips. */
+    above?: ReactNode;
+    /** Files pasted or dropped onto the composer. */
+    onFiles?: (files: File[]) => void;
+    /** Pasted text longer than `longPasteChars` goes here instead of into the box, e.g. as a card. */
+    onLongPaste?: (text: string) => void;
+    longPasteChars?: number;
+    /** Allows sending with no text, e.g. when attachments are ready. */
+    allowEmpty?: boolean;
+    /** Holds sending back, e.g. while a file uploads. */
+    submitDisabled?: boolean;
+    isDisabled?: boolean;
+    autoFocus?: boolean;
+    className?: string;
+}
+/** The chat box: growing textarea, toolbar slots, send / stop. Enter sends, Shift+Enter adds a line. */
+export declare function Composer({ onSubmit, onStop, busy, value, onChange, placeholder, variant, leading, trailing, above, onFiles, onLongPaste, longPasteChars, allowEmpty, submitDisabled, isDisabled, autoFocus, className, }: ComposerProps): React.JSX.Element;
+export interface AttachButtonProps {
+    /** The menu, e.g. `<Menu aria-label="Add">…</Menu>`. */
+    children: ReactNode;
+    label?: string;
+}
+/** The `+` button that opens the attach menu above the composer. */
+export declare function AttachButton({ children, label }: AttachButtonProps): React.JSX.Element;

package/dist/types/react/src/components/context-panel.d.ts

@@ -0,0 +1,13 @@
+import type { ContextUsage } from "../../../core/src/index.js";
+export interface ContextPanelProps {
+    usage: ContextUsage;
+    /** Section title. */
+    title?: string;
+    defaultExpanded?: boolean;
+    className?: string;
+}
+/**
+ * What fills the context window: a usage line, a segmented bar, one row per category with its share, and
+ * expandable lists (each MCP tool, each memory file). Deferred categories are listed but not counted.
+ */
+export declare function ContextPanel({ usage, title, defaultExpanded, className }: ContextPanelProps): import("react").JSX.Element;

package/dist/types/react/src/components/markdown.d.ts

@@ -0,0 +1,8 @@
+export interface MarkdownProps {
+    children: string;
+    /** While true, text is paced and new words fade in; unfinished markdown is completed for display. */
+    streaming?: boolean;
+    className?: string;
+}
+/** Message markdown: GFM, KaTeX math ($…$ and $$…$$), Shiki code blocks, smooth fade-in while streaming. */
+export declare function Markdown({ children, streaming, className }: MarkdownProps): import("react").JSX.Element;

package/dist/types/react/src/components/message-list.d.ts

@@ -0,0 +1,18 @@
+import type { Message, Part } from "../../../core/src/index.js";
+import { type ReactNode } from "react";
+import { type Feedback } from "./messages";
+export interface MessageListProps {
+    messages: Message[];
+    onRetry?: (assistantId: string) => void;
+    onEdit?: (userId: string) => void;
+    onFeedback?: (assistantId: string, feedback: Feedback) => void;
+    renderPart?: (part: Part) => ReactNode;
+    /** Under the last message, inside the scroll area, e.g. the docked composer. Stays in view at the bottom. */
+    footer?: ReactNode;
+    className?: string;
+}
+/**
+ * The scrolling conversation. It follows a streaming reply while the reader is at the bottom and leaves
+ * them alone once they scroll up, with a button to jump back. Sending a message always jumps down.
+ */
+export declare function MessageList({ messages, onRetry, onEdit, onFeedback, renderPart, footer, className }: MessageListProps): import("react").JSX.Element;

package/dist/types/react/src/components/messages.d.ts

@@ -0,0 +1,33 @@
+import { type Message, type Part } from "../../../core/src/index.js";
+import { type ReactNode } from "react";
+/** "just now", "5 minutes ago", "21 hours ago", "yesterday", then a date. */
+export declare function formatRelativeTime(iso: string, now?: number): string;
+/** Plain text of a message, for copy and read aloud. */
+export declare function messageText(message: Message): string;
+export interface UserMessageProps {
+    message: Message;
+    onRetry?: () => void;
+    onEdit?: () => void;
+    /** Extra buttons in the action row. */
+    actions?: ReactNode;
+    className?: string;
+}
+/** The user's turn: a bubble on the right, with time, retry, edit and copy under it on hover. */
+export declare function UserMessage({ message, onRetry, onEdit, actions, className }: UserMessageProps): import("react").JSX.Element;
+export type Feedback = "good" | "bad";
+export interface AssistantMessageProps {
+    message: Message;
+    onRetry?: () => void;
+    onFeedback?: (feedback: Feedback) => void;
+    onReadAloud?: () => void;
+    /** Renders parts the kit does not draw itself (custom parts, widgets until WidgetFrame lands). */
+    renderPart?: (part: Part) => ReactNode;
+    /** Extra buttons in the action row. */
+    actions?: ReactNode;
+    className?: string;
+}
+/**
+ * The assistant's turn: activity groups (each with its own token count), markdown, and other parts in
+ * order. When done, copy / read aloud / feedback / retry and the time sit under it.
+ */
+export declare function AssistantMessage({ message, onRetry, onFeedback, onReadAloud, renderPart, actions, className }: AssistantMessageProps): import("react").JSX.Element;

package/dist/types/react/src/components/model-picker.d.ts

@@ -0,0 +1,16 @@
+import type { ModelInfo } from "../../../core/src/index.js";
+import type { ReactNode } from "react";
+export interface ModelPickerProps {
+    models: ModelInfo[];
+    model: string;
+    onModelChange: (id: string) => void;
+    effort?: string;
+    onEffortChange?: (id: string) => void;
+    /** Explains effort at the top of the Effort submenu. */
+    effortNote?: ReactNode;
+    /** Small print at the bottom of the menu, e.g. a link to model docs. */
+    footnote?: ReactNode;
+    className?: string;
+}
+/** "Opus 5.5  High ⌄": the models, an Effort submenu for models that have levels, and More models. */
+export declare function ModelPicker({ models, model, onModelChange, effort, onEffortChange, effortNote, footnote, className, }: ModelPickerProps): import("react").JSX.Element;

package/dist/types/react/src/components/token-counter.d.ts

@@ -0,0 +1,16 @@
+/** Compact token count: 526, 1.4k, 33k, 76.8k, 1M. */
+export declare function formatTokens(n: number): string;
+/**
+ * Follows `target` with a number that counts up smoothly instead of jumping. Each frame closes part of the
+ * gap, so bursts of tokens roll in rather than land at once. Jumps straight there with reduced motion.
+ */
+export declare function useCountUp(target: number): number;
+export interface TokenCounterProps {
+    /** Tokens so far, e.g. from `activityTokens(parts)` or `outputTokens(message)`. */
+    tokens: number;
+    /** "standalone": "↓ 1.2k tokens". "inline": "(1.2k tokens)", for inside a heading. */
+    variant?: "standalone" | "inline";
+    className?: string;
+}
+/** A token count that counts up as `tokens` grows and holds still when it stops growing. */
+export declare function TokenCounter({ tokens, variant, className }: TokenCounterProps): import("react").JSX.Element;

package/dist/types/react/src/components/tools.d.ts

@@ -0,0 +1,68 @@
+import type { ActivityPart, ToolCallPart } from "../../../core/src/index.js";
+import { type ComponentType, type ReactNode } from "react";
+import { type AgentTool } from "../hooks/agent";
+/**
+ * How one kind of tool call shows up in an activity group. Registered by tool name; hosts add their own and
+ * override the built-in ones through `ChatProvider`.
+ */
+export interface ToolView {
+    /** Row label, e.g. "Ran a command". Defaults to the part's title, then its name. */
+    label?: (part: ToolCallPart) => ReactNode;
+    /** Highlighted text after the label, e.g. the search query. Defaults to the part's subtitle. */
+    subtitle?: (part: ToolCallPart) => ReactNode;
+    /** Tooltip on the row label, e.g. the command's description. */
+    hint?: (part: ToolCallPart) => string | undefined;
+    /** The approval question, e.g. "Add 4 events to your calendar?". Defaults to "Allow <label>?". */
+    ask?: (part: ToolCallPart) => ReactNode;
+    /** Phrase for the group heading, lowercase: "ran a command", "ran 3 commands". */
+    summary?: (count: number) => string;
+    /** Body shown when the row is expanded. Defaults to the result, or the input as JSON. */
+    Detail?: ComponentType<{
+        part: ToolCallPart;
+    }>;
+    /**
+     * Renders the call on its own in the message instead of as a row in the activity group, e.g. the
+     * answers to a question or a chart.
+     */
+    Block?: ComponentType<{
+        part: ToolCallPart;
+    }>;
+}
+export type ToolViews = Record<string, ToolView>;
+export declare function ToolViewsProvider({ tools, children }: {
+    tools: ToolViews;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useToolView(name: string): ToolView;
+/** The provider's views, plus views brought by tools the page registered (`ChatTool.view`). */
+export declare function useToolViews(): ToolViews;
+/** A tool with its look in the chat. Register it with `useChatTool` from the component that owns it. */
+export interface ChatTool<Input = any, Output = unknown> extends AgentTool<Input, Output> {
+    view?: ToolView;
+}
+/** `useAgentTool` for tools that bring a view. */
+export declare const useChatTool: <Input, Output>(tool: ChatTool<Input, Output>) => void;
+/** Streaming or running: the model or a tool is busy with it. */
+export declare const isWorking: (part: ActivityPart) => boolean;
+/** Row label for any activity part. */
+export declare function activityLabel(part: ActivityPart, view?: ToolView): ReactNode;
+/**
+ * Heading of an activity group. While live it follows the latest step. Once done it lists what the tools
+ * did, in order ("Ran a command, searched the web"); a group of only thinking shows the first title.
+ */
+export declare function activityHeading(parts: readonly ActivityPart[], views: ToolViews): ReactNode;
+/** A shell command. Input `{ command, description? }`; result a string or `{ stdout, stderr, exitCode }`. */
+export declare const commandTool: ToolView;
+export interface SearchResult {
+    title: string;
+    url: string;
+    /** Icon url. Without one a globe is shown; the kit never fetches icons itself. */
+    favicon?: string;
+}
+/** A web search. Input `{ query }`; result `{ results: SearchResult[] }` or `SearchResult[]`. */
+export declare const webSearchTool: ToolView;
+/** Memory lookups, e.g. Anthropic's memory tool. Input `{ path }`. */
+export declare const memoryTool: ToolView;
+export declare const defaultToolViews: ToolViews;
+/** "9s", "1m 5s". */
+export declare function formatDuration(ms: number): string;

package/dist/types/react/src/components/word-fade.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rehype plugin that wraps each word of prose in `<span class="chat-word">`. CSS fades a span in when it
+ * mounts. React keeps the spans already on screen as the text grows, so a word fades once and is never cut
+ * short or restarted; words revealed together fade together.
+ *
+ * Code, math internals and SVG are left alone. A math element as a whole gets the class, so a formula
+ * fades in as one piece.
+ */
+interface HastNode {
+    type: string;
+    tagName?: string;
+    value?: string;
+    properties?: Record<string, unknown> & {
+        className?: unknown;
+    };
+    children?: HastNode[];
+}
+export declare function rehypeWordFade(): (tree: HastNode) => void;
+export {};

package/dist/types/react/src/core.d.ts

@@ -0,0 +1 @@
+export * from "../../core/src/index.js";

package/dist/types/react/src/hooks/agent.d.ts

@@ -0,0 +1,86 @@
+import type { ToolCallPart } from "../../../core/src/index.js";
+import { type ReactNode } from "react";
+/** JSON Schema for a tool's input, as the model provider expects it. */
+export type JsonSchema = Record<string, unknown>;
+export interface ToolContext {
+    callId: string;
+    messageId: string;
+    /** Aborted when the user stops the chat. */
+    signal: AbortSignal;
+}
+/**
+ * One tool, as the page that owns it sees it. The same definition covers both kinds:
+ *
+ * - Client tool (has `execute`): the model calls it, the backend ends the run with the call awaiting, the
+ *   browser runs `execute` (which can change the page directly) and sends the result back.
+ * - Server tool (no `execute`): the backend runs it. `onResult` lets the page react, e.g. refetch the
+ *   record the tool changed or apply the patch it returned.
+ *
+ * Either kind can need the user's approval first, and either kind can bring its own look in the chat.
+ */
+export interface AgentTool<Input = any, Output = unknown> {
+    name: string;
+    /** For the model. Sent with each request for client tools; server tools are described by the backend. */
+    description?: string;
+    inputSchema?: JsonSchema;
+    execute?: (input: Input, context: ToolContext) => Output | Promise<Output>;
+    /** Ask before running. The backend can also ask, per call, with `needsApproval`. */
+    approval?: boolean | ((input: Input) => boolean);
+    /**
+     * Called whenever a call of this tool changes: input streaming in, awaiting approval, running, done.
+     * For previews, e.g. drawing proposed calendar events while the user decides.
+     */
+    onCall?: (part: ToolCallPart & {
+        input?: Input;
+        result?: Output;
+    }) => void;
+    /** Called once when a call of this tool finishes, client or server, done or failed. */
+    onResult?: (part: ToolCallPart & {
+        input: Input;
+        result?: Output;
+    }) => void;
+}
+/** What a client tool looks like to the backend: sent with every request so it can offer them to the model. */
+export interface ToolSpec {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+}
+/**
+ * The tools and context the page currently offers. Components register what they own while mounted, so
+ * the model's tools follow what is on screen.
+ */
+export declare class AgentRegistry {
+    private tools;
+    private contexts;
+    private listeners;
+    private version;
+    addTool(holder: {
+        current: AgentTool;
+    }): () => void;
+    setContext(key: string, value: unknown): () => void;
+    tool(name: string): AgentTool | undefined;
+    list(): AgentTool[];
+    /** Client tools, for the request. */
+    specs(): ToolSpec[];
+    /** Everything the page shared with `useAgentContext`, for the request. */
+    context(): Record<string, unknown>;
+    subscribe: (listener: () => void) => () => boolean;
+    getVersion: () => number;
+    private emit;
+}
+/** Holds the tools and context for the chats and the page inside it. */
+export declare function AgentProvider({ registry, children }: {
+    registry?: AgentRegistry;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<AgentRegistry | null>>;
+export declare const useAgentRegistry: () => AgentRegistry | null;
+/** Re-renders when tools or context change, e.g. for an inspector. */
+export declare function useAgentSnapshot(): AgentRegistry | null;
+/**
+ * Offers a tool while the calling component is mounted. The latest `tool` is always used, so `execute` can
+ * close over current state; it is only re-registered when the name changes.
+ */
+export declare function useAgentTool<Input, Output>(tool: AgentTool<Input, Output>): void;
+/** Shares page state with the model, e.g. the form's current values. Sent with each request. */
+export declare function useAgentContext(key: string, value: unknown): void;

package/dist/types/react/src/hooks/sidebar-state.d.ts

@@ -0,0 +1,18 @@
+/** Below this width the sidebar is a drawer over the content (phones). */
+export declare const DRAWER_QUERY = "(max-width: 767.98px)";
+/** Below this width a pinned sidebar starts collapsed (tablet portrait). */
+export declare const NARROW_QUERY = "(max-width: 1023.98px)";
+export declare function useMediaQuery(query: string): boolean;
+export interface SidebarState {
+    /** Pinned sidebar shows only icons. */
+    collapsed: boolean;
+    /** The sidebar is a drawer (small screens). */
+    drawer: boolean;
+    drawerOpen: boolean;
+    /** Collapses / expands the pinned sidebar, or opens / closes the drawer. */
+    toggle: () => void;
+    /** Closes the drawer after a pick; does nothing for a pinned sidebar. */
+    dismiss: () => void;
+}
+export declare const SidebarContext: import("react").Context<SidebarState>;
+export declare const useSidebar: () => SidebarState;

package/dist/types/react/src/hooks/smooth-text.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Paces streamed text so it appears at an even rate instead of in network-sized bursts. The reveal speed
+ * follows the backlog: it never falls far behind and never stalls. It stops at word ends so a word fades
+ * in whole. When `streaming` ends the rest catches up quickly. With reduced motion it returns `text`.
+ *
+ * One animation loop runs while there is text left to show; new text only moves its target, so frequent
+ * small deltas do not restart it. Text is released in groups every CHUNK_MS rather than every frame.
+ */
+export declare function useSmoothText(text: string, streaming: boolean): string;

package/dist/types/react/src/hooks/sse-transport.d.ts

@@ -0,0 +1,15 @@
+import type { SendRequest, Transport } from "./use-chat";
+export interface SseTransportOptions {
+    /** POST endpoint. Gets the request as JSON and answers with a `text/event-stream` of events. */
+    url: string;
+    /** Extra headers, e.g. auth. A function is called per request. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** POSTed `{ runId }` when the user stops a reply. Without it the stream is only closed. */
+    stopUrl?: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** The request body the backend receives: everything in `SendRequest` except the abort signal. */
+export type SseRequestBody = Omit<SendRequest, "signal">;
+/** A `Transport` for backends that stream `StreamEvent`s over server-sent events (see `formatEvent`). */
+export declare function sseTransport({ url, headers, stopUrl, fetch: fetchImpl }: SseTransportOptions): Transport;

package/dist/types/react/src/hooks/use-chat.d.ts

@@ -0,0 +1,68 @@
+import { type AttachmentPart, type Message, type StreamEvent, type ToolCallPart } from "../../../core/src/index.js";
+import { type AgentRegistry, type ToolSpec } from "./agent";
+export interface SendRequest {
+    conversationId?: string;
+    /**
+     * The user message just added (the reply's parent), or for a continuation the assistant message whose
+     * awaiting tool calls now have results or approvals. The backend carries on that same message.
+     */
+    message: Message;
+    /** The conversation up to and including `message`. */
+    history: Message[];
+    /** Set after client tools ran or the user answered an approval. */
+    continuation?: boolean;
+    /** Client tools the page offers right now (`useAgentTool`), for the backend to give the model. */
+    tools?: ToolSpec[];
+    /** Page state shared with `useAgentContext`. */
+    context?: Record<string, unknown>;
+    model?: string;
+    effort?: string;
+    signal: AbortSignal;
+}
+/** How the kit talks to a backend. The kit ships an SSE one; hosts with other backends write an adapter. */
+export interface Transport {
+    send(request: SendRequest): AsyncIterable<StreamEvent>;
+    /** Tells the server to stop the run. The stream is aborted locally either way. */
+    stop?(runId: string): Promise<void>;
+}
+export interface UseChatOptions {
+    transport: Transport;
+    conversationId?: string;
+    initialMessages?: Message[];
+    onTitle?: (title: string) => void;
+    /** Tools and page context. Defaults to the nearest `AgentProvider`. */
+    agent?: AgentRegistry | null;
+    /** Continuations allowed per user message, so a looping model stops. Default 12. */
+    maxSteps?: number;
+}
+export interface SendOptions {
+    model?: string;
+    /** Only sent if set; pass `resolveEffort(model, effort)` so models without effort get none. */
+    effort?: string;
+    /** Shown above the text in the user's message. */
+    attachments?: AttachmentPart[];
+}
+/** A tool call waiting for the user to allow or deny it. */
+export interface PendingApproval {
+    messageId: string;
+    part: ToolCallPart;
+}
+export interface UseChat {
+    messages: Message[];
+    /** True while a reply streams or client tools run. False while waiting on an approval. */
+    busy: boolean;
+    /** Tool calls waiting on the user. Sending a new message declines them. */
+    approvals: PendingApproval[];
+    respond(partId: string, granted: boolean): void;
+    send(text: string, options?: SendOptions): void;
+    stop(): void;
+    /** Drops the assistant reply and asks again from its user message. */
+    retry(assistantId: string, options?: SendOptions): void;
+}
+export declare function userMessage(text: string, parentId: string | null, attachments?: AttachmentPart[]): Message;
+/**
+ * A linear conversation driven by a Transport: sends, streams the reply through `applyEvent`, stops and
+ * retries. With an `AgentProvider` it also runs the agent loop: client tools run in the page, approvals
+ * wait for the user, then the reply continues; every finished tool call reaches its tool's `onResult`.
+ */
+export declare function useChat({ transport, conversationId, initialMessages, onTitle, agent, maxSteps }: UseChatOptions): UseChat;