@jackwener/opencli 1.7.4 → 1.7.6

package/dist/src/cli.js

@@ -5,6 +5,7 @@
  * Dynamic adapter commands are registered via commanderAdapter.ts.
  */
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
@@ -13,7 +14,6 @@ import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
 import { fullName, getRegistry, strategyLabel } from './registry.js';
 import { serializeCommand, formatArgSummary } from './serialization.js';
 import { render as renderOutput } from './output.js';
-import { getBrowserFactory, browserSession } from './runtime.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
@@ -21,14 +21,188 @@ import { registerAllCommands } from './commanderAdapter.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
+import { buildFindJs, isFindError } from './browser/find.js';
+import { inferShape } from './browser/shape.js';
+import { assignKeys } from './browser/network-key.js';
+import { DEFAULT_TTL_MS, findEntry, loadNetworkCache, saveNetworkCache } from './browser/network-cache.js';
+import { parseFilter, shapeMatchesFilter } from './browser/shape-filter.js';
+import { buildHtmlTreeJs } from './browser/html-tree.js';
+import { buildExtractHtmlJs, runExtractFromHtml } from './browser/extract.js';
 import { daemonStatus, daemonStop } from './commands/daemon.js';
 import { log } from './logger.js';
 const CLI_FILE = fileURLToPath(import.meta.url);
+const DEFAULT_BROWSER_WORKSPACE = 'browser:default';
+const BROWSER_TAB_OPTION_DESCRIPTION = 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"';
+/**
+ * Normalize raw capture entries (from daemon/CDP `readNetworkCapture` or
+ * the JS interceptor's `window.__opencli_net`) into a consistent shape.
+ * Response preview is parsed as JSON when possible, otherwise kept as string.
+ * `bodyFullSize` / `bodyTruncated` surface capture-layer truncation so the
+ * agent-facing envelope can warn when the body isn't whole.
+ */
+async function captureNetworkItems(page) {
+    if (page.readNetworkCapture) {
+        const raw = await page.readNetworkCapture();
+        return raw.map((e) => {
+            const preview = e.responsePreview ?? null;
+            let body = null;
+            if (preview) {
+                try {
+                    body = JSON.parse(preview);
+                }
+                catch {
+                    body = preview;
+                }
+            }
+            const fullSize = typeof e.responseBodyFullSize === 'number'
+                ? e.responseBodyFullSize
+                : (preview ? preview.length : 0);
+            const truncated = e.responseBodyTruncated === true;
+            return {
+                url: e.url || '',
+                method: e.method || 'GET',
+                status: e.responseStatus || 0,
+                size: fullSize,
+                ct: e.responseContentType || '',
+                body,
+                bodyFullSize: fullSize,
+                bodyTruncated: truncated,
+            };
+        });
+    }
+    const raw = await page.evaluate(`(function(){ return JSON.stringify(window.__opencli_net || []); })()`);
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+}
+/** Drop static-resource / telemetry noise so agents see only API-shaped traffic. */
+function filterNetworkItems(items) {
+    return items.filter((r) => (r.ct?.includes('json') || r.ct?.includes('xml') || r.ct?.includes('text/plain')) &&
+        !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
+        !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url));
+}
+/** Emit a structured error JSON so agents can branch on `error.code` without regex. */
+function emitNetworkError(code, message, extra = {}) {
+    console.log(JSON.stringify({ error: { code, message, ...extra } }, null, 2));
+    process.exitCode = EXIT_CODES.USAGE_ERROR;
+}
+function getBrowserCacheDir() {
+    return process.env.OPENCLI_CACHE_DIR || path.join(os.homedir(), '.opencli', 'cache');
+}
+function getBrowserTargetStatePath(scope = DEFAULT_BROWSER_WORKSPACE) {
+    const safeWorkspace = scope.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return path.join(getBrowserCacheDir(), 'browser-state', `${safeWorkspace}.json`);
+}
+function loadBrowserTargetState(scope = DEFAULT_BROWSER_WORKSPACE) {
+    try {
+        const raw = fs.readFileSync(getBrowserTargetStatePath(scope), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveBrowserTargetState(defaultPage, scope = DEFAULT_BROWSER_WORKSPACE) {
+    const target = getBrowserTargetStatePath(scope);
+    if (!defaultPage) {
+        fs.rmSync(target, { force: true });
+        return;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify({ defaultPage, updatedAt: new Date().toISOString() }), 'utf-8');
+}
+function hasBrowserTabTarget(tabs, targetPage) {
+    return tabs.some((tab) => {
+        return typeof tab === 'object'
+            && tab !== null
+            && 'page' in tab
+            && typeof tab.page === 'string'
+            && tab.page === targetPage;
+    });
+}
+async function resolveBrowserTargetInSession(page, targetPage, opts) {
+    const candidate = targetPage.trim();
+    if (!candidate)
+        return undefined;
+    let tabs;
+    try {
+        tabs = await page.tabs();
+    }
+    catch (err) {
+        if (opts.source === 'saved') {
+            saveBrowserTargetState(undefined, opts.scope);
+            return undefined;
+        }
+        throw new Error(`Target tab ${candidate} could not be validated in the current browser session. ` +
+            'The Browser Bridge workspace may have restarted; re-run "opencli browser tab list" and choose a current target.', { cause: err });
+    }
+    if (Array.isArray(tabs) && hasBrowserTabTarget(tabs, candidate)) {
+        return candidate;
+    }
+    if (opts.source === 'saved') {
+        saveBrowserTargetState(undefined, opts.scope);
+        return undefined;
+    }
+    throw new Error(`Target tab ${candidate} is not part of the current browser session. ` +
+        'The Browser Bridge workspace may have restarted; re-run "opencli browser tab list" and choose a current target.');
+}
+async function resolveStoredBrowserTarget(page, scope = DEFAULT_BROWSER_WORKSPACE) {
+    const defaultPage = loadBrowserTargetState(scope)?.defaultPage?.trim();
+    if (!defaultPage)
+        return undefined;
+    return resolveBrowserTargetInSession(page, defaultPage, { scope, source: 'saved' });
+}
 /** Create a browser page for browser commands. Uses a dedicated browser workspace for session persistence. */
-async function getBrowserPage() {
+async function getBrowserPage(targetPage) {
     const { BrowserBridge } = await import('./browser/index.js');
     const bridge = new BrowserBridge();
-    return bridge.connect({ timeout: 30, workspace: 'browser:default' });
+    const envTimeout = process.env.OPENCLI_BROWSER_TIMEOUT;
+    const idleTimeout = envTimeout ? parseInt(envTimeout, 10) : undefined;
+    const page = await bridge.connect({
+        timeout: 30,
+        workspace: DEFAULT_BROWSER_WORKSPACE,
+        ...(idleTimeout && idleTimeout > 0 && { idleTimeout }),
+    });
+    const resolvedTargetPage = targetPage
+        ? await resolveBrowserTargetInSession(page, targetPage, { scope: DEFAULT_BROWSER_WORKSPACE, source: 'explicit' })
+        : await resolveStoredBrowserTarget(page, DEFAULT_BROWSER_WORKSPACE);
+    if (resolvedTargetPage) {
+        if (!page.setActivePage) {
+            throw new Error('This browser session does not support explicit tab targeting');
+        }
+        page.setActivePage(resolvedTargetPage);
+    }
+    return page;
+}
+function addBrowserTabOption(command) {
+    return command.option('--tab <targetId>', BROWSER_TAB_OPTION_DESCRIPTION);
+}
+function getBrowserTargetId(command) {
+    if (!command)
+        return undefined;
+    const opts = command.optsWithGlobals ? command.optsWithGlobals() : command.opts();
+    return typeof opts.tab === 'string' && opts.tab.trim() ? opts.tab.trim() : undefined;
+}
+function resolveBrowserTabTarget(targetId, opts) {
+    if (typeof targetId === 'string' && targetId.trim())
+        return targetId.trim();
+    if (typeof opts?.tab === 'string' && opts.tab.trim())
+        return opts.tab.trim();
+    return undefined;
+}
+function parsePositiveIntOption(val, label, fallback) {
+    if (val === undefined)
+        return fallback;
+    const parsed = parseInt(val, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        console.error(`[cli] Invalid ${label}="${val}", using default ${fallback}`);
+        return fallback;
+    }
+    return parsed;
 }
 function applyVerbose(opts) {
     if (opts.verbose)
@@ -131,119 +305,6 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         console.log(renderVerifyReport(r));
         process.exitCode = r.ok ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERIC_ERROR;
     });
-    // ── Built-in: explore / synthesize / generate / cascade ───────────────────
-    program
-        .command('explore')
-        .alias('probe')
-        .description('Explore a website: discover APIs, stores, and recommend strategies')
-        .argument('<url>')
-        .option('--site <name>')
-        .option('--goal <text>')
-        .option('--wait <s>', '', '3')
-        .option('--auto', 'Enable interactive fuzzing')
-        .option('--click <labels>', 'Comma-separated labels to click before fuzzing')
-        .option('-v, --verbose', 'Debug output')
-        .action(async (url, opts) => {
-        applyVerbose(opts);
-        const { exploreUrl, renderExploreSummary } = await import('./explore.js');
-        const clickLabels = opts.click
-            ? opts.click.split(',').map((s) => s.trim())
-            : undefined;
-        const workspace = `explore:${inferHost(url, opts.site)}`;
-        const result = await exploreUrl(url, {
-            BrowserFactory: getBrowserFactory(),
-            site: opts.site,
-            goal: opts.goal,
-            waitSeconds: parseFloat(opts.wait),
-            auto: opts.auto,
-            clickLabels,
-            workspace,
-        });
-        console.log(renderExploreSummary(result));
-    });
-    program
-        .command('synthesize')
-        .description('Synthesize CLIs from explore')
-        .argument('<target>')
-        .option('--top <n>', '', '3')
-        .option('-v, --verbose', 'Debug output')
-        .action(async (target, opts) => {
-        applyVerbose(opts);
-        const { synthesizeFromExplore, renderSynthesizeSummary } = await import('./synthesize.js');
-        console.log(renderSynthesizeSummary(synthesizeFromExplore(target, { top: parseInt(opts.top) })));
-    });
-    program
-        .command('generate')
-        .description('One-shot: explore → synthesize → verify → register')
-        .argument('<url>')
-        .option('--goal <text>')
-        .option('--site <name>')
-        .option('--format <fmt>', 'Output format: table, json', 'table')
-        .option('--no-register', 'Verify the generated adapter without registering it')
-        .option('-v, --verbose', 'Debug output')
-        .action(async (url, opts) => {
-        applyVerbose(opts);
-        const { generateVerifiedFromUrl, renderGenerateVerifiedSummary } = await import('./generate-verified.js');
-        const workspace = `generate:${inferHost(url, opts.site)}`;
-        const r = await generateVerifiedFromUrl({
-            url,
-            BrowserFactory: getBrowserFactory(),
-            goal: opts.goal,
-            site: opts.site,
-            workspace,
-            noRegister: opts.register === false,
-        });
-        if (opts.format === 'json')
-            console.log(JSON.stringify(r, null, 2));
-        else
-            console.log(renderGenerateVerifiedSummary(r));
-        process.exitCode = r.status === 'success' ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERIC_ERROR;
-    });
-    // ── Built-in: record ─────────────────────────────────────────────────────
-    program
-        .command('record')
-        .description('Record API calls from a live browser session → generate YAML candidates')
-        .argument('<url>', 'URL to open and record')
-        .option('--site <name>', 'Site name (inferred from URL if omitted)')
-        .option('--out <dir>', 'Output directory for candidates')
-        .option('--poll <ms>', 'Poll interval in milliseconds', '2000')
-        .option('--timeout <ms>', 'Auto-stop after N milliseconds (default: 60000)', '60000')
-        .option('-v, --verbose', 'Debug output')
-        .action(async (url, opts) => {
-        applyVerbose(opts);
-        const { recordSession, renderRecordSummary } = await import('./record.js');
-        const result = await recordSession({
-            BrowserFactory: getBrowserFactory(),
-            url,
-            site: opts.site,
-            outDir: opts.out,
-            pollMs: parseInt(opts.poll, 10),
-            timeoutMs: parseInt(opts.timeout, 10),
-        });
-        console.log(renderRecordSummary(result));
-        process.exitCode = result.candidateCount > 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.EMPTY_RESULT;
-    });
-    program
-        .command('cascade')
-        .description('Strategy cascade: find simplest working strategy')
-        .argument('<url>')
-        .option('--site <name>')
-        .option('-v, --verbose', 'Debug output')
-        .action(async (url, opts) => {
-        applyVerbose(opts);
-        const { cascadeProbe, renderCascadeResult } = await import('./cascade.js');
-        const workspace = `cascade:${inferHost(url, opts.site)}`;
-        const result = await browserSession(getBrowserFactory(), async (page) => {
-            try {
-                const siteUrl = new URL(url);
-                await page.goto(`${siteUrl.protocol}//${siteUrl.host}`);
-                await page.wait(2);
-            }
-            catch { }
-            return cascadeProbe(page, url);
-        }, { workspace });
-        console.log(renderCascadeResult(result));
-    });
     // ── Built-in: browser (browser control for Claude Code skill) ───────────────
     //
     // Make websites accessible for AI agents.
@@ -251,18 +312,58 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     const browser = program
         .command('browser')
         .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
-    /** Resolve a ref/CSS target via the unified resolver, throwing TargetError on failure. */
-    async function resolveRef(page, ref) {
-        const resolution = await page.evaluate(resolveTargetJs(ref));
+    /**
+     * Resolve a `<target>` (numeric ref or CSS selector) via the unified resolver.
+     * Returns the CSS match count so callers can propagate `matches_n` into the
+     * JSON envelope printed back to the agent.
+     */
+    async function resolveRef(page, ref, opts = {}) {
+        const resolution = await page.evaluate(resolveTargetJs(ref, opts));
         if (!resolution.ok) {
-            throw new TargetError(resolution);
+            throw new TargetError({
+                code: resolution.code,
+                message: resolution.message,
+                hint: resolution.hint,
+                candidates: resolution.candidates,
+                matches_n: resolution.matches_n,
+            });
+        }
+        return { matches_n: resolution.matches_n, match_level: resolution.match_level };
+    }
+    /**
+     * Parse `--nth <n>` flag, returning the parsed 0-based index or a usage error.
+     * The surface mirrors `--depth` etc. in `browser get html --as json`: the flag
+     * is optional, must be a non-negative integer when present, and on failure we
+     * emit the structured error envelope rather than throwing past the command.
+     */
+    function parseNthFlag(raw) {
+        if (raw === undefined || raw === null || raw === '')
+            return null;
+        const str = String(raw);
+        if (!/^\d+$/.test(str)) {
+            return { error: `--nth must be a non-negative integer, got "${str}"` };
         }
+        return Number.parseInt(str, 10);
+    }
+    /** Emit the `{ error: { code, message, hint?, candidates?, matches_n? } }` envelope used by the selector-first commands. */
+    function emitTargetError(err) {
+        console.log(JSON.stringify({
+            error: {
+                code: err.code,
+                message: err.message,
+                hint: err.hint,
+                ...(err.candidates && { candidates: err.candidates }),
+                ...(err.matches_n !== undefined && { matches_n: err.matches_n }),
+            },
+        }, null, 2));
     }
     /** Wrap browser actions with error handling and optional --json output */
     function browserAction(fn) {
         return async (...args) => {
             try {
-                const page = await getBrowserPage();
+                const command = args.at(-1) instanceof Command ? args.at(-1) : undefined;
+                const targetPage = getBrowserTargetId(command);
+                const page = await getBrowserPage(targetPage);
                 await fn(page, ...args);
             }
             catch (err) {
@@ -272,13 +373,11 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                         log.error(`Hint: ${err.hint}`);
                 }
                 else if (err instanceof TargetError) {
+                    // Agent-facing structured envelope on stdout + short human line on stderr.
+                    emitTargetError(err);
                     log.error(`[${err.code}] ${err.message}`);
                     if (err.hint)
                         log.error(`Hint: ${err.hint}`);
-                    if (err.candidates?.length) {
-                        log.error('Candidates:');
-                        err.candidates.forEach((c, i) => log.error(`  ${i + 1}. ${c}`));
-                    }
                 }
                 else {
                     const msg = getErrorMessage(err);
@@ -293,10 +392,77 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             }
         };
     }
+    const browserTab = browser
+        .command('tab')
+        .description('Tab management — list, create, and close tabs in the automation window');
+    browserTab.command('list')
+        .description('List tabs in the automation window with target IDs')
+        .action(browserAction(async (page) => {
+        const tabs = await page.tabs();
+        console.log(JSON.stringify(tabs, null, 2));
+    }));
+    browserTab.command('new')
+        .argument('[url]', 'Optional URL to open in the new tab')
+        .description('Create a new tab and print its target ID')
+        .action(browserAction(async (page, url) => {
+        if (!page.newTab) {
+            throw new Error('This browser session does not support creating tabs');
+        }
+        const createdPage = await page.newTab(url);
+        console.log(JSON.stringify({
+            page: createdPage,
+            url: url ?? null,
+        }, null, 2));
+    }));
+    addBrowserTabOption(browserTab.command('select')
+        .argument('[targetId]', 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"')
+        .description('Select a tab by target ID and make it the default browser tab'))
+        .action(browserAction(async (page, targetId, opts) => {
+        const resolvedTarget = resolveBrowserTabTarget(targetId, opts);
+        if (!resolvedTarget) {
+            throw new Error('Target tab required. Pass it as an argument or --tab <targetId>.');
+        }
+        await page.selectTab(resolvedTarget);
+        saveBrowserTargetState(resolvedTarget, DEFAULT_BROWSER_WORKSPACE);
+        console.log(JSON.stringify({ selected: resolvedTarget }, null, 2));
+    }));
+    addBrowserTabOption(browserTab.command('close')
+        .argument('[targetId]', 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"')
+        .description('Close a tab by target ID'))
+        .action(browserAction(async (page, targetId, opts) => {
+        const resolvedTarget = resolveBrowserTabTarget(targetId, opts);
+        if (!page.closeTab) {
+            throw new Error('This browser session does not support closing tabs');
+        }
+        if (!resolvedTarget) {
+            throw new Error('Target tab required. Pass it as an argument or --tab <targetId>.');
+        }
+        const validatedTarget = await resolveBrowserTargetInSession(page, resolvedTarget, {
+            scope: DEFAULT_BROWSER_WORKSPACE,
+            source: 'explicit',
+        });
+        if (!validatedTarget) {
+            throw new Error(`Target tab ${resolvedTarget} is not part of the current browser session.`);
+        }
+        await page.closeTab(validatedTarget);
+        if (loadBrowserTargetState(DEFAULT_BROWSER_WORKSPACE)?.defaultPage === validatedTarget) {
+            saveBrowserTargetState(undefined, DEFAULT_BROWSER_WORKSPACE);
+        }
+        console.log(JSON.stringify({ closed: validatedTarget }, null, 2));
+    }));
     // ── Navigation ──
-    /** Network interceptor JS — injected on every open/navigate to capture fetch/XHR */
-    const NETWORK_INTERCEPTOR_JS = `(function(){if(window.__opencli_net)return;window.__opencli_net=[];var M=200,B=50000,F=window.fetch;window.fetch=async function(){var r=await F.apply(this,arguments);try{var ct=r.headers.get('content-type')||'';if(ct.includes('json')||ct.includes('text')){var c=r.clone(),t=await c.text();if(window.__opencli_net.length<M){var b=null;if(t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:r.url||(arguments[0]&&arguments[0].url)||String(arguments[0]),method:(arguments[1]&&arguments[1].method)||'GET',status:r.status,size:t.length,ct:ct,body:b})}}}catch(e){}return r};var X=XMLHttpRequest.prototype,O=X.open,S=X.send;X.open=function(m,u){this._om=m;this._ou=u;return O.apply(this,arguments)};X.send=function(){var x=this;x.addEventListener('load',function(){try{var ct=x.getResponseHeader('content-type')||'';if((ct.includes('json')||ct.includes('text'))&&window.__opencli_net.length<M){var t=x.responseText,b=null;if(t&&t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:x._ou,method:x._om||'GET',status:x.status,size:t?t.length:0,ct:ct,body:b})}}catch(e){}});return S.apply(this,arguments)}})()`;
-    browser.command('open').argument('<url>').description('Open URL in automation window')
+    /**
+     * Network interceptor JS — injected on every open/navigate to capture
+     * fetch/XHR bodies when the session-level capture channel (CDP/extension)
+     * isn't available. Keeps parity with the CDP path's truncation contract:
+     * when a body exceeds the per-entry cap, we keep a string prefix and set
+     * `bodyTruncated: true` + `bodyFullSize: <original length>` so `browser
+     * network` can propagate a visible signal to the agent instead of
+     * silently dropping the body. Per-entry cap is 1 MiB and the ring is
+     * capped at 200 entries, bounding worst-case in-page memory.
+     */
+    const NETWORK_INTERCEPTOR_JS = `(function(){if(window.__opencli_net)return;window.__opencli_net=[];var M=200,B=1048576,F=window.fetch;function capture(url,method,status,text,ct){if(window.__opencli_net.length>=M)return;var full=text?text.length:0,trunc=full>B,stored=trunc?text.slice(0,B):text,body=null;if(stored){if(trunc){body=stored}else{try{body=JSON.parse(stored)}catch(e){body=stored}}}var e={url:url,method:method||'GET',status:status,size:full,ct:ct,body:body};if(trunc){e.bodyTruncated=true;e.bodyFullSize=full}window.__opencli_net.push(e)}window.fetch=async function(){var r=await F.apply(this,arguments);try{var ct=r.headers.get('content-type')||'';if(ct.includes('json')||ct.includes('text')){var c=r.clone(),t=await c.text();capture(r.url||(arguments[0]&&arguments[0].url)||String(arguments[0]),(arguments[1]&&arguments[1].method)||'GET',r.status,t,ct)}}catch(e){}return r};var X=XMLHttpRequest.prototype,O=X.open,S=X.send;X.open=function(m,u){this._om=m;this._ou=u;return O.apply(this,arguments)};X.send=function(){var x=this;x.addEventListener('load',function(){try{var ct=x.getResponseHeader('content-type')||'';if(ct.includes('json')||ct.includes('text')){capture(x._ou,x._om||'GET',x.status,x.responseText||'',ct)}}catch(e){}});return S.apply(this,arguments)}})()`;
+    addBrowserTabOption(browser.command('open').argument('<url>').description('Open URL in automation window'))
         .action(browserAction(async (page, url) => {
         // Start session-level capture before navigation (catches initial requests)
         const hasSessionCapture = await page.startNetworkCapture?.() ?? false;
@@ -309,15 +475,18 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             }
             catch { /* non-fatal */ }
         }
-        console.log(`Navigated to: ${await page.getCurrentUrl?.() ?? url}`);
+        console.log(JSON.stringify({
+            url: await page.getCurrentUrl?.() ?? url,
+            ...(page.getActivePage?.() ? { page: page.getActivePage?.() } : {}),
+        }, null, 2));
     }));
-    browser.command('back').description('Go back in browser history')
+    addBrowserTabOption(browser.command('back').description('Go back in browser history'))
         .action(browserAction(async (page) => {
         await page.evaluate('history.back()');
         await page.wait(2);
         console.log('Navigated back');
     }));
-    browser.command('scroll').argument('<direction>', 'up or down').option('--amount <pixels>', 'Pixels to scroll', '500')
+    addBrowserTabOption(browser.command('scroll').argument('<direction>', 'up or down').option('--amount <pixels>', 'Pixels to scroll', '500'))
         .description('Scroll page')
         .action(browserAction(async (page, direction, opts) => {
         if (direction !== 'up' && direction !== 'down') {
@@ -329,14 +498,19 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         console.log(`Scrolled ${direction}`);
     }));
     // ── Inspect ──
-    browser.command('state').description('Page state: URL, title, interactive elements with [N] indices')
+    addBrowserTabOption(browser.command('state').description('Page state: URL, title, interactive elements with [N] indices'))
         .action(browserAction(async (page) => {
         const snapshot = await page.snapshot({ viewportExpand: 2000 });
         const url = await page.getCurrentUrl?.() ?? '';
         console.log(`URL: ${url}\n`);
         console.log(typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2));
     }));
-    browser.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)')
+    addBrowserTabOption(browser.command('frames').description('List cross-origin iframe targets in snapshot order'))
+        .action(browserAction(async (page) => {
+        const frames = await page.frames?.() ?? [];
+        console.log(JSON.stringify(frames, null, 2));
+    }));
+    addBrowserTabOption(browser.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)'))
         .description('Take screenshot')
         .action(browserAction(async (page, path) => {
         if (path) {
@@ -347,84 +521,335 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             console.log(await page.screenshot({ format: 'png' }));
         }
     }));
+    // ── Find (structured CSS query, agent-native) ──
+    //
+    // `browser find --css <sel>` lets agents jump straight from a semantic
+    // selector to a JSON list of matching elements, without having to parse
+    // the free-text state snapshot to recover indices.
+    addBrowserTabOption(browser.command('find')
+        .option('--css <selector>', 'CSS selector (required)')
+        .option('--limit <n>', 'Max entries returned', '50')
+        .option('--text-max <n>', 'Max chars of trimmed text per entry', '120')
+        .description('Find DOM elements by CSS selector — returns JSON {matches_n, entries[]}'))
+        .action(browserAction(async (page, opts) => {
+        if (!opts.css || typeof opts.css !== 'string') {
+            console.log(JSON.stringify({
+                error: {
+                    code: 'usage_error',
+                    message: '--css <selector> is required',
+                    hint: 'Example: opencli browser find --css ".btn.primary"',
+                },
+            }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const limit = parseNthFlag(opts.limit);
+        if (limit && typeof limit === 'object' && 'error' in limit) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: limit.error.replace('--nth', '--limit') } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const textMax = parseNthFlag(opts.textMax);
+        if (textMax && typeof textMax === 'object' && 'error' in textMax) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: textMax.error.replace('--nth', '--text-max') } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const result = await page.evaluate(buildFindJs(opts.css, {
+            limit: limit ?? undefined,
+            textMax: textMax ?? undefined,
+        }));
+        if (isFindError(result)) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
+            return;
+        }
+        console.log(JSON.stringify(result, null, 2));
+    }));
     // ── Get commands (structured data extraction) ──
     const get = browser.command('get').description('Get page properties');
-    get.command('title').description('Page title')
+    addBrowserTabOption(get.command('title').description('Page title'))
         .action(browserAction(async (page) => {
         console.log(await page.evaluate('document.title'));
     }));
-    get.command('url').description('Current page URL')
+    addBrowserTabOption(get.command('url').description('Current page URL'))
         .action(browserAction(async (page) => {
         console.log(await page.getCurrentUrl?.() ?? await page.evaluate('location.href'));
     }));
-    get.command('text').argument('<index>', 'Element index').description('Element text content')
-        .action(browserAction(async (page, index) => {
-        await resolveRef(page, String(index));
-        const text = await page.evaluate(getTextResolvedJs());
-        console.log(text ?? '(empty)');
-    }));
-    get.command('value').argument('<index>', 'Element index').description('Input/textarea value')
-        .action(browserAction(async (page, index) => {
-        await resolveRef(page, String(index));
-        const val = await page.evaluate(getValueResolvedJs());
-        console.log(val ?? '(empty)');
-    }));
-    get.command('html').option('--selector <css>', 'CSS selector scope').description('Page HTML (or scoped)')
+    // Read commands (`get text/value/attributes`) always emit a JSON envelope:
+    //
+    //   { value, matches_n }                           — success
+    //   { error: { code, message, hint, matches_n? } } — structured failure
+    //
+    // `<target>` accepts either a numeric ref (from `browser state`/`browser find`)
+    // or a CSS selector. On multi-match CSS, the first element wins and the real
+    // match count is exposed via `matches_n`; `--nth <n>` picks a specific one.
+    const runGetCommand = async (page, target, opts, evalJs, field) => {
+        const nth = parseNthFlag(opts.nth);
+        if (nth && typeof nth === 'object' && 'error' in nth) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: nth.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { matches_n, match_level } = await resolveRef(page, String(target), {
+            firstOnMulti: nth === null,
+            ...(typeof nth === 'number' ? { nth } : {}),
+        });
+        const raw = await page.evaluate(evalJs);
+        let value;
+        if (field === 'attributes') {
+            // getAttributesResolvedJs stringifies the attribute record — parse it back so
+            // the JSON envelope contains a real object rather than a nested JSON string.
+            try {
+                value = raw == null ? {} : JSON.parse(String(raw));
+            }
+            catch {
+                value = raw;
+            }
+        }
+        else {
+            value = raw ?? null;
+        }
+        console.log(JSON.stringify({ value, matches_n, match_level }, null, 2));
+    };
+    addBrowserTabOption(get.command('text')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
+        .description('Element text content — JSON envelope {value, matches_n}'))
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getTextResolvedJs(), 'text')));
+    addBrowserTabOption(get.command('value')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
+        .description('Input/textarea value — JSON envelope {value, matches_n}'))
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getValueResolvedJs(), 'value')));
+    addBrowserTabOption(get.command('html')
+        .option('--selector <css>', 'CSS selector scope (first match)')
+        .option('--as <format>', 'Output format: "html" (default) or "json" for structured tree', 'html')
+        .option('--max <n>', 'Max characters of raw HTML to return (0 = unlimited)', '0')
+        .option('--depth <n>', '(--as json) Max tree depth below root (0 = root only, 0 disables = unlimited via empty)', '')
+        .option('--children-max <n>', '(--as json) Max element children kept per node (empty = unlimited)', '')
+        .option('--text-max <n>', '(--as json) Max chars of direct text kept per node (empty = unlimited)', '')
+        .description('Page HTML (or scoped); use --as json for a {tag, attrs, text, children} tree'))
         .action(browserAction(async (page, opts) => {
+        const format = String(opts.as || 'html').toLowerCase();
+        if (format !== 'html' && format !== 'json') {
+            console.log(JSON.stringify({ error: { code: 'invalid_format', message: `--as must be "html" or "json", got "${opts.as}"` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        // `--max` is validated up-front (before touching the page) so a bad value
+        // gets the same structured error regardless of selector/format path.
+        const rawMax = String(opts.max ?? '0');
+        if (!/^\d+$/.test(rawMax)) {
+            console.log(JSON.stringify({ error: { code: 'invalid_max', message: `--max must be a non-negative integer, got "${opts.max}"` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const max = Number.parseInt(rawMax, 10);
+        if (format === 'json') {
+            const parseBudget = (flag, value) => {
+                const raw = value === undefined || value === null ? '' : String(value);
+                if (raw === '')
+                    return null;
+                if (!/^\d+$/.test(raw))
+                    return { error: `${flag} must be a non-negative integer, got "${raw}"` };
+                return Number.parseInt(raw, 10);
+            };
+            const depth = parseBudget('--depth', opts.depth);
+            const childrenMax = parseBudget('--children-max', opts.childrenMax);
+            const textMax = parseBudget('--text-max', opts.textMax);
+            for (const budget of [depth, childrenMax, textMax]) {
+                if (budget && typeof budget === 'object' && 'error' in budget) {
+                    console.log(JSON.stringify({ error: { code: 'invalid_budget', message: budget.error } }, null, 2));
+                    process.exitCode = EXIT_CODES.USAGE_ERROR;
+                    return;
+                }
+            }
+            const js = buildHtmlTreeJs({
+                selector: opts.selector ?? null,
+                depth: depth,
+                childrenMax: childrenMax,
+                textMax: textMax,
+            });
+            const result = await page.evaluate(js);
+            if (result && typeof result === 'object' && 'invalidSelector' in result && result.invalidSelector) {
+                console.log(JSON.stringify({
+                    error: { code: 'invalid_selector', message: `Selector "${opts.selector}" is not a valid CSS selector: ${result.reason}` },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            const ok = result;
+            if (!ok || ok.matched === 0) {
+                console.log(JSON.stringify({
+                    error: {
+                        code: 'selector_not_found',
+                        message: opts.selector
+                            ? `Selector "${opts.selector}" matched 0 elements.`
+                            : 'Page has no documentElement.',
+                    },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            console.log(JSON.stringify(ok, null, 2));
+            return;
+        }
+        // Raw HTML path — unbounded by default; --max optionally caps with a visible marker.
+        // Selector lookup is wrapped in try/catch inside page context so an invalid
+        // selector returns a structured signal instead of throwing through page.evaluate.
         const sel = opts.selector ? JSON.stringify(opts.selector) : 'null';
-        const html = await page.evaluate(`(${sel} ? document.querySelector(${sel})?.outerHTML : document.documentElement.outerHTML)?.slice(0, 50000)`);
-        console.log(html ?? '(empty)');
-    }));
-    get.command('attributes').argument('<index>', 'Element index').description('Element attributes')
-        .action(browserAction(async (page, index) => {
-        await resolveRef(page, String(index));
-        const attrs = await page.evaluate(getAttributesResolvedJs());
-        console.log(attrs ?? '{}');
+        const rawResult = await page.evaluate(`(() => {
+          const s = ${sel};
+          if (s) {
+            try {
+              const el = document.querySelector(s);
+              return { kind: 'ok', html: el ? el.outerHTML : null };
+            } catch (e) {
+              return { kind: 'invalid_selector', reason: (e && e.message) || String(e) };
+            }
+          }
+          return { kind: 'ok', html: document.documentElement ? document.documentElement.outerHTML : null };
+        })()`);
+        if (rawResult.kind === 'invalid_selector') {
+            console.log(JSON.stringify({
+                error: { code: 'invalid_selector', message: `Selector "${opts.selector}" is not a valid CSS selector: ${rawResult.reason}` },
+            }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const html = rawResult.html;
+        if (html === null) {
+            if (opts.selector) {
+                console.log(JSON.stringify({
+                    error: { code: 'selector_not_found', message: `Selector "${opts.selector}" matched 0 elements.` },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            console.log('(empty)');
+            return;
+        }
+        if (max > 0 && html.length > max) {
+            console.log(`<!-- opencli: truncated ${max} of ${html.length} chars; re-run without --max (or --max 0) for full -->\n${html.slice(0, max)}`);
+            return;
+        }
+        console.log(html);
     }));
+    addBrowserTabOption(get.command('attributes')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
+        .description('Element attributes — JSON envelope {value, matches_n}'))
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getAttributesResolvedJs(), 'attributes')));
     // ── Interact ──
-    browser.command('click').argument('<index>', 'Element index from state').description('Click element by index')
-        .action(browserAction(async (page, index) => {
-        await page.click(index);
-        console.log(`Clicked element [${index}]`);
+    //
+    // Write commands (`click/type/select`) share the same `<target>` contract
+    // as the read commands but *reject* multi-match CSS as `selector_ambiguous`
+    // unless the caller passes `--nth <n>`. That asymmetry is intentional:
+    // clicking "one of three buttons" at random is almost never what the agent
+    // meant. Every branch emits a JSON envelope on stdout; error envelopes go
+    // through the unified TargetError handler in browserAction.
+    /**
+     * Parse the `--nth` flag and convert it to `ResolveOptions`.
+     * Returns `{ error }` when the flag was malformed (so the command can
+     * print the structured usage error and exit) or `{ opts }` to feed
+     * into resolveRef / page.click / page.typeText.
+     */
+    function nthToResolveOpts(raw) {
+        const parsed = parseNthFlag(raw);
+        if (parsed && typeof parsed === 'object' && 'error' in parsed)
+            return parsed;
+        if (typeof parsed === 'number')
+            return { opts: { nth: parsed } };
+        return { opts: {} };
+    }
+    addBrowserTabOption(browser.command('click')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Click element — JSON envelope {clicked, target, matches_n}'))
+        .action(browserAction(async (page, target, opts) => {
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { matches_n, match_level } = await page.click(String(target), parsed.opts);
+        console.log(JSON.stringify({ clicked: true, target: String(target), matches_n, match_level }, null, 2));
     }));
-    browser.command('type').argument('<index>', 'Element index').argument('<text>', 'Text to type')
-        .description('Click element, then type text')
-        .action(browserAction(async (page, index, text) => {
-        await page.click(index);
+    addBrowserTabOption(browser.command('type')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .argument('<text>', 'Text to type')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Click element, then type text — JSON envelope {typed, text, target, matches_n, autocomplete}'))
+        .action(browserAction(async (page, target, text, opts) => {
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        // Click first (focuses the field), wait briefly, then type.
+        await page.click(String(target), parsed.opts);
         await page.wait(0.3);
-        await page.typeText(index, text);
-        // Detect autocomplete/combobox fields and wait for dropdown suggestions
-        // __resolved is already set by typeText's resolver call
+        const { matches_n, match_level } = await page.typeText(String(target), String(text), parsed.opts);
+        // __resolved is already set by the resolver call inside page.typeText
         const isAutocomplete = await page.evaluate(isAutocompleteResolvedJs());
-        if (isAutocomplete) {
+        if (isAutocomplete)
             await page.wait(0.4);
-            console.log(`Typed "${text}" into autocomplete [${index}] — use state to see suggestions`);
-        }
-        else {
-            console.log(`Typed "${text}" into element [${index}]`);
-        }
+        console.log(JSON.stringify({
+            typed: true,
+            text: String(text),
+            target: String(target),
+            matches_n,
+            match_level,
+            autocomplete: !!isAutocomplete,
+        }, null, 2));
     }));
-    browser.command('select').argument('<index>', 'Element index of <select>').argument('<option>', 'Option text')
-        .description('Select dropdown option')
-        .action(browserAction(async (page, index, option) => {
-        await resolveRef(page, String(index));
-        const result = await page.evaluate(selectResolvedJs(option));
+    addBrowserTabOption(browser.command('select')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector of a <select> element')
+        .argument('<option>', 'Option text (or value) to select')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Select dropdown option — JSON envelope {selected, target, matches_n}'))
+        .action(browserAction(async (page, target, option, opts) => {
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { matches_n, match_level } = await resolveRef(page, String(target), parsed.opts);
+        const result = await page.evaluate(selectResolvedJs(String(option)));
         if (result?.error) {
-            console.error(`Error: ${result.error}${result.available ? ` — Available: ${result.available.join(', ')}` : ''}`);
+            // The select-specific "Not a <select>" / "Option not found" errors
+            // are domain-level failures — emit a structured envelope so agents
+            // can branch on code rather than scrape a log line.
+            console.log(JSON.stringify({
+                error: {
+                    code: result.error === 'Not a <select>' ? 'not_a_select' : 'option_not_found',
+                    message: result.error,
+                    ...(result.available && { available: result.available }),
+                    matches_n,
+                },
+            }, null, 2));
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
+            return;
         }
-        else {
-            console.log(`Selected "${result?.selected}" in element [${index}]`);
-        }
+        console.log(JSON.stringify({
+            selected: result?.selected ?? String(option),
+            target: String(target),
+            matches_n,
+            match_level,
+        }, null, 2));
     }));
-    browser.command('keys').argument('<key>', 'Key to press (Enter, Escape, Tab, Control+a)')
+    addBrowserTabOption(browser.command('keys').argument('<key>', 'Key to press (Enter, Escape, Tab, Control+a)'))
         .description('Press keyboard key')
         .action(browserAction(async (page, key) => {
         await page.pressKey(key);
         console.log(`Pressed: ${key}`);
     }));
     // ── Wait commands ──
-    browser.command('wait')
+    addBrowserTabOption(browser.command('wait'))
         .argument('<type>', 'selector, text, or time')
         .argument('[value]', 'CSS selector, text string, or seconds')
         .option('--timeout <ms>', 'Timeout in milliseconds', '10000')
@@ -460,94 +885,258 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         }
     }));
     // ── Extract ──
-    browser.command('eval').argument('<js>', 'JavaScript code').description('Execute JS in page context, return result')
-        .action(browserAction(async (page, js) => {
-        const result = await page.evaluate(js);
+    addBrowserTabOption(browser.command('eval')
+        .argument('<js>', 'JavaScript code')
+        .option('--frame <index>', 'Cross-origin iframe index from "browser frames"')
+        .description('Execute JS in page context, return result'))
+        .action(browserAction(async (page, js, opts) => {
+        let result;
+        if (opts.frame !== undefined) {
+            const frameIndex = Number.parseInt(opts.frame, 10);
+            if (!Number.isInteger(frameIndex) || frameIndex < 0) {
+                console.error(`Invalid frame index "${opts.frame}". Use a 0-based index from "browser frames".`);
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            if (!page.evaluateInFrame) {
+                throw new Error('This browser session does not support frame-targeted evaluation');
+            }
+            result = await page.evaluateInFrame(js, frameIndex);
+        }
+        else {
+            result = await page.evaluate(js);
+        }
         if (typeof result === 'string')
             console.log(result);
         else
             console.log(JSON.stringify(result, null, 2));
     }));
+    // ── Extract (content reading) ──
+    //
+    // `extract` answers the "read this page" question that `get html` / `get text`
+    // can't: denoise → markdown → paragraph-aware chunking. Agents walk long pages
+    // by passing back the `next_start_char` cursor instead of juggling selectors.
+    addBrowserTabOption(browser.command('extract')
+        .option('--selector <css>', 'CSS selector scope; defaults to <main>/<article>/<body>')
+        .option('--chunk-size <chars>', 'Target chunk size in chars', '20000')
+        .option('--start <char>', 'Start offset (use next_start_char from a previous extract)', '0')
+        .description('Extract page content as markdown, paragraph-aware chunks for long pages'))
+        .action(browserAction(async (page, opts) => {
+        const rawChunk = String(opts.chunkSize ?? '20000');
+        if (!/^\d+$/.test(rawChunk) || Number.parseInt(rawChunk, 10) <= 0) {
+            console.log(JSON.stringify({ error: { code: 'invalid_chunk_size', message: `--chunk-size must be a positive integer, got "${opts.chunkSize}"` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const rawStart = String(opts.start ?? '0');
+        if (!/^\d+$/.test(rawStart)) {
+            console.log(JSON.stringify({ error: { code: 'invalid_start', message: `--start must be a non-negative integer, got "${opts.start}"` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const chunkSize = Number.parseInt(rawChunk, 10);
+        const start = Number.parseInt(rawStart, 10);
+        const selector = typeof opts.selector === 'string' && opts.selector.length > 0 ? opts.selector : null;
+        const js = buildExtractHtmlJs(selector);
+        const res = await page.evaluate(js);
+        if (!res) {
+            console.log(JSON.stringify({ error: { code: 'extract_failed', message: 'Page returned no root element.' } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        if ('invalidSelector' in res) {
+            console.log(JSON.stringify({ error: { code: 'invalid_selector', message: `Selector "${selector}" is not a valid CSS selector: ${res.reason}` } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        if ('notFound' in res) {
+            console.log(JSON.stringify({ error: { code: 'selector_not_found', message: selector ? `Selector "${selector}" matched 0 elements.` : 'Page has no body/main/article element.' } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const envelope = runExtractFromHtml({
+            html: res.html,
+            url: res.url,
+            title: res.title,
+            selector,
+            start,
+            chunkSize,
+        });
+        console.log(JSON.stringify(envelope, null, 2));
+    }));
     // ── Network (API discovery) ──
-    browser.command('network')
-        .option('--detail <index>', 'Show full response body of request at index')
-        .option('--all', 'Show all requests including static resources')
-        .description('Show captured network requests (auto-captured since last open)')
+    //
+    // Default output is JSON (agent-native). Each entry carries a stable `key`
+    // (GraphQL operationName or `METHOD host+pathname`) so agents can fetch
+    // full bodies with `--detail <key>` even after subsequent commands.
+    // Captures are persisted per workspace under ~/.opencli/cache/browser-network/.
+    addBrowserTabOption(browser.command('network'))
+        .option('--detail <key>', 'Emit full body for the entry with this key')
+        .option('--all', 'Include static resources (js/css/images/telemetry)')
+        .option('--raw', 'Emit full bodies for every entry (skip shape preview)')
+        .option('--filter <fields>', 'Comma-separated field names; keep only entries whose body shape has ALL names as path segments')
+        .option('--max-body <chars>', 'With --detail: cap the emitted body at N chars (0 = unlimited, default)', '0')
+        .option('--ttl <ms>', 'Cache TTL in ms for --detail lookups', String(DEFAULT_TTL_MS))
+        .description('Capture network requests as shape previews; retrieve full bodies by key')
         .action(browserAction(async (page, opts) => {
-        let items = [];
-        if (page.readNetworkCapture) {
-            const raw = await page.readNetworkCapture();
-            // Normalize daemon/CDP capture entries to __opencli_net shape.
-            // Daemon returns: responseStatus, responseContentType, responsePreview
-            // CDP returns the same shape after PR A fix.
-            items = raw.map(e => {
-                const preview = e.responsePreview ?? null;
-                let body = null;
-                if (preview) {
-                    try {
-                        body = JSON.parse(preview);
-                    }
-                    catch {
-                        body = preview;
-                    }
-                }
-                return {
-                    url: e.url || '',
-                    method: e.method || 'GET',
-                    status: e.responseStatus || 0,
-                    size: preview ? preview.length : 0,
-                    ct: e.responseContentType || '',
-                    body,
-                };
-            });
+        const ttlMs = parsePositiveIntOption(opts.ttl, 'ttl', DEFAULT_TTL_MS);
+        const workspace = DEFAULT_BROWSER_WORKSPACE;
+        const hasDetail = typeof opts.detail === 'string' && opts.detail.length > 0;
+        const hasFilter = typeof opts.filter === 'string';
+        // --detail and --filter do different things (one request by key vs. narrow
+        // the list by shape), don't compose, and combining them has no sensible
+        // semantic. Reject up front with a structured error instead of silently
+        // dropping one.
+        if (hasDetail && hasFilter) {
+            emitNetworkError('invalid_args', '--filter and --detail cannot be used together (one narrows a list, the other fetches a specific entry).');
+            return;
         }
-        else {
-            // Fallback to JS interceptor data
-            const requests = await page.evaluate(`(function(){
-          var reqs = window.__opencli_net || [];
-          return JSON.stringify(reqs);
-        })()`);
-            try {
-                items = JSON.parse(requests);
+        let filterFields = null;
+        if (hasFilter) {
+            const parsed = parseFilter(opts.filter);
+            if ('reason' in parsed) {
+                emitNetworkError('invalid_filter', parsed.reason);
+                return;
             }
-            catch {
-                console.log('No network data captured. Run "browser open <url>" first.');
+            filterFields = parsed.fields;
+        }
+        // --detail short-circuits: read from cache only, no live capture needed.
+        if (hasDetail) {
+            const res = loadNetworkCache(workspace, { ttlMs });
+            if (res.status === 'missing') {
+                emitNetworkError('cache_missing', `No cached capture. Run "browser network" first (in workspace "${workspace}").`);
+                return;
+            }
+            if (res.status === 'expired') {
+                emitNetworkError('cache_expired', `Cache is stale (age ${res.ageMs}ms > ttl ${ttlMs}ms). Re-run "browser network" to refresh.`);
+                return;
+            }
+            if (res.status === 'corrupt' || !res.file) {
+                emitNetworkError('cache_corrupt', 'Cache file is malformed; re-run "browser network" to regenerate.');
+                return;
+            }
+            const entry = findEntry(res.file, opts.detail);
+            if (!entry) {
+                emitNetworkError('key_not_found', `Key "${opts.detail}" not in cache.`, {
+                    available_keys: res.file.entries.map((e) => e.key),
+                });
                 return;
             }
+            const rawMaxBody = String(opts.maxBody ?? '0');
+            if (!/^\d+$/.test(rawMaxBody)) {
+                emitNetworkError('invalid_max_body', `--max-body must be a non-negative integer, got "${opts.maxBody}"`);
+                return;
+            }
+            const maxBody = Number.parseInt(rawMaxBody, 10);
+            // Body shape/source:
+            // - If capture already truncated it (entry.body_truncated), the body is a string.
+            // - If the adapter stored a JSON value, it parsed cleanly at capture time; leave it.
+            // - --max-body applies a transport-level cap when the caller wants to keep output small.
+            let outputBody = entry.body;
+            let transportTruncated = false;
+            if (maxBody > 0 && typeof entry.body === 'string' && entry.body.length > maxBody) {
+                outputBody = entry.body.slice(0, maxBody);
+                transportTruncated = true;
+            }
+            const captureTruncated = entry.body_truncated === true;
+            const detailEnvelope = {
+                key: entry.key,
+                url: entry.url,
+                method: entry.method,
+                status: entry.status,
+                ct: entry.ct,
+                size: entry.size,
+                shape: inferShape(entry.body),
+                body: outputBody,
+            };
+            if (captureTruncated || transportTruncated) {
+                detailEnvelope.body_truncated = true;
+                detailEnvelope.body_full_size = entry.body_full_size ?? entry.size;
+                detailEnvelope.body_truncation_reason = captureTruncated
+                    ? 'capture-limit'
+                    : 'max-body';
+            }
+            console.log(JSON.stringify(detailEnvelope, null, 2));
+            return;
+        }
+        // Fresh capture path.
+        let rawItems;
+        try {
+            rawItems = await captureNetworkItems(page);
         }
-        if (items.length === 0) {
-            console.log('No requests captured.');
+        catch (err) {
+            emitNetworkError('capture_failed', `Could not read network capture: ${err.message}`);
             return;
         }
-        // Filter out static resources unless --all
-        if (!opts.all) {
-            items = items.filter(r => (r.ct?.includes('json') || r.ct?.includes('xml') || r.ct?.includes('text/plain')) &&
-                !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
-                !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url));
-        }
-        if (opts.detail !== undefined) {
-            const idx = parseInt(opts.detail, 10);
-            const req = items[idx];
-            if (!req) {
-                console.error(`Request #${idx} not found. ${items.length} requests available.`);
-                process.exitCode = EXIT_CODES.USAGE_ERROR;
-                return;
-            }
-            console.log(`${req.method} ${req.url}`);
-            console.log(`Status: ${req.status} | Size: ${req.size} | Type: ${req.ct}`);
-            console.log('---');
-            console.log(typeof req.body === 'string' ? req.body : JSON.stringify(req.body, null, 2));
+        const items = opts.all ? rawItems : filterNetworkItems(rawItems);
+        const filteredOut = rawItems.length - items.length;
+        const keyed = assignKeys(items);
+        const cacheEntries = keyed.map((it) => ({
+            key: it.key,
+            url: it.url,
+            method: it.method,
+            status: it.status,
+            size: it.size,
+            ct: it.ct,
+            body: it.body,
+            ...(it.bodyTruncated ? { body_truncated: true } : {}),
+            ...(it.bodyTruncated && typeof it.bodyFullSize === 'number'
+                ? { body_full_size: it.bodyFullSize }
+                : {}),
+        }));
+        // Soft failure: the caller already has the data, so surface a warning
+        // via the output envelope rather than erroring out the whole command.
+        let cacheWarning = null;
+        try {
+            saveNetworkCache(workspace, cacheEntries);
+        }
+        catch (err) {
+            cacheWarning = `Could not persist capture cache: ${err.message}. --detail lookups may miss this capture.`;
+        }
+        // Pair each cache entry with its shape up front so --filter can read
+        // segments without recomputing, and the --raw view can keep the full
+        // body. Cache persistence above stored the unfiltered set on purpose:
+        // later `--detail <key>` lookups must still see requests that the
+        // current --filter narrowed out.
+        const shaped = cacheEntries.map((e) => ({ entry: e, shape: inferShape(e.body) }));
+        const visible = filterFields
+            ? shaped.filter((s) => shapeMatchesFilter(s.shape, filterFields))
+            : shaped;
+        const filterDropped = filterFields ? shaped.length - visible.length : 0;
+        const envelope = {
+            workspace,
+            captured_at: new Date().toISOString(),
+            count: visible.length,
+            filtered_out: filteredOut,
+        };
+        if (filterFields) {
+            envelope.filter = filterFields;
+            envelope.filter_dropped = filterDropped;
+        }
+        if (cacheWarning)
+            envelope.cache_warning = cacheWarning;
+        const truncatedCount = visible.filter((s) => s.entry.body_truncated).length;
+        if (truncatedCount > 0) {
+            envelope.body_truncated_count = truncatedCount;
+            envelope.body_truncated_hint = 'Some bodies exceeded the capture limit; their `shape` reflects only the captured prefix.';
+        }
+        if (opts.raw) {
+            envelope.entries = visible.map((s) => s.entry);
         }
         else {
-            console.log(`Captured ${items.length} API requests:\n`);
-            items.forEach((r, i) => {
-                const bodyPreview = r.body ? (typeof r.body === 'string' ? r.body.slice(0, 60) : JSON.stringify(r.body).slice(0, 60)) : '';
-                console.log(`  [${i}] ${r.method} ${r.status} ${r.url.slice(0, 80)}`);
-                if (bodyPreview)
-                    console.log(`      ${bodyPreview}...`);
-            });
-            console.log(`\nUse --detail <index> to see full response body.`);
+            envelope.entries = visible.map((s) => ({
+                key: s.entry.key,
+                method: s.entry.method,
+                status: s.entry.status,
+                url: s.entry.url,
+                ct: s.entry.ct,
+                size: s.entry.size,
+                shape: s.shape,
+                ...(s.entry.body_truncated ? { body_truncated: true } : {}),
+            }));
+            envelope.detail_hint = 'Run "browser network --detail <key>" for full body.';
         }
+        console.log(JSON.stringify(envelope, null, 2));
     }));
     // ── Init (adapter scaffolding) ──
     browser.command('init')
@@ -1071,10 +1660,14 @@ cli({
         .command('serve')
         .description('Start Anthropic-compatible API proxy for Antigravity')
         .option('--port <port>', 'Server port (default: 8082)', '8082')
+        .option('--timeout <seconds>', 'Maximum time to wait for a reply (default: 120s)')
         .action(async (opts) => {
         // @ts-expect-error JS adapter — no type declarations
         const { startServe } = await import('../clis/antigravity/serve.js');
-        await startServe({ port: parseInt(opts.port) });
+        await startServe({
+            port: parseInt(opts.port, 10),
+            timeout: opts.timeout ? parsePositiveIntOption(opts.timeout, '--timeout', 120) : undefined,
+        });
     });
     // ── Dynamic adapter commands ──────────────────────────────────────────────
     const siteGroups = new Map();
@@ -1132,14 +1725,3 @@ export function resolveBrowserVerifyInvocation(opts = {}) {
         ...(platform === 'win32' ? { shell: true } : {}),
     };
 }
-/** Infer a workspace-friendly hostname from a URL, with site override. */
-function inferHost(url, site) {
-    if (site)
-        return site;
-    try {
-        return new URL(url).host;
-    }
-    catch {
-        return 'default';
-    }
-}