@alexkroman1/aai-ui 0.12.3 → 0.13.0

package/dist/define-client.js

@@ -1,74 +1,220 @@
-import { ClientConfigProvider } from "./client-context.js";
-import { SessionProvider, createSessionControls } from "./signals.js";
-import { t as createVoiceSession } from "./session-CWB7vmqz.js";
-import { render } from "preact";
-import { batch, signal } from "@preact/signals";
-import { jsx } from "preact/jsx-runtime";
-//#region define-client.tsx
+import { t as ChatView } from "./chat-view-BCbI7gD4.js";
+import { n as pageBaseUrl, r as setPageTitle } from "./_utils-Mi-SCFA1.js";
+import { n as fetchClientConfig } from "./client-config-C7fQrioM.js";
+import { t as createBrowserSession } from "./session-CE0Ipsb3.js";
+import { SessionProvider, ThemeProvider } from "./context.js";
+import { t as ToolConfigContext } from "./tool-config-context-Es4YUzV2.js";
+import { SidebarLayout } from "./components/sidebar-layout.js";
+import { StartScreen } from "./components/start-screen.js";
+import { createElement, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+//#region src/define-client.tsx
+/** @jsxImportSource react */
+/**
+* The element a mount renders into.
+*
+* Exported so `mountPage()` resolves its target the same way `mountClient()` does — the
+* default selector and the "element not found" sentence are part of what an
+* author has learned, and a second copy is how the two mounts come to disagree
+* about which one they were given.
+*
+* @internal
+*/
 function resolveContainer(target = "#app") {
 	if (typeof target !== "string") return target;
 	const el = document.querySelector(target);
-	if (!el) throw new Error(`Element not found: ${target}`);
+	if (!el) throw new Error(`Element not found: ${target} — no element matches that selector when the mount runs. Add \`<div id="app"></div>\` (or the element your selector names) to the page before the script, or pass the element itself as the mount's \`target\` option.`);
 	return el;
 }
 /**
+* Render `node` into `container` and hand back its teardown.
+*
+* Shared by {@link mountClient} and `mountPage()` because the plumbing is identical and
+* the two decisions in it are not obvious enough to be re-derived: the root is
+* created here rather than by the caller so nothing else can hold one, and the
+* render is `flushSync` so the mount is observable to the caller's NEXT
+* STATEMENT (and to a test) rather than scheduled — `mountClient()` returns a handle
+* whose session is expected to be live, and `mountPage()` returns one a caller may
+* dispose immediately.
+*
+* `onDispose` runs after the unmount, which is the order `mountClient()` needs: the
+* tree comes down before the session under it goes away.
+*
+* @internal
+*/
+function mountRoot(container, node, onDispose) {
+	const root = createRoot(container);
+	flushSync(() => {
+		root.render(node);
+	});
+	return {
+		dispose() {
+			root.unmount();
+			onDispose?.();
+		},
+		[Symbol.dispose]() {
+			this.dispose();
+		}
+	};
+}
+/**
+* Default shell rendered in config tier.
+* Wraps StartScreen → (SidebarLayout →) ChatView.
+*/
+function DefaultShell({ name, icon, subtitle, buttonText, Sidebar, ...layout }) {
+	const chat = /* @__PURE__ */ jsx(ChatView, {
+		title: name,
+		icon
+	});
+	return /* @__PURE__ */ jsx(StartScreen, {
+		title: name,
+		icon,
+		subtitle,
+		buttonText,
+		children: Sidebar ? /* @__PURE__ */ jsx(SidebarLayout, {
+			sidebar: /* @__PURE__ */ jsx(Sidebar, {}),
+			sidebarWidth: layout.sidebarWidth,
+			sidebarPosition: layout.sidebarPosition,
+			children: chat
+		}) : chat
+	});
+}
+/**
+* Config-tier root: fetches the server-declared display name via
+* `GET client-config` and renders the chat shell. The shell renders
+* immediately — optimistically — while the lookup is in flight; servers
+* without the endpoint (every lookup failure resolves to the empty default)
+* work exactly as before.
+*
+* **The lookup is SKIPPED when the caller already named the agent.** The
+* response's only consumer here is the fallback below, so with an explicit
+* `mountClient({ name })` the request was issued and its answer thrown away — and on
+* the platform this endpoint is the BROKER, so the discarded request is one that
+* can boot a sandbox. The session's own per-attempt lookup
+* (`session/browser-session.ts`'s URL provider) is a different question and deliberately
+* left alone: it re-brokers on every connection attempt, which is what makes a
+* reconnect land on a REPLACEMENT sandbox, so it may not be served from
+* anything this render already has.
+*/
+function DefaultRoot({ platformUrl, ...display }) {
+	const { name } = display;
+	const [resolved, setResolved] = useState(null);
+	const needsLookup = name === void 0;
+	useEffect(() => {
+		if (!needsLookup) return;
+		let cancelled = false;
+		fetchClientConfig(platformUrl).then((cfg) => {
+			if (!cancelled) setResolved(cfg);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [platformUrl, needsLookup]);
+	return /* @__PURE__ */ jsx(DefaultShell, {
+		...display,
+		name: name ?? resolved?.name
+	});
+}
+/**
+* The tree under the providers: the caller's component, or the default shell.
+*
+* A custom component owns the whole page, so there is no header to hang a
+* `sidebar` off — but the layout the default shell uses is right here, and
+* `mountClient({ component, sidebar })` names one pane and one aside, which is
+* exactly what it renders. Honouring the combination rather than ignoring it is
+* the same call this file already made for `name` and `tools`.
+*/
+function rootFor(config, platformUrl) {
+	const Custom = config.component;
+	const Sidebar = config.sidebar;
+	if (!Custom) return /* @__PURE__ */ jsx(DefaultRoot, {
+		platformUrl,
+		name: config.name,
+		icon: config.icon,
+		subtitle: config.subtitle,
+		buttonText: config.buttonText,
+		Sidebar,
+		sidebarWidth: config.sidebarWidth,
+		sidebarPosition: config.sidebarPosition
+	});
+	if (!Sidebar) return /* @__PURE__ */ jsx(Custom, {});
+	return /* @__PURE__ */ jsx(SidebarLayout, {
+		sidebar: /* @__PURE__ */ jsx(Sidebar, {}),
+		sidebarWidth: config.sidebarWidth,
+		sidebarPosition: config.sidebarPosition,
+		children: /* @__PURE__ */ jsx(Custom, {})
+	});
+}
+/**
 * Define and mount a client UI for a voice agent.
 *
-* Creates a {@link VoiceSession}, wraps it in
-* {@link SessionSignals}, and renders the component
-* inside a {@link SessionProvider}.
+* **Config only:** leave `component` out and the default shell renders
+* (StartScreen + ChatView, optional sidebar).
+*
+* **A custom component:** pass `component` and it is rendered inside the same
+* providers instead of the default shell — beside a `sidebar` if one is given,
+* in the same {@link SidebarLayout}. A provided `name` then also sets
+* `document.title`, there being no shell header to show it in.
+*
+* Mounts into `target` — a CSS selector or DOM element, defaulting to
+* `"#app"` — and throws `Element not found: <target>` when the selector
+* matches nothing.
+*
+* @example The default shell
+* ```tsx
+* import { mountClient } from "@alexkroman1/aai-ui";
+*
+* function OrderPanel() {
+*   return <div>Cart</div>;
+* }
+*
+* mountClient({
+*   name: "Pizza Ordering",
+*   theme: { bg: "#1a1a1a", primary: "#e55" },
+*   sidebar: OrderPanel,
+*   tools: { add_pizza: { icon: "🍕", label: "Adding pizza" } },
+* });
+* ```
+*
+* @example A custom component
+* ```tsx
+* import { mountClient, useSession } from "@alexkroman1/aai-ui";
+*
+* function MyCustomApp() {
+*   const session = useSession();
+*   return <div>{session.state}</div>;
+* }
+*
+* mountClient({ component: MyCustomApp });
+* ```
 *
-* @param Component - The Preact component to render.
-* @param options - Client options (target element, platform URL, theme).
 * @returns A {@link ClientHandle} for cleanup.
 * @throws If the target element is not found in the DOM.
 *
 * @public
 */
-function defineClient(Component, options) {
-	const container = resolveContainer(options?.target);
-	const session = createVoiceSession({
-		platformUrl: options?.platformUrl ?? globalThis.location.origin + globalThis.location.pathname,
-		reactiveFactory: signal,
-		batch,
-		onSessionId: options?.onSessionId,
-		resumeSessionId: options?.resumeSessionId,
-		...options?.WebSocket ? { WebSocket: options.WebSocket } : {}
+function mountClient(config) {
+	const container = resolveContainer(config.target);
+	const platformUrl = config.platformUrl ?? pageBaseUrl();
+	const session = createBrowserSession({
+		platformUrl,
+		onSessionId: config.onSessionId,
+		resumeSessionId: config.resumeSessionId,
+		location: config.location,
+		phone: config.phone,
+		client: config.client,
+		token: config.token,
+		WebSocket: config.WebSocket
 	});
-	const signals = createSessionControls(session);
-	const clientConfig = {
-		title: options?.title,
-		theme: options?.theme
-	};
-	if (options?.theme) {
-		const t = options.theme;
-		const el = container;
-		if (t.bg) el.style.setProperty("--color-aai-bg", t.bg);
-		if (t.primary) el.style.setProperty("--color-aai-primary", t.primary);
-		if (t.text) el.style.setProperty("--color-aai-text", t.text);
-		if (t.surface) el.style.setProperty("--color-aai-surface", t.surface);
-		if (t.border) el.style.setProperty("--color-aai-border", t.border);
-	}
-	render(/* @__PURE__ */ jsx(ClientConfigProvider, {
-		value: clientConfig,
-		children: /* @__PURE__ */ jsx(SessionProvider, {
-			value: signals,
-			children: /* @__PURE__ */ jsx(Component, {})
-		})
-	}), container);
-	const handle = {
+	setPageTitle(config.name);
+	const rootNode = rootFor(config, platformUrl);
+	const toolConfig = config.tools ?? {};
+	return {
 		session,
-		signals,
-		dispose() {
-			render(null, container);
-			signals.dispose();
-			session.disconnect();
-		},
-		[Symbol.dispose]() {
-			handle.dispose();
-		}
+		...mountRoot(container, createElement(ToolConfigContext.Provider, { value: toolConfig }, createElement(ThemeProvider, { value: config.theme }, createElement(SessionProvider, { value: session }, rootNode))), () => session[Symbol.dispose]())
 	};
-	return handle;
 }
 //#endregion
-export { defineClient };
+export { mountClient, mountRoot, resolveContainer };

package/dist/eyebrow-UfmSz9yy.js

@@ -0,0 +1,27 @@
+import { useTheme } from "./context.js";
+import clsx from "clsx";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/eyebrow.tsx
+/** @jsxImportSource react */
+/**
+* Eyebrow label — the design system's small outlined pill with ALL-CAPS,
+* tracked text ("VOICE AGENT", "LISTENING", …). Used as a section label on
+* the start screen and as the live status chip in the chat header.
+*
+* @internal
+*/
+function Eyebrow({ children, className, style, ...rest }) {
+	const theme = useTheme();
+	return /* @__PURE__ */ jsx("span", {
+		className: clsx("inline-flex items-center gap-1.5 px-2 py-1 rounded-aai border leading-none", "font-aai text-[10px] font-medium tracking-[1.2px] uppercase", className),
+		style: {
+			borderColor: theme.border,
+			color: theme.text,
+			...style
+		},
+		...rest,
+		children
+	});
+}
+//#endregion
+export { Eyebrow as t };

package/dist/hooks-DN4gHYsj.js

@@ -0,0 +1,182 @@
+import { a as tryParseJSON } from "./_utils-Mi-SCFA1.js";
+import { useSessionSelector } from "./context.js";
+import { useEffect, useMemo, useRef } from "react";
+//#region src/agent-state.ts
+/** One stable selector per slot name — see {@link selectAgentState}. */
+const selectors = /* @__PURE__ */ new Map();
+/** The whole frame — module scope, so its identity is stable. */
+const selectFrame = (snapshot) => snapshot.agentState;
+/**
+* A `useSessionSelector` selector for ONE slot of the agent's projected state:
+* its value, or `undefined` before the agent has pushed it.
+*
+* The same function for the same name on every call, which is load-bearing:
+* `useSessionSelector` caches its selection on the selector's identity, and an
+* inline arrow would re-run it on every snapshot.
+*
+* ```tsx
+* import { selectAgentState, useSessionSelector } from "@alexkroman1/aai-ui";
+*
+* function CartBadge() {
+*   // Re-renders when the `cart` slot changes, and on nothing else.
+*   const cart = useSessionSelector(selectAgentState<{ count: number }>("cart"));
+*   return <span>{cart?.count ?? 0}</span>;
+* }
+* ```
+*
+* @public
+*/
+function selectAgentState(slot) {
+	let selector = selectors.get(slot);
+	if (selector === void 0) {
+		selector = (snapshot) => snapshot.agentState?.[slot];
+		selectors.set(slot, selector);
+	}
+	return selector;
+}
+function useAgentState(source, fallback) {
+	const projection = typeof source === "function" ? source : void 0;
+	const slot = projection?.key ?? (typeof source === "string" ? source : void 0);
+	const selected = useSessionSelector(slot === void 0 ? selectFrame : selectAgentState(slot));
+	const empty = useMemo(() => projection?.(), [projection]);
+	if (slot === void 0) return selected ?? null;
+	if (selected !== void 0) return selected;
+	if (projection !== void 0) return empty;
+	return fallback === void 0 ? null : fallback;
+}
+//#endregion
+//#region src/hooks.ts
+/** Index of the first item whose sequence number is above the watermark (tail scan from the end). */
+function tailStart(items, seqOf, watermark) {
+	let start = items.length;
+	for (let i = items.length - 1; i >= 0; i--) {
+		const item = items[i];
+		if (!item || seqOf(item) <= watermark) break;
+		start = i;
+	}
+	return start;
+}
+/**
+* Process the unprocessed tail of `toolCalls`: fire `onNew` once per item that
+* has settled (per `isSettled`), then advance the watermark past the leading
+* run of settled items. Resets the cursor when the list is empty (session
+* reset), matching the previous seen-set behavior.
+*/
+function processToolCallTail(toolCalls, cursor, isSettled, onNew) {
+	if (toolCalls.length === 0) {
+		cursor.seq = 0;
+		cursor.fired.clear();
+		return;
+	}
+	const start = tailStart(toolCalls, (tc) => tc.seq, cursor.seq);
+	for (let i = start; i < toolCalls.length; i++) {
+		const tc = toolCalls[i];
+		if (!(tc && isSettled(tc)) || cursor.fired.has(tc.callId)) continue;
+		cursor.fired.add(tc.callId);
+		onNew(tc);
+	}
+	for (let i = start; i < toolCalls.length; i++) {
+		const tc = toolCalls[i];
+		if (!(tc && isSettled(tc))) break;
+		cursor.fired.delete(tc.callId);
+		cursor.seq = tc.seq;
+	}
+}
+/**
+* The two `fire` implementations, at module scope so they are stable across
+* renders — which is what lets `useToolCallEffect` name `fire` as a plain
+* dependency instead of holding it in a ref.
+*/
+const fireResult = (callback, tc, filtered) => {
+	const parsed = tryParseJSON(tc.result);
+	if (filtered) callback(parsed, tc);
+	else callback(tc.name, parsed, tc);
+};
+const fireStart = (callback, tc) => {
+	callback(tc);
+};
+/**
+* Shared scaffold for the tool-call lifecycle hooks: parses the optional
+* `(toolName, callback)` / `(callback)` overload args, dedups by call ID,
+* and invokes `fire` once per tool call reaching `status`.
+*/
+function useToolCallEffect(status, args, fire) {
+	const first = args[0];
+	const filterName = typeof first === "string" ? first : null;
+	const callback = filterName === null ? first : args[1];
+	const toolCalls = useSessionSelector((s) => s.toolCalls);
+	const cursorRef = useRef({
+		seq: 0,
+		fired: /* @__PURE__ */ new Set()
+	});
+	const mountedRef = useRef(false);
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	useEffect(() => {
+		const firstRun = !mountedRef.current;
+		mountedRef.current = true;
+		processToolCallTail(toolCalls, cursorRef.current, (tc) => status === "pending" || tc.status === status, (tc) => {
+			if (tc.status !== status && firstRun) return;
+			if (filterName && tc.name !== filterName) return;
+			fire(callbackRef.current, tc, filterName !== null);
+		});
+	}, [
+		toolCalls,
+		filterName,
+		status,
+		fire
+	]);
+}
+function useToolResult(...args) {
+	useToolCallEffect("done", args, fireResult);
+}
+/**
+* Subscribe to custom events emitted by agent tools via
+* `ctx.send(event, data)`; the callback receives each event's `data`.
+*
+* This is the preferred way to drive UI from tools — an explicit event beats
+* inferring state from tool results with {@link useToolResult}.
+*
+* @example
+* ```tsx
+* import { useEvent } from "@alexkroman1/aai-ui";
+* import { useState } from "react";
+*
+* type Item = { sku: string; qty: number };
+*
+* function Cart() {
+*   const [cart, setCart] = useState<Item[]>([]);
+*   // Tool: ctx.send("item_added", { sku, qty })
+*   useEvent<Item>("item_added", (data) => {
+*     setCart((cart) => [...cart, data]);
+*   });
+*   return <div>{cart.length} items</div>;
+* }
+* ```
+*
+* @public
+*/
+function useEvent(event, callback) {
+	const customEvents = useSessionSelector((s) => s.customEvents);
+	const watermarkRef = useRef(0);
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	useEffect(() => {
+		if (customEvents.length === 0) {
+			watermarkRef.current = 0;
+			return;
+		}
+		const start = tailStart(customEvents, (ce) => ce.id, watermarkRef.current);
+		for (let i = start; i < customEvents.length; i++) {
+			const ce = customEvents[i];
+			if (!ce) continue;
+			watermarkRef.current = ce.id;
+			if (ce.event === event) callbackRef.current(ce.data);
+		}
+	}, [customEvents, event]);
+}
+function useToolCallStart(...args) {
+	useToolCallEffect("pending", args, fireStart);
+}
+//#endregion
+export { useAgentState as a, selectAgentState as i, useToolCallStart as n, useToolResult as r, useEvent as t };

package/dist/hooks.d.ts

@@ -0,0 +1,172 @@
+import type { ToolCallInfo } from "./types.ts";
+export { selectAgentState, useAgentState } from "./agent-state.ts";
+/**
+ * Fire a callback when ONE named tool settles, with its parsed JSON result.
+ *
+ * For new code prefer explicit events — `ctx.send(event, data)` in the tool
+ * paired with {@link useEvent} here — over listening to tool results.
+ *
+ * A component that mounts late still receives the results of calls that
+ * already completed, because a result is a value the UI is driven from rather
+ * than a moment. Each call fires exactly once per hook instance.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { useToolResult } from "@alexkroman1/aai-ui";
+ *
+ * type Quote = { symbol: string; price: number };
+ *
+ * function QuoteCard() {
+ *   const [quote, setQuote] = useState<Quote>();
+ *   useToolResult<Quote>("get_quote", (result) => setQuote(result));
+ *   return quote ? <p>{quote.symbol}: {quote.price}</p> : null;
+ * }
+ * ```
+ *
+ * @typeParam R - The result shape. Defaults to `unknown`, NOT to
+ *   `DefaultToolResult` (`any`): the return type is inferred perfectly
+ *   at `tool()` and this hook is the one place a client reads it, so an `any`
+ *   default threw the whole inference away exactly where it was wanted —
+ *   `useToolResult("get_order", (r) => r.a.b.c.d.e)` reported nothing. It is
+ *   the tool's own shape that belongs here, and the spelling that costs a
+ *   browser bundle nothing is a TYPE-ONLY import of the tool module:
+ *   `import type getOrder from "./tools/get_order.ts"` is erased, so
+ *   `useToolResult<InferToolOutput<typeof getOrder>>(…)` pulls no host code
+ *   into the client graph. `useToolResult<Quote>(…)` against a hand-written
+ *   shape is the other spelling. `DefaultToolResult` itself stays `any`
+ *   — see `ToolCallInfo.args` for why a value the framework cannot see is
+ *   typed that way at REST; the argument does not extend to a call site whose
+ *   whole job is to name the shape.
+ * @param toolName - Only calls of this tool fire the callback.
+ * @param callback - Called with the parsed result and the call itself.
+ *
+ * @public
+ */
+export declare function useToolResult<R = unknown>(toolName: string, callback: (result: R, toolCall: ToolCallInfo) => void): void;
+/**
+ * Fire a callback when ANY tool call settles — the tool's name is the
+ * callback's first argument.
+ *
+ * The unfiltered form, for a chrome rendering a log of everything the agent
+ * did rather than reacting to one tool.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { useToolResult } from "@alexkroman1/aai-ui";
+ *
+ * function ToolLog() {
+ *   const [lines, setLines] = useState<string[]>([]);
+ *   useToolResult((name, result) => {
+ *     setLines((prev) => [...prev, `${name}: ${JSON.stringify(result)}`]);
+ *   });
+ *   return <pre>{lines.join("\n")}</pre>;
+ * }
+ * ```
+ *
+ * @typeParam R - The result shape. Defaults to `unknown`, for the reason the
+ *   filtered overload's `@typeParam` gives. A log renderer is the one caller
+ *   that legitimately wants no shape, and `unknown` is what it should say:
+ *   `JSON.stringify(result)` takes it unchanged.
+ * @param callback - Called with the tool's name, the parsed result, and the
+ * call itself.
+ *
+ * @public
+ */
+export declare function useToolResult<R = unknown>(callback: (name: string, result: R, toolCall: ToolCallInfo) => void): void;
+/**
+ * Subscribe to custom events emitted by agent tools via
+ * `ctx.send(event, data)`; the callback receives each event's `data`.
+ *
+ * This is the preferred way to drive UI from tools — an explicit event beats
+ * inferring state from tool results with {@link useToolResult}.
+ *
+ * @example
+ * ```tsx
+ * import { useEvent } from "@alexkroman1/aai-ui";
+ * import { useState } from "react";
+ *
+ * type Item = { sku: string; qty: number };
+ *
+ * function Cart() {
+ *   const [cart, setCart] = useState<Item[]>([]);
+ *   // Tool: ctx.send("item_added", { sku, qty })
+ *   useEvent<Item>("item_added", (data) => {
+ *     setCart((cart) => [...cart, data]);
+ *   });
+ *   return <div>{cart.length} items</div>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useEvent<T = unknown>(event: string, callback: (data: T) => void): void;
+/**
+ * Fire a callback when ONE named tool starts, before its result arrives.
+ *
+ * A start is a MOMENT rather than a value, so unlike {@link useToolResult}
+ * this never replays: a component that mounts mid-session learns nothing about
+ * calls that started before it.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { useToolCallStart } from "@alexkroman1/aai-ui";
+ *
+ * function Searching() {
+ *   const [busy, setBusy] = useState(false);
+ *   useToolCallStart("search_catalog", () => setBusy(true));
+ *   return busy ? <p>Searching the catalog…</p> : null;
+ * }
+ * ```
+ *
+ * @typeParam A - The tool's ARGUMENT shape. Defaults to
+ *   `ToolCallInfo["args"]`, which is `Record<string, any>` — so an
+ *   un-parameterized call behaves exactly as it always has, and
+ *   `toolCall.args.totally_made_up_field` still compiles. That default is a
+ *   property of {@link ToolCallInfo} rather than a choice made here (its doc
+ *   carries the argument, and the escape hatch it recommends —
+ *   `args as { url: string }` — is what this type parameter replaces); until
+ *   that field is tightened there is nothing stricter for this hook to fall
+ *   back to. What was missing was any way to opt IN: there was no type
+ *   parameter at all, so a custom client could not check args even when it
+ *   knew the shape. Name it — `useToolCallStart<{ query: string }>(…)` — or
+ *   derive it from the tool with a TYPE-ONLY import, which is erased and so
+ *   pulls no host code into the browser graph:
+ *   `useToolCallStart<InferToolInput<typeof search>>("search", …)`.
+ * @param toolName - Only calls of this tool fire the callback.
+ * @param callback - Called with the pending call.
+ *
+ * @public
+ */
+export declare function useToolCallStart<A = ToolCallInfo["args"]>(toolName: string, callback: (toolCall: Omit<ToolCallInfo, "args"> & {
+    args: A;
+}) => void): void;
+/**
+ * Fire a callback when ANY tool call starts — read the tool's name off the
+ * call itself (`toolCall.name`).
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { useToolCallStart } from "@alexkroman1/aai-ui";
+ *
+ * function Activity() {
+ *   const [now, setNow] = useState<string>();
+ *   useToolCallStart((toolCall) => setNow(toolCall.name));
+ *   return now ? <p>Running {now}…</p> : null;
+ * }
+ * ```
+ *
+ * @typeParam A - The tool's ARGUMENT shape; see the filtered overload. On the
+ *   unfiltered form every tool's call arrives, so naming one shape here is
+ *   only right for a page that switches on `toolCall.name` and narrows it
+ *   itself — the default is the honest answer for a log renderer.
+ * @param callback - Called with the pending call.
+ *
+ * @public
+ */
+export declare function useToolCallStart<A = ToolCallInfo["args"]>(callback: (toolCall: Omit<ToolCallInfo, "args"> & {
+    args: A;
+}) => void): void;

package/dist/hooks.js

@@ -0,0 +1,3 @@
+import "./context.js";
+import { a as useAgentState, i as selectAgentState, n as useToolCallStart, r as useToolResult, t as useEvent } from "./hooks-DN4gHYsj.js";
+export { selectAgentState, useAgentState, useEvent, useToolCallStart, useToolResult };

package/dist/hooks.test-d.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Type-level contract for the four `aai-ui` hooks a custom client is written
+ * against. All four are generic, all four are typed BY THE CALLER, and every
+ * one of them was unpinned — the root guide claimed `aai-ui` (`.`) had
+ * type-level coverage and no `.test-d.ts` existed in this package at all.
+ *
+ * The reason these need a type test rather than a runtime one: nothing here
+ * has runtime behaviour to observe. `useAgentState` is one `useSessionSelector`
+ * call over a per-slot selector, and `useToolResult`'s two overloads erase to the same
+ * `(...args: unknown[])` implementation. What a consumer actually depends on
+ * is the SIGNATURE, and a signature is exactly what a runtime suite cannot
+ * assert.
+ */
+export {};