@pgege/kaboo-react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,557 @@
+import { a as KabooInterruptHandlerProps, I as InterruptReason, A as ActivityState, D as DrillState, S as StreamGroup, T as ToolCall, b as InterruptRendererProps, c as TimelineEntry } from './KabooInterruptHandler-BO2Uv3gS.cjs';
+export { d as ApprovalReason, F as FormQuestion, e as FormReason, f as InterruptData } from './KabooInterruptHandler-BO2Uv3gS.cjs';
+import * as react from 'react';
+import { ReactElement, ReactNode } from 'react';
+import { CopilotKitProps } from '@copilotkit/react-core/v2';
+
+/**
+ * A map of custom renderers for structured agent output, keyed by the output
+ * schema name. When a group carries `structuredOutput` and a matching
+ * `outputSchemaName`, its renderer is used instead of the default JSON view.
+ *
+ * @example
+ * ```tsx
+ * import type { StructuredRenderers } from "@pgege/kaboo-react";
+ *
+ * const renderers: StructuredRenderers = {
+ *   WeatherReport: (data) => <div>{String(data.summary)}</div>,
+ * };
+ * ```
+ */
+type StructuredRenderers = Record<string, (data: Record<string, unknown>) => ReactElement>;
+/** React context carrying the {@link StructuredRenderers} map for structured output. */
+declare const StructuredRenderersContext: react.Context<StructuredRenderers>;
+/** Props for {@link KabooActivityProvider}. */
+interface KabooActivityProviderProps {
+    /**
+     * CopilotKit agent id whose activity snapshots to consume. Omit to use the
+     * provider's default agent. Agent and thread scoping come from CopilotKit.
+     */
+    agentId?: string;
+    /** Renderers for structured agent outputs, keyed by output schema name. */
+    structuredRenderers?: StructuredRenderers;
+    /** The subtree that reads activity via {@link useActivity}. */
+    children: ReactNode;
+}
+/**
+ * Reads kaboo's hierarchical activity from the AG-UI run stream. The backend
+ * emits it as `ACTIVITY_SNAPSHOT` events interleaved on `/invocations`, so we
+ * subscribe to the CopilotKit agent instead of a separate SSE endpoint.
+ *
+ * Included automatically by {@link KabooProvider}; mount it yourself only when
+ * composing providers by hand under an existing `<CopilotKit>`.
+ *
+ * @example
+ * ```tsx
+ * import { KabooActivityProvider, ActivityPanel } from "@pgege/kaboo-react";
+ *
+ * function Activity({ agent }: { agent: string }) {
+ *   return (
+ *     <KabooActivityProvider agentId={agent}>
+ *       <ActivityPanel />
+ *     </KabooActivityProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function KabooActivityProvider({ agentId, structuredRenderers, children }: KabooActivityProviderProps): react.JSX.Element;
+
+/**
+ * Provides drill-down navigation state ({@link DrillState}) to the activity
+ * components below it. Included automatically by {@link KabooProvider}; only
+ * mount it yourself if you compose the providers by hand.
+ *
+ * @example
+ * ```tsx
+ * import { DrillProvider, GlassTabs, DrillDetailView } from "@pgege/kaboo-react";
+ *
+ * function Panel() {
+ *   return (
+ *     <DrillProvider>
+ *       <GlassTabs />
+ *       <DrillDetailView />
+ *     </DrillProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function DrillProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+/** Props for {@link KabooProvider}. */
+interface KabooProviderProps {
+    /** URL of the CopilotKit runtime endpoint (e.g. `/api/copilotkit`). */
+    runtimeUrl: string;
+    /** CopilotKit agent id to run (the workflow entry agent). */
+    agent: string;
+    /** Conversation id. Scopes both the run and its activity. */
+    threadId?: string;
+    /** Renderers for structured agent outputs, keyed by output schema name. */
+    structuredRenderers?: StructuredRenderers;
+    /** Per-interrupt-type renderer overrides for the built-in HITL handler. */
+    interruptRenderers?: KabooInterruptHandlerProps["renderers"];
+    /** Skip auto-mounting the built-in {@link KabooInterruptHandler}. */
+    disableInterruptHandler?: boolean;
+    /** Skip auto-mounting the built-in {@link KabooInlineCards}. */
+    disableInlineCards?: boolean;
+    /** Extra props forwarded to the underlying `<CopilotKit>`. */
+    copilotKitProps?: Partial<Omit<CopilotKitProps, "children" | "runtimeUrl" | "agent" | "threadId">>;
+    /** Your app subtree, rendered inside all kaboo contexts. */
+    children: ReactNode;
+}
+/**
+ * Batteries-included CopilotKit plugin. Renders `<CopilotKit>` and nests every
+ * kaboo context (activity -> drill -> interrupt bridge) plus the built-in HITL
+ * and inline-card handlers, so integrators drop this once near the root and use
+ * only kaboo-react. Activity rides the AG-UI run stream, so there is no separate
+ * activity endpoint to configure.
+ *
+ * @example
+ * ```tsx
+ * import { CopilotChat } from "@copilotkit/react-core/v2";
+ * import { KabooProvider, GlassTabs, DrillDetailView } from "@pgege/kaboo-react";
+ * import { KabooMessageView } from "@pgege/kaboo-react/copilotkit";
+ * import "@pgege/kaboo-react/styles.css";
+ *
+ * function App({ agent, threadId }: { agent: string; threadId: string }) {
+ *   return (
+ *     <KabooProvider runtimeUrl="/api/copilotkit" agent={agent} threadId={threadId}>
+ *       <GlassTabs />
+ *       <CopilotChat messageView={KabooMessageView} />
+ *       <DrillDetailView />
+ *     </KabooProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function KabooProvider({ runtimeUrl, agent, threadId, structuredRenderers, interruptRenderers, disableInterruptHandler, disableInlineCards, copilotKitProps, children, }: KabooProviderProps): react.JSX.Element;
+
+/**
+ * An open interrupt published onto the InterruptBridge so an owning agent card
+ * can render its prompt inline (rather than only in the chat slot). Carries the
+ * reason plus resolve/cancel callbacks bound to this specific interrupt id.
+ */
+interface ActiveInterrupt {
+    /**
+     * Unique interrupt id (from the AG-UI interrupt). Distinguishes concurrent
+     * gates that may share a single tool-call id (e.g. two parallel sub-agent
+     * gates re-keyed onto one delegating call), so each resolves independently.
+     */
+    id: string;
+    /** Why the run paused, and what input it needs. */
+    reason: InterruptReason;
+    /** Resume the run with the user's answer/approval payload. */
+    onResolve: (payload: unknown) => void;
+    /** Cancel/reject this gate, resuming the run without a positive answer. */
+    onCancel: () => void;
+    /**
+     * The originating tool-call id, when the interrupt was raised by a tool (e.g.
+     * `ask_user` or a gated tool). Lets the owning agent card render the live
+     * prompt inline at its tool-call position, so the prompt sits in chronological
+     * order rather than in a separate top-level slot.
+     */
+    toolCallId?: string;
+}
+/**
+ * Holds the set of currently open interrupts so any tool row can claim and
+ * render its own gate inline (see {@link useInterruptFor}). Included
+ * automatically by {@link KabooProvider}.
+ *
+ * @example
+ * ```tsx
+ * import { InterruptBridgeProvider } from "@pgege/kaboo-react";
+ *
+ * function Providers({ children }: { children: React.ReactNode }) {
+ *   return <InterruptBridgeProvider>{children}</InterruptBridgeProvider>;
+ * }
+ * ```
+ */
+declare function InterruptBridgeProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * Reads the InterruptBridge: the list of open interrupts plus `publish`. Most
+ * consumers want {@link useInterruptFor} instead; use this to inspect or drive
+ * the whole set.
+ *
+ * @example
+ * ```tsx
+ * import { useInterruptBridge } from "@pgege/kaboo-react";
+ *
+ * function OpenGateCount() {
+ *   const { active } = useInterruptBridge();
+ *   return <span>{active.length} open</span>;
+ * }
+ * ```
+ */
+declare function useInterruptBridge(): {
+    /** Every open interrupt from the current run, in emission order. */
+    active: ActiveInterrupt[];
+    /** Replace the set of interrupts published to the bridge. */
+    publish: (interrupts: ActiveInterrupt[]) => void;
+};
+/**
+ * The first open interrupt anchored to a given tool-call id, or `undefined`.
+ * Lets a tool row claim and render its own gate inline while N concurrent gates
+ * are open, each anchored to a distinct tool call.
+ */
+declare function useInterruptFor(toolCallId: string | undefined): ActiveInterrupt | undefined;
+/**
+ * Publishes the current set of open interrupts to the bridge so each owning
+ * agent card can render its prompt inline at the matching tool-call position.
+ * CopilotKit surfaces every open interrupt at once, so this takes the full list
+ * and keeps the latest resolve/cancel callbacks in a ref — their per-render
+ * identity churn must not re-publish (only the interrupt set should).
+ */
+declare function InterruptBridgePublisher({ interrupts, }: {
+    interrupts: ActiveInterrupt[];
+}): null;
+
+/**
+ * Reads the current {@link ActivityState} (all activity groups for the thread)
+ * from the nearest {@link KabooActivityProvider}. Re-renders on each new
+ * `ACTIVITY_SNAPSHOT`.
+ *
+ * @example
+ * ```tsx
+ * import { useActivity } from "@pgege/kaboo-react";
+ *
+ * function GroupCount() {
+ *   const { groups } = useActivity();
+ *   return <span>{Object.keys(groups).length} agents</span>;
+ * }
+ * ```
+ */
+declare function useActivity(): ActivityState;
+
+/**
+ * Reads the drill-down navigation state ({@link DrillState}) from the nearest
+ * {@link DrillProvider}: the current path plus `drillIn`/`drillUp`/`drillToRoot`/
+ * `drillToLevel`.
+ *
+ * @example
+ * ```tsx
+ * import { useDrill } from "@pgege/kaboo-react";
+ *
+ * function BackButton() {
+ *   const { drillUp, activeDrill } = useDrill();
+ *   if (!activeDrill) return null;
+ *   return <button onClick={drillUp}>Back</button>;
+ * }
+ * ```
+ */
+declare function useDrill(): DrillState;
+
+/** A `[groupId, group]` pair, as returned by the group-hierarchy helpers. */
+type GroupEntry = [string, StreamGroup];
+/**
+ * Top-level groups are those without a parent. Uses the explicit
+ * `parentGroup` field rather than parsing dot-paths out of the group id, so
+ * group names are free to contain any characters.
+ *
+ * @example
+ * ```ts
+ * import { topLevelGroups } from "@pgege/kaboo-react";
+ *
+ * function rootCount(groups: Parameters<typeof topLevelGroups>[0]) {
+ *   return topLevelGroups(groups).length;
+ * }
+ * ```
+ */
+declare function topLevelGroups(groups: Record<string, StreamGroup>): GroupEntry[];
+/**
+ * Direct children of `parentId` (one level deep) via the `parentGroup` field.
+ *
+ * @example
+ * ```ts
+ * import { directChildren } from "@pgege/kaboo-react";
+ *
+ * function childCount(
+ *   groups: Parameters<typeof directChildren>[0],
+ *   parentId: string,
+ * ) {
+ *   return directChildren(groups, parentId).length;
+ * }
+ * ```
+ */
+declare function directChildren(groups: Record<string, StreamGroup>, parentId: string): GroupEntry[];
+
+/**
+ * Standalone panel that renders the current activity tree as a list of
+ * {@link AgentCard}s — top-level groups at the root, or the drilled-in group's
+ * children. Use it when you want the hierarchical activity view outside the chat
+ * transcript (the in-chat view is handled by `KabooMessageView`). Renders
+ * nothing when there is no activity.
+ *
+ * @example
+ * ```tsx
+ * import { ActivityPanel } from "@pgege/kaboo-react";
+ *
+ * function Sidebar() {
+ *   return (
+ *     <aside>
+ *       <ActivityPanel />
+ *     </aside>
+ *   );
+ * }
+ * ```
+ */
+declare function ActivityPanel(): react.JSX.Element | null;
+
+/** Props for {@link AgentCard}. */
+interface AgentCardProps {
+    /** Id of the group this card renders. */
+    groupId: string;
+    /** The activity group to render. */
+    group: StreamGroup;
+    /** Task/input text to show, overriding the group's own `task`. */
+    input?: string;
+    /** Raw tool result to render as the card's answer, when provided by the host. */
+    result?: string;
+    /** Host-provided action status (e.g. `"complete"`) used to mark the card done. */
+    actionStatus?: string;
+    /**
+     * When true, the card renders its `directChildren` inline as nested
+     * {@link AgentCard}s (recursively). Used by the first-class swarm/graph inline
+     * renderer to show the whole member tree without the drill navigation. Left
+     * off (default) for the delegate path and the drill views, which surface
+     * children through their own navigation.
+     */
+    showChildren?: boolean;
+}
+/**
+ * Card for a single agent run: title, status badge, task, chronological timeline
+ * (text + tool rows), result/structured output, and a "View details" drill
+ * button. Delegated sub-agents are interleaved at their tool-call position; with
+ * `showChildren` the card renders its whole child tree inline.
+ *
+ * @example
+ * ```tsx
+ * import { AgentCard, useActivity } from "@pgege/kaboo-react";
+ *
+ * function FirstCard() {
+ *   const { groups } = useActivity();
+ *   const [id, group] = Object.entries(groups)[0] ?? [];
+ *   return id ? <AgentCard groupId={id} group={group} /> : null;
+ * }
+ * ```
+ */
+declare function AgentCard({ groupId, group, input, result, actionStatus, showChildren }: AgentCardProps): react.JSX.Element;
+
+/**
+ * Renders a single {@link ToolCall} as a collapsible row: status icon, label, an
+ * input summary, and — when expanded — the formatted result (a {@link MiniTable}
+ * for tabular JSON, otherwise text). Used inside the {@link Timeline}.
+ *
+ * @example
+ * ```tsx
+ * import { ToolRow } from "@pgege/kaboo-react";
+ * import type { ToolCall } from "@pgege/kaboo-react";
+ *
+ * const tool: ToolCall = {
+ *   toolUseId: "t1",
+ *   toolName: "run_sql",
+ *   toolInput: { query: "select 1" },
+ *   status: "done",
+ * };
+ *
+ * function Example() {
+ *   return <ToolRow tool={tool} />;
+ * }
+ * ```
+ */
+declare function ToolRow({ tool }: {
+    tool: ToolCall;
+}): react.JSX.Element;
+
+/**
+ * Compact table for row-shaped tool results. Columns are inferred from the first
+ * row's keys; underscores in headers become spaces. Renders at most `maxRows`
+ * rows with a "+N more" footer, and nothing at all for an empty list.
+ *
+ * @example
+ * ```tsx
+ * import { MiniTable } from "@pgege/kaboo-react";
+ *
+ * function Example() {
+ *   return <MiniTable rows={[{ id: "1", name: "Ada" }]} maxRows={5} />;
+ * }
+ * ```
+ */
+declare function MiniTable({ rows, maxRows }: {
+    rows: Record<string, string>[];
+    maxRows?: number;
+}): react.JSX.Element | null;
+
+/**
+ * Breadcrumb navigation for the drill-down path: a "Chat" root followed by one
+ * crumb per drilled-in group. Clicking a crumb jumps to that level; the current
+ * (last) crumb is disabled. Renders nothing at the root. Pair with
+ * {@link DrillDetailView}.
+ *
+ * @example
+ * ```tsx
+ * import { GlassTabs, DrillDetailView } from "@pgege/kaboo-react";
+ *
+ * function DrillArea() {
+ *   return (
+ *     <>
+ *       <GlassTabs />
+ *       <DrillDetailView />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function GlassTabs(): react.JSX.Element | null;
+
+/**
+ * Detail pane for the currently drilled-in group: its task, full timeline
+ * (with delegated sub-agents interleaved at their tool-call position), any
+ * unanchored interrupt prompts, and a "Sub-agents" section for swarm/graph
+ * members. Renders a hidden placeholder at the root. Pair with {@link GlassTabs}.
+ *
+ * @example
+ * ```tsx
+ * import { GlassTabs, DrillDetailView } from "@pgege/kaboo-react";
+ *
+ * function DrillArea() {
+ *   return (
+ *     <>
+ *       <GlassTabs />
+ *       <DrillDetailView />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function DrillDetailView(): react.JSX.Element;
+
+/**
+ * Minimal, dependency-free markdown renderer used for agent text: supports
+ * `#`/`##`/`###` headings, `-`/`*` list items, `**bold**` inline, and blank-line
+ * spacing. Intentionally small — it is not a full CommonMark implementation.
+ *
+ * @example
+ * ```tsx
+ * import { MarkdownContent } from "@pgege/kaboo-react";
+ *
+ * function Example() {
+ *   return <MarkdownContent text={"# Title\n\nSome **bold** text."} />;
+ * }
+ * ```
+ */
+declare function MarkdownContent({ text }: {
+    text: string;
+}): react.JSX.Element;
+
+/**
+ * Default human-in-the-loop interrupt UI. Renders an Approve/Reject panel for an
+ * {@link ApprovalReason} and a (optionally multi-step) form with radio/checkbox/
+ * text inputs for a {@link FormReason}, calling `onResolve`/`onCancel` with the
+ * answer payload. Override per type via `interruptRenderers` on
+ * {@link KabooProvider}.
+ *
+ * @example
+ * ```tsx
+ * import { InterruptRenderer } from "@pgege/kaboo-react";
+ * import type { InterruptReason } from "@pgege/kaboo-react";
+ *
+ * const reason: InterruptReason = {
+ *   type: "approval",
+ *   message: "Run this query?",
+ *   tool_name: "run_sql",
+ * };
+ *
+ * function Example() {
+ *   return (
+ *     <InterruptRenderer
+ *       reason={reason}
+ *       onResolve={() => {}}
+ *       onCancel={() => {}}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function InterruptRenderer(props: InterruptRendererProps): ReactElement;
+
+/** Props for {@link Timeline}. */
+interface TimelineProps {
+    /** The interleaved text/tool entries to render, in order. */
+    timeline: TimelineEntry[];
+    /** When true, a blinking cursor is shown after the last text segment. */
+    active: boolean;
+    /** Visual variant selecting the text container class. */
+    variant?: "card" | "drill";
+    /**
+     * Optional hook to render a delegating tool call as its spawned sub-agent
+     * card, interleaved at its chronological position. Returns the card node for a
+     * given tool-call id, or `null`/`undefined` to fall back to the tool row. Keeps
+     * a delegated agent's work in order relative to the parent's surrounding text.
+     */
+    renderToolCard?: (toolUseId: string) => ReactNode | null | undefined;
+}
+/**
+ * Chronological render of interleaved text segments and tool calls. Shared by
+ * {@link AgentCard} and {@link DrillDetailView} so the two stay in sync.
+ */
+declare function Timeline({ timeline, active, variant, renderToolCard }: TimelineProps): react.JSX.Element;
+
+/**
+ * Condenses arbitrary tool input into a short one-line `summary` for a tool row.
+ * Prefers well-known fields (`query`/`table_name`/`url`), unwraps single-key
+ * objects, and otherwise joins `key: value` pairs. `detail` is reserved for
+ * future expansion and is currently always `null`.
+ *
+ * @example
+ * ```ts
+ * import { formatToolInput } from "@pgege/kaboo-react";
+ *
+ * const { summary } = formatToolInput({ query: "select 1" });
+ * // summary === "select 1"
+ * ```
+ */
+declare function formatToolInput(input: unknown): {
+    /** One-line summary suitable for a tool row. */
+    summary: string;
+    /** Reserved for future detail expansion; currently always `null`. */
+    detail: string | null;
+};
+
+/**
+ * Parses a raw tool result into a renderable shape: `rows` (for tabular JSON —
+ * either `{ rows: [...] }` or a top-level array of objects) or `text` (a
+ * `key: value` rendering of an object, or the raw string when it isn't JSON).
+ *
+ * @example
+ * ```ts
+ * import { formatToolResult } from "@pgege/kaboo-react";
+ *
+ * const { rows } = formatToolResult('{"rows":[{"id":"1"}]}');
+ * // rows?.length === 1
+ * ```
+ */
+declare function formatToolResult(raw: string): {
+    /** Row-shaped result for a table view, or `null` when not tabular. */
+    rows: Record<string, string>[] | null;
+    /** Text rendering of the result when it is not tabular. */
+    text: string;
+};
+/**
+ * Normalizes a raw result string for display: unwraps one layer of JSON string
+ * encoding, converts escaped `\n` into real newlines, and returns `null` for
+ * empty/undefined input.
+ *
+ * @example
+ * ```ts
+ * import { normalizeResult } from "@pgege/kaboo-react";
+ *
+ * normalizeResult('"line one\\nline two"');
+ * // "line one\nline two"
+ * ```
+ */
+declare function normalizeResult(result: string | undefined): string | null;
+
+export { type ActiveInterrupt, ActivityPanel, ActivityState, AgentCard, type AgentCardProps, DrillDetailView, DrillProvider, DrillState, GlassTabs, type GroupEntry, InterruptBridgeProvider, InterruptBridgePublisher, InterruptReason, InterruptRenderer, InterruptRendererProps, KabooActivityProvider, type KabooActivityProviderProps, KabooProvider, type KabooProviderProps, MarkdownContent, MiniTable, StreamGroup, type StructuredRenderers, StructuredRenderersContext, Timeline, TimelineEntry, type TimelineProps, ToolCall, ToolRow, directChildren, formatToolInput, formatToolResult, normalizeResult, topLevelGroups, useActivity, useDrill, useInterruptBridge, useInterruptFor };