@xopcai/xopc 0.0.250 → 0.0.252

package/dist/src/browser/automations/service.js

@@ -0,0 +1,168 @@
+import { BrowserAutomationDefinitionSchema } from "./schema.js";
+import { resolveBrowserAutomationInputs } from "./runner.js";
+import { appendBrowserAutomationRunEvent, deleteBrowserAutomation, getBrowserAutomation, getBrowserAutomationRun, hasActiveBrowserAutomationRuns, listActiveBrowserAutomationRuns, listBrowserAutomationRunEvents, listBrowserAutomationRuns, listBrowserAutomations, nextBrowserAutomationRunEventSeq, saveBrowserAutomation, saveBrowserAutomationRun } from "./repository.js";
+import { randomUUID } from "node:crypto";
+//#region src/browser/automations/service.ts
+var BrowserAutomationService = class {
+	activeRuns = /* @__PURE__ */ new Map();
+	executions = /* @__PURE__ */ new Map();
+	waiters = /* @__PURE__ */ new Map();
+	constructor(executor, emit) {
+		this.executor = executor;
+		this.emit = emit;
+		for (const run of listActiveBrowserAutomationRuns()) {
+			const endedAtMs = Date.now();
+			saveBrowserAutomationRun({
+				...run,
+				status: "failed",
+				error: "Gateway stopped before the run completed.",
+				endedAtMs,
+				durationMs: run.startedAtMs ? endedAtMs - run.startedAtMs : void 0
+			});
+		}
+	}
+	list() {
+		return listBrowserAutomations();
+	}
+	get(id) {
+		return getBrowserAutomation(id);
+	}
+	listRuns(automationId) {
+		return listBrowserAutomationRuns(automationId);
+	}
+	getRun(id) {
+		return getBrowserAutomationRun(id);
+	}
+	listRunEvents(id) {
+		return listBrowserAutomationRunEvents(id);
+	}
+	validate(definition) {
+		return BrowserAutomationDefinitionSchema.safeParse(definition);
+	}
+	save(input) {
+		const parsed = BrowserAutomationDefinitionSchema.parse(input.definition);
+		if (input.expectedId && parsed.id !== input.expectedId) throw new Error("Browser automation id cannot change.");
+		const existing = getBrowserAutomation(parsed.id);
+		const now = Date.now();
+		const automation = {
+			id: parsed.id,
+			revision: (existing?.revision ?? 0) + 1,
+			status: input.status ?? existing?.status ?? "enabled",
+			definition: parsed,
+			createdAtMs: existing?.createdAtMs ?? now,
+			updatedAtMs: now
+		};
+		saveBrowserAutomation(automation);
+		return automation;
+	}
+	remove(id) {
+		if (hasActiveBrowserAutomationRuns(id)) throw new Error("Cannot delete a running browser automation.");
+		return deleteBrowserAutomation(id);
+	}
+	startRun(automationId, inputs) {
+		const automation = getBrowserAutomation(automationId);
+		if (!automation) throw new Error("Browser automation not found.");
+		if (automation.status !== "enabled") throw new Error("Browser automation is disabled.");
+		const resolvedInputs = resolveBrowserAutomationInputs(automation.definition, inputs);
+		const run = {
+			id: randomUUID(),
+			automationId,
+			automationRevision: automation.revision,
+			definition: automation.definition,
+			status: "queued",
+			inputs: resolvedInputs,
+			createdAtMs: Date.now()
+		};
+		saveBrowserAutomationRun(run);
+		this.addEvent(run.id, "run.queued", { automationId });
+		const execution = this.execute(run);
+		this.executions.set(run.id, execution);
+		execution.finally(() => this.executions.delete(run.id)).catch(() => void 0);
+		return run;
+	}
+	cancel(runId) {
+		const active = this.activeRuns.get(runId);
+		if (!active) return false;
+		active.abort();
+		return true;
+	}
+	async shutdown() {
+		for (const active of this.activeRuns.values()) active.abort();
+		await Promise.allSettled(this.executions.values());
+	}
+	async runAndWait(automationId, inputs, signal) {
+		const run = this.startRun(automationId, inputs);
+		return new Promise((resolve) => {
+			const complete = (value) => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve(value);
+			};
+			const onAbort = () => this.cancel(run.id);
+			const set = this.waiters.get(run.id) ?? /* @__PURE__ */ new Set();
+			set.add(complete);
+			this.waiters.set(run.id, set);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) onAbort();
+		});
+	}
+	addEvent(runId, type, data) {
+		const event = {
+			id: randomUUID(),
+			runId,
+			seq: nextBrowserAutomationRunEventSeq(runId),
+			type,
+			data,
+			createdAtMs: Date.now()
+		};
+		appendBrowserAutomationRunEvent(event);
+		this.emit?.(`browser.automation.${type}`, event);
+	}
+	async execute(run) {
+		const controller = new AbortController();
+		this.activeRuns.set(run.id, controller);
+		const startedAtMs = Date.now();
+		let current = {
+			...run,
+			status: "running",
+			startedAtMs
+		};
+		saveBrowserAutomationRun(current);
+		this.addEvent(run.id, "run.started");
+		try {
+			const outcome = await this.executor({
+				definition: run.definition,
+				inputs: run.inputs,
+				signal: controller.signal,
+				onStep: (event) => this.addEvent(run.id, "step", event)
+			});
+			const endedAtMs = Date.now();
+			current = {
+				...current,
+				status: controller.signal.aborted ? "cancelled" : outcome.ok ? "succeeded" : "failed",
+				result: outcome.result,
+				error: outcome.error,
+				endedAtMs,
+				durationMs: endedAtMs - startedAtMs
+			};
+		} catch (error) {
+			const endedAtMs = Date.now();
+			current = {
+				...current,
+				status: controller.signal.aborted ? "cancelled" : "failed",
+				error: error instanceof Error ? error.message : String(error),
+				endedAtMs,
+				durationMs: endedAtMs - startedAtMs
+			};
+		}
+		saveBrowserAutomationRun(current);
+		this.addEvent(run.id, "run.completed", {
+			status: current.status,
+			error: current.error
+		});
+		this.activeRuns.delete(run.id);
+		for (const waiter of this.waiters.get(run.id) ?? []) waiter(current);
+		this.waiters.delete(run.id);
+	}
+};
+//#endregion
+export { BrowserAutomationService };

package/dist/src/browser/automations/types.d.ts

@@ -0,0 +1,90 @@
+import type { BrowserExpectation, BrowserRiskLevel } from '@xopcai/browser-control-contract';
+export type BrowserAutomationStatus = 'enabled' | 'disabled';
+export type BrowserAutomationRunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+export interface BrowserAutomationInputDefinition {
+    type: 'string' | 'number' | 'boolean';
+    required?: boolean;
+    default?: string | number | boolean;
+    description?: string;
+    choices?: Array<string | number | boolean>;
+}
+export interface BrowserSemanticTarget {
+    role: string;
+    name?: string;
+    nameIncludes?: string;
+}
+export type BrowserAutomationStep = {
+    action: 'navigate';
+    url: string;
+    expect?: BrowserExpectation;
+} | {
+    action: 'click';
+    target: BrowserSemanticTarget;
+    expect?: BrowserExpectation;
+} | {
+    action: 'fill';
+    target: BrowserSemanticTarget;
+    value: string;
+    submit?: boolean;
+    expect?: BrowserExpectation;
+} | {
+    action: 'select';
+    target: BrowserSemanticTarget;
+    value: string;
+    expect?: BrowserExpectation;
+} | {
+    action: 'press';
+    target?: BrowserSemanticTarget;
+    key: string;
+    expect?: BrowserExpectation;
+} | {
+    action: 'scroll';
+    target?: BrowserSemanticTarget;
+    deltaY: number;
+    expect?: BrowserExpectation;
+} | {
+    action: 'wait';
+    condition: 'page_idle' | 'text' | 'visible' | 'hidden';
+    value?: string;
+    target?: BrowserSemanticTarget;
+    timeoutMs?: number;
+};
+export interface BrowserAutomationDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    allowedDomains: string[];
+    risk: BrowserRiskLevel;
+    inputs: Record<string, BrowserAutomationInputDefinition>;
+    steps: BrowserAutomationStep[];
+}
+export interface BrowserAutomation {
+    id: string;
+    revision: number;
+    status: BrowserAutomationStatus;
+    definition: BrowserAutomationDefinition;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+export interface BrowserAutomationRun {
+    id: string;
+    automationId: string;
+    automationRevision: number;
+    definition: BrowserAutomationDefinition;
+    status: BrowserAutomationRunStatus;
+    inputs: Record<string, unknown>;
+    result?: unknown;
+    error?: string;
+    createdAtMs: number;
+    startedAtMs?: number;
+    endedAtMs?: number;
+    durationMs?: number;
+}
+export interface BrowserAutomationRunEvent {
+    id: string;
+    runId: string;
+    seq: number;
+    type: string;
+    data?: unknown;
+    createdAtMs: number;
+}

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

@@ -1,5 +1,5 @@
 /**
- * Where user-facing browser caches (CloakBrowser binaries, CDP launcher
+ * Where user-facing browser caches (extension artifacts and CDP launcher
  * profiles, etc.) are allowed to live.
  *
  * Restricting the writable set to the user's home directory makes it safe to

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

@@ -1,4 +1,3 @@
-import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { homedir } from "node:os";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 //#region src/browser/cache-dir-policy.ts
@@ -47,7 +46,5 @@ function assertCacheDir(input) {
 	if (r.ok === false) throw new Error(r.message);
 	return r.resolved;
 }
-var init_cache_dir_policy = __esmMin((() => {}));
 //#endregion
-init_cache_dir_policy();
-export { assertCacheDir, checkCacheDir, expandHome, init_cache_dir_policy };
+export { assertCacheDir, checkCacheDir, expandHome };

package/dist/src/browser/drivers/browser-driver.d.ts

@@ -0,0 +1,17 @@
+import type { BrowserActionInput, BrowserControlResult, BrowserNavigateInput, BrowserObservation, BrowserObserveInput, BrowserTabsInput } from '@xopcai/browser-control-contract';
+export type BrowserPrimitiveInput = Exclude<BrowserActionInput, BrowserNavigateInput | BrowserObserveInput | BrowserTabsInput | {
+    action: 'sequence';
+} | {
+    action: 'close';
+}>;
+export interface BrowserDriver {
+    readonly kind: 'playwright' | 'extension';
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    createSession(sessionId: string): Promise<void>;
+    closeSession(sessionId: string): Promise<void>;
+    navigate(sessionId: string, input: BrowserNavigateInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+    observe(sessionId: string, input: BrowserObserveInput, signal?: AbortSignal): Promise<BrowserObservation>;
+    perform(sessionId: string, input: BrowserPrimitiveInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+    tabs(sessionId: string, input: BrowserTabsInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+}

package/dist/src/browser/drivers/create-driver.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from '../../config/schema.js';
+import type { BrowserDriver } from './browser-driver.js';
+export declare function createBrowserDriver(config: Config['browser']): Promise<BrowserDriver>;

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

@@ -0,0 +1,84 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { loadPlaywrightCoreModule } from "../providers/playwright-doctor.js";
+import { BrowserbaseProvider } from "../providers/browserbase.js";
+import { BrowserUseProvider } from "../providers/browser-use.js";
+import { acquireExtensionBrowserServer } from "../providers/extension-ws-acquire.js";
+import { ExtensionDriver } from "./extension-driver.js";
+import { PlaywrightDriver } from "./playwright-driver.js";
+//#region src/browser/drivers/create-driver.ts
+init_logger();
+const log = createLogger("BrowserDriverFactory");
+async function createBrowserDriver(config) {
+	const limits = config.limits;
+	if (config.driver.kind === "extension") {
+		const { provider, release } = await acquireExtensionBrowserServer({
+			host: "127.0.0.1",
+			port: 19820,
+			connectionTimeout: limits.actionTimeoutMs,
+			commandTimeout: limits.actionTimeoutMs
+		});
+		return new ExtensionDriver(provider, limits.actionTimeoutMs, config.observation.visualFallback, release);
+	}
+	const driver = config.driver;
+	return new PlaywrightDriver({
+		connect: () => connectPlaywright(driver),
+		maxNodes: config.observation.maxNodes,
+		maxCharacters: config.observation.maxCharacters,
+		visualFallback: config.observation.visualFallback,
+		actionTimeoutMs: limits.actionTimeoutMs
+	});
+}
+async function connectPlaywright(driver) {
+	if (driver.kind === "remote") {
+		const provider = driver.provider === "browserbase" ? new BrowserbaseProvider({
+			type: driver.provider,
+			apiKey: driver.apiKey,
+			projectId: driver.projectId,
+			region: driver.region
+		}) : new BrowserUseProvider({
+			type: driver.provider,
+			apiKey: driver.apiKey,
+			projectId: driver.projectId,
+			region: driver.region
+		});
+		return {
+			...await provider.connect(),
+			release: () => provider.disconnect()
+		};
+	}
+	const playwright = await loadPlaywrightCoreModule();
+	const chromium = playwright.chromium ?? playwright.default?.chromium;
+	if (!chromium) throw new Error("playwright-core did not expose Chromium");
+	if (driver.kind === "cdp") {
+		const browser = await chromium.connectOverCDP(driver.endpoint);
+		const context = browser.contexts()[0] ?? await browser.newContext();
+		log.info({ kind: driver.kind }, "Browser driver connected");
+		return {
+			browser,
+			context
+		};
+	}
+	const browser = await chromium.launch({
+		headless: driver.headless,
+		executablePath: driver.executablePath,
+		args: ["--no-sandbox", "--disable-setuid-sandbox"]
+	});
+	const context = await createContext(browser);
+	log.info({
+		kind: driver.kind,
+		headless: driver.headless
+	}, "Browser driver connected");
+	return {
+		browser,
+		context
+	};
+}
+async function createContext(browser) {
+	return browser.newContext({ viewport: {
+		width: 1280,
+		height: 720
+	} });
+}
+//#endregion
+export { createBrowserDriver };

package/dist/src/browser/drivers/extension-driver.d.ts

@@ -0,0 +1,20 @@
+import type { BrowserControlResult, BrowserNavigateInput, BrowserObservation, BrowserObserveInput, BrowserTabsInput } from '@xopcai/browser-control-contract';
+import type { ExtensionBrowserProvider } from '../providers/extension.js';
+import type { BrowserDriver, BrowserPrimitiveInput } from './browser-driver.js';
+export declare class ExtensionDriver implements BrowserDriver {
+    private readonly provider;
+    private readonly timeoutMs;
+    private readonly visualFallback;
+    private readonly release;
+    readonly kind: "extension";
+    constructor(provider: ExtensionBrowserProvider, timeoutMs: number, visualFallback: boolean, release: () => Promise<void>);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    createSession(_sessionId: string): Promise<void>;
+    closeSession(sessionId: string): Promise<void>;
+    navigate(_sessionId: string, input: BrowserNavigateInput): Promise<BrowserControlResult>;
+    observe(_sessionId: string, input: BrowserObserveInput): Promise<BrowserObservation>;
+    perform(_sessionId: string, input: BrowserPrimitiveInput): Promise<BrowserControlResult>;
+    tabs(_sessionId: string, input: BrowserTabsInput): Promise<BrowserControlResult>;
+    private send;
+}

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

@@ -0,0 +1,47 @@
+//#region src/browser/drivers/extension-driver.ts
+var ExtensionDriver = class {
+	kind = "extension";
+	constructor(provider, timeoutMs, visualFallback, release) {
+		this.provider = provider;
+		this.timeoutMs = timeoutMs;
+		this.visualFallback = visualFallback;
+		this.release = release;
+	}
+	async connect() {
+		await this.provider.start();
+		await this.provider.waitForConnection();
+	}
+	async disconnect() {
+		await this.release();
+	}
+	async createSession(_sessionId) {
+		await this.connect();
+	}
+	async closeSession(sessionId) {
+		await this.send({
+			action: "close",
+			sessionId
+		});
+	}
+	navigate(_sessionId, input) {
+		return this.send(input);
+	}
+	async observe(_sessionId, input) {
+		const result = await this.send(input);
+		if ("error" in result) throw new Error(result.error.message);
+		const observation = result.receipt.observation;
+		if (!observation) throw new Error("Extension returned no browser observation");
+		return observation;
+	}
+	perform(_sessionId, input) {
+		return this.send(input);
+	}
+	tabs(_sessionId, input) {
+		return this.send(input);
+	}
+	async send(input) {
+		return (await this.provider.send(input, this.timeoutMs, this.visualFallback)).result;
+	}
+};
+//#endregion
+export { ExtensionDriver };

package/dist/src/browser/drivers/playwright-driver.d.ts

@@ -0,0 +1,38 @@
+import type { BrowserControlResult, BrowserNavigateInput, BrowserObservation, BrowserObserveInput, BrowserTabsInput } from '@xopcai/browser-control-contract';
+import type { Browser, BrowserContext } from 'playwright-core';
+import type { BrowserDriver, BrowserPrimitiveInput } from './browser-driver.js';
+export interface PlaywrightConnection {
+    browser: Browser;
+    context: BrowserContext;
+    release?: () => Promise<void>;
+}
+export interface PlaywrightDriverOptions {
+    connect: () => Promise<PlaywrightConnection>;
+    maxNodes: number;
+    maxCharacters: number;
+    visualFallback: boolean;
+    actionTimeoutMs: number;
+}
+export declare class PlaywrightDriver implements BrowserDriver {
+    private readonly options;
+    readonly kind: "playwright";
+    private connection;
+    private sessions;
+    constructor(options: PlaywrightDriverOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    createSession(sessionId: string): Promise<void>;
+    closeSession(sessionId: string): Promise<void>;
+    navigate(sessionId: string, input: BrowserNavigateInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+    observe(sessionId: string, input: BrowserObserveInput, signal?: AbortSignal): Promise<BrowserObservation>;
+    perform(sessionId: string, input: BrowserPrimitiveInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+    tabs(sessionId: string, input: BrowserTabsInput, signal?: AbortSignal): Promise<BrowserControlResult>;
+    private wait;
+    private verifiedResult;
+    private captureVisual;
+    private activeState;
+    private session;
+    private createPageState;
+    private context;
+    private listTabs;
+}