@xopcai/xopc 0.0.251 → 0.0.252

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

@@ -0,0 +1,30 @@
+import type { BrowserActionInput, BrowserControlResult } from '@xopcai/browser-control-contract';
+import type { Config } from '../../config/schema.js';
+import type { BrowserDriver } from '../drivers/browser-driver.js';
+export interface BrowserRuntimeOptions {
+    getConfig: () => Config['browser'];
+    createDriver: () => Promise<BrowserDriver>;
+    allowedUploadRoots?: string[];
+    emit?: (type: string, payload: unknown) => void;
+}
+export declare class BrowserRuntime {
+    private readonly options;
+    private driver;
+    private sessionsByTask;
+    constructor(options: BrowserRuntimeOptions);
+    execute(taskKey: string, input: BrowserActionInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+    shutdown(): Promise<void>;
+    closeTaskSession(taskKey: string): Promise<void>;
+    private dispatch;
+    private executeSequence;
+    private authorize;
+    private validateUrl;
+    private validateRedirect;
+    private blockedRedirect;
+    private crossDomainPolicy;
+    private invalidUploadPath;
+    private resolveSession;
+    private getDriver;
+    private constrainResult;
+    private evictExpiredSessions;
+}

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

@@ -0,0 +1,362 @@
+import { assertBrowserUrlAllowed, checkPostRedirectUrl, containsApiKeyPattern } from "../url-policy.js";
+import { consumeBrowserApproval, createBrowserApproval } from "../policy/approval-store.js";
+import { browserRiskNeedsApproval, classifyBrowserRisk } from "../policy/browser-policy.js";
+import { isAbsolute, relative, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/browser/runtime/browser-runtime.ts
+var BrowserRuntime = class {
+	driver = null;
+	sessionsByTask = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+	}
+	async execute(taskKey, input, signal) {
+		this.evictExpiredSessions();
+		if (!this.options.getConfig().enabled) return failure("DRIVER_UNAVAILABLE", "Browser Control is disabled.");
+		if (signal?.aborted) return failure("ABORTED", "Operation was aborted.");
+		let session;
+		let driver;
+		try {
+			session = await this.resolveSession(taskKey, input.sessionId);
+			if (!session) return failure("SESSION_NOT_FOUND", "The browser session does not belong to this task.");
+			driver = await this.getDriver();
+		} catch (error) {
+			return failure("DRIVER_UNAVAILABLE", error instanceof Error ? error.message : String(error));
+		}
+		session.lastUsedAt = Date.now();
+		this.options.emit?.("browser.action.started", {
+			sessionId: session.id,
+			action: input.action
+		});
+		let result;
+		try {
+			result = await this.dispatch(driver, session, input, signal);
+			result = this.constrainResult(result);
+		} catch (error) {
+			result = failure("DRIVER_UNAVAILABLE", error instanceof Error ? error.message : String(error));
+		}
+		if (result.ok) {
+			if (result.receipt.observation) session.observation = result.receipt.observation;
+			this.options.emit?.("browser.action.completed", {
+				sessionId: session.id,
+				receipt: withoutVisual(result.receipt)
+			});
+			if (result.receipt.observation) this.options.emit?.("browser.observation.created", withoutVisual(result.receipt.observation));
+		} else if ("error" in result) {
+			if (result.error.observation) session.observation = result.error.observation;
+			this.options.emit?.("browser.session.failed", {
+				sessionId: session.id,
+				error: result.error
+			});
+		}
+		return result;
+	}
+	async shutdown() {
+		await this.driver?.disconnect();
+		this.driver = null;
+		this.sessionsByTask.clear();
+	}
+	async closeTaskSession(taskKey) {
+		const session = this.sessionsByTask.get(taskKey);
+		if (!session) return;
+		await this.driver?.closeSession(session.id);
+		this.sessionsByTask.delete(taskKey);
+		this.options.emit?.("browser.session.closed", { sessionId: session.id });
+	}
+	async dispatch(driver, session, input, signal) {
+		if (input.action === "close") {
+			await this.closeTaskSession(session.taskKey);
+			return {
+				ok: true,
+				receipt: {
+					action: "close",
+					risk: "read",
+					durationMs: 0,
+					verified: true
+				}
+			};
+		}
+		if (input.action === "observe") return {
+			ok: true,
+			receipt: {
+				action: "observe",
+				risk: "read",
+				durationMs: 0,
+				verified: true,
+				observation: await driver.observe(session.id, input, signal)
+			}
+		};
+		if (input.action === "navigate") {
+			const blocked = this.validateUrl(input.url);
+			if (blocked) return failure("BLOCKED_URL", blocked);
+			const crossDomainPolicy = this.crossDomainPolicy(session.observation?.url, input.url);
+			if (crossDomainPolicy === "deny") return failure("BLOCKED_URL", "Cross-domain navigation is denied by policy.");
+			const authorization = this.authorize(session.taskKey, input, crossDomainPolicy === "ask" ? "external_effect" : "read", crossDomainPolicy);
+			if (authorization) return authorization;
+			const result = await driver.navigate(session.id, input, signal);
+			return this.validateRedirect(input.url, result);
+		}
+		if (input.action === "tabs") {
+			if (input.url) {
+				const blocked = this.validateUrl(input.url);
+				if (blocked) return failure("BLOCKED_URL", blocked);
+				const crossDomainPolicy = this.crossDomainPolicy(session.observation?.url, input.url);
+				if (crossDomainPolicy === "deny") return failure("BLOCKED_URL", "Cross-domain navigation is denied by policy.");
+				const authorization = this.authorize(session.taskKey, input, crossDomainPolicy === "ask" ? "external_effect" : "read", crossDomainPolicy);
+				if (authorization) return authorization;
+			}
+			const result = await driver.tabs(session.id, input, signal);
+			if (!input.url || !result.ok) return result;
+			const finalUrl = result.receipt.tabs?.find((tab) => tab.active)?.url;
+			const blocked = finalUrl ? this.blockedRedirect(finalUrl) : "The created tab did not report its final URL.";
+			return blocked ? failure("BLOCKED_URL", blocked) : result;
+		}
+		if (input.action === "sequence") return this.executeSequence(driver, session, input, signal);
+		const target = findActionTarget(input, session.observation);
+		const risk = classifyBrowserRisk(input, target);
+		if (input.action === "upload") {
+			const invalidPath = this.invalidUploadPath(input.paths);
+			if (invalidPath) return failure("INVALID_INPUT", invalidPath);
+		}
+		const authorization = this.authorize(session.taskKey, input, risk, void 0, target);
+		if (authorization) return authorization;
+		return withRisk(await driver.perform(session.id, input, signal), risk);
+	}
+	async executeSequence(driver, session, input, signal) {
+		const config = this.options.getConfig();
+		if (input.steps.length === 0 || input.steps.length > config.limits.maxSequenceLength) return failure("INVALID_INPUT", `Sequence length must be between 1 and ${config.limits.maxSequenceLength}.`);
+		const initialDocument = session.observation?.documentId;
+		let revision = input.revision;
+		let last;
+		let highestRisk = "draft";
+		for (const step of input.steps) {
+			const risk = classifyBrowserRisk(step, findActionTarget(step, session.observation));
+			if (riskRank(risk) > riskRank(highestRisk)) highestRisk = risk;
+		}
+		const authorization = this.authorize(session.taskKey, input, highestRisk);
+		if (authorization) return authorization;
+		for (const step of input.steps) {
+			const primitive = {
+				...step,
+				sessionId: session.id,
+				revision
+			};
+			last = await driver.perform(session.id, primitive, signal);
+			if (!last.ok) return last;
+			const observation = last.receipt.observation;
+			if (observation) {
+				session.observation = observation;
+				revision = observation.revision;
+				if (initialDocument && observation.documentId !== initialDocument) return failure("STALE_OBSERVATION", "Sequence stopped because navigation replaced the document.", observation);
+			}
+		}
+		if (!last?.ok) return failure("INVALID_INPUT", "Sequence did not execute.");
+		return {
+			ok: true,
+			receipt: {
+				...last.receipt,
+				action: "sequence",
+				risk: highestRisk
+			}
+		};
+	}
+	authorize(sessionKey, input, risk, explicitPolicy, target) {
+		const security = this.options.getConfig().security;
+		const policy = explicitPolicy ?? (input.action === "upload" ? security.uploads : security.consequentialActions);
+		if (!browserRiskNeedsApproval(risk) || policy === "allow") return null;
+		if (policy === "deny") return failure("APPROVAL_REQUIRED", `Browser action is denied by policy (${risk}).`);
+		if (consumeBrowserApproval(input.approvalId, sessionKey, input)) return null;
+		const approval = createBrowserApproval(sessionKey, input, risk, browserApprovalSummary(input, target));
+		this.options.emit?.("browser.approval.required", approval);
+		return {
+			ok: false,
+			error: {
+				code: "APPROVAL_REQUIRED",
+				message: "This browser action needs local-owner approval before it can run.",
+				approval: {
+					id: approval.id,
+					risk,
+					summary: approval.summary,
+					expiresAt: approval.expiresAt
+				}
+			}
+		};
+	}
+	validateUrl(url) {
+		if (containsApiKeyPattern(url)) return "URL contains a credential-like value.";
+		try {
+			const host = new URL(url).hostname.toLowerCase();
+			assertBrowserUrlAllowed(url, { privateHostAllowed: this.options.getConfig().security.allowedPrivateHosts.some((candidate) => candidate.toLowerCase() === host) });
+			return null;
+		} catch (error) {
+			return error instanceof Error ? error.message : String(error);
+		}
+	}
+	validateRedirect(requestedUrl, result) {
+		if (!result.ok || !result.receipt.observation) return result;
+		const finalUrl = result.receipt.observation.url;
+		if (finalUrl === requestedUrl) return result;
+		const blocked = this.blockedRedirect(finalUrl);
+		return blocked ? failure("BLOCKED_URL", blocked, result.receipt.observation) : result;
+	}
+	blockedRedirect(finalUrl) {
+		try {
+			const host = new URL(finalUrl).hostname.toLowerCase();
+			return checkPostRedirectUrl(finalUrl, { privateHostAllowed: this.options.getConfig().security.allowedPrivateHosts.some((candidate) => candidate.toLowerCase() === host) });
+		} catch {
+			return "Browser returned an invalid final URL.";
+		}
+	}
+	crossDomainPolicy(currentUrl, nextUrl) {
+		if (!currentUrl || currentUrl === "about:blank") return "allow";
+		try {
+			if (new URL(currentUrl).hostname === new URL(nextUrl).hostname) return "allow";
+		} catch {
+			return "allow";
+		}
+		return this.options.getConfig().security.crossDomainNavigation;
+	}
+	invalidUploadPath(paths) {
+		const roots = this.options.allowedUploadRoots ?? [];
+		if (roots.length === 0) return "File uploads are unavailable because no upload root is configured.";
+		const normalizedRoots = roots.map((root) => resolve(root));
+		const invalid = paths.find((path) => {
+			if (!isAbsolute(path)) return true;
+			const absolute = resolve(path);
+			return !normalizedRoots.some((root) => {
+				const child = relative(root, absolute);
+				return child === "" || !child.startsWith("..") && !isAbsolute(child);
+			});
+		});
+		return invalid ? `Upload path is outside the allowed workspace: ${invalid}` : null;
+	}
+	async resolveSession(taskKey, requestedId) {
+		const existing = this.sessionsByTask.get(taskKey);
+		if (existing) return !requestedId || requestedId === existing.id ? existing : null;
+		if (requestedId) return null;
+		const session = {
+			id: randomUUID(),
+			taskKey,
+			lastUsedAt: Date.now()
+		};
+		const driver = await this.getDriver();
+		await driver.createSession(session.id);
+		this.sessionsByTask.set(taskKey, session);
+		this.options.emit?.("browser.session.started", {
+			sessionId: session.id,
+			taskKey,
+			driver: driver.kind
+		});
+		return session;
+	}
+	async getDriver() {
+		if (this.driver) return this.driver;
+		this.driver = await this.options.createDriver();
+		await this.driver.connect();
+		return this.driver;
+	}
+	constrainResult(result) {
+		const observation = "error" in result ? result.error.observation : result.receipt.observation;
+		if (!observation) return result;
+		const { maxNodes, maxCharacters } = this.options.getConfig().observation;
+		const nodes = [];
+		let characters = 0;
+		for (const node of observation.nodes.slice(0, maxNodes)) {
+			const size = node.name.length + (node.value?.length ?? 0) + (node.description?.length ?? 0);
+			if (characters + size > maxCharacters) break;
+			characters += size;
+			nodes.push(node);
+		}
+		if (nodes.length === observation.nodes.length) return result;
+		const refs = new Set(nodes.map((node) => node.ref));
+		const constrained = {
+			...observation,
+			nodes,
+			changes: {
+				added: observation.changes.added.filter((node) => refs.has(node.ref)),
+				changed: observation.changes.changed.filter((node) => refs.has(node.ref)),
+				removed: observation.changes.removed
+			}
+		};
+		return "error" in result ? {
+			ok: false,
+			error: {
+				...result.error,
+				observation: constrained
+			}
+		} : {
+			ok: true,
+			receipt: {
+				...result.receipt,
+				observation: constrained
+			}
+		};
+	}
+	evictExpiredSessions() {
+		const expiresBefore = Date.now() - this.options.getConfig().limits.sessionTimeoutMs;
+		for (const [taskKey, session] of this.sessionsByTask) {
+			if (session.lastUsedAt >= expiresBefore) continue;
+			this.driver?.closeSession(session.id).catch(() => {});
+			this.sessionsByTask.delete(taskKey);
+		}
+	}
+};
+function failure(code, message, observation) {
+	return {
+		ok: false,
+		error: {
+			code,
+			message,
+			observation
+		}
+	};
+}
+function withRisk(result, risk) {
+	return result.ok ? {
+		ok: true,
+		receipt: {
+			...result.receipt,
+			risk
+		}
+	} : result;
+}
+function riskRank(risk) {
+	return [
+		"read",
+		"draft",
+		"external_effect",
+		"destructive",
+		"sensitive"
+	].indexOf(risk);
+}
+function findActionTarget(input, observation) {
+	const ref = "ref" in input && input.ref ? input.ref : input.action === "press" ? observation?.focused : void 0;
+	return ref ? observation?.nodes.find((node) => node.ref === ref) : void 0;
+}
+function browserApprovalSummary(input, target) {
+	const targetName = target?.name.trim() ? ` “${target.name.slice(0, 120)}”` : "";
+	switch (input.action) {
+		case "navigate": return `Navigate to ${safeUrlLabel(input.url)}.`;
+		case "tabs": return input.url ? `Open a tab at ${safeUrlLabel(input.url)}.` : `Change browser tabs (${input.operation}).`;
+		case "click": return `Click${targetName || ` element ${input.ref}`}.`;
+		case "fill": return `${target?.states.includes("sensitive") ? "Fill a sensitive field" : "Fill field"}${targetName || ` ${input.ref}`}${input.submit ? " and submit the form" : ""}.`;
+		case "upload": return `Upload ${input.paths.length} file${input.paths.length === 1 ? "" : "s"}${targetName ? ` using${targetName}` : ""}.`;
+		case "press": return `Press ${input.key}${targetName ? ` on${targetName}` : ""}.`;
+		case "sequence": return `Run ${input.steps.length} browser actions as one sequence.`;
+		default: return `Run browser action “${input.action}”${targetName ? ` on${targetName}` : ""}.`;
+	}
+}
+function safeUrlLabel(raw) {
+	try {
+		const url = new URL(raw);
+		return `${url.origin}${url.pathname}`.slice(0, 240);
+	} catch {
+		return "the requested URL";
+	}
+}
+function withoutVisual(value) {
+	if (!value || typeof value !== "object") return value;
+	return JSON.parse(JSON.stringify(value, (key, child) => key === "visual" ? void 0 : child));
+}
+//#endregion
+export { BrowserRuntime };

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

@@ -5,10 +5,10 @@
  * no cloud metadata endpoints, no API key exfiltration attempts.
  *
  * @param raw URL string from the agent
- * @param options.allowPrivateUrls When true, skip private-IP blocking (cloud metadata still blocked)
+ * @param options.privateHostAllowed When true, skip private-IP blocking (cloud metadata still blocked)
  */
 export declare function assertBrowserUrlAllowed(raw: string, options?: {
-    allowPrivateUrls?: boolean;
+    privateHostAllowed?: boolean;
 }): void;
 /**
  * Check whether a URL targets an always-blocked cloud metadata endpoint.
@@ -33,5 +33,5 @@ export declare function containsApiKeyPattern(raw: string): boolean;
  * @returns Error message string if blocked, `undefined` if safe.
  */
 export declare function checkPostRedirectUrl(finalUrl: string, options?: {
-    allowPrivateUrls?: boolean;
+    privateHostAllowed?: boolean;
 }): string | undefined;

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

@@ -7,7 +7,7 @@ import { isIPv4, isIPv6 } from "node:net";
 */
 const ALWAYS_BLOCKED_HOSTNAMES = new Set(["metadata.google.internal", "metadata.goog"]);
 /**
-* Cloud metadata / IMDS IPv4 addresses — always blocked regardless of `allowPrivateUrls`.
+* Cloud metadata / IMDS IPv4 addresses — always blocked regardless of `privateHostAllowed`.
 * Covers AWS, GCP, Azure, DigitalOcean, Oracle, Alibaba Cloud, and ECS task metadata.
 */
 const ALWAYS_BLOCKED_IPV4 = new Set([
@@ -30,13 +30,13 @@ const API_KEY_PATTERN = /(?:sk-ant-|sk-[a-zA-Z0-9]{20,}|OPENAI_API_KEY|ANTHROPIC
 * no cloud metadata endpoints, no API key exfiltration attempts.
 *
 * @param raw URL string from the agent
-* @param options.allowPrivateUrls When true, skip private-IP blocking (cloud metadata still blocked)
+* @param options.privateHostAllowed When true, skip private-IP blocking (cloud metadata still blocked)
 */
 function assertBrowserUrlAllowed(raw, options) {
 	const parsed = parseAndValidateUrl(raw);
 	assertNotApiKeyExfiltration(raw);
 	assertNotAlwaysBlocked(parsed.hostname);
-	assertNotPrivate(parsed.hostname, options?.allowPrivateUrls ?? false);
+	assertNotPrivate(parsed.hostname, options?.privateHostAllowed ?? false);
 }
 /**
 * Check whether a URL targets an always-blocked cloud metadata endpoint.
@@ -79,7 +79,7 @@ function containsApiKeyPattern(raw) {
 */
 function checkPostRedirectUrl(finalUrl, options) {
 	if (isAlwaysBlockedUrl(finalUrl)) return "Blocked: redirect landed on a cloud metadata endpoint";
-	if (options?.allowPrivateUrls) return void 0;
+	if (options?.privateHostAllowed) return void 0;
 	try {
 		const host = new URL(finalUrl.trim()).hostname.toLowerCase();
 		if (host === "localhost" || host.endsWith(".localhost")) return "Blocked: redirect landed on localhost";
@@ -111,13 +111,14 @@ function assertNotAlwaysBlocked(hostname) {
 }
 function assertNotPrivate(hostname, allowPrivate) {
 	const host = hostname.toLowerCase();
+	if (allowPrivate) return;
 	if (host === "localhost" || host.endsWith(".localhost")) throw new Error("Blocked: localhost");
 	if (isIPv4(host)) {
-		if (!allowPrivate && isBlockedIPv4(host)) throw new Error("Blocked: private or non-public IPv4 address");
+		if (isBlockedIPv4(host)) throw new Error("Blocked: private or non-public IPv4 address");
 		return;
 	}
 	if (isIPv6(host)) {
-		if (!allowPrivate && isBlockedIPv6(host)) throw new Error("Blocked: private or loopback IPv6 address");
+		if (isBlockedIPv6(host)) throw new Error("Blocked: private or loopback IPv6 address");
 		return;
 	}
 	if (host.endsWith(".local") || host.endsWith(".internal")) throw new Error("Blocked: internal hostname");

package/dist/src/browser/verification/expectation.d.ts

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

package/dist/src/browser/verification/expectation.js

@@ -0,0 +1,17 @@
+//#region src/browser/verification/expectation.ts
+function verifyBrowserExpectation(expectation, observation) {
+	if (!expectation) return null;
+	if (expectation.urlIncludes && !observation.url.includes(expectation.urlIncludes)) return `URL does not include ${JSON.stringify(expectation.urlIncludes)}`;
+	if (expectation.titleIncludes && !observation.title.includes(expectation.titleIncludes)) return `Title does not include ${JSON.stringify(expectation.titleIncludes)}`;
+	if (expectation.textIncludes) {
+		if (!observation.nodes.map((node) => `${node.name}\n${node.value ?? ""}\n${node.description ?? ""}`).join("\n").includes(expectation.textIncludes)) return `Page does not include ${JSON.stringify(expectation.textIncludes)}`;
+	}
+	if (expectation.ref && expectation.state) {
+		const present = observation.nodes.some((node) => node.ref === expectation.ref);
+		if (expectation.state === "visible" && !present) return `Target ${expectation.ref} is not visible`;
+		if (expectation.state === "hidden" && present) return `Target ${expectation.ref} is still visible`;
+	}
+	return null;
+}
+//#endregion
+export { verifyBrowserExpectation };

package/dist/src/cli/command-loaders.js

@@ -18,6 +18,7 @@ const REGISTRY_COMMAND_MODULES = {
 	doctor: () => import("./commands/doctor/index.js"),
 	support: () => import("./commands/support.js"),
 	runtime: () => import("./commands/runtime.js"),
+	platform: () => import("./commands/platform.js"),
 	image: () => import("./commands/image.js"),
 	channels: () => import("./commands/channels.js"),
 	models: () => import("./commands/models.js"),

package/dist/src/cli/command-manifest.js

@@ -91,6 +91,10 @@ const ROOT_HELP_COMMANDS = [
 		name: "runtime",
 		description: "Manage Node.js and Python tool runtimes used by agents"
 	},
+	{
+		name: "platform",
+		description: "Connect to XOPC Cloud or an enterprise platform"
+	},
 	{
 		name: "update [options]",
 		description: "Check for and install xopc updates"
@@ -137,7 +141,7 @@ const ROOT_HELP_COMMANDS = [
 	},
 	{
 		name: "browser",
-		description: "Browser automation commands (uses Playwright)"
+		description: "Browser Control v2 diagnostics and extension setup"
 	},
 	{
 		name: "agents",

package/dist/src/cli/commands/browser-cli-helpers.d.ts

@@ -1,7 +1 @@
-/**
- * CLI helpers for `xopc browser` — shared runtime setup for CLI browser commands.
- */
-export declare function executeBrowserCliAction(action: string, args: Record<string, unknown>): Promise<void>;
-export declare function validatePipelineCli(file: string): Promise<void>;
-export declare function runPipelineCli(file: string, args: Record<string, unknown>): Promise<void>;
 export declare function doctorCli(): Promise<void>;