@calliopelabs/ui 0.14.0 → 0.16.0

package/README.md

@@ -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
 
@@ -428,6 +428,147 @@ const chat = useAgUiRun();
 
 `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.

package/dist/agent/AgentChat.d.ts

@@ -3,6 +3,7 @@ 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;
@@ -23,6 +24,12 @@ export interface AgentChatProps {
     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). */
@@ -53,4 +60,4 @@ export declare function NewConversationButton({ className }: {
  * 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;
+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

@@ -14,6 +14,8 @@ 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,
@@ -43,7 +45,7 @@ function Suggestions({ suggestions, disabled, onPick, }) {
  * 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, }) {
+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();
@@ -64,13 +66,52 @@ export function AgentChat({ title, hideHeader = false, headerActions, onClose, e
         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" })), _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, 
+    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/WorkflowRenderers.d.ts

@@ -0,0 +1,61 @@
+import * as React from "react";
+import { type DocumentReviewProps } from "../workflow/DocumentReview.js";
+import { type FormReviewProps } from "../workflow/FormReview.js";
+import { type MediaReviewProps } from "../workflow/MediaReview.js";
+import type { WorkflowQuestion } from "../workflow/question.js";
+import type { Artifact, RunStage } from "../workflow/run.js";
+import type { AgentRenderers, CustomRendererProps, InterruptRendererProps } from "./renderers.js";
+/** `calliope.run`: a run's stages as the agent reports them. Send it again with the same `id` to update. */
+export interface RunProgressValue {
+    id?: string;
+    label?: string;
+    stages: readonly RunStage[];
+}
+/** The review viewer an artifact opens in. */
+export type ArtifactReviewValue = ({
+    viewer: "document";
+} & Pick<DocumentReviewProps, "title" | "pages" | "annotations" | "signOffs" | "signOffRole">) | ({
+    viewer: "media";
+} & Pick<MediaReviewProps, "kind" | "src" | "title" | "poster" | "captions" | "duration" | "comments">) | ({
+    viewer: "form";
+} & Pick<FormReviewProps, "title" | "pages" | "fields" | "threshold">);
+/**
+ * `calliope.artifact`: an output for the person to look at, and to review
+ * when the run waits on it. `interruptId` names the run's interrupt the
+ * review answers: signing a document resolves it with `{ action: "sign-off" }`,
+ * sending a form's review with `{ action: "form-review", fields }`.
+ */
+export interface ArtifactValue {
+    id: string;
+    artifact: Artifact;
+    review?: ArtifactReviewValue;
+    interruptId?: string;
+}
+/** `calliope.question` interrupts carry a question in `metadata.question`. */
+export interface QuestionInterruptMetadata {
+    question: WorkflowQuestion;
+}
+/** The run timeline for `calliope.run` events: progress drawn in the conversation. */
+export declare function RunProgressCard({ value }: CustomRendererProps<RunProgressValue>): React.JSX.Element;
+/**
+ * An artifact the agent produced, with its review viewer (document, media or
+ * form) as the preview. While the run waits on its review, signing off or
+ * sending the form's review answers the interrupt and resumes the run.
+ */
+export declare function ArtifactReviewCard({ value, agent }: CustomRendererProps<ArtifactValue>): React.JSX.Element;
+/** A `calliope.question` interrupt: the runtime question card, its answers resuming the run. */
+export declare function QuestionInterruptCard({ interrupt, resolve }: InterruptRendererProps): React.JSX.Element;
+/**
+ * Any other open interrupt not tied to a tool call: the agent's question in
+ * its words, with approve and decline (a decline always with a reason).
+ */
+export declare function InterruptCard({ interrupt, resolve, className, }: InterruptRendererProps & {
+    className?: string;
+}): React.JSX.Element;
+/**
+ * The workflow run and review components as generative UI: `calliope.run`
+ * custom events draw the run timeline, `calliope.artifact` events draw the
+ * artifact with its document, media or form review, and `calliope.question`
+ * interrupts draw the runtime question card. Merge with the host's own.
+ */
+export declare const workflowRenderers: AgentRenderers;

package/dist/agent/WorkflowRenderers.js

@@ -0,0 +1,102 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { useUI } from "../provider/UIProvider.js";
+import { ArtifactCard } from "../workflow/ArtifactCard.js";
+import { DocumentReview } from "../workflow/DocumentReview.js";
+import { FormReview } from "../workflow/FormReview.js";
+import { MediaReview } from "../workflow/MediaReview.js";
+import { RunTimeline } from "../workflow/RunTimeline.js";
+import { WorkflowQuestionCard } from "../workflow/WorkflowQuestionCard.js";
+/** The run timeline for `calliope.run` events: progress drawn in the conversation. */
+export function RunProgressCard({ value }) {
+    return (_jsx("div", { className: "min-w-0 rounded-lg border bg-card p-3", children: _jsx(RunTimeline, { stages: value.stages, label: value.label }) }));
+}
+function openInterrupt(agent, id) {
+    if (!id || agent.view.status !== "interrupted")
+        return undefined;
+    return agent.view.interrupts.find((i) => i.id === id);
+}
+/**
+ * An artifact the agent produced, with its review viewer (document, media or
+ * form) as the preview. While the run waits on its review, signing off or
+ * sending the form's review answers the interrupt and resumes the run.
+ */
+export function ArtifactReviewCard({ value, agent }) {
+    const { messages } = useUI();
+    const waiting = openInterrupt(agent, value.interruptId);
+    const [fields, setFields] = React.useState({});
+    const resolve = (payload) => waiting && agent.resolveInterrupt(waiting.id, { status: "resolved", payload });
+    const review = value.review;
+    let preview = null;
+    if (review?.viewer === "document") {
+        const { viewer: _, ...props } = review;
+        preview = (_jsx(DocumentReview, { ...props, ...(waiting
+                ? { onSignOff: () => resolve({ action: "sign-off", artifactId: value.id }) }
+                : {}) }));
+    }
+    else if (review?.viewer === "media") {
+        const { viewer: _, ...props } = review;
+        preview = _jsx(MediaReview, { ...props });
+    }
+    else if (review?.viewer === "form") {
+        const { viewer: _, ...props } = review;
+        const current = props.fields.map((f) => fields[f.id] ?? f);
+        preview = (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsx(FormReview, { ...props, fields: current, ...(waiting
+                        ? {
+                            onAccept: (field) => setFields((s) => ({ ...s, [field.id]: { ...field, status: "accepted" } })),
+                            onCorrect: (field, corrected) => setFields((s) => ({
+                                ...s,
+                                [field.id]: { ...field, status: "corrected", corrected },
+                            })),
+                        }
+                        : {}) }), waiting && (_jsx(Button, { size: "sm", className: "self-end", onClick: () => resolve({
+                        action: "form-review",
+                        artifactId: value.id,
+                        fields: current.map(({ id, status, corrected }) => ({ id, status, corrected })),
+                    }), children: messages.agent.sendReview }))] }));
+    }
+    return _jsx(ArtifactCard, { artifact: value.artifact, preview: preview, headingLevel: "h3" });
+}
+/** A `calliope.question` interrupt: the runtime question card, its answers resuming the run. */
+export function QuestionInterruptCard({ interrupt, resolve }) {
+    const question = interrupt.metadata?.question;
+    const [state, setState] = React.useState("waiting");
+    return (_jsx(WorkflowQuestionCard, { question: question ?? null, state: state, onSubmit: (submission) => {
+            setState("submitting");
+            resolve({ answers: submission.answers, revision: submission.revision });
+        } }));
+}
+/**
+ * Any other open interrupt not tied to a tool call: the agent's question in
+ * its words, with approve and decline (a decline always with a reason).
+ */
+export function InterruptCard({ interrupt, resolve, className, }) {
+    const { messages } = useUI();
+    const t = messages.agent;
+    const [declining, setDeclining] = React.useState(false);
+    const [reason, setReason] = React.useState("");
+    const reasonId = React.useId();
+    return (_jsxs("section", { "aria-label": t.interrupt, "data-slot": "agent-interrupt", className: cn("flex min-w-0 flex-col gap-2 rounded-lg border border-warning-border bg-warning-bg p-3 text-sm text-warning-fg", className), children: [_jsx("p", { className: "[overflow-wrap:anywhere]", children: interrupt.message ?? messages.chat.approvalNeeded }), declining ? (_jsxs("form", { className: "flex min-w-0 flex-col gap-2", onSubmit: (event) => {
+                    event.preventDefault();
+                    if (reason.trim())
+                        resolve({ approved: false, reason: reason.trim() });
+                }, children: [_jsx("label", { htmlFor: reasonId, className: "text-xs font-medium", children: messages.chat.denyReason }), _jsx("textarea", { id: reasonId, value: reason, onChange: (event) => setReason(event.target.value), rows: 2, className: "min-w-0 rounded-md border border-input bg-background p-2 text-sm text-foreground" }), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => setDeclining(false), children: t.back }), _jsx(Button, { type: "submit", variant: "destructive", size: "sm", disabled: !reason.trim(), children: t.decline })] })] })) : (_jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => setDeclining(true), children: t.decline }), _jsx(Button, { size: "sm", onClick: () => resolve({ approved: true }), children: messages.chat.approve })] }))] }));
+}
+/**
+ * The workflow run and review components as generative UI: `calliope.run`
+ * custom events draw the run timeline, `calliope.artifact` events draw the
+ * artifact with its document, media or form review, and `calliope.question`
+ * interrupts draw the runtime question card. Merge with the host's own.
+ */
+export const workflowRenderers = {
+    custom: {
+        "calliope.run": RunProgressCard,
+        "calliope.artifact": ArtifactReviewCard,
+    },
+    interrupts: {
+        "calliope.question": QuestionInterruptCard,
+    },
+};

package/dist/agent/controller.d.ts

@@ -38,6 +38,20 @@ export interface AgentControllerOptions {
     /** Every AG-UI event, for the host's telemetry. */
     onEvent?: (event: AgUiEvent) => void;
 }
+/**
+ * A custom event as the conversation draws it: events whose value carries
+ * the same `id` are one item (progress updating in place), placed where the
+ * first of them arrived.
+ */
+export interface AgentCustomItem {
+    key: string;
+    name: string;
+    /** The latest value. */
+    value: unknown;
+    history: readonly unknown[];
+    /** The timeline item it arrived after ("message:<id>", "tool-call:<id>"), or null before any. */
+    after: string | null;
+}
 export interface AgentSnapshot {
     view: ChatView;
     /** True from send until the agent is done, follow-ups and browser tools included. */
@@ -49,6 +63,8 @@ export interface AgentSnapshot {
     unread: number;
     suggestions: readonly AgentSuggestion[];
     tools: readonly AgentTool[];
+    /** The conversation's custom events, grouped and placed (see `AgentCustomItem`). */
+    custom: readonly AgentCustomItem[];
 }
 export interface SendOptions {
     /** Attachments and other parts after the text (AG-UI input content). */
@@ -76,6 +92,8 @@ export declare class AgentController {
     private visible;
     private read;
     private snapshot;
+    /** Where each custom event arrived, by its index in the view. */
+    private anchors;
     private disposed;
     private connected;
     private threadSeq;
@@ -97,6 +115,7 @@ export declare class AgentController {
     private emit;
     private finishedAnswers;
     private build;
+    private customItems;
     private bind;
     /** The view the agent's own messages and state make, for a fresh start or a thread switch. */
     private fromAgent;

package/dist/agent/controller.js

@@ -43,6 +43,8 @@ export class AgentController {
     visible = true;
     read = 0;
     snapshot;
+    /** Where each custom event arrived, by its index in the view. */
+    anchors = [];
     disposed = false;
     connected = false;
     threadSeq = 0;
@@ -140,8 +142,32 @@ export class AgentController {
             unread: Math.max(0, this.finishedAnswers() - this.read),
             suggestions,
             tools: [...this.tools.values()].sort((a, b) => a.order - b.order).map((t) => t.tool),
+            custom: this.customItems(),
         };
     }
+    customItems() {
+        const items = new Map();
+        this.view.custom.forEach((event, i) => {
+            const value = event.value;
+            const id = typeof value === "object" && value !== null && typeof value.id === "string";
+            const key = id ? `${event.name}:${value.id}` : `${event.name}#${i}`;
+            const item = items.get(key);
+            if (item) {
+                item.value = event.value;
+                item.history.push(event.value);
+            }
+            else {
+                items.set(key, {
+                    key,
+                    name: event.name,
+                    value: event.value,
+                    history: [event.value],
+                    after: this.anchors[i] ?? null,
+                });
+            }
+        });
+        return [...items.values()];
+    }
     bind() {
         const agent = this.engine.agent;
         this.unsubscribe();
@@ -160,6 +186,7 @@ export class AgentController {
     /** The view the agent's own messages and state make, for a fresh start or a thread switch. */
     fromAgent(threadId) {
         const agent = this.engine.agent;
+        this.anchors = [];
         let view = { ...createChatView(), threadId };
         if (agent.messages.length > 0) {
             view = reduceChat(view, {
@@ -180,7 +207,12 @@ export class AgentController {
         if (this.halted && event.type !== EventType.RUN_STARTED)
             return;
         this.halted = false;
+        const before = this.view.custom.length;
         this.view = reduceChat(this.view, event);
+        if (this.view.custom.length > before) {
+            const last = this.view.timeline.at(-1);
+            this.anchors.push(last ? `${last.kind}:${last.id}` : null);
+        }
         this.emit();
     }
     /** Tool results the agent's messages gained outside the event stream: the browser's own tools. */
@@ -435,6 +467,7 @@ export class AgentController {
         this.agent.setMessages([]);
         this.agent.setState({});
         this.failed.clear();
+        this.anchors = [];
         this.view = { ...createChatView(), threadId: id };
         this.emit();
         return id;

package/dist/agent/copilotkit/CopilotKitAgentProvider.js

@@ -38,13 +38,13 @@ export function createCopilotKitEngine(copilotkit, agent, invoke, agentId) {
         },
         setTools(next) {
             clearTools();
-            for (const tool of next) {
+            // A render-only tool (available: false) draws the agent's own calls; CopilotKit must not run it.
+            for (const tool of next.filter((t) => t.available !== false)) {
                 copilotkit.addTool({
                     name: tool.name,
                     ...(tool.description !== undefined ? { description: tool.description } : {}),
                     parameters: toolStandardSchema(tool),
                     ...(tool.followUp !== undefined ? { followUp: tool.followUp } : {}),
-                    ...(tool.available !== undefined ? { available: tool.available } : {}),
                     ...(agentId ? { agentId } : {}),
                     handler: (args, ctx) => invoke(tool, args, {
                         toolCallId: ctx.toolCall.id,

package/dist/agent/index.d.ts

@@ -4,12 +4,14 @@
  * `@ag-ui/client`, which the package's main entry never loads. For a
  * CopilotKit runtime, see `@calliopelabs/ui/agent/copilotkit`.
  */
-export { AgentController, agentId, type AgentContextEntry, type AgentControllerOptions, type AgentSnapshot, type AgentSuggestion, type AgentThread, type SendOptions, } from "./controller.js";
+export { AgentController, agentId, type AgentContextEntry, type AgentCustomItem, type AgentControllerOptions, type AgentSnapshot, type AgentSuggestion, type AgentThread, type SendOptions, } from "./controller.js";
 export { createDirectEngine, type AgentEngine, type EngineRunInput, type ToolInvoker, } from "./engine.js";
 export { defineTool, isStandardSchema, toolJsonSchema, toolResultText, toolStandardSchema, validateToolArgs, type AgentTool, type AgentToolContext, type AgentToolRenderProps, type JsonSchema, type StandardSchemaV1, } from "./tool.js";
 export { CalliopeAgentProvider, useAgentController, useAgentReadable, useAgentSuggestions, useAgentTool, useCalliopeAgent, type CalliopeAgentApi, type CalliopeAgentOptions, type CalliopeAgentProviderProps, } from "./AgentProvider.js";
-export { createMockAgent, textEvents, toolCallEvents, type MockAgentOptions, type MockTurn, } from "./mock.js";
+export { createFunctionAgent, createMockAgent, type AgentRunFunction, type FunctionAgentOptions, textEvents, toolCallEvents, type MockAgentOptions, type MockTurn, } from "./mock.js";
 export { AgentChat, NewConversationButton, type AgentChatProps } from "./AgentChat.js";
 export { AgentLauncher, type AgentLauncherProps } from "./AgentLauncher.js";
 export { CalliopeAgent, type CalliopeAgentMode, type CalliopeAgentProps } from "./CalliopeAgent.js";
 export { shortcutLabel, useMediaQuery, useOpenState, useShortcut } from "./surface.js";
+export { mergeRenderers, parseResult, type AgentRenderers, type CustomRendererProps, type InterruptRendererProps, type StateRendererProps, type ToolRendererProps, } from "./renderers.js";
+export { ArtifactReviewCard, InterruptCard, QuestionInterruptCard, RunProgressCard, workflowRenderers, type ArtifactReviewValue, type ArtifactValue, type QuestionInterruptMetadata, type RunProgressValue, } from "./WorkflowRenderers.js";

package/dist/agent/index.js

@@ -8,8 +8,10 @@ export { AgentController, agentId, } from "./controller.js";
 export { createDirectEngine, } from "./engine.js";
 export { defineTool, isStandardSchema, toolJsonSchema, toolResultText, toolStandardSchema, validateToolArgs, } from "./tool.js";
 export { CalliopeAgentProvider, useAgentController, useAgentReadable, useAgentSuggestions, useAgentTool, useCalliopeAgent, } from "./AgentProvider.js";
-export { createMockAgent, textEvents, toolCallEvents, } from "./mock.js";
+export { createFunctionAgent, createMockAgent, textEvents, toolCallEvents, } from "./mock.js";
 export { AgentChat, NewConversationButton } from "./AgentChat.js";
 export { AgentLauncher } from "./AgentLauncher.js";
 export { CalliopeAgent } from "./CalliopeAgent.js";
 export { shortcutLabel, useMediaQuery, useOpenState, useShortcut } from "./surface.js";
+export { mergeRenderers, parseResult, } from "./renderers.js";
+export { ArtifactReviewCard, InterruptCard, QuestionInterruptCard, RunProgressCard, workflowRenderers, } from "./WorkflowRenderers.js";