@calliopelabs/ui 0.12.0 → 0.14.0

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/controller.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 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;
+}
+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[];
+}
+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;
+    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 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 {};