@calliopelabs/ui 0.13.0 → 0.16.0

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;

package/dist/agent/CalliopeAgent.js

@@ -0,0 +1,111 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { useProduct } from "../appearance/AppearanceProvider.js";
+import { cn } from "../lib/cn.js";
+import { Drawer, DrawerContent, DrawerTitle } from "../overlays/Drawer.js";
+import { useUI } from "../provider/UIProvider.js";
+import { useRailPlacement } from "../shell/placement.js";
+import { RailPanel } from "../shell/RailPanel.js";
+import { AgentChat, NewConversationButton } from "./AgentChat.js";
+import { AgentLauncher } from "./AgentLauncher.js";
+import { useAgentController } from "./AgentProvider.js";
+import { useMediaQuery, useOpenState, useShortcut } from "./surface.js";
+/**
+ * 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 function CalliopeAgent({ mode, open: openProp, defaultOpen, onOpenChange, persistKey, shortcut = "mod+/", launcherIcon, hideLauncher = false, railWidth = 380, onRailWidthChange, expanded, onExpandedChange, hideHeader, title, className, ...chat }) {
+    const controller = useAgentController();
+    if (!controller) {
+        throw new Error("CalliopeAgent needs CalliopeAgentProvider or CopilotKitAgentProvider above it.");
+    }
+    const { messages } = useUI();
+    const product = useProduct();
+    const name = title ?? messages.agent.title(product?.name);
+    const floating = mode === "bubble" || mode === "rail";
+    const [open, setStoredOpen] = useOpenState({
+        ...(openProp !== undefined ? { open: openProp } : {}),
+        defaultOpen: defaultOpen ?? !floating,
+        ...(onOpenChange ? { onOpenChange } : {}),
+        ...(persistKey ? { persistKey } : {}),
+    });
+    // The composer takes focus when the person opens the assistant, never on a page load that restores it open.
+    const [focusComposer, setFocusComposer] = React.useState(false);
+    const setOpen = React.useCallback((next) => {
+        setFocusComposer(next);
+        setStoredOpen(next);
+    }, [setStoredOpen]);
+    const shown = !floating || open;
+    React.useEffect(() => controller.setVisible(shown), [controller, shown]);
+    useShortcut(floating ? shortcut : false, () => setOpen(!open));
+    const unread = React.useSyncExternalStore(controller.subscribe, () => controller.getSnapshot().unread, () => 0);
+    const panelId = React.useId();
+    const launcher = React.useRef(null);
+    const refocus = React.useRef(false);
+    const close = () => {
+        refocus.current = true;
+        setOpen(false);
+    };
+    // Closing from inside the panel hands focus back to the launcher once it is back.
+    React.useEffect(() => {
+        if (open || !refocus.current)
+            return;
+        refocus.current = false;
+        launcher.current?.focus();
+    }, [open]);
+    if (mode === "inline" || mode === "page") {
+        return (_jsx(AgentChat, { ...chat, title: name, hideHeader: hideHeader ?? mode === "inline", progress: chat.progress ?? (mode === "page" ? "steps" : "line"), className: cn(mode === "inline" ? "h-full rounded-lg border" : "mx-auto h-full w-full max-w-3xl", className) }));
+    }
+    const launcherButton = !hideLauncher && !open ? (_jsx(AgentLauncher, { ref: launcher, open: open, onOpenChange: setOpen, title: name, unread: unread, controls: panelId, shortcut: shortcut, icon: launcherIcon, className: "fixed right-4 bottom-4 z-40" })) : null;
+    if (mode === "rail") {
+        return (_jsx(RailSurface, { id: panelId, name: name, open: open, onClose: close, railWidth: railWidth, onRailWidthChange: onRailWidthChange, expanded: expanded, onExpandedChange: onExpandedChange, launcher: launcherButton, className: className, chat: { ...chat, autoFocus: chat.autoFocus ?? focusComposer } }));
+    }
+    return (_jsx(BubbleSurface, { id: panelId, name: name, open: open, onOpenChange: setOpen, onClose: close, launcher: launcherButton, className: className, chat: { ...chat, autoFocus: chat.autoFocus ?? focusComposer } }));
+}
+function RailSurface({ id, name, open, onClose, railWidth, onRailWidthChange, expanded, onExpandedChange, launcher, className, chat, }) {
+    const inDrawer = useRailPlacement() === "drawer";
+    return (_jsxs(_Fragment, { children: [_jsx(RailPanel, { label: name, collapsed: !open, onCollapsedChange: (collapsed) => (collapsed ? onClose() : undefined), collapsedMode: "hidden", actions: chat.hideNewConversation ? undefined : (_jsx(NewConversationButton, { className: "text-sidebar-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-foreground" })), width: railWidth, minWidth: 300, maxWidth: 720, ...(onRailWidthChange ? { onWidthChange: onRailWidthChange } : {}), expanded: expanded ?? false, ...(onExpandedChange ? { onExpandedChange } : {}), className: className, children: _jsx("div", { id: id, className: "flex h-full min-h-0 flex-col", children: _jsx(AgentChat, { ...chat, title: name, hideHeader: true, 
+                        // eslint-disable-next-line jsx-a11y/no-autofocus -- the person just opened the assistant to type
+                        autoFocus: chat.autoFocus, className: "min-h-0 flex-1" }) }) }), !inDrawer && launcher] }));
+}
+function BubbleSurface({ id, name, open, onOpenChange, onClose, launcher, className, chat, }) {
+    const wide = useMediaQuery("(min-width: 640px)");
+    const panel = React.useRef(null);
+    // A non-modal dialog closes on Escape (WAI-ARIA dialog pattern): from inside it, or from
+    // nowhere in particular (focus left on the page after a chip it held went away).
+    const latestClose = React.useRef(onClose);
+    React.useEffect(() => {
+        latestClose.current = onClose;
+    });
+    React.useEffect(() => {
+        if (!open || !wide)
+            return;
+        const onKey = (event) => {
+            if (event.key !== "Escape" || event.defaultPrevented)
+                return;
+            const target = event.target instanceof Node ? event.target : null;
+            const inside = target !== null && panel.current?.contains(target);
+            if (!inside && target !== document.body)
+                return;
+            // A confirm dialog inside handles its own Escape.
+            if (target instanceof Element &&
+                target.closest("[role='alertdialog'], [role='dialog'][aria-modal='true']"))
+                return;
+            event.preventDefault();
+            latestClose.current();
+        };
+        document.addEventListener("keydown", onKey);
+        return () => document.removeEventListener("keydown", onKey);
+    }, [open, wide]);
+    if (!wide) {
+        return (_jsxs(_Fragment, { children: [launcher, _jsx(Drawer, { open: open, onOpenChange: onOpenChange, children: _jsxs(DrawerContent, { side: "bottom", hideCloseButton: true, "aria-describedby": undefined, className: "h-dvh max-h-dvh gap-0 p-0", children: [_jsx(DrawerTitle, { className: "sr-only", children: name }), _jsx(AgentChat, { ...chat, title: name, onClose: onClose, className: "min-h-0 flex-1" })] }) })] }));
+    }
+    return (_jsxs(_Fragment, { children: [launcher, open && (_jsx("div", { id: id, role: "dialog", "aria-modal": "false", "aria-label": name, "data-slot": "agent-bubble", ref: panel, className: cn("fixed right-4 bottom-4 z-40 flex h-[min(40rem,calc(100dvh-2rem))] w-[min(26rem,calc(100vw-2rem))] flex-col overflow-hidden rounded-lg border bg-card shadow-xl", className), children: _jsx(AgentChat, { ...chat, title: name, 
+                    // eslint-disable-next-line jsx-a11y/no-autofocus -- the person just opened the assistant to type
+                    autoFocus: chat.autoFocus, onClose: onClose, className: "min-h-0 flex-1" }) }))] }));
+}

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

@@ -0,0 +1,167 @@
+/**
+ * The agent controller: one conversation with one AG-UI agent, as a store a
+ * React hook reads. It folds every event the agent emits into the chat kit's
+ * `ChatView` (the same reducer every chat surface reads), and owns what the
+ * person does: send, stop, regenerate, approve or deny, answer a tool that
+ * waits on them, edit the shared state, switch threads. The engine does the
+ * running; the controller never touches the network itself.
+ */
+import type { AbstractAgent } from "@ag-ui/client";
+import { type InputContent, type Message } from "@ag-ui/core";
+import { type AgUiEvent, type ChatToolCall, type ChatView } from "../chat/model.js";
+import type { AgentEngine, ToolInvoker } from "./engine.js";
+import { type AgentTool } from "./tool.js";
+/** A prompt offered as a chip: the title shown, the message sent. */
+export interface AgentSuggestion {
+    title: string;
+    message: string;
+}
+/** Something the agent should know about the page: a readable. */
+export interface AgentContextEntry {
+    /** What it is, for the agent ("The open project"). */
+    description: string;
+    /** Sent as JSON text unless it is a string. */
+    value: unknown;
+}
+/** A saved conversation, as a host's history endpoint returns it. */
+export interface AgentThread {
+    messages: Message[];
+    state?: unknown;
+}
+export interface AgentControllerOptions {
+    /** Sent with every run: the model picked, the page. */
+    forwardedProps?: () => Record<string, unknown> | undefined;
+    /** Loads a thread's history on `switchThread`. Without it a switched-to thread starts empty. */
+    loadThread?: (threadId: string) => Promise<AgentThread> | AgentThread;
+    /** A run that failed (also shown in the conversation). */
+    onError?: (error: unknown) => void;
+    /** 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. */
+    running: boolean;
+    /** Tool calls waiting on the person (human-in-the-loop tools), by id. */
+    waiting: readonly string[];
+    threadId: string;
+    /** Answers that finished while the surface was not visible. */
+    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). */
+    parts?: readonly InputContent[];
+}
+type Listener = () => void;
+/** An id unique in this page: crypto when there is one, a counter otherwise. */
+export declare function agentId(prefix?: string): string;
+export declare class AgentController {
+    private options;
+    private engine;
+    private unsubscribe;
+    private listeners;
+    private view;
+    private running;
+    private runSeq;
+    private tools;
+    private toolOrder;
+    private context;
+    private suggestionSets;
+    private waiting;
+    private executing;
+    private failed;
+    private decisions;
+    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;
+    /** Set by stop until the next run: a stopped run's late events (its abort error) are dropped. */
+    private halted;
+    constructor(createEngine: (invoke: ToolInvoker) => AgentEngine, options?: AgentControllerOptions);
+    /**
+     * Starts reading the agent's events; returns the disconnect, which stops a
+     * run in flight. Called from an effect, so nothing subscribes on the server
+     * and a StrictMode remount reconnects cleanly.
+     */
+    connect(): () => void;
+    get agent(): AbstractAgent;
+    setOptions(options: AgentControllerOptions): void;
+    /** Swaps the engine (CopilotKit hands over a new agent once its runtime connects). */
+    attach(createEngine: (invoke: ToolInvoker) => AgentEngine): void;
+    subscribe: (listener: Listener) => (() => void);
+    getSnapshot: () => AgentSnapshot;
+    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;
+    private fold;
+    /** Tool results the agent's messages gained outside the event stream: the browser's own tools. */
+    private syncResults;
+    private invoke;
+    private run;
+    /** Answers every interrupt still open as cancelled, so a new message can start a run. */
+    private cancelOpen;
+    /** Sends the person's message and runs the agent. Ignored while a run is in flight. */
+    send: (text: string, options?: SendOptions) => Promise<void>;
+    /** Stops the run in flight and any tool waiting on the person. */
+    stop: () => void;
+    /** Drops the answer to the last message and asks again. */
+    regenerate: () => Promise<void>;
+    /**
+     * Answers one interrupt. When every open interrupt has an answer, the run
+     * resumes with them (AG-UI `resume`).
+     */
+    resolveInterrupt: (interruptId: string, response: {
+        status: "resolved";
+        payload?: unknown;
+    } | {
+        status: "cancelled";
+    }) => void;
+    /** Approves a tool call the run paused on. */
+    approve: (call: ChatToolCall, payload?: Record<string, unknown>) => void;
+    /** Denies it, with the person's reason. */
+    deny: (call: ChatToolCall, reason: string) => void;
+    /** Answers a human-in-the-loop tool call: the result goes back to the agent. */
+    respond: (toolCallId: string, result: unknown) => void;
+    getState: <T = unknown>() => T;
+    /** Replaces the shared state: the next run sends it, and the view shows it now. */
+    setState: (state: unknown) => void;
+    registerTool: <Args>(given: AgentTool<Args>) => (() => void);
+    private syncTools;
+    addContext: (entry: AgentContextEntry) => (() => void);
+    private syncContext;
+    addSuggestions: (suggestions: readonly AgentSuggestion[]) => (() => void);
+    /** Opens another conversation: stops this one, loads the other's history. */
+    switchThread: (threadId: string) => Promise<void>;
+    /** Starts a new, empty conversation and returns its id. */
+    newThread: () => Promise<string>;
+    /** Whether the person can see the conversation: answers that land while hidden count as unread. */
+    setVisible: (visible: boolean) => void;
+    dispose(): void;
+}
+export {};