@calliopelabs/ui 0.12.0 → 0.14.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**.
 
@@ -373,10 +373,61 @@ const registry: WorkflowRegistry = {
 
 It marks unsaved edits and a draft that differs from live (`documentStatus`). A newer saved revision is taken when there is nothing to lose; when it moves under unsaved edits, it stops and asks: compare, use theirs, or keep mine. Publishing shows the draft against live (`WorkflowDiff`) and is held while anything blocks. A rejected promise's message is shown and the edits stay. Persistence and authority stay with the host: it never saves, publishes or runs anything itself. Below a 64rem container the palette and the side panel open as drawers.
 
+A host can reach further into the editor. Each is opt-in; without them the editor is as above.
+
+- **Deep links.** `defaultSelection` opens the editor on a flow and a node (`{ type: "node", flow, id }`); `selection` with `onSelectionChange` holds it in the host. A selection in another flow opens that flow, and the canvas brings the node into view.
+- **Flows.** `onFlowCreate` offers New flow and `onFlowRename` offers Rename flow for the open one. The dialog checks the name as it is typed against `WORKFLOW_FLOW_NAME` (a lowercase slug of up to 32 characters), against the other flows and against `WORKFLOW_MAX_FLOWS`, then hands the host the next definition to apply. `renameFlow` renames the key, `main` and every sub-flow node that runs it; anything else the host keeps that names flows is the host's to follow. `flowNameProblem`, `addFlow` and `renameFlow` are exported for hosts that edit flows themselves.
+- **Host fields.** `renderNodeFields` adds the host's own fields to the inspector after a node's kind fields, with the node, its flow and an `onChange` that patches it. Switch on `node.kind` and return null for none.
+
+```tsx
+<WorkflowWorkspace
+  {...props}
+  defaultSelection={at ? { type: "node", flow: at.flow, id: at.node } : null}
+  onFlowCreate={(next) => setDraft(next)}
+  onFlowRename={(next, from, to) => setDraft(next) /* and follow `from` to `to` in what you keep */}
+  renderNodeFields={({ node, readOnly }) =>
+    node.kind === "step" ? <RunnerPicker step={node.id} readOnly={readOnly} /> : null
+  }
+/>
+```
+
 The canvas pans, zooms and fits without going below `READABLE_ZOOM`; loop bodies and fan-out branches fold, and a sub-flow shows in place. Every drag has a keyboard equivalent: Tab to a node or edge, Enter to select, arrows to move, Delete to remove, and Add and Connect in its toolbar.
 
 `@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.
+
 ## 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.
@@ -536,6 +587,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:
@@ -555,11 +620,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,56 @@
+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";
+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;
+    /** "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, progress, empty, attachments, composerActions, modelPicker, sendOptions, placeholder, autoFocus, suggestionsAfterRun, className, }: AgentChatProps): React.JSX.Element;

package/dist/agent/AgentChat.js

@@ -0,0 +1,76 @@
+"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";
+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, 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 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 }));
+    };
+    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" })), _jsx(MessageList, { view: view, renderContent: renderContent, renderToolCall: drawCall, 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;

package/dist/agent/AgentProvider.js

@@ -0,0 +1,176 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { HttpAgent } from "@ag-ui/client";
+import * as React from "react";
+import { AgentController, } from "./controller.js";
+import { createDirectEngine } from "./engine.js";
+import { toolJsonSchema } from "./tool.js";
+const AgentContext = React.createContext(null);
+/** The controller of the nearest agent provider, or null outside one. */
+export function useAgentController() {
+    return React.useContext(AgentContext);
+}
+function useController() {
+    const controller = React.useContext(AgentContext);
+    if (!controller) {
+        throw new Error("No agent here: wrap the app in CalliopeAgentProvider or CopilotKitAgentProvider.");
+    }
+    return controller;
+}
+/** Keeps a value's identity while its JSON stays the same, so inline arrays do not re-register. */
+function useStable(value) {
+    const key = safeKey(value);
+    // The key is the value's content; a new array with the same content keeps the old identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return React.useMemo(() => value, [key]);
+}
+/** Sets an HttpAgent's request headers for its next run. */
+function assignHeaders(agent, headers) {
+    if (agent instanceof HttpAgent && headers)
+        agent.headers = { ...headers };
+}
+function safeKey(value) {
+    try {
+        return JSON.stringify(value, (_k, v) => typeof v === "function" ? `fn:${v.name}` : v);
+    }
+    catch {
+        return String(Math.random());
+    }
+}
+/**
+ * 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 function AgentHost({ createEngine, engineKey, options, children, }) {
+    const [controller] = React.useState(() => new AgentController(createEngine, options));
+    const engineRef = React.useRef(engineKey);
+    React.useEffect(() => {
+        if (engineRef.current === engineKey)
+            return;
+        engineRef.current = engineKey;
+        controller.attach(createEngine);
+        // createEngine follows engineKey; the key is the identity that matters.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [controller, engineKey]);
+    React.useEffect(() => controller.setOptions(options));
+    React.useEffect(() => controller.connect(), [controller]);
+    const { tools, context, suggestions } = options;
+    React.useEffect(() => {
+        if (!tools?.length)
+            return;
+        const offs = tools.map((tool) => controller.registerTool(tool));
+        return () => offs.forEach((off) => off());
+    }, [controller, tools]);
+    const stableContext = useStable(context);
+    React.useEffect(() => {
+        if (!stableContext?.length)
+            return;
+        const offs = stableContext.map((entry) => controller.addContext(entry));
+        return () => offs.forEach((off) => off());
+    }, [controller, stableContext]);
+    const stableSuggestions = useStable(suggestions);
+    React.useEffect(() => (stableSuggestions?.length ? controller.addSuggestions(stableSuggestions) : undefined), [controller, stableSuggestions]);
+    return _jsx(AgentContext.Provider, { value: controller, children: children });
+}
+/**
+ * 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 function CalliopeAgentProvider({ agent: given, url, headers, threadId, forwardedProps, children, ...options }) {
+    const agent = React.useMemo(() => {
+        if (given)
+            return given;
+        if (!url)
+            throw new Error("CalliopeAgentProvider needs an agent or a url.");
+        return new HttpAgent({ url, ...(threadId ? { threadId } : {}) });
+        // threadId only seeds a new agent; switchThread moves it afterwards.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [given, url]);
+    React.useEffect(() => {
+        assignHeaders(agent, headers);
+    }, [agent, headers]);
+    const props = React.useRef(forwardedProps);
+    React.useEffect(() => {
+        props.current = forwardedProps;
+    });
+    return (_jsx(AgentHost, { engineKey: agent, createEngine: (invoke) => createDirectEngine(agent, invoke), options: { ...options, forwardedProps: () => props.current }, children: children }));
+}
+/** The nearest agent: its conversation, state and actions. Re-renders on every change. */
+export function useCalliopeAgent() {
+    const controller = useController();
+    const snapshot = React.useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    return React.useMemo(() => ({
+        ...snapshot,
+        send: controller.send,
+        stop: controller.stop,
+        regenerate: controller.regenerate,
+        approve: controller.approve,
+        deny: controller.deny,
+        resolveInterrupt: controller.resolveInterrupt,
+        respond: controller.respond,
+        getState: controller.getState,
+        setState: controller.setState,
+        registerTool: controller.registerTool,
+        addContext: controller.addContext,
+        switchThread: controller.switchThread,
+        newThread: controller.newThread,
+        setVisible: controller.setVisible,
+        agent: controller.agent,
+        controller,
+    }), [controller, snapshot]);
+}
+/**
+ * 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 function useAgentTool(tool) {
+    const controller = useController();
+    const latest = React.useRef(tool);
+    React.useEffect(() => {
+        latest.current = tool;
+    });
+    const schema = safeKey(toolJsonSchema(tool));
+    const hasHandler = tool.handler !== undefined;
+    const hasRender = tool.render !== undefined;
+    React.useEffect(() => {
+        const t = latest.current;
+        return controller.registerTool({
+            name: t.name,
+            ...(t.description !== undefined ? { description: t.description } : {}),
+            ...(t.parameters !== undefined ? { parameters: t.parameters } : {}),
+            ...(t.followUp !== undefined ? { followUp: t.followUp } : {}),
+            ...(t.available !== undefined ? { available: t.available } : {}),
+            ...(hasHandler
+                ? { handler: (args, context) => latest.current.handler?.(args, context) }
+                : {}),
+            ...(hasRender ? { render: (props) => latest.current.render?.(props) } : {}),
+        });
+    }, [
+        controller,
+        tool.name,
+        tool.description,
+        tool.followUp,
+        tool.available,
+        schema,
+        hasHandler,
+        hasRender,
+    ]);
+}
+/** Tells the agent about the page while mounted: a readable. Re-sent when the value's JSON changes. */
+export function useAgentReadable(description, value) {
+    const controller = useController();
+    const stable = useStable(value);
+    React.useEffect(() => controller.addContext({ description, value: stable }), [controller, description, stable]);
+}
+/** Offers prompts as chips while mounted (a page's starting points). */
+export function useAgentSuggestions(suggestions) {
+    const controller = useController();
+    const stable = useStable(suggestions);
+    React.useEffect(() => (stable.length ? controller.addSuggestions(stable) : undefined), [controller, stable]);
+}

package/dist/agent/CalliopeAgent.d.ts

@@ -0,0 +1,43 @@
+import * as React from "react";
+import { type AgentChatProps } from "./AgentChat.js";
+export type CalliopeAgentMode = "bubble" | "rail" | "inline" | "page";
+export interface CalliopeAgentProps extends Omit<AgentChatProps, "onClose" | "hideHeader" | "expanded" | "onExpandedChange"> {
+    /**
+     * `bubble`: a launcher at the page's corner opening a floating panel (a
+     * drawer on phones). `rail`: a RailPanel for AppShell's `rightRail` (the
+     * shell's drawer on phones), with the launcher while closed. `inline`: the
+     * conversation in place, filling its box. `page`: the conversation as the
+     * page, centred to a reading width.
+     */
+    mode: CalliopeAgentMode;
+    /** Open (bubble, rail), when the host holds it. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Remembers open or closed per person in this browser under this key ("studio.assistant.open.<user>"). */
+    persistKey?: string;
+    /** Toggles the bubble or rail: "mod+/" (Cmd or Ctrl and /) by default; false for none. */
+    shortcut?: string | false;
+    /** The launcher's mark. Defaults to the product's logo mark, then a sparkle. */
+    launcherIcon?: React.ReactNode;
+    /** Hides the launcher (a rail opened from the host's own header button). */
+    hideLauncher?: boolean;
+    /** Rail: its width in px, and resizable when `onRailWidthChange` is given. */
+    railWidth?: number;
+    onRailWidthChange?: (width: number) => void;
+    /** Rail: taking the content column (pair with AppShell's `rightRailExpanded`). */
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    /** Hides the header for inline and page surfaces that have their own. */
+    hideHeader?: boolean;
+    className?: string;
+}
+/**
+ * The embedded agent of a Calliope AI product, one primitive for every
+ * surface: a floating bubble, the shell's right rail, inline in a page or a
+ * page of its own. Reads the nearest `CalliopeAgentProvider` (or the
+ * CopilotKit one); draws everything with the chat kit and the product's
+ * tokens, so it carries each product's and each deployment's brand. Answers
+ * that land while it is closed count as unread on the launcher.
+ */
+export declare function CalliopeAgent({ mode, open: openProp, defaultOpen, onOpenChange, persistKey, shortcut, launcherIcon, hideLauncher, railWidth, onRailWidthChange, expanded, onExpandedChange, hideHeader, title, className, ...chat }: CalliopeAgentProps): React.JSX.Element;