@xopcai/xopc 0.0.251 → 0.0.253

package/dist/src/browser/drivers/playwright-driver.js

@@ -0,0 +1,406 @@
+import { verifyBrowserExpectation } from "../verification/expectation.js";
+import { randomUUID } from "node:crypto";
+//#region src/browser/drivers/playwright-driver.ts
+const INTERACTIVE_SELECTOR = [
+	"a[href]",
+	"button",
+	"input:not([type=\"hidden\"])",
+	"textarea",
+	"select",
+	"summary",
+	"[contenteditable=\"true\"]",
+	"[role=\"button\"]",
+	"[role=\"link\"]",
+	"[role=\"checkbox\"]",
+	"[role=\"radio\"]",
+	"[role=\"combobox\"]",
+	"[role=\"menuitem\"]",
+	"[role=\"option\"]",
+	"[role=\"tab\"]",
+	"[tabindex]:not([tabindex=\"-1\"])"
+].join(",");
+var PlaywrightDriver = class {
+	kind = "playwright";
+	connection = null;
+	sessions = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+	}
+	async connect() {
+		if (this.connection?.browser.isConnected()) return;
+		this.connection = await this.options.connect();
+	}
+	async disconnect() {
+		for (const session of this.sessions.values()) for (const state of session.tabs.values()) await state.page.close().catch(() => {});
+		this.sessions.clear();
+		await this.connection?.release?.().catch(() => {});
+		await this.connection?.context.close().catch(() => {});
+		await this.connection?.browser.close().catch(() => {});
+		this.connection = null;
+	}
+	async createSession(sessionId) {
+		if (this.sessions.has(sessionId)) return;
+		await this.connect();
+		const page = await this.context().newPage();
+		const state = this.createPageState(page);
+		this.sessions.set(sessionId, {
+			activeTabId: state.id,
+			tabs: new Map([[state.id, state]])
+		});
+	}
+	async closeSession(sessionId) {
+		const session = this.sessions.get(sessionId);
+		if (!session) return;
+		for (const state of session.tabs.values()) await state.page.close().catch(() => {});
+		this.sessions.delete(sessionId);
+	}
+	async navigate(sessionId, input, signal) {
+		const startedAt = Date.now();
+		const state = await this.activeState(sessionId);
+		try {
+			throwIfAborted(signal);
+			await state.page.goto(input.url, {
+				waitUntil: "domcontentloaded",
+				timeout: this.options.actionTimeoutMs
+			});
+			const observation = await this.observe(sessionId, {
+				action: "observe",
+				visual: "auto"
+			}, signal);
+			return this.verifiedResult(input, observation, startedAt, "read");
+		} catch (error) {
+			return failureFrom(error);
+		}
+	}
+	async observe(sessionId, input, signal) {
+		throwIfAborted(signal);
+		const state = await this.activeState(sessionId);
+		const marker = await state.page.evaluate(() => {
+			const root = globalThis;
+			return `${root.location.href}|${root.performance.timeOrigin}`;
+		});
+		if (marker !== state.documentMarker) {
+			state.documentMarker = marker;
+			state.documentId = randomUUID();
+			state.revision = 0;
+			state.refs.clear();
+			state.lastNodes = [];
+		}
+		const candidates = state.page.locator(INTERACTIVE_SELECTOR);
+		const count = Math.min(await candidates.count(), this.options.maxNodes * 3);
+		const nodes = [];
+		const refs = /* @__PURE__ */ new Map();
+		let characters = 0;
+		for (let index = 0; index < count && nodes.length < this.options.maxNodes; index += 1) {
+			throwIfAborted(signal);
+			const locator = candidates.nth(index);
+			if (!await locator.isVisible().catch(() => false)) continue;
+			const handle = await locator.elementHandle();
+			if (!handle) continue;
+			let raw = await handle.evaluate((element, elementIndex) => {
+				const html = element;
+				const tag = element.tagName.toLowerCase();
+				const input = element;
+				const explicitRole = element.getAttribute("role");
+				const implicitRole = tag === "a" ? "link" : tag === "button" ? "button" : tag === "select" ? "combobox" : tag === "textarea" ? "textbox" : tag === "summary" ? "button" : tag === "input" && input.type === "checkbox" ? "checkbox" : tag === "input" && input.type === "radio" ? "radio" : tag === "input" ? "textbox" : "interactive";
+				const label = tag === "input" || tag === "textarea" || tag === "select" ? input.labels?.[0]?.innerText ?? "" : "";
+				const name = element.getAttribute("aria-label") ?? label ?? element.getAttribute("alt") ?? element.getAttribute("placeholder") ?? html.innerText ?? element.getAttribute("title") ?? "";
+				const rect = element.getBoundingClientRect();
+				const root = globalThis;
+				root.__xopcRefCounter = (root.__xopcRefCounter ?? 0) + 1;
+				const existing = element.getAttribute("data-xopc-ref");
+				const ref = existing && /^xopc-e\d+$/.test(existing) ? existing : `xopc-e${root.__xopcRefCounter}`;
+				if (ref !== existing) element.setAttribute("data-xopc-ref", ref);
+				const states = [];
+				const autocomplete = element.getAttribute("autocomplete")?.toLowerCase() ?? "";
+				const sensitive = input.type === "password" || /^(cc-|one-time-code$|transaction-)/.test(autocomplete);
+				if (element.disabled) states.push("disabled");
+				if (element.checked) states.push("checked");
+				if (globalThis.document.activeElement === element) states.push("focused");
+				if (element.getAttribute("aria-expanded") === "true") states.push("expanded");
+				if (sensitive) states.push("sensitive");
+				if ((tag === "button" || tag === "input") && input.type === "submit") states.push("submit");
+				return {
+					ref,
+					role: explicitRole || implicitRole,
+					name: name.trim().replace(/\s+/g, " ").slice(0, 240),
+					value: !sensitive && "value" in element ? String(element.value ?? "").slice(0, 500) : void 0,
+					description: element.getAttribute("aria-description") ?? void 0,
+					states,
+					bounds: {
+						x: rect.x,
+						y: rect.y,
+						width: rect.width,
+						height: rect.height
+					},
+					elementIndex
+				};
+			}, index);
+			if (refs.has(raw.ref)) {
+				const ref = `xopc-e${Date.now()}${index}`;
+				await handle.evaluate((element, nextRef) => element.setAttribute("data-xopc-ref", nextRef), ref);
+				raw = {
+					...raw,
+					ref
+				};
+			}
+			characters += raw.name.length + (raw.value?.length ?? 0) + (raw.description?.length ?? 0);
+			if (characters > this.options.maxCharacters) break;
+			const node = raw;
+			nodes.push(node);
+			refs.set(node.ref, handle);
+		}
+		state.revision += 1;
+		state.refs = refs;
+		const changes = diffNodes(state.lastNodes, nodes);
+		state.lastNodes = nodes;
+		const focused = nodes.find((node) => node.states.includes("focused"))?.ref;
+		const visual = await this.captureVisual(state.page, input.visual ?? "auto", nodes.length);
+		return {
+			sessionId,
+			tabId: state.id,
+			revision: state.revision,
+			documentId: state.documentId,
+			url: state.page.url(),
+			title: await state.page.title().catch(() => ""),
+			focused,
+			nodes,
+			changes,
+			visual
+		};
+	}
+	async perform(sessionId, input, signal) {
+		const startedAt = Date.now();
+		try {
+			throwIfAborted(signal);
+			const state = await this.activeState(sessionId);
+			if ("revision" in input && input.revision !== state.revision) return stale(await this.observe(sessionId, {
+				action: "observe",
+				visual: "never"
+			}, signal));
+			const handle = "ref" in input && input.ref ? state.refs.get(input.ref) : void 0;
+			if ("ref" in input && input.ref && !handle) return targetNotFound(input.ref);
+			switch (input.action) {
+				case "click":
+					await handle.click({ timeout: this.options.actionTimeoutMs });
+					break;
+				case "fill":
+					await handle.fill(input.value, { timeout: this.options.actionTimeoutMs });
+					if (input.submit) await handle.press("Enter");
+					break;
+				case "select":
+					await handle.selectOption(input.value);
+					break;
+				case "press":
+					if (handle) await handle.press(input.key);
+					else await state.page.keyboard.press(input.key);
+					break;
+				case "scroll":
+					if (handle) await handle.evaluate((element, deltaY) => element.scrollBy({ top: deltaY }), input.deltaY);
+					else await state.page.mouse.wheel(0, input.deltaY);
+					break;
+				case "wait":
+					await this.wait(state, input, signal);
+					break;
+				case "upload":
+					await handle.setInputFiles(input.paths);
+					break;
+			}
+			await state.page.waitForTimeout(200);
+			const observation = await this.observe(sessionId, {
+				action: "observe",
+				visual: "auto"
+			}, signal);
+			return this.verifiedResult(input, observation, startedAt, "draft");
+		} catch (error) {
+			return failureFrom(error);
+		}
+	}
+	async tabs(sessionId, input, signal) {
+		const startedAt = Date.now();
+		try {
+			throwIfAborted(signal);
+			const session = await this.session(sessionId);
+			if (input.operation === "create") {
+				const page = await this.context().newPage();
+				const state = this.createPageState(page);
+				session.tabs.set(state.id, state);
+				session.activeTabId = state.id;
+				if (input.url) await page.goto(input.url, {
+					waitUntil: "domcontentloaded",
+					timeout: this.options.actionTimeoutMs
+				});
+			} else if (input.operation === "activate") {
+				if (!input.tabId || !session.tabs.has(input.tabId)) return targetNotFound(input.tabId ?? "");
+				session.activeTabId = input.tabId;
+				await session.tabs.get(input.tabId).page.bringToFront();
+			} else if (input.operation === "close") {
+				if (!input.tabId || !session.tabs.has(input.tabId)) return targetNotFound(input.tabId ?? "");
+				await session.tabs.get(input.tabId).page.close();
+				session.tabs.delete(input.tabId);
+				if (session.tabs.size === 0) {
+					const next = this.createPageState(await this.context().newPage());
+					session.tabs.set(next.id, next);
+				}
+				session.activeTabId = session.tabs.keys().next().value;
+			}
+			const tabs = await this.listTabs(session);
+			return {
+				ok: true,
+				receipt: {
+					action: "tabs",
+					risk: "read",
+					durationMs: Date.now() - startedAt,
+					verified: true,
+					tabs
+				}
+			};
+		} catch (error) {
+			return failureFrom(error);
+		}
+	}
+	async wait(state, input, signal) {
+		const timeout = input.timeoutMs ?? this.options.actionTimeoutMs;
+		if (input.condition === "page_idle") {
+			await state.page.waitForLoadState("networkidle", { timeout });
+			return;
+		}
+		if (input.condition === "text") {
+			if (!input.value) throw new Error("wait text requires value");
+			await state.page.getByText(input.value, { exact: false }).first().waitFor({
+				state: "visible",
+				timeout
+			});
+			return;
+		}
+		if (!input.ref) throw new Error(`wait ${input.condition} requires ref`);
+		const handle = state.refs.get(input.ref);
+		if (!handle && input.condition === "hidden") return;
+		if (!handle) throw new Error(`Target ${input.ref} was not found`);
+		const deadline = Date.now() + timeout;
+		while (Date.now() < deadline) {
+			throwIfAborted(signal);
+			const visible = await handle.isVisible().catch(() => false);
+			if (input.condition === "visible" && visible || input.condition === "hidden" && !visible) return;
+			await state.page.waitForTimeout(100);
+		}
+		throw new Error(`Timed out waiting for ${input.ref} to become ${input.condition}`);
+	}
+	verifiedResult(input, observation, startedAt, risk) {
+		const failed = verifyBrowserExpectation("expect" in input ? input.expect : void 0, observation);
+		if (failed) return {
+			ok: false,
+			error: {
+				code: "EXPECTATION_FAILED",
+				message: failed,
+				observation
+			}
+		};
+		return {
+			ok: true,
+			receipt: {
+				action: input.action,
+				risk,
+				durationMs: Date.now() - startedAt,
+				verified: true,
+				observation
+			}
+		};
+	}
+	async captureVisual(page, mode, nodeCount) {
+		if (mode === "never") return void 0;
+		if (!(mode === "always" || this.options.visualFallback && (nodeCount === 0 || await page.locator("canvas,embed[type=\"application/pdf\"],object[type=\"application/pdf\"]").count() > 0))) return void 0;
+		const data = await page.screenshot({
+			type: "jpeg",
+			quality: 70,
+			fullPage: false,
+			scale: "css"
+		});
+		const viewport = page.viewportSize();
+		return {
+			mimeType: "image/jpeg",
+			data: data.toString("base64"),
+			width: viewport?.width,
+			height: viewport?.height
+		};
+	}
+	async activeState(sessionId) {
+		const session = await this.session(sessionId);
+		const state = session.tabs.get(session.activeTabId);
+		if (!state) throw new Error(`Active tab is missing for session ${sessionId}`);
+		return state;
+	}
+	async session(sessionId) {
+		await this.createSession(sessionId);
+		return this.sessions.get(sessionId);
+	}
+	createPageState(page) {
+		return {
+			id: `tab_${randomUUID()}`,
+			page,
+			documentId: randomUUID(),
+			documentMarker: "",
+			revision: 0,
+			refs: /* @__PURE__ */ new Map(),
+			lastNodes: []
+		};
+	}
+	context() {
+		if (!this.connection) throw new Error("Playwright driver is not connected");
+		return this.connection.context;
+	}
+	async listTabs(session) {
+		return Promise.all([...session.tabs.values()].map(async (state) => ({
+			id: state.id,
+			url: state.page.url(),
+			title: await state.page.title().catch(() => ""),
+			active: state.id === session.activeTabId
+		})));
+	}
+};
+function diffNodes(previous, next) {
+	const before = new Map(previous.map((node) => [node.ref, node]));
+	const after = new Map(next.map((node) => [node.ref, node]));
+	return {
+		added: next.filter((node) => !before.has(node.ref)),
+		changed: next.filter((node) => {
+			const old = before.get(node.ref);
+			return old && JSON.stringify(old) !== JSON.stringify(node);
+		}),
+		removed: previous.filter((node) => !after.has(node.ref)).map((node) => node.ref)
+	};
+}
+function stale(observation) {
+	return {
+		ok: false,
+		error: {
+			code: "STALE_OBSERVATION",
+			message: "The page changed. Use the attached observation and retry with its revision.",
+			observation
+		}
+	};
+}
+function targetNotFound(ref) {
+	return {
+		ok: false,
+		error: {
+			code: "TARGET_NOT_FOUND",
+			message: `Target ${ref || "(missing)"} was not found.`
+		}
+	};
+}
+function failureFrom(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		ok: false,
+		error: {
+			code: /aborted/i.test(message) ? "ABORTED" : /timeout|timed out/i.test(message) ? "TIMEOUT" : "DRIVER_UNAVAILABLE",
+			message
+		}
+	};
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("Operation was aborted");
+}
+//#endregion
+export { PlaywrightDriver };

package/dist/src/browser/index.d.ts

@@ -1,16 +1,11 @@
-export { BrowserManager, type BrowserManagerOptions } from './manager.js';
-export { resolveBrowserBackendFromConfig } from './backend-from-config.js';
-export { resolveBrowserCommandTimeoutMs } from './browser-command-timeout.js';
-export { BrowserNotReadyError, buildBrowserSetupDeepLink, checkBrowserReadiness, type BrowserBackendKind, type BrowserNotReadyReason, type BrowserSetupHint, } from './readiness.js';
+export { BrowserRuntime, type BrowserRuntimeOptions } from './runtime/browser-runtime.js';
+export { createBrowserDriver } from './drivers/create-driver.js';
+export type { BrowserDriver, BrowserPrimitiveInput } from './drivers/browser-driver.js';
+export { PlaywrightDriver, type PlaywrightDriverOptions } from './drivers/playwright-driver.js';
+export { ExtensionDriver } from './drivers/extension-driver.js';
+export { formatBrowserObservation } from './observation/format.js';
+export { classifyBrowserRisk, browserRiskNeedsApproval } from './policy/browser-policy.js';
+export { createBrowserApproval, consumeBrowserApproval, decideBrowserApproval, listBrowserApprovals, } from './policy/approval-store.js';
+export { verifyBrowserExpectation } from './verification/expectation.js';
+export { BrowserNotReadyError, buildBrowserSetupDeepLink, checkBrowserReadiness, type BrowserDriverKind, type BrowserNotReadyReason, type BrowserSetupHint, } from './readiness.js';
 export { assertBrowserUrlAllowed, checkPostRedirectUrl, containsApiKeyPattern, isAlwaysBlockedUrl, } from './url-policy.js';
-export { CdpSupervisor, type DialogEvent, type ConsoleEntry, type DialogPolicy } from './cdp-supervisor.js';
-export { truncateSnapshotAtBoundary, snapshotSummaryHeader } from './snapshot-helpers.js';
-export { startTracing, stopTracing, checkBotDetection, cleanupOrphanProcesses, type TracingOptions, type BotDetectionResult, } from './session-lifecycle.js';
-export { BrowserBackSchema, BrowserCdpSchema, BrowserClickSchema, BrowserCloseSchema, BrowserConsoleSchema, BrowserDialogSchema, BrowserGetImagesSchema, BrowserNavigateSchema, BrowserPressSchema, BrowserScreenshotSchema, BrowserScrollSchema, BrowserSnapshotSchema, BrowserTypeSchema, BrowserVisionSchema, } from './schemas.js';
-export { humanizedClick, humanizedFill, humanizedPress, humanizedScroll, resolveHumanConfig, generateMousePath, generateTypingPlan, generateScrollPlan, type HumanConfig, type HumanPreset, } from './humanize.js';
-export { buildStealthArgs, buildLocalStealthArgs, generateFingerprintSeed, removeQuarantineAttr, makeExecutable, WEBDRIVER_OVERRIDE_SCRIPT, type StealthOptions, } from './stealth.js';
-export { createBrowserActionRegistry } from './actions/registry.js';
-export type { BrowserActionName, BrowserActionContext, BrowserActionHandler, BrowserActionRegistry as BrowserActionRegistryType, BrowserActionResult, BrowserArtifact, BrowserDiagnostics, } from './actions/types.js';
-export { parseBrowserPipeline, type PipelineDocument, type PipelineStep } from './pipeline/schema.js';
-export { runBrowserPipeline, validateBrowserPipeline } from './pipeline/runner.js';
-export { resolveTemplate, resolveTemplateDeep } from './pipeline/template.js';

package/dist/src/browser/index.js

@@ -1,16 +1,11 @@
-import { BrowserManager } from "./manager.js";
-import { resolveBrowserBackendFromConfig } from "./backend-from-config.js";
-import { resolveBrowserCommandTimeoutMs } from "./browser-command-timeout.js";
-import { BrowserNotReadyError, buildBrowserSetupDeepLink, checkBrowserReadiness } from "./readiness.js";
 import { assertBrowserUrlAllowed, checkPostRedirectUrl, containsApiKeyPattern, isAlwaysBlockedUrl } from "./url-policy.js";
-import { CdpSupervisor } from "./cdp-supervisor.js";
-import { snapshotSummaryHeader, truncateSnapshotAtBoundary } from "./snapshot-helpers.js";
-import { checkBotDetection, cleanupOrphanProcesses, startTracing, stopTracing } from "./session-lifecycle.js";
-import { BrowserBackSchema, BrowserCdpSchema, BrowserClickSchema, BrowserCloseSchema, BrowserConsoleSchema, BrowserDialogSchema, BrowserGetImagesSchema, BrowserNavigateSchema, BrowserPressSchema, BrowserScreenshotSchema, BrowserScrollSchema, BrowserSnapshotSchema, BrowserTypeSchema, BrowserVisionSchema } from "./schemas.js";
-import { generateMousePath, generateScrollPlan, generateTypingPlan, humanizedClick, humanizedFill, humanizedPress, humanizedScroll, resolveHumanConfig } from "./humanize.js";
-import { WEBDRIVER_OVERRIDE_SCRIPT, buildLocalStealthArgs, buildStealthArgs, generateFingerprintSeed, makeExecutable, removeQuarantineAttr } from "./stealth.js";
-import { resolveTemplate, resolveTemplateDeep } from "./pipeline/template.js";
-import { createBrowserActionRegistry } from "./actions/registry.js";
-import { parseBrowserPipeline } from "./pipeline/schema.js";
-import { runBrowserPipeline, validateBrowserPipeline } from "./pipeline/runner.js";
-export { BrowserBackSchema, BrowserCdpSchema, BrowserClickSchema, BrowserCloseSchema, BrowserConsoleSchema, BrowserDialogSchema, BrowserGetImagesSchema, BrowserManager, BrowserNavigateSchema, BrowserNotReadyError, BrowserPressSchema, BrowserScreenshotSchema, BrowserScrollSchema, BrowserSnapshotSchema, BrowserTypeSchema, BrowserVisionSchema, CdpSupervisor, WEBDRIVER_OVERRIDE_SCRIPT, assertBrowserUrlAllowed, buildBrowserSetupDeepLink, buildLocalStealthArgs, buildStealthArgs, checkBotDetection, checkBrowserReadiness, checkPostRedirectUrl, cleanupOrphanProcesses, containsApiKeyPattern, createBrowserActionRegistry, generateFingerprintSeed, generateMousePath, generateScrollPlan, generateTypingPlan, humanizedClick, humanizedFill, humanizedPress, humanizedScroll, isAlwaysBlockedUrl, makeExecutable, parseBrowserPipeline, removeQuarantineAttr, resolveBrowserBackendFromConfig, resolveBrowserCommandTimeoutMs, resolveHumanConfig, resolveTemplate, resolveTemplateDeep, runBrowserPipeline, snapshotSummaryHeader, startTracing, stopTracing, truncateSnapshotAtBoundary, validateBrowserPipeline };
+import { consumeBrowserApproval, createBrowserApproval, decideBrowserApproval, listBrowserApprovals } from "./policy/approval-store.js";
+import { browserRiskNeedsApproval, classifyBrowserRisk } from "./policy/browser-policy.js";
+import { BrowserRuntime } from "./runtime/browser-runtime.js";
+import { ExtensionDriver } from "./drivers/extension-driver.js";
+import { verifyBrowserExpectation } from "./verification/expectation.js";
+import { PlaywrightDriver } from "./drivers/playwright-driver.js";
+import { createBrowserDriver } from "./drivers/create-driver.js";
+import { formatBrowserObservation } from "./observation/format.js";
+import { BrowserNotReadyError, buildBrowserSetupDeepLink, checkBrowserReadiness } from "./readiness.js";
+export { BrowserNotReadyError, BrowserRuntime, ExtensionDriver, PlaywrightDriver, assertBrowserUrlAllowed, browserRiskNeedsApproval, buildBrowserSetupDeepLink, checkBrowserReadiness, checkPostRedirectUrl, classifyBrowserRisk, consumeBrowserApproval, containsApiKeyPattern, createBrowserApproval, createBrowserDriver, decideBrowserApproval, formatBrowserObservation, isAlwaysBlockedUrl, listBrowserApprovals, verifyBrowserExpectation };

package/dist/src/browser/install-lock.d.ts

@@ -1,5 +1,4 @@
-/** Per-backend install mutex — Playwright and CloakBrowser may install in parallel. */
-export type BrowserInstallKind = 'playwright' | 'cloakbrowser';
+export type BrowserInstallKind = 'playwright';
 export type BrowserInstallLock = {
     readonly signal: AbortSignal;
     release: () => void;

package/dist/src/browser/install-lock.js

@@ -1,12 +1,6 @@
 //#region src/browser/install-lock.ts
-const locked = {
-	playwright: false,
-	cloakbrowser: false
-};
-const activeController = {
-	playwright: null,
-	cloakbrowser: null
-};
+const locked = { playwright: false };
+const activeController = { playwright: null };
 function acquireBrowserInstallLock(kind) {
 	if (locked[kind]) return null;
 	locked[kind] = true;
@@ -35,7 +29,7 @@ function isBrowserInstallRunning(kind) {
 }
 /** Test helper — reset lock state between unit tests. */
 function resetBrowserInstallLockForTests() {
-	for (const kind of ["playwright", "cloakbrowser"]) {
+	for (const kind of ["playwright"]) {
 		activeController[kind]?.abort();
 		activeController[kind] = null;
 		locked[kind] = false;

package/dist/src/browser/install-progress.d.ts

@@ -1,4 +1,4 @@
-/** Shared install progress events for CloakBrowser and Playwright Chromium. */
+/** Playwright Chromium installation progress. */
 export type BrowserInstallPhase = 'starting' | 'downloading' | 'verifying' | 'extracting' | 'running' | 'ready';
 export type BrowserInstallProgress = {
     phase: BrowserInstallPhase;

package/dist/src/browser/observation/format.d.ts

@@ -0,0 +1,2 @@
+import type { BrowserObservation } from '@xopcai/browser-control-contract';
+export declare function formatBrowserObservation(observation: BrowserObservation): string;

package/dist/src/browser/observation/format.js

@@ -0,0 +1,26 @@
+//#region src/browser/observation/format.ts
+function formatBrowserObservation(observation) {
+	const lines = [
+		`Session: ${observation.sessionId}`,
+		`Tab: ${observation.tabId}`,
+		`Revision: ${observation.revision}`,
+		`URL: ${observation.url}`,
+		`Title: ${observation.title}`
+	];
+	if (observation.nodes.length === 0) lines.push("Interactive elements: none");
+	else {
+		lines.push("Interactive elements:");
+		for (const node of observation.nodes) lines.push(formatNode(node));
+	}
+	const { added, changed, removed } = observation.changes;
+	if (added.length || changed.length || removed.length) lines.push(`Changes: +${added.length} ~${changed.length} -${removed.length}`);
+	if (observation.visual) lines.push("Visual screenshot attached.");
+	return lines.join("\n");
+}
+function formatNode(node) {
+	const state = node.states.length ? ` [${node.states.join(",")}]` : "";
+	const value = node.value ? ` value=${JSON.stringify(node.value)}` : "";
+	return `- ${node.ref} ${node.role} ${JSON.stringify(node.name)}${value}${state}`;
+}
+//#endregion
+export { formatBrowserObservation };

package/dist/src/browser/policy/approval-store.d.ts

@@ -0,0 +1,17 @@
+import type { BrowserActionInput, BrowserRiskLevel } from '@xopcai/browser-control-contract';
+export type BrowserApprovalStatus = 'pending' | 'approved' | 'denied' | 'consumed' | 'expired';
+export interface BrowserApproval {
+    id: string;
+    sessionKey: string;
+    risk: BrowserRiskLevel;
+    action: BrowserActionInput['action'];
+    summary: string;
+    argumentsHash: string;
+    status: BrowserApprovalStatus;
+    createdAt: string;
+    expiresAt: string;
+}
+export declare function createBrowserApproval(sessionKey: string, input: BrowserActionInput, risk: BrowserRiskLevel, summary: string): BrowserApproval;
+export declare function listBrowserApprovals(sessionKey?: string): BrowserApproval[];
+export declare function decideBrowserApproval(id: string, decision: 'approved' | 'denied'): BrowserApproval | undefined;
+export declare function consumeBrowserApproval(id: string | undefined, sessionKey: string, input: BrowserActionInput): boolean;

package/dist/src/browser/policy/approval-store.js

@@ -0,0 +1,62 @@
+import { createHash, randomUUID } from "node:crypto";
+//#region src/browser/policy/approval-store.ts
+const TTL_MS = 600 * 1e3;
+const approvals = /* @__PURE__ */ new Map();
+function createBrowserApproval(sessionKey, input, risk, summary) {
+	expireApprovals();
+	const argumentsHash = browserArgumentsHash(input);
+	const existing = [...approvals.values()].find((approval) => approval.sessionKey === sessionKey && approval.argumentsHash === argumentsHash && approval.status === "pending");
+	if (existing) return existing;
+	const now = Date.now();
+	const approval = {
+		id: randomUUID(),
+		sessionKey,
+		risk,
+		action: input.action,
+		summary,
+		argumentsHash,
+		status: "pending",
+		createdAt: new Date(now).toISOString(),
+		expiresAt: new Date(now + TTL_MS).toISOString()
+	};
+	approvals.set(approval.id, approval);
+	return approval;
+}
+function listBrowserApprovals(sessionKey) {
+	expireApprovals();
+	return [...approvals.values()].filter((approval) => !sessionKey || approval.sessionKey === sessionKey).sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+function decideBrowserApproval(id, decision) {
+	expireApprovals();
+	const approval = approvals.get(id);
+	if (!approval || approval.status !== "pending") return approval;
+	approval.status = decision;
+	return approval;
+}
+function consumeBrowserApproval(id, sessionKey, input) {
+	expireApprovals();
+	const argumentsHash = browserArgumentsHash(input);
+	const approval = id ? approvals.get(id) : [...approvals.values()].find((candidate) => candidate.sessionKey === sessionKey && candidate.argumentsHash === argumentsHash && candidate.status === "approved");
+	if (!approval || approval.status !== "approved") return false;
+	if (approval.sessionKey !== sessionKey || approval.argumentsHash !== argumentsHash) return false;
+	approval.status = "consumed";
+	return true;
+}
+function browserArgumentsHash(input) {
+	const canonical = {
+		...input,
+		approvalId: void 0
+	};
+	return createHash("sha256").update(JSON.stringify(sortRecursively(canonical))).digest("hex");
+}
+function sortRecursively(value) {
+	if (Array.isArray(value)) return value.map(sortRecursively);
+	if (!value || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, sortRecursively(child)]));
+}
+function expireApprovals() {
+	const now = Date.now();
+	for (const approval of approvals.values()) if ((approval.status === "pending" || approval.status === "approved") && Date.parse(approval.expiresAt) <= now) approval.status = "expired";
+}
+//#endregion
+export { consumeBrowserApproval, createBrowserApproval, decideBrowserApproval, listBrowserApprovals };

package/dist/src/browser/policy/browser-policy.d.ts

@@ -0,0 +1,3 @@
+import type { BrowserActionInput, BrowserNode, BrowserRiskLevel } from '@xopcai/browser-control-contract';
+export declare function classifyBrowserRisk(input: BrowserActionInput, target?: BrowserNode): BrowserRiskLevel;
+export declare function browserRiskNeedsApproval(risk: BrowserRiskLevel): boolean;

package/dist/src/browser/policy/browser-policy.js

@@ -0,0 +1,27 @@
+//#region src/browser/policy/browser-policy.ts
+const DESTRUCTIVE_PATTERN = /\b(delete|remove|erase|destroy|cancel subscription|关闭账户|删除|移除|注销)\b/i;
+const EXTERNAL_EFFECT_PATTERN = /\b(send|submit|publish|post|pay|buy|purchase|confirm|发送|提交|发布|支付|购买|确认)\b/i;
+function classifyBrowserRisk(input, target) {
+	if (input.action === "upload") return "sensitive";
+	if (input.action === "fill") {
+		if (target?.states.includes("sensitive")) return "sensitive";
+		if (input.submit) return "external_effect";
+		return "draft";
+	}
+	if (input.action === "press") {
+		if (input.key === "Enter" && target?.states.includes("submit")) return "external_effect";
+		return "draft";
+	}
+	if (input.action === "select" || input.action === "scroll") return "draft";
+	if (input.action !== "click") return "read";
+	const label = `${target?.role ?? ""} ${target?.name ?? ""} ${target?.description ?? ""}`;
+	if (DESTRUCTIVE_PATTERN.test(label)) return "destructive";
+	if (target?.states.includes("submit")) return "external_effect";
+	if (EXTERNAL_EFFECT_PATTERN.test(label)) return "external_effect";
+	return "draft";
+}
+function browserRiskNeedsApproval(risk) {
+	return risk === "external_effect" || risk === "destructive" || risk === "sensitive";
+}
+//#endregion
+export { browserRiskNeedsApproval, classifyBrowserRisk };

package/dist/src/browser/providers/browser-ext-install.d.ts

@@ -56,7 +56,7 @@ export declare function ensureBrowserExtensionArtifacts(opts?: {
     force?: boolean;
     cacheDir?: string;
 }): Promise<EnsureBrowserExtResult>;
-/** Gateway startup hook: ensure artifacts only while the extension backend is active. */
+/** Gateway startup hook: ensure artifacts only while the extension driver is active. */
 export declare function ensureBrowserExtensionOnStartup(config: Config | undefined): Promise<void>;
 export declare function readInstalledExtensionDir(cacheDir?: string): Promise<string | null>;
 export type BrowserExtensionOpenAction = 'chrome' | 'folder' | 'both';