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

package/dist/cli.js

@@ -75,6 +75,7 @@ async function main() {
             goal: { type: 'string', short: 'g' },
             url: { type: 'string', short: 'u' },
             cases: { type: 'string', short: 'c' },
+            'cases-json': { type: 'string' },
             'allowed-domains': { type: 'string' },
             // LLM configuration
             model: { type: 'string', short: 'm' },
@@ -146,6 +147,8 @@ async function main() {
             'user-data-dir': { type: 'string' },
             'profile-dir': { type: 'string' },
             'cdp-url': { type: 'string' },
+            attach: { type: 'boolean' },
+            'attach-port': { type: 'string' },
             wallet: { type: 'boolean' },
             'wallet-auto-approve': { type: 'boolean' },
             'wallet-password': { type: 'string' },
@@ -177,6 +180,16 @@ async function main() {
             cookie: { type: 'string', multiple: true },
             'wait-for': { type: 'string' },
             'wait-timeout': { type: 'string' },
+            // Gen 32 — `bad share` flags
+            visibility: { type: 'string' },
+            'bad-app-url': { type: 'string' },
+            'no-copy': { type: 'boolean' },
+            // Gen 32 — preview / stream / interrupt
+            'max-steps': { type: 'string' },
+            headed: { type: 'boolean' },
+            stream: { type: 'string' },
+            'stream-token': { type: 'string' },
+            interrupt: { type: 'boolean' },
             help: { type: 'boolean', short: 'h', default: false },
             version: { type: 'boolean', short: 'v', default: false },
         },
@@ -317,6 +330,16 @@ async function main() {
         });
         process.exit(0);
     }
+    if (command === 'chrome-debug') {
+        const { runChromeDebugCommand } = await import('./cli-attach.js');
+        const port = values['attach-port'] ? parseInt(values['attach-port'], 10) : undefined;
+        const rc = await runChromeDebugCommand({
+            port,
+            userDataDir: values['user-data-dir'],
+            quiet: values.quiet,
+        });
+        process.exit(rc);
+    }
     if (command === 'auth') {
         const sub = positionals[1];
         if (sub === 'save') {
@@ -351,13 +374,85 @@ async function main() {
         cliError(`Unknown auth subcommand: ${sub || '(none)'}. Use "auth save", "auth login", or "auth check".`);
         process.exit(1);
     }
-    if (command !== 'run') {
-        cliError(`Unknown command: ${command}. Use "run", "runs", "design-audit", "view", "showcase", or "auth".`);
+    // `bad attach` is a top-level alias for `bad run --attach`. Every other
+    // flag on `run` (--goal, --url, --model, --provider, --base-url,
+    // --api-key, --show-cursor, --mode, --max-turns, --timeout, --no-memory,
+    // --attach-port) works identically. Attach's mental model is "drive my
+    // real Chrome," which is distinct enough from "spawn a fresh browser"
+    // to deserve its own command name.
+    if (command === 'attach') {
+        values.attach = true;
+    }
+    // `bad preview` — plan-only dry-run. Observe the URL once, ask the
+    // planner to emit a structured plan, render it, exit. No execution.
+    // terraform plan for browser agents.
+    if (command === 'preview') {
+        if (!values.goal || !values.url) {
+            cliError('usage: bad preview --goal "..." --url <url> [--max-steps 12] [--headed] [--json] [--out plan.json]');
+            process.exit(1);
+        }
+        const { handlePreviewCommand, PreviewError } = await import('./cli-preview.js');
+        try {
+            const result = await handlePreviewCommand({
+                goal: values.goal,
+                url: values.url,
+                model: values.model,
+                provider: values.provider,
+                apiKey: values['api-key'],
+                baseUrl: values['base-url'],
+                output: values.sink,
+                json: values.json,
+                maxSteps: values['max-steps'] ? parseInt(values['max-steps'], 10) : undefined,
+                headed: values.headed,
+            });
+            process.exit(result.plan ? 0 : 1);
+        }
+        catch (err) {
+            if (err instanceof PreviewError) {
+                cliError(err.message);
+                process.exit(1);
+            }
+            throw err;
+        }
+    }
+    // `bad share <run-id>` — create a bad-app share link, copy to clipboard.
+    if (command === 'share') {
+        const runId = positionals[1];
+        if (!runId) {
+            cliError('usage: bad share <run-id> [--visibility metadata|full|artifacts] [--json]');
+            process.exit(1);
+        }
+        const { handleShareCommand, ShareError } = await import('./cli-share.js');
+        const visArg = values.visibility;
+        const visibility = visArg === 'full' || visArg === 'artifacts' || visArg === 'metadata'
+            ? visArg
+            : undefined;
+        try {
+            await handleShareCommand({
+                runId,
+                visibility,
+                baseUrl: values['bad-app-url'],
+                apiKey: values['api-key'],
+                noCopy: values['no-copy'],
+                json: values.json,
+            });
+            process.exit(0);
+        }
+        catch (err) {
+            if (err instanceof ShareError) {
+                cliError(err.message);
+                process.exit(1);
+            }
+            throw err;
+        }
+    }
+    if (command !== 'run' && command !== 'attach') {
+        cliError(`Unknown command: ${command}. Use "run", "attach", "preview", "runs", "view", "share", "chrome-debug", "design-audit", "showcase", or "auth".`);
         process.exit(1);
     }
     // Validate inputs
-    if (!values.goal && !values.cases && !values['resume-run'] && !values['fork-run']) {
-        cliError('provide --goal "..." --url "..." for a single task, --cases ./cases.json for a suite, or --resume-run / --fork-run <runId>.');
+    if (!values.goal && !values.cases && !values['cases-json'] && !values['resume-run'] && !values['fork-run']) {
+        cliError('provide --goal "..." --url "..." for a single task, --cases ./cases.json (or --cases-json \'[...]\') for a suite, or --resume-run / --fork-run <runId>.');
         process.exit(1);
     }
     // Load config file, then overlay CLI flags
@@ -531,6 +626,40 @@ async function main() {
         cliOverrides.profileDir = values['profile-dir'];
     if (values['cdp-url'])
         cliOverrides.cdpUrl = values['cdp-url'];
+    // --attach resolves to cdpUrl by probing a running Chrome's DevTools
+    // endpoint. Done here (pre-config-merge) so the existing cdpUrl path at
+    // cli.ts:916 takes over unchanged. Conflicts with wallet/extension/profile
+    // flags are surfaced up-front rather than silently ignored.
+    if (values.attach) {
+        if (values['cdp-url']) {
+            cliError('--attach and --cdp-url are mutually exclusive (both select a CDP endpoint). Use one.');
+            process.exit(1);
+        }
+        const { resolveAttachEndpoint, validateAttachConflicts } = await import('./cli-attach.js');
+        const conflicts = validateAttachConflicts({
+            walletEnabled: Boolean(cliOverrides.wallet?.enabled) || Boolean(values.extension?.length),
+            profileDir: values['profile-dir'],
+            extensionPaths: values.extension,
+            userDataDir: values['user-data-dir'],
+        });
+        if (!conflicts.ok) {
+            for (const err of conflicts.errors)
+                cliError(err);
+            process.exit(1);
+        }
+        const port = values['attach-port'] ? parseInt(values['attach-port'], 10) : undefined;
+        if (port !== undefined && !Number.isFinite(port)) {
+            cliError(`Invalid --attach-port value: ${values['attach-port']}`);
+            process.exit(1);
+        }
+        const info = await resolveAttachEndpoint({ port }).catch((err) => {
+            cliError(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        });
+        cliOverrides.cdpUrl = info.webSocketDebuggerUrl;
+        if (!values.quiet)
+            cliLog('attach', `connected to ${info.browser ?? 'Chrome'}`);
+    }
     if (values.memory !== undefined || values['memory-dir']) {
         cliOverrides.memory = {
             ...(cliOverrides.memory ?? {}),
@@ -694,9 +823,13 @@ async function main() {
     // Optional live event bus + SSE viewer. Constructed only when `--live` is
     // passed; otherwise the runner uses an internal no-op bus and pays nothing.
     // The bus is shared across the entire suite so a single SSE connection
-    // observes all turns of all test cases.
+    // observes all turns of all test cases. Gen 32: when `--stream <url>` is
+    // passed the bus is always created (even without --live) so the webhook
+    // streamer has something to subscribe to.
     const liveEnabled = values.live === true;
-    const liveBus = liveEnabled ? new TurnEventBus() : undefined;
+    const streamUrl = typeof values.stream === 'string' && values.stream.length > 0 ? values.stream : undefined;
+    const needsBus = liveEnabled || !!streamUrl;
+    const liveBus = needsBus ? new TurnEventBus() : undefined;
     const liveCancelController = liveEnabled ? new AbortController() : undefined;
     let liveViewHandle;
     if (liveEnabled && liveBus) {
@@ -708,6 +841,39 @@ async function main() {
             noOpen: values['no-open'] === true,
         });
     }
+    // Gen 32 — webhook streamer. When `--stream <url>` is passed, subscribe
+    // to the bus and POST every event to <url> as it fires. Auth via
+    // `--stream-token` or $BAD_STREAM_TOKEN. Non-fatal on failure — the
+    // canonical record is always events.jsonl on disk.
+    let webhookStreamer;
+    if (streamUrl && liveBus) {
+        const { WebhookStreamer } = await import('./runner/stream-webhook.js');
+        const token = values['stream-token'] || process.env.BAD_STREAM_TOKEN;
+        const streamId = `stream_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        webhookStreamer = new WebhookStreamer({
+            url: streamUrl,
+            authToken: token,
+            streamId,
+            onError: (err, dropped) => {
+                if (!values.json)
+                    cliWarn(`stream: ${err.message} (dropped ${dropped} event${dropped === 1 ? '' : 's'})`);
+            },
+        }).attach(liveBus);
+        if (!values.json)
+            cliLog('stream', `POST → ${streamUrl} (id ${streamId})`);
+    }
+    // Gen 32 — interrupt controller. `--interrupt` enables keyboard pause/
+    // resume/abort during a run. No-op in non-TTY (CI, piped output).
+    let interruptController;
+    let detachInterrupt;
+    if (values.interrupt === true && process.stdin.isTTY) {
+        const { InterruptController } = await import('./runner/interrupt-controller.js');
+        interruptController = new InterruptController({
+            onStatus: (msg) => { if (!values.json)
+                cliLog('interrupt', msg); },
+        });
+        detachInterrupt = interruptController.attach();
+    }
     // Auto-discover bad.config.{ts,mjs,js,...} from cwd plus any explicit
     // --extension paths. Failures are reported but never fatal: a broken user
     // config should warn, not abort the run.
@@ -717,6 +883,27 @@ async function main() {
         : explicitExtPaths
             ? [explicitExtPaths]
             : [];
+    // Domain skills: markdown-based per-host rule libraries under
+    // skills/domain/<host>/SKILL.md. They plumb into the same BadExtension
+    // pipeline as user `bad.config.mjs` files via addRulesForDomain, so the
+    // existing setExtensionRules injection at brain/index.ts:899 picks them up
+    // with no second injection site. Gated by BAD_DOMAIN_SKILLS_DISABLED=1.
+    const domainSkillsDisabled = process.env.BAD_DOMAIN_SKILLS_DISABLED === '1';
+    let domainSkillExtension;
+    let domainSkillsLoadedCount = 0;
+    if (!domainSkillsDisabled) {
+        const { loadDomainSkills, buildDomainSkillExtension } = await import('./skills/domain-loader.js');
+        const domainLoad = await loadDomainSkills();
+        if (domainLoad.skills.length > 0) {
+            domainSkillExtension = buildDomainSkillExtension(domainLoad.skills);
+            domainSkillsLoadedCount = domainLoad.skills.length;
+        }
+        if (domainLoad.errors.length > 0 && !values.json) {
+            for (const err of domainLoad.errors) {
+                cliWarn(`domain-skill load failed: ${err.path} — ${err.error}`);
+            }
+        }
+    }
     const extensionLoad = await loadExtensions({ explicitPaths: explicitExtArr });
     if (extensionLoad.loadedFrom.length > 0 && !values.json) {
         cliLog('extensions', `loaded ${extensionLoad.loadedFrom.length}: ${extensionLoad.loadedFrom.join(', ')}`);
@@ -726,6 +913,35 @@ async function main() {
             cliWarn(`extension load failed: ${err.path} — ${err.error}`);
         }
     }
+    if (domainSkillExtension && domainSkillsLoadedCount > 0) {
+        // Re-resolve the bundle with the domain-skill synthetic extension
+        // merged in. Resolving twice is cheap (the list is short) and keeps
+        // domainSkillExtension from having to plumb through a separate wire.
+        const { resolveExtensions } = await import('./extensions/types.js');
+        const combined = resolveExtensions([...extensionLoad.resolved.extensions, domainSkillExtension]);
+        extensionLoad.resolved = combined;
+        if (!values.json)
+            cliLog('skills', `domain: ${domainSkillsLoadedCount} loaded`);
+    }
+    // Gen 29: macros. Loaded alongside domain skills; gated by
+    // BAD_MACROS_DISABLED=1. The registry is passed to PlaywrightDriver
+    // (dispatch) and its promptBlock to the BrowserAgent (visibility).
+    const macrosDisabled = process.env.BAD_MACROS_DISABLED === '1';
+    let macroRegistry;
+    if (!macrosDisabled) {
+        const { loadMacros, buildMacroRegistry } = await import('./skills/macro-loader.js');
+        const macroLoad = await loadMacros();
+        if (macroLoad.errors.length > 0 && !values.json) {
+            for (const err of macroLoad.errors) {
+                cliWarn(`macro load failed: ${err.path} — ${err.error}`);
+            }
+        }
+        if (macroLoad.macros.length > 0) {
+            macroRegistry = buildMacroRegistry(macroLoad.macros);
+            if (!values.json)
+                cliLog('skills', `macros: ${macroLoad.macros.length} loaded`);
+        }
+    }
     const concurrency = launchPlan.concurrency;
     const maxTurns = driverConfig.maxTurns ?? 30;
     const screenshotInterval = driverConfig.screenshotInterval ?? 5;
@@ -807,8 +1023,8 @@ async function main() {
                 parentRunId: scenario.parentRunId,
             }];
     }
-    else if (values.cases) {
-        const raw = fs.readFileSync(path.resolve(values.cases), 'utf-8');
+    else if (values['cases-json'] || values.cases) {
+        const raw = values['cases-json'] || fs.readFileSync(path.resolve(values.cases), 'utf-8');
         const parsed = JSON.parse(raw);
         const rawCases = Array.isArray(parsed) ? parsed : [parsed];
         // Ensure required fields — spread raw case first so explicit fields become defaults
@@ -943,7 +1159,7 @@ async function main() {
         fs.mkdirSync(userDataDir, { recursive: true });
         const persistentLaunchStartedAt = Date.now();
         persistentContext = await chromium.launchPersistentContext(userDataDir, {
-            channel: 'chrome',
+            channel: isStealthProfile ? 'chrome' : 'chromium',
             headless: launchPlan.headless,
             args: launchPlan.browserArgs,
             viewport,
@@ -1088,10 +1304,11 @@ async function main() {
         browser = await browserType.launch({
             headless: launchPlan.headless,
             ...(browserName === 'chromium' ? { args: launchPlan.browserArgs } : {}),
-            // Use system Chrome for all Chromium runs — real TLS/JA3 fingerprint
-            // vs bundled Chromium. Bundled Chromium's TLS handshake is detectably
-            // different from real Chrome, causing 403s on Cloudflare/Akamai sites.
-            ...(browserName === 'chromium' ? { channel: 'chrome' } : {}),
+            // System Chrome for stealth profiles only — real TLS/JA3 fingerprint
+            // fixes anti-bot blocking. But system Chrome renders differently than
+            // bundled Chromium on some sites (Allrecipes click timeouts, Amazon
+            // layout shifts), so only enable when anti-bot evasion is needed.
+            ...(isStealthProfile && browserName === 'chromium' ? { channel: 'chrome' } : {}),
             // Residential/SOCKS5/HTTP proxy — routes all traffic through the proxy
             ...(launchPlan.proxyServer ? { proxy: { server: launchPlan.proxyServer } } : {}),
         });
@@ -1277,6 +1494,7 @@ async function main() {
             visionStrategy: config.visionStrategy,
             screenshotInterval,
             showCursor: values['show-cursor'],
+            ...(macroRegistry ? { macros: macroRegistry } : {}),
         });
         // Apply resource blocking if configured
         const resourceBlockingStartedAt = Date.now();
@@ -1333,7 +1551,11 @@ async function main() {
         screenshotInterval,
         artifactSink: sink,
         extensions: extensionLoad.resolved,
+        ...(macroRegistry ? { macroPromptBlock: macroRegistry.promptBlock } : {}),
         ...(liveBus ? { eventBus: liveBus } : {}),
+        ...(interruptController
+            ? { beforeTurn: async () => { await interruptController.waitIfPaused(); } }
+            : {}),
         onProgress: (event) => {
             if (values.json) {
                 console.log(JSON.stringify(event));
@@ -1363,7 +1585,23 @@ async function main() {
     let result;
     let runError;
     try {
-        result = await runner.runSuite(cases, liveCancelController ? { signal: liveCancelController.signal } : undefined);
+        // Gen 32 — wire interrupt controller. When the user presses `q`,
+        // abort() fires which the runner observes via the suite-level
+        // signal. Runs a check before the runner starts so pressing `q`
+        // BEFORE the first turn still aborts cleanly.
+        const interruptSignal = interruptController
+            ? (() => {
+                const ac = new AbortController();
+                interruptController.on('abort', () => ac.abort('interrupted by user'));
+                if (interruptController.isAborted)
+                    ac.abort('interrupted by user');
+                return ac.signal;
+            })()
+            : undefined;
+        // If --live already provided a signal, merge both. Prefer the user
+        // interrupt signal so `q` wins even when --live is set.
+        const mergedSignal = interruptSignal ?? liveCancelController?.signal;
+        result = await runner.runSuite(cases, mergedSignal ? { signal: mergedSignal } : undefined);
         // Write reports for each configured format
         const { generateReport } = await import('./test-report.js');
         const reporters = driverConfig.reporters ?? ['json'];
@@ -1399,6 +1637,16 @@ async function main() {
     }
     finally {
         renderer?.destroy();
+        // Gen 32 — detach interrupt controller first so stdin leaves raw mode
+        // BEFORE we try to write any shutdown logs. Otherwise the user's TTY
+        // stays in raw mode after the run ends and Ctrl-C, arrow keys, etc.
+        // come through as garbage bytes.
+        if (detachInterrupt)
+            detachInterrupt();
+        // Flush and close the stream webhook so the final events (run-completed,
+        // suite-complete) reach the endpoint before the CLI exits.
+        if (webhookStreamer)
+            await webhookStreamer.close().catch(() => { });
         await singleDriver?.close?.().catch(() => { });
         stopWalletAutoApprover?.();
         await persistentContext?.close().catch(() => { });