@tangle-network/browser-agent-driver 0.24.1 → 0.25.0

package/dist/cli-attach.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Attach mode — connect to the user's already-running Chrome via CDP.
+ *
+ * Inspired by browser-use/browser-harness. The agent drives the user's
+ * real browser instead of launching a fresh Chromium, which preserves
+ * login state, cookies, SSO — the workflows that "automate anything
+ * I'm already logged into" need.
+ *
+ * Two entrypoints:
+ *   - `bad --attach` probes 127.0.0.1:9222 (or `--attach-port`),
+ *     populates the existing cdpUrl path at cli.ts:916.
+ *   - `bad chrome-debug` launches the user's system Chrome with
+ *     `--remote-debugging-port=<port>` pointed at their default profile
+ *     so attach has something to connect to.
+ *
+ * Attach is fundamentally incompatible with wallet mode and extension
+ * loading — both require launchPersistentContext. Those combinations
+ * error out with a clear message rather than silently ignoring flags.
+ */
+import { spawn } from 'node:child_process';
+export declare const DEFAULT_ATTACH_PORT = 9222;
+export interface ChromeDebugInfo {
+    /** WebSocket URL for CDP (passable to playwright.chromium.connectOverCDP) */
+    webSocketDebuggerUrl: string;
+    /** Human-readable browser label (e.g. "Chrome/131.0.6778.86") */
+    browser?: string;
+    /** Raw probe payload for diagnostics */
+    raw: unknown;
+}
+export interface ProbeOptions {
+    host?: string;
+    port?: number;
+    /** Abort probe after this many ms. Default 1500. */
+    timeoutMs?: number;
+    /** Injected fetch for tests */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Probe the Chrome DevTools JSON endpoint at host:port/json/version.
+ * Returns connection info if Chrome is listening, null if the probe
+ * fails (no listener, non-JSON body, missing field, timeout).
+ *
+ * Never throws — attach UX hinges on a probe that reports "not running"
+ * rather than crashing when the user hasn't started Chrome yet.
+ */
+export declare function probeChromeDebug(opts?: ProbeOptions): Promise<ChromeDebugInfo | null>;
+export interface ResolveAttachOptions {
+    /** Host (default 127.0.0.1) */
+    host?: string;
+    /** Port (default 9222). */
+    port?: number;
+    /** Max probe attempts; ms between attempts comes from `retryDelayMs`. */
+    attempts?: number;
+    retryDelayMs?: number;
+    /** Injected for tests */
+    probeImpl?: (o: ProbeOptions) => Promise<ChromeDebugInfo | null>;
+    /** Injected for tests */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/**
+ * Probe up to `attempts` times with `retryDelayMs` between tries.
+ * Returns the resolved info or throws a user-facing error explaining
+ * how to start Chrome with debugging enabled.
+ */
+export declare function resolveAttachEndpoint(opts?: ResolveAttachOptions): Promise<ChromeDebugInfo>;
+/** Find the user's system Chrome binary. Returns null if none found. */
+export declare function findChromeBinary(platform?: NodeJS.Platform): string | null;
+/**
+ * Return the user's default Chrome profile directory for this platform,
+ * or null if we can't locate it. Used by `chrome-debug` to launch against
+ * the real profile (so login state is preserved).
+ */
+export declare function findChromeUserDataDir(platform?: NodeJS.Platform, homeDir?: string): string | null;
+export interface ChromeDebugOptions {
+    port?: number;
+    /** Override the user-data-dir. Default: the system profile. */
+    userDataDir?: string;
+    /** Override Chrome binary path. Default: auto-detected. */
+    binary?: string;
+    /** Injected for tests */
+    spawnImpl?: typeof spawn;
+    /** Injected for tests */
+    probeImpl?: (o: ProbeOptions) => Promise<ChromeDebugInfo | null>;
+    /** Injected for tests */
+    platform?: NodeJS.Platform;
+    /** Injected for tests */
+    homeDir?: string;
+    /** Total wait time for the port to open before giving up. Default 10s. */
+    readyTimeoutMs?: number;
+}
+/**
+ * Launch the user's system Chrome with `--remote-debugging-port=<port>`
+ * against their default profile. Waits up to readyTimeoutMs for the
+ * port to respond, then returns the probe info.
+ *
+ * This is intentionally ergonomic over "correct for all edge cases" —
+ * advanced users with non-default Chrome installs or custom profiles
+ * should still use `--cdp-url` directly. This handles the 90% case.
+ */
+export declare function handleChromeDebug(opts?: ChromeDebugOptions): Promise<ChromeDebugInfo>;
+/**
+ * CLI subcommand entrypoint. Wraps handleChromeDebug with help-text
+ * output. Exits with the probe info printed so the user (or a shell
+ * script) can copy the WS URL.
+ */
+export declare function runChromeDebugCommand(opts: {
+    port?: number;
+    userDataDir?: string;
+    quiet?: boolean;
+}): Promise<number>;
+/**
+ * Assert-helper used by the main run path. Hard-errors when a caller
+ * passed flags that attach mode cannot honor — no silent fallback, no
+ * "warn and do the wrong thing." If the user said --profile-dir AND
+ * --attach, they meant something, and we shouldn't guess.
+ */
+export declare function validateAttachConflicts(opts: {
+    walletEnabled: boolean;
+    profileDir?: string;
+    extensionPaths?: string[];
+    userDataDir?: string;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    errors: string[];
+};
+//# sourceMappingURL=cli-attach.d.ts.map

package/dist/cli-attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-attach.d.ts","sourceRoot":"","sources":["../src/cli-attach.ts"],"names":[],"mappings":"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"}

package/dist/cli-attach.js

@@ -0,0 +1,254 @@
+/**
+ * Attach mode — connect to the user's already-running Chrome via CDP.
+ *
+ * Inspired by browser-use/browser-harness. The agent drives the user's
+ * real browser instead of launching a fresh Chromium, which preserves
+ * login state, cookies, SSO — the workflows that "automate anything
+ * I'm already logged into" need.
+ *
+ * Two entrypoints:
+ *   - `bad --attach` probes 127.0.0.1:9222 (or `--attach-port`),
+ *     populates the existing cdpUrl path at cli.ts:916.
+ *   - `bad chrome-debug` launches the user's system Chrome with
+ *     `--remote-debugging-port=<port>` pointed at their default profile
+ *     so attach has something to connect to.
+ *
+ * Attach is fundamentally incompatible with wallet mode and extension
+ * loading — both require launchPersistentContext. Those combinations
+ * error out with a clear message rather than silently ignoring flags.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import chalk from 'chalk';
+import { cliError, cliLog } from './cli-ui.js';
+export const DEFAULT_ATTACH_PORT = 9222;
+/**
+ * Probe the Chrome DevTools JSON endpoint at host:port/json/version.
+ * Returns connection info if Chrome is listening, null if the probe
+ * fails (no listener, non-JSON body, missing field, timeout).
+ *
+ * Never throws — attach UX hinges on a probe that reports "not running"
+ * rather than crashing when the user hasn't started Chrome yet.
+ */
+export async function probeChromeDebug(opts = {}) {
+    const host = opts.host ?? '127.0.0.1';
+    const port = opts.port ?? DEFAULT_ATTACH_PORT;
+    const timeoutMs = opts.timeoutMs ?? 1500;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const url = `http://${host}:${port}/json/version`;
+    // Single AbortController spans the whole request: connect + headers +
+    // body read. Per the fetch spec, aborting mid-stream propagates into
+    // body.text()/json(), so a server that sends headers then stalls the
+    // body gets cut off at the same timeout as a dead-port connection.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, { signal: controller.signal });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        const ws = body?.webSocketDebuggerUrl;
+        if (typeof ws !== 'string' || ws.length === 0)
+            return null;
+        const browserLabel = typeof body?.Browser === 'string' ? body.Browser : undefined;
+        return { webSocketDebuggerUrl: ws, browser: browserLabel, raw: body };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Probe up to `attempts` times with `retryDelayMs` between tries.
+ * Returns the resolved info or throws a user-facing error explaining
+ * how to start Chrome with debugging enabled.
+ */
+export async function resolveAttachEndpoint(opts = {}) {
+    const host = opts.host ?? '127.0.0.1';
+    const port = opts.port ?? DEFAULT_ATTACH_PORT;
+    const attempts = Math.max(1, opts.attempts ?? 1);
+    const delay = Math.max(0, opts.retryDelayMs ?? 500);
+    const probe = opts.probeImpl ?? probeChromeDebug;
+    const sleep = opts.sleepImpl ?? ((ms) => new Promise(res => setTimeout(res, ms)));
+    for (let i = 0; i < attempts; i++) {
+        const info = await probe({ host, port });
+        if (info)
+            return info;
+        if (i < attempts - 1)
+            await sleep(delay);
+    }
+    throw new Error(`No Chrome DevTools listener on ${host}:${port}. ` +
+        `Start your Chrome with remote debugging first:\n` +
+        `    bad chrome-debug\n` +
+        `…or pass --cdp-url <ws://...> to target a different endpoint.`);
+}
+/** Find the user's system Chrome binary. Returns null if none found. */
+export function findChromeBinary(platform = process.platform) {
+    const candidates = [];
+    if (platform === 'darwin') {
+        candidates.push('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta', '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary', '/Applications/Chromium.app/Contents/MacOS/Chromium');
+    }
+    else if (platform === 'linux') {
+        candidates.push('/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium');
+    }
+    else if (platform === 'win32') {
+        candidates.push('C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe');
+    }
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Return the user's default Chrome profile directory for this platform,
+ * or null if we can't locate it. Used by `chrome-debug` to launch against
+ * the real profile (so login state is preserved).
+ */
+export function findChromeUserDataDir(platform = process.platform, homeDir = os.homedir()) {
+    let candidate = null;
+    if (platform === 'darwin') {
+        candidate = path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome');
+    }
+    else if (platform === 'linux') {
+        candidate = path.join(homeDir, '.config', 'google-chrome');
+    }
+    else if (platform === 'win32') {
+        candidate = path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome', 'User Data');
+    }
+    if (candidate && fs.existsSync(candidate))
+        return candidate;
+    return null;
+}
+/**
+ * Launch the user's system Chrome with `--remote-debugging-port=<port>`
+ * against their default profile. Waits up to readyTimeoutMs for the
+ * port to respond, then returns the probe info.
+ *
+ * This is intentionally ergonomic over "correct for all edge cases" —
+ * advanced users with non-default Chrome installs or custom profiles
+ * should still use `--cdp-url` directly. This handles the 90% case.
+ */
+export async function handleChromeDebug(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const homeDir = opts.homeDir ?? os.homedir();
+    const port = opts.port ?? DEFAULT_ATTACH_PORT;
+    const probe = opts.probeImpl ?? probeChromeDebug;
+    const spawnFn = opts.spawnImpl ?? spawn;
+    // If Chrome is already listening on the port, just return it.
+    const existing = await probe({ port });
+    if (existing) {
+        cliLog('attach', `Chrome already listening on :${port} (${existing.browser ?? 'unknown'})`);
+        return existing;
+    }
+    const binary = opts.binary ?? findChromeBinary(platform);
+    if (!binary) {
+        throw new Error(`Could not locate a system Chrome binary on ${platform}. ` +
+            `Install Chrome, or start it manually with --remote-debugging-port=${port} and pass --cdp-url.`);
+    }
+    const userDataDir = opts.userDataDir ?? findChromeUserDataDir(platform, homeDir) ?? undefined;
+    const args = [
+        `--remote-debugging-port=${port}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+    ];
+    if (userDataDir)
+        args.push(`--user-data-dir=${userDataDir}`);
+    cliLog('attach', `launching ${binary}`);
+    if (userDataDir)
+        cliLog('attach', `using profile ${userDataDir}`);
+    const child = spawnFn(binary, args, {
+        detached: true,
+        stdio: 'ignore',
+    });
+    // Capture early exit so the thrown error at deadline can name the exit
+    // code instead of generically saying "timed out". `detached:true` means
+    // we deliberately don't block on the child, but we still want to know if
+    // it died before our probe succeeded.
+    let childExitCode = null;
+    let childExitSignal = null;
+    child.on?.('exit', (code, signal) => {
+        childExitCode = code;
+        childExitSignal = signal;
+    });
+    child.unref?.();
+    const deadline = Date.now() + (opts.readyTimeoutMs ?? 10_000);
+    while (Date.now() < deadline) {
+        if (childExitCode !== null || childExitSignal !== null) {
+            throw new Error(`Chrome exited before the DevTools endpoint came up ` +
+                `(code=${childExitCode ?? 'null'} signal=${childExitSignal ?? 'null'}). ` +
+                `Another Chrome instance may be holding the profile lock — quit it and retry.`);
+        }
+        const info = await probe({ port });
+        if (info) {
+            cliLog('attach', `connected (${info.browser ?? 'chrome'})`);
+            return info;
+        }
+        await new Promise(res => setTimeout(res, 250));
+    }
+    // Deadline hit without a successful probe. Kill the child we spawned so
+    // the user doesn't accumulate zombie Chrome processes on repeated tries.
+    if (child.pid && !child.killed) {
+        try {
+            child.kill('SIGTERM');
+        }
+        catch { /* best-effort */ }
+    }
+    throw new Error(`Chrome launched but the DevTools endpoint didn't come up within ${opts.readyTimeoutMs ?? 10_000}ms. ` +
+        `Try starting Chrome manually:\n    "${binary}" --remote-debugging-port=${port}`);
+}
+/**
+ * CLI subcommand entrypoint. Wraps handleChromeDebug with help-text
+ * output. Exits with the probe info printed so the user (or a shell
+ * script) can copy the WS URL.
+ */
+export async function runChromeDebugCommand(opts) {
+    try {
+        const info = await handleChromeDebug({
+            port: opts.port,
+            userDataDir: opts.userDataDir,
+        });
+        if (!opts.quiet) {
+            console.log('');
+            console.log(`  ${chalk.green('✓')} Chrome debugging: ${info.webSocketDebuggerUrl}`);
+            console.log(`  ${chalk.dim('run:')} bad --attach ${opts.port && opts.port !== DEFAULT_ATTACH_PORT ? `--attach-port ${opts.port} ` : ''}--goal "..."`);
+            console.log('');
+        }
+        return 0;
+    }
+    catch (err) {
+        cliError(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+}
+/**
+ * Assert-helper used by the main run path. Hard-errors when a caller
+ * passed flags that attach mode cannot honor — no silent fallback, no
+ * "warn and do the wrong thing." If the user said --profile-dir AND
+ * --attach, they meant something, and we shouldn't guess.
+ */
+export function validateAttachConflicts(opts) {
+    const errors = [];
+    if (opts.walletEnabled) {
+        errors.push('Attach mode connects to your real Chrome and cannot load the wallet extension. ' +
+            'Use `bad --wallet` (without --attach) for wallet flows.');
+    }
+    if (opts.extensionPaths && opts.extensionPaths.length > 0) {
+        errors.push('Attach mode cannot load extensions (they must be installed in the running Chrome already). ' +
+            'Drop --extension, or use `bad --wallet` for wallet extensions.');
+    }
+    if (opts.profileDir) {
+        errors.push('--profile-dir is incompatible with --attach. ' +
+            'The attached Chrome uses its own profile — drop --profile-dir or run without --attach.');
+    }
+    if (opts.userDataDir) {
+        errors.push('--user-data-dir is incompatible with --attach. ' +
+            'The attached Chrome uses its own data dir — drop --user-data-dir or run without --attach.');
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true };
+}
+//# sourceMappingURL=cli-attach.js.map

package/dist/cli-attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-attach.js","sourceRoot":"","sources":["../src/cli-attach.ts"],"names":[],"mappings":"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"}

package/dist/cli-preview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `bad preview` — plan-only mode, no execution.
+ *
+ * `terraform plan` for browser agents. Given a goal + URL, launch a
+ * browser, observe the page once, ask the Brain's planner to emit a
+ * full structured plan, render it as a dry-run tree, then EXIT without
+ * executing a single action.
+ *
+ * Use cases:
+ *   - Regulated workflows where BSA / compliance needs to review the
+ *     agent's intent before execution
+ *   - Pre-flight for expensive long runs ("will this agent do the
+ *     right thing? let me see the plan first")
+ *   - Debugging — which approach is the agent taking?
+ *
+ * Library-friendly: throws `PreviewError`; CLI dispatcher catches.
+ *
+ * Implementation: reuses BrowserAgent.brain.plan() — the planner is
+ * already a first-class concept in the runner. We just never hand the
+ * plan to the executor.
+ */
+import type { Plan } from './types.js';
+export declare class PreviewError extends Error {
+    constructor(message: string);
+}
+export interface PreviewOptions {
+    goal: string;
+    url: string;
+    model?: string;
+    provider?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    /** Write the plan as JSON to this path in addition to printing it. */
+    output?: string;
+    /** Emit JSON on stdout (pipe-friendly). */
+    json?: boolean;
+    /** Cap on plan steps. Default 12. */
+    maxSteps?: number;
+    /** Headed browser (default: headless). Useful when you want to see the page the plan is built against. */
+    headed?: boolean;
+}
+export interface PreviewResult {
+    goal: string;
+    url: string;
+    plan: Plan | null;
+    raw: string;
+    parseError?: string;
+    tokensUsed?: number;
+    durationMs: number;
+}
+/**
+ * Run the planner against a single observation of the URL. Never
+ * executes an action. Returns the structured plan + raw model output.
+ */
+export declare function runPreview(opts: PreviewOptions): Promise<PreviewResult>;
+/** Print a plan as a tree to stdout (human-readable). */
+export declare function renderPreview(result: PreviewResult): void;
+export declare function handlePreviewCommand(opts: PreviewOptions): Promise<PreviewResult>;
+//# sourceMappingURL=cli-preview.d.ts.map

package/dist/cli-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-preview.d.ts","sourceRoot":"","sources":["../src/cli-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2CAA2C;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0GAA0G;IAC1G,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAyC7E;AAED,yDAAyD;AACzD,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAkDzD;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAWvF"}

package/dist/cli-preview.js

@@ -0,0 +1,144 @@
+/**
+ * `bad preview` — plan-only mode, no execution.
+ *
+ * `terraform plan` for browser agents. Given a goal + URL, launch a
+ * browser, observe the page once, ask the Brain's planner to emit a
+ * full structured plan, render it as a dry-run tree, then EXIT without
+ * executing a single action.
+ *
+ * Use cases:
+ *   - Regulated workflows where BSA / compliance needs to review the
+ *     agent's intent before execution
+ *   - Pre-flight for expensive long runs ("will this agent do the
+ *     right thing? let me see the plan first")
+ *   - Debugging — which approach is the agent taking?
+ *
+ * Library-friendly: throws `PreviewError`; CLI dispatcher catches.
+ *
+ * Implementation: reuses BrowserAgent.brain.plan() — the planner is
+ * already a first-class concept in the runner. We just never hand the
+ * plan to the executor.
+ */
+import * as fs from 'node:fs';
+import chalk from 'chalk';
+export class PreviewError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PreviewError';
+    }
+}
+/**
+ * Run the planner against a single observation of the URL. Never
+ * executes an action. Returns the structured plan + raw model output.
+ */
+export async function runPreview(opts) {
+    if (!opts.goal)
+        throw new PreviewError('preview requires --goal "..."');
+    if (!opts.url)
+        throw new PreviewError('preview requires --url "..."');
+    // Lazy-load the heavy surface — browser, brain, driver. Keeps
+    // `bad --help` snappy for users who never run preview.
+    const { chromium } = await import('playwright');
+    const { Brain } = await import('./brain/index.js');
+    const { PlaywrightDriver } = await import('./drivers/playwright.js');
+    const startedAt = Date.now();
+    const browser = await chromium.launch({ headless: !opts.headed });
+    let result;
+    try {
+        const ctx = await browser.newContext();
+        const page = await ctx.newPage();
+        await page.goto(opts.url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+        const driver = new PlaywrightDriver(page, { captureScreenshots: false });
+        const state = await driver.observe();
+        const brain = new Brain({
+            provider: opts.provider ?? undefined,
+            model: opts.model,
+            apiKey: opts.apiKey,
+            baseUrl: opts.baseUrl,
+        });
+        const planResult = await brain.plan(opts.goal, state, { maxSteps: opts.maxSteps ?? 12 });
+        result = {
+            goal: opts.goal,
+            url: opts.url,
+            plan: planResult.plan,
+            raw: planResult.raw,
+            parseError: planResult.parseError,
+            tokensUsed: planResult.tokensUsed,
+            durationMs: Date.now() - startedAt,
+        };
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    return result;
+}
+/** Print a plan as a tree to stdout (human-readable). */
+export function renderPreview(result) {
+    const G = chalk.green;
+    const D = chalk.dim;
+    const C = chalk.cyan;
+    const Y = chalk.yellow;
+    const R = chalk.red;
+    console.log('');
+    console.log(`  ${chalk.bold('Goal:')} ${result.goal}`);
+    console.log(`  ${chalk.bold('URL:')}  ${result.url}`);
+    console.log(`  ${D(`planned in ${result.durationMs}ms${result.tokensUsed ? ` · ${result.tokensUsed} tokens` : ''}`)}`);
+    console.log('');
+    if (!result.plan) {
+        console.log(`  ${R('✗ No structured plan returned.')}`);
+        if (result.parseError)
+            console.log(`  ${D('parse error:')} ${result.parseError}`);
+        console.log('');
+        console.log(`  ${D('Raw model output:')}`);
+        console.log(indent(result.raw, '    '));
+        return;
+    }
+    const plan = result.plan;
+    const n = plan.steps.length;
+    console.log(`  ${G(`✓ Plan: ${n} step${n === 1 ? '' : 's'}`)}`);
+    if (plan.reasoning)
+        console.log(`  ${D('strategy:')} ${plan.reasoning}`);
+    console.log('');
+    for (let i = 0; i < plan.steps.length; i++) {
+        const s = plan.steps[i];
+        const action = s.action;
+        const verb = action.action;
+        const target = (() => {
+            switch (verb) {
+                case 'click': return action.selector;
+                case 'type': return `${action.selector} ← ${C(`"${action.text}"`)}`;
+                case 'press': return `${action.selector} ← ${Y(action.key)}`;
+                case 'navigate': return action.url;
+                default: return '';
+            }
+        })();
+        const num = String(i + 1).padStart(String(n).length, ' ');
+        console.log(`  ${D(num + '.')} ${C(verb)}${target ? '  ' + target : ''}`);
+        if (s.rationale)
+            console.log(`       ${D(s.rationale)}`);
+        if (s.expectedEffect)
+            console.log(`       ${D('→ verify:')} ${s.expectedEffect}`);
+    }
+    if (plan.finalResult) {
+        console.log('');
+        console.log(`  ${G('complete:')} ${plan.finalResult}`);
+    }
+    console.log('');
+}
+export async function handlePreviewCommand(opts) {
+    const result = await runPreview(opts);
+    if (opts.output) {
+        fs.writeFileSync(opts.output, JSON.stringify(result, null, 2));
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        renderPreview(result);
+    }
+    return result;
+}
+function indent(text, prefix) {
+    return text.split('\n').map((l) => prefix + l).join('\n');
+}
+//# sourceMappingURL=cli-preview.js.map

package/dist/cli-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-preview.js","sourceRoot":"","sources":["../src/cli-preview.ts"],"names":[],"mappings":"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"}