@pgege/kaboo-react 0.1.0

package/AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md
+
+Guidance for AI agents contributing to **kaboo-react**. Humans: see
+[CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Commands
+
+```bash
+corepack enable            # once; Yarn 4 is pinned via packageManager
+yarn install --immutable   # install
+yarn build                 # tsup -> dist/ (both barrels + styles.css)
+yarn test                  # vitest run
+yarn typecheck             # tsc --noEmit (src, excludes tests)
+yarn docs:api              # typedoc + regenerate docs/api-inventory.md (completeness gate)
+yarn docs:verify           # type-check every tsx/ts snippet in README + docs
+yarn docs:llms             # regenerate llms.txt + llms-full.txt
+yarn examples:typecheck    # type-check examples/ against built types
+```
+
+`prepack` runs build + docs:api + docs:llms + docs:verify + test (fires on
+`yarn pack` and `yarn npm publish`).
+
+## Architecture & conventions
+
+- **Two barrels.**
+  - `kaboo-react` (`src/index.ts`) — framework-agnostic contexts, hooks,
+    components, utils, formatters, types.
+  - `@pgege/kaboo-react/copilotkit` (`src/copilotkit.ts`) — integrations coupled to
+    CopilotKit. **Put any CopilotKit-dependent code here, never in the main
+    barrel.**
+- **Stylesheet.** `src/styles.css` is copied to `dist/styles.css` by tsup and
+  exported as `@pgege/kaboo-react/styles.css`. Theming is via CSS variables only
+  (`--background`/`--foreground`/`--card`/`--muted`/`--border` + `--kaboo-*`
+  overrides). Do not add a CSS-in-JS dependency.
+- **Peer deps.** `react`, `react-dom`, `@copilotkit/react-core`. Do not add
+  runtime dependencies without discussion.
+- **CopilotChat slots** each integration targets:
+  - `KabooMessageView` → the `messageView` slot (carries a `Cursor` static so it
+    is a drop-in slot component).
+  - `KabooAssistantMessage` → the assistant-message slot (used by
+    `KabooMessageView`).
+  - `KabooInlineCards`, `KabooInterruptHandler` → auto-mounted by `KabooProvider`.
+
+## Playbooks
+
+### Add a component or hook
+
+1. Implement it under `src/` (main-barrel code) or `src/integrations/`
+   (CopilotKit-coupled → `copilotkit` barrel).
+2. Add a TSDoc description **and at least one `@example`** (`tsx` for
+   components/providers, `ts` for utils/formatters). The completeness gate fails
+   on any undocumented export.
+3. Export it from the correct barrel (`src/index.ts` or `src/copilotkit.ts`).
+4. Add a test under the same folder (`*.test.tsx`), following the existing
+   `vi.hoisted` + `vi.mock("@copilotkit/react-core/v2", …)` pattern.
+5. Run `yarn docs:api` (regenerates `docs/api` + `docs/api-inventory.md`).
+
+### Add a guide
+
+1. Create `docs/<name>.md`. Every `tsx`/`ts` fence must be self-contained and
+   type-check under `docs:verify` (tag illustrative fragments ```` ```tsx no-verify ````).
+2. Add it to `mkdocs.yml` nav **and** to the `NAV` list in
+   `scripts/generate-llms.mjs` (same order).
+3. Run `yarn docs:verify` and `yarn docs:llms`.
+
+### Add an example
+
+1. Create `examples/<name>/` with `package.json`, `tsconfig.json` (map
+   `kaboo-react` → `../../dist`), `README.md`, and `src/`.
+2. If a guide/README snippet copies from it, wrap the region with
+   `// #region <name>` / `// #endregion` and reference it with
+   `<!-- source: examples/<name>/src/File.tsx#<name> -->` above the fence.
+3. Run `yarn build && yarn examples:typecheck`.
+
+## Definition of done
+
+- `yarn test` green.
+- `yarn docs:api` passes the TypeDoc completeness gate across **both** barrels
+  and produces no `docs/api` / `docs/api-inventory.md` drift.
+- `yarn docs:verify` green.
+- `yarn docs:llms` produces no `llms.txt` / `llms-full.txt` drift.
+- `yarn examples:typecheck` green.
+- `mkdocs build --strict` green.
+- `yarn pack --dry-run` clean (both barrels + `styles.css` resolve).
+
+## Guardrails
+
+- Never add an undocumented public export.
+- Never add an unverified `tsx`/`ts` snippet to the docs.
+- Never point URLs at the old `kaboo/kaboo-workflows` monorepo path — use
+  `gl-pgege/kaboo-react`.
+- Never plan or run a live publish; the deliverable is a dry run + the publish
+  command for a human to run.
+
+## Related
+
+- [kaboo-workflows](https://github.com/gl-pgege/kaboo-workflows)
+- [kaboo-runtime](https://github.com/gl-pgege/kaboo-runtime)
+- [kaboo-workflows-demo](https://github.com/gl-pgege/kaboo-docs/tree/main/examples/kaboo-workflows-demo) — the
+  runnable, end-to-end reference that consumes this library.
+- [The kaboo stack](https://gl-pgege.github.io/kaboo-docs/) — umbrella landing.

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+
+- `kaboo-react` main barrel: `KabooProvider` (batteries-included CopilotKit
+  plugin), `KabooActivityProvider`, `DrillProvider`, `InterruptBridgeProvider`,
+  hooks (`useActivity`, `useDrill`, `useInterruptBridge`, `useInterruptFor`),
+  activity components (`ActivityPanel`, `AgentCard`, `Timeline`, `ToolRow`,
+  `MiniTable`, `GlassTabs`, `DrillDetailView`, `MarkdownContent`,
+  `InterruptRenderer`), group helpers (`topLevelGroups`, `directChildren`) and
+  formatters (`formatToolInput`, `formatToolResult`, `normalizeResult`).
+- `@pgege/kaboo-react/copilotkit` subpath: CopilotKit-coupled integrations
+  (`KabooMessageView`, `KabooAssistantMessage`, `KabooInlineCards`,
+  `KabooInterruptHandler`, `KabooAskUser`, `KabooToolRender`).
+- `@pgege/kaboo-react/styles.css` stylesheet with themeable `--kaboo-*` design tokens.
+
+[Unreleased]: https://github.com/gl-pgege/kaboo-react/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/gl-pgege/kaboo-react/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gl-pgege
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# kaboo-react
+
+> React components + hooks for rendering kaboo multi-agent activity in a
+> [CopilotKit](https://copilotkit.ai) app, with batteries-included CopilotKit
+> integrations.
+
+[![npm version](https://img.shields.io/npm/v/kaboo-react.svg)](https://www.npmjs.com/package/kaboo-react)
+[![license](https://img.shields.io/npm/l/kaboo-react.svg)](./LICENSE)
+[![docs](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://gl-pgege.github.io/kaboo-react/)
+[![CI](https://github.com/gl-pgege/kaboo-react/actions/workflows/ci.yml/badge.svg)](https://github.com/gl-pgege/kaboo-react/actions/workflows/ci.yml)
+
+kaboo-react renders a live, hierarchical view of what your agents are doing —
+sub-agent cards, tool calls, streamed tokens, structured outputs, drill-down
+navigation, and human-in-the-loop interrupts. Activity rides the **same AG-UI run
+stream** as the chat (as `ACTIVITY_SNAPSHOT` events), so there is no separate
+endpoint to wire up: kaboo-react is a batteries-included CopilotKit plugin.
+
+## Features
+
+- **Live hierarchical activity** — nested agent/tool cards that stream in as work
+  happens, inside the chat transcript.
+- **Drill-down navigation** — breadcrumb + detail view to explore any sub-agent.
+- **Human-in-the-loop** — approval gates and forms, with N parallel interrupts
+  resolved independently.
+- **Structured renderers** — plug custom UI for schema-shaped agent output.
+- **Batteries included** — one `KabooProvider` renders `<CopilotKit>` and mounts
+  every context and handler for you.
+- **Themeable** — styled with CSS variables and `--kaboo-*` tokens.
+
+## Install
+
+```bash
+yarn add @pgege/kaboo-react
+```
+
+Peer dependencies: `react`, `react-dom`, and `@copilotkit/react-core` (>= 1.62).
+
+Import the stylesheet once, near your app root:
+
+```ts
+import "@pgege/kaboo-react/styles.css";
+```
+
+## Quick start
+
+`KabooProvider` renders `<CopilotKit>` for you and mounts every kaboo context and
+handler inside it. Give it the runtime URL, the entry agent, and a thread id —
+then drop in the components.
+
+<!-- source: examples/minimal/src/App.tsx#quickstart -->
+```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";
+
+export function App({ agent, threadId }: { agent: string; threadId: string }) {
+  return (
+    <KabooProvider runtimeUrl="/api/copilotkit" agent={agent} threadId={threadId}>
+      <GlassTabs />
+      <CopilotChat messageView={KabooMessageView} />
+      <DrillDetailView />
+    </KabooProvider>
+  );
+}
+```
+
+That's it — `KabooProvider` nests the three contexts (`KabooActivityProvider`,
+`DrillProvider`, `InterruptBridgeProvider`) plus the built-in `KabooInlineCards`
+and `KabooInterruptHandler`. Disable the auto-mounted handlers with
+`disableInlineCards` / `disableInterruptHandler`, and forward extra CopilotKit
+props via `copilotKitProps`.
+
+## Core concepts
+
+- **Activity rides the run stream.** The backend emits activity as
+  `ACTIVITY_SNAPSHOT` events on the same AG-UI run stream as the chat, so there is
+  no separate activity endpoint. `KabooActivityProvider` subscribes to the
+  CopilotKit agent and exposes it via `useActivity()`.
+- **Providers nest under `KabooProvider`.** Activity → drill → interrupt bridge,
+  with the built-in handlers mounted inside.
+- **Two barrels.** Import framework-agnostic pieces from `kaboo-react`, and the
+  CopilotKit-coupled integrations from `@pgege/kaboo-react/copilotkit`.
+- **The `threadId` scopes everything.** Each conversation gets its own
+  hierarchical activity view automatically.
+- **Theming via CSS variables.** Components read standard design-system tokens and
+  accept `--kaboo-*` overrides.
+
+## Guides
+
+- [Getting started](./docs/getting-started.md)
+- [Theming](./docs/theming.md)
+- [Structured renderers](./docs/structured-renderers.md)
+- [Human-in-the-loop](./docs/hitl.md)
+- [Activity panel & drill-down](./docs/activity-panel.md)
+- [The `@pgege/kaboo-react/copilotkit` subpath](./docs/copilotkit-subpath.md)
+
+## API reference
+
+Full, auto-generated API docs for both barrels live on the
+[documentation site](https://gl-pgege.github.io/kaboo-react/api/). A flat index
+of every public export is in [docs/api-inventory.md](./docs/api-inventory.md).
+
+## Examples
+
+- [`examples/minimal`](./examples/minimal) — the smallest end-to-end wiring
+  (this README's quick start).
+- The [kaboo-workflows-demo](https://github.com/gl-pgege/kaboo-docs/tree/main/examples/kaboo-workflows-demo)
+  frontend is the canonical, production-shaped consumer.
+
+## Compatibility & versioning
+
+- **React** 18 and 19 (`react` / `react-dom` >= 18 as peer deps).
+- **CopilotKit** `@copilotkit/react-core` >= 1.62 (peer dep).
+- Follows [semantic versioning](https://semver.org). See
+  [CHANGELOG.md](./CHANGELOG.md).
+
+## The kaboo stack
+
+kaboo-react is one of three libraries:
+
+- [kaboo-workflows](https://github.com/gl-pgege/kaboo-workflows) — Python
+  multi-agent orchestration.
+- [kaboo-runtime](https://github.com/gl-pgege/kaboo-runtime) — CopilotKit runtime
+  persistence/orchestration plugin.
+- **kaboo-react** — this library, the UI layer.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) (humans) and [AGENTS.md](./AGENTS.md)
+(AI contributors).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/KabooInterruptHandler-BO2Uv3gS.d.cts

@@ -0,0 +1,226 @@
+import { ReactElement } from 'react';
+
+/**
+ * A single tool invocation captured within an agent's activity group. One
+ * `ToolCall` maps to one AG-UI tool-call and carries enough state to render the
+ * live tool row, its input summary, and its result (or cancellation).
+ */
+interface ToolCall {
+    /** AG-UI tool-call id. Stable key used to correlate rows, cards, and gates. */
+    toolUseId: string;
+    /** The tool's machine name (e.g. `run_sql`, `ask_user`). */
+    toolName: string;
+    /** Optional human-friendly label shown instead of `toolName`. */
+    toolLabel?: string;
+    /** The raw tool input (arbitrary JSON), summarized by the formatters. */
+    toolInput?: unknown;
+    /** The raw tool result, if the call has completed. */
+    toolResult?: string;
+    /** Lifecycle state of the call, driving the row's icon and status text. */
+    status: "running" | "done" | "success" | "error" | "cancelled";
+}
+/**
+ * One chronological entry in an agent's timeline: either a streamed text segment
+ * or a tool call, interleaved in the order they occurred.
+ */
+type TimelineEntry = {
+    /** Discriminator: a streamed text segment. */
+    type: "text";
+    /** The streamed text for this segment. */
+    text: string;
+} | {
+    /** Discriminator: a tool call. */
+    type: "tool";
+    /** The tool call for this entry. */
+    tool: ToolCall;
+};
+/**
+ * A single question in a human-in-the-loop form interrupt. `type` selects the
+ * input control; `options` supplies the choices for `radio`/`checkbox`.
+ */
+interface FormQuestion {
+    /** The prompt text shown to the user. */
+    question: string;
+    /** Which input control to render for this question. */
+    type: "radio" | "checkbox" | "text";
+    /** Selectable choices for `radio`/`checkbox` questions. */
+    options?: string[];
+}
+/**
+ * An approval interrupt: the agent is asking the user to approve or reject a
+ * gated tool call before it runs.
+ */
+interface ApprovalReason {
+    /** Discriminator marking this as an approval gate. */
+    type: "approval";
+    /** Human-readable description of what is being approved. */
+    message: string;
+    /** Name of the gated tool awaiting approval. */
+    tool_name: string;
+    /** The proposed tool input, shown for review. */
+    tool_input?: unknown;
+}
+/**
+ * A form interrupt: the agent is asking the user one or more questions and
+ * waiting for the answers before it continues.
+ */
+interface FormReason {
+    /** Discriminator marking this as a form prompt. */
+    type: "form";
+    /** The questions to present, rendered in order. */
+    questions: FormQuestion[];
+}
+/**
+ * The reason a run paused for human input — either an {@link ApprovalReason}
+ * (approve/reject a gated tool) or a {@link FormReason} (answer questions).
+ */
+type InterruptReason = ApprovalReason | FormReason;
+/**
+ * A single open interrupt from the AG-UI run, as delivered by CopilotKit.
+ * Multiple can be open at once (e.g. parallel gates); each is resolved by `id`.
+ */
+interface InterruptData {
+    /** Unique interrupt id, used to resolve this gate independently. */
+    id: string;
+    /** The interrupt's name (typically the originating tool name). */
+    name: string;
+    /** Why the run paused, and what input it needs. */
+    reason: InterruptReason;
+}
+/**
+ * Props for a custom interrupt renderer supplied via `interruptRenderers`.
+ * Receives the reason plus resolve/cancel callbacks so a bespoke UI can drive
+ * the gate.
+ */
+interface InterruptRendererProps {
+    /** 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 the gate, resuming the run without a positive answer. */
+    onCancel: () => void;
+    /**
+     * The interrupt's originating tool-call id, when available. Used to correlate
+     * the answered form with the durable tool-call card that renders the Q&A
+     * inline in the transcript.
+     */
+    toolCallId?: string;
+}
+/**
+ * One node of kaboo's hierarchical activity tree: a single agent run and its
+ * streamed text, tool calls, timeline, structured output, and (optional)
+ * open interrupt. Groups nest via {@link StreamGroup.parentGroup} to form the
+ * drill-down hierarchy.
+ */
+interface StreamGroup {
+    /** Display title for the group's card. */
+    title: string;
+    /** The agent's machine name (used to correlate inline cards). */
+    agentName: string;
+    /** Parent group id, or `null` for a top-level group. */
+    parentGroup: string | null;
+    /**
+     * The delegating tool-call id (AG-UI `toolCallId`) that spawned this group.
+     * Stable key for correlating an inline chat card with its activity group.
+     * `null`/absent for the entry agent and non-delegated groups.
+     */
+    toolCallId?: string | null;
+    /**
+     * The AG-UI `runId` of the turn that produced this group. `null`/absent for
+     * older streams. Note: an interrupt/resume changes the `runId` mid-turn, so
+     * prefer {@link StreamGroup.turnId} for turn scoping.
+     */
+    runId?: string | null;
+    /**
+     * The logical turn that produced this group — stable across an
+     * interrupt/resume (server-stamped). All groups of one user turn share it, so
+     * the UI can bind them to that turn's single chat reply without fragmenting
+     * on `runId`. `null`/absent for older streams.
+     */
+    turnId?: string | null;
+    /**
+     * The task this agent was handed (its latest human/handoff message), shown at
+     * the top of the card so you can see what each agent was asked to do.
+     */
+    task?: string | null;
+    /**
+     * True when this agent's streamed text IS the chat reply (the swarm/graph
+     * `chat_output`, or a delegate manager). Inline cards suppress only this
+     * group's text so the answer isn't duplicated between the card and the bubble.
+     */
+    isChatReply?: boolean;
+    /**
+     * True for a plain-agent entry group: its text and tool calls are already
+     * rendered inline in the chat by the host (CopilotKit), so this group exists
+     * only to enrich those tool rows (labels, formatted results, error status)
+     * and must never be drawn as its own card.
+     */
+    inlineChatOwner?: boolean;
+    /** Lifecycle state of the group's run. */
+    status: "active" | "completed" | "error" | "interrupted";
+    /** Every tool call made in this group, in call order. */
+    tools: ToolCall[];
+    /** Accumulated streamed text tokens for this group. */
+    tokens: string;
+    /** Interleaved text/tool entries in chronological order. */
+    timeline: TimelineEntry[];
+    /** The open interrupt for this group, when it is paused for input. */
+    interrupt?: InterruptData;
+    /** Structured (schema-shaped) output emitted by the agent, if any. */
+    structuredOutput?: Record<string, unknown>;
+    /** Name of the schema for {@link StreamGroup.structuredOutput}, selecting a renderer. */
+    outputSchemaName?: string;
+}
+/**
+ * The full activity snapshot for a conversation: every {@link StreamGroup}
+ * keyed by group id. This is what {@link useActivity} exposes.
+ */
+interface ActivityState {
+    /** All activity groups for the current thread, keyed by group id. */
+    groups: Record<string, StreamGroup>;
+}
+/**
+ * Drill-down navigation state: the current path into the activity tree plus the
+ * actions to move through it. Exposed by {@link useDrill}.
+ */
+interface DrillState {
+    /** Group ids from root to the current level. */
+    drillPath: string[];
+    /** The deepest group id in the path, or `null` at the root. */
+    activeDrill: string | null;
+    /** Push a group id, descending one level. */
+    drillIn: (groupId: string) => void;
+    /** Pop the last group id, ascending one level. */
+    drillUp: () => void;
+    /** Clear the path, returning to the root. */
+    drillToRoot: () => void;
+    /** Trim the path to `level` (0-based), jumping to a breadcrumb. */
+    drillToLevel: (level: number) => void;
+}
+
+/** Props for {@link KabooInterruptHandler}. */
+interface KabooInterruptHandlerProps {
+    /** Restrict handling to a single CopilotKit agent (optional). */
+    agentId?: string;
+    /** Per-interrupt-type renderer overrides. */
+    renderers?: Partial<Record<InterruptReason["type"], React.ComponentType<InterruptRendererProps>>>;
+    /**
+     * Also publish the active interrupts to the InterruptBridge so each renders
+     * inside the drill-down detail view (not just the chat). Defaults to `true`;
+     * requires an `InterruptBridgeProvider` (included in `KabooProvider`).
+     */
+    bridge?: boolean;
+}
+/**
+ * Ready-made human-in-the-loop interrupt handler. CopilotKit surfaces every open
+ * interrupt of a run at once (e.g. two gated tools called in parallel); we render
+ * one card per interrupt and resolve each independently by its own id. The client
+ * accumulates the per-id responses and only resumes the run once every open
+ * interrupt has been answered — so resolving with `intr.id` (never the bare
+ * `resolve()`, which would only ever answer the first) is what keeps N parallel
+ * gates from wedging. Prompts anchored to an on-screen tool render inline at that
+ * tool's position; the rest fall back to the chat slot.
+ */
+declare function KabooInterruptHandler({ agentId, renderers, bridge, }: KabooInterruptHandlerProps): ReactElement | null;
+
+export { type ActivityState as A, type DrillState as D, type FormQuestion as F, type InterruptReason as I, KabooInterruptHandler as K, type StreamGroup as S, type ToolCall as T, type KabooInterruptHandlerProps as a, type InterruptRendererProps as b, type TimelineEntry as c, type ApprovalReason as d, type FormReason as e, type InterruptData as f };