@burdenoff/fluidgrids-fe-sdk 2026.1111.14 → 2026.1111.16

package/dist/uiMarkTools-nlmzsHQM.js

@@ -0,0 +1,937 @@
+"use client";
+import { r as useTr } from "./TranslationBridge-Da-TPgQm.js";
+import { u as nodesOf } from "./fluidgridsEvents-CNdcrUNN.js";
+import { n as useAgentMarksStore } from "./marksStore-DGCXjTmZ.js";
+import { useEffect, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Sparkles, X } from "lucide-react";
+import { createPortal } from "react-dom";
+import { AgentToolError, INTERACTIVE_SELECTOR, accessibleName, assertNoUnsavedChanges, defineAgentTool, isDenied, roleOf } from "@burdenoff/fe-libs/shared/agent-tools";
+import { z } from "zod";
+
+// src/agentTools/operations.ts
+/**
+* GraphQL operations behind the FluidGrids agent tools (BOFF-9784).
+*
+* Deliberately small selections — an agent gets ~1.5 KB per result, so these
+* ask only for what the tools return. Every document is validated against the
+* composed workspace schema (`graphql/wspace.graphql`) by
+* `operations.test.ts`, so a schema change that breaks one fails CI, not an
+* agent's call.
+*/
+const AGENT_FIND_WORKFLOWS = `
+  query AgentFindWorkflows($input: ListWorkflowDefinitionsInput!) {
+    workflowDefinitions(input: $input) {
+      total
+      hasMore
+      items { id name workflowKey version status updatedAt workspaceId deletedAt description }
+    }
+  }
+`;
+const AGENT_GET_WORKFLOW = `
+  query AgentGetWorkflow($workflowKey: String!, $version: String) {
+    workflowDefinition(workflowKey: $workflowKey, version: $version) {
+      id name workflowKey version status updatedAt description definitionJson totalVersions workspaceId deletedAt
+    }
+  }
+`;
+const AGENT_LIST_RUNS = `
+  query AgentListRuns($input: ListWorkflowRunsInput!) {
+    workflowRuns(input: $input) {
+      total
+      hasMore
+      items { id workflowKey version status mode startedAt completedAt duration errorMessage workflow { name } }
+    }
+  }
+`;
+const AGENT_GET_RUN = `
+  query AgentGetRun($id: ID!) {
+    workflowRun(id: $id) {
+      id workflowKey version status mode startedAt completedAt duration errorMessage errorType
+      totalNodes completedNodes failedNodes
+      workflow { name }
+      nodeStates { nodeId nodeType status error }
+    }
+  }
+`;
+const AGENT_ACTIVATE_WORKFLOW = `
+  mutation AgentActivateWorkflow($id: ID!) {
+    activateWorkflowDefinition(id: $id) { workflowKey version status }
+  }
+`;
+const AGENT_DEACTIVATE_WORKFLOW = `
+  mutation AgentDeactivateWorkflow($id: ID!) {
+    deactivateWorkflowDefinition(id: $id) { workflowKey version status }
+  }
+`;
+const AGENT_TRIGGER_WORKFLOW = `
+  mutation AgentTriggerWorkflow($input: TriggerWorkflowInput!) {
+    triggerWorkflow(input: $input) { runId status workflowKey version }
+  }
+`;
+const AGENT_CANCEL_RUN = `
+  mutation AgentCancelRun($id: ID!) {
+    cancelWorkflowRun(id: $id) { id status }
+  }
+`;
+
+// src/agentTools/fluidgridsAgentTools.ts
+const WORKFLOW_STATUSES = [
+	"ACTIVE",
+	"DRAFT",
+	"ARCHIVED",
+	"DEPRECATED"
+];
+const RUN_STATUSES = [
+	"PENDING",
+	"RUNNING",
+	"WAITING",
+	"COMPLETED",
+	"FAILED",
+	"CANCELLED",
+	"TERMINATED"
+];
+/** Runs that can still be cancelled. */
+const LIVE_RUN_STATUSES = /* @__PURE__ */ new Set([
+	"PENDING",
+	"RUNNING",
+	"WAITING"
+]);
+/** One page of latest versions — the same window the workflows list searches. */
+const SEARCH_WINDOW = 100;
+const MAX_NODE_LABELS = 20;
+const workflowKey = z.string().trim().min(1).max(200).regex(/^[\w.:-]+$/, "must be a workflow key").describe("The workflow key, from fg_workflows_search.");
+const version = z.string().trim().min(1).max(40).regex(/^[\w.-]+$/, "must be a version like 1.0.2").describe("The version, e.g. \"1.0.2\". Omit for the default version.");
+const runId = z.string().trim().min(1).max(100).regex(/^[\w-]+$/, "must be a run id").describe("The run id, from fg_runs_list.");
+const clip = (text, max) => {
+	if (!text) return void 0;
+	const clean = text.replace(/\s+/g, " ").trim();
+	return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+};
+const durationMs = (seconds) => typeof seconds === "number" && Number.isFinite(seconds) ? Math.round(seconds * 1e3) : void 0;
+const workflowPath = (key, ver, view) => `/workflows/${view === "builder" ? "builder" : "workflow"}/${encodeURIComponent(key)}/${encodeURIComponent(ver)}`;
+const runPath = (id) => `/workflows/runs/${encodeURIComponent(id)}`;
+function nodeLabel(node) {
+	const data = node.data && typeof node.data === "object" ? node.data : {};
+	for (const candidate of [
+		data.label,
+		data.name,
+		data.title,
+		node.type
+	]) if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+	return "node";
+}
+/** The trigger nodes of a saved definition, the same test the analytics use. */
+function triggerNodesOf(definition) {
+	return nodesOf(definition).filter((node) => {
+		const type = typeof node.type === "string" ? node.type.toLowerCase() : "";
+		const data = node.data && typeof node.data === "object" ? node.data : {};
+		return type.includes("trigger") || data.isTrigger === true || data.category === "trigger";
+	}).map((node) => {
+		const raw = node;
+		return {
+			id: typeof raw.id === "string" ? raw.id : "",
+			label: nodeLabel(node),
+			type: typeof raw.type === "string" ? raw.type : ""
+		};
+	}).filter((node) => node.id);
+}
+/**
+* Which trigger a manual run starts from: the one asked for, else the manual
+* trigger, else the only trigger. Ambiguity is the agent's to resolve.
+*/
+function pickTriggerNode(triggers, requested) {
+	if (requested) {
+		const match = triggers.find((node) => node.id === requested);
+		if (!match) throw new AgentToolError("INVALID_INPUT", `No trigger "${requested.slice(0, 60)}" in this workflow. Triggers: ${describeTriggers(triggers)}.`);
+		return match;
+	}
+	const manual = triggers.filter((node) => node.type.toLowerCase().includes("manual"));
+	if (manual.length === 1 && manual[0]) return manual[0];
+	if (triggers.length === 1 && triggers[0]) return triggers[0];
+	if (triggers.length === 0) throw new AgentToolError("CONFLICT", "This workflow has no trigger, so it cannot be started. Ask the person to add one in the builder.");
+	throw new AgentToolError("INVALID_INPUT", `This workflow has several triggers; pass triggerNodeId. Triggers: ${describeTriggers(triggers)}.`);
+}
+function describeTriggers(triggers) {
+	return triggers.slice(0, 6).map((node) => `${node.id} (${node.label})`).join(", ") || "none";
+}
+function createFluidGridsAgentTools(deps) {
+	const requireWorkspace = () => {
+		const workspaceId = deps.getWorkspaceId();
+		if (!workspaceId) throw new AgentToolError("NEEDS_USER", "No workspace is selected. Ask the person to choose one.");
+		return workspaceId;
+	};
+	/** A record answered for another workspace (a switch mid-request) is treated as missing. */
+	const sameWorkspace = (record, workspaceId) => !record.workspaceId || record.workspaceId === workspaceId;
+	const getWorkflow = async (key, ver, signal) => {
+		const workspaceId = requireWorkspace();
+		const workflow = (await deps.request({
+			operationName: "AgentGetWorkflow",
+			query: AGENT_GET_WORKFLOW,
+			variables: {
+				workflowKey: key,
+				...ver ? { version: ver } : {}
+			},
+			signal
+		})).workflowDefinition;
+		if (!workflow || workflow.deletedAt || !sameWorkspace(workflow, workspaceId)) throw new AgentToolError("NOT_FOUND", `No workflow "${key.slice(0, 60)}"${ver ? ` version ${ver}` : ""} in this workspace.`);
+		return workflow;
+	};
+	const search = defineAgentTool({
+		name: "fg_workflows_search",
+		title: "Find workflows",
+		description: "Finds workflows in the current FluidGrids workspace by name, description or key, optionally by status. Returns the latest version of each with its key, name, status and version. Use the key with the other fg_ tools.",
+		input: z.strictObject({
+			query: z.string().trim().max(100).optional().describe("Words to look for in the workflow name, description or key. Omit to list all."),
+			status: z.enum(WORKFLOW_STATUSES).optional().describe("Only workflows in this status."),
+			limit: z.number().int().min(1).max(20).default(10).describe("How many to return (1-20)."),
+			offset: z.number().int().min(0).max(SEARCH_WINDOW).default(0).describe("How many matches to skip, for paging.")
+		}),
+		annotations: {
+			readOnly: true,
+			untrustedContent: true
+		},
+		execute: async ({ query, status, limit, offset }, { signal }) => {
+			const workspaceId = requireWorkspace();
+			const filters = deps.listFilters?.();
+			const data = await deps.request({
+				operationName: "AgentFindWorkflows",
+				query: AGENT_FIND_WORKFLOWS,
+				variables: { input: {
+					latestOnly: true,
+					limit: SEARCH_WINDOW,
+					offset: 0,
+					...status ? { status } : {},
+					...filters && Object.keys(filters).length > 0 ? { customFilters: filters } : {}
+				} },
+				signal
+			});
+			const needle = query?.toLowerCase();
+			const matches = (data.workflowDefinitions?.items ?? []).filter((item) => !item.deletedAt && sameWorkspace(item, workspaceId) && (!needle || [
+				item.name,
+				item.description,
+				item.workflowKey
+			].some((field) => field?.toLowerCase().includes(needle))));
+			const page = matches.slice(offset, offset + limit);
+			return {
+				total: matches.length,
+				workflows: page.map((item) => ({
+					workflowKey: item.workflowKey,
+					name: clip(item.name, 80),
+					status: item.status,
+					version: item.version,
+					updatedAt: item.updatedAt
+				})),
+				...offset + page.length < matches.length ? { nextOffset: offset + page.length } : {}
+			};
+		}
+	});
+	const get = defineAgentTool({
+		name: "fg_workflow_get",
+		title: "Read a workflow",
+		description: "Reads one workflow version: name, status, version, number of versions, its triggers and the labels of its nodes. Omit version for the default version.",
+		input: z.strictObject({
+			workflowKey,
+			version: version.optional()
+		}),
+		annotations: {
+			readOnly: true,
+			untrustedContent: true
+		},
+		execute: async ({ workflowKey: key, version: ver }, { signal }) => {
+			const workflow = await getWorkflow(key, ver, signal);
+			const nodes = nodesOf(workflow.definitionJson);
+			return {
+				workflowKey: workflow.workflowKey,
+				name: clip(workflow.name, 80),
+				status: workflow.status,
+				version: workflow.version,
+				totalVersions: workflow.totalVersions ?? void 0,
+				updatedAt: workflow.updatedAt,
+				description: clip(workflow.description, 200),
+				triggers: triggerNodesOf(workflow.definitionJson).map((node) => ({
+					nodeId: node.id,
+					label: clip(node.label, 60)
+				})),
+				nodeCount: nodes.length,
+				nodes: nodes.slice(0, MAX_NODE_LABELS).map((node) => clip(nodeLabel(node), 60))
+			};
+		}
+	});
+	const listRuns = defineAgentTool({
+		name: "fg_runs_list",
+		title: "List runs",
+		description: "Lists recent workflow runs in the current workspace, newest first, optionally for one workflow, by status or since a date. Returns run id, workflow name, status, start time, duration and a short error.",
+		input: z.strictObject({
+			workflowKey: workflowKey.optional(),
+			status: z.enum(RUN_STATUSES).optional().describe("Only runs in this status."),
+			since: z.iso.datetime({ offset: true }).optional().describe("Only runs started at or after this ISO date-time, e.g. 2026-10-27T00:00:00Z."),
+			search: z.string().trim().max(100).optional().describe("Matches a run id prefix, or a workflow key or name."),
+			limit: z.number().int().min(1).max(20).default(10).describe("How many to return (1-20)."),
+			offset: z.number().int().min(0).max(1e4).default(0).describe("How many to skip, for paging.")
+		}),
+		annotations: {
+			readOnly: true,
+			untrustedContent: true
+		},
+		execute: async ({ workflowKey: key, status, since, search: text, limit, offset }, { signal }) => {
+			requireWorkspace();
+			const data = await deps.request({
+				operationName: "AgentListRuns",
+				query: AGENT_LIST_RUNS,
+				variables: { input: {
+					limit,
+					offset,
+					...key ? { workflowKey: key } : {},
+					...status ? { status } : {},
+					...since ? { startDate: since } : {},
+					...text ? { search: text } : {}
+				} },
+				signal
+			});
+			const items = data.workflowRuns?.items ?? [];
+			return {
+				total: data.workflowRuns?.total ?? items.length,
+				runs: items.map((run) => ({
+					runId: run.id,
+					workflowKey: run.workflowKey,
+					workflowName: clip(run.workflow?.name, 60),
+					version: run.version,
+					status: run.status,
+					...run.mode === "TEST" ? { mode: "TEST" } : {},
+					startedAt: run.startedAt ?? void 0,
+					durationMs: durationMs(run.duration),
+					error: clip(run.errorMessage, 120)
+				})),
+				...data.workflowRuns?.hasMore ? { nextOffset: offset + items.length } : {}
+			};
+		}
+	});
+	const getRun = defineAgentTool({
+		name: "fg_run_get",
+		title: "Read a run",
+		description: "Reads one workflow run: status, timing, node counts, the nodes that failed and the error. Use it to explain why a run failed.",
+		input: z.strictObject({ runId }),
+		annotations: {
+			readOnly: true,
+			untrustedContent: true
+		},
+		execute: async ({ runId: id }, { signal }) => {
+			requireWorkspace();
+			const run = (await deps.request({
+				operationName: "AgentGetRun",
+				query: AGENT_GET_RUN,
+				variables: { id },
+				signal
+			})).workflowRun;
+			if (!run) throw new AgentToolError("NOT_FOUND", "No run with that id in this workspace.");
+			const failed = (run.nodeStates ?? []).filter((node) => node.status === "FAILED");
+			return {
+				runId: run.id,
+				workflowKey: run.workflowKey,
+				workflowName: clip(run.workflow?.name, 60),
+				version: run.version,
+				status: run.status,
+				mode: run.mode,
+				startedAt: run.startedAt ?? void 0,
+				completedAt: run.completedAt ?? void 0,
+				durationMs: durationMs(run.duration),
+				nodes: {
+					total: run.totalNodes ?? void 0,
+					completed: run.completedNodes ?? void 0,
+					failed: run.failedNodes ?? void 0
+				},
+				failedNodes: failed.slice(0, 3).map((node) => ({
+					nodeId: node.nodeId,
+					type: node.nodeType,
+					error: clip(node.error, 200)
+				})),
+				error: clip(run.errorMessage, 300),
+				errorType: run.errorType ?? void 0
+			};
+		}
+	});
+	const open = defineAgentTool({
+		name: "fg_workflow_open",
+		title: "Open a workflow or run",
+		description: "Opens a workflow (its details page or the builder) or a run in the person's tab. Pass workflowKey (and optionally version and view) or runId. Refused while the page has unsaved changes.",
+		input: z.strictObject({
+			workflowKey: workflowKey.optional(),
+			version: version.optional(),
+			view: z.enum(["details", "builder"]).default("details").describe("For a workflow: its details page or the builder."),
+			runId: runId.optional()
+		}),
+		annotations: { navigation: true },
+		execute: async ({ workflowKey: key, version: ver, view, runId: id }, { signal }) => {
+			if (!key === !id) throw new AgentToolError("INVALID_INPUT", "Pass either workflowKey or runId.");
+			assertNoUnsavedChanges();
+			let path;
+			if (id) path = runPath(id);
+			else {
+				const workflow = await getWorkflow(key ?? "", ver, signal);
+				path = workflowPath(workflow.workflowKey ?? key ?? "", workflow.version ?? ver ?? "", view);
+			}
+			deps.navigate(path);
+			return { navigatedTo: path };
+		}
+	});
+	const setActive = (activate) => defineAgentTool({
+		name: activate ? "fg_workflow_activate" : "fg_workflow_deactivate",
+		title: activate ? "Activate a workflow version" : "Deactivate a workflow version",
+		description: activate ? "Makes one version of a workflow the active one, so its triggers (schedules, webhooks, app events) start running it. The previously active version is archived. Asks the person to confirm." : "Deactivates the active version of a workflow, so its triggers stop starting runs. Asks the person to confirm.",
+		input: z.strictObject({
+			workflowKey,
+			version: version.describe("The version to change.")
+		}),
+		annotations: { consequential: true },
+		confirm: ({ workflowKey: key, version: ver }) => ({
+			title: activate ? "Activate this workflow version?" : "Deactivate this workflow?",
+			body: activate ? `Workflow "${key}" version ${ver} becomes the active version and its triggers start running it. The version active now is archived.` : `Workflow "${key}" version ${ver} stops running: its schedules, webhooks and app-event triggers stop starting runs.`,
+			confirmLabel: activate ? "Activate" : "Deactivate"
+		}),
+		execute: async ({ workflowKey: key, version: ver }, { signal }) => {
+			const workflow = await getWorkflow(key, ver, signal);
+			if (!workflow.id) throw new AgentToolError("NOT_FOUND", "That workflow version has no id.");
+			if (activate && workflow.status === "ACTIVE") return {
+				workflowKey: key,
+				version: ver,
+				status: "ACTIVE",
+				changed: false
+			};
+			if (!activate && workflow.status !== "ACTIVE") throw new AgentToolError("CONFLICT", `That version is ${workflow.status}, not ACTIVE.`);
+			const result = (await deps.request({
+				operationName: activate ? "AgentActivateWorkflow" : "AgentDeactivateWorkflow",
+				query: activate ? AGENT_ACTIVATE_WORKFLOW : AGENT_DEACTIVATE_WORKFLOW,
+				variables: { id: workflow.id },
+				signal
+			}))[activate ? "activateWorkflowDefinition" : "deactivateWorkflowDefinition"];
+			if (!result?.status) throw new AgentToolError("FAILED", "The backend did not confirm the change.");
+			return {
+				workflowKey: key,
+				version: result.version ?? ver,
+				status: result.status,
+				changed: true
+			};
+		}
+	});
+	const run = defineAgentTool({
+		name: "fg_workflow_run",
+		title: "Run a workflow",
+		description: "Starts a production run of a workflow's active version from its manual trigger (or the given trigger), with optional input data. Uses the workspace's run quota. Asks the person to confirm. Returns the run id; follow it with fg_run_get.",
+		input: z.strictObject({
+			workflowKey,
+			triggerNodeId: z.string().trim().min(1).max(100).optional().describe("The trigger to start from, from fg_workflow_get. Omit for the manual trigger."),
+			input: z.string().max(4e3).optional().describe("Input data for the trigger as a JSON object string, e.g. {\"email\":\"a@b.co\"}.")
+		}),
+		annotations: { consequential: true },
+		confirm: ({ workflowKey: key, input }) => ({
+			title: "Run this workflow?",
+			body: `Start a production run of workflow "${key}"${input ? " with the input the agent prepared" : ""}. It counts toward this workspace's runs and its steps take effect.`,
+			confirmLabel: "Run workflow"
+		}),
+		execute: async ({ workflowKey: key, triggerNodeId, input }, { signal }) => {
+			let triggerData;
+			if (input) {
+				let parsed;
+				try {
+					parsed = JSON.parse(input);
+				} catch {
+					throw new AgentToolError("INVALID_INPUT", "input must be a JSON object string.");
+				}
+				if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new AgentToolError("INVALID_INPUT", "input must be a JSON object.");
+				triggerData = parsed;
+			}
+			const workflow = await getWorkflow(key, void 0, signal);
+			if (workflow.status !== "ACTIVE" || !workflow.version) throw new AgentToolError("CONFLICT", "Only an active workflow version can be run here. Activate a version first, or ask the person to test it in the builder.");
+			const trigger = pickTriggerNode(triggerNodesOf(workflow.definitionJson), triggerNodeId);
+			const started = (await deps.request({
+				operationName: "AgentTriggerWorkflow",
+				query: AGENT_TRIGGER_WORKFLOW,
+				variables: { input: {
+					workflowKey: key,
+					version: workflow.version,
+					triggerNodeId: trigger.id,
+					mode: "PRODUCTION",
+					idempotencyKey: `agent-${crypto.randomUUID()}`,
+					...triggerData ? { triggerData } : {}
+				} },
+				signal
+			})).triggerWorkflow;
+			if (!started?.runId) throw new AgentToolError("FAILED", "The workflow did not start.");
+			return {
+				runId: started.runId,
+				status: started.status,
+				workflowKey: key,
+				version: started.version ?? workflow.version,
+				trigger: clip(trigger.label, 60)
+			};
+		}
+	});
+	const cancel = defineAgentTool({
+		name: "fg_run_cancel",
+		title: "Cancel a run",
+		description: "Cancels a workflow run that is pending, running or waiting. Steps already done are not undone. Asks the person to confirm.",
+		input: z.strictObject({ runId }),
+		annotations: { consequential: true },
+		confirm: ({ runId: id }) => ({
+			title: "Cancel this run?",
+			body: `Run ${id} stops. Steps it already completed are not undone.`,
+			confirmLabel: "Cancel run"
+		}),
+		execute: async ({ runId: id }, { signal }) => {
+			requireWorkspace();
+			const status = (await deps.request({
+				operationName: "AgentGetRun",
+				query: AGENT_GET_RUN,
+				variables: { id },
+				signal
+			})).workflowRun?.status;
+			if (!status) throw new AgentToolError("NOT_FOUND", "No run with that id in this workspace.");
+			if (!LIVE_RUN_STATUSES.has(status)) throw new AgentToolError("CONFLICT", `That run already finished (${status}).`);
+			const data = await deps.request({
+				operationName: "AgentCancelRun",
+				query: AGENT_CANCEL_RUN,
+				variables: { id },
+				signal
+			});
+			if (!data.cancelWorkflowRun?.status) throw new AgentToolError("FAILED", "The backend did not confirm the cancellation.");
+			return {
+				runId: id,
+				status: data.cancelWorkflowRun.status
+			};
+		}
+	});
+	return [
+		search,
+		get,
+		listRuns,
+		getRun,
+		open,
+		setActive(true),
+		setActive(false),
+		run,
+		cancel
+	];
+}
+
+// src/agentMarks/findTargets.ts
+/**
+* ★ BOFF-11584: find what the assistant wants to point at, the way assistive
+* technology names it — the same view `ui_snapshot` gives the agent.
+*
+* Besides the controls `ui_snapshot` lists, headings and labelled regions can
+* be pointed at ("the Run history section is here"). Regions an agent may not
+* see (`data-agent="deny"`, the assistant's own panel, confirmation dialogs,
+* and the marks overlay itself) are never candidates.
+*/
+const LANDMARK_SELECTOR = [
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"[role=\"heading\"]",
+	"[role=\"tabpanel\"][aria-label]",
+	"[role=\"region\"][aria-label]",
+	"[role=\"region\"][aria-labelledby]",
+	"section[aria-label]",
+	"section[aria-labelledby]",
+	"nav[aria-label]",
+	"aside[aria-label]",
+	"form[aria-label]"
+].join(", ");
+const POINTABLE_SELECTOR = `${INTERACTIVE_SELECTOR}, ${LANDMARK_SELECTOR}`;
+const LANDMARK_ROLE = {
+	h1: "heading",
+	h2: "heading",
+	h3: "heading",
+	h4: "heading",
+	section: "region",
+	nav: "navigation",
+	aside: "complementary",
+	form: "form"
+};
+/** The role an agent knows the element by. */
+function pointableRole(element) {
+	const role = roleOf(element);
+	if (role !== "generic") return role;
+	return LANDMARK_ROLE[element.tagName.toLowerCase()] ?? role;
+}
+/**
+* Rendered and reachable: connected, not hidden, not inert, not behind a modal
+* (a modal dialog marks the rest of the page `aria-hidden`), not
+* `display: none` / `visibility: hidden`.
+*/
+function isPointable(element) {
+	if (!element.isConnected) return false;
+	if (element.closest("[hidden], [inert], [aria-hidden=\"true\"]")) return false;
+	if (isDenied(element)) return false;
+	const withCheck = element;
+	if (typeof withCheck.checkVisibility === "function") return withCheck.checkVisibility({ checkVisibilityCSS: true });
+	const view = element.ownerDocument.defaultView;
+	if (!view) return true;
+	for (let node = element; node; node = node.parentElement) {
+		const style = view.getComputedStyle(node);
+		if (style.display === "none" || style.visibility === "hidden") return false;
+	}
+	return true;
+}
+function normalise(text) {
+	return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+function rankOf(name, needle) {
+	const value = normalise(name);
+	if (!value) return null;
+	if (value === needle) return 0;
+	if (value.startsWith(needle)) return 1;
+	if (value.includes(needle)) return 2;
+	return null;
+}
+/**
+* Every visible element whose accessible name holds `name` (and, when given,
+* whose role is `role`), best match first and in page order within a rank.
+* An element nested in another match with the same name (a heading's inner
+* link, say) is dropped in favour of the outer one only when both rank alike.
+*/
+function findPointTargets(root, query) {
+	const needle = normalise(query.name);
+	if (!needle) return [];
+	const wantedRole = query.role?.toLowerCase();
+	const matches = [];
+	for (const element of Array.from(root.querySelectorAll(POINTABLE_SELECTOR))) {
+		const role = pointableRole(element);
+		if (role === "generic") continue;
+		if (wantedRole && role !== wantedRole) continue;
+		const name = accessibleName(element);
+		const rank = rankOf(name, needle);
+		if (rank === null) continue;
+		if (!isPointable(element)) continue;
+		matches.push({
+			element,
+			role,
+			name,
+			rank
+		});
+	}
+	return matches.filter((match) => !matches.some((other) => other !== match && other.rank === match.rank && normalise(other.name) === normalise(match.name) && other.element.contains(match.element))).sort((a, b) => a.rank - b.rank);
+}
+/**
+* Where `element` sits among the visible elements with the same role and
+* exact name (1-based), so it can be found again after a re-render replaces
+* the node.
+*/
+function positionAmongTwins(root, match) {
+	const index = findPointTargets(root, {
+		name: match.name,
+		role: match.role
+	}).filter((other) => normalise(other.name) === normalise(match.name)).findIndex((other) => other.element === match.element);
+	return index < 0 ? 1 : index + 1;
+}
+/** Find a callout's element again: same role, same exact name, same position. */
+function refindTarget(root, target) {
+	return findPointTargets(root, {
+		name: target.name,
+		role: target.role
+	}).filter((other) => normalise(other.name) === normalise(target.name))[target.nth - 1]?.element ?? null;
+}
+/** The candidates the person could mean, as one line each for the agent. */
+function describeMatches(matches, limit = 6) {
+	return matches.slice(0, limit).map((match, index) => `${index + 1}. ${match.role} ${JSON.stringify(match.name)}`).join("; ");
+}
+
+// src/agentMarks/AgentCalloutOverlay.tsx
+const RING_PAD = 4;
+const BUBBLE_GAP = 10;
+const BUBBLE_MAX_WIDTH = 280;
+/** Room the bubble needs below the element before it flips above. */
+const BUBBLE_ROOM = 120;
+const EDGE = 8;
+const REFIND_EVERY_MS = 400;
+function boxOf(element) {
+	if (!isPointable(element)) return null;
+	const rect = element.getBoundingClientRect();
+	if (rect.width === 0 && rect.height === 0) return null;
+	return {
+		top: Math.round(rect.top),
+		left: Math.round(rect.left),
+		width: Math.round(rect.width),
+		height: Math.round(rect.height)
+	};
+}
+/** Where each callout's element is now (null: not on screen). */
+function useCalloutBoxes(callouts) {
+	const [boxes, setBoxes] = useState({});
+	useEffect(() => {
+		if (callouts.length === 0) {
+			setBoxes({});
+			return;
+		}
+		const lastRefind = /* @__PURE__ */ new Map();
+		let frame = 0;
+		let previous = "";
+		const tick = () => {
+			const here = window.location.pathname;
+			if (callouts.some((callout) => callout.route !== here)) {
+				useAgentMarksStore.getState().actions.dropCalloutsOffRoute(here);
+				return;
+			}
+			const next = {};
+			for (const callout of callouts) {
+				let element = callout.element?.deref() ?? null;
+				if (!element?.isConnected) {
+					element = null;
+					const now = Date.now();
+					if (now - (lastRefind.get(callout.id) ?? 0) >= REFIND_EVERY_MS) {
+						lastRefind.set(callout.id, now);
+						const found = refindTarget(document.body, callout.target);
+						if (found) {
+							useAgentMarksStore.getState().actions.rebindCallout(callout.id, found);
+							return;
+						}
+					}
+				}
+				next[callout.id] = element ? boxOf(element) : null;
+			}
+			const key = JSON.stringify(next);
+			if (key !== previous) {
+				previous = key;
+				setBoxes(next);
+			}
+			frame = requestAnimationFrame(tick);
+		};
+		tick();
+		return () => cancelAnimationFrame(frame);
+	}, [callouts]);
+	return boxes;
+}
+/** Clicking the element pointed at (the person found it) or Escape clears. */
+function useDismissals(callouts) {
+	useEffect(() => {
+		if (callouts.length === 0) return;
+		const { removeCallout, clearCallouts } = useAgentMarksStore.getState().actions;
+		const onPointerDown = (event) => {
+			const target = event.target;
+			if (!(target instanceof Node)) return;
+			for (const callout of callouts) if (callout.element?.deref()?.contains(target)) removeCallout(callout.id);
+		};
+		const onKeyDown = (event) => {
+			if (event.key === "Escape") clearCallouts();
+		};
+		document.addEventListener("pointerdown", onPointerDown, true);
+		document.addEventListener("keydown", onKeyDown);
+		return () => {
+			document.removeEventListener("pointerdown", onPointerDown, true);
+			document.removeEventListener("keydown", onKeyDown);
+		};
+	}, [callouts]);
+}
+/**
+* Below the element when there is room, otherwise above; kept inside the
+* viewport and clear of the docked assistant panel.
+*/
+function placeBubble(box, viewport, rightInset) {
+	const usableRight = Math.max(viewport.width - rightInset - EDGE, 16);
+	const maxWidth = Math.min(BUBBLE_MAX_WIDTH, usableRight - EDGE);
+	const left = Math.min(Math.max(box.left, EDGE), Math.max(usableRight - maxWidth, EDGE));
+	const below = box.top + box.height + RING_PAD + BUBBLE_GAP;
+	if (below + BUBBLE_ROOM <= viewport.height || box.top < BUBBLE_ROOM) return {
+		top: below,
+		left,
+		maxWidth
+	};
+	return {
+		bottom: viewport.height - box.top + RING_PAD + BUBBLE_GAP,
+		left,
+		maxWidth
+	};
+}
+const AgentCalloutOverlay = ({ rightInset = 0 }) => {
+	const tr = useTr();
+	const callouts = useAgentMarksStore((state) => state.callouts);
+	const boxes = useCalloutBoxes(callouts);
+	useDismissals(callouts);
+	if (callouts.length === 0 || typeof document === "undefined") return null;
+	const viewport = {
+		width: window.innerWidth,
+		height: window.innerHeight
+	};
+	return createPortal(/* @__PURE__ */ jsx("div", {
+		"data-agent": "deny",
+		"data-testid": "fg-agent-callouts",
+		className: "pointer-events-none fixed inset-0 z-[1000]",
+		children: callouts.map((callout) => {
+			const box = boxes[callout.id];
+			if (!box) return null;
+			const placement = placeBubble(box, viewport, rightInset);
+			return /* @__PURE__ */ jsxs("div", {
+				"data-testid": "fg-agent-callout",
+				children: [/* @__PURE__ */ jsx("div", {
+					"aria-hidden": "true",
+					"data-testid": "fg-agent-callout-ring",
+					className: "absolute rounded-md ring-2 ring-primary ring-offset-2 ring-offset-background motion-safe:animate-pulse",
+					style: {
+						top: box.top - RING_PAD,
+						left: box.left - RING_PAD,
+						width: box.width + 8,
+						height: box.height + 8
+					}
+				}), /* @__PURE__ */ jsx("div", {
+					role: "status",
+					className: "pointer-events-auto absolute rounded-lg border border-border bg-popover p-3 text-sm text-foreground shadow-lg",
+					style: {
+						top: placement.top,
+						bottom: placement.bottom,
+						left: placement.left,
+						maxWidth: placement.maxWidth
+					},
+					children: /* @__PURE__ */ jsxs("div", {
+						className: "flex items-start gap-2",
+						children: [
+							/* @__PURE__ */ jsx(Sparkles, {
+								"aria-hidden": "true",
+								className: "mt-0.5 size-4 shrink-0 text-primary"
+							}),
+							/* @__PURE__ */ jsx("p", {
+								"data-testid": "fg-agent-callout-label",
+								className: "min-w-0 whitespace-pre-line break-words",
+								children: callout.label
+							}),
+							/* @__PURE__ */ jsx("button", {
+								type: "button",
+								"aria-label": tr("fluidgrids.agentMarks.dismissCallout", "Dismiss"),
+								onClick: () => useAgentMarksStore.getState().actions.removeCallout(callout.id),
+								className: "-m-1 shrink-0 rounded p-1 text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+								children: /* @__PURE__ */ jsx(X, {
+									"aria-hidden": "true",
+									className: "size-4"
+								})
+							})
+						]
+					})
+				})]
+			}, callout.id);
+		})
+	}), document.body);
+};
+
+// src/agentMarks/uiMarkTools.ts
+/**
+* ★ BOFF-11584: show the person where something is.
+*
+*  - `fg_ui_point_at` draws a labelled callout on one control or heading.
+*  - `fg_ui_clear_marks` removes the assistant's callouts and canvas notes.
+*
+* Both are read-only: they change nothing in the workspace, only what the
+* overlay draws, so Ask (promised read-only) may offer them too
+* (fe-libs `isReadOnlyModeTool`). The overlay is `AgentCalloutOverlay`.
+*/
+/** How long to wait for the element after a navigation. */
+const POINT_WAIT_MS = 3e3;
+const POINT_POLL_MS = 150;
+const ROLE_PATTERN = /^[a-z]{2,24}$/;
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal.aborted) {
+			reject(new AgentToolError("CANCELLED", "The call was cancelled."));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new AgentToolError("CANCELLED", "The call was cancelled."));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** Matches as soon as there are any, or none after the wait. */
+async function waitForMatches(root, query, waitMs, signal) {
+	const deadline = Date.now() + waitMs;
+	for (;;) {
+		const scope = root();
+		const matches = scope ? findPointTargets(scope, query) : [];
+		if (matches.length > 0 || Date.now() >= deadline) return matches;
+		await sleep(POINT_POLL_MS, signal);
+	}
+}
+function pick(matches, nth) {
+	if (nth !== void 0) {
+		const chosen = matches[nth - 1];
+		if (!chosen) throw new AgentToolError("INVALID_INPUT", `Only ${matches.length} match: ${describeMatches(matches)}.`);
+		return chosen;
+	}
+	const best = matches.filter((match) => match.rank === matches[0]?.rank);
+	if (best.length === 1 && best[0]) return best[0];
+	throw new AgentToolError("INVALID_INPUT", `${matches.length} elements match: ${describeMatches(matches)}. Call again with nth, or a fuller name or a role.`);
+}
+function createUiMarkTools(options = {}) {
+	const root = options.root ?? (() => typeof document === "undefined" ? null : document.body);
+	const waitMs = options.waitMs ?? 3e3;
+	return [defineAgentTool({
+		name: "fg_ui_point_at",
+		title: "Point at something on screen",
+		description: "Shows the person where a control or heading is: scrolls it into view and draws a callout with your label beside it. Use it when they ask where something is or how to do something on this page. Open the right page first (app_navigate). The callout stays until they click the control, close it, or leave the page.",
+		input: z.strictObject({
+			name: z.string().trim().min(1).max(80).describe("The visible name of the control or heading, as on screen or in ui_snapshot, e.g. Cancel run."),
+			role: z.string().trim().toLowerCase().regex(ROLE_PATTERN, "a role like button, link, tab or heading").optional().describe("Only match this role: button, link, tab, menuitem, textbox, combobox, switch, heading, region…"),
+			nth: z.number().int().min(1).max(20).optional().describe("Which match to use, 1-based, when several elements match (the error lists them)."),
+			label: z.string().trim().min(1).max(200).describe("Short plain text shown beside it, e.g. Click here to cancel the run. No markdown.")
+		}),
+		annotations: {
+			readOnly: true,
+			untrustedContent: true
+		},
+		execute: async ({ name, role, nth, label }, { signal }) => {
+			const matches = await waitForMatches(root, role ? {
+				name,
+				role
+			} : { name }, waitMs, signal);
+			if (matches.length === 0) throw new AgentToolError("NOT_FOUND", `Nothing named "${name.slice(0, 60)}"${role ? ` with role ${role}` : ""} is visible on this page. Open the right page (app_navigate) or check names with ui_snapshot.`, { retryable: true });
+			const chosen = pick(matches, nth);
+			const scope = root();
+			const callout = useAgentMarksStore.getState().actions.addCallout({
+				label,
+				element: chosen.element,
+				route: chosen.element.ownerDocument.defaultView?.location.pathname ?? "",
+				target: {
+					role: chosen.role,
+					name: chosen.name,
+					nth: scope ? positionAmongTwins(scope, chosen) : 1
+				}
+			});
+			chosen.element.scrollIntoView?.({
+				block: "center",
+				inline: "nearest"
+			});
+			return {
+				shown: true,
+				pointedAt: {
+					role: chosen.role,
+					name: chosen.name
+				},
+				calloutId: callout.id,
+				...matches.length > 1 ? { otherMatches: matches.length - 1 } : {}
+			};
+		}
+	}), defineAgentTool({
+		name: "fg_ui_clear_marks",
+		title: "Clear the assistant's marks",
+		description: "Removes the callouts you drew with fg_ui_point_at and, when asked, the notes you pinned on workflow nodes (all workflows). Only when the person asks to clear them or a callout no longer applies.",
+		input: z.strictObject({ which: z.enum([
+			"callouts",
+			"notes",
+			"all"
+		]).default("callouts").describe("callouts (default), notes, or all.") }),
+		annotations: { readOnly: true },
+		execute: ({ which }) => {
+			const { actions } = useAgentMarksStore.getState();
+			return {
+				clearedCallouts: which === "notes" ? 0 : actions.clearCallouts(),
+				clearedNotes: which === "callouts" ? 0 : actions.clearNotes()
+			};
+		}
+	})];
+}
+
+export { triggerNodesOf as a, pickTriggerNode as i, AgentCalloutOverlay as n, createFluidGridsAgentTools as r, createUiMarkTools as t };