@burdenoff/fe-libs 2026.1024.4 → 2026.1027.1

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

@@ -0,0 +1,105 @@
+//#region src/shared/agent-tools/errors.ts
+var e = Symbol.for("burdenoff.fe-libs.agentToolError.v1"), t = new Set([
+	"INVALID_INPUT",
+	"UNAUTHENTICATED",
+	"FORBIDDEN",
+	"NOT_FOUND",
+	"CONFLICT",
+	"NEEDS_USER",
+	"CANCELLED",
+	"FAILED"
+]), n = class extends Error {
+	code;
+	retryable;
+	[e] = !0;
+	constructor(e, t, n) {
+		super(t), this.name = "AgentToolError", this.code = e, this.retryable = n?.retryable ?? (e === "FAILED" || e === "INVALID_INPUT");
+	}
+};
+function r(r) {
+	if (r instanceof n) return !0;
+	if (!r || typeof r != "object") return !1;
+	let i = r;
+	return i[e] === !0 && typeof i.code == "string" && t.has(i.code) && typeof i.message == "string" && typeof i.retryable == "boolean";
+}
+var i = {
+	UNAUTHENTICATED: "UNAUTHENTICATED",
+	UNAUTHORIZED: "UNAUTHENTICATED",
+	FORBIDDEN: "FORBIDDEN",
+	PERMISSION_DENIED: "FORBIDDEN",
+	NOT_FOUND: "NOT_FOUND",
+	CONFLICT: "CONFLICT",
+	BAD_USER_INPUT: "INVALID_INPUT",
+	GRAPHQL_VALIDATION_FAILED: "INVALID_INPUT"
+}, a = {
+	INVALID_INPUT: "The input was not accepted.",
+	UNAUTHENTICATED: "The person is signed out. Ask them to sign in again.",
+	FORBIDDEN: "The person does not have permission to do this here.",
+	NOT_FOUND: "Nothing with that id was found in the current workspace.",
+	CONFLICT: "The record is not in a state that allows this.",
+	NEEDS_USER: "Only the person can do this step.",
+	CANCELLED: "The action was cancelled.",
+	FAILED: "The action failed. Try again, or ask the person to do it in the page."
+};
+function o(e) {
+	if (!e || typeof e != "object") return [];
+	let t = e;
+	for (let e of [
+		t.graphQLErrors,
+		t.errors,
+		t.response?.errors
+	]) if (Array.isArray(e) && e.length > 0) return e;
+	return [];
+}
+function s(e) {
+	return !!e && typeof e == "object" && "name" in e && e.name === "AbortError";
+}
+function c(e) {
+	if (r(e)) return {
+		ok: !1,
+		error: {
+			code: e.code,
+			message: e.message,
+			retryable: e.retryable
+		}
+	};
+	if (s(e)) return {
+		ok: !1,
+		error: {
+			code: "CANCELLED",
+			message: a.CANCELLED,
+			retryable: !1
+		}
+	};
+	for (let t of o(e)) {
+		let e = t.extensions?.code, n = typeof e == "string" ? i[e] : void 0;
+		if (n) return {
+			ok: !1,
+			error: {
+				code: n,
+				message: a[n],
+				retryable: n === "INVALID_INPUT"
+			}
+		};
+	}
+	return {
+		ok: !1,
+		error: {
+			code: "FAILED",
+			message: a.FAILED,
+			retryable: !0
+		}
+	};
+}
+function l(e, t = a[e], n = !1) {
+	return {
+		ok: !1,
+		error: {
+			code: e,
+			message: t,
+			retryable: n
+		}
+	};
+}
+//#endregion
+export { n as AgentToolError, l as agentToolFailure, r as isAgentToolError, c as toAgentToolFailure };

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

@@ -0,0 +1,29 @@
+/**
+ * ★ BOFF-9783: agent tools — actions AI agents may take in the page, defined
+ * once and offered through WebMCP and the in-app assistant.
+ *
+ * ```tsx
+ * // once, in the app shell
+ * <AgentToolsProvider product="fluidgrids" gatherPageContext={gatherPageContext} />
+ *
+ * // in the component that owns the state a tool acts on
+ * const RUN_TOOLS = [defineAgentTool({ name: 'fg_run_get', … })];
+ * useAgentTools(RUN_TOOLS);
+ * ```
+ */
+export * from './types';
+export * from './limits';
+export * from './errors';
+export * from './defineAgentTool';
+export * from './outputBudget';
+export * from './registry';
+export * from './runAgentTool';
+export * from './useAgentTools';
+export * from './confirm/confirmStore';
+export * from './confirm/AgentConfirmHost';
+export * from './adapters/webmcp';
+export * from './adapters/assistant';
+export * from './shell/shellTools';
+export * from './ui/uiTools';
+export { DENY_SELECTOR, INTERACTIVE_SELECTOR, accessibleName, isDenied, isSensitiveField, roleOf, } from './ui/dom';
+export * from './AgentToolsProvider';

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

@@ -0,0 +1,20 @@
+/**
+ * Size limits for agent tools.
+ *
+ * The first four are Chrome's published WebMCP guidance
+ * (developer.chrome.com/docs/ai/webmcp/secure-tools): not enforced by the
+ * browser, but every tool here keeps to them so an agent's context stays small
+ * and a tool reads the same in every channel.
+ */
+/** Tool names and parameter names. */
+export declare const AGENT_TOOL_NAME_MAX = 30;
+/** A tool's description. */
+export declare const AGENT_TOOL_DESCRIPTION_MAX = 500;
+/** A parameter's description. */
+export declare const AGENT_TOOL_PARAM_DESCRIPTION_MAX = 150;
+/** One result, as serialized JSON (UTF-8 bytes). */
+export declare const AGENT_TOOL_OUTPUT_MAX_BYTES = 1536;
+/** Longest string any single field of a result keeps before it is clamped. */
+export declare const AGENT_TOOL_OUTPUT_STRING_MAX = 300;
+/** `^[a-z][a-z0-9_]*$` — WebMCP allows more, this is the house style. */
+export declare const AGENT_TOOL_NAME_PATTERN: RegExp;

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

@@ -0,0 +1,4 @@
+//#region src/shared/agent-tools/limits.ts
+var e = 30, t = 500, n = 150, r = 1536, i = 300, a = /^[a-z][a-z0-9_]*$/;
+//#endregion
+export { t as AGENT_TOOL_DESCRIPTION_MAX, e as AGENT_TOOL_NAME_MAX, a as AGENT_TOOL_NAME_PATTERN, r as AGENT_TOOL_OUTPUT_MAX_BYTES, i as AGENT_TOOL_OUTPUT_STRING_MAX, n as AGENT_TOOL_PARAM_DESCRIPTION_MAX };

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

@@ -0,0 +1,15 @@
+import { AgentToolErrorCode, AgentToolInitiator } from './types';
+/**
+ * One line per tool call: which tool, who asked, how it ended, how long it took.
+ *
+ * ★ Never the input or the result. Inputs carry what a person typed or an agent
+ * made up; results carry workspace data. Neither belongs in a log.
+ */
+export declare function logAgentToolCall(entry: {
+    tool: string;
+    initiator: AgentToolInitiator;
+    outcome: 'ok' | AgentToolErrorCode;
+    durationMs: number;
+    truncated?: boolean;
+}): void;
+export declare function logAgentToolProblem(message: string, context: Record<string, unknown>): void;

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

@@ -0,0 +1,11 @@
+import { logManager as e } from "../logger/LogManager.js";
+//#region src/shared/agent-tools/log.ts
+var t = e.getLogger("agent-tools");
+function n(e) {
+	e.outcome === "ok" ? t.info("agent tool call", e) : t.warn("agent tool call", e);
+}
+function r(e, n) {
+	t.warn(e, n);
+}
+//#endregion
+export { n as logAgentToolCall, r as logAgentToolProblem };

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

@@ -0,0 +1,21 @@
+export interface CappedResult {
+    data: unknown;
+    truncated: boolean;
+}
+/** Serialized size in UTF-8 bytes — what the agent's context actually pays for. */
+export declare function jsonByteLength(value: unknown): number;
+/**
+ * Fit a tool's result into the output budget.
+ *
+ * Tools are written to return small results; this is the backstop for the one
+ * that does not (a long list, a long error text). In order, until it fits:
+ *  1. clamp every string to `AGENT_TOOL_OUTPUT_STRING_MAX` characters;
+ *  2. drop items from the END of the longest array, repeatedly — a list keeps
+ *     its first, most relevant rows;
+ *  3. give up on the payload and say so, so the agent narrows its query instead
+ *     of acting on a silently partial object.
+ *
+ * A value that cannot be serialized (a cycle, a BigInt) is a tool bug: it
+ * throws, and `runAgentTool` reports `FAILED`.
+ */
+export declare function capResult(value: unknown, maxBytes?: number): CappedResult;

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

@@ -0,0 +1,51 @@
+import { AGENT_TOOL_OUTPUT_MAX_BYTES as e } from "./limits.js";
+//#region src/shared/agent-tools/outputBudget.ts
+var t = new TextEncoder();
+function n(e) {
+	return t.encode(JSON.stringify(e) ?? "null").length;
+}
+function r(t, r = e) {
+	let o = JSON.parse(JSON.stringify(t ?? null));
+	if (n(o) <= r) return {
+		data: o,
+		truncated: !1
+	};
+	let s = i(o);
+	if (n(s) <= r) return {
+		data: s,
+		truncated: !0
+	};
+	for (let e = 0; e < 1e4; e += 1) {
+		let e = a(s);
+		if (!e || e.length === 0) break;
+		if (e.pop(), n(s) <= r) return {
+			data: s,
+			truncated: !0
+		};
+	}
+	return {
+		data: { note: "The result was too large to return. Narrow the request (filters, a smaller limit)." },
+		truncated: !0
+	};
+}
+function i(e) {
+	if (typeof e == "string") return e.length > 300 ? `${e.slice(0, 299)}…` : e;
+	if (Array.isArray(e)) return e.map(i);
+	if (e && typeof e == "object") {
+		let t = {};
+		for (let [n, r] of Object.entries(e)) t[n] = i(r);
+		return t;
+	}
+	return e;
+}
+function a(e) {
+	let t = null, r = -1, i = (e) => {
+		if (Array.isArray(e)) {
+			let a = n(e);
+			e.length > 0 && a > r && (t = e, r = a), e.forEach(i);
+		} else e && typeof e == "object" && Object.values(e).forEach(i);
+	};
+	return i(e), t;
+}
+//#endregion
+export { r as capResult, n as jsonByteLength };

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

@@ -0,0 +1,13 @@
+import { AnyDefinedAgentTool } from './types';
+type Listener = () => void;
+/** Register `tool`. Returns the cleanup that removes exactly this registration. */
+export declare function registerAgentTool(tool: AnyDefinedAgentTool): () => void;
+/** The tools in force (newest per name), sorted by name. Stable between changes. */
+export declare function listAgentTools(): readonly AnyDefinedAgentTool[];
+/** The tool in force for `name`, or null. */
+export declare function getAgentTool(name: string): AnyDefinedAgentTool | null;
+/** Called after every change to the set of tools in force. */
+export declare function subscribeAgentTools(listener: Listener): () => void;
+/** Test seam: forget every registration. */
+export declare function clearAgentTools(): void;
+export {};

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

@@ -0,0 +1,53 @@
+//#region src/shared/agent-tools/registry.ts
+var e = Symbol.for("burdenoff.fe-libs.agentTools.registry.v1");
+function t() {
+	let t = globalThis, n = t[e];
+	if (n && n.stacks instanceof Map) return n;
+	let r = {
+		stacks: /* @__PURE__ */ new Map(),
+		listeners: /* @__PURE__ */ new Set(),
+		snapshot: []
+	};
+	return t[e] = r, r;
+}
+function n() {
+	let e = t(), n = [];
+	for (let t of e.stacks.values()) {
+		let e = t[t.length - 1];
+		e && n.push(e.tool);
+	}
+	n.sort((e, t) => e.name.localeCompare(t.name)), e.snapshot = n;
+	for (let t of e.listeners) t();
+}
+function r(e) {
+	let { stacks: r } = t(), i = Symbol(e.name), a = r.get(e.name) ?? [];
+	a.push({
+		token: i,
+		tool: e
+	}), r.set(e.name, a), n();
+	let o = !1;
+	return () => {
+		if (o) return;
+		o = !0;
+		let r = t().stacks.get(e.name);
+		if (!r) return;
+		let a = r.findIndex((e) => e.token === i);
+		a < 0 || (r.splice(a, 1), r.length === 0 && t().stacks.delete(e.name), n());
+	};
+}
+function i() {
+	return t().snapshot;
+}
+function a(e) {
+	let n = t().stacks.get(e);
+	return n?.[n.length - 1]?.tool ?? null;
+}
+function o(e) {
+	let { listeners: n } = t();
+	return n.add(e), () => n.delete(e);
+}
+function s() {
+	t().stacks.clear(), n();
+}
+//#endregion
+export { s as clearAgentTools, a as getAgentTool, i as listAgentTools, r as registerAgentTool, o as subscribeAgentTools };

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

@@ -0,0 +1,21 @@
+import { AgentToolInitiator, AgentToolResult, AnyDefinedAgentTool } from './types';
+export interface RunAgentToolOptions {
+    initiator: AgentToolInitiator;
+    /** Cancels the call: a pending confirmation closes, the tool's own requests abort. */
+    signal: AbortSignal;
+}
+/**
+ * Run a tool for an agent — the ONE path every channel uses, so validation,
+ * confirmation, cancellation and the output budget are the same whichever
+ * agent asked.
+ *
+ *  1. Validate the input against the tool's strict schema. Wrong types, missing
+ *     or unknown fields, oversized strings and out-of-range numbers are refused
+ *     with a message naming the field, so the agent can correct and retry.
+ *  2. A consequential tool asks the person first; declining is `CANCELLED`.
+ *  3. Execute with the call's AbortSignal.
+ *  4. Cap the result.
+ *
+ * Never throws: every outcome is an `AgentToolResult`.
+ */
+export declare function runAgentTool(tool: AnyDefinedAgentTool, rawInput: unknown, { initiator, signal }: RunAgentToolOptions): Promise<AgentToolResult>;

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

@@ -0,0 +1,57 @@
+import { AgentToolError as e, agentToolFailure as t, toAgentToolFailure as n } from "./errors.js";
+import { logAgentToolCall as r } from "./log.js";
+import { requestAgentConfirmation as i } from "./confirm/confirmStore.js";
+import { capResult as a } from "./outputBudget.js";
+//#region src/shared/agent-tools/runAgentTool.ts
+var o = 5;
+async function s(o, s, { initiator: u, signal: d }) {
+	let f = Date.now(), p = (e) => (r({
+		tool: o.name,
+		initiator: u,
+		outcome: e.ok ? "ok" : e.error.code,
+		durationMs: Date.now() - f,
+		...e.ok && e.truncated ? { truncated: !0 } : {}
+	}), e);
+	if (d.aborted) return p(t("CANCELLED"));
+	let m = o.input.safeParse(c(s));
+	if (!m.success) return p(t("INVALID_INPUT", l(m.error), !0));
+	let h = m.data;
+	try {
+		if (o.annotations?.consequential) {
+			let n = o.confirm?.(h);
+			if (!n) throw new e("NEEDS_USER", "This action needs the person to do it.");
+			if (!await i(o.title, n, d)) return p(t("CANCELLED", "The person declined this action.", !1));
+		}
+		let n = await o.execute(h, {
+			signal: d,
+			initiator: u
+		});
+		if (d.aborted) return p(t("CANCELLED"));
+		let { data: r, truncated: s } = a(n);
+		return p(s ? {
+			ok: !0,
+			data: r,
+			truncated: !0
+		} : {
+			ok: !0,
+			data: r
+		});
+	} catch (e) {
+		return p(n(e));
+	}
+}
+function c(e) {
+	if (e == null) return {};
+	if (typeof e == "string") try {
+		return JSON.parse(e);
+	} catch {
+		return e;
+	}
+	return e;
+}
+function l(e) {
+	let t = e.issues.slice(0, o).map((e) => `${e.path.length > 0 ? e.path.join(".") : "input"}: ${e.message}`), n = e.issues.length - o;
+	return n > 0 && t.push(`…and ${n} more`), `Invalid input. ${t.join("; ")}`;
+}
+//#endregion
+export { s as runAgentTool };

package/dist/shared/agent-tools/shell/shellTools.d.ts

@@ -0,0 +1,44 @@
+import { LocalDestination } from '../../assistant/localUiCommands';
+import { AnyDefinedAgentTool } from '../types';
+/**
+ * ★ BOFF-9783: the tools every product shell offers, whatever the product —
+ * where am I, take me somewhere, switch the theme. They read live shell state
+ * through `ShellToolsSource`, which `AgentToolsProvider` refreshes on every
+ * render, so a tool never acts on a stale workspace or navigation tree.
+ */
+export interface ShellToolsSource {
+    /** Product id, e.g. the assistant's product namespace. */
+    product: string;
+    organizationId: string | null;
+    workspaceId: string | null;
+    projectId: string | null;
+    /** The signed-in person's display name, if the shell wants agents to know it. Never an email. */
+    userDisplayName: string | null;
+    /**
+     * The product's description of the current page (the assistant's
+     * `gatherPageContext`). Only the entity keys below are passed on.
+     */
+    pageContext: () => Readonly<Record<string, unknown>> | null;
+    /** The places the person's own navigation can take them (permission-filtered). */
+    destinations: readonly LocalDestination[];
+    /** False while permissions load or a role is being simulated: no navigation then. */
+    navigationReady: boolean;
+    /** Navigate within the app. */
+    navigate: (path: string) => void;
+    /** Current theme mode, or null without a theme provider. */
+    themeMode: string | null;
+    setThemeMode: ((mode: 'light' | 'dark' | 'system') => void) | null;
+}
+/**
+ * Resolve what an agent asked for to a destination the person's own navigation
+ * offers. A free path is accepted only AT or BELOW a path the navigation lists
+ * (a record under a listed page), never a sibling the permission or persona
+ * filter removed, so an agent cannot reach a page the sidebar hides from this
+ * person.
+ */
+export declare function resolveDestination(destinations: readonly LocalDestination[], requested: string): {
+    path: string;
+    label: string;
+} | null;
+export declare function assertNoUnsavedChanges(): void;
+export declare function createShellTools(getSource: () => ShellToolsSource): AnyDefinedAgentTool[];

package/dist/shared/agent-tools/shell/shellTools.js

@@ -0,0 +1,145 @@
+import { isSafeInAppPath as e } from "../../navigation/inAppPath.js";
+import { unsavedChangesBlocking as t } from "../../navigation/unsavedChanges.js";
+import { AgentToolError as n } from "../errors.js";
+import { defineAgentTool as r } from "../defineAgentTool.js";
+import { z as i } from "zod";
+//#region src/shared/agent-tools/shell/shellTools.ts
+var a = [
+	"entityType",
+	"entityId",
+	"entityName",
+	"pageType",
+	"activeTab"
+], o = 25;
+function s(e) {
+	let t = {};
+	if (!e) return t;
+	for (let n of a) {
+		let r = e[n];
+		typeof r == "string" && r.trim() && (t[n] = r.slice(0, 120));
+	}
+	return t;
+}
+function c(e) {
+	try {
+		return e.pageContext();
+	} catch {
+		return null;
+	}
+}
+function l() {
+	if (typeof document > "u") return null;
+	let e = document.querySelector("main h1, h1")?.textContent?.replace(/\s+/g, " ").trim();
+	return e ? e.slice(0, 120) : null;
+}
+function u(t, n) {
+	let r = n.trim(), i = r.toLowerCase(), a = t.find((e) => e.label.toLowerCase() === i || e.id.toLowerCase() === i);
+	if (a) return {
+		path: a.path,
+		label: a.label
+	};
+	if (!r.startsWith("/") || !e(r)) return null;
+	let o = r.split(/[?#]/)[0] ?? r, s = null;
+	for (let e of t) for (let t of [e.path, ...e.aliases ?? []]) {
+		let n = t.split(/[?#]/)[0]?.replace(/\/+$/, "") ?? "";
+		n && (o === n || o.startsWith(`${n}/`)) && (!s || n.length > s.length) && (s = {
+			path: o === n ? e.path : r,
+			label: e.label,
+			length: n.length
+		});
+	}
+	return s ? {
+		path: s.path,
+		label: s.label
+	} : null;
+}
+function d(e) {
+	if (!e.navigationReady) throw new n("CONFLICT", "The app's navigation is still loading. Try again in a moment.", { retryable: !0 });
+}
+function f() {
+	let e = t("assistant");
+	if (e) throw new n("CONFLICT", `The page has unsaved changes (${e.map((e) => e.label).join(", ")}). Ask the person to save or discard them first.`);
+}
+function p(e) {
+	return [
+		r({
+			name: "app_get_context",
+			title: "Get current context",
+			description: "Returns where the person is in the app: product, current page path and heading, the record the page shows (entity type and id), and the active organization, workspace and project ids. Use it first to understand \"this\", \"here\" or \"current\".",
+			input: i.strictObject({}),
+			annotations: {
+				readOnly: !0,
+				untrustedContent: !0
+			},
+			execute: () => {
+				let t = e();
+				return {
+					product: t.product,
+					path: typeof window > "u" ? null : window.location.pathname,
+					title: typeof document > "u" ? null : document.title.slice(0, 120),
+					heading: l(),
+					...s(c(t)),
+					organizationId: t.organizationId,
+					workspaceId: t.workspaceId,
+					projectId: t.projectId,
+					...t.userDisplayName ? { userDisplayName: t.userDisplayName } : {}
+				};
+			}
+		}),
+		r({
+			name: "app_list_pages",
+			title: "List pages",
+			description: "Lists the pages the person's navigation offers (label and path). Use it to find where to go before calling app_navigate.",
+			input: i.strictObject({ offset: i.number().int().min(0).max(1e3).default(0).describe("Index of the first page to return, for paging.") }),
+			annotations: { readOnly: !0 },
+			execute: ({ offset: t }) => {
+				let n = e();
+				d(n);
+				let { destinations: r } = n, i = r.slice(t, t + o), a = t + i.length;
+				return {
+					pages: i.map((e) => ({
+						label: e.context ? `${e.context} › ${e.label}` : e.label,
+						path: e.path
+					})),
+					...a < r.length ? { nextOffset: a } : {}
+				};
+			}
+		}),
+		r({
+			name: "app_navigate",
+			title: "Open a page",
+			description: "Opens a page of the app in the person's tab. Pass a page label from app_list_pages (e.g. \"Runs\") or an in-app path starting with \"/\". Refused while the current page has unsaved changes.",
+			input: i.strictObject({ destination: i.string().trim().min(1).max(200).describe("A page label from app_list_pages, or an in-app path starting with \"/\".") }),
+			execute: ({ destination: t }) => {
+				let r = e();
+				d(r);
+				let i = u(r.destinations, t);
+				if (!i) {
+					let e = r.destinations.slice(0, 12).map((e) => e.label).join(", ");
+					throw new n("NOT_FOUND", `No page "${t.slice(0, 60)}" in this app's navigation. Known pages include: ${e}. Use app_list_pages for all.`, { retryable: !0 });
+				}
+				return f(), r.navigate(i.path), {
+					navigatedTo: i.path,
+					page: i.label
+				};
+			}
+		}),
+		r({
+			name: "app_set_theme",
+			title: "Change theme",
+			description: "Switches the app between light, dark and system appearance.",
+			input: i.strictObject({ mode: i.enum([
+				"light",
+				"dark",
+				"system"
+			]).describe("The appearance to switch to.") }),
+			execute: ({ mode: t }) => {
+				let { setThemeMode: r } = e();
+				if (!r) throw new n("NEEDS_USER", "This app does not let the theme be changed here.");
+				return r(t), { mode: t };
+			}
+		})
+	];
+}
+//#endregion
+export { f as assertNoUnsavedChanges, p as createShellTools, u as resolveDestination };

package/dist/shared/agent-tools/testSupport/installDom.d.ts

@@ -0,0 +1,6 @@
+import { Window } from 'happy-dom';
+export interface InstalledDom {
+    window: Window;
+    restore: () => void;
+}
+export declare function installDom(url?: string): InstalledDom;