@burdenoff/fe-libs 2026.1024.4 → 2026.1027.1

package/dist/credentials/SchemaForm.js

@@ -132,6 +132,7 @@ var l = typeof CSS < "u" && typeof CSS.supports == "function" && CSS.supports("-
 			C,
 			/* @__PURE__ */ c("div", {
 				className: "relative",
+				...u.secret ? { "data-agent-sensitive": "" } : {},
 				children: [/* @__PURE__ */ s("textarea", {
 					id: e,
 					"aria-label": b,
@@ -161,6 +162,7 @@ var l = typeof CSS < "u" && typeof CSS.supports == "function" && CSS.supports("-
 		C,
 		/* @__PURE__ */ c("div", {
 			className: "relative",
+			...u.secret ? { "data-agent-sensitive": "" } : {},
 			children: [/* @__PURE__ */ s("input", {
 				id: e,
 				"aria-label": b,

package/dist/shared/agent-tools/AgentToolsProvider.d.ts

@@ -0,0 +1,33 @@
+import { FC, ReactNode } from 'react';
+export interface AgentToolsProviderProps {
+    /** Product id (the assistant's product namespace), reported by `app_get_context`. */
+    product: string;
+    /** Publish the registered tools to the browser's agent through WebMCP, where available. */
+    webmcp?: boolean;
+    /** Offer `app_get_context`, `app_list_pages`, `app_navigate`, `app_set_theme`. */
+    shellTools?: boolean;
+    /** Offer the generic UI tools (`ui_snapshot`, `ui_click`, `ui_fill`, `ui_select`, `ui_press_key`). */
+    uiTools?: boolean;
+    /** The product's page description (the assistant seam's `gatherPageContext`). */
+    gatherPageContext?: () => Readonly<Record<string, unknown>>;
+    /** In-app navigation. Default: push the path and announce it (`navigateInApp`). */
+    navigate?: (path: string) => void;
+    /** The signed-in person's display name for `app_get_context`. Never pass an email. */
+    userDisplayName?: string | null;
+    children?: ReactNode;
+}
+/**
+ * ★ BOFF-9783: mount once per app shell, inside the shell's providers, to let
+ * AI agents act in the app.
+ *
+ * It registers the shared tools (shell + UI, as switched on), mounts the host
+ * that asks the person to confirm consequential actions, and — when the
+ * browser implements WebMCP and the page is top-level — publishes every
+ * registered tool, the product's own included, to the browser's agent. Where
+ * WebMCP is missing the app is unchanged: tools stay registered for the in-app
+ * assistant, nothing is published.
+ *
+ * Product tools are registered separately, by the components that own them,
+ * with `useAgentTools`.
+ */
+export declare const AgentToolsProvider: FC<AgentToolsProviderProps>;

package/dist/shared/agent-tools/AgentToolsProvider.js

@@ -0,0 +1,48 @@
+import { useActiveContextOrNull as e } from "../providers/shell/ActiveContextProvider.js";
+import { useThemeOrNull as t } from "../providers/shell/ThemeProvider.js";
+import { navigateInApp as n } from "../navigation/inAppPath.js";
+import { navDestinations as r } from "../assistant/localUiCommands.js";
+import { useVisibleNavItems as i } from "../../chrome/mobileTabBar/useVisibleNavItems.js";
+import { useAgentTools as a } from "./useAgentTools.js";
+import { AgentConfirmHost as o } from "./confirm/AgentConfirmHost.js";
+import { getWebMcpModelContext as s, startWebMcpBridge as c } from "./adapters/webmcp.js";
+import { createShellTools as l } from "./shell/shellTools.js";
+import { createUiTools as u } from "./ui/uiTools.js";
+import { useEffect as d, useMemo as f, useRef as p } from "react";
+import { Fragment as m, jsx as h, jsxs as g } from "react/jsx-runtime";
+//#region src/shared/agent-tools/AgentToolsProvider.tsx
+var _ = ({ product: _, webmcp: y = !0, shellTools: b = !0, uiTools: x = !0, gatherPageContext: S, navigate: C, userDisplayName: w = null, children: T }) => {
+	let E = e(), D = t(), { items: O, permissionsSettled: k, simulating: A } = i(), j = k && !A, M = p(null), N = {
+		product: _,
+		organizationId: E?.organizationId ?? null,
+		workspaceId: E?.workspaceId ?? null,
+		projectId: E?.projectId ?? null,
+		userDisplayName: w,
+		pageContext: () => v(S),
+		destinations: j ? r(O) : [],
+		navigationReady: j,
+		navigate: C ?? ((e) => void n(e)),
+		themeMode: D?.mode ?? null,
+		setThemeMode: D ? (e) => D.setMode(e) : null
+	};
+	return d(() => {
+		M.current = N;
+	}), a(f(() => [...b ? l(() => {
+		if (!M.current) throw Error("agent tools source missing");
+		return M.current;
+	}) : [], ...x ? u() : []], [b, x])), d(() => {
+		if (!y) return;
+		let e = s();
+		if (e) return c(e);
+	}, [y]), /* @__PURE__ */ g(m, { children: [T, /* @__PURE__ */ h(o, {})] });
+};
+function v(e) {
+	if (!e) return null;
+	try {
+		return e();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { _ as AgentToolsProvider };

package/dist/shared/agent-tools/adapters/assistant.d.ts

@@ -0,0 +1,85 @@
+import { AgentToolResult, AnyDefinedAgentTool } from '../types';
+/**
+ * ★ BOFF-9786: the in-app assistant's channel to the page's agent tools
+ * ("browser tools").
+ *
+ * The assistant's agent runs in a sandbox, not in this tab. To act in the
+ * page it runs a helper that mints a call; the sandbox binds the call to this
+ * person's session and lists it on `GET /sessions/:id/messages` as
+ * `clientToolRequests`. The panel hands that list to a turn's
+ * `ClientToolRunner`, which runs each call ONCE through `runAgentTool` — the
+ * same validation, confirmation, cancellation and output cap WebMCP uses —
+ * and posts the result back. The agent never sees anything the tool did not
+ * return.
+ */
+/** One tool as the prompt body's `clientTools` manifest describes it. */
+export interface ClientToolManifestEntry {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: {
+        readOnly: boolean;
+        untrustedContent: boolean;
+        consequential: boolean;
+    };
+}
+/** The sandbox refuses a larger manifest whole; stay well inside it. */
+export declare const CLIENT_TOOL_MANIFEST_MAX_BYTES: number;
+/** The sandbox's tool-count cap (ai-assistant `MANIFEST_MAX_TOOLS`). */
+export declare const CLIENT_TOOL_MANIFEST_MAX_TOOLS = 48;
+/**
+ * The tools this turn offers: the registered tools that fit the manifest cap,
+ * and the manifest itself. The runner may run ONLY these definitions, so a
+ * turn never invokes a tool it did not advertise (one the cap left out, or a
+ * page's replacement registered after the prompt was sent).
+ */
+export interface ClientToolOffer {
+    tools: readonly AnyDefinedAgentTool[];
+    manifest: ClientToolManifestEntry[];
+}
+export declare function offerClientTools(tools?: readonly AnyDefinedAgentTool[]): ClientToolOffer;
+/**
+ * The tools registered right now, as the prompt's `clientTools`. Product tools
+ * come first, then the shared ones (`app_`, `ui_`), so if the cap is reached
+ * the generic tools are the ones left out. Empty when nothing is registered.
+ */
+export declare function buildClientToolManifest(tools?: readonly AnyDefinedAgentTool[]): ClientToolManifestEntry[];
+/** One call as `clientToolRequests` lists it. */
+export interface ClientToolRequest {
+    callId: string;
+    tool: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Polls stop when a turn ends however it ends (done, stopped, an error the
+ * loop throws). A call still running this long after the last poll has nobody
+ * listening for its result: it is cancelled, closing any open confirmation.
+ */
+export declare const CLIENT_TOOL_ORPHAN_MS = 20000;
+/** The well-formed entries of an untrusted `clientToolRequests` value. */
+export declare function parseClientToolRequests(raw: unknown): ClientToolRequest[];
+export interface ClientToolRunnerOptions {
+    /** The definitions this turn advertised (`offerClientTools().tools`). */
+    tools: readonly AnyDefinedAgentTool[];
+    /** Post one result to the sandbox. Rejects when the post did not land. */
+    post: (callId: string, result: AgentToolResult) => Promise<void>;
+    /** Shown in the chat while a tool runs ("Using: Read a run"), cleared with null. */
+    onActivity?: (title: string | null) => void;
+    /** Clock and timer seams for tests. */
+    now?: () => number;
+    orphanMs?: number;
+}
+export interface ClientToolRunner {
+    /** The `clientToolRequests` of one poll. New calls start; vanished ones are cancelled. */
+    receive: (raw: unknown) => void;
+    /** The turn is over: cancel everything still running. Idempotent. */
+    dispose: () => void;
+}
+/**
+ * One runner per assistant turn. Each call runs at most once, however many
+ * polls list it; a call the sandbox stops listing (its helper ended — the turn
+ * was stopped, or it timed out) is cancelled, which also closes a pending
+ * confirmation.
+ */
+export declare function createClientToolRunner(options: ClientToolRunnerOptions): ClientToolRunner;

package/dist/shared/agent-tools/adapters/assistant.js

@@ -0,0 +1,110 @@
+import { agentToolFailure as e } from "../errors.js";
+import { logAgentToolProblem as t } from "../log.js";
+import { getAgentTool as n, listAgentTools as r } from "../registry.js";
+import { runAgentTool as i } from "../runAgentTool.js";
+//#region src/shared/agent-tools/adapters/assistant.ts
+var a = 40 * 1024, o = 48, s = new TextEncoder();
+function c(e) {
+	let t = e.annotations ?? {};
+	return {
+		name: e.name,
+		title: e.title,
+		description: e.description,
+		inputSchema: e.inputSchema,
+		annotations: {
+			readOnly: t.readOnly === !0,
+			untrustedContent: t.untrustedContent === !0,
+			consequential: t.consequential === !0
+		}
+	};
+}
+function l(e = r()) {
+	let t = u(e), n = new Set(t.map((e) => e.name));
+	return {
+		tools: e.filter((e) => n.has(e.name)),
+		manifest: t
+	};
+}
+function u(e = r()) {
+	let n = (e) => e.startsWith("app_") || e.startsWith("ui_"), i = [...e.filter((e) => !n(e.name)), ...e.filter((e) => n(e.name))], a = [], o = 2;
+	for (let e of i) {
+		let n = c(e), r = s.encode(JSON.stringify(n)).length + 1;
+		if (a.length >= 48 || o + r > 40960) {
+			t("client tool manifest cap reached", { left: e.name });
+			continue;
+		}
+		a.push(n), o += r;
+	}
+	return a;
+}
+var d = /^ct_[0-9a-f]{32}$/, f = 4, p = 2e4;
+function m(e) {
+	if (!Array.isArray(e)) return [];
+	let t = [];
+	for (let n of e.slice(0, f)) {
+		if (typeof n != "object" || !n || Array.isArray(n)) continue;
+		let { callId: e, tool: r, input: i } = n;
+		typeof e != "string" || !d.test(e) || typeof r != "string" || r.length === 0 || r.length > 64 || typeof i != "object" || !i || Array.isArray(i) || t.push({
+			callId: e,
+			tool: r,
+			input: i
+		});
+	}
+	return t;
+}
+function h(r) {
+	let a = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Set(), s = !1, c = r.now ?? Date.now, l = r.orphanMs ?? 2e4, u = c(), d, f = () => {
+		d !== void 0 && clearInterval(d), d = void 0;
+	}, p = () => {
+		d === void 0 && (d = setInterval(() => {
+			if (a.size === 0) return f();
+			if (!(c() - u < l)) {
+				for (let e of a.values()) e.abort();
+				f();
+			}
+		}, Math.max(1e3, Math.floor(l / 4))));
+	}, h = () => {
+		if (!r.onActivity) return;
+		let e = [...a.keys()].map((e) => g.get(e)).filter((e) => typeof e == "string");
+		r.onActivity(e.length > 0 ? e.join(", ") : null);
+	}, g = /* @__PURE__ */ new Map(), _ = async (e, n) => {
+		for (let t = 0; t < 2; t += 1) try {
+			await r.post(e, n);
+			return;
+		} catch {}
+		t("client tool result not delivered", { callId: e });
+	}, v = (t) => {
+		o.add(t.callId);
+		let s = r.tools.find((e) => e.name === t.tool), c = s && n(t.tool) === s ? s : null;
+		if (!c) {
+			_(t.callId, e("NOT_FOUND", `The page does not offer "${t.tool.slice(0, 40)}" right now. It may have changed; use the current browser tools.`, !0));
+			return;
+		}
+		let l = new AbortController();
+		a.set(t.callId, l), g.set(t.callId, c.title), h(), p(), i(c, t.input, {
+			initiator: "assistant",
+			signal: l.signal
+		}).then((e) => {
+			if (!l.signal.aborted) return _(t.callId, e);
+		}).finally(() => {
+			a.delete(t.callId), g.delete(t.callId), h();
+		});
+	};
+	return {
+		receive(e) {
+			if (s) return;
+			u = c();
+			let t = m(e), n = new Set(t.map((e) => e.callId));
+			for (let [e, t] of a) n.has(e) || t.abort();
+			for (let e of t) o.has(e.callId) || v(e);
+		},
+		dispose() {
+			if (!s) {
+				s = !0, f();
+				for (let e of a.values()) e.abort();
+			}
+		}
+	};
+}
+//#endregion
+export { a as CLIENT_TOOL_MANIFEST_MAX_BYTES, o as CLIENT_TOOL_MANIFEST_MAX_TOOLS, p as CLIENT_TOOL_ORPHAN_MS, u as buildClientToolManifest, h as createClientToolRunner, l as offerClientTools, m as parseClientToolRequests };

package/dist/shared/agent-tools/adapters/webmcp.d.ts

@@ -0,0 +1,69 @@
+import { AnyDefinedAgentTool } from '../types';
+/**
+ * ★ BOFF-9783: publish the registered agent tools to the browser's own agent
+ * through W3C WebMCP — `document.modelContext.registerTool()`, per the Web
+ * Machine Learning CG draft (webmachinelearning.github.io/webmcp, 2026-10-20)
+ * and Chrome's origin-trial implementation (Chrome 149+, Edge 150+).
+ *
+ * The API is experimental: everything here is feature-detected and every call
+ * guarded, so a browser without it — or with an older or newer shape of it —
+ * gets exactly the app it had before.
+ */
+/** The parts of the WebMCP `ModelContext` interface this adapter uses. */
+export interface WebMcpModelContext {
+    registerTool(tool: WebMcpToolDescriptor, options?: WebMcpRegisterToolOptions): Promise<void>;
+}
+export interface WebMcpToolDescriptor {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (input: unknown, options?: {
+        signal?: AbortSignal;
+    }) => Promise<unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        untrustedContentHint?: boolean;
+        consequentialHint?: boolean;
+    };
+}
+export interface WebMcpRegisterToolOptions {
+    signal?: AbortSignal;
+    /**
+     * Origins other than ours allowed to see the tool. ★ Never set: our tools
+     * act with the person's session, and no other site is trusted with that.
+     */
+    exposedTo?: never;
+}
+/** The window members the availability check reads (a seam for tests). */
+export interface WebMcpWindow {
+    isSecureContext: boolean;
+    self: unknown;
+    top: unknown;
+    document: unknown;
+}
+/**
+ * `document.modelContext` when it is usable here, else null.
+ *
+ * ★★ Never inside a frame. The `tools` permission policy only switches the API
+ * off in cross-origin frames by DEFAULT — an embedding page can switch it back
+ * on with `allow="tools"`, and our own `Permissions-Policy: tools=(self)` header
+ * does not prevent that (inside the frame, "self" is us). The app is framable
+ * on purpose in places (the public workflow embed), so the rule is simply: a
+ * framed copy of the app registers nothing.
+ */
+export declare function getWebMcpModelContext(win?: WebMcpWindow | undefined): WebMcpModelContext | null;
+export declare function toWebMcpDescriptor(tool: AnyDefinedAgentTool): WebMcpToolDescriptor;
+/**
+ * Keep `modelContext` in step with the registry until the returned stop
+ * function is called.
+ *
+ * One `AbortController` per published tool: aborting it unregisters the tool
+ * (the spec's cleanup mechanism). Changes to one name are serialised on a
+ * promise chain — abort the old registration, wait for its `registerTool` to
+ * settle, then register the new one — because registering a name that is
+ * still registered rejects with `InvalidStateError`. If that happens anyway
+ * (another copy of the app's code registered it), the adapter retries once on
+ * the next tick and then logs and gives up on that name.
+ */
+export declare function startWebMcpBridge(modelContext: WebMcpModelContext): () => void;

package/dist/shared/agent-tools/adapters/webmcp.js

@@ -0,0 +1,81 @@
+import { logAgentToolProblem as e } from "../log.js";
+import { listAgentTools as t, subscribeAgentTools as n } from "../registry.js";
+import { runAgentTool as r } from "../runAgentTool.js";
+//#region src/shared/agent-tools/adapters/webmcp.ts
+function i(e = typeof window > "u" ? void 0 : window) {
+	if (!e) return null;
+	try {
+		if (!e.isSecureContext || e.top !== e.self) return null;
+		let t = e.document?.modelContext;
+		return !t || typeof t != "object" ? null : typeof t.registerTool == "function" ? t : null;
+	} catch {
+		return null;
+	}
+}
+function a(e) {
+	return !!e && typeof e == "object" && e.name === "InvalidStateError";
+}
+function o(e) {
+	let t = e.annotations ?? {};
+	return {
+		name: e.name,
+		title: e.title,
+		description: e.description,
+		inputSchema: e.inputSchema,
+		execute: (t, n) => r(e, t, {
+			initiator: "webmcp",
+			signal: n?.signal ?? new AbortController().signal
+		}),
+		annotations: {
+			readOnlyHint: t.readOnly === !0,
+			untrustedContentHint: t.untrustedContent === !0,
+			consequentialHint: t.consequential === !0
+		}
+	};
+}
+function s(r) {
+	let i = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Map(), c = !1, l = async (t, n) => {
+		for (let i = 0; i < 2; i += 1) {
+			if (n.aborted || c) return;
+			try {
+				await r.registerTool(o(t), { signal: n });
+				return;
+			} catch (r) {
+				if (n.aborted) return;
+				if (i === 0 && a(r)) {
+					await new Promise((e) => setTimeout(e, 0));
+					continue;
+				}
+				e("WebMCP registerTool failed", {
+					tool: t.name,
+					error: r?.name ?? "unknown"
+				});
+				return;
+			}
+		}
+	}, u = (e, t) => {
+		let n = i.get(e);
+		if (n && (n.controller.abort(), i.delete(e)), !t) return;
+		let r = new AbortController();
+		i.set(e, {
+			tool: t,
+			controller: r
+		});
+		let a = (s.get(e) ?? Promise.resolve()).then(() => l(t, r.signal));
+		s.set(e, a);
+	}, d = () => {
+		if (c) return;
+		let e = new Map(t().map((e) => [e.name, e]));
+		for (let [t, n] of e) i.get(t)?.tool !== n && u(t, n);
+		for (let t of [...i.keys()]) e.has(t) || u(t, null);
+	};
+	d();
+	let f = n(d);
+	return () => {
+		c = !0, f();
+		for (let { controller: e } of i.values()) e.abort();
+		i.clear();
+	};
+}
+//#endregion
+export { i as getWebMcpModelContext, s as startWebMcpBridge, o as toWebMcpDescriptor };

package/dist/shared/agent-tools/confirm/AgentConfirmHost.d.ts

@@ -0,0 +1,12 @@
+import { FC } from 'react';
+/** Test-id prefix of the dialog; UI tools treat it as a deny zone. */
+export declare const AGENT_CONFIRM_TEST_ID_PREFIX = "agent-tool-confirm";
+/**
+ * Shows the confirmation an agent tool is waiting on.
+ *
+ * It reuses the assistant's control confirmation dialog, and with it every rule
+ * that makes a confirmation a person's decision: focus starts on Cancel, Enter
+ * decides nothing, confirm arms only after a delay and counts a trusted press
+ * only. Mounted once, by `AgentToolsProvider`.
+ */
+export declare const AgentConfirmHost: FC;

package/dist/shared/agent-tools/confirm/AgentConfirmHost.js

@@ -0,0 +1,34 @@
+import { useOptionalI18n as e } from "../../providers/shell/I18nProvider.js";
+import { AssistantControlConfirmDialog as t } from "../../assistant/ui/AssistantControlConfirmDialog.js";
+import { currentConfirmation as n, registerConfirmHost as r, settle as i, subscribeConfirmations as a } from "./confirmStore.js";
+import { useCallback as o, useEffect as s, useSyncExternalStore as c } from "react";
+import { jsx as l } from "react/jsx-runtime";
+//#region src/shared/agent-tools/confirm/AgentConfirmHost.tsx
+var u = "agent-tool-confirm", d = () => {
+	let d = e(), p = c(a, n, n);
+	s(() => r(), []);
+	let m = o((e, t, n) => {
+		let r = `agentTools.${e}`, i = d?.t(r, t, n);
+		return i && i !== r ? i : f(t, n);
+	}, [d]);
+	if (!p) return null;
+	let h = `${p.confirmation.body}\n\n${m("confirm.requestedBy", "An AI agent asked to do this ({{tool}}). Nothing happens unless you confirm.", { tool: p.toolTitle })}`;
+	return /* @__PURE__ */ l(t, {
+		open: !0,
+		copy: {
+			title: p.confirmation.title,
+			body: h,
+			confirm: p.confirmation.confirmLabel
+		},
+		tr: m,
+		cancelLabel: m("confirm.cancel", "Cancel"),
+		testIdPrefix: u,
+		onConfirm: () => i(p.id, !0),
+		onDismiss: () => i(p.id, !1)
+	}, p.id);
+};
+function f(e, t) {
+	return t ? Object.entries(t).reduce((e, [t, n]) => e.replace(RegExp(`\\{\\{${t}\\}\\}`, "g"), String(n)), e) : e;
+}
+//#endregion
+export { u as AGENT_CONFIRM_TEST_ID_PREFIX, d as AgentConfirmHost };

package/dist/shared/agent-tools/confirm/confirmStore.d.ts

@@ -0,0 +1,37 @@
+import { AgentToolConfirmation } from '../types';
+/**
+ * The queue of confirmations agent tools are waiting on.
+ *
+ * ★ Page-global state, for the same reason as the tool registry: a tool may be
+ * registered anywhere in the tree, the host that shows the dialog is mounted
+ * once by `AgentToolsProvider`. One dialog at a time, first come first served.
+ *
+ * ★★ What makes a consequential tool safe to expose is that the dialog's
+ * confirm button counts a TRUSTED press only (`AssistantControlConfirmDialog`):
+ * a click a script dispatched — including an agent's own `ui_click` — is
+ * ignored. With no host mounted there is no way to ask, and the request fails
+ * with `NEEDS_USER` rather than running unconfirmed.
+ */
+export interface PendingConfirmation {
+    id: number;
+    toolTitle: string;
+    confirmation: AgentToolConfirmation;
+    resolve: (confirmed: boolean) => void;
+}
+type Listener = () => void;
+export declare function subscribeConfirmations(listener: Listener): () => void;
+/** The confirmation on screen (the head of the queue), or null. */
+export declare function currentConfirmation(): PendingConfirmation | null;
+/** A host announces itself while mounted. Returns its cleanup. */
+export declare function registerConfirmHost(): () => void;
+/** Answer the confirmation `id`. Idempotent: a second answer is ignored. */
+export declare function settle(id: number, confirmed: boolean): void;
+/**
+ * Ask the person to confirm. Resolves true only on their confirm press; false
+ * on cancel. Rejects with `CANCELLED` when `signal` aborts (the dialog closes),
+ * and with `NEEDS_USER` when no host is mounted to ask.
+ */
+export declare function requestAgentConfirmation(toolTitle: string, confirmation: AgentToolConfirmation, signal: AbortSignal): Promise<boolean>;
+/** Test seam: drop every request and host. */
+export declare function resetConfirmations(): void;
+export {};

package/dist/shared/agent-tools/confirm/confirmStore.js

@@ -0,0 +1,58 @@
+import { AgentToolError as e } from "../errors.js";
+//#region src/shared/agent-tools/confirm/confirmStore.ts
+var t = Symbol.for("burdenoff.fe-libs.agentTools.confirmations.v1");
+function n() {
+	let e = globalThis, n = e[t];
+	if (n && n.listeners instanceof Set) return n;
+	let r = {
+		queue: [],
+		nextId: 1,
+		hosts: 0,
+		listeners: /* @__PURE__ */ new Set()
+	};
+	return e[t] = r, r;
+}
+function r() {
+	for (let e of n().listeners) e();
+}
+function i(e) {
+	let { listeners: t } = n();
+	return t.add(e), () => t.delete(e);
+}
+function a() {
+	return n().queue[0] ?? null;
+}
+function o() {
+	return n().hosts += 1, () => {
+		let e = n();
+		if (e.hosts = Math.max(0, e.hosts - 1), e.hosts === 0) for (let t of [...e.queue]) s(t.id, !1);
+	};
+}
+function s(e, t) {
+	let i = n(), a = i.queue.find((t) => t.id === e);
+	a && (i.queue = i.queue.filter((t) => t.id !== e), r(), a.resolve(t));
+}
+function c(t, i, a) {
+	return n().hosts === 0 ? Promise.reject(new e("NEEDS_USER", "This action needs the person to do it in the page.")) : a.aborted ? Promise.reject(new e("CANCELLED", "The action was cancelled.")) : new Promise((o, s) => {
+		let c = n(), l = c.nextId;
+		c.nextId += 1;
+		let u = () => {
+			let t = c.queue.some((e) => e.id === l);
+			c.queue = c.queue.filter((e) => e.id !== l), t && r(), s(new e("CANCELLED", "The action was cancelled."));
+		};
+		a.addEventListener("abort", u, { once: !0 }), c.queue = [...c.queue, {
+			id: l,
+			toolTitle: t,
+			confirmation: i,
+			resolve: (e) => {
+				a.removeEventListener("abort", u), o(e);
+			}
+		}], r();
+	});
+}
+function l() {
+	let e = n();
+	e.queue = [], e.hosts = 0, r();
+}
+//#endregion
+export { a as currentConfirmation, o as registerConfirmHost, c as requestAgentConfirmation, l as resetConfirmations, s as settle, i as subscribeConfirmations };

package/dist/shared/agent-tools/defineAgentTool.d.ts

@@ -0,0 +1,13 @@
+import { AgentToolDefinition, AgentToolInputSchema, DefinedAgentTool } from './types';
+/**
+ * Check a tool definition once, when the module that declares it loads, and
+ * derive the JSON Schema every channel advertises.
+ *
+ * ★ It THROWS on a definition that breaks a limit. Definitions are static code,
+ * so a broken one fails the first test or page load that imports it, never a
+ * person's agent call in production.
+ *
+ * The schema is derived from the zod object rather than written by hand, so
+ * what the agent is told and what `runAgentTool` enforces cannot drift apart.
+ */
+export declare function defineAgentTool<S extends AgentToolInputSchema, O>(definition: AgentToolDefinition<S, O>): DefinedAgentTool<S, O>;

package/dist/shared/agent-tools/defineAgentTool.js

@@ -0,0 +1,27 @@
+import { AGENT_TOOL_NAME_PATTERN as e } from "./limits.js";
+import { z as t } from "zod";
+//#region src/shared/agent-tools/defineAgentTool.ts
+function n(t) {
+	let { name: n, title: i, description: a, annotations: o, confirm: s } = t, c = (e) => {
+		throw TypeError(`Agent tool "${n}": ${e}`);
+	};
+	(!e.test(n) || n.length > 30) && c(`name must match ${e} and be at most 30 chars`), i.trim() || c("title is required"), a.trim() || c("description is required"), a.length > 500 && c(`description is ${a.length} chars (max 500)`), o?.consequential && !s && c("a consequential tool must say what the person confirms (`confirm`)"), o?.consequential && o.readOnly && c("a tool cannot be both readOnly and consequential");
+	let l = r(t.input);
+	l.additionalProperties !== !1 && c("input must be a strict object (z.strictObject) so unknown keys are rejected");
+	let u = l.properties ?? {};
+	for (let [e, t] of Object.entries(u)) {
+		e.length > 30 && c(`parameter "${e}" is longer than 30 chars`);
+		let n = t.description;
+		typeof n != "string" || !n.trim() ? c(`parameter "${e}" needs a .describe()`) : n.length > 150 && c(`parameter "${e}" description is ${n.length} chars (max 150)`);
+	}
+	return Object.freeze({
+		...t,
+		inputSchema: l
+	});
+}
+function r(e) {
+	let n = { ...t.toJSONSchema(e, { io: "input" }) };
+	return delete n.$schema, n;
+}
+//#endregion
+export { n as defineAgentTool };

package/dist/shared/agent-tools/errors.d.ts

@@ -0,0 +1,33 @@
+import { AgentToolErrorCode, AgentToolFailure } from './types';
+/**
+ * An expected failure a tool reports to the agent: the code is machine-readable,
+ * the message is written for the model to act on ("No run with that id in this
+ * workspace"). Never put input values, tokens or response bodies in it.
+ */
+/**
+ * A brand every copy of fe-libs shares (`Symbol.for`): a microfrontend's copy
+ * of this class and the shell's are different constructors, so `instanceof`
+ * alone would turn a product tool's expected error into a generic FAILED.
+ */
+declare const AGENT_TOOL_ERROR_BRAND: unique symbol;
+export declare class AgentToolError extends Error {
+    readonly code: AgentToolErrorCode;
+    readonly retryable: boolean;
+    readonly [AGENT_TOOL_ERROR_BRAND] = true;
+    constructor(code: AgentToolErrorCode, message: string, options?: {
+        retryable?: boolean;
+    });
+}
+/** An AgentToolError from ANY copy of fe-libs (brand + shape, not `instanceof`). */
+export declare function isAgentToolError(error: unknown): error is AgentToolError;
+/**
+ * Turn anything a tool threw into the failure the agent sees.
+ *
+ * ★ Only the error CODE survives from a GraphQL or network error, mapped to a
+ * fixed sentence. A client error's message can embed the whole request,
+ * variables included (graphql-request's `ClientError` does), and a server
+ * message can carry another tenant's identifiers; neither may reach an agent.
+ */
+export declare function toAgentToolFailure(error: unknown): AgentToolFailure;
+export declare function agentToolFailure(code: AgentToolErrorCode, message?: string, retryable?: boolean): AgentToolFailure;
+export {};