@thinkrun/cli 0.1.27

package/dist/src/commands/actions.js

@@ -0,0 +1,2207 @@
+/**
+ * Browser action commands
+ * Includes: navigate, click, type, scroll, wait, hover, select, screenshot, extract, evaluate,
+ *           back, forward, press, fill, snapshot, wait-for-text, dialog, console, network
+ */
+import { Command, Option } from 'commander';
+import chalk from 'chalk';
+import { writeFileSync, copyFileSync, unlinkSync } from 'fs';
+import { getAdapter, getResolutionInfo } from '../adapters/index.js';
+import { ApiError } from '../errors.js';
+import { handleError, readBridgePort, BRIDGE_HEALTH_PROBE_TIMEOUT_MS, BRIDGE_REQUEST_TIMEOUT_MS } from '../utils.js';
+import { isJsonMode } from '../output/mode.js';
+import { emitJson, createSpinner } from '../output/formatter.js';
+import { clearLocalSessionContext, getCloudSessionContext, getLocalSessionContext, setLocalSessionContext, } from '../session/context.js';
+import { isBlockedOutcome } from '../protected-flow/types.js';
+import { setWorkingLocation, releaseWorkingLocation, getLockedBy } from '../working-location.js';
+import { initCliSession, closeCliSession } from '../session/cli-session-sync.js';
+import { resolveAgentId } from '../session/agent-identity.js';
+import { clampEvaluateTimeoutMs } from './evaluate-helpers.js';
+import { getNativeCodeHint } from '../adapters/local.js';
+function withModeOption(command) {
+    return command.addOption(new Option('--mode <mode>', 'Execution mode override: local|cloud').choices(['local', 'cloud']));
+}
+/** Add --tab option for tab-scoped commands (bypasses working-location.json). */
+function withTabOption(command) {
+    return command.addOption(new Option('-t, --tab <tabId>', 'Target a specific Chromium-based browser tab (bypasses working location)'));
+}
+/** Add both --mode and --tab options. */
+function withActionOptions(command) {
+    return withTabOption(withModeOption(command));
+}
+/** Validate tab ID is a positive integer. Returns the normalized numeric string. */
+function validateTabId(value, source) {
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed) || parsed <= 0 || String(parsed) !== value.trim()) {
+        throw new Error(`Invalid tab ID "${value}" from ${source}. Must be a positive integer. Run: thinkrun tabs`);
+    }
+    return String(parsed);
+}
+/** Resolve tab override from --tab flag or THINKRUN_TAB_ID env var. */
+function resolveTabOverride(options) {
+    let tabId;
+    if (options?.tab) {
+        tabId = validateTabId(options.tab, '--tab flag');
+    }
+    else {
+        const envTab = process.env.THINKRUN_TAB_ID;
+        if (envTab) {
+            try {
+                tabId = validateTabId(envTab, 'THINKRUN_TAB_ID env var');
+            }
+            catch {
+                process.stderr.write(`[thinkrun] Warning: THINKRUN_TAB_ID="${envTab}" is not a valid tab ID, ignoring\n`);
+            }
+        }
+    }
+    // Lock safety check: if tab is owned by a different live agent, block
+    if (tabId) {
+        const lock = getLockedBy(parseInt(tabId, 10));
+        if (lock) {
+            const currentAgentId = resolveAgentId();
+            const isSameAgent = lock.agentId && lock.agentId === currentAgentId;
+            const isSamePid = lock.pid === process.pid;
+            if (!isSameAgent && !isSamePid) {
+                const ownerPid = lock.ownerShellPid ?? lock.pid;
+                let ownerAlive = false;
+                try {
+                    process.kill(ownerPid, 0);
+                    ownerAlive = true;
+                }
+                catch (e) {
+                    if (e.code === 'EPERM')
+                        ownerAlive = true; // alive but no permission
+                    // ESRCH = dead process, stale lock — proceed
+                }
+                if (ownerAlive) {
+                    const ownerLabel = lock.agentId ? `agent ${lock.agentId}` : `PID ${ownerPid}`;
+                    throw new Error(`Tab ${tabId} is owned by ${ownerLabel} (PID ${ownerPid}). ` +
+                        `Use 'thinkrun attach ${tabId}' to take ownership, or wait for the other agent to release.`);
+                }
+            }
+        }
+    }
+    return tabId;
+}
+async function getCommandAdapter(options) {
+    return getAdapter(options?.mode, resolveTabOverride(options));
+}
+/** Handle blocked-outcome from click/type/fill: emit JSON or TTY message and exit(1). No-op if result is success or not a blocked outcome. */
+function handleBlockedResult(result, command, startMs, spinner) {
+    if (result.success || !result.data || !isBlockedOutcome(result.data))
+        return;
+    const data = result.data;
+    if (isJsonMode()) {
+        emitJson({ success: false, command, durationMs: Date.now() - startMs, blocked: true, data });
+        process.exit(1);
+    }
+    spinner.fail(data.message);
+    if (data.handoffRequired) {
+        console.log(chalk.yellow('  Human input required. Complete the step manually, then resume.'));
+    }
+    process.exit(1);
+}
+/** For JSON output: include resolved mode and source when available. */
+async function getModeMetadataForJson(preferredMode) {
+    const r = await getResolutionInfo(preferredMode);
+    return r.resolvedMode ? { mode: r.resolvedMode, modeSource: r.modeSource } : {};
+}
+async function unregisterLocalAgentSession(port, sessionId) {
+    if (!sessionId)
+        return;
+    const res = await fetch(`http://127.0.0.1:${port}/sessions/unregister`, {
+        method: 'DELETE',
+        headers: { 'x-session-id': sessionId },
+        signal: AbortSignal.timeout(3000),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Unregister local session failed: ${res.status} ${body || res.statusText}`);
+    }
+}
+function printLocalSessionReceipt(args) {
+    const { tabId, group, windowId, controlSessionId, refreshed } = args;
+    const controllerId = summarizeControllerId(resolveAgentId());
+    const controlSummary = summarizeControlSessionLabel(controlSessionId);
+    console.log(chalk.gray(`Session receipt: tab ${tabId}`
+        + (windowId !== undefined ? ` (window ${windowId})` : '')
+        + (refreshed ? ' [refreshed]' : '')));
+    console.log(chalk.gray(`Control lease: ${controlSummary}`));
+    console.log(chalk.gray(`Ownership: controller ${controllerId} holds local mutating control for tab ${tabId}.`
+        + ' Cross-agent takeover is not supported in v1; use new-window for isolated work.'));
+    console.log(chalk.gray('If local context drifts later, run: thinkrun session debug --json'));
+    if (group)
+        console.log(chalk.gray(`Group: ${group}`));
+}
+function summarizeControllerId(controllerId) {
+    if (!controllerId)
+        return 'unknown';
+    const compact = controllerId.replace(/[^a-zA-Z0-9]/g, '');
+    if (compact.length === 0)
+        return 'unknown';
+    if (compact.length <= 6)
+        return '<redacted>';
+    return compact.slice(-6);
+}
+function summarizeControlSessionLabel(controlSessionId) {
+    if (!controlSessionId)
+        return 'unavailable';
+    const compact = controlSessionId.replace(/[^a-zA-Z0-9]/g, '');
+    if (compact.length === 0)
+        return 'unavailable';
+    if (compact.length <= 6)
+        return 'lease-<redacted>';
+    return `lease-${compact.slice(-6)}`;
+}
+// Navigate
+export function createNavigateCommand() {
+    return withActionOptions(new Command('navigate'))
+        .argument('<url>', 'URL to navigate to')
+        .option('--wait-until <condition>', 'Wait condition: load|domcontentloaded|networkidle', 'load')
+        .option('--timeout <ms>', 'Navigation timeout in milliseconds', '30000')
+        .option('--wait-for <selector>', 'Wait for selector after navigation')
+        .description('Navigate to a URL')
+        .action(async (url, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Navigating to ${url}...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            // Prepend https:// if no protocol
+            if (!url.startsWith('http://') && !url.startsWith('https://')) {
+                url = 'https://' + url;
+            }
+            // Strip trailing slashes to prevent double-slash routes (e.g. //navigate)
+            url = url.replace(/\/+$/, '');
+            const result = await adapter.navigate(url, {
+                waitUntil: options.waitUntil,
+                timeout: parseInt(options.timeout),
+                waitFor: options.waitFor,
+            });
+            if (isJsonMode()) {
+                const modeMeta = await getModeMetadataForJson(options?.mode);
+                emitJson({ success: true, command: 'navigate', durationMs: Date.now() - startMs,
+                    data: { url: result.data?.url || url, title: result.data?.title }, ...modeMeta });
+                return;
+            }
+            spinner.succeed('Navigation complete');
+            if (result.data?.title) {
+                console.log('  Title:', chalk.cyan(result.data.title));
+            }
+            console.log('  URL:  ', chalk.cyan(result.data?.url || url));
+        }
+        catch (error) {
+            spinner.fail('Navigation failed');
+            handleError(error, 'navigate', startMs);
+        }
+    });
+}
+// Click
+export function createClickCommand() {
+    return withActionOptions(new Command('click'))
+        .argument('<selector>', 'CSS selector of element to click')
+        .option('--button <type>', 'Mouse button: left|right|middle', 'left')
+        .option('--count <n>', 'Click count (for double-click)', '1')
+        .option('--delay <ms>', 'Delay between mouse down and up', '0')
+        .option('--timeout <ms>', 'Timeout waiting for selector', '15000')
+        .description('Click an element')
+        .action(async (selector, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Clicking ${selector}...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.click(selector, {
+                button: options.button,
+                count: parseInt(options.count),
+                delay: parseInt(options.delay),
+                timeout: parseInt(options.timeout),
+            });
+            handleBlockedResult(result, 'click', startMs, spinner);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'click', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed(`Clicked ${selector}`);
+        }
+        catch (error) {
+            spinner.fail('Click failed');
+            handleError(error, 'click', startMs);
+        }
+    });
+}
+// Type
+export function createTypeCommand() {
+    return withActionOptions(new Command('type'))
+        .argument('<selector>', 'CSS selector of input element')
+        .argument('<text>', 'Text to type')
+        .option('--delay <ms>', 'Delay between keystrokes', '0')
+        .option('--clear', 'Clear field before typing')
+        .option('--mask', 'Mask text in output (for passwords)')
+        .description('Type text into an element')
+        .action(async (selector, text, options) => {
+        const startMs = Date.now();
+        const displayText = options.mask ? '***' : text;
+        const spinner = createSpinner(`Typing into ${selector}...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.type(selector, text, {
+                delay: parseInt(options.delay),
+                clear: options.clear,
+                mask: options.mask,
+            });
+            handleBlockedResult(result, 'type', startMs, spinner);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'type', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed(`Typed "${displayText}" into ${selector}`);
+        }
+        catch (error) {
+            spinner.fail('Type failed');
+            handleError(error, 'type', startMs);
+        }
+    });
+}
+// Fill (clears field first, then sets value)
+export function createFillCommand() {
+    return withActionOptions(new Command('fill'))
+        .argument('<selector>', 'CSS selector of input element')
+        .argument('<value>', 'Value to fill')
+        .description('Fill a form field (clears existing value first)')
+        .action(async (selector, value, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Filling ${selector}...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.fill(selector, value);
+            handleBlockedResult(result, 'fill', startMs, spinner);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'fill', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed(`Filled ${selector}`);
+        }
+        catch (error) {
+            spinner.fail('Fill failed');
+            handleError(error, 'fill', startMs);
+        }
+    });
+}
+// Scroll
+export function createScrollCommand() {
+    return withActionOptions(new Command('scroll'))
+        .option('--down <px>', 'Scroll down by pixels')
+        .option('--up <px>', 'Scroll up by pixels')
+        .option('--to <selector>', 'Scroll element into view')
+        .option('--direction <dir>', 'Scroll direction: up or down (use with --amount)')
+        .option('--amount <px>', 'Pixels to scroll when using --direction (default: 500)')
+        .description('Scroll the page')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Scrolling...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            let scrollOptions = {};
+            if (options.to) {
+                scrollOptions.selector = options.to;
+            }
+            else if (options.direction) {
+                if (options.direction !== 'up' && options.direction !== 'down') {
+                    spinner.fail('--direction must be "up" or "down"');
+                    process.exit(1);
+                }
+                const px = parseStrictIntPixels(String(options.amount ?? '500'));
+                if (px === null || px <= 0) {
+                    spinner.fail('--amount must be a positive integer (pixels)');
+                    process.exit(1);
+                }
+                scrollOptions.y = options.direction === 'up' ? -px : px;
+            }
+            else if (options.down) {
+                const n = parseStrictIntPixels(String(options.down));
+                if (n === null || n <= 0) {
+                    spinner.fail('--down must be a positive integer (pixels)');
+                    process.exit(1);
+                }
+                scrollOptions.y = n;
+            }
+            else if (options.up) {
+                const n = parseStrictIntPixels(String(options.up));
+                if (n === null || n <= 0) {
+                    spinner.fail('--up must be a positive integer (pixels)');
+                    process.exit(1);
+                }
+                scrollOptions.y = -n;
+            }
+            else {
+                spinner.fail('Specify --down <px>, --up <px>, --direction <up|down> [--amount <px>], or --to <selector>');
+                process.exit(1);
+            }
+            await scrollWithRetryAndFallback(adapter, scrollOptions);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'scroll', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed('Scrolled');
+        }
+        catch (error) {
+            spinner.fail('Scroll failed');
+            handleError(error, 'scroll', startMs);
+        }
+    });
+}
+// Wait
+export function createWaitCommand() {
+    return withActionOptions(new Command('wait'))
+        .argument('<condition>', 'Selector to wait for, or milliseconds to wait')
+        .option('--visible', 'Wait for element to be visible')
+        .option('--hidden', 'Wait for element to be hidden')
+        .option('--timeout <ms>', 'Timeout in milliseconds', '30000')
+        .description('Wait for element or time')
+        .action(async (condition, options) => {
+        const startMs = Date.now();
+        try {
+            const adapter = await getCommandAdapter(options);
+            // Check if condition is a number (milliseconds)
+            const ms = parseInt(condition);
+            if (!isNaN(ms)) {
+                const spinner = createSpinner(`Waiting ${ms}ms...`);
+                await adapter.wait(ms);
+                if (isJsonMode()) {
+                    emitJson({ success: true, command: 'wait', durationMs: Date.now() - startMs });
+                    return;
+                }
+                spinner.succeed(`Waited ${ms}ms`);
+                return;
+            }
+            // Otherwise it's a selector
+            const action = options.hidden ? 'hide' : 'appear';
+            const spinner = createSpinner(`Waiting for ${condition} to ${action}...`);
+            await adapter.wait(condition, {
+                visible: !options.hidden,
+                hidden: options.hidden,
+                timeout: parseInt(options.timeout),
+            });
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'wait', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed(`Element ${condition} ${action}ed`);
+        }
+        catch (error) {
+            handleError(error, 'wait', startMs);
+        }
+    });
+}
+// Wait for text
+export function createWaitForTextCommand() {
+    return withActionOptions(new Command('wait-for-text'))
+        .argument('<text>', 'Text to wait for on the page')
+        .option('--timeout <ms>', 'Timeout in milliseconds', '30000')
+        .description('Wait for text to appear on the page')
+        .action(async (text, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Waiting for "${text}"...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.waitForText(text, {
+                timeout: parseInt(options.timeout),
+            });
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'wait-for-text', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed(`Text "${text}" found`);
+        }
+        catch (error) {
+            spinner.fail(`Text "${text}" not found`);
+            handleError(error, 'wait-for-text', startMs);
+        }
+    });
+}
+// Hover
+export function createHoverCommand() {
+    return withActionOptions(new Command('hover'))
+        .argument('<selector>', 'CSS selector of element to hover')
+        .description('Hover over an element')
+        .action(async (selector, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Hovering over ${selector}...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.hover(selector);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'hover', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed(`Hovered over ${selector}`);
+        }
+        catch (error) {
+            spinner.fail('Hover failed');
+            handleError(error, 'hover', startMs);
+        }
+    });
+}
+// Select
+export function createSelectCommand() {
+    return withActionOptions(new Command('select'))
+        .argument('<selector>', 'CSS selector of select element')
+        .argument('<value>', 'Value to select')
+        .description('Select option in dropdown')
+        .action(async (selector, value, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Selecting "${value}" in ${selector}...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.select(selector, value);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'select', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed(`Selected "${value}" in ${selector}`);
+        }
+        catch (error) {
+            spinner.fail('Select failed');
+            handleError(error, 'select', startMs);
+        }
+    });
+}
+// Press key
+export function createPressCommand() {
+    return withActionOptions(new Command('press'))
+        .argument('<key>', 'Key to press (e.g. Enter, Tab, Escape, ArrowDown)')
+        .description('Press a keyboard key')
+        .action(async (key, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Pressing ${key}...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.press(key);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'press', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed(`Pressed ${key}`);
+        }
+        catch (error) {
+            spinner.fail('Press failed');
+            handleError(error, 'press', startMs);
+        }
+    });
+}
+// Back
+export function createBackCommand() {
+    return withActionOptions(new Command('back'))
+        .description('Navigate back in browser history')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Going back...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.goBack();
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'back', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed('Navigated back');
+        }
+        catch (error) {
+            spinner.fail('Back failed');
+            handleError(error, 'back', startMs);
+        }
+    });
+}
+// Forward
+export function createForwardCommand() {
+    return withActionOptions(new Command('forward'))
+        .description('Navigate forward in browser history')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Going forward...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.goForward();
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'forward', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed('Navigated forward');
+        }
+        catch (error) {
+            spinner.fail('Forward failed');
+            handleError(error, 'forward', startMs);
+        }
+    });
+}
+const RESUME_SNAPSHOT_TIMEOUT_MS = 30_000;
+// Resume (re-read page state after handoff; equivalent to snapshot with handoff messaging)
+export function createResumeCommand() {
+    return withActionOptions(new Command('resume'))
+        .description('Re-read page state after human handoff (captures current snapshot so automation can continue)')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Resuming (capturing current state)...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await Promise.race([
+                adapter.snapshot(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Resume timed out after ${RESUME_SNAPSHOT_TIMEOUT_MS}ms`)), RESUME_SNAPSHOT_TIMEOUT_MS)),
+            ]);
+            if (isJsonMode()) {
+                const modeMeta = await getModeMetadataForJson(options?.mode);
+                emitJson({
+                    success: true,
+                    command: 'resume',
+                    durationMs: Date.now() - startMs,
+                    data: { content: result.data, resumed: true },
+                    ...modeMeta,
+                });
+                return;
+            }
+            spinner.succeed('Resumed. Current state captured.');
+            if (result.data != null) {
+                console.log(typeof result.data === 'string' ? result.data : JSON.stringify(result.data));
+            }
+        }
+        catch (error) {
+            spinner.fail('Resume failed');
+            handleError(error, 'resume', startMs);
+        }
+    });
+}
+// Snapshot (accessibility tree)
+export function createSnapshotCommand() {
+    return withActionOptions(new Command('snapshot'))
+        .description('Get accessibility snapshot of the page')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Taking snapshot...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.snapshot();
+            if (isJsonMode()) {
+                const modeMeta = await getModeMetadataForJson(options?.mode);
+                emitJson({ success: true, command: 'snapshot', durationMs: Date.now() - startMs, data: { content: result.data }, ...modeMeta });
+                return;
+            }
+            spinner.succeed('Snapshot captured');
+            console.log(result.data);
+        }
+        catch (error) {
+            spinner.fail('Snapshot failed');
+            handleError(error, 'snapshot', startMs);
+        }
+    });
+}
+// Screenshot
+export function createScreenshotCommand() {
+    return withActionOptions(new Command('screenshot'))
+        .option('--output <path>', 'Save screenshot to file')
+        .option('--full-page', 'Capture full scrollable page')
+        .option('--selector <selector>', 'Capture specific element')
+        .option('--caption <text>', 'Required when syncing local screenshots to a ThinkRun session')
+        .option('--format <type>', 'Image format: png|jpeg|webp', 'png')
+        .option('--quality <n>', 'JPEG/WebP quality (0-100)', '80')
+        .option('--max-dimension <px>', 'Resize so the largest dimension does not exceed this value (e.g. 1280)')
+        .description('Capture screenshot')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Capturing screenshot...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.screenshot({
+                output: options.output,
+                fullPage: options.fullPage,
+                selector: options.selector,
+                format: options.format,
+                quality: parseInt(options.quality),
+                maxDimension: options.maxDimension ? parseInt(options.maxDimension) : undefined,
+                caption: options.caption,
+            });
+            if (result.data?.local) {
+                // Local mode — screenshot already saved to temp file by LocalAdapter
+                const savedPath = options.output || result.data.path;
+                if (options.output && result.data.path !== options.output) {
+                    copyFileSync(result.data.path, options.output);
+                    // Remove the temp file after copying to the requested output path to avoid
+                    // leaking stale screenshots in /tmp (especially in agent loops).
+                    try {
+                        unlinkSync(result.data.path);
+                    }
+                    catch { /* ignore cleanup errors */ }
+                }
+                if (isJsonMode()) {
+                    emitJson({ success: true, command: 'screenshot', durationMs: Date.now() - startMs,
+                        data: { path: savedPath, url: result.data?.url } });
+                    return;
+                }
+                spinner.succeed(`Screenshot saved to ${savedPath}`);
+                if (result.data?.url)
+                    console.log('  URL:', chalk.cyan(result.data.url));
+            }
+            else if (options.output && result.data?.url) {
+                // Cloud mode — download from R2 to file
+                const response = await fetch(result.data.url);
+                const buffer = Buffer.from(await response.arrayBuffer());
+                writeFileSync(options.output, buffer);
+                if (isJsonMode()) {
+                    emitJson({ success: true, command: 'screenshot', durationMs: Date.now() - startMs,
+                        data: { path: options.output, url: result.data.url } });
+                    return;
+                }
+                spinner.succeed(`Screenshot saved to ${options.output}`);
+            }
+            else {
+                if (isJsonMode()) {
+                    emitJson({ success: true, command: 'screenshot', durationMs: Date.now() - startMs,
+                        data: { url: result.data?.url, path: result.data?.path } });
+                    return;
+                }
+                spinner.succeed('Screenshot captured');
+                if (result.data?.url)
+                    console.log('  URL:', chalk.cyan(result.data.url));
+                if (result.data?.path)
+                    console.log('  Saved:', chalk.cyan(result.data.path));
+            }
+        }
+        catch (error) {
+            spinner.fail('Screenshot failed');
+            handleError(error, 'screenshot', startMs);
+        }
+    });
+}
+// Extract
+export function createExtractCommand() {
+    return withActionOptions(new Command('extract'))
+        .argument('<selector>', 'CSS selector of element(s) to extract')
+        .option('--all', 'Extract all matching elements')
+        .option('--attr <name>', 'Extract attribute instead of text')
+        .option('--format <type>', 'Output format: text|json|html', 'text')
+        .description('Extract content from elements')
+        .action(async (selector, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Extracting from ${selector}...`);
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.extract(selector, {
+                all: options.all,
+                attr: options.attr,
+                format: options.format,
+            });
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'extract', durationMs: Date.now() - startMs, data: result.data });
+                return;
+            }
+            spinner.succeed('Extracted');
+            if (options.format === 'json') {
+                console.log(JSON.stringify(result.data, null, 2));
+            }
+            else {
+                console.log(result.data);
+            }
+        }
+        catch (error) {
+            spinner.fail('Extract failed');
+            handleError(error, 'extract', startMs);
+        }
+    });
+}
+// Evaluate
+export function createEvaluateCommand() {
+    return withActionOptions(new Command('evaluate'))
+        .argument('[script]', 'JavaScript to execute')
+        .option('--file <path>', 'Read script from file')
+        .option('--stdin', 'Read script from stdin (pipe or heredoc; mutually exclusive with --file and a script argument)')
+        .option('--timeout <ms>', 'Maximum time for evaluate in milliseconds (default: 30000)', '30000')
+        .description('Execute JavaScript in page context')
+        .action(async (script, options) => {
+        const startMs = Date.now();
+        try {
+            const adapter = await getCommandAdapter(options);
+            if (options.file && options.stdin) {
+                console.error(chalk.red('Error:'), 'Use either --file or --stdin, not both');
+                process.exit(1);
+            }
+            if (options.stdin && script) {
+                console.error(chalk.red('Error:'), 'With --stdin, do not pass a script argument');
+                process.exit(1);
+            }
+            if (options.file) {
+                const { readFileSync } = await import('fs');
+                script = readFileSync(options.file, 'utf-8');
+            }
+            else if (options.stdin) {
+                const { readFileSync } = await import('fs');
+                const { isatty } = await import('tty');
+                if (isatty(0)) {
+                    console.error(chalk.red('Error:'), '--stdin requires piped or redirected input (e.g. cat script.js | thinkrun evaluate --stdin)');
+                    process.exit(1);
+                }
+                script = readFileSync(0, 'utf-8');
+            }
+            if (!script) {
+                console.error(chalk.red('Error:'), 'Provide script as argument, --file, or --stdin');
+                process.exit(1);
+            }
+            const timeoutMs = clampEvaluateTimeoutMs(options.timeout);
+            const spinner = createSpinner('Executing script...');
+            const result = await adapter.evaluate(script, [], { timeout: timeoutMs });
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'evaluate', durationMs: Date.now() - startMs, data: result.data });
+                return;
+            }
+            spinner.succeed('Script executed');
+            console.log(result.data);
+        }
+        catch (error) {
+            handleError(error, 'evaluate', startMs);
+        }
+    });
+}
+// Dialog
+export function createDialogCommand() {
+    const dialogCmd = new Command('dialog')
+        .description('Handle browser dialogs (alert, confirm, prompt)');
+    dialogCmd.addCommand(withActionOptions(new Command('get'))
+        .description('Check for pending dialog')
+        .action(async (options) => {
+        const startMs = Date.now();
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.getDialog();
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'dialog get', durationMs: Date.now() - startMs,
+                    data: { dialog: result.dialog ?? null, history: result.history ?? [] } });
+                return;
+            }
+            if (result.dialog) {
+                console.log(chalk.bold('Dialog:'));
+                console.log('  Type:   ', chalk.cyan(result.dialog.type));
+                console.log('  Message:', result.dialog.message);
+                if (result.dialog.defaultValue) {
+                    console.log('  Default:', result.dialog.defaultValue);
+                }
+            }
+            else {
+                console.log(chalk.gray('No pending dialog'));
+            }
+            if (result.history && result.history.length > 0) {
+                console.log('');
+                console.log(chalk.bold(`Dialog History (${result.history.length}):`));
+                for (const entry of result.history) {
+                    console.log(`  ${chalk.gray(entry.timestamp)} ${entry.type}: "${entry.message}" -> ${entry.action}`);
+                }
+            }
+        }
+        catch (error) {
+            handleError(error, 'dialog get', startMs);
+        }
+    }));
+    dialogCmd.addCommand(withActionOptions(new Command('accept'))
+        .argument('[text]', 'Text for prompt dialogs')
+        .description('Accept the pending dialog')
+        .action(async (text, options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Accepting dialog...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.handleDialog('accept', text);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'dialog accept', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed('Dialog accepted');
+        }
+        catch (error) {
+            spinner.fail('Failed to accept dialog');
+            handleError(error, 'dialog accept', startMs);
+        }
+    }));
+    dialogCmd.addCommand(withActionOptions(new Command('dismiss'))
+        .description('Dismiss the pending dialog')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Dismissing dialog...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.handleDialog('dismiss');
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'dialog dismiss', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed('Dialog dismissed');
+        }
+        catch (error) {
+            spinner.fail('Failed to dismiss dialog');
+            handleError(error, 'dialog dismiss', startMs);
+        }
+    }));
+    return dialogCmd;
+}
+// Console
+export function createConsoleCommand() {
+    return withActionOptions(new Command('console'))
+        .description('Get browser console messages')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Fetching console messages...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.getConsoleMessages();
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'console', durationMs: Date.now() - startMs,
+                    data: { logs: result.logs, count: result.count } });
+                return;
+            }
+            spinner.stop();
+            if (!result.logs || result.logs.length === 0) {
+                console.log(chalk.gray('No console messages'));
+                return;
+            }
+            console.log(chalk.bold(`Console Messages (${result.count}):`));
+            console.log('');
+            for (const log of result.logs) {
+                const levelColor = log.level === 'error' ? chalk.red
+                    : log.level === 'warning' ? chalk.yellow
+                        : log.level === 'info' ? chalk.blue
+                            : chalk.gray;
+                console.log(`  ${levelColor(`[${log.level}]`)} ${log.text}`);
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to fetch console messages');
+            handleError(error, 'console', startMs);
+        }
+    });
+}
+// Network
+export function createNetworkCommand() {
+    return withActionOptions(new Command('network'))
+        .description('Get network requests')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Fetching network requests...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.getNetworkRequests();
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'network', durationMs: Date.now() - startMs,
+                    data: { requests: result.requests, count: result.count } });
+                return;
+            }
+            spinner.stop();
+            if (!result.requests || result.requests.length === 0) {
+                console.log(chalk.gray('No network requests'));
+                return;
+            }
+            console.log(chalk.bold(`Network Requests (${result.count}):`));
+            console.log('');
+            for (const req of result.requests) {
+                const statusColor = req.status && req.status < 300 ? chalk.green
+                    : req.status && req.status < 400 ? chalk.cyan
+                        : req.status && req.status < 500 ? chalk.yellow
+                            : chalk.red;
+                const status = req.status ? statusColor(req.status.toString()) : chalk.gray('---');
+                const method = chalk.bold(req.method.padEnd(6));
+                const size = req.size ? chalk.gray(`${(req.size / 1024).toFixed(1)}KB`) : '';
+                console.log(`  ${status} ${method} ${req.url} ${size}`);
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to fetch network requests');
+            handleError(error, 'network', startMs);
+        }
+    });
+}
+/**
+ * Fetch the list of open Chrome tabs from the native host bridge.
+ * Accepts an optional fetchFn for testability.
+ *
+ * Route note: the bridge exposes GET /tabs (no /api prefix) for the tab list.
+ * The switch endpoint lives at POST /api/tabs/switch (with /api prefix).
+ * This asymmetry is intentional — the bridge inherits browse.sh flat routes
+ * for read operations and express-style /api routes for mutations.
+ */
+export async function fetchTabsFromBridge(port, fetchFn = fetch) {
+    // Tab listing assumes the bridge is already up — not a cold-start probe (see BRIDGE_HEALTH_PROBE_TIMEOUT_MS).
+    const res = await fetchFn(`http://127.0.0.1:${port}/tabs`, {
+        signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        return { ok: false, status: res.status };
+    const body = await res.json();
+    const tabs = body?.data?.tabs;
+    if (!Array.isArray(tabs))
+        return { ok: false, error: 'tabs field is not an array' };
+    return { ok: true, tabs: tabs };
+}
+export function formatNativeTabLine(tab, maxUrlLen = 60) {
+    const activeMarker = tab.active ? chalk.green('*') : ' ';
+    const id = chalk.cyan(String(tab.id).padEnd(6));
+    const rawUrl = tab.url ?? '';
+    const truncatedUrl = rawUrl.length > maxUrlLen
+        ? rawUrl.slice(0, maxUrlLen - 1) + '…'
+        : rawUrl;
+    const url = chalk.cyan(truncatedUrl);
+    const title = String(tab.title ?? '');
+    const owner = tab.ownerSessionId
+        ? chalk.gray(`  [owned by ${tab.ownerSessionId}]`)
+        : '';
+    return `  ${activeMarker}  ${id}  ${url}  ${title}${owner}`;
+}
+const SCROLL_FALLBACK_AFTER_EXCEPTIONS = 'scroll command fell back to evaluate after repeated bridge/API errors';
+const SCROLL_FALLBACK_AFTER_FALSE = 'scroll command fell back to evaluate after scroll returned success:false repeatedly';
+/** Integer pixels only — rejects partial strings like `200px` that parseInt would truncate. */
+function parseStrictIntPixels(raw) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n))
+        return null;
+    return n;
+}
+/** True for transport-level bridge failures (used by scroll retry and attach/switch-tab/focus). */
+export function isBridgeUnreachableError(error) {
+    if (typeof error === 'object' && error !== null && error.name === 'TimeoutError') {
+        return true;
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    return /ECONNREFUSED|fetch failed/i.test(msg);
+}
+function isRetryableScrollFailure(e) {
+    if (isBridgeUnreachableError(e))
+        return true;
+    if (e instanceof ApiError) {
+        if (e.retryable === true)
+            return true;
+        if (e.retryable === false)
+            return false;
+        const c = e.nativeCode ?? e.code;
+        if (c === 'NATIVE_HOST_UNREACHABLE')
+            return true;
+        if (c === 'API_ERROR') {
+            const s = e.statusCode ?? 0;
+            if (s === 408 || s === 429 || s >= 500)
+                return true;
+        }
+        return false;
+    }
+    return false;
+}
+/**
+ * Vertical page scroll with retries on transient bridge/API failures, then
+ * `evaluate(window.scrollBy)` fallback (0042-B). Selector-based scroll is unchanged.
+ */
+export async function scrollWithRetryAndFallback(adapter, scrollOptions) {
+    if (scrollOptions.selector !== undefined) {
+        await adapter.scroll(scrollOptions);
+        return;
+    }
+    const y = scrollOptions.y;
+    if (y === undefined) {
+        await adapter.scroll(scrollOptions);
+        return;
+    }
+    if (!Number.isFinite(y)) {
+        throw new Error('scroll amount must be a number');
+    }
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const out = await adapter.scroll(scrollOptions);
+            if (out.success !== false)
+                return;
+            if (attempt < 2) {
+                await new Promise((r) => setTimeout(r, 500));
+                continue;
+            }
+            console.error(chalk.yellow('Warning:'), SCROLL_FALLBACK_AFTER_FALSE);
+            await adapter.evaluate('window.scrollBy(0, arguments[0])', [y]);
+            return;
+        }
+        catch (e) {
+            if (!isRetryableScrollFailure(e))
+                throw e;
+            if (attempt < 2) {
+                await new Promise((r) => setTimeout(r, 500));
+                continue;
+            }
+            console.error(chalk.yellow('Warning:'), SCROLL_FALLBACK_AFTER_EXCEPTIONS);
+            await adapter.evaluate('window.scrollBy(0, arguments[0])', [y]);
+            return;
+        }
+    }
+}
+function exitWithSwitchTabFailure(tabId, result, jsonCommand, startMs) {
+    if (isJsonMode()) {
+        emitJson({
+            success: false,
+            command: jsonCommand,
+            durationMs: Date.now() - startMs,
+            error: result.message || `HTTP ${result.status}`,
+            code: result.code ?? 'SWITCH_TAB_FAILED',
+        });
+        process.exit(1);
+    }
+    if (result.code === 'TAB_NOT_FOUND') {
+        const tabDesc = tabId != null ? `Tab ${tabId}` : 'Tab';
+        console.error(chalk.red('Error:'), `${tabDesc} not found. Run \`thinkrun tabs\` to list visible tabs. Note: incognito tabs are not visible to the extension.`);
+        process.exit(1);
+    }
+    if (result.code === 'EXTENSION_NOT_CONNECTED') {
+        console.error(chalk.red('Error:'), 'Extension not connected. Open your Chromium-based browser with the ThinkRun extension and try again. Run `thinkrun doctor` to diagnose.');
+        process.exit(1);
+    }
+    console.error(chalk.red('Error:'), result.message || `HTTP ${result.status}`, chalk.gray('Run `thinkrun doctor` if this persists.'));
+    process.exit(1);
+}
+function exitWithBridgeUnreachable(command, startMs, error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    if (isJsonMode()) {
+        emitJson({
+            success: false,
+            command,
+            durationMs: Date.now() - startMs,
+            error: msg,
+            code: 'BRIDGE_UNREACHABLE',
+        });
+        process.exit(1);
+    }
+    console.error(chalk.red('Error:'), 'Bridge not running. Run `thinkrun doctor` to diagnose.');
+    process.exit(1);
+}
+/**
+ * Switch the active Chrome tab via the native host bridge.
+ * Accepts an optional fetchFn for testability.
+ */
+export async function switchTabOnBridge(port, tabId, opts, fetchFn = fetch) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (opts?.sessionId) {
+        headers['x-session-id'] = opts.sessionId;
+    }
+    const res = await fetchFn(`http://127.0.0.1:${port}/api/tabs/switch`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ tabId }),
+        signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+    });
+    const text = await res.text();
+    let body = {};
+    if (text) {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                body = parsed;
+            }
+        }
+        catch {
+            // non-JSON body
+        }
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            status: res.status,
+            code: typeof body.code === 'string' ? body.code : undefined,
+            message: typeof body.error === 'string' ? body.error : undefined,
+        };
+    }
+    return { ok: true };
+}
+export async function newTabOnBridge(port, url, fetchFn = fetch) {
+    const res = await fetchFn(`http://127.0.0.1:${port}/api/tabs/new`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(url ? { url } : {}),
+        signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+    });
+    const text = await res.text();
+    let body = {};
+    if (text) {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === 'object')
+                body = parsed;
+        }
+        catch {
+            // non-JSON body
+        }
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            status: res.status,
+            code: typeof body.code === 'string' ? body.code : undefined,
+            message: typeof body.error === 'string' ? body.error : undefined,
+        };
+    }
+    const data = body.data ?? {};
+    const tabId = data.tabId;
+    if (!Number.isFinite(tabId) || !tabId) {
+        return { ok: false, status: 502, code: 'INVALID_RESPONSE', message: 'Native host returned no tabId for new tab' };
+    }
+    return {
+        ok: true,
+        tab: {
+            id: tabId,
+            url: typeof data.url === 'string' ? data.url : (url ?? 'about:blank'),
+            title: typeof data.title === 'string' ? data.title : '',
+            active: false,
+            ...(typeof data.windowId === 'number' ? { windowId: data.windowId } : {}),
+        },
+    };
+}
+export async function closeTabOnBridge(port, tabId, opts, fetchFn = fetch) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (opts?.sessionId) {
+        headers['x-session-id'] = opts.sessionId;
+    }
+    const res = await fetchFn(`http://127.0.0.1:${port}/api/tabs/close`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ tabId }),
+        signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+    });
+    const text = await res.text();
+    let body = {};
+    if (text) {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === 'object')
+                body = parsed;
+        }
+        catch {
+            // non-JSON body
+        }
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            status: res.status,
+            code: typeof body.code === 'string' ? body.code : undefined,
+            message: typeof body.error === 'string' ? body.error : undefined,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Register (or refresh) an agent session for a tab via POST /sessions/register.
+ * When `sessionId` is omitted, the extension assigns a new session id.
+ */
+export async function registerSessionOnBridge(port, tabId, opts, fetchFn = fetch) {
+    const res = await fetchFn(`http://127.0.0.1:${port}/sessions/register`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            tabId,
+            ...(opts?.sessionId ? { sessionId: opts.sessionId } : {}),
+        }),
+        signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+    });
+    const text = await res.text();
+    let body = {};
+    if (text) {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === 'object')
+                body = parsed;
+        }
+        catch {
+            // non-JSON
+        }
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            status: res.status,
+            code: typeof body.code === 'string' ? body.code : undefined,
+            message: typeof body.error === 'string' ? body.error : undefined,
+        };
+    }
+    const data = body.data ?? {};
+    return {
+        ok: true,
+        sessionId: typeof data.sessionId === 'string' ? data.sessionId : undefined,
+        windowId: typeof data.windowId === 'number' ? data.windowId : undefined,
+    };
+}
+async function readLiveTabMetadata(port, tabId, fetchFn = fetch) {
+    try {
+        // Best-effort reconciliation only: if /tabs is unavailable or returns an
+        // unexpected shape, fall back silently to the create/register response.
+        const res = await fetchFn(`http://127.0.0.1:${port}/tabs`, {
+            signal: AbortSignal.timeout(BRIDGE_HEALTH_PROBE_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return {};
+        const text = await res.text();
+        if (!text)
+            return {};
+        const parsed = JSON.parse(text);
+        const liveTab = parsed?.data?.tabs?.find((tab) => tab?.id === tabId);
+        if (!liveTab)
+            return {};
+        return {
+            ...(typeof liveTab.windowId === 'number' ? { windowId: liveTab.windowId } : {}),
+            ...(typeof liveTab.url === 'string' ? { url: liveTab.url } : {}),
+            ...(typeof liveTab.title === 'string' ? { title: liveTab.title } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function exitWithRegisterFailure(reg, jsonCommand, startMs, spinner) {
+    const hint = getNativeCodeHint(reg.code) ?? 'Run: thinkrun session debug --json';
+    const msg = reg.message || `Session registration failed (HTTP ${reg.status})`;
+    if (isJsonMode()) {
+        emitJson({
+            success: false,
+            command: jsonCommand,
+            durationMs: Date.now() - startMs,
+            error: msg,
+            code: reg.code ?? 'REGISTER_SESSION_FAILED',
+            hint,
+            retryable: false,
+        });
+        process.exit(1);
+    }
+    spinner.fail('Failed to attach to tab');
+    console.error(chalk.red('Error:'), msg);
+    console.error(chalk.yellow('Tip:'), hint);
+    process.exit(1);
+}
+// Tabs — list open Chrome tabs via the native host
+export function createTabsCommand() {
+    return new Command('tabs')
+        .description('List open Chromium-based browser tabs via the native host (local mode)')
+        .action(async () => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Fetching tabs...');
+        try {
+            const port = readBridgePort();
+            const result = await fetchTabsFromBridge(port);
+            if (!result.ok) {
+                const errMsg = 'status' in result
+                    ? `Failed to fetch tabs: HTTP ${result.status}`
+                    : `Failed to fetch tabs: ${result.error}`;
+                spinner.fail(errMsg);
+                if (isJsonMode()) {
+                    // Write structured error to stderr so agents reading stdout don't mix error
+                    // envelopes with success envelopes.
+                    process.stderr.write(JSON.stringify({ success: false, command: 'tabs', durationMs: Date.now() - startMs, error: errMsg, code: 'NATIVE_HOST_ERROR' }) + '\n');
+                }
+                process.exit(1);
+            }
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'tabs', durationMs: Date.now() - startMs, data: { tabs: result.tabs } });
+                return;
+            }
+            spinner.stop();
+            const { tabs } = result;
+            if (tabs.length === 0) {
+                console.log(chalk.gray('No tabs found'));
+                return;
+            }
+            const MAX_URL_LEN = 60;
+            console.log(chalk.bold(`Tabs (${tabs.length}):`));
+            console.log('');
+            for (const tab of tabs) {
+                console.log(formatNativeTabLine(tab, MAX_URL_LEN));
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to fetch tabs');
+            handleError(error, 'tabs', startMs);
+        }
+    });
+}
+export function createNewTabCommand() {
+    return withModeOption(new Command('new-tab'))
+        .argument('[url]', 'Optional URL to open in the new tab')
+        .description('Open a new tab in your Chromium-based browser (local mode). ' +
+        'Unlike new-window, this does not attach to or rebind the active local session.')
+        .action(async (url, options) => {
+        const startMs = Date.now();
+        if (options?.mode === 'cloud') {
+            console.error(chalk.red('Error:'), 'new-tab is local-only; do not use --mode cloud');
+            process.exit(1);
+        }
+        const spinner = createSpinner('Opening new browser tab...');
+        try {
+            const port = readBridgePort();
+            const result = await newTabOnBridge(port, url);
+            if (!result.ok) {
+                spinner.fail('Failed to open new tab');
+                exitWithSwitchTabFailure(undefined, result, 'new-tab', startMs);
+            }
+            if (isJsonMode()) {
+                emitJson({
+                    success: true,
+                    command: 'new-tab',
+                    durationMs: Date.now() - startMs,
+                    data: result.tab,
+                });
+                return;
+            }
+            spinner.succeed(`Opened tab ${result.tab.id}`);
+            console.log(chalk.gray('Not attached — use `thinkrun attach <tabId>` if you want to bind this tab.'));
+            console.log(chalk.gray(`URL: ${result.tab.url}`));
+        }
+        catch (error) {
+            spinner.fail('Failed to open new tab');
+            if (isBridgeUnreachableError(error)) {
+                exitWithBridgeUnreachable('new-tab', startMs, error);
+            }
+            handleError(error, 'new-tab', startMs);
+        }
+    });
+}
+// URL — get the current page URL
+export function createUrlCommand() {
+    return withActionOptions(new Command('url'))
+        .description('Get the current page URL')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Fetching page URL...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.getUrl();
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'url', durationMs: Date.now() - startMs, data: result.data });
+                return;
+            }
+            spinner.succeed('URL retrieved');
+            console.log(result.data);
+        }
+        catch (error) {
+            spinner.fail('Failed to get URL');
+            handleError(error, 'url', startMs);
+        }
+    });
+}
+// Title — get the current page title
+export function createTitleCommand() {
+    return withActionOptions(new Command('title'))
+        .description('Get the current page title')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Fetching page title...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.getTitle();
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'title', durationMs: Date.now() - startMs, data: result.data });
+                return;
+            }
+            spinner.succeed('Title retrieved');
+            console.log(result.data);
+        }
+        catch (error) {
+            spinner.fail('Failed to get title');
+            handleError(error, 'title', startMs);
+        }
+    });
+}
+// HTML — get the full page HTML
+export function createHtmlCommand() {
+    return withActionOptions(new Command('html'))
+        .description('Get the full page HTML')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Fetching page HTML...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            const result = await adapter.getHtml();
+            const html = result.data;
+            if (!html) {
+                spinner.fail('No HTML returned');
+                process.exit(1);
+            }
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'html', durationMs: Date.now() - startMs, data: html });
+                return;
+            }
+            if (process.stdout.isTTY) {
+                spinner.succeed('HTML retrieved');
+            }
+            else {
+                spinner.stop();
+            }
+            process.stdout.write(html + '\n');
+        }
+        catch (error) {
+            spinner.fail('Failed to get HTML');
+            handleError(error, 'html', startMs);
+        }
+    });
+}
+// Clear logs — clear console and network logs for the active session
+export function createClearLogsCommand() {
+    return withActionOptions(new Command('clear-logs'))
+        .description('Clear console and network logs for the active session')
+        .action(async (options) => {
+        const startMs = Date.now();
+        const spinner = createSpinner('Clearing logs...');
+        try {
+            const adapter = await getCommandAdapter(options);
+            await adapter.clearLogs();
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'clear-logs', durationMs: Date.now() - startMs });
+                return;
+            }
+            spinner.succeed('Logs cleared');
+        }
+        catch (error) {
+            spinner.fail('Failed to clear logs');
+            handleError(error, 'clear-logs', startMs);
+        }
+    });
+}
+// Switch tab — switch the active Chrome tab in the browser (local mode only, does NOT update active session config)
+export function createFocusCommand() {
+    return withModeOption(new Command('focus'))
+        .description('Bring the Chromium-based browser window for the attached tab to the foreground (local mode). ' +
+        'Uses your current attach session tab — same as switch-tab with that id, without looking it up.')
+        .action(async (options) => {
+        const startMs = Date.now();
+        if (options?.mode === 'cloud') {
+            console.error(chalk.red('Error:'), 'focus is local-only. Pass --mode local, or use a local attach session (see thinkrun config --help).');
+            process.exit(1);
+        }
+        let currentCtx;
+        let tabIdStr;
+        try {
+            currentCtx = getLocalSessionContext();
+            tabIdStr = currentCtx?.tabId;
+        }
+        catch {
+            currentCtx = undefined;
+            tabIdStr = undefined;
+        }
+        if (!tabIdStr) {
+            console.error(chalk.red('Error:'), 'No active local tab. Run: thinkrun tabs\nThen: thinkrun attach <tabId>');
+            process.exit(1);
+        }
+        const tabId = parseInt(tabIdStr, 10);
+        if (isNaN(tabId) || tabId <= 0) {
+            console.error(chalk.red('Error:'), 'Invalid tab id in session context');
+            process.exit(1);
+        }
+        const spinner = createSpinner(`Focusing window for tab ${tabId}...`);
+        try {
+            const port = readBridgePort();
+            const result = await switchTabOnBridge(port, tabId, {
+                sessionId: currentCtx?.agentSessionId,
+            });
+            if (!result.ok) {
+                spinner.fail('Failed to focus');
+                exitWithSwitchTabFailure(tabId, result, 'focus', startMs);
+            }
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'focus', durationMs: Date.now() - startMs, data: { tabId } });
+                return;
+            }
+            spinner.succeed(`Focused window for tab ${tabId}`);
+        }
+        catch (error) {
+            spinner.fail('Failed to focus');
+            if (isBridgeUnreachableError(error)) {
+                exitWithBridgeUnreachable('focus', startMs, error);
+            }
+            handleError(error, 'focus', startMs);
+        }
+    });
+}
+export function createSwitchTabCommand() {
+    return new Command('switch-tab')
+        .argument('<tabId>', 'Chromium-based browser tab ID to switch to')
+        .description('Switch the active tab in your Chromium-based browser via the native host (local mode). Does not change active session config — use attach for that.')
+        .action(async (tabIdArg) => {
+        const startMs = Date.now();
+        const tabId = parseInt(tabIdArg, 10);
+        if (isNaN(tabId) || tabId <= 0) {
+            console.error(chalk.red('Error:'), 'tabId must be a positive integer');
+            process.exit(1);
+        }
+        const spinner = createSpinner(`Switching to tab ${tabId}...`);
+        try {
+            const port = readBridgePort();
+            const result = await switchTabOnBridge(port, tabId);
+            if (!result.ok) {
+                spinner.fail('Failed to switch tab');
+                exitWithSwitchTabFailure(tabId, result, 'switch-tab', startMs);
+            }
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'switch-tab', durationMs: Date.now() - startMs, data: { tabId } });
+                return;
+            }
+            spinner.succeed(`Switched to tab ${tabId}`);
+        }
+        catch (error) {
+            spinner.fail('Failed to switch tab');
+            if (isBridgeUnreachableError(error)) {
+                exitWithBridgeUnreachable('switch-tab', startMs, error);
+            }
+            handleError(error, 'switch-tab', startMs);
+        }
+    });
+}
+// Attach — switch to a Chrome tab by ID and set it as the active session
+export function createAttachCommand() {
+    return withModeOption(new Command('attach'))
+        .argument('<tabId>', 'Chromium-based browser tab ID to attach to')
+        .description('Attach to a tab in your Chromium-based browser (local mode) and set it as the active session.\n' +
+        'When an API key is configured, also registers a session in the cloud\n' +
+        'activity feed so screenshots and actions are visible in the dashboard.')
+        .option('--group <name>', 'Associate this agent with a named group for isolation')
+        .action(async (tabIdArg, options) => {
+        const startMs = Date.now();
+        if (options?.mode === 'cloud') {
+            console.error(chalk.red('Error:'), 'attach is local-only; do not use --mode cloud');
+            process.exit(1);
+        }
+        const tabId = parseInt(tabIdArg, 10);
+        if (isNaN(tabId) || tabId <= 0) {
+            console.error(chalk.red('Error:'), 'tabId must be a positive integer');
+            process.exit(1);
+        }
+        const group = options?.group;
+        const spinner = createSpinner(`Attaching to tab ${tabId}...`);
+        try {
+            const port = readBridgePort();
+            const ctxBefore = getLocalSessionContext();
+            const attachSessionId = ctxBefore?.tabId === String(tabId) && ctxBefore.agentSessionId
+                ? ctxBefore.agentSessionId
+                : undefined;
+            const result = await switchTabOnBridge(port, tabId, attachSessionId ? { sessionId: attachSessionId } : undefined);
+            if (!result.ok) {
+                spinner.fail('Failed to attach to tab');
+                exitWithSwitchTabFailure(tabId, result, 'attach', startMs);
+            }
+            // Idempotent re-attach: same tab + known session — refresh registry without unregistering first.
+            if (ctxBefore?.tabId === String(tabId) && ctxBefore.agentSessionId) {
+                const idem = await registerSessionOnBridge(port, tabId, { sessionId: ctxBefore.agentSessionId });
+                if (idem.ok) {
+                    const liveTab = await readLiveTabMetadata(port, tabId);
+                    const windowIdIdem = liveTab.windowId ?? idem.windowId;
+                    const agentSessionIdIdem = idem.sessionId ?? ctxBefore.agentSessionId;
+                    setWorkingLocation({
+                        tabId,
+                        ...(windowIdIdem !== undefined ? { windowId: windowIdIdem } : {}),
+                        ...(group ? { group } : {}),
+                    });
+                    initCliSession(String(tabId)).catch(() => { });
+                    setLocalSessionContext(String(tabId), agentSessionIdIdem, windowIdIdem);
+                    const refreshedContext = getLocalSessionContext();
+                    if (isJsonMode()) {
+                        emitJson({
+                            success: true,
+                            command: 'attach',
+                            durationMs: Date.now() - startMs,
+                            data: {
+                                tabId,
+                                idempotent: true,
+                                ...(refreshedContext?.controlSessionId
+                                    ? { controlSessionLabel: summarizeControlSessionLabel(refreshedContext.controlSessionId) }
+                                    : {}),
+                                ...(group ? { group } : {}),
+                            },
+                        });
+                        return;
+                    }
+                    spinner.succeed(`Attached to tab ${tabId}`);
+                    printLocalSessionReceipt({
+                        tabId,
+                        windowId: windowIdIdem,
+                        group,
+                        controlSessionId: refreshedContext?.controlSessionId,
+                        refreshed: true,
+                    });
+                    return;
+                }
+            }
+            const prevSessionId = getLocalSessionContext()?.agentSessionId;
+            const reg = await registerSessionOnBridge(port, tabId);
+            if (!reg.ok) {
+                exitWithRegisterFailure(reg, 'attach', startMs, spinner);
+            }
+            const liveTab = await readLiveTabMetadata(port, tabId);
+            let windowId = liveTab.windowId ?? reg.windowId;
+            let agentSessionId = reg.sessionId;
+            // Acquire per-process working location lock (throws TAB_LOCKED if contested).
+            setWorkingLocation({ tabId, ...(windowId !== undefined ? { windowId } : {}), ...(group ? { group } : {}) });
+            // Fire-and-forget: register CLI session in the cloud activity feed.
+            // Must never block or throw to the caller — cloud sync is best-effort.
+            initCliSession(String(tabId)).catch(() => { });
+            // Lock acquired — safe to update session context now.
+            setLocalSessionContext(String(tabId), agentSessionId, windowId);
+            if (prevSessionId && prevSessionId !== agentSessionId) {
+                try {
+                    await unregisterLocalAgentSession(port, prevSessionId);
+                }
+                catch (err) {
+                    process.stderr.write(`[thinkrun] warn: failed to unregister previous local session ${prevSessionId}: ${err}\n`);
+                }
+            }
+            const localContext = getLocalSessionContext();
+            if (isJsonMode()) {
+                emitJson({
+                    success: true,
+                    command: 'attach',
+                    durationMs: Date.now() - startMs,
+                    data: {
+                        tabId,
+                        ...(localContext?.controlSessionId
+                            ? { controlSessionLabel: summarizeControlSessionLabel(localContext.controlSessionId) }
+                            : {}),
+                        ...(group ? { group } : {}),
+                    },
+                });
+                return;
+            }
+            spinner.succeed(`Attached to tab ${tabId}`);
+            printLocalSessionReceipt({
+                tabId,
+                windowId,
+                group,
+                controlSessionId: localContext?.controlSessionId,
+            });
+        }
+        catch (error) {
+            const errMsg = error instanceof Error ? error.message : String(error);
+            if (errMsg.startsWith('TAB_LOCKED')) {
+                if (isJsonMode()) {
+                    emitJson({
+                        success: false,
+                        command: 'attach',
+                        durationMs: Date.now() - startMs,
+                        error: errMsg,
+                        code: 'TAB_LOCKED',
+                    });
+                    process.exit(1);
+                }
+                spinner.fail(errMsg);
+                process.exit(1);
+            }
+            spinner.fail('Failed to attach to tab');
+            if (isBridgeUnreachableError(error)) {
+                exitWithBridgeUnreachable('attach', startMs, error);
+            }
+            handleError(error, 'attach', startMs);
+        }
+    });
+}
+// New-window — open a dedicated Chrome window for isolated agent testing
+export function createNewWindowCommand() {
+    return withModeOption(new Command('new-window'))
+        .argument('[url]', 'Optional URL to open in the new window', 'about:blank')
+        .description('Open a new window in your Chromium-based browser and attach to it (local mode).\n' +
+        'Each window is fully isolated for screenshots — multiple agents can\n' +
+        'run simultaneously without interfering with each other.\n' +
+        'When an API key is configured, also registers a session in the cloud\n' +
+        'activity feed so screenshots and actions are visible in the dashboard.')
+        .option('--no-focus', 'Open the window in the background without stealing focus')
+        .option('--group <name>', 'Associate this agent with a named group for isolation')
+        .action(async (url, opts) => {
+        const startMs = Date.now();
+        if (opts?.mode === 'cloud') {
+            console.error(chalk.red('Error:'), 'new-window is local-only; do not use --mode cloud');
+            process.exit(1);
+        }
+        const group = opts?.group;
+        const spinner = createSpinner('Opening new browser window...');
+        try {
+            const port = readBridgePort();
+            // Ask the extension to open a new Chrome window
+            const res = await fetch(`http://127.0.0.1:${port}/api/sessions/new-window`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ url, focused: opts.focus }),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => ({}));
+                spinner.fail(`Failed to open window: ${body?.error ?? res.status}`);
+                process.exit(1);
+            }
+            const data = (await res.json());
+            const tabId = data?.data?.tabId;
+            const reportedWindowId = data?.data?.windowId;
+            if (!tabId) {
+                spinner.fail('No tabId returned from native host');
+                process.exit(1);
+            }
+            const previousLocalSessionId = getLocalSessionContext()?.agentSessionId;
+            const reg = await registerSessionOnBridge(port, tabId);
+            if (!reg.ok) {
+                exitWithRegisterFailure(reg, 'new-window', startMs, spinner);
+            }
+            const liveTab = await readLiveTabMetadata(port, tabId);
+            const windowId = liveTab.windowId ?? reg.windowId ?? reportedWindowId;
+            const agentSessionId = reg.sessionId;
+            if (!agentSessionId) {
+                if (isJsonMode()) {
+                    emitJson({
+                        success: false,
+                        command: 'new-window',
+                        durationMs: Date.now() - startMs,
+                        error: 'Session registration succeeded but returned no sessionId',
+                        code: 'REGISTER_SESSION_FAILED',
+                        hint: 'Run: thinkrun attach <tabId> or thinkrun session debug --json',
+                        retryable: false,
+                    });
+                    process.exit(1);
+                }
+                spinner.fail('Failed to open new window');
+                console.error(chalk.red('Error:'), 'Session registration succeeded but returned no sessionId');
+                console.error(chalk.yellow('Tip:'), 'Run: thinkrun attach <tabId> or thinkrun session debug --json');
+                process.exit(1);
+            }
+            // Acquire per-process working location lock BEFORE updating session context
+            // so a TAB_LOCKED failure doesn't leave context pointing at a contested tab.
+            setWorkingLocation({ tabId, ...(windowId !== undefined ? { windowId } : {}), ...(group ? { group } : {}) });
+            // Fire-and-forget: register CLI session in the cloud activity feed.
+            // Must never block or throw to the caller — cloud sync is best-effort.
+            initCliSession(String(tabId)).catch(() => { });
+            // Lock acquired — safe to update session context now.
+            setLocalSessionContext(String(tabId), agentSessionId, windowId);
+            if (previousLocalSessionId) {
+                try {
+                    await unregisterLocalAgentSession(port, previousLocalSessionId);
+                }
+                catch (err) {
+                    process.stderr.write(`[thinkrun] warn: failed to unregister previous local session ${previousLocalSessionId}: ${err}\n`);
+                }
+            }
+            const localContext = getLocalSessionContext();
+            if (isJsonMode()) {
+                emitJson({
+                    success: true,
+                    command: 'new-window',
+                    durationMs: Date.now() - startMs,
+                    data: {
+                        tabId,
+                        windowId,
+                        url,
+                        ...(localContext?.controlSessionId
+                            ? { controlSessionLabel: summarizeControlSessionLabel(localContext.controlSessionId) }
+                            : {}),
+                        ...(group ? { group } : {}),
+                    },
+                });
+                return;
+            }
+            spinner.succeed(`New window opened — attached to tab ${tabId} (window ${windowId})`);
+            console.log(chalk.gray(`Screenshot isolation: each agent window captures independently`));
+            printLocalSessionReceipt({
+                tabId,
+                windowId,
+                group,
+                controlSessionId: localContext?.controlSessionId,
+            });
+        }
+        catch (error) {
+            if (error?.message?.startsWith('TAB_LOCKED')) {
+                if (isJsonMode()) {
+                    emitJson({
+                        success: false,
+                        command: 'new-window',
+                        durationMs: Date.now() - startMs,
+                        error: error.message,
+                        code: 'TAB_LOCKED',
+                    });
+                    process.exit(1);
+                }
+                spinner.fail(error.message);
+                process.exit(1);
+            }
+            spinner.fail('Failed to open new window');
+            handleError(error, 'new-window', startMs);
+        }
+    });
+}
+export function createCloseTabCommand() {
+    return withModeOption(new Command('close-tab'))
+        .argument('[tabId]', 'Optional Chromium-based browser tab ID to close (defaults to the current attached tab)')
+        .description('Close a tab in your Chromium-based browser (local mode). ' +
+        'If no tab ID is provided, closes the currently attached local tab. ' +
+        'If you close the attached tab, local context and lock state are cleared.')
+        .action(async (tabIdArg, options) => {
+        const startMs = Date.now();
+        if (options?.mode === 'cloud') {
+            console.error(chalk.red('Error:'), 'close-tab is local-only; do not use --mode cloud');
+            process.exit(1);
+        }
+        const currentCtx = getLocalSessionContext();
+        const resolvedTabId = tabIdArg
+            ? parseInt(validateTabId(tabIdArg, 'close-tab argument'), 10)
+            : currentCtx?.tabId
+                ? parseInt(currentCtx.tabId, 10)
+                : NaN;
+        if (!Number.isFinite(resolvedTabId) || resolvedTabId <= 0) {
+            console.error(chalk.red('Error:'), 'No tabId provided and no active local tab is attached. Run: thinkrun tabs\nThen: thinkrun close-tab <tabId>');
+            process.exit(1);
+        }
+        const lock = getLockedBy(resolvedTabId);
+        if (lock) {
+            const currentAgentId = resolveAgentId();
+            const sameAgent = !!lock.agentId && lock.agentId === currentAgentId;
+            const samePid = lock.pid === process.pid;
+            const ownerPid = lock.ownerShellPid ?? lock.pid;
+            let ownerAlive = false;
+            try {
+                process.kill(ownerPid, 0);
+                ownerAlive = true;
+            }
+            catch (err) {
+                if (err.code === 'EPERM')
+                    ownerAlive = true;
+            }
+            if (!sameAgent && !samePid && ownerAlive) {
+                const ownerLabel = lock.agentId ? `agent ${lock.agentId}` : `PID ${ownerPid}`;
+                console.error(chalk.red('Error:'), `Tab ${resolvedTabId} is owned by ${ownerLabel}. Refusing to close a live foreign tab.`);
+                process.exit(1);
+            }
+        }
+        const spinner = createSpinner(`Closing tab ${resolvedTabId}...`);
+        try {
+            const port = readBridgePort();
+            const isCurrentTab = currentCtx?.tabId === String(resolvedTabId);
+            const result = await closeTabOnBridge(port, resolvedTabId, {
+                sessionId: currentCtx?.tabId === String(resolvedTabId) ? currentCtx.agentSessionId : undefined,
+            });
+            if (!result.ok) {
+                spinner.fail('Failed to close tab');
+                exitWithSwitchTabFailure(resolvedTabId, result, 'close-tab', startMs);
+            }
+            if (isCurrentTab && currentCtx?.agentSessionId) {
+                try {
+                    await unregisterLocalAgentSession(port, currentCtx.agentSessionId);
+                }
+                catch {
+                    // best-effort cleanup after the close succeeds; local context cleanup still proceeds
+                }
+            }
+            if (isCurrentTab) {
+                releaseWorkingLocation();
+                clearLocalSessionContext();
+                closeCliSession(String(resolvedTabId), 'completed');
+            }
+            if (isJsonMode()) {
+                emitJson({
+                    success: true,
+                    command: 'close-tab',
+                    durationMs: Date.now() - startMs,
+                    data: { tabId: resolvedTabId, clearedContext: Boolean(isCurrentTab) },
+                });
+                return;
+            }
+            spinner.succeed(`Closed tab ${resolvedTabId}`);
+            if (isCurrentTab) {
+                console.log(chalk.gray('Cleared attached local session context.'));
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to close tab');
+            if (isBridgeUnreachableError(error)) {
+                exitWithBridgeUnreachable('close-tab', startMs, error);
+            }
+            handleError(error, 'close-tab', startMs);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// AI Task commands — local mode only (native host task system)
+// ---------------------------------------------------------------------------
+const TASK_POLL_INTERVAL_MS = 2000;
+const TASK_DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const EXTENSION_AUTH_HINT = 'Local AI tasks still use the extension session relay. Save your API key in the ThinkRun extension Settings; `thinkrun config set-key` only configures the CLI/cloud client.';
+/**
+ * Throw the appropriate error for a failed native-host task start.
+ * 401 is gated on the HTTP status (not the error message text) so the
+ * actionable extension-auth hint survives server copy changes.
+ */
+function throwTaskStartError(status, message) {
+    if (status === 401) {
+        throw new ApiError(message, 401, EXTENSION_AUTH_HINT);
+    }
+    throw new Error(message);
+}
+/**
+ * POST a task to the native host and return `{taskId}`.
+ */
+async function startNativeTask(port, instruction, tabId, maxIterations) {
+    const body = { task: instruction };
+    if (tabId !== undefined)
+        body.tabId = tabId;
+    if (maxIterations !== undefined)
+        body.maxIterations = maxIterations;
+    const res = await fetch(`http://127.0.0.1:${port}/tasks`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10000),
+    });
+    const json = (await res.json());
+    // Native host wraps response as { success, data: { taskId, status } }
+    const taskId = json.data?.taskId ?? json.taskId;
+    if (!res.ok || !taskId) {
+        const message = json.error || json.data?.error || `Task start failed: HTTP ${res.status}`;
+        throwTaskStartError(res.status, message);
+    }
+    return taskId;
+}
+/**
+ * GET /tasks/:id/status from the native host.
+ */
+async function getNativeTaskStatus(port, taskId) {
+    const res = await fetch(`http://127.0.0.1:${port}/tasks/${taskId}/status`, {
+        signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+    });
+    const json = (await res.json());
+    if (!res.ok)
+        throw new Error(json.error || `Status fetch failed: HTTP ${res.status}`);
+    return json;
+}
+// Task — run an AI task via the native host
+export function createTaskCommand() {
+    return new Command('task')
+        .argument('<instruction>', 'Natural language instruction for the AI agent')
+        .option('--async', 'Return immediately with taskId instead of waiting for completion')
+        .option('--stream', 'Stream task events as NDJSON (SSE)')
+        .option('--timeout <ms>', 'Max wait time in milliseconds (default: 5 minutes)', String(TASK_DEFAULT_TIMEOUT_MS))
+        .option('--max-iterations <n>', 'Maximum AI iterations')
+        .description('Run an AI task in the active Chromium-based browser tab (local mode)')
+        .action(async (instruction, options) => {
+        const startMs = Date.now();
+        // Resolve port and active tabId
+        const port = readBridgePort();
+        const localContext = getLocalSessionContext();
+        const cloudContext = getCloudSessionContext();
+        if (!localContext) {
+            const hint = 'List tabs: thinkrun tabs\nThen attach: thinkrun attach <tabId>';
+            const cloudHint = 'The active session is a cloud session. Use: thinkrun attach <tabId> to attach to a local Chromium-based browser tab.';
+            if (isJsonMode()) {
+                process.stderr.write(JSON.stringify({
+                    success: false,
+                    command: 'task',
+                    error: cloudContext ? 'Active session is not a local tab' : 'No active tab',
+                    code: 'SESSION_ERROR',
+                    hint: cloudContext ? cloudHint : hint,
+                }) + '\n');
+                process.exit(1);
+            }
+            console.error(chalk.red('Error:'), cloudContext ? 'Active session is not a local tab ID' : 'No active tab');
+            console.error(chalk.yellow('Tip:'), cloudContext ? cloudHint : hint);
+            process.exit(1);
+        }
+        const tabId = parseInt(localContext.tabId, 10);
+        // --stream and --async are mutually exclusive
+        if (options.stream && options.async) {
+            const hint = 'Use --stream for live event output, or --async to get the taskId immediately. Not both.';
+            if (isJsonMode()) {
+                process.stderr.write(JSON.stringify({ success: false, command: 'task', error: '--stream and --async are mutually exclusive', code: 'INVALID_OPTIONS', hint }) + '\n');
+            }
+            else {
+                console.error(chalk.red('Error:'), '--stream and --async are mutually exclusive');
+                console.error(chalk.yellow('Tip:'), hint);
+            }
+            process.exit(1);
+        }
+        // --stream mode: connect to SSE endpoint
+        if (options.stream) {
+            const spinner = createSpinner(`Running task (streaming)...`);
+            try {
+                const body = { task: instruction, tabId };
+                if (options.maxIterations)
+                    body.maxIterations = parseInt(options.maxIterations);
+                const res = await fetch(`http://127.0.0.1:${port}/tasks/stream`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(parseInt(options.timeout) || TASK_DEFAULT_TIMEOUT_MS),
+                });
+                if (!res.ok) {
+                    const json = (await res.json());
+                    const message = json.error || `Stream start failed: HTTP ${res.status}`;
+                    throwTaskStartError(res.status, message);
+                }
+                spinner.stop();
+                // Stream SSE lines
+                if (!res.body) {
+                    throw new Error('Response body is null — native host returned no stream');
+                }
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                // Track task outcome so we can exit non-zero on failure (agents rely on exit code).
+                let lastTaskStatus;
+                try {
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        buffer += decoder.decode(value, { stream: true });
+                        const lines = buffer.split('\n');
+                        buffer = lines.pop() ?? '';
+                        for (const line of lines) {
+                            if (line.startsWith('data: ')) {
+                                const data = line.slice(6).trim();
+                                if (!data || data === '[DONE]')
+                                    continue;
+                                try {
+                                    const event = JSON.parse(data);
+                                    if (event?.status)
+                                        lastTaskStatus = event.status;
+                                    if (isJsonMode()) {
+                                        console.log(JSON.stringify(event));
+                                    }
+                                    else {
+                                        const type = event.type ?? 'event';
+                                        console.log('%s %s', chalk.gray(`[${type}]`), JSON.stringify(event).slice(0, 120));
+                                    }
+                                }
+                                catch { /* ignore malformed lines */ }
+                            }
+                        }
+                    }
+                }
+                finally {
+                    // Always release the reader to prevent connection leaks
+                    reader.cancel().catch(() => { });
+                }
+                // Exit non-zero if the task failed or was cancelled so agents can detect failure.
+                if (lastTaskStatus && lastTaskStatus !== 'completed') {
+                    process.exit(1);
+                }
+            }
+            catch (error) {
+                spinner.fail('Task stream failed');
+                handleError(error, 'task', startMs);
+            }
+            return;
+        }
+        const maxIterations = options.maxIterations ? parseInt(options.maxIterations) : undefined;
+        const spinner = createSpinner(`Starting task...`);
+        try {
+            const taskId = await startNativeTask(port, instruction, tabId, maxIterations);
+            // --async mode: return immediately
+            if (options.async) {
+                if (isJsonMode()) {
+                    emitJson({ success: true, command: 'task', durationMs: Date.now() - startMs,
+                        data: { taskId, status: 'pending' } });
+                }
+                else {
+                    spinner.succeed(`Task started: ${taskId}`);
+                    console.log(chalk.gray(`Poll with: thinkrun task-status ${taskId}`));
+                }
+                return;
+            }
+            // Synchronous poll until done
+            spinner.text = `Running task ${taskId}...`;
+            const timeoutMs = parseInt(options.timeout) || TASK_DEFAULT_TIMEOUT_MS;
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                await new Promise(r => setTimeout(r, TASK_POLL_INTERVAL_MS));
+                const status = await getNativeTaskStatus(port, taskId);
+                if (!isJsonMode()) {
+                    spinner.text = `Task ${taskId}: ${status.status}${status.iteration ? ` (step ${status.iteration})` : ''}`;
+                }
+                const terminal = ['completed', 'failed', 'cancelled'];
+                if (terminal.includes(status.status)) {
+                    if (isJsonMode()) {
+                        const envelope = { success: status.status === 'completed', command: 'task',
+                            durationMs: Date.now() - startMs, data: status };
+                        // Route failure envelopes to stderr so agents reading stdout only see successes.
+                        if (status.status === 'completed') {
+                            emitJson(envelope);
+                        }
+                        else {
+                            process.stderr.write(JSON.stringify(envelope) + '\n');
+                        }
+                    }
+                    else if (status.status === 'completed') {
+                        spinner.succeed(`Task completed (${status.iteration ?? '?'} steps)`);
+                        if (status.result)
+                            console.log(JSON.stringify(status.result, null, 2));
+                    }
+                    else {
+                        spinner.fail(`Task ${status.status}: ${status.error ?? ''}`);
+                    }
+                    if (status.status !== 'completed')
+                        process.exit(1);
+                    return;
+                }
+            }
+            // Timed out
+            spinner.fail(`Task timed out after ${Math.round(timeoutMs / 1000)}s`);
+            if (isJsonMode()) {
+                // Route failure envelopes to stderr — consistent with other failure paths.
+                process.stderr.write(JSON.stringify({ success: false, command: 'task',
+                    durationMs: Date.now() - startMs, error: 'Task timed out',
+                    code: 'TASK_TIMEOUT', retryable: false }) + '\n');
+            }
+            process.exit(1);
+        }
+        catch (error) {
+            spinner.fail('Task failed');
+            handleError(error, 'task', startMs);
+        }
+    });
+}
+// Task-status — poll task status by ID
+export function createTaskStatusCommand() {
+    return new Command('task-status')
+        .argument('<taskId>', 'Task ID returned by: thinkrun task --async')
+        .description('Get the status of a running or completed AI task (local mode)')
+        .action(async (taskId) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Fetching task status...`);
+        try {
+            const port = readBridgePort();
+            const status = await getNativeTaskStatus(port, taskId);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'task-status', durationMs: Date.now() - startMs, data: status });
+                return;
+            }
+            spinner.succeed(`Task ${taskId}: ${status.status}`);
+            if (status.result)
+                console.log(JSON.stringify(status.result, null, 2));
+            if (status.error)
+                console.error(chalk.red('Error:'), status.error);
+        }
+        catch (error) {
+            spinner.fail('Failed to get task status');
+            handleError(error, 'task-status', startMs);
+        }
+    });
+}
+// Task-cancel — cancel a running task
+export function createTaskCancelCommand() {
+    return new Command('task-cancel')
+        .argument('<taskId>', 'Task ID to cancel')
+        .description('Cancel a running AI task (local mode)')
+        .action(async (taskId) => {
+        const startMs = Date.now();
+        const spinner = createSpinner(`Cancelling task ${taskId}...`);
+        try {
+            const port = readBridgePort();
+            const res = await fetch(`http://127.0.0.1:${port}/tasks/${taskId}/cancel`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                signal: AbortSignal.timeout(BRIDGE_REQUEST_TIMEOUT_MS),
+            });
+            const json = (await res.json());
+            if (!res.ok)
+                throw new Error(json.error || `Cancel failed: HTTP ${res.status}`);
+            if (isJsonMode()) {
+                emitJson({ success: true, command: 'task-cancel', durationMs: Date.now() - startMs,
+                    data: { taskId, status: json.status } });
+                return;
+            }
+            spinner.succeed(`Task ${taskId} cancelled`);
+        }
+        catch (error) {
+            spinner.fail('Failed to cancel task');
+            handleError(error, 'task-cancel', startMs);
+        }
+    });
+}
+//# sourceMappingURL=actions.js.map