@f5-sales-demo/xcsh 19.51.2

package/src/internal-urls/extension-api.md

@@ -0,0 +1,147 @@
+# xcsh Chrome Extension Bridge — Tool API Reference
+
+> Surfaced via `xcsh://extension`. The xcsh assistant drives the browser through
+> the Chrome extension bridge (native messaging → service worker → CDP). Knowing
+> which tool to use — and which to avoid — for each interaction is essential for
+> deterministic, non-fragile automation.
+
+---
+
+## Deterministic click path (PREFERRED)
+
+### `click_element { js, wait_ms? }`
+**Use for:** clicking any element that exists in the page's main document.
+
+`js` is a JavaScript expression that returns the target **Element** (or null). The
+extension resolves geometry from the renderer (`DOM.getContentQuads` — CSS viewport
+px with transforms/zoom/DPR baked in) and **hit-tests** the point
+(`document.elementFromPoint`) before dispatching the trusted click. On occlusion it
+re-scrolls once, then **fails loudly** naming the occluder — never a silent mis-click.
+`wait_ms` polls for async elements (CDK portals, lazy content).
+
+**Guarantees:**
+- Deterministic across window sizes and zoom levels (layout-engine coords, not JS rects).
+- Catches overlays (CDK portals, dialogs) and tells you what's in the way.
+- Holds the element handle atomically across scroll → measure → verify → click.
+
+**Build the `js` arg via** `buildElementResolverScript(selector)` (the same catalogue
+selector grammar: `text('…')`, `role:text('…')`, `role[name='…']`, CSS, row-scoped `>>`)
+so the click resolves the same element the workflow YAML names.
+
+---
+
+### `click { ref }`
+Use when you already have an AX `ref` handle (from `read_ax`). Routes through
+`click_element` internally — same determinism guarantees.
+
+### `click_xy { x, y }`
+**Last-resort.** Only for viewport points with no backing element (e.g. a computed
+portal-overlay coordinate, or testing a specific pixel). Skips hit-testing.
+
+---
+
+## CDK-portal / typeahead (REQUIRED for CDK portals)
+
+### `label_select { selector, value, label_value?, wait_ms? }`
+**Use for:** any CDK-portal typeahead (`.cdk-overlay-container`): label-selector
+key/operator/value steps, vsui "Type to search" inputs.
+
+The extension keeps the input **focused throughout** (uses plain `Runtime.evaluate`,
+NOT `evaluateWithRecovery` which detaches the debugger and kills focus). It:
+1. Clicks the input (focus).
+2. Types `value` via `Input.insertText` (keeps focus).
+3. Polls the CDK portal for a matching option (`span` in `.cdk-overlay-container`).
+4. Clicks the option via trusted CDP.
+5. If `label_value` is provided, enters it into the value field that appears (uses the
+   secret-textarea real-typing path if it's a `<textarea>`).
+
+**Why mandatory for CDK portals:** `javascript_tool` routes through `evaluateWithRecovery`
+which DETACHES the CDP debugger on timeout — killing input focus and closing the portal.
+`label_select` uses plain `Runtime.evaluate` and holds focus end-to-end.
+
+---
+
+## Input (trusted)
+
+### `type_text { text }`
+Inserts text via `Input.insertText` into the currently-focused element. Fires genuine
+trusted input events that Angular's ControlValueAccessor and vsui pick up. Use this
+(or `fill` via page-actions) for text fields, not programmatic value setting.
+
+### `key_press { key }`
+Dispatches a trusted `Input.dispatchKeyEvent` (keyDown + keyUp) for the named key
+(e.g. `"Enter"`, `"Tab"`, `"Escape"`, `"Backspace"`).
+
+### `form_input { ref, value }`
+Sets a form field's value via `Runtime.callFunctionOn` — the Angular-compat path that
+bypasses vsui's value-descriptor patching. Use when `fill` isn't available.
+
+---
+
+## DOM inspection (caution: defocuses active input)
+
+### `javascript_tool { code }`
+Evaluates arbitrary JavaScript and returns the result. Routes through
+`evaluateWithRecovery` — **IMPORTANT: this defocuses the currently-focused input and
+closes any open CDK portal / vsui dropdown.** Never call it between a typeahead open
+and a portal selection. Safe for reading DOM state BEFORE opening a typeahead.
+
+### `read_ax { }` / `find { selector }`
+Reads the accessibility tree or finds AX nodes by selector. Both freeze the MV3
+service worker on heavy F5 XC SPA pages (30s+) — prefer `javascript_tool` for quick
+DOM queries. `read_ax` is usable on lighter pages.
+
+### `get_page_text { }`
+Returns the visible text content of the current page.
+
+---
+
+## Navigation
+
+### `navigate { url }`
+Navigates to a URL. Auto-accepts `beforeunload` ("Leave site?") dialogs — so a dirty
+form's dialog does NOT block navigation. Wait for the target page to settle before
+querying the DOM.
+
+### `wait_for { selector, context?, timeoutMs? }` / `assert_text { selector, expected }`
+Wait for an element to appear / assert text. Use these as post-navigation settle points.
+
+---
+
+## Tab management
+
+### `tabs_list`, `tabs_create`, `tabs_close`
+Enumerate, open, and close browser tabs. Useful for multi-tab flows or checking that a
+navigation landed on the intended page.
+
+---
+
+## Screenshot (avoid in automation)
+
+### `screenshot { }` → base64 JPEG
+Captures a scaled canvas screenshot. **Avoid in automation loops** — `captureVisibleTab`
+freezes the MV3 service worker event loop on retina Mac displays, blocking all
+subsequent bridge requests for several seconds.
+
+---
+
+## Debugging tools
+
+### `read_console { pattern? }` / `read_network { pattern? }`
+Read Chrome DevTools console logs or network requests. Use for debugging — not required
+in deterministic create/read/update/delete flows.
+
+---
+
+## Summary: which tool for which job
+
+| Situation | Tool |
+|-----------|------|
+| Click a button/tab/link in the page | `click_element` (buildElementResolverScript) |
+| Click inside a CDK portal option | `label_select` (the ONLY reliable path) |
+| Fill a text input | page-actions `fill` → `type_text` under the hood |
+| Select from a vsui listbox | page-actions `selectOption` → `click_element` + poll |
+| Need current DOM state | `javascript_tool` (but check there's no open typeahead first) |
+| Navigate between pages | `navigate` |
+| Verify something appeared | `wait_for` / `assert_text` |
+| Raw coordinates only | `click_xy` (last resort) |

package/src/internal-urls/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal URL routing system for internal protocols like agent://, memory://, skill://, mcp://, and local://.
+ *
+ * This module provides a unified way to resolve internal URLs without
+ * exposing filesystem paths to the agent.
+ *
+ * @example
+ * ```ts
+ * import { InternalUrlRouter, AgentProtocolHandler, MemoryProtocolHandler, SkillProtocolHandler } from './internal-urls';
+ *
+ * const router = new InternalUrlRouter();
+ * router.register(new AgentProtocolHandler({ getArtifactsDir: () => sessionDir }));
+ * router.register(new MemoryProtocolHandler({ getMemoryRoot: () => memoryRoot }));
+ * router.register(new SkillProtocolHandler({ getSkills: () => skills }));
+ *
+ * if (router.canHandle('agent://reviewer_0')) {
+ *   const resource = await router.resolve('agent://reviewer_0');
+ *   console.log(resource.content);
+ * }
+ * ```
+ */
+
+export * from "./agent-protocol";
+export * from "./api-catalog-resolve";
+export * from "./api-catalog-types";
+export * from "./api-spec-resolve";
+export * from "./api-spec-types";
+export * from "./artifact-protocol";
+export * from "./computer-profile";
+export * from "./console-catalog-types";
+export * from "./console-resolve";
+export * from "./jobs-protocol";
+export * from "./json-query";
+export * from "./local-protocol";
+export * from "./mcp-protocol";
+export * from "./memory-protocol";
+export * from "./parse";
+export * from "./profile-collectors";
+export * from "./router";
+export * from "./rule-protocol";
+export * from "./skill-protocol";
+export * from "./terraform-resolve";
+export type * from "./terraform-types";
+export type * from "./types";
+export * from "./user-profile";
+export * from "./xcsh-protocol";

package/src/internal-urls/jobs-protocol.ts

@@ -0,0 +1,119 @@
+import type { AsyncJobManager } from "../async";
+import { formatDuration } from "../tools/render-utils";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface JobsProtocolOptions {
+	getAsyncJobManager: () => AsyncJobManager | undefined;
+}
+
+function formatJobTime(startTime: number): string {
+	return new Date(startTime).toISOString();
+}
+
+function formatJobDuration(startTime: number): string {
+	return formatDuration(Math.max(0, Date.now() - startTime));
+}
+
+function normalizeJobId(url: InternalUrl): string {
+	const host = url.rawHost || url.hostname;
+	const pathname = (url.rawPathname ?? url.pathname).replace(/^\/+/, "").trim();
+	if (host && pathname) return `${host}/${pathname}`;
+	if (host) return host;
+	return pathname;
+}
+
+export class JobsProtocolHandler implements ProtocolHandler {
+	readonly scheme = "jobs";
+
+	constructor(private readonly options: JobsProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const manager = this.options.getAsyncJobManager();
+		if (!manager) {
+			const content =
+				"# Jobs\n\nBackground job support is disabled. Enable `async.enabled` or `bash.autoBackground.enabled` to use jobs://.";
+			return {
+				url: url.href,
+				content,
+				contentType: "text/markdown",
+				size: Buffer.byteLength(content, "utf-8"),
+			};
+		}
+
+		const jobId = normalizeJobId(url);
+		if (!jobId) {
+			return this.#listJobs(url, manager);
+		}
+
+		return this.#getJob(url, manager, jobId);
+	}
+
+	#listJobs(url: InternalUrl, manager: AsyncJobManager): InternalResource {
+		const jobs = manager.getAllJobs();
+		const running = jobs.filter(job => job.status === "running").sort((a, b) => a.startTime - b.startTime);
+		const done = jobs.filter(job => job.status !== "running").sort((a, b) => b.startTime - a.startTime);
+		const ordered = [...running, ...done];
+
+		if (ordered.length === 0) {
+			const content = "# Jobs\n\nNo background jobs found.";
+			return {
+				url: url.href,
+				content,
+				contentType: "text/markdown",
+				size: Buffer.byteLength(content, "utf-8"),
+			};
+		}
+
+		const lines = ordered.map(job => {
+			return `- \`${job.id}\` [${job.type}] **${job.status}** — ${job.label}  \n  started: ${formatJobTime(job.startTime)} · duration: ${formatJobDuration(job.startTime)}`;
+		});
+		const content = `# Jobs\n\n${ordered.length} job${ordered.length === 1 ? "" : "s"}\n\n${lines.join("\n")}`;
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+		};
+	}
+
+	#getJob(url: InternalUrl, manager: AsyncJobManager, jobId: string): InternalResource {
+		const job = manager.getJob(jobId);
+		if (!job) {
+			const content = `# Job Not Found\n\n404: No async job found with id \`${jobId}\`.`;
+			return {
+				url: url.href,
+				content,
+				contentType: "text/markdown",
+				size: Buffer.byteLength(content, "utf-8"),
+			};
+		}
+
+		const sections = [
+			`# Job ${job.id}`,
+			"",
+			`- type: ${job.type}`,
+			`- status: ${job.status}`,
+			`- label: ${job.label}`,
+			`- start: ${formatJobTime(job.startTime)}`,
+			`- duration: ${formatJobDuration(job.startTime)}`,
+		];
+
+		if (job.status === "completed" && job.resultText) {
+			sections.push("", "## Result", "", "```", job.resultText, "```");
+		}
+		if (job.status === "failed" && job.errorText) {
+			sections.push("", "## Error", "", "```", job.errorText, "```");
+		}
+		if (job.status === "cancelled" && job.errorText) {
+			sections.push("", "## Cancellation", "", "```", job.errorText, "```");
+		}
+
+		const content = sections.join("\n");
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+		};
+	}
+}

package/src/internal-urls/json-query.ts

@@ -0,0 +1,126 @@
+/**
+ * JSON query parser and executor for agent:// URL extraction.
+ *
+ * Supports jq-like syntax: .foo, [0], .foo.bar[0].baz, ["special-key"]
+ * Also supports path form: /foo/bar/0 -> .foo.bar[0]
+ */
+
+/**
+ * Parse a jq-like query string into tokens.
+ *
+ * @example
+ * parseQuery(".foo.bar[0]") // ["foo", "bar", 0]
+ * parseQuery(".foo['special-key']") // ["foo", "special-key"]
+ */
+export function parseQuery(query: string): Array<string | number> {
+	let input = query.trim();
+	if (!input) return [];
+	if (input.startsWith(".")) input = input.slice(1);
+	if (!input) return [];
+
+	const tokens: Array<string | number> = [];
+	let i = 0;
+
+	const isIdentChar = (ch: string) => /[A-Za-z0-9_-]/.test(ch);
+
+	while (i < input.length) {
+		const ch = input[i];
+		if (ch === ".") {
+			i++;
+			continue;
+		}
+		if (ch === "[") {
+			const closeIndex = input.indexOf("]", i + 1);
+			if (closeIndex === -1) {
+				throw new Error(`Invalid query: missing ] in ${query}`);
+			}
+			const raw = input.slice(i + 1, closeIndex).trim();
+			if (!raw) {
+				throw new Error(`Invalid query: empty [] in ${query}`);
+			}
+			const quote = raw[0];
+			if ((quote === '"' || quote === "'") && raw.endsWith(quote)) {
+				let inner = raw.slice(1, -1);
+				inner = inner.replace(/\\(["'\\])/g, "$1");
+				tokens.push(inner);
+			} else if (/^\d+$/.test(raw)) {
+				tokens.push(Number(raw));
+			} else {
+				tokens.push(raw);
+			}
+			i = closeIndex + 1;
+			continue;
+		}
+
+		const start = i;
+		while (i < input.length && isIdentChar(input[i])) {
+			i++;
+		}
+		if (start === i) {
+			throw new Error(`Invalid query: unexpected token '${input[i]}' in ${query}`);
+		}
+		const ident = input.slice(start, i);
+		tokens.push(ident);
+	}
+
+	return tokens;
+}
+
+/**
+ * Apply a parsed query to a JSON value.
+ *
+ * @example
+ * applyQuery({ foo: { bar: [1, 2, 3] } }, ".foo.bar[0]") // 1
+ */
+export function applyQuery(data: unknown, query: string): unknown {
+	const tokens = parseQuery(query);
+	let current: unknown = data;
+	for (const token of tokens) {
+		if (current === null || current === undefined) return undefined;
+		if (typeof token === "number") {
+			if (!Array.isArray(current)) return undefined;
+			current = current[token];
+			continue;
+		}
+		if (typeof current !== "object") return undefined;
+		const record = current as Record<string, unknown>;
+		current = record[token];
+	}
+	return current;
+}
+
+/**
+ * Convert a URL path form to a query string.
+ *
+ * Path form: /foo/bar/0 -> .foo.bar[0]
+ * Trailing slash is normalized (ignored).
+ *
+ * Segments that are not valid identifiers use bracket notation: ['segment']
+ */
+export function pathToQuery(urlPath: string): string {
+	if (!urlPath || urlPath === "/") return "";
+
+	const segments = urlPath.split("/").filter(Boolean);
+	if (segments.length === 0) return "";
+
+	const parts: string[] = [];
+	for (const segment of segments) {
+		let decoded = segment;
+		try {
+			decoded = decodeURIComponent(segment);
+		} catch {
+			decoded = segment;
+		}
+		const isIdentifier = /^[A-Za-z0-9_-]+$/.test(decoded);
+		if (/^\d+$/.test(decoded)) {
+			parts.push(`[${decoded}]`);
+		} else if (isIdentifier) {
+			parts.push(`.${decoded}`);
+		} else {
+			const escaped = decoded.replace(/\\/g, String.raw`\\`).replace(/'/g, String.raw`\'`);
+			parts.push(`['${escaped}']`);
+		}
+	}
+
+	return parts.join("");
+}

package/src/internal-urls/local-protocol.ts

@@ -0,0 +1,206 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isEnoent } from "@f5xc-salesdemos/pi-utils";
+import { parseInternalUrl } from "./parse";
+import { validateRelativePath } from "./skill-protocol";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface LocalProtocolOptions {
+	getArtifactsDir?: () => string | null;
+	getSessionId?: () => string | null;
+}
+
+function parseLocalUrl(input: string): InternalUrl {
+	return parseInternalUrl(input);
+}
+
+function ensureWithinRoot(targetPath: string, rootPath: string): void {
+	if (targetPath !== rootPath && !targetPath.startsWith(`${rootPath}${path.sep}`)) {
+		throw new Error("local:// URL escapes local root");
+	}
+}
+
+function toLocalValidationError(error: unknown): Error {
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(message.replace("skill://", "local://"));
+}
+
+function getContentType(filePath: string): InternalResource["contentType"] {
+	const ext = path.extname(filePath).toLowerCase();
+	if (ext === ".md") return "text/markdown";
+	if (ext === ".json") return "application/json";
+	return "text/plain";
+}
+
+async function listFilesRecursively(rootPath: string): Promise<string[]> {
+	const pending = [""];
+	const files: string[] = [];
+
+	while (pending.length > 0) {
+		const relativeDir = pending.pop();
+		if (relativeDir === undefined) continue;
+		const absoluteDir = path.join(rootPath, relativeDir);
+		const entries = await fs.readdir(absoluteDir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const entryPath = path.join(relativeDir, entry.name);
+			if (entry.isDirectory()) {
+				pending.push(entryPath);
+				continue;
+			}
+			if (entry.isFile()) {
+				files.push(entryPath.replaceAll(path.sep, "/"));
+			}
+		}
+	}
+
+	return files.sort((a, b) => a.localeCompare(b));
+}
+
+async function buildListing(url: InternalUrl, localRoot: string): Promise<InternalResource> {
+	const files = await listFilesRecursively(localRoot);
+	const listing = files.length === 0 ? "(empty)" : files.map(file => `- [${file}](local://${file})`).join("\n");
+	const content =
+		`# Local\n\n` +
+		`Session-scoped scratch space for large intermediate data, subagent handoffs, and reusable planning artifacts.\n\n` +
+		`Root: ${localRoot}\n\n` +
+		`${files.length} file${files.length === 1 ? "" : "s"} available:\n\n` +
+		`${listing}\n`;
+
+	return {
+		url: url.href,
+		content,
+		contentType: "text/markdown",
+		size: Buffer.byteLength(content, "utf-8"),
+		sourcePath: localRoot,
+	};
+}
+
+function extractRelativePath(url: InternalUrl): string {
+	const host = url.rawHost || url.hostname;
+	const pathname = url.rawPathname ?? url.pathname;
+
+	const combined = host
+		? pathname && pathname !== "/"
+			? `${host}${pathname}`
+			: host
+		: pathname && pathname !== "/"
+			? pathname.slice(1)
+			: "";
+
+	if (!combined) {
+		return "";
+	}
+
+	let decoded: string;
+	try {
+		decoded = decodeURIComponent(combined.replaceAll("\\", "/"));
+	} catch {
+		throw new Error(`Invalid URL encoding in local:// path: ${url.href}`);
+	}
+	try {
+		validateRelativePath(decoded);
+	} catch (error) {
+		throw toLocalValidationError(error);
+	}
+	return decoded;
+}
+
+export function resolveLocalRoot(options: LocalProtocolOptions): string {
+	const artifactsDir = options.getArtifactsDir?.();
+	if (artifactsDir) {
+		return path.resolve(artifactsDir, "local");
+	}
+
+	const sessionId = options.getSessionId?.() ?? "session";
+	const safeSessionId = sessionId.replace(/[^a-zA-Z0-9_.-]/g, "_");
+	return path.join(os.tmpdir(), "xcsh-local", safeSessionId);
+}
+
+export function resolveLocalUrlToPath(input: string | InternalUrl, options: LocalProtocolOptions): string {
+	const url = typeof input === "string" ? parseLocalUrl(input) : input;
+	const localRoot = path.resolve(resolveLocalRoot(options));
+	const relativePath = extractRelativePath(url);
+
+	if (!relativePath) {
+		return localRoot;
+	}
+
+	const resolved = path.resolve(localRoot, relativePath);
+	ensureWithinRoot(resolved, localRoot);
+	return resolved;
+}
+
+/**
+ * Protocol handler for local:// URLs.
+ *
+ * URL forms:
+ * - local:// - Lists all session local files
+ * - local://<path> - Reads a file under session local root
+ */
+export class LocalProtocolHandler implements ProtocolHandler {
+	readonly scheme = "local";
+
+	constructor(private readonly options: LocalProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const localRoot = path.resolve(resolveLocalRoot(this.options));
+		await fs.mkdir(localRoot, { recursive: true });
+
+		let resolvedRoot: string;
+		try {
+			resolvedRoot = await fs.realpath(localRoot);
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error("Unable to initialize local:// root");
+			}
+			throw error;
+		}
+
+		const relativePath = extractRelativePath(url);
+		const targetPath = relativePath ? path.resolve(resolvedRoot, relativePath) : resolvedRoot;
+		ensureWithinRoot(targetPath, resolvedRoot);
+
+		if (targetPath === resolvedRoot) {
+			return buildListing(url, resolvedRoot);
+		}
+
+		const parentDir = path.dirname(targetPath);
+		try {
+			const realParent = await fs.realpath(parentDir);
+			ensureWithinRoot(realParent, resolvedRoot);
+		} catch (error) {
+			if (!isEnoent(error)) {
+				throw error;
+			}
+		}
+
+		let realTargetPath: string;
+		try {
+			realTargetPath = await fs.realpath(targetPath);
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error(`Local file not found: ${url.href}`);
+			}
+			throw error;
+		}
+
+		ensureWithinRoot(realTargetPath, resolvedRoot);
+
+		const stat = await fs.stat(realTargetPath);
+		if (!stat.isFile()) {
+			throw new Error(`local:// URL must resolve to a file: ${url.href}`);
+		}
+
+		const content = await Bun.file(realTargetPath).text();
+		return {
+			url: url.href,
+			content,
+			contentType: getContentType(realTargetPath),
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: realTargetPath,
+			notes: ["Use write path local://<file> to persist large intermediate artifacts across turns."],
+		};
+	}
+}