@calliopelabs/ui 0.13.0 → 0.16.0

package/README.md

@@ -2,7 +2,7 @@
 
 The shared operator UI of Calliope AI: the app shell, navigation, page frame, data table and list patterns, status colours, design tokens and appearance settings that Astrolift AI and Zentinelle AI both run on. Extracted from the Astrolift AI frontend and generalized with a per-product config, so each console keeps its own name, accent, sidebar colour and navigation while sharing everything else.
 
-The shared base of the Calliope AI ui series. Product packages (`@calliopelabs/ui-astrolift`, `ui-zentinelle`, `ui-workbench`, later `ui-chat`) depend on it and carry only what is specific to their product. `0.2.0` was published as `@calliopelabs/ui-astrolift` with the same exports; it is deprecated in favour of this package.
+The shared base of the Calliope AI ui series. Product packages (`@calliopelabs/ui-astrolift`, `ui-zentinelle`, `ui-workbench`) depend on it and carry only what is specific to their product. `0.2.0` was published as `@calliopelabs/ui-astrolift` with the same exports; it is deprecated in favour of this package.
 
 It is built Storybook first: every component and every screen pattern is built and reviewed in the catalog before an app uses it. The catalog is published at **https://calliope-ux.astro.conflict.cloud**.
 
@@ -16,7 +16,7 @@ It is built Storybook first: every component and every screen pattern is built a
 npm i @calliopelabs/ui
 ```
 
-Peer dependencies: `react` and `react-dom` 19, and `tailwindcss` 4 for styling.
+Peer dependencies: `react` and `react-dom` 19, and `tailwindcss` 4 for styling. The opt-in agent entries add `@ag-ui/client` and `@copilotkit/react-core` (see [Agent](#agent)).
 
 ## Styles
 
@@ -395,6 +395,180 @@ The canvas pans, zooms and fits without going below `READABLE_ZOOM`; loop bodies
 
 `@xyflow/react` comes with the package; its structural CSS is in the preset.
 
+## Chat
+
+Engine-agnostic building blocks for agent chat, over the [AG-UI](https://docs.ag-ui.com) event shape (`@ag-ui/core` 1.0). An engine that speaks AG-UI drives them directly; any other gets an adapter that turns its stream into AG-UI events. Products keep their own screens and brands: there is no shipped chat page, only the pieces. Host-driven like everything else here: the package never connects, authenticates, runs a tool or resumes a run.
+
+- **The model.** `reduceChat(view, event)` folds one AG-UI event into a `ChatView`: messages with streaming text, tool calls with their arguments, results, status and approvals, the timeline that interleaves them, the run's steps and status (`idle`, `running`, `finished`, `interrupted`, `cancelled`, `error`), the shared state (`STATE_SNAPSHOT` plus `STATE_DELTA` as JSON Patch, `applyJsonPatch`), and `CUSTOM` and `RAW` events in order. `MESSAGES_SNAPSHOT` replaces the conversation, so a watcher can join part way. It is pure and immutable, never throws on an event it does not expect, and counts a delta that fails in `rejectedDeltas`. `foldChat(events, view?)` folds a list; `createChatView()` starts one. Activity, reasoning and sub-agent events leave the view as it is.
+- **The hook.** `useAgUiRun({ initialView?, onError? })` holds the view and reads one run at a time from the source the host hands `run(source)`: an `AsyncIterable` of events or a subscribe function `(emit, done) => unsubscribe`. `stop()` lets go and closes the view as cancelled (telling the agent to stop is the host's request); `dispatch(userMessageEvents(id, text))` shows the person's message before the run starts; a stream that fails lands in the view as a run error.
+- **Human in the loop.** A `RUN_FINISHED` interrupt outcome whose interrupt names a `toolCallId` puts an `approval` on that call. `ToolCallCard` then offers approve and deny through `ConfirmDialog`, a denial always with a reason, and hands the decision to `onApprove` or `onDeny`; the host resumes the run (AG-UI `resume`) and the next `RUN_STARTED` clears the approval.
+- **The components.** `MessageList` (the timeline, tool calls inline, follows the stream until the person scrolls up, a failed run's error with retry), `MessageBubble` (user, assistant, system, developer and tool), `Composer` (Enter sends, Shift+Enter breaks the line, stop while running, `attachments` and `actions` slots), `ToolCallCard` (arguments, result or error, `renderResult` for a table or chart), `AgentProgress` (status and steps on `RunTimeline`) and `ModelPicker` (the host's options).
+- **Markdown is the host's.** Text renders as plain text unless the host passes `renderContent` (its markdown component, given the text so far). Plain text is never parsed as HTML.
+
+```tsx
+const chat = useAgUiRun();
+
+<MessageList
+  view={chat.view}
+  renderContent={(text) => <Markdown>{text}</Markdown>}
+  onApprove={(call) => chat.run(agent.resume(call.approval!.interruptId, "resolved"))}
+  onDeny={(call, reason) => chat.run(agent.resume(call.approval!.interruptId, "cancelled", reason))}
+/>
+<Composer
+  running={chat.running}
+  onStop={() => { agent.abort(); chat.stop(); }}
+  onSubmit={(text) => {
+    chat.dispatch(userMessageEvents(crypto.randomUUID(), text));
+    void chat.run(agent.stream({ threadId, text }));
+  }}
+  actions={<ModelPicker options={models} value={model} onValueChange={setModel} />}
+/>
+<AgentProgress view={chat.view} />
+```
+
+`agent` above is the host's own client. The catalog's `Chat/ChatPanel` composes the pieces the same way, driven by a recorded run. Their copy is in the `chat` message group.
+
+## Agent
+
+`CalliopeAgent` is the one embedded agent for every Calliope AI product: a floating bubble, the shell's right rail, inline in a page, or a page of its own. It speaks [AG-UI](https://docs.ag-ui.com) to any agent, directly or through a [CopilotKit](https://docs.copilotkit.ai) runtime, and draws every pixel with the chat kit above, on the product's tokens, mark and runtime brand. CopilotKit wires the runtime and runs the agent; its UI and stylesheet are never loaded.
+
+It is an opt-in entry, so apps without an agent never load its dependencies:
+
+```sh
+npm i @ag-ui/client                      # @calliopelabs/ui/agent
+npm i @ag-ui/client @copilotkit/react-core   # @calliopelabs/ui/agent/copilotkit (1.79.1 or later, 1.x)
+```
+
+Both are optional peers. `npm run pack:check` fails if the main entry ever reaches them. Most of the entry's weight is `@ag-ui/client` itself (with its protobuf codec, about 150 KB gzipped; the agent's own code is about 24 KB minified), which a CopilotKit app already ships. To keep it off a page's first load, load the provider when the person first opens the assistant (`next/dynamic` with `ssr: false`) and keep it mounted after.
+
+### A Next.js app with a CopilotKit runtime
+
+```ts
+// app/api/copilotkit/route.ts: the runtime, on the server (agents, keys and auth stay here)
+import { HttpAgent } from "@ag-ui/client";
+import { CopilotRuntime, createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";
+
+const runtime = new CopilotRuntime({
+  agents: { default: new HttpAgent({ url: process.env.AGENT_URL! }) },
+});
+const handler = createCopilotRuntimeHandler({
+  runtime,
+  basePath: "/api/copilotkit",
+  mode: "single-route",
+});
+export const POST = (request: Request) => handler(request);
+```
+
+```tsx
+// app/assistant.tsx
+"use client";
+import { CalliopeAgent, useAgentReadable, useAgentTool } from "@calliopelabs/ui/agent";
+import { CopilotKitAgentProvider } from "@calliopelabs/ui/agent/copilotkit";
+import { z } from "zod";
+
+export function Assistant({ children, project }: { children: React.ReactNode; project: string }) {
+  return (
+    <CopilotKitAgentProvider
+      runtimeUrl="/api/copilotkit"
+      useSingleEndpoint
+      headers={{ "x-project": project }}
+    >
+      {children}
+      <CalliopeAgent mode="bubble" persistKey="app.assistant.open" />
+    </CopilotKitAgentProvider>
+  );
+}
+
+// Anywhere under it, while mounted:
+useAgentReadable("The open project", { project });
+useAgentTool({
+  name: "open_scene",
+  parameters: z.object({ id: z.string() }),
+  handler: ({ id }) => router.push(`/scenes/${id}`),
+});
+```
+
+Mount it from the root layout (a Server Component) as `<Assistant project={slug}>{children}</Assistant>`. Tools carry functions, so they are registered in client components, never passed from a server one.
+
+### A plain AG-UI endpoint
+
+```tsx
+"use client";
+import { CalliopeAgent, CalliopeAgentProvider } from "@calliopelabs/ui/agent";
+
+<CalliopeAgentProvider url="/api/agui" headers={{ "x-project": slug }} suggestions={startingPoints}>
+  <AppShell
+    {...shell}
+    rightRail={<CalliopeAgent mode="rail" open={open} onOpenChange={setOpen} />}
+    rightRailLabel="Assistant"
+    onToggleRightRail={() => setOpen((o) => !o)}
+  >
+    {children}
+  </AppShell>
+</CalliopeAgentProvider>;
+```
+
+`url` makes an `HttpAgent` (same origin, so the session cookie goes along); `agent` takes any `AbstractAgent` instead. `createFunctionAgent(run)` turns a function that yields AG-UI events (or an existing non-AG-UI endpoint, adapted) into one.
+
+### What it does
+
+- **One conversation, one store.** `useCalliopeAgent()` returns the chat kit's `ChatView` (messages, tool calls, steps, interrupts, shared state, custom events) and the actions: `send(text, { parts })`, `stop()` (aborts the run and any tool waiting), `regenerate()`, `approve(call)` and `deny(call, reason)`, `resolveInterrupt(id, response)`, `respond(toolCallId, result)`, `getState()` and `setState(state)`, `switchThread(id)` (with the provider's `loadThread`) and `newThread()`, plus `running`, `waiting`, `unread` and `suggestions`.
+- **Tools.** `useAgentTool(defineTool({ name, description, parameters, handler, render, followUp }))` offers a browser tool while the component is mounted. `parameters` is a Standard Schema (zod 4, valibot, arktype), which types and validates the arguments, or a JSON Schema. A tool with `render` and no `handler` is human-in-the-loop: the run waits until its card calls `respond(result)`, and the composer holds meanwhile.
+- **Readables and suggestions.** `useAgentReadable(description, value)` sends page context with every run; `useAgentSuggestions([{ title, message }])` offers starting points. Both also come as provider props for the whole app.
+- **Approvals.** A run that ends on an AG-UI interrupt pauses. A tool call it names gets approve and deny on its card (a denial always with a reason); any other interrupt gets `InterruptCard`, or the host's `renderers.interrupts[reason]`. The run resumes with AG-UI `resume` once every open interrupt has an answer; a new message cancels what is still open.
+- **Generative UI.** `renderers` on `CalliopeAgent` maps tool names (backend tools too), `CUSTOM` event names and interrupt reasons to host components, and draws the shared state above the conversation. `workflowRenderers` draws the run and review components: `calliope.run` on `RunTimeline` (events with one `id` update one card), `calliope.artifact` on `ArtifactCard` with `DocumentReview`, `MediaReview` or `FormReview` (signing or sending the review resumes the run), and `calliope.question` interrupts on `WorkflowQuestionCard`.
+- **Surfaces.** `mode="bubble"` (a launcher and a non-modal panel; a drawer on phones), `"rail"` (a `RailPanel` for `AppShell`'s `rightRail`; the shell's drawer on phones), `"inline"` and `"page"`. Open state is controlled, held, or remembered per person with `persistKey`; `shortcut` (`mod+/` by default) toggles it; answers that land while it is closed show as unread on the launcher. Slots: `renderContent` (the host's markdown), `attachments` and `sendOptions` (attachments as AG-UI input parts), `composerActions`, `modelPicker` (pass the choice in the provider's `forwardedProps`), `headerActions`, `empty`.
+- **Telemetry and errors.** `onEvent(event)` sees every AG-UI event; `onError(error)` every failed run (also shown in the conversation with retry).
+- **Testing.** `createMockAgent({ turns })` plays recorded turns; `createFunctionAgent(run)` makes an agent of any function that yields AG-UI events. Both are real `HttpAgent`s answered in the page, so stories and tests need no network.
+
+Headers on the provider run in the browser: never put a secret there. Keys, the model and authorization stay on the server, in the runtime route or the agent. Copy is in the `agent` message group.
+
+### Moving to it
+
+| Product                              | Today                                                                                                                                                                           | With `CalliopeAgent`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Astrolift Studio                     | `CopilotKitProvider` (1.79.1) and its own `AssistantPanel`, `AssistantTranscript`, `AssistantInput`, `SuggestionChips`, `AssistantLauncher`, `dock.tsx`, `useStored` open state | `CopilotKitAgentProvider runtimeUrl="/api/assistant" useSingleEndpoint agentId="studio" headers={{ [PROJECT_HEADER]: slug }}` (or keep its `CopilotKitProvider`: ours reuses it) and `<CalliopeAgent mode="rail" persistKey={openKey}>` in the shell's rail. The 15 `useHumanInTheLoop` actions become `useAgentTool({ name, parameters, render })` with `ActionCard` as `render` (calling `respond`); the whiteboard tools become `useAgentTool` with their zod schemas; `useAgentContext` readables become `useAgentReadable`; `startingPoints` becomes `useAgentSuggestions`; thread loading becomes `loadThread`. The server route and runner stay. |
+| Zentinelle                           | `ChatBubble` (sparkle button, `Drawer`), `use-chat` parsing a custom `data:` stream, `MessageList`, `ChatInput`, `ModelSelector`, full-page `AssistantScreen`                   | `<CalliopeAgent mode="bubble">` and `mode="page"`, with `modelPicker` fed from `/assistant/providers` and the model in `forwardedProps`. Transport: port `/assistant/chat` to AG-UI (`pending_action` as an interrupt, `navigation` as a `CUSTOM` event drawn as a link chip), or until then adapt it with `createFunctionAgent` over `authenticatedFetch`. An approval resolves the interrupt; the host's `execute-tool` call with the approval token stays a host action in the interrupt renderer, gated on `canMutate`.                                                                                                                             |
+| Astrolift app (Wayfinding)           | `WayfindingBubble` and `use-wayfinding` posting to `/wayfinding/ask/`                                                                                                           | `<CalliopeAgent mode="bubble">` over `createFunctionAgent` that posts the question and returns the answer as text and the routes as a `CUSTOM` event, drawn by a `renderers.custom.routes` component of `Link` chips that close the panel. No tools: read-only by construction. A 503 thrown from the function shows as the run's error.                                                                                                                                                                                                                                                                                                                |
+| Boilerworks django-nextjs-copilotkit | CopilotKit 1.63.1 v1 (`CopilotKit`, `CopilotSidebar`, `useCopilotAction`, `useCopilotReadable`, `react-ui` CSS re-themed)                                                       | Upgrade to `@copilotkit/react-core` 1.79+ and `@copilotkit/runtime/v2` (the runtime route keeps its `HttpAgent` to Django), then `CopilotKitAgentProvider runtimeUrl="/api/copilotkit" agentId="boilerworks_agent"` and `<CalliopeAgent mode="rail">` in place of `CopilotSidebar`. `useCopilotReadable` becomes `useAgentReadable`; `renderAndWaitForResponse` becomes `useAgentTool` with `render` and `respond`; the render-only `draft_form_definition` card becomes `renderers.tools.draft_form_definition`. Drop `@copilotkit/react-ui` and `copilot.css`.                                                                                        |
+
+## Workbench
+
+`@calliopelabs/ui/workbench` is an opt-in entry for IDE-style tools (File Manager, Loadr, Chat Studio): an app without a file browser never loads it. It needs nothing beyond the package's own dependencies, and its styles come from the preset. Like the rest, it is host-driven: data comes in as props, every change goes out through a callback, and nothing fetches.
+
+- **`FileBrowser`**: breadcrumb (its crumbs are drop targets), list and grid views, sorting (folders first, natural order), selection, a context menu, drag-and-drop moves (Alt copies) and an optional folder tree. View, sort and selection work uncontrolled or controlled. Copy for an empty folder, a toolbar slot, and thumbnails for grid tiles.
+- **`FileTree`**: a lazy tree on the WAI-ARIA tree pattern (arrows open and move, Home, End, typeahead). The host answers `onLoad(path)` with a `FileBranch` (`loading`, `error`, `ready`) per directory in `branches`; a failed branch retries through `onRetry`.
+- **`FileList`** and **`FileGrid`**, the two views on their own: a grid (WAI-ARIA grid pattern: arrows between cells, selection follows focus, Shift extends, Cmd/Ctrl moves without selecting, Cmd/Ctrl+A, Escape, Enter opens, Delete, F2 renames) and a multi-select listbox of tiles with two-dimensional arrows.
+- **`UploadDropzone`**: wraps an area (an overlay while desktop files hover, progress floating in a corner) or draws its own box with a picker. `accept` and `maxSize` filter into `onFiles` and `onReject`; the host's `uploads` (`queued`, `uploading` with a percentage or none, `done`, `error`, `canceled`) draw as progress bars with cancel and dismiss.
+- **`FilePreview`**: CSV and TSV (parsed here, quoted fields included) and server-parsed tables in the library's `DataTable` with search, sort and paging; JSON pretty-printed; images; text; markdown through the host's `renderMarkdown` (the package ships no markdown parser, so without one the source shows); a binary fallback, loading, error and a truncation note.
+- Helpers: `FileItem`, `sortFiles`, `previewKindFor`, `parseDelimited`, `formatBytes`, `canDrop`, `pathSegments`, `parentPath`, `joinPath`, `FileIcon`.
+
+```tsx
+import {
+  FileBrowser,
+  FilePreview,
+  UploadDropzone,
+  previewKindFor,
+} from "@calliopelabs/ui/workbench";
+
+<UploadDropzone onFiles={(files) => upload(files, path)} uploads={uploads} onCancel={cancel}>
+  <FileBrowser
+    path={path}
+    items={listing.data?.entries.map(toFileItem)}
+    error={listing.error}
+    onRetry={listing.refetch}
+    onNavigate={setPath}
+    onOpen={(item) => setPreview(item.path)}
+    onMove={(sources, target, { copy }) => (copy ? copyTo : moveTo)(sources, target)}
+    onDelete={confirmDelete}
+    contextMenu={(targets) => <FileActions targets={targets} />}
+    tree={{ root, branches, onLoad: loadFolder, onRetry: loadFolder }}
+  />
+</UploadDropzone>;
+```
+
+Their copy is in the `workbench` message group. The catalog's **Workbench** section shows every state, light and dark, narrow, and large trees.
+
 ## Appearance
 
 The person sets four axes, per product: the **ground** (black, charcoal, graphite, emerald, navy, paper, mist; it decides light or dark), the **accent** (the product's own, a family accent, or any colour that stands 3:1 off the ground), the **density** (`compact` hairline rows or boxed `cards`) and the **corners** (0, 2, 4 or 10 px). `AppearancePicker` is the settings UI for all four.
@@ -554,6 +728,20 @@ document.addEventListener("calliope:appearance", (event) => console.log(event.de
 
 A product that is not built in sets its sidebar with `[data-product="myapp"] { --brand-sidebar: #0b0b19; }` in its own CSS, picks a family accent, and boots with `CalliopeAppearance.boot(config)`, where `config` is the JSON `bootConfig(defineProduct(...))` returns (or one of `CalliopeAppearance.products`, edited).
 
+## Token mappings
+
+Stacks that cannot take the preset or the CSS layer read the same tokens through generated files under `@calliopelabs/ui/tokens/`, each with a guide beside it in `dist/tokens/`:
+
+| File                                     | For                                                         |
+| ---------------------------------------- | ----------------------------------------------------------- |
+| `@calliopelabs/ui/tokens/jupyterlab.css` | JupyterLab and Notebook 7: the `--jp-*` theme variables     |
+| `@calliopelabs/ui/tokens/vscode.css`     | VS Code webviews: `--vscode-*` fallbacks outside VS Code    |
+| `@calliopelabs/ui/tokens/tokens.py`      | Python (the installer): RGB triplets and a small accessor   |
+| `@calliopelabs/ui/tokens/native`         | React Native: a typed palette object per ground and accent  |
+| `@calliopelabs/ui/tokens/plain.css`      | Sites and Cykick: every token as a plain, concrete variable |
+
+Every file covers every ground and family accent, chosen by `data-ground` and `data-accent` in the CSS ones and by argument in the others. They are generated by `npm run theme` from the design tokens (`tokens/*.json`, through `src/theme/tokens.ts`), and a test holds every mapped value to what the preset paints on that ground with that accent. The mapping tables are in each guide.
+
 ## Copy and languages
 
 Every string the package renders is English by default and overridable, one group at a time:
@@ -573,11 +761,11 @@ Node 24 (`.nvmrc`).
 | `npm run storybook`                                         | The catalog, on port 6006                                                        |
 | `npm test`                                                  | Every test, including one that renders every story and runs the a11y addon on it |
 | `npm run lint`, `npm run typecheck`, `npm run format:check` | The gates CI runs                                                                |
-| `npm run theme`                                             | Regenerates `src/styles/theme.css` and the CSS layer after a token change        |
+| `npm run theme`                                             | Regenerates the constants, `theme.css`, the CSS layer and the token mappings     |
 | `npm run build`, `npm run pack:check`                       | Builds `dist/` and checks the package a consumer receives                        |
 | `npm run build-storybook`                                   | The static catalog                                                               |
 
-Conventions for contributors and agents are in [`bootstrap.md`](bootstrap.md).
+Conventions for contributors and agents are in [`bootstrap.md`](bootstrap.md). Designers: the token files, what each one changes and how to propose a change are in the Storybook pages under **Designer guide** (`src/docs/`).
 
 ## Releasing
 

package/dist/agent/AgentChat.d.ts

@@ -0,0 +1,63 @@
+import * as React from "react";
+import type { ChatContentRenderer } from "../chat/MessageBubble.js";
+import { type ChatToolCall } from "../chat/model.js";
+import { type ModelPickerProps } from "../chat/ModelPicker.js";
+import type { SendOptions } from "./controller.js";
+import { type AgentRenderers } from "./renderers.js";
+export interface AgentChatProps {
+    /** The panel's title. Defaults to the product's assistant ("Astrolift AI assistant"). */
+    title?: string;
+    /** Hides the heading row (inline and page surfaces that have their own). */
+    hideHeader?: boolean;
+    /** Controls beside the title, before the built-in ones. */
+    headerActions?: React.ReactNode;
+    /** Shows a close button. */
+    onClose?: () => void;
+    /** Shows expand and restore (the rail's full-width mode). */
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    /** Hides "New conversation". */
+    hideNewConversation?: boolean;
+    /** Draws message text: the host's markdown renderer. Plain text by default. */
+    renderContent?: ChatContentRenderer;
+    /** Draws a tool call the host has its own component for; undefined falls through to the tool's `render`, then the default card. */
+    renderToolCall?: (call: ChatToolCall) => React.ReactNode;
+    /** The tool's name for people, per call. */
+    toolTitle?: (call: ChatToolCall) => string | undefined;
+    /**
+     * Generative UI: host components for tool calls, custom events, interrupts
+     * and the shared state (see `AgentRenderers`; `workflowRenderers` draws the
+     * run and review components). `renderToolCall` still wins for a call.
+     */
+    renderers?: AgentRenderers;
+    /** "line": a one-line status while running (bubble, rail). "steps": the run's steps on the run timeline (page). */
+    progress?: "line" | "steps" | "none";
+    /** Replaces the empty state (the suggestions still show under it). */
+    empty?: React.ReactNode;
+    /** Above the composer's field: the host's attachment chips. */
+    attachments?: React.ReactNode;
+    /** Beside send: an attach button, other controls. */
+    composerActions?: React.ReactNode;
+    /** A model picker in the composer; the host passes the chosen model in `forwardedProps`. */
+    modelPicker?: ModelPickerProps;
+    /** What to send with the text: the attachments as AG-UI input parts. Called on send. */
+    sendOptions?: () => SendOptions | undefined;
+    placeholder?: string;
+    autoFocus?: boolean;
+    /** Offers the suggestions after each answer too, not only before the first message. */
+    suggestionsAfterRun?: boolean;
+    className?: string;
+}
+/** Starts a new, empty conversation with the nearest agent. */
+export declare function NewConversationButton({ className }: {
+    className?: string;
+}): React.JSX.Element;
+/**
+ * The conversation with the nearest agent, whole: a heading row, the
+ * messages with tool cards and approvals, starting points, run status and
+ * the composer. Every surface of `CalliopeAgent` draws this; a host that
+ * lays out its own screen can too. Tools registered with a `render` draw
+ * their own calls; one that waits on the person gets `respond`, and the
+ * composer holds until it is answered.
+ */
+export declare function AgentChat({ title, hideHeader, headerActions, onClose, expanded, onExpandedChange, hideNewConversation, renderContent, renderToolCall, toolTitle, renderers, progress, empty, attachments, composerActions, modelPicker, sendOptions, placeholder, autoFocus, suggestionsAfterRun, className, }: AgentChatProps): React.JSX.Element;

package/dist/agent/AgentChat.js

@@ -0,0 +1,117 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Maximize2Icon, Minimize2Icon, SquarePenIcon, XIcon } from "lucide-react";
+import * as React from "react";
+import { useProduct } from "../appearance/AppearanceProvider.js";
+import { AgentProgress } from "../chat/AgentProgress.js";
+import { Composer } from "../chat/Composer.js";
+import { MessageList } from "../chat/MessageList.js";
+import { parseToolCallArgs } from "../chat/model.js";
+import { ModelPicker } from "../chat/ModelPicker.js";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { useUI } from "../provider/UIProvider.js";
+import { EmptyState } from "../states/EmptyState.js";
+import { StatusDot } from "../status/StatusDot.js";
+import { useCalliopeAgent } from "./AgentProvider.js";
+import { parseResult } from "./renderers.js";
+import { InterruptCard } from "./WorkflowRenderers.js";
+function ToolRender({ tool, call, waiting, respond, }) {
+    return (_jsx(_Fragment, { children: tool.render?.({
+            call,
+            args: parseToolCallArgs(call.args),
+            ...(waiting ? { respond: (result) => respond(call.id, result) } : {}),
+        }) }));
+}
+/** Starts a new, empty conversation with the nearest agent. */
+export function NewConversationButton({ className }) {
+    const agent = useCalliopeAgent();
+    const { messages } = useUI();
+    const label = messages.agent.newConversation;
+    const fresh = agent.view.timeline.length === 0 && !agent.view.error;
+    return (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": label, title: label, disabled: fresh && !agent.running, onClick: () => void agent.newThread(), className: className, children: _jsx(SquarePenIcon, { "aria-hidden": true }) }));
+}
+function Suggestions({ suggestions, disabled, onPick, }) {
+    const { messages } = useUI();
+    if (suggestions.length === 0)
+        return null;
+    return (_jsx("div", { role: "group", "aria-label": messages.agent.suggestions, "data-slot": "agent-suggestions", className: "flex min-w-0 flex-wrap gap-2", children: suggestions.map((s) => (_jsx(Button, { variant: "outline", size: "sm", disabled: disabled, onClick: () => onPick(s), className: "max-w-full", children: _jsx("span", { className: "truncate", children: s.title }) }, s.message))) }));
+}
+/**
+ * The conversation with the nearest agent, whole: a heading row, the
+ * messages with tool cards and approvals, starting points, run status and
+ * the composer. Every surface of `CalliopeAgent` draws this; a host that
+ * lays out its own screen can too. Tools registered with a `render` draw
+ * their own calls; one that waits on the person gets `respond`, and the
+ * composer holds until it is answered.
+ */
+export function AgentChat({ title, hideHeader = false, headerActions, onClose, expanded, onExpandedChange, hideNewConversation = false, renderContent, renderToolCall, toolTitle, renderers, progress = "line", empty, attachments, composerActions, modelPicker, sendOptions, placeholder, autoFocus, suggestionsAfterRun = false, className, }) {
+    const agent = useCalliopeAgent();
+    const { messages } = useUI();
+    const product = useProduct();
+    const t = messages.agent;
+    const name = title ?? t.title(product?.name);
+    const headingId = React.useId();
+    const { view, running, waiting, suggestions, tools } = agent;
+    const blocked = waiting.length > 0;
+    const fresh = view.timeline.length === 0 && !view.error;
+    const send = (text) => void agent.send(text, sendOptions?.());
+    const root = React.useRef(null);
+    const pick = (s) => {
+        void agent.send(s.message);
+        // The chip goes away with the empty state; the composer keeps the person's place.
+        root.current?.querySelector("[data-slot=composer] textarea")?.focus();
+    };
+    const drawCall = (call) => {
+        const custom = renderToolCall?.(call);
+        if (custom !== undefined)
+            return custom;
+        const Renderer = renderers?.tools?.[call.name];
+        if (Renderer) {
+            return (_jsx(Renderer, { call: call, args: parseToolCallArgs(call.args), result: parseResult(call), agent: agent, ...(waiting.includes(call.id)
+                    ? { respond: (result) => agent.respond(call.id, result) }
+                    : {}) }));
+        }
+        const tool = tools.find((t) => t.name === call.name && t.render);
+        if (!tool)
+            return undefined;
+        return (_jsx(ToolRender, { tool: tool, call: call, waiting: waiting.includes(call.id), respond: agent.respond }));
+    };
+    // Custom events, each after the timeline item it arrived after (the first, when before any).
+    const first = view.timeline[0];
+    const firstKey = first ? `${first.kind}:${first.id}` : null;
+    const drawAfter = (item) => {
+        const key = `${item.kind}:${item.id}`;
+        const here = agent.custom.filter((c) => renderers?.custom?.[c.name] && (c.after ?? firstKey) === key);
+        if (here.length === 0)
+            return null;
+        return here.map((c) => {
+            const Renderer = renderers.custom[c.name];
+            return (_jsx("div", { "data-slot": "agent-custom", className: "min-w-0", children: _jsx(Renderer, { name: c.name, value: c.value, history: c.history, agent: agent }) }, c.key));
+        });
+    };
+    // Interrupts that no tool card or artifact answers: drawn after the conversation.
+    const claimed = new Set(agent.custom.flatMap((c) => {
+        const id = c.value?.interruptId;
+        return renderers?.custom?.[c.name] && typeof id === "string" ? [id] : [];
+    }));
+    const loose = view.status === "interrupted"
+        ? view.interrupts.filter((i) => !i.toolCallId && !claimed.has(i.id))
+        : [];
+    const footer = loose.length > 0
+        ? loose.map((interrupt) => {
+            const Renderer = renderers?.interrupts?.[interrupt.reason] ?? InterruptCard;
+            return (_jsx(Renderer, { interrupt: interrupt, agent: agent, resolve: (payload) => agent.resolveInterrupt(interrupt.id, {
+                    status: "resolved",
+                    ...(payload === undefined ? {} : { payload }),
+                }), cancel: () => agent.resolveInterrupt(interrupt.id, { status: "cancelled" }) }, interrupt.id));
+        })
+        : undefined;
+    const StateView = renderers?.state;
+    const step = [...view.steps].reverse().find((s) => s.status === "running");
+    return (_jsxs("section", { ref: root, "aria-labelledby": hideHeader ? undefined : headingId, "aria-label": hideHeader ? name : undefined, "data-slot": "agent-chat", className: cn("flex min-h-0 min-w-0 flex-col bg-card text-card-foreground", className), children: [!hideHeader && (_jsxs("div", { className: "flex min-w-0 items-center gap-1 border-b px-3 py-2", children: [_jsx("h2", { id: headingId, className: "min-w-0 flex-1 truncate text-sm font-semibold", children: name }), headerActions, !hideNewConversation && _jsx(NewConversationButton, {}), onExpandedChange && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": expanded ? t.restore : t.expand, title: expanded ? t.restore : t.expand, onClick: () => onExpandedChange(!expanded), children: expanded ? _jsx(Minimize2Icon, { "aria-hidden": true }) : _jsx(Maximize2Icon, { "aria-hidden": true }) })), onClose && (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": t.close, title: t.close, onClick: onClose, children: _jsx(XIcon, { "aria-hidden": true }) }))] })), progress === "steps" && view.steps.length > 0 && (_jsx(AgentProgress, { view: view, className: "border-b px-3 py-2" })), StateView && view.state !== undefined && (_jsx("div", { role: "region", "aria-label": t.sharedState, "data-slot": "agent-state", 
+                // A scrolling region is reached by keyboard (WCAG 2.1.1).
+                tabIndex: 0, className: "max-h-48 min-w-0 shrink-0 overflow-y-auto border-b px-3 py-2", children: _jsx(StateView, { state: view.state, setState: agent.setState, agent: agent }) })), _jsx(MessageList, { view: view, renderContent: renderContent, renderToolCall: drawCall, renderAfter: drawAfter, footer: footer, toolTitle: toolTitle, onApprove: (call) => agent.approve(call), onDeny: (call, reason) => agent.deny(call, reason), onRetry: () => void agent.regenerate(), empty: _jsxs("div", { className: "flex flex-col items-center gap-4 py-6", children: [empty ?? _jsx(EmptyState, { title: t.emptyTitle, description: t.emptyDescription }), _jsx(Suggestions, { suggestions: suggestions, disabled: running, onPick: pick })] }), className: "min-h-0 flex-1" }), _jsxs("div", { className: "flex min-w-0 flex-col gap-2 border-t p-3", children: [suggestionsAfterRun && !fresh && !running && (_jsx(Suggestions, { suggestions: suggestions, disabled: running, onPick: pick })), _jsx("p", { role: "status", "data-slot": "agent-status", className: cn("flex min-w-0 items-center gap-2 text-xs text-muted-foreground", !(progress === "line" && running) && !blocked && "sr-only"), children: blocked ? (t.waitingOnYou) : running ? (_jsxs(_Fragment, { children: [_jsx(StatusDot, { tone: "info", pulse: true }), _jsx("span", { className: "truncate", children: step ? step.name : messages.chat.runStatus("running") })] })) : null }), _jsx(Composer, { onSubmit: send, running: running, onStop: agent.stop, disabled: blocked, placeholder: placeholder, 
+                        // eslint-disable-next-line jsx-a11y/no-autofocus -- the person just opened the assistant to type
+                        autoFocus: autoFocus, attachments: attachments, actions: modelPicker || composerActions ? (_jsxs(_Fragment, { children: [modelPicker && _jsx(ModelPicker, { ...modelPicker }), composerActions] })) : undefined })] })] }));
+}

package/dist/agent/AgentLauncher.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+export interface AgentLauncherProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** The assistant's name, for the button's label. */
+    title: string;
+    /** Answers that arrived while closed: a badge, and part of the name. */
+    unread?: number;
+    /** The id of the panel it opens. */
+    controls?: string;
+    /** Shown in the tooltip and announced ("mod+/"). */
+    shortcut?: string | false;
+    /** The mark on the button. Defaults to the product's logo mark, then a sparkle. */
+    icon?: React.ReactNode;
+    /** "floating": the round button at the page's corner. "inline": a header button. */
+    variant?: "floating" | "inline";
+    ref?: React.Ref<HTMLButtonElement>;
+    className?: string;
+}
+/**
+ * The button that opens the agent: floating at the page's corner (the
+ * bubble) or in a header (beside a rail). Carries the product's mark, an
+ * unread badge whose count is part of its name, and its shortcut.
+ */
+export declare function AgentLauncher({ open, onOpenChange, title, unread, controls, shortcut, icon, variant, ref, className, }: AgentLauncherProps): React.JSX.Element;

package/dist/agent/AgentLauncher.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SparklesIcon } from "lucide-react";
+import * as React from "react";
+import { useProduct } from "../appearance/AppearanceProvider.js";
+import { cn } from "../lib/cn.js";
+import { useUI } from "../provider/UIProvider.js";
+import { shortcutAria, shortcutLabel } from "./surface.js";
+/**
+ * The button that opens the agent: floating at the page's corner (the
+ * bubble) or in a header (beside a rail). Carries the product's mark, an
+ * unread badge whose count is part of its name, and its shortcut.
+ */
+export function AgentLauncher({ open, onOpenChange, title, unread = 0, controls, shortcut, icon, variant = "floating", ref, className, }) {
+    const { messages } = useUI();
+    const product = useProduct();
+    const t = messages.agent;
+    const mark = icon ??
+        (product?.logo?.mark ? (_jsx("img", { src: product.logo.mark, alt: "", className: "size-5 rounded-sm object-contain" })) : (_jsx(SparklesIcon, { "aria-hidden": true, className: "size-5" })));
+    const label = open ? t.close : t.open(title);
+    const hint = shortcut ? `${label} (${shortcutLabel(shortcut)})` : label;
+    return (_jsxs("button", { ref: ref, type: "button", "data-slot": "agent-launcher", "aria-expanded": open, "aria-controls": controls, "aria-keyshortcuts": shortcut ? shortcutAria(shortcut) : undefined, title: hint, onClick: () => onOpenChange(!open), className: cn("relative inline-flex shrink-0 items-center justify-center outline-none focus-visible:ring-3 focus-visible:ring-ring/50", variant === "floating"
+            ? "size-12 rounded-full bg-primary text-primary-foreground shadow-lg transition-transform hover:scale-105 motion-reduce:transition-none motion-reduce:hover:scale-100"
+            : "h-8 gap-1.5 rounded-lg border border-border bg-background px-2.5 text-sm font-medium hover:bg-muted", className), children: [mark, variant === "inline" && _jsx("span", { children: title }), _jsxs("span", { className: "sr-only", children: [variant === "floating" ? label : "", unread > 0 ? `, ${t.unread(unread)}` : ""] }), unread > 0 && (_jsx("span", { "aria-hidden": true, "data-slot": "agent-unread", className: "absolute -top-1 -right-1 inline-flex min-w-5 items-center justify-center rounded-full border border-danger-border bg-danger-bg px-1 text-2xs font-semibold text-danger-fg", children: unread > 9 ? "9+" : unread }))] }));
+}

package/dist/agent/AgentProvider.d.ts

@@ -0,0 +1,82 @@
+import { type AbstractAgent } from "@ag-ui/client";
+import * as React from "react";
+import type { ChatToolCall } from "../chat/model.js";
+import { AgentController, type AgentContextEntry, type AgentControllerOptions, type AgentSnapshot, type AgentSuggestion, type SendOptions } from "./controller.js";
+import { type AgentEngine, type ToolInvoker } from "./engine.js";
+import { type AgentTool } from "./tool.js";
+/** What every agent provider takes, whatever runs the agent. */
+export interface CalliopeAgentOptions extends AgentControllerOptions {
+    /** Tools for the whole app; a page adds its own with `useAgentTool`. */
+    tools?: readonly AgentTool<any>[];
+    /** Readables for the whole app; a page adds its own with `useAgentReadable`. */
+    context?: readonly AgentContextEntry[];
+    /** Prompts offered as chips; a page adds its own with `useAgentSuggestions`. */
+    suggestions?: readonly AgentSuggestion[];
+}
+export interface CalliopeAgentProviderProps extends Omit<CalliopeAgentOptions, "forwardedProps"> {
+    /** The AG-UI agent: an `HttpAgent`, any `AbstractAgent`, or `createMockAgent` in a story. */
+    agent?: AbstractAgent;
+    /** Or a plain AG-UI endpoint: an `HttpAgent` is made for it. Same origin, so the session cookie goes along. */
+    url?: string;
+    /** Request headers for `url` (a project id). Never a secret: this runs in the browser. */
+    headers?: Record<string, string>;
+    /** The conversation to start in; `switchThread` moves later. */
+    threadId?: string;
+    /** Sent with every run (the model picked, the page). */
+    forwardedProps?: Record<string, unknown>;
+    children: React.ReactNode;
+}
+/** The agent as a page reads it: the conversation and what the person can do. */
+export interface CalliopeAgentApi extends AgentSnapshot {
+    send: (text: string, options?: SendOptions) => Promise<void>;
+    stop: () => void;
+    regenerate: () => Promise<void>;
+    approve: (call: ChatToolCall, payload?: Record<string, unknown>) => void;
+    deny: (call: ChatToolCall, reason: string) => void;
+    resolveInterrupt: AgentController["resolveInterrupt"];
+    respond: (toolCallId: string, result: unknown) => void;
+    getState: <T = unknown>() => T;
+    setState: (state: unknown) => void;
+    registerTool: AgentController["registerTool"];
+    addContext: (entry: AgentContextEntry) => () => void;
+    switchThread: (threadId: string) => Promise<void>;
+    newThread: () => Promise<string>;
+    setVisible: (visible: boolean) => void;
+    agent: AbstractAgent;
+    controller: AgentController;
+}
+/** The controller of the nearest agent provider, or null outside one. */
+export declare function useAgentController(): AgentController | null;
+/**
+ * Hosts a controller for any engine; the providers below and the CopilotKit
+ * one are this with their engine. Registers the option-level tools, context
+ * and suggestions, and connects after mount.
+ */
+export declare function AgentHost({ createEngine, engineKey, options, children, }: {
+    createEngine: (invoke: ToolInvoker) => AgentEngine;
+    /** A new key swaps the engine (a new agent). */
+    engineKey: unknown;
+    options: CalliopeAgentOptions;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * The agent for a page tree, over a plain AG-UI endpoint (`url`) or any
+ * AG-UI agent (`agent`). Headless: it renders nothing of its own; put
+ * `CalliopeAgent` (a bubble, a rail, inline or a page) or the chat kit's
+ * components under it, and read it with `useCalliopeAgent`. For a CopilotKit
+ * runtime use `CopilotKitAgentProvider` from `@calliopelabs/ui/agent/copilotkit`.
+ */
+export declare function CalliopeAgentProvider({ agent: given, url, headers, threadId, forwardedProps, children, ...options }: CalliopeAgentProviderProps): React.JSX.Element;
+/** The nearest agent: its conversation, state and actions. Re-renders on every change. */
+export declare function useCalliopeAgent(): CalliopeAgentApi;
+/**
+ * Offers a tool to the agent while the component is mounted (a whiteboard's
+ * tools only while it is open). The handler and renderer may change every
+ * render; the tool re-registers only when its name, description, schema,
+ * availability or follow-up change.
+ */
+export declare function useAgentTool<Args>(tool: AgentTool<Args>): void;
+/** Tells the agent about the page while mounted: a readable. Re-sent when the value's JSON changes. */
+export declare function useAgentReadable(description: string, value: unknown): void;
+/** Offers prompts as chips while mounted (a page's starting points). */
+export declare function useAgentSuggestions(suggestions: readonly AgentSuggestion[]): void;