Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

96.4 KB
Raw Blame
import { Command, InvalidArgumentError } from 'commander';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from '../browser/config.js';
import { bindTab, BrowserCommandError, sendCommand } from '../browser/daemon-client.js';
import { buildExtractHtmlJs, runExtractFromHtml } from '../browser/extract.js';
import { buildFindJs, buildSemanticFindJs, isFindError, type FindError, type FindResult, type SemanticFindOptions } from '../browser/find.js';
import { buildHtmlTreeJs, type HtmlTreeResult } from '../browser/html-tree.js';
import { DEFAULT_TTL_MS, findEntry, loadNetworkCache, saveNetworkCache, type CachedNetworkEntry } from '../browser/network-cache.js';
import { NETWORK_INTERCEPTOR_JS } from '../browser/network-interceptor.js';
import { assignKeys } from '../browser/network-key.js';
import { sanitizeCapturedRequest, sanitizeCapturedUrl, type SafeNetworkRequest } from '../browser/network-request.js';
import { profileRouteParams, resolveProfileSelection, type ProfileSelection } from '../browser/profile.js';
import { parseFilter, shapeMatchesFilter } from '../browser/shape-filter.js';
import { inferShape } from '../browser/shape.js';
import { TargetError, type TargetErrorCode } from '../browser/target-errors.js';
import { getAttributesResolvedJs, getTextResolvedJs, getValueResolvedJs, isAutocompleteResolvedJs, resolveTargetJs, selectResolvedJs, type ResolveOptions, type TargetMatchLevel } from '../browser/target-resolver.js';
import { EXIT_CODES, getErrorMessage } from '../errors.js';
import { installCommanderNamespaceStructuredHelp } from '../help.js';
import { log } from '../logger.js';
import type { BrowserWindowMode } from '../runtime.js';
import type { BrowserDownloadWaitResult, IPage, ScreenshotOptions } from '../types.js';


import { emitHook, type HookContext } from '../hooks.js';
import { captureCommandOutput, type CommandOutputCapture, emitFailure, emitResult } from '../command-output.js';
const BROWSER_TAB_OPTION_DESCRIPTION = 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"';
const FOLLOW_POLL_MS = 1_000;

type BrowserNetworkItem = {
  url: string;
  method: string;
  status: number;
  size: number;
  ct: string;
  body: unknown;
  /** Full body size in chars before any capture-layer truncation. */
  bodyFullSize?: number;
  /** True when the capture layer had to cap the stored body to protect memory. */
  bodyTruncated?: boolean;
  /** Epoch milliseconds when the request was observed. */
  timestamp?: number;
  /** Sanitized request context captured by CDP. */
  request?: SafeNetworkRequest;
};

function parseDurationMs(raw: unknown, flagName: string): number | null | { error: string } {
  if (raw === undefined || raw === null || raw === '') return null;
  const str = String(raw).trim();
  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(str);
  if (!match) return { error: `--${flagName} must be a duration like 500ms, 30s, 2m, got "${str}"` };
  const value = Number.parseFloat(match[1]);
  const unit = match[2] ?? 'ms';
  const multiplier = unit === 'h' ? 3_600_000 : unit === 'm' ? 60_000 : unit === 's' ? 1_000 : 1;
  return Math.round(value * multiplier);
}

function timestampFromRaw(value: unknown): number {
  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : Date.now();
}

function toIsoTimestamp(timestamp: unknown): string | undefined {
  if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0) return undefined;
  return new Date(timestamp).toISOString();
}

function filterByTimeWindow<T extends { timestamp?: number }>(items: T[], opts: { sinceMs?: number | null; untilMs?: number | null }, now: number = Date.now()): T[] {
  const sinceTs = opts.sinceMs != null ? now - opts.sinceMs : undefined;
  const untilTs = opts.untilMs != null ? now - opts.untilMs : undefined;
  return items.filter((item) => {
    const ts = item.timestamp ?? now;
    if (sinceTs !== undefined && ts < sinceTs) return false;
    if (untilTs !== undefined && ts > untilTs) return false;
    return true;
  });
}

export function selectFreshByTimestamp<T extends { timestamp?: unknown }>(
  items: T[],
  lastSeenTs: number,
): { fresh: T[]; lastSeenTs: number } {
  const fresh = items.filter((item) => Number(item.timestamp ?? 0) > lastSeenTs);
  const nextSeenTs = fresh.length > 0
    ? Math.max(lastSeenTs, ...fresh.map((item) => Number(item.timestamp ?? 0)).filter(Number.isFinite))
    : lastSeenTs;
  return { fresh, lastSeenTs: nextSeenTs };
}

async function captureNetworkItems(page: import('../types.js').IPage): Promise<BrowserNetworkItem[]> {
  if (page.readNetworkCapture) {
    const raw = await page.readNetworkCapture();
    if (Array.isArray(raw) && raw.length > 0) {
      return (raw as Array<Record<string, unknown>>).map((e) => {
        const preview = (e.responsePreview as string) ?? null;
        let body: unknown = null;
        if (preview) {
          try { body = JSON.parse(preview); } catch { body = preview; }
        }
        const fullSize = typeof e.responseBodyFullSize === 'number'
          ? (e.responseBodyFullSize as number)
          : (preview ? preview.length : 0);
        const truncated = e.responseBodyTruncated === true;
        const request = sanitizeCapturedRequest({
          headers: e.requestHeaders,
          bodyKind: e.requestBodyKind,
          bodyPreview: e.requestBodyPreview,
          bodyFullSize: e.requestBodyFullSize,
          bodyTruncated: e.requestBodyTruncated,
        });
        return {
          url: sanitizeCapturedUrl((e.url as string) || ''),
          method: (e.method as string) || 'GET',
          status: (e.responseStatus as number) || 0,
          size: fullSize,
          ct: (e.responseContentType as string) || '',
          body,
          bodyFullSize: fullSize,
          bodyTruncated: truncated,
          timestamp: timestampFromRaw(e.timestamp),
          ...(request ? { request } : {}),
        };
      });
    }
  }
  const raw = await page.evaluate(`(function(){ var out = window.__opencli_net || []; window.__opencli_net = []; return JSON.stringify(out); })()`) as string;
  try {
    const parsed = JSON.parse(raw) as BrowserNetworkItem[];
    return parsed.map((item) => ({
      ...item,
      url: sanitizeCapturedUrl(item.url),
      timestamp: timestampFromRaw(item.timestamp),
    }));
  } catch {
    if (process.env.OPENCLI_VERBOSE) log.warn(`[network] Failed to parse interceptor buffer: ${typeof raw === 'string' ? raw.slice(0, 200) : String(raw)}`);
    return [];
  }
}

/** Drop static-resource / telemetry noise so agents see only API-shaped traffic. */
function filterNetworkItems<T extends Pick<BrowserNetworkItem, 'url' | 'ct'>>(items: T[]): T[] {
  return items.filter((r) => {
    const ct = r.ct?.toLowerCase() ?? '';
    return (
      (ct.includes('json') || ct.includes('xml') || ct.includes('text/plain') || ct.includes('javascript') || ct.includes('text/x-component') || /\/rsc-action(?:\/|\?|$)/i.test(r.url)) &&
      !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
      !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url)
    );
  });
}

/** Exit codes by network error code — usage errors vs runtime failures. */
const NETWORK_ERROR_EXIT: Record<string, number> = {
  invalid_args: EXIT_CODES.USAGE_ERROR,
  invalid_filter: EXIT_CODES.USAGE_ERROR,
  invalid_max_body: EXIT_CODES.USAGE_ERROR,
};

/** Emit a structured error JSON so agents can branch on `error.code` without regex. */
function emitNetworkError(code: string, message: string, extra: Record<string, unknown> = {}): void {
  emitFailure({ code, message, ...extra }, NETWORK_ERROR_EXIT[code] ?? EXIT_CODES.GENERIC_ERROR);
}

type BrowserTargetState = {
  defaultPage?: string;
  updatedAt: string;
};

type BrowserTabSummary = {
  page?: string;
};

function getBrowserCacheDir(): string {
  return process.env.OPENCLI_CACHE_DIR || path.join(os.homedir(), '.opencli', 'cache');
}

function getBrowserTargetStatePath(scope: string): string {
  const safeSession = scope.replace(/[^a-zA-Z0-9_-]+/g, '_');
  return path.join(getBrowserCacheDir(), 'browser-state', `${safeSession}.json`);
}

function loadBrowserTargetState(scope: string): BrowserTargetState | null {
  try {
    const raw = fs.readFileSync(getBrowserTargetStatePath(scope), 'utf-8');
    const parsed = JSON.parse(raw) as BrowserTargetState | null;
    return parsed && typeof parsed === 'object' ? parsed : null;
  } catch {
    return null;
  }
}

function saveBrowserTargetState(defaultPage: string | undefined, scope: string): void {
  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: unknown[], targetPage: string): boolean {
  return tabs.some((tab) => {
    return typeof tab === 'object'
      && tab !== null
      && 'page' in tab
      && typeof (tab as BrowserTabSummary).page === 'string'
      && (tab as BrowserTabSummary).page === targetPage;
  });
}

async function resolveBrowserTargetInSession(
  page: import('../types.js').IPage,
  targetPage: string,
  opts: { scope: string; source: 'explicit' | 'saved' },
): Promise<string | undefined> {
  const candidate = targetPage.trim();
  if (!candidate) return undefined;

  let tabs: unknown[];
  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 session 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 session may have restarted; re-run "opencli browser tab list" and choose a current target.',
  );
}

function getBrowserScope(session: string, contextId?: string): string {
  return contextId ? `${contextId}:${session}` : session;
}

async function resolveStoredBrowserTarget(page: import('../types.js').IPage, scope: string): Promise<string | undefined> {
  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 named browser session for continuity. */
async function getBrowserPage(
  session: string,
  targetPage?: string,
  profileSelection?: ProfileSelection,
  opts: { windowMode?: BrowserWindowMode } = {},
): Promise<import('../types.js').IPage> {
  const { BrowserBridge } = await import('../browser/index.js');
  const bridge = new BrowserBridge();
  // Internal GC timeout for browser sessions. Not the per-command runtime timeout.
  const envTimeout = process.env.OPENCLI_BROWSER_IDLE_TIMEOUT;
  const idleTimeout = envTimeout ? parseInt(envTimeout, 10) : undefined;
  const page = await bridge.connect({
    timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT,
    session,
    surface: 'browser',
    ...profileRouteParams(profileSelection),
    ...(idleTimeout && idleTimeout > 0 && { idleTimeout }),
    windowMode: opts.windowMode ?? getBrowserWindowMode(undefined, 'foreground'),
  });
  const targetScope = getBrowserScope(session, profileSelection?.contextId);
  const resolvedTargetPage = targetPage
    ? await resolveBrowserTargetInSession(page, targetPage, { scope: targetScope, source: 'explicit' })
    : await resolveStoredBrowserTarget(page, targetScope);
  if (resolvedTargetPage) {
    if (!page.setActivePage) {
      throw new Error('This browser session does not support explicit tab targeting');
    }
    page.setActivePage(resolvedTargetPage);
  }
  return page;
}

function getBrowserWindowMode(command: Command | undefined, defaultMode: BrowserWindowMode): BrowserWindowMode {
  const optionRaw = getCommandOption(command, 'window');
  if (optionRaw !== undefined && optionRaw !== '') {
    if (optionRaw === 'foreground' || optionRaw === 'background') return optionRaw;
    throw new Error(`--window must be one of: foreground, background. Received: "${String(optionRaw)}"`);
  }
  const envRaw = process.env.OPENCLI_WINDOW;
  if (envRaw !== undefined && envRaw !== '') {
    if (envRaw === 'foreground' || envRaw === 'background') return envRaw;
    throw new Error(`OPENCLI_WINDOW must be one of: foreground, background. Received: "${envRaw}"`);
  }
  return defaultMode;
}

function addBrowserTabOption(command: Command): Command {
  return command.option('--tab <targetId>', BROWSER_TAB_OPTION_DESCRIPTION);
}

function getBrowserTargetId(command?: Command): string | undefined {
  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 getCommandOption(command: Command | undefined, option: string): unknown {
  let current: Command | undefined = command;
  while (current) {
    const opts = current.opts();
    if (Object.prototype.hasOwnProperty.call(opts, option) && opts[option] !== undefined) return opts[option];
    current = current.parent as Command | undefined;
  }
  return undefined;
}

function getBrowserSession(command?: Command): string {
  const raw = getCommandOption(command, 'session');
  if (typeof raw === 'string' && raw.trim()) return raw.trim();
  throw Object.assign(new Error('Page commands require --session <name>.'), { code: 'usage_error' });
}

function getBrowserProfileSelection(command?: Command): ProfileSelection | undefined {
  const raw = getCommandOption(command, 'profile');
  return resolveProfileSelection(typeof raw === 'string' && raw.trim() ? raw.trim() : undefined);
}

function getPageSession(page: import('../types.js').IPage): string {
  const session = (page as unknown as { session?: unknown }).session;
  if (typeof session === 'string' && session.trim()) return session.trim();
  throw new Error('Browser page is missing a session');
}

function getPageScope(page: import('../types.js').IPage): string {
  // Scope is keyed by the SELECTED profile (explicit or preferred), matching
  // getBrowserPage's targetScope — reading only the explicit contextId would
  // save and look up the remembered tab under different keys whenever the
  // profile came from the config default.
  const { contextId, preferredContextId } = page as unknown as { contextId?: unknown; preferredContextId?: unknown };
  const selected = typeof contextId === 'string' && contextId.trim()
    ? contextId.trim()
    : (typeof preferredContextId === 'string' && preferredContextId.trim() ? preferredContextId.trim() : undefined);
  return getBrowserScope(getPageSession(page), selected);
}

type SnapshotSource = 'dom' | 'ax';

function snapshotMetricText(snapshot: unknown): string {
  return typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2);
}

function snapshotMetrics(snapshot: unknown, elapsedMs: number): Record<string, unknown> {
  const text = snapshotMetricText(snapshot);
  const interactiveMatch = text.match(/^interactive:\s*(\d+)\s*$/m);
  return {
    ok: true,
    chars: text.length,
    bytes: Buffer.byteLength(text, 'utf8'),
    lines: text ? text.split(/\r?\n/).length : 0,
    approx_tokens: Math.ceil(text.length / 4),
    refs: (text.match(/(^|\n)\s*\[\d+\]/g) ?? []).length,
    frame_sections: (text.match(/(^|\n)frame /g) ?? []).length,
    ...(interactiveMatch ? { interactive: Number(interactiveMatch[1]) } : {}),
    elapsed_ms: elapsedMs,
  };
}

async function snapshotSourceMetrics(page: IPage, source: SnapshotSource): Promise<Record<string, unknown>> {
  const started = Date.now();
  try {
    const snapshot = await page.snapshot({ viewportExpand: 2000, source });
    return snapshotMetrics(snapshot, Date.now() - started);
  } catch (err) {
    return {
      ok: false,
      elapsed_ms: Date.now() - started,
      error: {
        ...(err instanceof Error && 'code' in err ? { code: String((err as { code?: unknown }).code) } : {}),
        message: err instanceof Error ? err.message : String(err),
      },
    };
  }
}

function resolveBrowserTabTarget(targetId?: string, opts?: { tab?: string } | Command): string | undefined {
  if (typeof targetId === 'string' && targetId.trim()) return targetId.trim();
  const tab = opts instanceof Command ? opts.opts().tab : opts?.tab;
  if (typeof tab === 'string' && tab.trim()) return tab.trim();
  return undefined;
}

function parsePositiveIntOption(val: string | undefined, label: string, fallback: number): number {
  if (val === undefined) return fallback;
  const parsed = parseInt(val, 10);
  if (Number.isNaN(parsed) || parsed <= 0) {
    emitFailure(`[cli] Invalid ${label}="${val}", using default ${fallback}`);
    return fallback;
  }
  return parsed;
}

function parseScreenshotDim(val: string, label: string): number {
  if (!/^\d+$/.test(val)) {
    throw new InvalidArgumentError(`--${label} must be a positive integer (got "${val}")`);
  }
  const parsed = parseInt(val, 10);
  if (parsed <= 0) {
    throw new InvalidArgumentError(`--${label} must be a positive integer (got "${val}")`);
  }
  return parsed;
}


export function registerBrowserCommands(program: Command): Command {
  const browser = program.command('browser')
    .option('--session <name>', 'Page session (required for page commands)')
    .option('--window <mode>', 'Browser window mode: foreground or background')
    .description('Inspect pages, interact with elements, and manage Chrome resources');
  const originalBrowserDescription = browser.description();

  /**
   * 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: Awaited<ReturnType<typeof getBrowserPage>>,
    ref: string,
    opts: ResolveOptions = {},
  ): Promise<{ matches_n: number; match_level: TargetMatchLevel }> {
    const resolution = await page.evaluate(resolveTargetJs(ref, opts)) as
      | { ok: true; matches_n: number; match_level: TargetMatchLevel }
      | { ok: false; code: TargetErrorCode; message: string; hint: string; candidates?: string[]; matches_n?: number };
    if (!resolution.ok) {
      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: unknown): number | null | { error: string } {
    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: TargetError): void {
    emitFailure({
      code: err.code,
      message: err.message,
      hint: err.hint,
      ...(err.candidates && { candidates: err.candidates }),
      ...(err.matches_n !== undefined && { matches_n: err.matches_n }),
    });
  }

  function isJavaScriptDialogMessage(message: string): boolean {
    const normalized = message.toLowerCase();
    return normalized.includes('javascript dialog');
  }

  function emitJavaScriptDialogError(message: string): void {
    emitFailure({
      code: 'javascript_dialog_open',
      message,
      hint: 'Handle the modal first: opencli browser dialog accept (or dismiss). Use --text for prompt dialogs.',
    });
  }

  function emitBrowserCommandErrorEnvelope(err: BrowserCommandError): void {
    if (!err.code) return;
    emitFailure({
      code: err.code,
      message: err.message,
      ...(err.hint ? { hint: err.hint } : {}),
    });
  }

  function logBrowserCommandError(err: BrowserCommandError): void {
    log.error(err.message);
    if (err.hint) log.error(`Hint: ${err.hint}`);
  }

  function browserLifecycle<Args extends unknown[]>(action: (...args: Args) => Promise<unknown>) {
    return async (...args: Args) => {
      const command = args.at(-1) instanceof Command ? args.at(-1) as Command : undefined;
      const names: string[] = [];
      for (let node = command; node && node !== browser; node = node.parent ?? undefined) names.unshift(node.name());
      const hookArgs: Record<string, unknown> = { ...command?.optsWithGlobals() };
      command?.registeredArguments.forEach((argument, index) => {
        hookArgs[argument.name()] = command.processedArgs[index];
      });
      const context: HookContext = { command: ['browser', ...names].join('/'), args: hookArgs, startedAt: Date.now() };
      const output: CommandOutputCapture = {};
      await emitHook('onBeforeExecute', context);
      try {
        await captureCommandOutput(output, () => action(...args));
      } catch (error) {
        context.error = error;
        throw error;
      } finally {
        context.error ??= output.error;
        context.finishedAt = Date.now();
        await emitHook('onAfterExecute', context, output.result);
      }
    };
  }

  /** Wrap browser actions with error handling and optional --json output */
  function browserAction<Args extends unknown[]>(fn: (page: Awaited<ReturnType<typeof getBrowserPage>>, ...args: Args) => Promise<unknown>) {
    return browserLifecycle(async (...args: Args) => {
      let page: Awaited<ReturnType<typeof getBrowserPage>> | null = null;
      try {
        const command = args.at(-1) instanceof Command ? args.at(-1) as Command : undefined;
        const targetPage = getBrowserTargetId(command);
        const session = getBrowserSession(command);
        const profileSelection = getBrowserProfileSelection(command);
        const windowMode = getBrowserWindowMode(command, 'foreground');
        page = await getBrowserPage(session, targetPage, profileSelection, { windowMode });
        await fn(page, ...args);
      } catch (err) {
        if (isJavaScriptDialogMessage(getErrorMessage(err))) emitJavaScriptDialogError(getErrorMessage(err));
        else emitFailure(err);
      }
    });
  }

  type BrowserSessionCommandContext = {
    session: string;
    contextId?: string;
  };

  function browserSessionCommandAction(fn: (ctx: BrowserSessionCommandContext) => Promise<void>) {
    return browserLifecycle(async (optsOrCommand: unknown, maybeCommand?: Command) => {
      const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;
      try {
        const session = getBrowserSession(command);
        const profileSelection = getBrowserProfileSelection(command);
        const contextId = profileSelection?.contextId;
        const { BrowserBridge } = await import('../browser/index.js');
        const bridge = new BrowserBridge();
        await bridge.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, session, surface: 'browser', ...profileRouteParams(profileSelection) });
        await fn({ session, contextId });
      } catch (err) { emitFailure(err); }
    });
  }

  browser.command('bind')
    .description('Bind the current Chrome tab/window to the browser session named by <session>')
    .action(browserSessionCommandAction(async ({ session, contextId }) => {
      const data = await bindTab(session, { ...(contextId && { contextId }) });
      saveBrowserTargetState(undefined, getBrowserScope(session, contextId));
      emitResult({ session, ...((data && typeof data === 'object') ? data as Record<string, unknown> : { data }) });
    }));

  browser.command('unbind')
    .description('Detach the bound browser session named by <session> without closing the user tab/window')
    .action(browserSessionCommandAction(async ({ session, contextId }) => {
      await sendCommand('close-window', { session, surface: 'browser', ...(contextId && { contextId }) });
      saveBrowserTargetState(undefined, getBrowserScope(session, contextId));
      emitResult({ unbound: true, session });
    }));

  const browserTab = browser
    .command('tab')
    .description('Tab management — list, create, and close tabs in the browser session');

  browserTab.command('list')
    .description('List tabs in the browser session with target IDs')
    .action(browserAction(async (page) => {
      const tabs = await page.tabs();
      emitResult(tabs);
    }));

  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?: string) => {
      if (!page.newTab) {
        throw new Error('This browser session does not support creating tabs');
      }
      const createdPage = await page.newTab(url);
      emitResult({
        page: createdPage,
        url: url ?? null,
      });
    }));

  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?: string, opts?: { tab?: string } | Command) => {
      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, getPageScope(page));
      emitResult({ selected: resolvedTarget });
    }));

  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?: string, opts?: { tab?: string } | Command) => {
      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: getPageScope(page),
        source: 'explicit',
      });
      if (!validatedTarget) {
        throw new Error(`Target tab ${resolvedTarget} is not part of the current browser session.`);
      }
      await page.closeTab(validatedTarget);
      const scope = getPageScope(page);
      if (loadBrowserTargetState(scope)?.defaultPage === validatedTarget) {
        saveBrowserTargetState(undefined, scope);
      }
      emitResult({ closed: validatedTarget });
    }));

  // ── Navigation ──

  addBrowserTabOption(browser.command('open').argument('<url>').description('Open URL in the browser session'))
    .action(browserAction(async (page, url) => {
      // Start session-level capture before navigation (catches initial requests)
      const hasSessionCapture = await page.startNetworkCapture?.() ?? false;
      await page.goto(url);
      await page.wait(2);
      // Fallback: inject JS interceptor when session capture is unavailable
      if (!hasSessionCapture) {
        try { await page.evaluate(NETWORK_INTERCEPTOR_JS); } catch { /* non-fatal */ }
      }
      const currentUrl = await page.getCurrentUrl?.() ?? url;
      emitResult({
        url: currentUrl,
        ...(page.getActivePage?.() ? { page: page.getActivePage?.() } : {}),
      });
    }));

  addBrowserTabOption(browser.command('back').description('Go back in browser history'))
    .action(browserAction(async (page) => {
      await page.evaluate('history.back()');
      await page.wait(2);
      emitResult('Navigated back');
    }));

  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') {
        emitFailure(`Invalid direction "${direction}". Use "up" or "down".`, EXIT_CODES.USAGE_ERROR);
        return;
      }
      await page.scroll(direction, parseInt(opts.amount, 10));
      emitResult(`Scrolled ${direction}`);
    }));

  // ── Inspect ──

  addBrowserTabOption(browser.command('state').description('Page state: URL, title, interactive elements with [N] indices')
    .option('--source <source>', 'Snapshot backend: dom (default) or ax prototype', 'dom')
    .option('--diagnostics', 'Include page facts: title, URL and initial-state globals')
    .option('--compare-sources', 'Print DOM vs AX snapshot metrics for observation promotion decisions', false))
    .action(browserAction(async (page, opts) => {
      if (opts.compareSources === true) {
        const [dom, ax] = await Promise.all([
          snapshotSourceMetrics(page, 'dom'),
          snapshotSourceMetrics(page, 'ax'),
        ]);
        emitResult({
          url: await page.getCurrentUrl?.() ?? '',
          sources: { dom, ax },
        });
        return;
      }
      const source = String(opts.source ?? 'dom').toLowerCase();
      if (source !== 'dom' && source !== 'ax') {
        emitFailure({
          code: 'invalid_source',
          message: `--source must be "dom" or "ax", got "${opts.source}"`,
        }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const snapshot = await page.snapshot({ viewportExpand: 2000, source: source as 'dom' | 'ax' });
      const url = await page.getCurrentUrl?.() ?? '';
      const diagnostics = opts.diagnostics ? await page.evaluate(`(() => ({
        title: document.title, url: location.href,
        initialState: ['__INITIAL_STATE__','__NUXT__','__NEXT_DATA__','__APOLLO_STATE__'].filter(key => typeof window[key] !== 'undefined')
      }))()`) : undefined;
      emitResult({ url, snapshot, ...(diagnostics ? { diagnostics } : {}) });
    }));

  addBrowserTabOption(browser.command('frames').description('List cross-origin iframe targets in snapshot order'))
    .action(browserAction(async (page) => {
      const frames = await page.frames?.() ?? [];
      emitResult(frames);
    }));

  addBrowserTabOption(browser.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)'))
    .option('--full-page', 'Capture the full scrollable page, not just the viewport', false)
    .option('--annotate', 'Overlay visible browser state ref labels on the screenshot', false)
    .option('--width <n>', 'Override viewport width in CSS pixels for this screenshot only', (v: string) => parseScreenshotDim(v, 'width'))
    .option('--height <n>', 'Override viewport height in CSS pixels for this screenshot only (ignored with --full-page)', (v: string) => parseScreenshotDim(v, 'height'))
    .description('Take screenshot')
    .action(browserAction(async (page, path, opts) => {
      const shotOpts: ScreenshotOptions = {
        fullPage: opts.fullPage === true,
        annotate: opts.annotate === true,
        width: opts.width,
        height: opts.height,
      };
      const capture = opts.annotate === true
        ? (page.annotatedScreenshot ?? page.screenshot).bind(page)
        : page.screenshot.bind(page);
      if (path) {
        await capture({ ...shotOpts, path });
        emitResult(`Screenshot saved to: ${path}`);
      } else {
        emitResult(await capture({ ...shotOpts, format: 'png' }));
      }
    }));

  addBrowserTabOption(browser.command('console'))
    .option('--level <level>', 'Console level: all, error, warning, log, info, debug', 'all')
    .option('--since <duration>', 'Only include messages from the last duration (for example: 30s, 2m)')
    .option('--until <duration>', 'Only include messages older than the duration from now')
    .option('--follow', 'Continuously print new console messages as JSON lines', false)
    .description('Read recent browser console messages')
    .action(browserAction(async (page, opts) => {
      const sinceMs = parseDurationMs(opts.since, 'since');
      const untilMs = parseDurationMs(opts.until, 'until');
      if (sinceMs && typeof sinceMs === 'object') {
        emitFailure({ code: 'invalid_since', message: sinceMs.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      if (untilMs && typeof untilMs === 'object') {
        emitFailure({ code: 'invalid_until', message: untilMs.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const normalize = (messages: unknown[]): Array<Record<string, unknown>> => messages.map((message) => {
        if (message && typeof message === 'object') {
          const record = message as Record<string, unknown>;
          return {
            ...record,
            timestamp: timestampFromRaw(record.timestamp),
          };
        }
        return { type: 'log', text: String(message), timestamp: Date.now() };
      });
      const filter = (messages: Array<Record<string, unknown>>) =>
        filterByTimeWindow(messages, { sinceMs, untilMs }).filter((message) => {
          if (opts.level === 'all') return true;
          const type = String(message.type ?? message.level ?? '').toLowerCase();
          return opts.level === 'error'
            ? type === 'error' || type === 'warning'
            : type === String(opts.level).toLowerCase();
        });

      if (opts.follow) {
        let lastSeenTs = 0;
        while (true) {
          const messages = filter(normalize(await page.consoleMessages('all')));
          const next = selectFreshByTimestamp(messages, lastSeenTs);
          for (const message of next.fresh) {
            emitResult({
              ...message,
              timestamp: toIsoTimestamp(message.timestamp),
            });
          }
          lastSeenTs = next.lastSeenTs;
          await new Promise((resolve) => setTimeout(resolve, FOLLOW_POLL_MS));
        }
      }

      const messages = filter(normalize(await page.consoleMessages(opts.level)));
      emitResult({
        session: getPageSession(page),
        captured_at: new Date().toISOString(),
        count: messages.length,
        messages: messages.map((message) => ({
          ...message,
          timestamp: toIsoTimestamp(message.timestamp),
        })),
      });
    }));

  // ── Native Chrome management ──
  const nativeChrome = browser.command('chrome').description('Manage native Chrome tabs, groups and windows without attaching a page');
  const nativeAction = (mode: 'chrome-call' | 'chrome-describe') => browserLifecycle(async (...args: any[]) => {
    try {
      const command = args.at(-1) as Command;
      const method = args[0] as string | undefined;
      const chromeArgs = mode === 'chrome-call' ? JSON.parse(args[1]) : [];
      if (!Array.isArray(chromeArgs)) throw Object.assign(new Error('Chrome arguments must be a JSON array.'), { code: 'invalid_args' });
      const result = await sendCommand(mode, {
        surface: 'browser',
        ...profileRouteParams(getBrowserProfileSelection(command)), chromeMethod: method, chromeArgs
      });
      emitResult(result);
    } catch (error) {
      const err = error as Error & { code?: string };
      emitFailure(err instanceof SyntaxError ? { code: 'invalid_args', message: err.message, exitCode: 2 } : err);
    }
  });
  nativeChrome.command('describe').argument('[method]').description('List supported methods or inspect signature and live permissions').action(nativeAction('chrome-describe'));
  nativeChrome.command('call').argument('<method>').argument('[args]', 'JSON array of native positional arguments', '[]')
    .description('Call a Chrome browser-management method; created resources persist').action(nativeAction('chrome-call'));

  // ── 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.
  const addSemanticLocatorOptions = (cmd: Command): Command => cmd
    .option('--role <role>', 'Semantic role (button, link, textbox, option, etc.)')
    .option('--name <text>', 'Accessible name contains text (aria-label, label, title, placeholder, or visible text)')
    .option('--label <text>', 'Associated label contains text')
    .option('--text <text>', 'Visible text contains text')
    .option('--testid <id>', 'data-testid / data-test / test-id contains id');

  const addPrefixedSemanticLocatorOptions = (cmd: Command, prefix: string): Command => cmd
    .option(`--${prefix}-role <role>`, `${prefix} semantic role`)
    .option(`--${prefix}-name <text>`, `${prefix} accessible name contains text`)
    .option(`--${prefix}-label <text>`, `${prefix} associated label contains text`)
    .option(`--${prefix}-text <text>`, `${prefix} visible text contains text`)
    .option(`--${prefix}-testid <id>`, `${prefix} data-testid / data-test / test-id contains id`);

  const semanticLocatorFromOptions = (opts: Record<string, unknown>): SemanticFindOptions | null => {
    const locator: SemanticFindOptions = {};
    for (const key of ['role', 'name', 'label', 'text', 'testid'] as const) {
      const value = opts[key];
      if (typeof value === 'string' && value.trim()) locator[key] = value.trim();
    }
    return Object.keys(locator).length > 0 ? locator : null;
  };

  const prefixedSemanticLocatorFromOptions = (opts: Record<string, unknown>, prefix: string): SemanticFindOptions | null => {
    const locator: SemanticFindOptions = {};
    const map = {
      role: `${prefix}Role`,
      name: `${prefix}Name`,
      label: `${prefix}Label`,
      text: `${prefix}Text`,
      testid: `${prefix}Testid`,
    } as const;
    for (const key of ['role', 'name', 'label', 'text', 'testid'] as const) {
      const value = opts[map[key]];
      if (typeof value === 'string' && value.trim()) locator[key] = value.trim();
    }
    return Object.keys(locator).length > 0 ? locator : null;
  };

  const semanticTargetFromLocator = async (
    page: Awaited<ReturnType<typeof getBrowserPage>>,
    locator: SemanticFindOptions,
    mode: 'read' | 'write',
  ): Promise<string | { target: string; total_matches?: number } | { error: { code: string; message: string; hint?: string; matches_n?: number; entries?: FindResult['entries'] } }> => {
    const result = await page.evaluate(buildSemanticFindJs({ ...locator, limit: 6 })) as FindResult | FindError;
    if (isFindError(result)) return result;
    if (mode === 'write' && result.matches_n !== 1) {
      return {
        error: {
          code: 'semantic_ambiguous',
          message: `Semantic locator matched ${result.matches_n} elements; write actions require a unique target.`,
          hint: 'Add --name/--label/--text/--testid or use browser find with a narrower locator.',
          matches_n: result.matches_n,
          entries: result.entries,
        },
      };
    }
    const first = result.entries[0];
    if (!first) {
      return {
        error: {
          code: 'semantic_not_found',
          message: 'Semantic locator matched 0 elements',
          hint: 'Try browser state, --source ax, or relax the semantic locator.',
        },
      };
    }
    const target = String(first.ref);
    if (mode === 'read') {
      return {
        target,
        ...(result.matches_n > 1 ? { total_matches: result.matches_n } : {}),
      };
    }
    return target;
  };

  const semanticTargetFromOptions = async (
    page: Awaited<ReturnType<typeof getBrowserPage>>,
    opts: Record<string, unknown>,
    mode: 'read' | 'write',
  ): Promise<string | { target: string; total_matches?: number } | { error: { code: string; message: string; hint?: string; matches_n?: number; entries?: FindResult['entries'] } } | null> => {
    const locator = semanticLocatorFromOptions(opts);
    if (!locator) return null;
    return semanticTargetFromLocator(page, locator, mode);
  };

  const resolveExplicitOrSemanticTarget = async (
    page: Awaited<ReturnType<typeof getBrowserPage>>,
    target: unknown,
    opts: Record<string, unknown>,
    mode: 'read' | 'write',
  ): Promise<string | { target: string; total_matches?: number } | { error: { code: string; message: string; hint?: string; matches_n?: number; entries?: FindResult['entries'] } }> => {
    const explicit = typeof target === 'string' && target.trim() ? target.trim() : '';
    const hasSemantic = !!semanticLocatorFromOptions(opts);
    if (explicit && hasSemantic) {
      return {
        error: {
          code: 'usage_error',
          message: 'Pass either <target> or semantic locator flags, not both.',
        },
      };
    }
    if (explicit) return explicit;
    const semantic = await semanticTargetFromOptions(page, opts, mode);
    if (semantic) return semantic;
    return {
      error: {
        code: 'usage_error',
        message: 'Missing target. Pass a numeric ref/CSS selector, or semantic flags like --role button --name Submit.',
      },
    };
  };

  const printTargetResolutionError = (
    resolved: { error: { code: string; message: string; hint?: string; matches_n?: number; entries?: FindResult['entries'] } },
  ): void => {
    emitFailure(resolved.error, EXIT_CODES.USAGE_ERROR);
  };

  const resolveWriteTargetOrPrint = async (
    page: Awaited<ReturnType<typeof getBrowserPage>>,
    target: unknown,
    opts: Record<string, unknown>,
  ): Promise<string | null> => {
    const resolvedTarget = await resolveExplicitOrSemanticTarget(page, target, opts, 'write');
    if (typeof resolvedTarget === 'string') return resolvedTarget;
    if ('error' in resolvedTarget) printTargetResolutionError(resolvedTarget);
    return null;
  };

  const resolveWriteTargetAndValueOrPrint = async (
    page: Awaited<ReturnType<typeof getBrowserPage>>,
    targetOrValue: unknown,
    value: unknown,
    opts: Record<string, unknown>,
    valueLabel: string,
  ): Promise<{ target: string; value: string } | null> => {
    const hasSemantic = !!semanticLocatorFromOptions(opts);
    if (hasSemantic && value !== undefined) {
      printTargetResolutionError({
        error: {
          code: 'usage_error',
          message: `When using semantic locator flags, pass only <${valueLabel}> as the positional argument.`,
        },
      });
      return null;
    }
    const resolvedValue = hasSemantic ? targetOrValue : value;
    if (resolvedValue === undefined) {
      printTargetResolutionError({
        error: {
          code: 'usage_error',
          message: `Missing ${valueLabel}.`,
          hint: hasSemantic
            ? `With semantic locator flags, pass the ${valueLabel} as the only positional argument.`
            : `Pass both a target and ${valueLabel}.`,
        },
      });
      return null;
    }
    const resolvedTarget = await resolveWriteTargetOrPrint(page, hasSemantic ? undefined : targetOrValue, opts);
    if (!resolvedTarget) return null;
    return { target: resolvedTarget, value: String(resolvedValue) };
  };

  const resolvePrefixedWriteTargetOrPrint = async (
    page: Awaited<ReturnType<typeof getBrowserPage>>,
    target: unknown,
    opts: Record<string, unknown>,
    prefix: string,
    label: string,
  ): Promise<string | null> => {
    const explicit = typeof target === 'string' && target.trim() ? target.trim() : '';
    const locator = prefixedSemanticLocatorFromOptions(opts, prefix);
    if (explicit && locator) {
      printTargetResolutionError({
        error: {
          code: 'usage_error',
          message: `Pass either <${label}> or --${prefix}-* semantic locator flags, not both.`,
        },
      });
      return null;
    }
    if (explicit) return explicit;
    if (locator) {
      const resolved = await semanticTargetFromLocator(page, locator, 'write');
      if (typeof resolved === 'string') return resolved;
      if ('error' in resolved) printTargetResolutionError(resolved);
      return null;
    }
    printTargetResolutionError({
      error: {
        code: 'usage_error',
        message: `Missing ${label}. Pass a numeric ref/CSS selector, or --${prefix}-role/--${prefix}-name semantic flags.`,
      },
    });
    return null;
  };

  addBrowserTabOption(
    addSemanticLocatorOptions(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 or semantic locator — returns JSON {matches_n, entries[]}'),
  )
    .action(browserAction(async (page, opts) => {
      const locator = semanticLocatorFromOptions(opts);
      if ((!opts.css || typeof opts.css !== 'string') && !locator) {
        emitFailure({
          code: 'usage_error',
          message: '--css <selector> or a semantic locator flag is required',
          hint: 'Examples: opencli browser find --css ".btn.primary"; opencli browser find --role button --name Save',
        }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      if (opts.css && locator) {
        emitFailure({
          code: 'usage_error',
          message: 'Pass either --css or semantic locator flags, not both.',
        }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const limit = parseNthFlag(opts.limit);
      if (limit && typeof limit === 'object' && 'error' in limit) {
        emitFailure({ code: 'usage_error', message: limit.error.replace('--nth', '--limit') }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const textMax = parseNthFlag(opts.textMax);
      if (textMax && typeof textMax === 'object' && 'error' in textMax) {
        emitFailure({ code: 'usage_error', message: textMax.error.replace('--nth', '--text-max') }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const result = await page.evaluate(
        locator
          ? buildSemanticFindJs({
            ...locator,
            limit: limit as number | null ?? undefined,
            textMax: textMax as number | null ?? undefined,
          })
          : buildFindJs(opts.css, {
            limit: limit as number | null ?? undefined,
            textMax: textMax as number | null ?? undefined,
          }),
      ) as FindResult | FindError;
      if (isFindError(result)) {
        emitFailure(result.error, EXIT_CODES.GENERIC_ERROR);
        return;
      }
      emitResult(result);
    }));

  // ── Get commands (structured data extraction) ──

  const get = browser.command('get').description('Get page properties');

  addBrowserTabOption(get.command('title').description('Page title'))
    .action(browserAction(async (page) => {
      emitResult(await page.evaluate('document.title'));
    }));

  addBrowserTabOption(get.command('url').description('Current page URL'))
    .action(browserAction(async (page) => {
      emitResult(await page.getCurrentUrl?.() ?? await page.evaluate('location.href'));
    }));

  // 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: Awaited<ReturnType<typeof getBrowserPage>>,
    target: string | undefined,
    opts: Record<string, unknown> & { nth?: string },
    evalJs: string,
    field: 'text' | 'value' | 'attributes',
  ): Promise<void> => {
    const resolvedTarget = await resolveExplicitOrSemanticTarget(page, target, opts, 'read');
    if (typeof resolvedTarget !== 'string' && 'error' in resolvedTarget) {
      emitFailure(resolvedTarget.error, EXIT_CODES.USAGE_ERROR);
      return;
    }
    const targetRef = typeof resolvedTarget === 'string' ? resolvedTarget : resolvedTarget.target;
    const totalMatches = typeof resolvedTarget === 'string' ? undefined : resolvedTarget.total_matches;
    const nth = parseNthFlag(opts.nth);
    if (nth && typeof nth === 'object' && 'error' in nth) {
      emitFailure({ code: 'usage_error', message: nth.error }, EXIT_CODES.USAGE_ERROR);
      return;
    }
    const { matches_n, match_level } = await resolveRef(page, targetRef, {
      firstOnMulti: nth === null,
      ...(typeof nth === 'number' ? { nth } : {}),
    });
    const raw = await page.evaluate(evalJs);
    let value: unknown;
    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;
    }
    emitResult({
      value,
      matches_n,
      match_level,
      ...(totalMatches && totalMatches > 1 ? { total_matches: totalMatches } : {}),
    });
  };

  addBrowserTabOption(
    addSemanticLocatorOptions(get.command('text'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .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, target, opts ?? {}, getTextResolvedJs(), 'text')));

  addBrowserTabOption(
    addSemanticLocatorOptions(get.command('value'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .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, 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') {
        emitFailure({ code: 'invalid_format', message: `--as must be "html" or "json", got "${opts.as}"` }, 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)) {
        emitFailure({ code: 'invalid_max', message: `--max must be a non-negative integer, got "${opts.max}"` }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const max = Number.parseInt(rawMax, 10);

      if (format === 'json') {
        const parseBudget = (flag: string, value: unknown): number | null | { error: string } => {
          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) {
            emitFailure({ code: 'invalid_budget', message: budget.error }, EXIT_CODES.USAGE_ERROR);
            return;
          }
        }
        const js = buildHtmlTreeJs({
          selector: opts.selector ?? null,
          depth: depth as number | null,
          childrenMax: childrenMax as number | null,
          textMax: textMax as number | null,
        });
        const result = await page.evaluate(js) as HtmlTreeResult | { selector: string; invalidSelector: true; reason: string } | null;
        if (result && typeof result === 'object' && 'invalidSelector' in result && result.invalidSelector) {
          emitFailure({ code: 'invalid_selector', message: `Selector "${opts.selector}" is not a valid CSS selector: ${result.reason}` }, EXIT_CODES.USAGE_ERROR);
          return;
        }
        const ok = result as HtmlTreeResult | null;
        if (!ok || ok.matched === 0) {
          emitFailure({
            code: 'selector_not_found',
            message: opts.selector
              ? `Selector "${opts.selector}" matched 0 elements.`
              : 'Page has no documentElement.',
          }, EXIT_CODES.USAGE_ERROR);
          return;
        }
        emitResult(ok);
        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 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 };
        })()`,
      ) as { kind: 'ok'; html: string | null } | { kind: 'invalid_selector'; reason: string };

      if (rawResult.kind === 'invalid_selector') {
        emitFailure({ code: 'invalid_selector', message: `Selector "${opts.selector}" is not a valid CSS selector: ${rawResult.reason}` }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const html = rawResult.html;

      if (html === null) {
        if (opts.selector) {
          emitFailure({ code: 'selector_not_found', message: `Selector "${opts.selector}" matched 0 elements.` }, EXIT_CODES.USAGE_ERROR);
          return;
        }
        emitResult('(empty)');
        return;
      }
      if (max > 0 && html.length > max) {
        emitResult(`<!-- opencli: truncated ${max} of ${html.length} chars; re-run without --max (or --max 0) for full -->\n${html.slice(0, max)}`);
        return;
      }
      emitResult(html);
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(get.command('attributes'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .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, target, opts ?? {}, getAttributesResolvedJs(), 'attributes')));

  // ── Interact ──
  //
  // 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: unknown): { error: string } | { opts: ResolveOptions } {
    const parsed = parseNthFlag(raw);
    if (parsed && typeof parsed === 'object' && 'error' in parsed) return parsed;
    if (typeof parsed === 'number') return { opts: { nth: parsed } };
    return { opts: {} };
  }

  function resolveUploadFilePaths(rawFiles: unknown): { files: string[] } | { error: { code: string; message: string; hint?: string } } {
    const inputs = Array.isArray(rawFiles) ? rawFiles : [];
    if (inputs.length === 0) {
      return {
        error: {
          code: 'usage_error',
          message: 'At least one file path is required.',
          hint: 'Example: opencli browser upload "input[type=file]" ./receipt.pdf',
        },
      };
    }
    const files: string[] = [];
    for (const input of inputs) {
      const raw = String(input);
      const expanded = raw === '~' || raw.startsWith(`~${path.sep}`)
        ? path.join(os.homedir(), raw.slice(2))
        : raw;
      const resolved = path.resolve(expanded);
      if (!fs.existsSync(resolved)) {
        return { error: { code: 'file_not_found', message: `File not found: ${resolved}` } };
      }
      const stat = fs.statSync(resolved);
      if (!stat.isFile()) {
        return { error: { code: 'not_a_file', message: `Not a regular file: ${resolved}` } };
      }
      files.push(resolved);
    }
    return { files };
  }

  function parseResolveFlag(raw: unknown, flag: string): { error: string } | { opts: ResolveOptions } {
    const parsed = parseNthFlag(raw);
    if (parsed && typeof parsed === 'object' && 'error' in parsed) {
      return { error: parsed.error.replace('--nth', flag) };
    }
    if (typeof parsed === 'number') return { opts: { nth: parsed } };
    return { opts: {} };
  }

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('click'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .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 resolvedTarget = await resolveExplicitOrSemanticTarget(page, target, opts ?? {}, 'write');
      if (typeof resolvedTarget !== 'string' && 'error' in resolvedTarget) {
        emitFailure(resolvedTarget.error, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const clickTarget = typeof resolvedTarget === 'string' ? resolvedTarget : resolvedTarget.target;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const { matches_n, match_level, click_method, hit, retargeted } = await page.click(clickTarget, parsed.opts);
      emitResult({
        clicked: true, target: clickTarget, matches_n, match_level,
        ...(click_method && { click_method }),
        ...(hit && { hit }),
        ...(retargeted && { retargeted }),
      });
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('type'))
      .argument('[targetOrText]', 'Numeric ref/CSS target, or text when using --role/--name/etc.')
      .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, targetOrText, text, opts) => {
      const resolved = await resolveWriteTargetAndValueOrPrint(page, targetOrText, text, opts ?? {}, 'text');
      if (!resolved) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      // Click first (focuses the field), wait briefly, then type.
      await page.click(resolved.target, parsed.opts);
      await page.wait(0.3);
      const { matches_n, match_level } = await page.typeText(resolved.target, resolved.value, parsed.opts);
      // __resolved is already set by the resolver call inside page.typeText
      const isAutocomplete = await page.evaluate(isAutocompleteResolvedJs()) as boolean;
      if (isAutocomplete) await page.wait(0.4);
      emitResult({
        typed: true,
        text: resolved.value,
        target: resolved.target,
        matches_n,
        match_level,
        autocomplete: !!isAutocomplete,
      });
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('hover'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Move the mouse over an element — JSON envelope {hovered, target, matches_n}'),
  )
    .action(browserAction(async (page, target, opts) => {
      if (typeof page.hover !== 'function') throw new Error('browser hover is not supported by this browser backend');
      const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
      if (!resolvedTarget) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const { matches_n, match_level } = await page.hover(resolvedTarget, parsed.opts);
      emitResult({ hovered: true, target: resolvedTarget, matches_n, match_level });
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('focus'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Focus an element — JSON envelope {focused, target, matches_n}'),
  )
    .action(browserAction(async (page, target, opts) => {
      if (typeof page.focus !== 'function') throw new Error('browser focus is not supported by this browser backend');
      const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
      if (!resolvedTarget) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const { focused, matches_n, match_level } = await page.focus(resolvedTarget, parsed.opts);
      emitResult({ focused, target: resolvedTarget, matches_n, match_level });
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('dblclick'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Double-click element — JSON envelope {dblclicked, target, matches_n}'),
  )
    .action(browserAction(async (page, target, opts) => {
      if (typeof page.dblClick !== 'function') throw new Error('browser dblclick is not supported by this browser backend');
      const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
      if (!resolvedTarget) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const { matches_n, match_level } = await page.dblClick(resolvedTarget, parsed.opts);
      emitResult({ dblclicked: true, target: resolvedTarget, matches_n, match_level });
    }));

  const runCheckCommand = async (
    page: Awaited<ReturnType<typeof getBrowserPage>>,
    target: unknown,
    opts: Record<string, unknown>,
    checked: boolean,
  ): Promise<void> => {
    if (typeof page.setChecked !== 'function') throw new Error(`browser ${checked ? 'check' : 'uncheck'} is not supported by this browser backend`);
    const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts);
    if (!resolvedTarget) return;
    const parsed = nthToResolveOpts(opts?.nth);
    if ('error' in parsed) {
      emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
      return;
    }
    const result = await page.setChecked(resolvedTarget, checked, parsed.opts);
    emitResult({
      checked: result.checked,
      changed: result.changed,
      target: resolvedTarget,
      matches_n: result.matches_n,
      match_level: result.match_level,
      ...(result.kind ? { kind: result.kind } : {}),
    });
  };

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('check'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Ensure a checkbox/radio/aria-checked control is checked — JSON envelope {checked, changed, target, matches_n}'),
  )
    .action(browserAction(async (page, target, opts) => {
      await runCheckCommand(page, target, opts ?? {}, true);
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('uncheck'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Ensure a checkbox/aria-checked control is unchecked — JSON envelope {checked, changed, target, matches_n}'),
  )
    .action(browserAction(async (page, target, opts) => {
      await runCheckCommand(page, target, opts ?? {}, false);
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('upload'))
      .argument('[targetOrFile]', 'Numeric ref/CSS target, or first file when using --role/--name/etc.')
      .argument('[files...]', 'Local file path(s) to attach')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Attach local files to a file input — JSON envelope {uploaded, files, file_names, target, matches_n}'),
  )
    .action(browserAction(async (page, targetOrFile, files, opts) => {
      if (typeof page.uploadFiles !== 'function') throw new Error('browser upload is not supported by this browser backend');
      const hasSemantic = !!semanticLocatorFromOptions(opts ?? {});
      const target = hasSemantic ? undefined : targetOrFile;
      const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
      if (!resolvedTarget) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const rawFiles = hasSemantic
        ? [targetOrFile, ...(Array.isArray(files) ? files : [])].filter((value) => value !== undefined)
        : files;
      const resolvedFiles = resolveUploadFilePaths(rawFiles);
      if ('error' in resolvedFiles) {
        emitFailure(resolvedFiles.error, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const result = await page.uploadFiles(resolvedTarget, resolvedFiles.files, parsed.opts);
      emitResult(result);
    }));

  addBrowserTabOption(
    addPrefixedSemanticLocatorOptions(
      addPrefixedSemanticLocatorOptions(browser.command('drag'), 'from'),
      'to',
    )
      .argument('[source]', 'Numeric ref/CSS selector to drag from, or omit with --from-role/--from-name/etc.')
      .argument('[target]', 'Numeric ref/CSS selector to drop onto, or omit with --to-role/--to-name/etc.')
      .option('--from-nth <n>', 'When <source> is a multi-match CSS selector, pick the nth match (0-based)')
      .option('--to-nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Drag one element to another — JSON envelope {dragged, source, target, source_matches_n, target_matches_n}'),
  )
    .action(browserAction(async (page, source, target, opts) => {
      if (typeof page.drag !== 'function') throw new Error('browser drag is not supported by this browser backend');
      const resolvedSource = await resolvePrefixedWriteTargetOrPrint(page, source, opts ?? {}, 'from', 'source');
      if (!resolvedSource) return;
      const resolvedTarget = await resolvePrefixedWriteTargetOrPrint(page, target, opts ?? {}, 'to', 'target');
      if (!resolvedTarget) return;
      const from = parseResolveFlag(opts?.fromNth, '--from-nth');
      if ('error' in from) {
        emitFailure({ code: 'usage_error', message: from.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const to = parseResolveFlag(opts?.toNth, '--to-nth');
      if ('error' in to) {
        emitFailure({ code: 'usage_error', message: to.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const result = await page.drag(resolvedSource, resolvedTarget, { from: from.opts, to: to.opts });
      emitResult(result);
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('fill'))
      .argument('[targetOrText]', 'Numeric ref/CSS target, or text when using --role/--name/etc.')
      .argument('[text]', 'Text to set exactly')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Set input/textarea/contenteditable text exactly and verify the value — JSON envelope {filled, verified, text, actual}'),
  )
    .action(browserAction(async (page, targetOrText, text, opts) => {
      const resolved = await resolveWriteTargetAndValueOrPrint(page, targetOrText, text, opts ?? {}, 'text');
      if (!resolved) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const result = await page.fillText(resolved.target, resolved.value, parsed.opts);
      if (!result.verified) { emitFailure({ code: 'value_mismatch', message: 'The input did not retain the requested value.', expected: resolved.value, actual: result.actual }); return; }
      emitResult({
        filled: result.filled,
        verified: result.verified,
        target: resolved.target,
        text: resolved.value,
        actual: result.actual,
        length: result.length,
        matches_n: result.matches_n,
        match_level: result.match_level,
        ...(result.mode ? { mode: result.mode } : {}),
      });
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('select'))
      .argument('[targetOrOption]', 'Numeric ref/CSS target, or option text when using --role/--name/etc.')
      .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, targetOrOption, option, opts) => {
      const resolved = await resolveWriteTargetAndValueOrPrint(page, targetOrOption, option, opts ?? {}, 'option');
      if (!resolved) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        emitFailure({ code: 'usage_error', message: parsed.error }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const { matches_n, match_level } = await resolveRef(page, resolved.target, parsed.opts);
      const result = await page.evaluate(selectResolvedJs(resolved.value)) as
        | { error?: string; selected?: string; available?: string[] }
        | null;
      if (result?.error) {
        // 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.
        emitFailure({
          code: result.error === 'Not a <select>' ? 'not_a_select' : 'option_not_found',
          message: result.error,
          ...(result.available && { available: result.available }),
          matches_n,
        }, EXIT_CODES.GENERIC_ERROR);
        return;
      }
      emitResult({
        selected: result?.selected ?? resolved.value,
        target: resolved.target,
        matches_n,
        match_level,
      });
    }));

  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);
      emitResult(`Pressed: ${key}`);
    }));

  const browserDialog = browser
    .command('dialog')
    .description('Handle a blocking JavaScript alert/confirm/prompt dialog');

  addBrowserTabOption(browserDialog.command('accept')
    .option('--text <text>', 'Prompt text to submit for prompt() dialogs')
    .description('Accept the currently open JavaScript dialog'))
    .action(browserAction(async (page, opts?: { text?: string }) => {
      if (!page.handleJavaScriptDialog) {
        throw new Error('This browser session does not support JavaScript dialog handling');
      }
      try {
        await page.handleJavaScriptDialog(true, opts?.text);
      } catch (err) {
        const message = getErrorMessage(err);
        if (message.toLowerCase().includes('no dialog')) {
          emitFailure({
            code: 'no_javascript_dialog',
            message: 'No JavaScript dialog is currently open.',
          }, EXIT_CODES.USAGE_ERROR);
          return;
        }
        throw err;
      }
      emitResult({ handled: true, action: 'accept', ...(opts?.text !== undefined && { text: opts.text }) });
    }));

  addBrowserTabOption(browserDialog.command('dismiss')
    .description('Dismiss the currently open JavaScript dialog'))
    .action(browserAction(async (page) => {
      if (!page.handleJavaScriptDialog) {
        throw new Error('This browser session does not support JavaScript dialog handling');
      }
      try {
        await page.handleJavaScriptDialog(false);
      } catch (err) {
        const message = getErrorMessage(err);
        if (message.toLowerCase().includes('no dialog')) {
          emitFailure({
            code: 'no_javascript_dialog',
            message: 'No JavaScript dialog is currently open.',
          }, EXIT_CODES.USAGE_ERROR);
          return;
        }
        throw err;
      }
      emitResult({ handled: true, action: 'dismiss' });
    }));

  // ── Wait commands ──

  addBrowserTabOption(browser.command('wait'))
    .argument('<type>', 'selector, text, time, xhr, or download')
    .argument('[value]', 'CSS selector, text string, seconds, XHR URL regex, or download filename/URL pattern')
    .option('--timeout <ms>', 'Timeout in milliseconds', '10000')
    .description('Wait for selector, text, time, matching XHR, or browser download (e.g. wait selector ".loaded", wait text "Success", wait time 3, wait xhr "/api/search", wait download receipt.pdf)')
    .action(browserAction(async (page, type, value, opts) => {
      const timeout = parseInt(opts.timeout, 10);
      if (type === 'time') {
        const seconds = parseFloat(value ?? '2');
        await page.wait(seconds);
        emitResult(`Waited ${seconds}s`);
      } else if (type === 'selector') {
        if (!value) { emitFailure('Missing CSS selector', EXIT_CODES.USAGE_ERROR); return; }
        await page.wait({ selector: value, timeout: timeout / 1000 });
        emitResult(`Element "${value}" appeared`);
      } else if (type === 'text') {
        if (!value) { emitFailure('Missing text', EXIT_CODES.USAGE_ERROR); return; }
        await page.wait({ text: value, timeout: timeout / 1000 });
        emitResult(`Text "${value}" appeared`);
      } else if (type === 'xhr') {
        // Poll the capture ring until an entry matches the URL regex — turns
        // the common "open page, wait N seconds, hope the data landed" idiom
        // into a deterministic barrier keyed on the API the agent actually
        // cares about. Prevents silent "empty DOM" failures on slow SPAs.
        if (!value) { emitFailure('Missing XHR URL regex', EXIT_CODES.USAGE_ERROR); return; }
        let re: RegExp;
        try { re = new RegExp(value); } catch (err) {
          emitFailure(`Invalid regex "${value}": ${err instanceof Error ? err.message : String(err)}`, EXIT_CODES.USAGE_ERROR);
          return;
        }
        const hasSessionCapture = await page.startNetworkCapture?.() ?? false;
        if (!hasSessionCapture) {
          try { await page.evaluate(NETWORK_INTERCEPTOR_JS); } catch { /* non-fatal */ }
        }
        await captureNetworkItems(page);
        const deadline = Date.now() + timeout;
        const pollMs = 400;
        let matched: BrowserNetworkItem | null = null;
        while (Date.now() < deadline && !matched) {
          const items = await captureNetworkItems(page);
          matched = items.find((e) => re.test(e.url)) ?? null;
          if (!matched) await new Promise((r) => setTimeout(r, pollMs));
        }
        if (!matched) {
          emitFailure({
            code: 'xhr_not_seen',
            message: `No captured XHR matched /${value}/ within ${timeout}ms`,
            hint: 'Check the pattern against `browser network` output; the endpoint may not have fired yet, or capture is disabled.',
          }, EXIT_CODES.GENERIC_ERROR);
          return;
        }
        emitResult({
          matched: { url: matched.url, status: matched.status, contentType: matched.ct },
        });
      } else if (type === 'download') {
        if (typeof page.waitForDownload !== 'function') {
          emitFailure({
            code: 'download_wait_unavailable',
            message: 'The active browser backend does not support download lifecycle waits.',
            hint: 'Use the Browser Bridge extension version 1.0.8 or newer, then retry the command.',
          }, EXIT_CODES.GENERIC_ERROR);
          return;
        }
        const result = await page.waitForDownload(String(value ?? ''), timeout) as BrowserDownloadWaitResult;
        if (!result.downloaded) {
          const code = result.state === 'interrupted' && result.id !== undefined ? 'download_failed' : 'download_not_seen';
          emitFailure({
            code,
            download: result,
            message: result.error ?? `No download matched "${value ?? '*'}" within ${timeout}ms`,
            hint: 'Check the pattern against the expected filename or URL; use a longer --timeout if the download starts slowly.',
          }, EXIT_CODES.GENERIC_ERROR);
          return;
        }
        emitResult(result);
      } else {
        emitFailure(`Unknown wait type "${type}". Use: selector, text, time, xhr, or download`, EXIT_CODES.USAGE_ERROR);
      }
    }));

  // ── Extract ──

  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: unknown;
      if (opts.frame !== undefined) {
        const frameIndex = Number.parseInt(opts.frame, 10);
        if (!Number.isInteger(frameIndex) || frameIndex < 0) {
          emitFailure(`Invalid frame index "${opts.frame}". Use a 0-based index from "browser frames".`, 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);
      }
      emitResult(result);
    }));

  // ── 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) {
        emitFailure({ code: 'invalid_chunk_size', message: `--chunk-size must be a positive integer, got "${opts.chunkSize}"` }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      const rawStart = String(opts.start ?? '0');
      if (!/^\d+$/.test(rawStart)) {
        emitFailure({ code: 'invalid_start', message: `--start must be a non-negative integer, got "${opts.start}"` }, 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) as
        | { ok: true; url: string; title: string; html: string }
        | { invalidSelector: true; reason: string }
        | { notFound: true }
        | null;

      if (!res) {
        emitFailure({ code: 'extract_failed', message: 'Page returned no root element.' }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      if ('invalidSelector' in res) {
        emitFailure({ code: 'invalid_selector', message: `Selector "${selector}" is not a valid CSS selector: ${res.reason}` }, EXIT_CODES.USAGE_ERROR);
        return;
      }
      if ('notFound' in res) {
        emitFailure({ code: 'selector_not_found', message: selector ? `Selector "${selector}" matched 0 elements.` : 'Page has no body/main/article element.' }, EXIT_CODES.USAGE_ERROR);
        return;
      }

      const envelope = runExtractFromHtml({
        html: res.html,
        url: res.url,
        title: res.title,
        selector,
        start,
        chunkSize,
      });
      emitResult(envelope);
    }));

  // ── 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 browser session under ~/.opencli/cache/browser-network/.

  addBrowserTabOption(browser.command('network'))
    .option('--static', 'Include AST endpoint candidates from loaded scripts')
    .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('--since <duration>', 'Only include entries from the last duration (for example: 30s, 2m)')
    .option('--until <duration>', 'Only include entries older than the duration from now')
    .option('--follow', 'Continuously print new matching entries as JSON lines', false)
    .option('--failed', 'Only include failed HTTP requests (status 0 or >= 400)', false)
    .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) => {
      if (opts.static && (opts.follow || opts.detail || opts.raw || opts.filter)) {
        emitFailure({ code: 'usage_error', message: '--static cannot be combined with --follow, --detail, --raw or --filter.' });
        return;
      }
      const ttlMs = parsePositiveIntOption(opts.ttl, 'ttl', DEFAULT_TTL_MS);
      const session = getPageSession(page);
      const cacheScope = getPageScope(page);
      const hasDetail = typeof opts.detail === 'string' && opts.detail.length > 0;
      const hasFilter = typeof opts.filter === 'string';
      const sinceMs = parseDurationMs(opts.since, 'since');
      const untilMs = parseDurationMs(opts.until, 'until');
      if (sinceMs && typeof sinceMs === 'object') {
        emitNetworkError('invalid_since', sinceMs.error);
        return;
      }
      if (untilMs && typeof untilMs === 'object') {
        emitNetworkError('invalid_until', untilMs.error);
        return;
      }

      // --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;
      }

      let filterFields: string[] | null = null;
      if (hasFilter) {
        const parsed = parseFilter(opts.filter as string);
        if ('reason' in parsed) {
          emitNetworkError('invalid_filter', parsed.reason);
          return;
        }
        filterFields = parsed.fields;
      }

      if (hasDetail && opts.follow) {
        emitNetworkError('invalid_args', '--follow cannot be used with --detail.');
        return;
      }

      // --detail short-circuits: read from cache only, no live capture needed.
      if (hasDetail) {
        const res = loadNetworkCache(cacheScope, { ttlMs });
        if (res.status === 'missing') {
          emitNetworkError('cache_missing', `No cached capture. Run "browser network" first (in session "${session}").`);
          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: unknown = 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: Record<string, unknown> = {
          key: entry.key,
          url: entry.url,
          method: entry.method,
          status: entry.status,
          ct: entry.ct,
          size: entry.size,
          ...(typeof entry.timestamp === 'number' ? { timestamp: toIsoTimestamp(entry.timestamp) } : {}),
          shape: inferShape(entry.body),
          body: outputBody,
          ...(entry.request ? { request: entry.request } : {}),
        };
        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';
        }
        emitResult(detailEnvelope);
        return;
      }

      if (opts.follow) {
        if (!await page.startNetworkCapture?.()) {
          try { await page.evaluate(NETWORK_INTERCEPTOR_JS); } catch { /* non-fatal */ }
        }
        while (true) {
          const rawItems = await captureNetworkItems(page).catch((err) => {
            emitNetworkError('capture_failed', `Could not read network capture: ${(err as Error).message}`);
            return [];
          });
          let items = opts.all ? rawItems : filterNetworkItems(rawItems);
          items = filterByTimeWindow(items, { sinceMs, untilMs });
          if (opts.failed) items = items.filter((item) => item.status === 0 || item.status >= 400);
          const keyed = assignKeys(items);
          for (const item of keyed) {
            emitResult({
              key: item.key,
              timestamp: toIsoTimestamp(item.timestamp),
              method: item.method,
              status: item.status,
              url: item.url,
              ct: item.ct,
              size: item.size,
              ...(item.bodyTruncated ? { body_truncated: true } : {}),
            });
          }
          await new Promise((resolve) => setTimeout(resolve, FOLLOW_POLL_MS));
        }
      }

      // Fresh capture path.
      let rawItems: BrowserNetworkItem[];
      try {
        rawItems = await captureNetworkItems(page);
      } catch (err) {
        emitNetworkError('capture_failed', `Could not read network capture: ${(err as Error).message}`);
        return;
      }

      let selectedRaw = filterByTimeWindow(rawItems, { sinceMs, untilMs });
      if (opts.failed) selectedRaw = selectedRaw.filter((item) => item.status === 0 || item.status >= 400);

      // The live CDP buffer is a destructive drain. Assign keys and persist
      // the selected raw batch before applying display-only MIME/static/shape
      // filters, otherwise a default call permanently destroys RSC and other
      // non-standard responses before a later --all / --detail can inspect it.
      const keyed = assignKeys(selectedRaw);
      let cacheEntries: CachedNetworkEntry[] = keyed.map((it) => ({
        key: it.key,
        url: it.url,
        method: it.method,
        status: it.status,
        size: it.size,
        ct: it.ct,
        body: it.body,
        ...(typeof it.timestamp === 'number' ? { timestamp: it.timestamp } : {}),
        ...(it.bodyTruncated ? { body_truncated: true } : {}),
        ...(it.bodyTruncated && typeof it.bodyFullSize === 'number'
          ? { body_full_size: it.bodyFullSize }
          : {}),
        ...(it.request ? { request: it.request } : {}),
      }));

      // A repeated call commonly sees an empty live batch because the first
      // call drained it. Reuse the still-fresh raw cache instead of replacing
      // it with an empty file, so `network` followed by `network --all` works.
      let reusedCache = false;
      if (rawItems.length === 0) {
        const cached = loadNetworkCache(cacheScope, { ttlMs });
        if (cached.status === 'ok' && cached.file) {
          cacheEntries = filterByTimeWindow(cached.file.entries, { sinceMs, untilMs });
          if (opts.failed) cacheEntries = cacheEntries.filter((item) => item.status === 0 || item.status >= 400);
          reusedCache = true;
        }
      }

      const displayEntries = opts.all ? cacheEntries : filterNetworkItems(cacheEntries);
      const filteredOut = (reusedCache ? cacheEntries.length : rawItems.length) - displayEntries.length;
      // 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: string | null = null;
      if (!reusedCache && rawItems.length > 0) {
        try {
          saveNetworkCache(cacheScope, cacheEntries);
        } catch (err) {
          cacheWarning = `Could not persist capture cache: ${(err as Error).message}. --detail lookups may miss this capture.`;
        }
      }

      if (opts.static) {
        const { discoverEndpoints } = await import('../browser/discover.js');
        emitResult({
          ...await discoverEndpoints(page, displayEntries, true),
          networkSource: reusedCache ? 'cache' : rawItems.length ? 'live' : 'empty',
          ...(reusedCache ? { networkSavedAt: loadNetworkCache(cacheScope, { ttlMs }).file?.savedAt } : {}),
          ...(cacheWarning ? { cacheWarning } : {}),
        });
        return;
      }

      // 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 = displayEntries.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: Record<string, unknown> = {
        session,
        captured_at: new Date().toISOString(),
        count: visible.length,
        filtered_out: filteredOut,
      };
      if (reusedCache) envelope.cache_reused = true;
      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,
          ...(typeof s.entry.timestamp === 'number' ? { timestamp: toIsoTimestamp(s.entry.timestamp) } : {}),
        }));
      } else {
        envelope.entries = visible.map((s) => ({
          key: s.entry.key,
          method: s.entry.method,
          ...(typeof s.entry.timestamp === 'number' ? { timestamp: toIsoTimestamp(s.entry.timestamp) } : {}),
          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 opencli browser network --detail <key> --session ${JSON.stringify(session)} for full body.`;
      }
      emitResult(envelope);
    }));

  // ── Session ──

  browser.command('close').description('Release the current browser session tab lease')
    .action(browserAction(async (page) => {
      await page.closeWindow?.();
      emitResult('Browser session tab lease released');
    }));


  function addScopeOptions(command: Command, native = false): void {
    native ||= command.name() === 'chrome';
    if (!command.commands.length) {
      if (!native) {
        command.option('--session <name>', 'Required page session');
        command.option('--window <mode>', 'Browser window mode: foreground or background');
      }
      command.option('--profile <name>', 'Chrome profile/context');
    }
    for (const child of command.commands) addScopeOptions(child, native);
  }
  addScopeOptions(browser);
  installCommanderNamespaceStructuredHelp(browser, { globalCommand: program, description: originalBrowserDescription });
  return browser;
}