@jackwener/opencli 1.7.5 → 1.7.6

package/dist/src/cli.js

@@ -21,11 +21,74 @@ 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');
 }
@@ -249,12 +312,50 @@ 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) {
@@ -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);
@@ -352,8 +451,17 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         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)}})()`;
+    /**
+     * 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)
@@ -413,6 +521,51 @@ 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');
     addBrowserTabOption(get.command('title').description('Page title'))
@@ -423,65 +576,271 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         .action(browserAction(async (page) => {
         console.log(await page.getCurrentUrl?.() ?? await page.evaluate('location.href'));
     }));
-    addBrowserTabOption(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)');
-    }));
-    addBrowserTabOption(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)');
-    }));
-    addBrowserTabOption(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)');
-    }));
-    addBrowserTabOption(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 ──
-    addBrowserTabOption(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));
     }));
-    addBrowserTabOption(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));
     }));
-    addBrowserTabOption(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));
     }));
     addBrowserTabOption(browser.command('keys').argument('<key>', 'Key to press (Enter, Escape, Tab, Control+a)'))
         .description('Press keyboard key')
@@ -552,86 +911,232 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         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) ──
+    //
+    // 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 <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)')
+        .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);
         }
-        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.`);
+        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 {
+            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')