@burdenoff/fe-libs 2026.1026.1 → 2026.1027.2

package/dist/shared/agent-tools/ui/dom.js

@@ -0,0 +1,178 @@
+//#region src/shared/agent-tools/ui/dom.ts
+var e = [
+	"a[href]",
+	"button",
+	"input:not([type=\"hidden\"])",
+	"select",
+	"textarea",
+	"summary",
+	"[contenteditable=\"true\"]",
+	"[contenteditable=\"\"]",
+	...[
+		"button",
+		"link",
+		"tab",
+		"menuitem",
+		"menuitemcheckbox",
+		"menuitemradio",
+		"option",
+		"checkbox",
+		"radio",
+		"switch",
+		"combobox",
+		"textbox",
+		"searchbox",
+		"slider",
+		"spinbutton",
+		"treeitem"
+	].map((e) => `[role="${e}"]`)
+].join(", "), t = [
+	"[data-agent=\"deny\"]",
+	"[data-assistant-panel]",
+	"[data-assistant-overlay]",
+	"[data-assistant-voice-session]",
+	"[data-testid^=\"agent-tool-confirm\"]",
+	"[role=\"alertdialog\"][data-testid^=\"assistant-\"]",
+	"[role=\"dialog\"][data-testid^=\"assistant-\"]"
+].join(", "), n = /(^|\s)(current-password|new-password|one-time-code|cc-[a-z-]+|webauthn)(\s|$)/i, r = /pass(word|code|phrase)|passwd|pwd|secret|token|api[-_]?key|private[-_]?key|client[-_]?secret|cvv|cvc|card[-_]?number|iban|ssn/i;
+function i(e) {
+	return e.closest(t) !== null;
+}
+function a(e) {
+	if (e.closest("[data-agent-sensitive]")) return !0;
+	let t = e.tagName.toLowerCase();
+	if (t !== "input" && t !== "textarea") return !1;
+	if ((e.getAttribute("type") ?? "").toLowerCase() === "password" || n.test(e.getAttribute("autocomplete") ?? "")) return !0;
+	let i = `${e.getAttribute("name") ?? ""} ${e.getAttribute("id") ?? ""}`;
+	return r.test(i);
+}
+function o(e) {
+	if (!e.isConnected || e.closest("[hidden], [inert], [aria-hidden=\"true\"]")) return !1;
+	let t = e;
+	if (typeof t.checkVisibility == "function") return t.checkVisibility({
+		checkOpacity: !1,
+		checkVisibilityCSS: !0
+	});
+	let n = e.ownerDocument.defaultView;
+	if (!n) return !0;
+	for (let t = e; t; t = t.parentElement) {
+		let e = n.getComputedStyle(t);
+		if (e.display === "none" || e.visibility === "hidden") return !1;
+	}
+	return !0;
+}
+function s(e) {
+	return e.getAttribute("aria-disabled") === "true" ? !0 : "disabled" in e && e.disabled === !0;
+}
+var c = {
+	checkbox: "checkbox",
+	radio: "radio",
+	range: "slider",
+	number: "spinbutton",
+	button: "button",
+	submit: "button",
+	reset: "button",
+	image: "button",
+	search: "searchbox",
+	file: "file"
+};
+function l(e) {
+	let t = e.getAttribute("role")?.trim().split(/\s+/)[0];
+	if (t) return t;
+	switch (e.tagName.toLowerCase()) {
+		case "a": return "link";
+		case "button":
+		case "summary": return "button";
+		case "select": return e.multiple ? "listbox" : "combobox";
+		case "textarea": return "textbox";
+		case "input": return c[(e.getAttribute("type") ?? "text").toLowerCase()] ?? "textbox";
+		default: return e.hasAttribute("contenteditable") ? "textbox" : "generic";
+	}
+}
+function u(e) {
+	return (e ?? "").replace(/\s+/g, " ").trim();
+}
+var d = 80;
+function f(e) {
+	let t = e.ownerDocument, n = (e) => e.length > d ? `${e.slice(0, d - 1)}…` : e, r = e.getAttribute("aria-labelledby");
+	if (r) {
+		let e = u(r.split(/\s+/).map((e) => t.getElementById(e)?.textContent ?? "").join(" "));
+		if (e) return n(e);
+	}
+	let i = u(e.getAttribute("aria-label"));
+	if (i) return n(i);
+	let a = e.labels;
+	if (a && a.length > 0) {
+		let e = u(Array.from(a, (e) => e.textContent ?? "").join(" "));
+		if (e) return n(e);
+	}
+	let o = u(e.getAttribute("title"));
+	if (o) return n(o);
+	let s = e.tagName.toLowerCase();
+	if (!(s === "textarea" || s === "select" || s === "input" && ![
+		"button",
+		"submit",
+		"reset"
+	].includes((e.getAttribute("type") ?? "").toLowerCase()))) {
+		let t = u(e.textContent);
+		if (t) return n(t);
+		let r = u(e.querySelector("img[alt]")?.getAttribute("alt"));
+		if (r) return n(r);
+		if (s === "input") {
+			let t = u(e.value);
+			if (t) return n(t);
+		}
+	}
+	return n(u(e.getAttribute("placeholder")));
+}
+function p(e) {
+	let t = [];
+	s(e) && t.push("disabled");
+	let n = e.tagName.toLowerCase(), r = (e.getAttribute("type") ?? "").toLowerCase();
+	n === "input" && (r === "checkbox" || r === "radio") ? e.checked && t.push("checked") : e.getAttribute("aria-checked") === "true" && t.push("checked");
+	for (let n of [
+		"expanded",
+		"selected",
+		"pressed"
+	]) e.getAttribute(`aria-${n}`) === "true" && t.push(n);
+	return e.getAttribute("aria-current") && e.getAttribute("aria-current") !== "false" && t.push("current"), (e.hasAttribute("required") || e.getAttribute("aria-required") === "true") && t.push("required"), t;
+}
+var m = 60;
+function h(e) {
+	if (a(e)) return null;
+	let t = e.tagName.toLowerCase(), n = null;
+	if (t === "select") {
+		let t = e;
+		n = t.selectedOptions[0]?.textContent ?? t.value;
+	} else if (t === "textarea") n = e.value;
+	else if (t === "input") {
+		let t = (e.getAttribute("type") ?? "text").toLowerCase();
+		if ([
+			"checkbox",
+			"radio",
+			"button",
+			"submit",
+			"reset",
+			"image",
+			"file"
+		].includes(t)) return null;
+		n = e.value;
+	} else (e.getAttribute("role") === "combobox" || e.hasAttribute("aria-valuenow")) && (n = e.getAttribute("aria-valuetext") ?? e.getAttribute("aria-valuenow"));
+	let r = u(n);
+	return r ? r.length > m ? `${r.slice(0, m - 1)}…` : r : null;
+}
+function g(e) {
+	let t = Array.from(e.querySelectorAll("[role=\"dialog\"], [role=\"alertdialog\"], dialog[open]")).filter((e) => o(e) && !i(e)), n = t[t.length - 1];
+	return n ? _(n) || "Dialog" : null;
+}
+function _(e) {
+	let t = e.getAttribute("aria-labelledby");
+	if (t) {
+		let n = u(e.ownerDocument.getElementById(t)?.textContent);
+		if (n) return n.slice(0, d);
+	}
+	let n = u(e.getAttribute("aria-label"));
+	return n ? n.slice(0, d) : u(e.querySelector("h1, h2, h3")?.textContent).slice(0, d);
+}
+//#endregion
+export { t as DENY_SELECTOR, e as INTERACTIVE_SELECTOR, f as accessibleName, i as isDenied, s as isDisabled, a as isSensitiveField, o as isVisible, g as openDialogTitle, l as roleOf, p as stateOf, h as valueOf };

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

@@ -0,0 +1,8 @@
+export declare const REF_PATTERN: RegExp;
+export declare function refFor(element: Element): string;
+/** The element for `ref`, or null when it is gone from the page. */
+export declare function elementFor(ref: string): Element | null;
+/** Forget refs whose elements are gone. Called on every snapshot. */
+export declare function pruneRefs(): void;
+/** Test seam. */
+export declare function resetRefs(): void;

package/dist/shared/agent-tools/ui/refs.js

@@ -0,0 +1,20 @@
+//#region src/shared/agent-tools/ui/refs.ts
+var e = /* @__PURE__ */ new WeakMap(), t = /* @__PURE__ */ new Map(), n = 1, r = /^e\d{1,7}$/;
+function i(r) {
+	let i = e.get(r);
+	if (i) return t.has(i) || t.set(i, new WeakRef(r)), i;
+	let a = `e${n}`;
+	return n += 1, e.set(r, a), t.set(a, new WeakRef(r)), a;
+}
+function a(e) {
+	let n = t.get(e)?.deref();
+	return !n || !n.isConnected ? null : n;
+}
+function o() {
+	for (let [e, n] of t) {
+		let r = n.deref();
+		(!r || !r.isConnected) && t.delete(e);
+	}
+}
+//#endregion
+export { r as REF_PATTERN, a as elementFor, o as pruneRefs, i as refFor };

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

@@ -0,0 +1,40 @@
+import { AnyDefinedAgentTool } from '../types';
+/**
+ * ★ BOFF-9783: generic UI tools — see the page, click, type, choose, press a
+ * key — so an agent can do in any product what the person can do with a mouse
+ * and keyboard, without each product writing a tool per button.
+ *
+ * Guards, in order of strength:
+ *  - deny zones (`dom.ts`) are invisible and inoperable: products mark billing,
+ *    secrets and the like `data-agent="deny"`; the assistant panel and every
+ *    confirmation dialog are always denied;
+ *  - sensitive fields (passwords, payment, one-time codes) are listed but never
+ *    read or filled;
+ *  - a click on something consequential ("Delete", "Cancel run", "Log out", or
+ *    `data-agent="confirm"`) waits for the person to confirm with a real click;
+ *  - what only a person can start (a file picker, a link out of the tab) is
+ *    refused with `NEEDS_USER`.
+ *
+ * Every action is an ordinary page event, so the app's own handlers, validation
+ * and confirmation dialogs run as they would for the person — and those
+ * dialogs ignore the untrusted clicks scripts make, so an agent can open a
+ * "Delete?" dialog but never answer it.
+ */
+export interface UiToolsOptions {
+    /** Where the agent may look. Default `document.body`. */
+    root?: () => Element | null;
+}
+/**
+ * Would a click on this deserve the person's confirmation?
+ *
+ * ★ Locale-independent signals come first, because a product's labels may be
+ * in any language ("Supprimer", "Eliminar"):
+ *  - `data-agent="confirm"` on the control or a wrapper (product-declared);
+ *  - a destructive button (`data-variant="destructive"`, the shared Button);
+ *  - any control inside an alert dialog except its cancel button
+ *    (`data-slot="alert-dialog-cancel"`): alert dialogs are where the app asks
+ *    "are you sure?", so their action is the consequential step.
+ * The English verb list is an extra net for unmarked controls, not the rule.
+ */
+export declare function isConsequentialControl(element: Element, name: string): boolean;
+export declare function createUiTools(options?: UiToolsOptions): AnyDefinedAgentTool[];

package/dist/shared/agent-tools/ui/uiTools.js

@@ -0,0 +1,277 @@
+import { AgentToolError as e } from "../errors.js";
+import { requestAgentConfirmation as t } from "../confirm/confirmStore.js";
+import { defineAgentTool as n } from "../defineAgentTool.js";
+import { INTERACTIVE_SELECTOR as r, accessibleName as i, isDenied as a, isDisabled as o, isSensitiveField as s, isVisible as c, openDialogTitle as l, roleOf as u, stateOf as d, valueOf as f } from "./dom.js";
+import { REF_PATTERN as p, elementFor as m, pruneRefs as h, refFor as g } from "./refs.js";
+import { z as _ } from "zod";
+//#region src/shared/agent-tools/ui/uiTools.ts
+var v = 1100, y = new TextEncoder(), b = 250, x = 3e3, S = 1200, C = /\b(delete|remove|archive|revoke|deactivate|disable|cancel|terminate|stop|pay|purchase|buy|checkout|transfer|subscribe|unsubscribe|upgrade|downgrade|log ?out|sign ?out|reset|publish|send|invite|uninstall|disconnect|approve|reject)\b/i, w = /^(cancel|close|dismiss|back|no|not now|keep editing)$/i;
+function T(e, t) {
+	if (e.closest("[data-agent=\"confirm\"]") || e.closest("[data-variant=\"destructive\"]")) return !0;
+	if (e.closest("[role=\"alertdialog\"]")) return e.closest("[data-slot=\"alert-dialog-cancel\"]") === null;
+	let n = t.trim();
+	return w.test(n) ? !1 : C.test(n);
+}
+var E = _.string().regex(p, "must be a ref from ui_snapshot, like \"e12\"").describe("The ref of the element, from ui_snapshot (e.g. \"e12\").");
+function D() {
+	return typeof document > "u" ? null : document.body;
+}
+function O(t) {
+	let n = m(t);
+	if (!n) throw new e("NOT_FOUND", "That element is no longer on the page. Take a new ui_snapshot.", { retryable: !0 });
+	if (a(n)) throw new e("FORBIDDEN", "That part of the page is off-limits to agents.");
+	if (!c(n)) throw new e("CONFLICT", "That element is not visible right now. Take a new ui_snapshot.", { retryable: !0 });
+	return n;
+}
+function k(e) {
+	let { outline: t, outlineOffset: n } = e.style;
+	e.style.outline = "2px solid var(--ring)", e.style.outlineOffset = "2px", setTimeout(() => {
+		e.style.outline = t, e.style.outlineOffset = n;
+	}, S);
+}
+function A(e) {
+	e.scrollIntoView?.({
+		block: "center",
+		inline: "nearest"
+	}), k(e);
+}
+function j(e, t) {
+	return new Promise((n) => {
+		let r = e.defaultView;
+		if (!r || typeof r.MutationObserver != "function") {
+			n();
+			return;
+		}
+		let i, a = () => {
+			o.disconnect(), clearTimeout(i), clearTimeout(s), t.removeEventListener("abort", a), n();
+		}, o = new r.MutationObserver(() => {
+			clearTimeout(i), i = setTimeout(a, b);
+		});
+		o.observe(e.body, {
+			childList: !0,
+			subtree: !0,
+			attributes: !0,
+			characterData: !0
+		}), i = setTimeout(a, b);
+		let s = setTimeout(a, x);
+		t.addEventListener("abort", a, { once: !0 });
+	});
+}
+function M(e) {
+	let t = Array.from(e.querySelectorAll("[data-sonner-toast], [role=\"alert\"]")).filter((e) => c(e) && !a(e)).map((e) => (e.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, 120)).filter(Boolean).slice(-3), n = l(e);
+	return {
+		path: e.defaultView?.location.pathname ?? null,
+		...n ? { dialog: n } : {},
+		...t.length > 0 ? { notices: t } : {}
+	};
+}
+function N(e, t) {
+	let n = {
+		bubbles: !0,
+		cancelable: !0,
+		composed: !0,
+		button: 0,
+		view: t
+	};
+	return typeof t.PointerEvent == "function" ? new t.PointerEvent(e, {
+		...n,
+		pointerType: "mouse",
+		isPrimary: !0
+	}) : new t.MouseEvent(e, n);
+}
+function P(e) {
+	let t = e.ownerDocument.defaultView;
+	e.focus?.({ preventScroll: !0 }), t && (e.dispatchEvent(N("pointerdown", t)), e.dispatchEvent(new t.MouseEvent("mousedown", {
+		bubbles: !0,
+		cancelable: !0
+	})), e.dispatchEvent(N("pointerup", t)), e.dispatchEvent(new t.MouseEvent("mouseup", {
+		bubbles: !0,
+		cancelable: !0
+	}))), e.click();
+}
+function F(e, t) {
+	let n = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(e), "value")?.set;
+	n ? n.call(e, t) : e.value = t;
+	let r = e.ownerDocument.defaultView, i = r?.InputEvent ?? r?.Event;
+	i && e.dispatchEvent(new i("input", {
+		bubbles: !0,
+		cancelable: !1,
+		composed: !0
+	})), e.dispatchEvent(new Event("change", { bubbles: !0 }));
+}
+function I(e) {
+	let t = e.closest("a[href]");
+	if (!t) return !1;
+	if (t.target && t.target !== "_self") return !0;
+	let n = e.ownerDocument.defaultView?.location.origin;
+	try {
+		return !!n && new URL(t.href, n).origin !== n;
+	} catch {
+		return !0;
+	}
+}
+function L(p = {}) {
+	let m = p.root ?? D;
+	return [
+		n({
+			name: "ui_snapshot",
+			title: "Read the screen",
+			description: "Lists the controls visible on the page (links, buttons, fields, tabs, menu items) with a ref, role, name, current value and state. Use the refs with ui_click, ui_fill, ui_select and ui_press_key. Take a new snapshot after the page changes. Page through long lists with offset.",
+			input: _.strictObject({
+				filter: _.string().trim().max(60).optional().describe("Only list controls whose name or role contains this text."),
+				offset: _.number().int().min(0).max(5e3).default(0).describe("Index of the first control to list, from nextOffset of a previous call.")
+			}),
+			annotations: {
+				readOnly: !0,
+				untrustedContent: !0
+			},
+			execute: ({ filter: t, offset: n }) => {
+				let o = m();
+				if (!o) throw new e("NEEDS_USER", "The page is not available.");
+				h();
+				let p = t?.toLowerCase(), _ = Array.from(o.querySelectorAll(r)).filter((e) => c(e) && !a(e) && u(e) !== "generic"), b = [];
+				for (let e of _) {
+					let t = u(e), n = i(e);
+					if (p && !`${t} ${n}`.toLowerCase().includes(p)) continue;
+					let r = s(e), a = r ? null : f(e), o = d(e);
+					r && o.push("sensitive"), b.push(`${g(e)} ${t} ${JSON.stringify(n)}${a ? ` value=${JSON.stringify(a)}` : ""}${o.length > 0 ? ` [${o.join(",")}]` : ""}`);
+				}
+				let x = [], S = 0, C = n;
+				for (; C < b.length; C += 1) {
+					let e = b[C] ?? "", t = y.encode(e).length + 3;
+					if (x.length > 0 && S + t > v) break;
+					x.push(e), S += t;
+				}
+				let w = o.ownerDocument, T = w.querySelector("main h1, h1")?.textContent?.replace(/\s+/g, " ").trim(), E = l(w);
+				return {
+					path: w.defaultView?.location.pathname ?? null,
+					...T ? { heading: T.slice(0, 120) } : {},
+					...E ? { dialog: E } : {},
+					total: b.length,
+					items: x,
+					...C < b.length ? { nextOffset: C } : {}
+				};
+			}
+		}),
+		n({
+			name: "ui_click",
+			title: "Click",
+			description: "Clicks a control from ui_snapshot (button, link, tab, menu item, checkbox). Returns the page path, any dialog that opened and new notices. Clicks that delete, cancel, pay or similar first ask the person to confirm.",
+			input: _.strictObject({ ref: E }),
+			execute: async ({ ref: n }, { signal: r }) => {
+				let a = O(n);
+				if (o(a)) throw new e("CONFLICT", "That control is disabled right now.");
+				if (s(a)) throw new e("NEEDS_USER", "That control belongs to a password, key or payment field: ask the person to use it.");
+				if (a instanceof HTMLInputElement && a.type === "file") throw new e("NEEDS_USER", "Choosing a file needs the person: ask them to pick it.");
+				if (I(a)) throw new e("NEEDS_USER", "That link opens outside this tab: ask the person to open it.");
+				let c = i(a), l = u(a);
+				if (T(a, c)) {
+					if (!await t("Click", {
+						title: "Allow this click?",
+						body: `An AI agent wants to click "${c || u(a)}" on this page.`,
+						confirmLabel: "Allow"
+					}, r)) throw new e("CANCELLED", "The person declined this click.");
+					let s = O(n);
+					if (s !== a || o(s) || i(s) !== c || u(s) !== l) throw new e("CONFLICT", "The page changed. Take a new ui_snapshot.", { retryable: !0 });
+				}
+				return A(a), P(a), await j(a.ownerDocument, r), {
+					clicked: c || u(a),
+					...M(a.ownerDocument)
+				};
+			}
+		}),
+		n({
+			name: "ui_fill",
+			title: "Type into a field",
+			description: "Replaces the text of a text field, text area or search box from ui_snapshot. Does not submit; click the submit button or press Enter afterwards. Password, payment and code fields are refused.",
+			input: _.strictObject({
+				ref: E,
+				value: _.string().max(2e3).describe("The text the field should contain.")
+			}),
+			execute: async ({ ref: t, value: n }, { signal: r }) => {
+				let a = O(t);
+				if (s(a)) throw new e("NEEDS_USER", "That is a password, payment or code field: ask the person to fill it.");
+				if (o(a) || a.readOnly) throw new e("CONFLICT", "That field cannot be edited right now.");
+				if (A(a), a.focus?.({ preventScroll: !0 }), a instanceof HTMLInputElement || a instanceof HTMLTextAreaElement) {
+					let t = u(a);
+					if (![
+						"textbox",
+						"searchbox",
+						"combobox",
+						"spinbutton"
+					].includes(t)) throw new e("INVALID_INPUT", `A ${t} is not a text field; use ui_click.`);
+					if (a.maxLength > 0 && n.length > a.maxLength) throw new e("INVALID_INPUT", `That field takes at most ${a.maxLength} characters.`);
+					F(a, n);
+				} else if (a.isContentEditable) a.textContent = n, a.dispatchEvent(new Event("input", { bubbles: !0 }));
+				else throw new e("INVALID_INPUT", "That element is not a text field. Use ui_click, or ui_select for a dropdown.");
+				return await j(a.ownerDocument, r), {
+					filled: i(a),
+					...M(a.ownerDocument)
+				};
+			}
+		}),
+		n({
+			name: "ui_select",
+			title: "Choose an option",
+			description: "Chooses an option in a native dropdown (select) from ui_snapshot, by its visible text or value. For a custom dropdown, ui_click it, take a new ui_snapshot and ui_click the option.",
+			input: _.strictObject({
+				ref: E,
+				option: _.string().trim().min(1).max(200).describe("The option text (or value) to choose.")
+			}),
+			execute: async ({ ref: t, option: n }, { signal: r }) => {
+				let i = O(t);
+				if (!(i instanceof HTMLSelectElement)) throw new e("INVALID_INPUT", "That is not a native dropdown: ui_click it, take a new ui_snapshot, then ui_click the option.");
+				if (o(i)) throw new e("CONFLICT", "That dropdown is disabled.");
+				let a = n.toLowerCase(), s = Array.from(i.options).find((e) => !e.disabled && ((e.textContent ?? "").trim().toLowerCase() === a || e.value.toLowerCase() === a));
+				if (!s) {
+					let t = Array.from(i.options).filter((e) => !e.disabled).slice(0, 15).map((e) => (e.textContent ?? "").trim()).join(", ");
+					throw new e("INVALID_INPUT", `No option "${n.slice(0, 60)}". Options: ${t}`);
+				}
+				A(i);
+				let c = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, "value")?.set;
+				return c ? c.call(i, s.value) : i.value = s.value, i.dispatchEvent(new Event("input", { bubbles: !0 })), i.dispatchEvent(new Event("change", { bubbles: !0 })), await j(i.ownerDocument, r), {
+					selected: (s.textContent ?? "").trim(),
+					...M(i.ownerDocument)
+				};
+			}
+		}),
+		n({
+			name: "ui_press_key",
+			title: "Press a key",
+			description: "Presses a key on a control from ui_snapshot, or on the focused element: Enter to submit or activate, Escape to close a menu or dialog, arrow keys to move in lists.",
+			input: _.strictObject({
+				key: _.enum([
+					"Enter",
+					"Escape",
+					"ArrowUp",
+					"ArrowDown",
+					"ArrowLeft",
+					"ArrowRight"
+				]).describe("The key to press."),
+				ref: E.optional().describe("Element to press it on. Default: the focused element.")
+			}),
+			execute: async ({ key: t, ref: n }, { signal: r }) => {
+				let o = m()?.ownerDocument ?? (typeof document > "u" ? null : document);
+				if (!o) throw new e("NEEDS_USER", "The page is not available.");
+				let s = n ? O(n) : o.activeElement ?? o.body;
+				if (!s) throw new e("NEEDS_USER", "Nothing has focus on the page.");
+				if (a(s)) throw new e("FORBIDDEN", "Focus is in a part of the page that is off-limits to agents.");
+				if (t === "Enter" && T(s, i(s))) throw new e("NEEDS_USER", "Use ui_click on that control: it needs the person to confirm.");
+				s.focus?.({ preventScroll: !0 });
+				let c = o.defaultView?.KeyboardEvent ?? KeyboardEvent, l = {
+					key: t,
+					code: t,
+					bubbles: !0,
+					cancelable: !0,
+					composed: !0
+				};
+				return s.dispatchEvent(new c("keydown", l)), s.dispatchEvent(new c("keyup", l)), await j(o, r), {
+					pressed: t,
+					...M(o)
+				};
+			}
+		})
+	];
+}
+//#endregion
+export { L as createUiTools, T as isConsequentialControl };

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

@@ -0,0 +1,14 @@
+import { AnyDefinedAgentTool } from './types';
+/**
+ * Offer `tools` to agents for as long as the calling component is mounted.
+ *
+ * Call it in the component that owns the state the tools act on — a route's
+ * page for page tools, the builder for canvas tools — so a tool exists exactly
+ * when it can work. Registration is synchronous and removal is by token
+ * (`registry.ts`), so React Strict Mode's mount → unmount → mount and a route
+ * transition's overlapping mount/unmount both end with one registration each.
+ *
+ * `tools` should be stable (module constants, or memoised): a new array
+ * re-registers every tool.
+ */
+export declare function useAgentTools(tools: readonly AnyDefinedAgentTool[], enabled?: boolean): void;

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

@@ -0,0 +1,14 @@
+import { registerAgentTool as e } from "./registry.js";
+import { useEffect as t } from "react";
+//#region src/shared/agent-tools/useAgentTools.ts
+function n(n, r = !0) {
+	t(() => {
+		if (!r) return;
+		let t = n.map((t) => e(t));
+		return () => {
+			for (let e of t) e();
+		};
+	}, [n, r]);
+}
+//#endregion
+export { n as useAgentTools };

package/dist/shared/assistant/api.d.ts

@@ -1,4 +1,5 @@
 import { AssistantUiCatalogue } from './uiActions/uiCatalogue';
+import { ClientToolManifestEntry } from '../agent-tools/adapters/assistant';
 import { AssistantMode, AssistantPromptPart, AssistantRawMessage, AssistantTokenUsage, AssistantSandboxAuthContext, AssistantArtifact, AssistantSessionInfo, DownloadedAssistantArtifact, StreamAccess } from './types';
 import { SandboxWriteCapabilities, WriteApprovalMode, WriteExecutionState } from './writeProposals';
 import { WriteReplyKind, WriteReplyOrigin } from './writeReplyBinder';
@@ -439,6 +440,8 @@ export declare function buildPromptRequestBody(args: {
     writeReply?: AssistantPromptWriteReply | null;
     /** ★ BOFF-8060 (N1b, dormant): the pages this person may be sent to. Absent unless a product opts in. */
     uiCatalogue?: AssistantUiCatalogue | null;
+    /** ★ BOFF-9786: the page's browser tools. Absent unless the sandbox runs them and the page registers some. */
+    clientTools?: readonly ClientToolManifestEntry[] | null;
 }): Record<string, unknown>;
 export interface AssistantPromptGatewayRequest {
     sandboxId: string;
@@ -455,6 +458,8 @@ export interface AssistantPromptGatewayRequest {
     writeReply?: AssistantPromptWriteReply | null;
     /** The navigable pages (BOFF-8060 N1b, dormant). */
     uiCatalogue?: AssistantUiCatalogue | null;
+    /** The page's browser tools (BOFF-9786). */
+    clientTools?: readonly ClientToolManifestEntry[] | null;
 }
 /** The actual unbatched GraphQL body, including context and forwarded-token overhead. */
 export declare function buildPromptGatewayRequest(args: AssistantPromptGatewayRequest): {
@@ -473,6 +478,7 @@ options?: {
     conversationId?: string | null;
     writeReply?: AssistantPromptWriteReply | null;
     uiCatalogue?: AssistantUiCatalogue | null;
+    clientTools?: readonly ClientToolManifestEntry[] | null;
 }): Promise<{
     messageID?: string;
 }>;
@@ -502,7 +508,19 @@ export declare function getAssistantMessages(sandboxId: string, workspaceId: str
      * break the read: an offer is a suggestion, the turn is not.
      */
     surfaceUiOffers?: (offers: unknown, serverNow: number) => void;
+    /**
+     * ★ BOFF-9786: hand the answer's `clientToolRequests` (unparsed) to the
+     * turn's browser-tool runner. Only the panel's turn poller passes it, and
+     * never allowed to break the read.
+     */
+    surfaceClientToolRequests?: (requests: unknown) => void;
 }): Promise<AssistantRawMessage[]>;
+/**
+ * ★ BOFF-9786: answer one browser-tool call with the page's result. The
+ * sandbox accepts it only from the person the call is bound to; a call it has
+ * already ended answers 409, which is not an error worth retrying.
+ */
+export declare function postClientToolResult(sandboxId: string, workspaceId: string, sessionId: string, callId: string, result: unknown, mode: AssistantMode, authContext: AssistantSandboxAuthContext): Promise<void>;
 /**
  * Ask the svc to mint a signed SSE stream URL. Returns null when unavailable
  * (older backend / preview data plane off) → caller falls back to polling.