@camelai/agent-runtime-react 0.0.0 → 0.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qaml-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
 # @camelai/agent-runtime-react
 
-Placeholder. The first real release is 0.10.0.
+React hooks and components for a streaming chat with an agent on the
+[camelAI agent runtime](https://agents.camelai.dev). Your server has one route
+(`createAgentHandler` from `@camelai/agent-runtime/server`); these talk to it.
+
+```sh
+npm install @camelai/agent-runtime @camelai/agent-runtime-react
+```
+
+## Prebuilt
+
+```tsx
+import { AgentChat } from "@camelai/agent-runtime-react/ui";
+import "@camelai/agent-runtime-react/styles.css";
+
+<AgentChat endpoint="/api/agent" suggestions={["Where is my order?"]} tools={{ get_weather: WeatherCard }} />
+```
+
+Messages stream in as markdown; tool calls show as cards or your components; the agent's
+questions and approvals are answered in place; files it hands over are previews or downloads; the
+composer stops a run. Props: `endpoint` or `chat`, `thread`, `tools`, `components` (Markdown,
+UserMessage, AssistantMessage, ToolFallback, InputCard, FilePreview, EmptyState), `labels`,
+`placeholder`, `suggestions`, `theme`, `allowImages`, `showReasoning`, `whileRunning`, `data`,
+`header`, `className`, `style`. Theme it with CSS variables (`--agent-accent`, `--agent-radius`, …),
+or import `shadcn.css` too to follow a shadcn/ui theme.
+
+## Hooks
+
+```tsx
+import { AgentProvider, useMessages, useSend, useAgentStatus, useInputs } from "@camelai/agent-runtime-react";
+
+<AgentProvider endpoint="/api/agent" thread={threadId}>
+  <MyChat />
+</AgentProvider>
+```
+
+| Hook | Returns |
+| --- | --- |
+| `useMessages()` | the messages, as typed parts (`text`, `reasoning`, `tool`, `file`) |
+| `useSend()` | `send(text, { data? })`: shows the message at once, keyed by the id it keeps |
+| `useAgentStatus()` | `{ status, isRunning, error, connected, stop, retry }` |
+| `useInputs()` | `{ inputs, answer(input, value), decline(input) }` |
+| `useLoadOlder()` | `{ hasOlder, loading, loadOlder }` |
+| `useToolRenderer(name, Component)` | draws that tool's calls with your component |
+| `useAgentSelector(select)` | any part of the snapshot, re-rendering only when it changes |
+| `useAgent()` / `useAgentChat(options)` | the chat itself (`@camelai/agent-runtime/chat`) |
+
+Each hook re-renders only when what it returns changes, and unchanged messages keep their objects,
+so a streamed token re-renders one message.
+
+See the [Frontend guide](../../docs/frontend.md) for the route, security, tools, questions,
+threads and theming.

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * React bindings for an agent chat: a provider that holds the chat with the user's agent, and hooks
+ * that read it. Every hook subscribes to only what it returns, so a streamed token re-renders the
+ * message it belongs to, not the page.
+ *
+ *   <AgentProvider endpoint="/api/agent">
+ *     <MyChat />
+ *   </AgentProvider>
+ *
+ *   function MyChat() {
+ *     const messages = useMessages();
+ *     const send = useSend();
+ *     const { status, stop } = useAgentStatus();
+ *     …
+ *   }
+ */
+import { type ComponentType, type ReactNode } from "react";
+import { type AgentChat, type AgentChatOptions, type ChatError, type ChatInput, type ChatMessage, type ChatSnapshot, type ChatStatus, type InputAnswer, type InputValue, type SendOptions, type ToolPart } from "@camelai/agent-runtime/chat";
+export type * from "@camelai/agent-runtime/chat";
+export { answerValue, createAgentChat, projectMessages } from "@camelai/agent-runtime/chat";
+/** What a tool renderer gets: the call, and the means to answer what it waits on. */
+export interface ToolRenderProps {
+    part: ToolPart;
+    name: string;
+    args: Record<string, unknown>;
+    state: ToolPart["state"];
+    result: ToolPart["result"];
+    progress: ToolPart["progress"];
+    input: ChatInput | undefined;
+    /** Answer the call's input (approve with true, choose a label, fill a form). */
+    answer(value: InputValue | InputAnswer): Promise<void>;
+}
+export type ToolRenderer = ComponentType<ToolRenderProps>;
+export type ToolRenderers = Record<string, ToolRenderer>;
+export type UseAgentChatOptions = Omit<AgentChatOptions, "autoConnect">;
+/**
+ * A chat with the user's agent, connected while the component is mounted. A new `endpoint` or
+ * `thread` is a new chat; the other options are read when used, so they may change freely.
+ */
+export declare function useAgentChat(options: UseAgentChatOptions): AgentChat;
+export interface AgentProviderProps extends Partial<UseAgentChatOptions> {
+    /** A chat you made yourself (`useAgentChat` or `createAgentChat`), instead of `endpoint`. */
+    chat?: AgentChat;
+    /** Renderers for tool calls, by tool name (see `useToolRenderer`). */
+    tools?: ToolRenderers;
+    children?: ReactNode;
+}
+/** Holds the chat with the user's agent for the hooks and components below it. */
+export declare function AgentProvider({ chat, tools, children, ...options }: AgentProviderProps): import("react").JSX.Element;
+/** The chat (its actions and snapshot) from the nearest AgentProvider, or the one given. */
+export declare function useAgent(chat?: AgentChat): AgentChat;
+/**
+ * Part of the snapshot, re-rendering only when it changes (compared with `Object.is`, or `equal`).
+ * The snapshot's messages and parts keep their identity while unchanged, so selecting them is cheap.
+ */
+export declare function useAgentSelector<T>(select: (snapshot: ChatSnapshot) => T, options?: {
+    chat?: AgentChat;
+    equal?: (a: T, b: T) => boolean;
+}): T;
+/** The whole snapshot: status, messages, inputs, error. */
+export declare function useAgentSnapshot(chat?: AgentChat): ChatSnapshot;
+/** The chat's messages, oldest first. */
+export declare function useMessages(chat?: AgentChat): ChatMessage[];
+/** One message by id (re-renders only when that message changes). */
+export declare function useMessage(id: string, chat?: AgentChat): ChatMessage | undefined;
+/** Send a message: `send(text, { data })`. It shows at once and resolves once the handler took it. */
+export declare function useSend(chat?: AgentChat): (text: string, options?: SendOptions) => Promise<{
+    id: string;
+}>;
+export interface AgentStatus {
+    status: ChatStatus;
+    /** A turn runs or a message is on its way: show a stop button. */
+    isRunning: boolean;
+    error: ChatError | null;
+    connected: boolean;
+    stop(): Promise<void>;
+    retry(messageId: string): Promise<void>;
+}
+/** What the agent is doing, the latest error, and `stop`. */
+export declare function useAgentStatus(chat?: AgentChat): AgentStatus;
+/** What the agent waits on from the user, and the means to answer it. */
+export declare function useInputs(chat?: AgentChat): {
+    inputs: ChatInput[];
+    answer: AgentChat["answer"];
+    decline: AgentChat["decline"];
+};
+/** Older history: whether there is more, and `loadOlder()` (with `loading` while it runs). */
+export declare function useLoadOlder(chat?: AgentChat): {
+    hasOlder: boolean;
+    loading: boolean;
+    loadOlder(): Promise<boolean>;
+};
+/**
+ * Render calls of the tool `name` with `renderer` wherever this chat is shown (generative UI), while
+ * the calling component is mounted. A component's own `tools` prop comes first, then the latest
+ * registration, then the provider's `tools`.
+ */
+export declare function useToolRenderer(name: string, renderer: ToolRenderer): void;
+/** The renderer for tool `name`: `extra`'s, else one registered with `useToolRenderer`, else the provider's. */
+export declare function useToolRendererFor(name: string, extra?: ToolRenderers): ToolRenderer | undefined;

package/dist/index.js

@@ -0,0 +1,187 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React bindings for an agent chat: a provider that holds the chat with the user's agent, and hooks
+ * that read it. Every hook subscribes to only what it returns, so a streamed token re-renders the
+ * message it belongs to, not the page.
+ *
+ *   <AgentProvider endpoint="/api/agent">
+ *     <MyChat />
+ *   </AgentProvider>
+ *
+ *   function MyChat() {
+ *     const messages = useMessages();
+ *     const send = useSend();
+ *     const { status, stop } = useAgentStatus();
+ *     …
+ *   }
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { createAgentChat, } from "@camelai/agent-runtime/chat";
+export { answerValue, createAgentChat, projectMessages } from "@camelai/agent-runtime/chat";
+function createRegistry() {
+    const renderers = new Map();
+    const listeners = new Set();
+    let version = 0;
+    const changed = () => { version++; for (const listener of [...listeners])
+        listener(); };
+    return {
+        get: name => renderers.get(name)?.at(-1),
+        set(name, renderer) {
+            renderers.set(name, [...renderers.get(name) ?? [], renderer]);
+            changed();
+            return () => { renderers.set(name, (renderers.get(name) ?? []).filter(item => item !== renderer)); changed(); };
+        },
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        version: () => version,
+    };
+}
+const AgentContext = createContext(null);
+/**
+ * A chat with the user's agent, connected while the component is mounted. A new `endpoint` or
+ * `thread` is a new chat; the other options are read when used, so they may change freely.
+ */
+export function useAgentChat(options) {
+    const latest = useRef(options);
+    latest.current = options;
+    const key = `${options.endpoint}\u0000${options.thread ?? ""}`;
+    const make = () => createAgentChat({
+        ...options, autoConnect: false,
+        headers: () => { const headers = latest.current.headers; return typeof headers === "function" ? headers() : headers ?? {}; },
+        onEvent: event => latest.current.onEvent?.(event),
+        onError: error => latest.current.onError?.(error),
+    });
+    const [held, setHeld] = useState(() => ({ key, chat: make() }));
+    let chat = held.chat;
+    if (held.key !== key) {
+        chat = make();
+        setHeld({ key, chat });
+    }
+    useEffect(() => {
+        chat.connect();
+        return () => chat.disconnect();
+    }, [chat]);
+    return chat;
+}
+/** Holds the chat with the user's agent for the hooks and components below it. */
+export function AgentProvider({ chat, tools, children, ...options }) {
+    if (chat)
+        return _jsx(Provide, { chat: chat, tools: tools, children: children });
+    if (!options.endpoint)
+        throw new Error("AgentProvider needs an endpoint (your agent handler's URL, e.g. \"/api/agent\") or a chat");
+    return _jsx(ProvideOwn, { ...options, tools: tools, children: children });
+}
+function ProvideOwn({ tools, children, ...options }) {
+    return _jsx(Provide, { chat: useAgentChat(options), tools: tools, children: children });
+}
+function Provide({ chat, tools, children }) {
+    const parent = useContext(AgentContext);
+    const [registry] = useState(createRegistry);
+    const value = useMemo(() => ({ chat, registry, tools: { ...parent?.tools, ...tools } }), [chat, registry, parent?.tools, tools]);
+    return _jsx(AgentContext.Provider, { value: value, children: children });
+}
+function useContextValue(hook) {
+    const value = useContext(AgentContext);
+    if (!value)
+        throw new Error(`${hook} must be used inside <AgentProvider>`);
+    return value;
+}
+/** The chat (its actions and snapshot) from the nearest AgentProvider, or the one given. */
+export function useAgent(chat) {
+    const context = useContext(AgentContext);
+    const found = chat ?? context?.chat;
+    if (!found)
+        throw new Error("useAgent must be used inside <AgentProvider> (or given a chat)");
+    return found;
+}
+/**
+ * Part of the snapshot, re-rendering only when it changes (compared with `Object.is`, or `equal`).
+ * The snapshot's messages and parts keep their identity while unchanged, so selecting them is cheap.
+ */
+export function useAgentSelector(select, options = {}) {
+    const chat = useAgent(options.chat);
+    const cache = useRef(null);
+    const read = () => {
+        const snapshot = chat.getSnapshot();
+        const cached = cache.current;
+        if (cached && cached.snapshot === snapshot && cached.select === select)
+            return cached.value;
+        const value = select(snapshot);
+        const kept = cached && (options.equal ?? Object.is)(cached.value, value) ? cached.value : value;
+        cache.current = { snapshot, select, value: kept };
+        return kept;
+    };
+    return useSyncExternalStore(chat.subscribe, read, read);
+}
+/** The whole snapshot: status, messages, inputs, error. */
+export function useAgentSnapshot(chat) {
+    const found = useAgent(chat);
+    return useSyncExternalStore(found.subscribe, found.getSnapshot, found.getSnapshot);
+}
+/** The chat's messages, oldest first. */
+export function useMessages(chat) {
+    return useAgentSelector(snapshot => snapshot.messages, { chat });
+}
+/** One message by id (re-renders only when that message changes). */
+export function useMessage(id, chat) {
+    return useAgentSelector(snapshot => snapshot.messages.find(message => message.id === id), { chat });
+}
+/** Send a message: `send(text, { data })`. It shows at once and resolves once the handler took it. */
+export function useSend(chat) {
+    const found = useAgent(chat);
+    return useCallback((text, options) => options ? found.send(text, options) : found.send(text), [found]);
+}
+/** What the agent is doing, the latest error, and `stop`. */
+export function useAgentStatus(chat) {
+    const found = useAgent(chat);
+    const status = useAgentSelector(snapshot => snapshot.status, { chat: found });
+    const error = useAgentSelector(snapshot => snapshot.error, { chat: found });
+    const connected = useAgentSelector(snapshot => snapshot.connected, { chat: found });
+    return useMemo(() => ({
+        status, error, connected, isRunning: status === "submitted" || status === "streaming",
+        stop: () => found.stop(), retry: (id) => found.retry(id),
+    }), [status, error, connected, found]);
+}
+/** What the agent waits on from the user, and the means to answer it. */
+export function useInputs(chat) {
+    const found = useAgent(chat);
+    const inputs = useAgentSelector(snapshot => snapshot.inputs, { chat: found });
+    return useMemo(() => ({ inputs, answer: found.answer, decline: found.decline }), [inputs, found]);
+}
+/** Older history: whether there is more, and `loadOlder()` (with `loading` while it runs). */
+export function useLoadOlder(chat) {
+    const found = useAgent(chat);
+    const hasOlder = useAgentSelector(snapshot => snapshot.hasOlder, { chat: found });
+    const [loading, setLoading] = useState(false);
+    const busy = useRef(false);
+    const loadOlder = useCallback(async () => {
+        if (busy.current)
+            return false;
+        busy.current = true;
+        setLoading(true);
+        try {
+            return await found.loadOlder();
+        }
+        finally {
+            busy.current = false;
+            setLoading(false);
+        }
+    }, [found]);
+    return { hasOlder, loading, loadOlder };
+}
+/**
+ * Render calls of the tool `name` with `renderer` wherever this chat is shown (generative UI), while
+ * the calling component is mounted. A component's own `tools` prop comes first, then the latest
+ * registration, then the provider's `tools`.
+ */
+export function useToolRenderer(name, renderer) {
+    const { registry } = useContextValue("useToolRenderer");
+    useEffect(() => registry.set(name, renderer), [registry, name, renderer]);
+}
+/** The renderer for tool `name`: `extra`'s, else one registered with `useToolRenderer`, else the provider's. */
+export function useToolRendererFor(name, extra) {
+    const context = useContext(AgentContext);
+    const subscribe = useCallback((listener) => context?.registry.subscribe(listener) ?? (() => { }), [context]);
+    useSyncExternalStore(subscribe, () => context?.registry.version() ?? 0, () => 0);
+    return extra?.[name] ?? context?.registry.get(name) ?? context?.tools[name];
+}

package/dist/shadcn.css

@@ -0,0 +1,39 @@
+/*
+ * @camelai/agent-runtime-react/shadcn.css: <AgentChat> in your shadcn/ui theme. Import it after
+ * styles.css; it maps the chat's variables onto shadcn's tokens (--background, --foreground, …), so
+ * the chat follows your theme and its .dark class.
+ */
+:where(.agent-chat),
+:where(.dark, [data-theme="dark"]) :where(.agent-chat:not([data-theme="light"])),
+:where(.agent-chat[data-theme="dark"]) {
+  --agent-bg: var(--background);
+  --agent-fg: var(--foreground);
+  --agent-muted: var(--muted);
+  --agent-muted-fg: var(--muted-foreground);
+  --agent-border: var(--border);
+  --agent-accent: var(--primary);
+  --agent-accent-fg: var(--primary-foreground);
+  --agent-user-bg: var(--secondary);
+  --agent-user-fg: var(--secondary-foreground);
+  --agent-code-bg: var(--muted);
+  --agent-danger: var(--destructive);
+  --agent-focus: var(--ring);
+  --agent-radius: var(--radius);
+  --agent-font: inherit;
+}
+@media (prefers-color-scheme: dark) {
+  :where(.agent-chat:not([data-theme="light"], .light .agent-chat, [data-theme="light"] .agent-chat)) {
+    --agent-bg: var(--background);
+    --agent-fg: var(--foreground);
+    --agent-muted: var(--muted);
+    --agent-muted-fg: var(--muted-foreground);
+    --agent-border: var(--border);
+    --agent-accent: var(--primary);
+    --agent-accent-fg: var(--primary-foreground);
+    --agent-user-bg: var(--secondary);
+    --agent-user-fg: var(--secondary-foreground);
+    --agent-code-bg: var(--muted);
+    --agent-danger: var(--destructive);
+    --agent-focus: var(--ring);
+  }
+}

package/dist/styles.css

@@ -0,0 +1,209 @@
+/*
+ * @camelai/agent-runtime-react/styles.css: the default look of <AgentChat>.
+ * Theme it with the variables below (on .agent-chat or any ancestor); every rule has zero specificity
+ * beyond its class (:where), so your own CSS wins without !important.
+ * Dark mode follows the system unless theme="light"/"dark" is set, or an ancestor has .dark/.light
+ * (or data-theme="dark"/"light").
+ */
+:where(.agent-chat) {
+  --agent-bg: #ffffff;
+  --agent-fg: #0a0a0a;
+  --agent-muted: #f4f4f5;
+  --agent-muted-fg: #52525b;
+  --agent-border: #e4e4e7;
+  --agent-accent: #18181b;
+  --agent-accent-fg: #fafafa;
+  --agent-user-bg: #f4f4f5;
+  --agent-user-fg: var(--agent-fg);
+  --agent-code-bg: #f4f4f5;
+  --agent-danger: #b91c1c;
+  --agent-success: #15803d;
+  --agent-focus: #2563eb;
+  --agent-radius: 12px;
+  --agent-font: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --agent-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+  --agent-font-size: 15px;
+  --agent-line-height: 1.6;
+  --agent-max-width: 760px;
+  --agent-composer-max-height: 200px;
+}
+:where(.dark, [data-theme="dark"]) :where(.agent-chat:not([data-theme="light"])),
+:where(.agent-chat[data-theme="dark"]) {
+  --agent-bg: #0a0a0a;
+  --agent-fg: #fafafa;
+  --agent-muted: #18181b;
+  --agent-muted-fg: #a1a1aa;
+  --agent-border: #27272a;
+  --agent-accent: #fafafa;
+  --agent-accent-fg: #0a0a0a;
+  --agent-user-bg: #27272a;
+  --agent-code-bg: #18181b;
+  --agent-danger: #f87171;
+  --agent-success: #4ade80;
+  --agent-focus: #60a5fa;
+}
+@media (prefers-color-scheme: dark) {
+  :where(.agent-chat:not([data-theme="light"], .light .agent-chat, [data-theme="light"] .agent-chat)) {
+    --agent-bg: #0a0a0a;
+    --agent-fg: #fafafa;
+    --agent-muted: #18181b;
+    --agent-muted-fg: #a1a1aa;
+    --agent-border: #27272a;
+    --agent-accent: #fafafa;
+    --agent-accent-fg: #0a0a0a;
+    --agent-user-bg: #27272a;
+    --agent-code-bg: #18181b;
+    --agent-danger: #f87171;
+    --agent-success: #4ade80;
+    --agent-focus: #60a5fa;
+  }
+}
+
+:where(.agent-chat) {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  background: var(--agent-bg);
+  color: var(--agent-fg);
+  font-family: var(--agent-font);
+  font-size: var(--agent-font-size);
+  line-height: var(--agent-line-height);
+  color-scheme: light dark;
+  box-sizing: border-box;
+}
+:where(.agent-chat) *, :where(.agent-chat) *::before, :where(.agent-chat) *::after { box-sizing: inherit; }
+:where(.agent-chat :focus-visible) { outline: 2px solid var(--agent-focus); outline-offset: 2px; }
+:where(.agent-chat button) { font: inherit; color: inherit; cursor: pointer; }
+:where(.agent-chat button:disabled) { cursor: not-allowed; opacity: 0.5; }
+
+:where(.agent-chat__viewport) { position: relative; flex: 1 1 auto; min-height: 0; display: flex; flex-direction: column; }
+:where(.agent-chat__messages) { flex: 1 1 auto; overflow-y: auto; overscroll-behavior: contain; scrollbar-gutter: stable; }
+:where(.agent-chat__messages):focus-visible { outline-offset: -2px; }
+:where(.agent-chat__content) { max-width: var(--agent-max-width); margin: 0 auto; padding: 16px; display: flex; flex-direction: column; gap: 16px; }
+
+:where(.agent-chat__message) { display: flex; flex-direction: column; gap: 8px; min-width: 0; }
+:where(.agent-chat__message--user) { align-items: flex-end; }
+:where(.agent-chat__bubble) { max-width: 85%; background: var(--agent-user-bg); color: var(--agent-user-fg); padding: 8px 14px; border-radius: var(--agent-radius); overflow-wrap: anywhere; }
+:where(.agent-chat__message--user[data-status="sending"]) :where(.agent-chat__bubble) { opacity: 0.7; }
+:where(.agent-chat__user-text) { margin: 0; white-space: pre-wrap; }
+:where(.agent-chat__user-image) { max-width: 240px; border-radius: calc(var(--agent-radius) - 4px); display: block; }
+:where(.agent-chat__author) { font-size: 0.8em; color: var(--agent-muted-fg); }
+:where(.agent-chat__note) { font-size: 0.85em; color: var(--agent-muted-fg); }
+:where(.agent-chat__note--error) { color: var(--agent-danger); }
+:where(.agent-chat__link-button) { background: none; border: 0; padding: 0; text-decoration: underline; }
+
+/* Markdown */
+:where(.agent-chat__markdown) { overflow-wrap: anywhere; }
+:where(.agent-chat__markdown) > :first-child { margin-top: 0; }
+:where(.agent-chat__markdown) > :last-child { margin-bottom: 0; }
+:where(.agent-chat__markdown) :where(p, ul, ol, blockquote, .agent-chat__code, .agent-chat__table) { margin: 0 0 0.75em; }
+:where(.agent-chat__markdown) :where(h1, h2, h3, h4, h5, h6) { margin: 1em 0 0.5em; line-height: 1.3; }
+:where(.agent-chat__markdown) h1 { font-size: 1.4em; }
+:where(.agent-chat__markdown) h2 { font-size: 1.25em; }
+:where(.agent-chat__markdown) h3 { font-size: 1.1em; }
+:where(.agent-chat__markdown) :where(ul, ol) { padding-left: 1.5em; }
+:where(.agent-chat__markdown) li + li { margin-top: 0.25em; }
+:where(.agent-chat__markdown) blockquote { border-left: 3px solid var(--agent-border); padding-left: 12px; color: var(--agent-muted-fg); }
+:where(.agent-chat__markdown) a { color: inherit; text-decoration: underline; text-underline-offset: 2px; }
+:where(.agent-chat__markdown) img { max-width: 100%; border-radius: calc(var(--agent-radius) - 4px); }
+:where(.agent-chat__markdown) hr { border: 0; border-top: 1px solid var(--agent-border); margin: 1em 0; }
+:where(.agent-chat__markdown) :not(pre) > code { font-family: var(--agent-mono); font-size: 0.9em; background: var(--agent-code-bg); padding: 0.1em 0.35em; border-radius: 4px; }
+:where(.agent-chat__code) { border: 1px solid var(--agent-border); border-radius: calc(var(--agent-radius) - 4px); overflow: hidden; background: var(--agent-code-bg); }
+:where(.agent-chat__code-bar) { display: flex; justify-content: space-between; align-items: center; padding: 4px 10px; font-size: 0.8em; color: var(--agent-muted-fg); border-bottom: 1px solid var(--agent-border); }
+:where(.agent-chat__code-copy) { background: none; border: 0; padding: 2px 6px; border-radius: 4px; color: var(--agent-muted-fg); }
+:where(.agent-chat__code-copy):hover { color: var(--agent-fg); }
+:where(.agent-chat pre) { margin: 0; padding: 10px 12px; overflow-x: auto; font-family: var(--agent-mono); font-size: 0.85em; line-height: 1.5; }
+:where(.agent-chat__table) { overflow-x: auto; }
+:where(.agent-chat__table) table { border-collapse: collapse; font-size: 0.95em; }
+:where(.agent-chat__table) :where(th, td) { border: 1px solid var(--agent-border); padding: 4px 10px; text-align: left; }
+:where(.agent-chat__table) th { background: var(--agent-muted); }
+
+/* Streaming caret after the last block of the message being written */
+:where(.agent-chat__message[data-streaming]) > :where(.agent-chat__markdown):last-child > :last-child::after {
+  content: ""; display: inline-block; width: 0.5em; height: 1em; margin-left: 2px; vertical-align: -0.15em;
+  background: currentColor; opacity: 0.6; animation: agent-chat-blink 1s steps(2) infinite;
+}
+@keyframes agent-chat-blink { 50% { opacity: 0; } }
+
+/* Reasoning, tools */
+:where(.agent-chat__reasoning, .agent-chat__tool) { border: 1px solid var(--agent-border); border-radius: calc(var(--agent-radius) - 4px); font-size: 0.9em; }
+:where(.agent-chat__reasoning, .agent-chat__tool) > summary { cursor: pointer; padding: 6px 10px; color: var(--agent-muted-fg); display: flex; align-items: center; gap: 8px; list-style: none; }
+:where(.agent-chat__reasoning, .agent-chat__tool) > summary::-webkit-details-marker { display: none; }
+:where(.agent-chat__reasoning, .agent-chat__tool) > summary::after { content: ""; margin-left: auto; width: 6px; height: 6px; border-right: 1.5px solid currentColor; border-bottom: 1.5px solid currentColor; transform: rotate(-45deg); transition: transform 0.15s; }
+:where(.agent-chat__reasoning, .agent-chat__tool)[open] > summary::after { transform: rotate(45deg); }
+:where(.agent-chat__reasoning-text) { padding: 0 10px 10px; white-space: pre-wrap; color: var(--agent-muted-fg); }
+:where(.agent-chat__tool-body) { padding: 0 10px 10px; display: flex; flex-direction: column; gap: 8px; }
+:where(.agent-chat__tool-body) pre { background: var(--agent-code-bg); border-radius: 6px; max-height: 320px; }
+:where(.agent-chat__tool-heading) { font-size: 0.8em; text-transform: uppercase; letter-spacing: 0.04em; color: var(--agent-muted-fg); margin-bottom: 4px; }
+:where(.agent-chat__tool-progress-text) { font-size: 0.9em; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+:where(.agent-chat__tool) progress { width: 100%; accent-color: var(--agent-accent); }
+:where(.agent-chat__tool-icon) { width: 12px; height: 12px; border-radius: 50%; flex: none; border: 2px solid var(--agent-muted-fg); border-top-color: transparent; animation: agent-chat-spin 0.8s linear infinite; }
+:where(.agent-chat__tool[data-state="done"]) :where(.agent-chat__tool-icon) { animation: none; border: 0; background: var(--agent-success); }
+:where(.agent-chat__tool[data-state="error"]) :where(.agent-chat__tool-icon) { animation: none; border: 0; background: var(--agent-danger); }
+:where(.agent-chat__tool[data-state="input_required"]) :where(.agent-chat__tool-icon) { animation: none; border-color: var(--agent-focus); }
+@keyframes agent-chat-spin { to { transform: rotate(360deg); } }
+
+/* Inputs: approvals, questions, forms */
+:where(.agent-chat__input) { border: 1px solid var(--agent-border); border-radius: calc(var(--agent-radius) - 2px); padding: 12px; display: flex; flex-direction: column; gap: 10px; background: var(--agent-bg); }
+:where(.agent-chat__input) pre { background: var(--agent-code-bg); border-radius: 6px; max-height: 240px; }
+:where(.agent-chat__input-message) { margin: 0; font-weight: 500; }
+:where(.agent-chat__input-error) { margin: 0; color: var(--agent-danger); font-size: 0.9em; }
+:where(.agent-chat__input) fieldset { border: 0; padding: 0; margin: 0 0 10px; display: flex; flex-direction: column; gap: 6px; min-width: 0; }
+:where(.agent-chat__input) legend { font-weight: 500; padding: 0; margin-bottom: 6px; }
+:where(.agent-chat__question-header) { display: inline-block; font-size: 0.75em; font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; color: var(--agent-muted-fg); margin-right: 6px; }
+:where(.agent-chat__option) { display: flex; gap: 8px; align-items: flex-start; padding: 6px 8px; border: 1px solid var(--agent-border); border-radius: 8px; cursor: pointer; }
+:where(.agent-chat__option):has(input:checked) { border-color: var(--agent-accent); }
+:where(.agent-chat__option) input { margin-top: 0.3em; accent-color: var(--agent-accent); }
+:where(.agent-chat__option-description) { display: block; font-size: 0.85em; color: var(--agent-muted-fg); }
+:where(.agent-chat__field) { display: flex; flex-direction: column; gap: 4px; }
+:where(.agent-chat__field-description) { font-size: 0.85em; color: var(--agent-muted-fg); }
+:where(.agent-chat__text-input, .agent-chat__input select) { font: inherit; color: inherit; background: var(--agent-bg); border: 1px solid var(--agent-border); border-radius: 8px; padding: 6px 10px; }
+:where(.agent-chat__input-actions) { display: flex; gap: 8px; flex-wrap: wrap; }
+:where(.agent-chat__button) { display: inline-flex; align-items: center; justify-content: center; padding: 6px 14px; border-radius: 8px; border: 1px solid var(--agent-border); background: var(--agent-bg); color: var(--agent-fg); text-decoration: none; font-size: 0.95em; }
+:where(.agent-chat__button):hover:not(:disabled) { background: var(--agent-muted); }
+:where(.agent-chat__button--primary) { background: var(--agent-accent); color: var(--agent-accent-fg); border-color: var(--agent-accent); }
+:where(.agent-chat__button--primary):hover:not(:disabled) { background: var(--agent-accent); opacity: 0.9; }
+:where(.agent-chat__loose-inputs) { max-width: var(--agent-max-width); width: 100%; margin: 0 auto; padding: 0 16px; }
+
+/* Files */
+:where(.agent-chat__file) { margin: 0; display: flex; flex-direction: column; gap: 6px; max-width: 420px; }
+:where(.agent-chat__file) img { max-width: 100%; max-height: 360px; border-radius: calc(var(--agent-radius) - 4px); border: 1px solid var(--agent-border); display: block; }
+:where(.agent-chat__file-link) { display: flex; flex-direction: column; padding: 8px 12px; border: 1px solid var(--agent-border); border-radius: calc(var(--agent-radius) - 4px); color: inherit; text-decoration: none; }
+:where(.agent-chat__file[data-kind="image"]) :where(.agent-chat__file-link) { border: 0; padding: 0; flex-direction: row; gap: 8px; font-size: 0.85em; }
+:where(.agent-chat__file-link):hover { background: var(--agent-muted); }
+:where(.agent-chat__file-link[aria-disabled]) { pointer-events: none; opacity: 0.6; }
+:where(.agent-chat__file-name) { font-weight: 500; overflow-wrap: anywhere; }
+:where(.agent-chat__file-meta, .agent-chat__file-caption) { font-size: 0.85em; color: var(--agent-muted-fg); }
+
+/* Waiting, empty, older, jump, errors */
+:where(.agent-chat__thinking) { display: flex; align-items: center; gap: 4px; color: var(--agent-muted-fg); }
+:where(.agent-chat__thinking) > span:not(.agent-chat__thinking-text) { width: 6px; height: 6px; border-radius: 50%; background: currentColor; animation: agent-chat-pulse 1.2s ease-in-out infinite; }
+:where(.agent-chat__thinking) > span:nth-child(2) { animation-delay: 0.15s; }
+:where(.agent-chat__thinking) > span:nth-child(3) { animation-delay: 0.3s; }
+:where(.agent-chat__thinking-text) { margin-left: 6px; font-size: 0.9em; }
+@keyframes agent-chat-pulse { 0%, 100% { opacity: 0.25; } 50% { opacity: 1; } }
+:where(.agent-chat__empty) { margin: auto; padding: 48px 0 24px; text-align: center; display: flex; flex-direction: column; align-items: center; gap: 16px; }
+:where(.agent-chat__empty-title) { margin: 0; font-size: 1.25em; font-weight: 600; }
+:where(.agent-chat__suggestions) { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; gap: 8px; justify-content: center; }
+:where(.agent-chat__suggestion) { border: 1px solid var(--agent-border); background: var(--agent-bg); border-radius: 999px; padding: 6px 14px; font-size: 0.9em; }
+:where(.agent-chat__suggestion):hover { background: var(--agent-muted); }
+:where(.agent-chat__older) { align-self: center; border: 1px solid var(--agent-border); background: var(--agent-bg); border-radius: 999px; padding: 4px 12px; font-size: 0.85em; color: var(--agent-muted-fg); }
+:where(.agent-chat__jump) { position: absolute; bottom: 12px; left: 50%; transform: translateX(-50%); border: 1px solid var(--agent-border); background: var(--agent-bg); border-radius: 999px; padding: 4px 12px; font-size: 0.85em; box-shadow: 0 2px 8px rgb(0 0 0 / 0.12); }
+:where(.agent-chat__error) { max-width: var(--agent-max-width); width: calc(100% - 32px); margin: 0 auto 8px; padding: 8px 12px; border-radius: 8px; border: 1px solid var(--agent-danger); color: var(--agent-danger); font-size: 0.9em; }
+:where(.agent-chat__error--soft) { border-color: var(--agent-border); color: var(--agent-muted-fg); }
+
+/* Composer */
+:where(.agent-chat__composer) { max-width: var(--agent-max-width); width: calc(100% - 32px); margin: 0 auto 16px; display: flex; align-items: flex-end; gap: 8px; border: 1px solid var(--agent-border); border-radius: calc(var(--agent-radius) + 4px); padding: 8px 8px 8px 14px; background: var(--agent-bg); }
+:where(.agent-chat__composer):focus-within { border-color: var(--agent-muted-fg); }
+:where(.agent-chat__composer) textarea { flex: 1; resize: none; border: 0; outline: none; background: transparent; color: inherit; font: inherit; line-height: 1.5; padding: 6px 0; max-height: var(--agent-composer-max-height); field-sizing: content; min-height: 1.5em; }
+:where(.agent-chat__composer) textarea:focus-visible { outline: none; }
+:where(.agent-chat__send) { flex: none; width: 34px; height: 34px; border-radius: 50%; border: 0; background: var(--agent-accent); color: var(--agent-accent-fg); display: grid; place-items: center; }
+:where(.agent-chat__send-icon) { width: 0; height: 0; border-left: 6px solid transparent; border-right: 6px solid transparent; border-bottom: 9px solid currentColor; }
+:where(.agent-chat__send--stop) :where(.agent-chat__send-icon) { width: 11px; height: 11px; border: 0; border-radius: 2px; background: currentColor; }
+
+:where(.agent-chat__sr-only) { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
+
+@media (prefers-reduced-motion: reduce) {
+  :where(.agent-chat) *, :where(.agent-chat) *::before, :where(.agent-chat) *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; scroll-behavior: auto !important; }
+}

package/dist/ui/composer.d.ts

@@ -0,0 +1,20 @@
+export interface ComposerProps {
+    placeholder?: string;
+    autoFocus?: boolean;
+    /** What a message sent while the agent works does (the chat's own setting by default). */
+    whileRunning?: "queue" | "steer";
+    /** JSON sent with each message, for your handler's `onSend`. */
+    data?: unknown | (() => unknown);
+    className?: string;
+    /** Called after a message is sent. */
+    onSend?: (text: string) => void;
+}
+export interface ComposerHandle {
+    focus(): void;
+    setText(text: string): void;
+}
+/**
+ * The message box: Enter sends, Shift+Enter makes a new line, Escape stops the agent. While the agent
+ * works, an empty box offers Stop; typing turns it back into Send.
+ */
+export declare const Composer: import("react").ForwardRefExoticComponent<ComposerProps & import("react").RefAttributes<ComposerHandle>>;