@xopcai/xopc 0.0.251 → 0.0.252

package/dist/src/browser/session-lifecycle.js

@@ -1,136 +0,0 @@
-import { createLogger } from "../utils/logger/index.js";
-import { init_logger } from "../utils/logger.js";
-//#region src/browser/session-lifecycle.ts
-init_logger();
-const log = createLogger("BrowserLifecycle");
-const DEFAULT_TRACING = {
-	enabled: false,
-	outputDir: "/tmp/xopc-traces",
-	screenshots: true,
-	snapshots: false
-};
-/**
-* Start Playwright tracing on a browser context for session recording.
-* Captures network, actions, and optionally screenshots/snapshots.
-*/
-async function startTracing(context, options) {
-	const opts = {
-		...DEFAULT_TRACING,
-		...options
-	};
-	if (!opts.enabled) return;
-	try {
-		await context.tracing.start({
-			screenshots: opts.screenshots ?? true,
-			snapshots: opts.snapshots ?? false
-		});
-		log.info({ outputDir: opts.outputDir }, "Session tracing started");
-	} catch (e) {
-		const msg = e instanceof Error ? e.message : String(e);
-		log.warn({ errorMessage: msg }, `Failed to start tracing: ${msg}`);
-	}
-}
-/**
-* Stop tracing and save the trace file.
-*
-* @returns Path to the saved trace file, or undefined if tracing was not active.
-*/
-async function stopTracing(context, options) {
-	const opts = {
-		...DEFAULT_TRACING,
-		...options
-	};
-	if (!opts.enabled) return void 0;
-	const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-	const tracePath = `${opts.outputDir}/trace-${timestamp}.zip`;
-	try {
-		const { mkdir } = await import("node:fs/promises");
-		await mkdir(opts.outputDir, { recursive: true });
-		await context.tracing.stop({ path: tracePath });
-		log.info({ tracePath }, "Session trace saved");
-		return tracePath;
-	} catch (e) {
-		const msg = e instanceof Error ? e.message : String(e);
-		log.warn({ errorMessage: msg }, `Failed to save trace: ${msg}`);
-		return;
-	}
-}
-/**
-* Known bot detection indicators in page content or response headers.
-* When detected, we log a warning so the agent/user can adjust strategy.
-*/
-const BOT_DETECTION_PATTERNS = [
-	/captcha/i,
-	/recaptcha/i,
-	/hcaptcha/i,
-	/cloudflare.*challenge/i,
-	/please verify you are (a )?human/i,
-	/access denied/i,
-	/403 forbidden/i,
-	/blocked.*bot/i,
-	/automated.*browser/i,
-	/unusual.*traffic/i,
-	/just a moment/i,
-	/checking your browser/i,
-	/security check/i,
-	/verify.*not.*robot/i,
-	/turnstile/i,
-	/browser.*verification/i
-];
-/**
-* Check a page for signs of bot detection / CAPTCHA challenge.
-* Returns indicators found. Non-blocking — for advisory logging only.
-*/
-async function checkBotDetection(page) {
-	const indicators = [];
-	try {
-		const combined = `${await page.title()}\n${await page.evaluate(() => globalThis.document.body.innerText.slice(0, 2e3)).catch(() => "")}`;
-		for (const pattern of BOT_DETECTION_PATTERNS) {
-			const match = combined.match(pattern);
-			if (match) indicators.push(match[0]);
-		}
-		if (indicators.length > 0) log.warn({
-			url: page.url(),
-			indicators
-		}, `Bot detection likely: ${indicators.join(", ")}`);
-	} catch {}
-	return {
-		detected: indicators.length > 0,
-		indicators
-	};
-}
-/**
-* Kill orphan Chromium processes that may have been left behind by crashed sessions.
-*
-* This is a best-effort cleanup. On macOS/Linux, searches for chromium/chrome
-* processes with the `--no-sandbox` flag (which xopc adds to all launches).
-*
-* @returns Number of processes killed.
-*/
-async function cleanupOrphanProcesses() {
-	const { exec } = await import("node:child_process");
-	const { promisify } = await import("node:util");
-	const execAsync = promisify(exec);
-	let killed = 0;
-	try {
-		const { stdout } = await execAsync("ps aux | grep -E \"chromium|chrome\" | grep \"no-sandbox\" | grep -v grep").catch(() => ({ stdout: "" }));
-		const lines = stdout.trim().split("\n").filter(Boolean);
-		for (const line of lines) {
-			const parts = line.trim().split(/\s+/);
-			const pid = Number(parts[1]);
-			if (!pid || pid === process.pid) continue;
-			try {
-				process.kill(pid, "SIGTERM");
-				killed++;
-				log.info({ pid }, "Killed orphan browser process");
-			} catch {}
-		}
-		if (killed > 0) log.info({ killed }, `Cleaned up ${killed} orphan browser process(es)`);
-	} catch (e) {
-		const msg = e instanceof Error ? e.message : String(e);
-		log.debug({ errorMessage: msg }, "Orphan cleanup skipped or failed");
-	}
-	return killed;
-}
-//#endregion
-export { checkBotDetection, cleanupOrphanProcesses, startTracing, stopTracing };

package/dist/src/browser/snapshot-helpers.d.ts

@@ -1,24 +0,0 @@
-/**
- * Snapshot intelligence helpers — structure-aware truncation for ARIA snapshots.
- *
- * ARIA snapshots use indentation-based YAML-like trees. Naive character-based
- * truncation can split in the middle of a node, making the output confusing.
- * These helpers preserve tree-node boundaries and provide metadata.
- */
-/**
- * Truncate an ARIA snapshot at a line boundary, preserving complete tree nodes.
- *
- * Strategy:
- * 1. If the text is within `maxLength`, return as-is.
- * 2. Find the last newline before `maxLength`.
- * 3. Walk backwards to find a line at indentation level ≤ 2 (top-level nodes),
- *    ensuring we don't cut inside a deeply nested subtree.
- * 4. Append a truncation notice with stats.
- */
-export declare function truncateSnapshotAtBoundary(text: string, maxLength: number): string;
-/**
- * Produce a compact summary header for a snapshot.
- * Counts interactive elements (links, buttons, inputs) to help the agent
- * understand page complexity at a glance.
- */
-export declare function snapshotSummaryHeader(snapshotText: string, pageUrl: string): string;

package/dist/src/browser/snapshot-helpers.js

@@ -1,70 +0,0 @@
-//#region src/browser/snapshot-helpers.ts
-/**
-* Snapshot intelligence helpers — structure-aware truncation for ARIA snapshots.
-*
-* ARIA snapshots use indentation-based YAML-like trees. Naive character-based
-* truncation can split in the middle of a node, making the output confusing.
-* These helpers preserve tree-node boundaries and provide metadata.
-*/
-/**
-* Truncate an ARIA snapshot at a line boundary, preserving complete tree nodes.
-*
-* Strategy:
-* 1. If the text is within `maxLength`, return as-is.
-* 2. Find the last newline before `maxLength`.
-* 3. Walk backwards to find a line at indentation level ≤ 2 (top-level nodes),
-*    ensuring we don't cut inside a deeply nested subtree.
-* 4. Append a truncation notice with stats.
-*/
-function truncateSnapshotAtBoundary(text, maxLength) {
-	if (text.length <= maxLength) return text;
-	let cutoff = text.lastIndexOf("\n", maxLength);
-	if (cutoff <= 0) return `${text.slice(0, maxLength)}\n... (truncated)`;
-	const searchStart = Math.max(0, cutoff - 2e3);
-	const lines = text.slice(searchStart, cutoff).split("\n");
-	let bestCutIndex = cutoff;
-	let accumulated = cutoff;
-	for (let i = lines.length - 1; i >= 0; i--) {
-		const line = lines[i];
-		const indent = line.search(/\S/);
-		if (indent >= 0 && indent <= 2) {
-			bestCutIndex = accumulated;
-			break;
-		}
-		accumulated -= line.length + 1;
-	}
-	const truncated = text.slice(0, bestCutIndex);
-	const totalLines = text.split("\n").length;
-	const shownLines = truncated.split("\n").length;
-	return `${truncated}\n... (truncated: showing ${shownLines} of ${totalLines} lines, ${totalLines - shownLines} lines omitted)`;
-}
-/**
-* Produce a compact summary header for a snapshot.
-* Counts interactive elements (links, buttons, inputs) to help the agent
-* understand page complexity at a glance.
-*/
-function snapshotSummaryHeader(snapshotText, pageUrl) {
-	const lines = snapshotText.split("\n");
-	const totalLines = lines.length;
-	let linkCount = 0;
-	let buttonCount = 0;
-	let inputCount = 0;
-	let imageCount = 0;
-	for (const line of lines) {
-		const trimmed = line.trimStart();
-		if (trimmed.startsWith("- link ") || trimmed.startsWith("- link:")) linkCount++;
-		if (trimmed.startsWith("- button ") || trimmed.startsWith("- button:")) buttonCount++;
-		if (trimmed.startsWith("- textbox ") || trimmed.startsWith("- textbox:") || trimmed.startsWith("- searchbox ") || trimmed.startsWith("- combobox ")) inputCount++;
-		if (trimmed.startsWith("- img ") || trimmed.startsWith("- img:")) imageCount++;
-	}
-	const parts = [`Page: ${pageUrl}`, `Snapshot: ${totalLines} lines`];
-	const counts = [];
-	if (linkCount > 0) counts.push(`${linkCount} links`);
-	if (buttonCount > 0) counts.push(`${buttonCount} buttons`);
-	if (inputCount > 0) counts.push(`${inputCount} inputs`);
-	if (imageCount > 0) counts.push(`${imageCount} images`);
-	if (counts.length > 0) parts.push(`Interactive: ${counts.join(", ")}`);
-	return parts.join(" | ");
-}
-//#endregion
-export { snapshotSummaryHeader, truncateSnapshotAtBoundary };

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

@@ -1,46 +0,0 @@
-/**
- * Stealth launch utilities for anti-detection browser automation.
- *
- * Provides argument deduplication, fingerprint seed generation, and
- * macOS quarantine attribute removal. Shared by CloakBrowser provider
- * and enhanced local launch paths.
- */
-export interface StealthOptions {
-    /** Timezone to emulate (e.g. "America/New_York"). */
-    timezone?: string;
-    /** Locale to emulate (e.g. "en-US"). */
-    locale?: string;
-    /** Public IP for WebRTC leak prevention. */
-    webrtcIp?: string;
-    /** Platform to emulate in fingerprint (e.g. "windows", "macos"). */
-    fingerprintPlatform?: string;
-}
-/** Strip sandbox flags before passing user extraArgs to CloakBrowser. */
-export declare function filterCloakBrowserExtraArgs(extraArgs?: string[]): string[];
-/**
- * Build stealth launch args with deduplication.
- * User `extraArgs` override any default args with the same `--key=` prefix.
- */
-export declare function buildStealthArgs(extraArgs?: string[], options?: StealthOptions): string[];
-/**
- * Basic stealth args for the local Playwright launcher (less aggressive than CloakBrowser).
- * Does not include fingerprint or geo args — just reduces automation signals.
- */
-export declare function buildLocalStealthArgs(extraArgs?: string[]): string[];
-/** Generate a timestamp-based fingerprint seed for CloakBrowser. */
-export declare function generateFingerprintSeed(): number;
-/**
- * Remove the `com.apple.quarantine` extended attribute from a file or app bundle on macOS.
- * Files downloaded from the internet are tagged with this attribute, causing Gatekeeper
- * to block unsigned binaries. Without this, CloakBrowser silently fails to launch.
- *
- * Non-fatal — logs and returns on any error.
- */
-export declare function removeQuarantineAttr(path: string): Promise<void>;
-/**
- * JavaScript snippet to inject into every new page to hide automation signals.
- * Removes `navigator.webdriver` and patches other detectable properties.
- */
-export declare const WEBDRIVER_OVERRIDE_SCRIPT = "\nObject.defineProperty(navigator, 'webdriver', { get: () => undefined });\nif (navigator.plugins.length === 0) {\n  Object.defineProperty(navigator, 'plugins', {\n    get: () => [1, 2, 3, 4, 5],\n  });\n}\nObject.defineProperty(navigator, 'languages', {\n  get: () => ['en-US', 'en'],\n});\nwindow.chrome = window.chrome || {};\nwindow.chrome.runtime = window.chrome.runtime || {};\n";
-/** Ensure a binary file has executable permissions (Unix only, no-op on Windows). */
-export declare function makeExecutable(path: string): Promise<void>;

package/dist/src/browser/stealth.js

@@ -1,163 +0,0 @@
-import { createLogger } from "../utils/logger/index.js";
-import { init_logger } from "../utils/logger.js";
-import { platform } from "node:os";
-import { exec } from "node:child_process";
-import { chmod, stat } from "node:fs/promises";
-import { promisify } from "node:util";
-//#region src/browser/stealth.ts
-/**
-* Stealth launch utilities for anti-detection browser automation.
-*
-* Provides argument deduplication, fingerprint seed generation, and
-* macOS quarantine attribute removal. Shared by CloakBrowser provider
-* and enhanced local launch paths.
-*/
-init_logger();
-const execAsync = promisify(exec);
-const log = createLogger("BrowserStealth");
-/**
-* Default Chromium args that reduce automation detectability for CloakBrowser.
-* Does not include `--no-sandbox` — CloakBrowser rejects it with an infobar warning.
-*/
-const BASE_STEALTH_ARGS = [
-	"--disable-blink-features=AutomationControlled",
-	"--disable-infobars",
-	"--disable-dev-shm-usage",
-	"--disable-background-networking",
-	"--disable-default-apps",
-	"--disable-extensions-except=",
-	"--disable-sync",
-	"--metrics-recording-only",
-	"--no-first-run"
-];
-/** Flags CloakBrowser does not support (shown as unsupported infobar if passed). */
-const CLOAK_UNSUPPORTED_FLAGS = new Set(["--no-sandbox", "--disable-setuid-sandbox"]);
-/** Strip sandbox flags before passing user extraArgs to CloakBrowser. */
-function filterCloakBrowserExtraArgs(extraArgs = []) {
-	return extraArgs.filter((arg) => !CLOAK_UNSUPPORTED_FLAGS.has(arg.split("=")[0] ?? arg));
-}
-/**
-* Build stealth launch args with deduplication.
-* User `extraArgs` override any default args with the same `--key=` prefix.
-*/
-function buildStealthArgs(extraArgs = [], options = {}) {
-	const argsMap = /* @__PURE__ */ new Map();
-	const positionalArgs = [];
-	for (const arg of BASE_STEALTH_ARGS) {
-		const eqIdx = arg.indexOf("=");
-		if (eqIdx >= 0) argsMap.set(arg.slice(0, eqIdx), arg);
-		else positionalArgs.push(arg);
-	}
-	const fingerprintPlatform = options.fingerprintPlatform ?? detectFingerprintPlatform();
-	argsMap.set("--fingerprint", `--fingerprint=${generateFingerprintSeed()}`);
-	argsMap.set("--fingerprint-platform", `--fingerprint-platform=${fingerprintPlatform}`);
-	if (options.timezone) argsMap.set("--fingerprint-timezone", `--fingerprint-timezone=${options.timezone}`);
-	if (options.locale) {
-		argsMap.set("--lang", `--lang=${options.locale}`);
-		argsMap.set("--fingerprint-locale", `--fingerprint-locale=${options.locale}`);
-	}
-	if (options.webrtcIp) argsMap.set("--fingerprint-webrtc-ip", `--fingerprint-webrtc-ip=${options.webrtcIp}`);
-	for (const arg of extraArgs) {
-		const eqIdx = arg.indexOf("=");
-		if (eqIdx >= 0) argsMap.set(arg.slice(0, eqIdx), arg);
-		else positionalArgs.push(arg);
-	}
-	const kvArgs = [...argsMap.values()].sort();
-	return [...positionalArgs, ...kvArgs];
-}
-/**
-* Basic stealth args for the local Playwright launcher (less aggressive than CloakBrowser).
-* Does not include fingerprint or geo args — just reduces automation signals.
-*/
-function buildLocalStealthArgs(extraArgs = []) {
-	const baseArgs = [
-		"--disable-blink-features=AutomationControlled",
-		"--no-sandbox",
-		"--disable-setuid-sandbox"
-	];
-	const seen = /* @__PURE__ */ new Set();
-	const result = [];
-	for (const arg of extraArgs) {
-		const key = arg.split("=")[0];
-		if (!seen.has(key)) {
-			seen.add(key);
-			result.push(arg);
-		}
-	}
-	for (const arg of baseArgs) {
-		const key = arg.split("=")[0];
-		if (!seen.has(key)) {
-			seen.add(key);
-			result.push(arg);
-		}
-	}
-	return result;
-}
-/** Generate a timestamp-based fingerprint seed for CloakBrowser. */
-function generateFingerprintSeed() {
-	return Date.now();
-}
-/** Detect the fingerprint platform based on the current OS. */
-function detectFingerprintPlatform() {
-	switch (platform()) {
-		case "darwin": return "macos";
-		case "win32": return "windows";
-		default: return "windows";
-	}
-}
-/**
-* Remove the `com.apple.quarantine` extended attribute from a file or app bundle on macOS.
-* Files downloaded from the internet are tagged with this attribute, causing Gatekeeper
-* to block unsigned binaries. Without this, CloakBrowser silently fails to launch.
-*
-* Non-fatal — logs and returns on any error.
-*/
-async function removeQuarantineAttr(path) {
-	if (platform() !== "darwin") return;
-	const target = findAppBundle(path) ?? path;
-	log.debug({ target }, "Removing com.apple.quarantine");
-	try {
-		const { stderr } = await execAsync(`xattr -rd com.apple.quarantine "${target}"`);
-		if (stderr?.trim()) log.debug({ stderr: stderr.trim() }, "xattr stderr (non-fatal)");
-		log.debug("Quarantine attribute removed");
-	} catch {
-		log.debug("xattr command failed or attribute not set (non-fatal)");
-	}
-}
-/** Find the .app bundle root by walking up from an executable path. */
-function findAppBundle(executablePath) {
-	const parts = executablePath.split("/");
-	for (let i = parts.length - 1; i >= 0; i--) if (parts[i].endsWith(".app")) return parts.slice(0, i + 1).join("/");
-}
-/**
-* JavaScript snippet to inject into every new page to hide automation signals.
-* Removes `navigator.webdriver` and patches other detectable properties.
-*/
-const WEBDRIVER_OVERRIDE_SCRIPT = `
-Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
-if (navigator.plugins.length === 0) {
-  Object.defineProperty(navigator, 'plugins', {
-    get: () => [1, 2, 3, 4, 5],
-  });
-}
-Object.defineProperty(navigator, 'languages', {
-  get: () => ['en-US', 'en'],
-});
-window.chrome = window.chrome || {};
-window.chrome.runtime = window.chrome.runtime || {};
-`;
-/** Ensure a binary file has executable permissions (Unix only, no-op on Windows). */
-async function makeExecutable(path) {
-	if (platform() === "win32") return;
-	try {
-		await chmod(path, (await stat(path)).mode | 73);
-	} catch (e) {
-		const msg = e instanceof Error ? e.message : String(e);
-		log.warn({
-			path,
-			errorMessage: msg
-		}, `Failed to chmod binary: ${msg}`);
-	}
-}
-//#endregion
-export { WEBDRIVER_OVERRIDE_SCRIPT, buildLocalStealthArgs, buildStealthArgs, filterCloakBrowserExtraArgs, generateFingerprintSeed, makeExecutable, removeQuarantineAttr };

package/dist/src/gateway/hono/routes/browser-workflows.d.ts

@@ -1,3 +0,0 @@
-import type { Hono } from 'hono';
-import type { AuthenticatedRouteDeps } from './deps.js';
-export declare function registerBrowserWorkflowRoutes(authenticated: Hono, deps: AuthenticatedRouteDeps): void;

package/dist/src/gateway/hono/routes/browser-workflows.js

@@ -1,78 +0,0 @@
-//#region src/gateway/hono/routes/browser-workflows.ts
-function presentWorkflow(service, recipe) {
-	const inputs = service.validate(recipe.yaml).document?.args ?? {};
-	return {
-		id: recipe.id,
-		name: recipe.name,
-		description: recipe.description,
-		enabled: recipe.status === "published",
-		risk: recipe.risk,
-		domains: recipe.domains,
-		inputs,
-		createdAtMs: recipe.createdAtMs,
-		updatedAtMs: recipe.updatedAtMs
-	};
-}
-function presentRun(run) {
-	return {
-		id: run.id,
-		workflowId: run.recipeId,
-		status: run.status,
-		inputs: run.args,
-		result: run.result,
-		error: run.error,
-		createdAtMs: run.createdAtMs,
-		startedAtMs: run.startedAtMs,
-		endedAtMs: run.endedAtMs,
-		durationMs: run.durationMs
-	};
-}
-function registerBrowserWorkflowRoutes(authenticated, deps) {
-	const service = deps.service.browserRecipes;
-	authenticated.get("/api/browser/workflows", (c) => c.json({ workflows: service.list().map((recipe) => presentWorkflow(service, recipe)) }));
-	authenticated.get("/api/browser/workflows/:id", (c) => {
-		const recipe = service.get(c.req.param("id"));
-		return recipe ? c.json({ workflow: presentWorkflow(service, recipe) }) : c.json({ error: "Browser automation not found" }, 404);
-	});
-	authenticated.patch("/api/browser/workflows/:id", deps.strictRateLimitMiddleware, async (c) => {
-		try {
-			const current = service.get(c.req.param("id"));
-			if (!current) return c.json({ error: "Browser automation not found" }, 404);
-			const body = await c.req.json().catch(() => null);
-			if (typeof body?.enabled !== "boolean") return c.json({ error: "enabled must be a boolean" }, 400);
-			const workflow = service.save({
-				yaml: current.yaml,
-				status: body.enabled ? "published" : "disabled",
-				expectedId: current.id
-			});
-			return c.json({ workflow: presentWorkflow(service, workflow) });
-		} catch (error) {
-			return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
-		}
-	});
-	authenticated.delete("/api/browser/workflows/:id", deps.strictRateLimitMiddleware, (c) => {
-		try {
-			return c.json({ removed: service.remove(c.req.param("id")) });
-		} catch (error) {
-			return c.json({ error: error instanceof Error ? error.message : String(error) }, 409);
-		}
-	});
-	authenticated.post("/api/browser/workflows/:id/run", deps.strictRateLimitMiddleware, async (c) => {
-		try {
-			const body = await c.req.json().catch(() => ({}));
-			if (body.inputs !== void 0 && (!body.inputs || typeof body.inputs !== "object" || Array.isArray(body.inputs))) return c.json({ error: "inputs must be an object" }, 400);
-			const run = service.startRun(c.req.param("id"), body.inputs ?? {});
-			return c.json({ run: presentRun(run) }, 202);
-		} catch (error) {
-			return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
-		}
-	});
-	authenticated.get("/api/browser/workflow-runs", (c) => c.json({ runs: service.listRuns(c.req.query("workflowId")).map(presentRun) }));
-	authenticated.get("/api/browser/workflow-runs/:id", (c) => {
-		const run = service.getRun(c.req.param("id"));
-		return run ? c.json({ run: presentRun(run) }) : c.json({ error: "Run not found" }, 404);
-	});
-	authenticated.post("/api/browser/workflow-runs/:id/cancel", deps.strictRateLimitMiddleware, (c) => c.json({ cancelled: service.cancel(c.req.param("id")) }));
-}
-//#endregion
-export { registerBrowserWorkflowRoutes };