@burdenoff/fe-libs 2026.1026.1 → 2026.1027.2

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;

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

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+/**
+ * ★ BOFF-9783: one definition of an action an AI agent may take in the page,
+ * exposed through every channel that can reach the page — the browser's own
+ * agent through W3C WebMCP (`document.modelContext`) and the product's in-app
+ * assistant through client tool calls.
+ *
+ * A tool is code the product chose to expose. It runs in the person's tab, with
+ * the person's session, through the same API calls the UI makes, so the
+ * gateway's `@rbac` and tenant checks apply exactly as they do to a click.
+ * Nothing here is a security boundary on its own: the hints are advisory, the
+ * confirmation is a courtesy to the person, the backend decides.
+ */
+/** Who asked for the tool to run. Logged; never trusted for authorization. */
+export type AgentToolInitiator = 'webmcp' | 'assistant';
+/**
+ * Advisory hints, mapped one to one onto WebMCP's `ToolAnnotations`.
+ *
+ * `consequential` is ALSO enforced here: such a tool never runs until the
+ * person confirms it in the page with a real click (`requestAgentConfirmation`).
+ */
+export interface AgentToolAnnotations {
+    /** The tool changes nothing. */
+    readOnly?: boolean;
+    /** The result carries text other people wrote (names, run output, errors). */
+    untrustedContent?: boolean;
+    /** The tool changes something that matters: it is confirmed before it runs. */
+    consequential?: boolean;
+}
+/** What the confirmation dialog says. Plain text — never markup. */
+export interface AgentToolConfirmation {
+    title: string;
+    body: string;
+    /** The confirm button's words, e.g. "Cancel run". */
+    confirmLabel: string;
+}
+export interface AgentToolExecuteContext {
+    /** Aborted when the agent cancels the call or the tool is unregistered. */
+    signal: AbortSignal;
+    initiator: AgentToolInitiator;
+}
+/** The input type a tool's zod object describes. */
+export type AgentToolInputSchema = z.ZodObject<z.ZodRawShape>;
+export interface AgentToolDefinition<S extends AgentToolInputSchema = AgentToolInputSchema, O = unknown> {
+    /** `^[a-z][a-z0-9_]*$`, at most 30 characters, e.g. `fg_runs_list`. */
+    name: string;
+    /** Short human title, shown in the confirmation dialog and the assistant's status line. */
+    title: string;
+    /** What the tool does and when to use it. At most 500 characters. */
+    description: string;
+    /**
+     * A STRICT zod object. Unknown keys are rejected, so every parameter has to be
+     * declared — each with a `.describe()` of at most 150 characters.
+     */
+    input: S;
+    annotations?: AgentToolAnnotations;
+    /** Required for consequential tools: what the person is asked to confirm. */
+    confirm?: (input: z.output<S>) => AgentToolConfirmation;
+    /**
+     * Do the work. Return only the fields an agent needs: the result is capped
+     * (`AGENT_TOOL_OUTPUT_MAX_BYTES`). Throw `AgentToolError` for an expected
+     * failure; anything else is reported as `FAILED` without its message.
+     */
+    execute: (input: z.output<S>, context: AgentToolExecuteContext) => Promise<O> | O;
+}
+/** A definition after `defineAgentTool` checked it and derived its JSON Schema. */
+export interface DefinedAgentTool<S extends AgentToolInputSchema = AgentToolInputSchema, O = unknown> extends AgentToolDefinition<S, O> {
+    /** JSON Schema (draft 2020-12) of the input, `additionalProperties: false`. */
+    readonly inputSchema: Record<string, unknown>;
+}
+/** Any defined tool, whatever its input and output types. */
+export type AnyDefinedAgentTool = DefinedAgentTool<AgentToolInputSchema, unknown>;
+export type AgentToolErrorCode = 
+/** The input failed validation; `message` says which field and why. */
+'INVALID_INPUT'
+/** The person is signed out. */
+ | 'UNAUTHENTICATED'
+/** The backend refused: the person may not do this here. */
+ | 'FORBIDDEN'
+/** Nothing with that id in the person's current workspace. */
+ | 'NOT_FOUND'
+/** The record is in a state that does not allow this. */
+ | 'CONFLICT'
+/** Only the person can do this step (a file picker, a sign-in popup, a confirmation they declined to give here). */
+ | 'NEEDS_USER'
+/** The person declined, or the call was cancelled. */
+ | 'CANCELLED'
+/** Anything else. */
+ | 'FAILED';
+export interface AgentToolSuccess<O = unknown> {
+    ok: true;
+    data: O;
+    /** Set when the result was cut to fit the output budget. */
+    truncated?: true;
+}
+export interface AgentToolFailure {
+    ok: false;
+    error: {
+        code: AgentToolErrorCode;
+        message: string;
+        /** True when the same call may succeed later or with corrected input. */
+        retryable: boolean;
+    };
+}
+/** What every channel returns to the agent. */
+export type AgentToolResult<O = unknown> = AgentToolSuccess<O> | AgentToolFailure;

package/dist/shared/agent-tools/ui/dom.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ★ BOFF-9783: the DOM rules the generic UI tools live by — what counts as a
+ * control, what a control is called, and which parts of the page an agent may
+ * never see or touch.
+ *
+ * These read the page the way assistive technology does (roles, accessible
+ * names, states), so the agent's view is the same one a screen-reader user
+ * gets, and a page that is accessible is also operable by an agent.
+ */
+/** Elements an agent can operate. */
+export declare const INTERACTIVE_SELECTOR: string;
+/**
+ * ★★ Regions an agent never sees or operates:
+ *  - anything a product marks `data-agent="deny"` (billing, secrets, vault…);
+ *  - the assistant's own panel, overlay and voice session — an agent must not
+ *    drive the conversation it is part of;
+ *  - every confirmation dialog — the person's decision, never the agent's
+ *    (the dialogs also ignore untrusted clicks; this is the second line).
+ */
+export declare const DENY_SELECTOR: string;
+export declare function isDenied(element: Element): boolean;
+/** A credential, payment or one-time-code field, or one a product marked sensitive. */
+export declare function isSensitiveField(element: Element): boolean;
+/**
+ * Rendered and reachable: not hidden, not inert, not behind a modal (a modal
+ * dialog marks the rest of the page `aria-hidden`), not `display: none`.
+ */
+export declare function isVisible(element: Element): boolean;
+export declare function isDisabled(element: Element): boolean;
+/** The ARIA role, explicit or implied by the element. */
+export declare function roleOf(element: Element): string;
+/**
+ * The accessible name, in the order assistive technology computes it:
+ * aria-labelledby → aria-label → associated <label> → title → own text (for
+ * buttons, links and the like) → placeholder.
+ */
+export declare function accessibleName(element: Element): string;
+/** Short state flags: "disabled", "checked", "expanded", … */
+export declare function stateOf(element: Element): string[];
+/** The current value of a field, unless it is sensitive. */
+export declare function valueOf(element: Element): string | null;
+/** The open dialog's title, if a (non-denied) dialog is open. */
+export declare function openDialogTitle(doc: Document): string | null;