@surething/cockpit 1.0.217 → 1.0.219

package/bin/cock-browser.messages.mjs

@@ -0,0 +1,176 @@
+/**
+ * Centralized messages & generic example pool for the browser CLI.
+ *
+ * ALL user-facing text (help / errors / warnings) MUST source examples from
+ * EXAMPLES below. Never inline business-specific selectors or API paths.
+ *
+ * Single source of truth — PR review greps for case-specific leakage:
+ *   grep -E '<known case keywords>' bin/cock-browser.* chrome-extension/messages.js
+ *
+ * The extension side has its own copy (chrome-extension/messages.js); the
+ * subset that the extension generates locally (e.g. STALE_REF_MSG) lives
+ * there. Templates here are CLI-side only.
+ */
+
+// ─────────────────────────────────────────────────────────
+// Generic example pool. DO NOT add case-specific values.
+// ─────────────────────────────────────────────────────────
+
+export const EXAMPLES = Object.freeze({
+  selectorEmail: 'input[name="email"]',
+  selectorPassword: 'input[type="password"]',
+  selectorSubmit: 'button[type="submit"]',
+  selectorAriaSave: 'button[aria-label="Save"]',
+  selectorSearchBox: 'input[role="searchbox"]',
+  selectorStatus: '[role="status"]',
+  selectorContentEditable: '[contenteditable="true"]',
+  selectorLoginForm: 'form#login',
+  textSignIn: 'Sign in',
+  textSave: 'Save',
+  textSubmit: 'Submit',
+  apiUsersMe: '/api/users/me',
+  apiItems: '/api/items',
+  apiItemsId: '/api/items/123',
+});
+
+// ─────────────────────────────────────────────────────────
+// CLI-side error / warn templates
+// (server-side errors come back as data.error and are printed verbatim;
+//  the templates below cover errors the CLI itself originates.)
+// ─────────────────────────────────────────────────────────
+
+export const TIMEOUT_MSG = (timeoutMs, id) =>
+`Timeout: no response within ${timeoutMs}ms.
+  Likely cause: the page is busy (long render / streaming / network).
+  Diagnose:
+    cockpit browser ${id} health                    # is extension alive? (server-side, never blocks)
+    cockpit browser ${id} wait --extension-ready    # wait until responsive
+    cockpit browser ${id} wait --network-idle       # wait for the page to settle
+  If health returns alive but evaluate still hangs, the page itself is blocked.
+  Consider a service-level test if the page is driven by an async LLM/agent flow.`;
+
+export const CONNECT_REFUSED_MSG = (baseUrl) =>
+`Connection refused: Cockpit server not reachable at ${baseUrl}.
+  Recover:
+    1. Start the server: \`cockpit\` (prod, default port 3457) or \`cockpit-dev\` (dev, default 3456)
+    2. Or set COCKPIT_PORT env var if your server runs on a non-default port.`;
+
+// Used by F1.7 post-verify when click / key / submit succeeded per CDP
+// but no observable side-effect happened in the verify window.
+export const CLICK_NO_OP_WARN = (action, id, observed) =>
+`⚠ ${action} succeeded per CDP but no DOM mutation / URL change / network request in ${observed.windowMs}ms.
+  Likely a no-op (no real handler / portal-rendered / framework not listening).
+  Observed: url-changed=${observed.urlChanged} dom-changed=${observed.domChanged} new-requests=${observed.newRequests}
+  Try one of:
+    cockpit browser ${id} evaluate "(() => { const el = document.querySelector('${EXAMPLES.selectorAriaSave}'); el.click(); return el.outerHTML.slice(0,200); })()"
+    cockpit browser ${id} submit --form-selector '${EXAMPLES.selectorLoginForm}'
+    cockpit browser ${id} fetch ${EXAMPLES.apiItems} --method POST --body '{}'`;
+
+// ─────────────────────────────────────────────────────────
+// help fragments (composed in cock-browser.mjs printHelp)
+// ─────────────────────────────────────────────────────────
+
+export const HELP_WHEN_NOT_TO_USE =
+`── When NOT to use this CLI ───────────────────────────
+- Testing LLM-agent driven flows end-to-end: the agent's stochastic tool
+  choice and stop_reason make UI assertions flaky. Prefer a thin runtime
+  script that calls the same middleware / service directly with controlled
+  inputs.
+
+- Pages that stream / re-render for >10s: evaluate calls queue behind page
+  work and time out (~15s default). Run \`wait --extension-ready\` between
+  acts and asserts; if it stays hung, pivot to a service-level test.
+
+- Multi-tab / popup OAuth flows: each browser bubble tracks one tab. Open
+  the secondary tab in its own bubble or stub the OAuth handshake.`;
+
+export const HELP_INTERACTION_BY_SELECTOR = (idForExamples) =>
+`Interaction by selector (preferred — refs go stale on re-render):
+  click <ref|text>                Click by ref (e5#v3), or fall back to:
+  click --text <substr>           Click button/link by visible text or aria-label
+                                    e.g. click --text "${EXAMPLES.textSignIn}"
+  click --selector <css>          Click first element matching CSS
+                                    e.g. click --selector '${EXAMPLES.selectorSubmit}'
+  fill <ref> <value>              Fill via ref, or:
+  fill --selector <css> --value V Fill via native setter (works on React-controlled inputs)
+                                    e.g. fill --selector '${EXAMPLES.selectorEmail}' --value "user@example.com"
+  submit [--form-selector <css>]  form.requestSubmit() — works where key Enter is ignored
+                                    e.g. submit --form-selector '${EXAMPLES.selectorLoginForm}'
+
+  Post-verify (click / key / submit / click-by-text/-selector):
+  --verify-ms <N>                 Window in ms to wait before re-probing page state
+                                  (default 1000). Lower = faster but more false positives
+                                  on slow-rendering React. Higher = more tolerant.
+  --skip-verify (or --no-verify)  Disable post-verify for this command
+                                  (e.g. legit clicks that have no observable side-effect).`;
+
+export const HELP_FETCH =
+`Backend probing (inherits page auth):
+  fetch <url>                     GET, returns JSON or text
+                                    e.g. fetch ${EXAMPLES.apiUsersMe}
+  fetch <url> --method POST --body '{"name":"hello"}'
+  fetch <url> --json $.data.id    Extract via simple JSONPath ($, .key, [N], [*])`;
+
+export const HELP_HEALTH =
+`Diagnostics:
+  health                          Server-side bridge state (never blocks page).
+                                  Returns: ws status, last command timestamp, pending count.
+                                  Use when evaluate times out to distinguish
+                                  "extension dead" vs "page busy".
+  health --deep                   Also probe the page itself (may block if page is busy).`;
+
+export const HELP_WAIT =
+`Wait (synchronisation between act and assert):
+  wait --text <substr>            Wait for substring in body text
+  wait --selector <css> [--state visible|hidden|attached|detached]
+                                  Wait for element to reach state (default: visible)
+                                    e.g. wait --selector '${EXAMPLES.selectorStatus}' --state visible
+  wait --url <pat>                Wait for URL match (substring or *-glob)
+  wait --network-idle [--quiet-ms 500] [--max-request-age-ms 30000]
+                                  Wait until 0 in-flight HTTP requests for quiet-ms.
+                                  Long-running (>max-request-age-ms) are ignored
+                                  so SSE / long-poll don't block.
+                                    e.g. wait --network-idle --quiet-ms 800
+  wait --dom-stable [--quiet-ms 300]
+                                  Wait until MutationObserver sees no changes
+                                  for quiet-ms (useful between act and snapshot).
+  wait --extension-ready [--quiet-ms 500]
+                                  CLI-side poll of \`health\` (never blocks on page).
+                                  Replaces manual \`until evaluate "1+1"\` loops.
+  wait --time <ms>                Sleep <ms> (escape hatch — prefer above)
+  wait --ref <ref>                Wait for ref to still be connected`;
+
+export const HELP_LIFECYCLE =
+`Lifecycle / fixtures:
+  status                          One-line summary: url, title, last console error,
+                                  last failed request, top visible buttons.
+                                  Run after a long gap before another act.
+  reset [--cookies] [--storage] [--cache] [--reload]
+                                  Atomic test-isolation. Combine flags as needed.
+                                    e.g. reset --cookies --storage --reload
+  set --type cookie --name K --value V [--domain D] [--path P] [--secure]
+                                  [--same-site Lax|Strict|None] [--expires <date>]
+  set --type local-storage --name K --value V
+  set --type session-storage --name K --value V
+                                    e.g. set --type cookie --name auth --value abc123 --secure
+                                    e.g. set --type local-storage --name theme --value '"dark"'`;
+
+export const HELP_ASSERT =
+`Assert (act + assert atoms; non-zero exit on failure):
+  assert --selector <css> [--text X | --visible <bool> | --attr "k=v"]
+                                    e.g. assert --selector '${EXAMPLES.selectorStatus}' --text "Saved"
+                                    e.g. assert --selector '${EXAMPLES.selectorSubmit}' --visible true
+                                    e.g. assert --selector '[role="dialog"]' --attr "aria-modal=true"
+  assert --ref <ref> --text/...   Legacy ref-based form (refs go stale; prefer --selector)
+  assert --url <pat>              URL substring or *-glob match
+  assert --title <substr>
+  assert --console-no-errors
+  assert --network --method M --url U --status S [--since <ms>]
+                                  Assert a matching request occurred in networkBuffer.
+                                  Status accepts ints or "2xx"/"4xx"/etc.
+                                    e.g. assert --network --method POST --url ${EXAMPLES.apiItems} --status 200
+  assert --fetch <url> [--fetch-method M] [--body B] [--fetch-status N]
+         [--jsonpath P --equals V | --contains V | --not-contains V]
+                                  Make a fetch and assert response. Inherits auth.
+                                    e.g. assert --fetch ${EXAMPLES.apiItems} --jsonpath '$.count' --equals 5
+                                    e.g. assert --fetch ${EXAMPLES.apiItems} --jsonpath '$[*].id' --contains 42`;

package/bin/cock-browser.mjs

@@ -19,6 +19,19 @@
  *   cockpit browser abcd list   (list all connected browsers)
  */
 
+import {
+  TIMEOUT_MSG,
+  CONNECT_REFUSED_MSG,
+  CLICK_NO_OP_WARN,
+  HELP_WHEN_NOT_TO_USE,
+  HELP_INTERACTION_BY_SELECTOR,
+  HELP_FETCH,
+  HELP_HEALTH,
+  HELP_WAIT,
+  HELP_ASSERT,
+  HELP_LIFECYCLE,
+} from './cock-browser.messages.mjs';
+
 const args = process.argv.slice(2);
 
 // Help text
@@ -55,14 +68,16 @@ Three templates that always work:
   # 2) Set a React-controlled <input> via the native setter + input event:
   evaluate "(() => { const el = document.querySelector('input[name=foo]'); const set = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set; set.call(el, 'hello'); el.dispatchEvent(new Event('input', { bubbles: true })); return el.value; })()"
 
-  # 3) Click a button by aria-label / text (refs go stale after re-render):
-  evaluate "(() => { const btn = Array.from(document.querySelectorAll('button')).find(b => b.getAttribute('aria-label') === 'Send message' || b.textContent.trim() === 'Send'); if (!btn) return 'not-found'; btn.click(); return 'clicked'; })()"
+  # 3) Click a button by visible text or aria-label (refs go stale on re-render):
+  click --text "Sign in"                          # preferred shortcut
+  click --selector 'button[type="submit"]'        # exact selector
+  evaluate "(() => document.querySelector('button[aria-label=\\"Save\\"]').click())()"  # last resort
 
-Refs (e5, e23, …) returned by \`snapshot\` are valid only for the
-DOM at snapshot time. Any re-render / route change / focus shift
-invalidates them — \`Element ref "eN" not found or disconnected\`
-means you need a fresh \`snapshot\` (or just use \`evaluate\` with
-CSS selectors).
+Refs returned by \`snapshot\` are \`e<N>#v<epoch>\` — valid only until
+the next snapshot or re-render. The error message
+\`Element ref "..." is stale (current snapshot v=N)\` tells you to
+re-snapshot OR use \`click --text\` / \`click --selector\` /
+\`fill --selector\` for re-render-resilient interaction.
 
 ──────────────────────────────────────────────────────
 
@@ -74,18 +89,29 @@ Navigation:
   title                       Get page title
 
 Inspection:
-  snapshot                    Get element tree (returns refs like [e5])
-  screenshot                  Take a screenshot
+  snapshot                    a11y tree (refs like e5#v3; banner explains format)
+                              --filter <regex>           server-side grep
+                              --include-hidden-text      surface collapsed <summary>/container text
+                              --max-depth N              limit walk depth (default 12)
+  screenshot                  PNG saved to /tmp; path printed for Read tool
+
+${HELP_INTERACTION_BY_SELECTOR(prefix)}
 
-Interaction (use ref from snapshot):
-  click <ref>                 Click element  ⚠ React/SPA: may silently miss; use evaluate
-  type <ref> <text>           Type text  ⚠ React/SPA: may silently miss; use evaluate (template 1/2)
-  fill <ref> <value>          Fill input value  ⚠ Same — prefer template 2
+  type <ref> <text>           Type into ref (CDP key events; React-controlled may silently miss → use fill --selector)
   hover <ref>                 Hover element
   focus <ref>                 Focus element
   scroll --direction D        Scroll page (up/down/left/right)
   key <key>                   Press key (e.g. Enter, Ctrl+A)
-  wait --text T               Wait for text to appear
+
+${HELP_WAIT}
+
+${HELP_ASSERT}
+
+${HELP_LIFECYCLE}
+
+${HELP_FETCH}
+
+${HELP_HEALTH}
 
 DOM:
   computed <ref>              Get computed styles
@@ -111,6 +137,8 @@ Console & Debug:
   cookies                     Get cookies
   storage [--type T]          Get storage (local|session)
 
+${HELP_WHEN_NOT_TO_USE}
+
 ── Next step ──────────────────────────────────────────
 Run \`cockpit browser ${prefix} snapshot\` to inspect the page.
 It returns an element tree with refs like [e5]. Use those
@@ -191,9 +219,32 @@ const params = parseFlags(args.slice(action === 'list' ? 1 : 2));
 if (params._positional?.length) {
   const pos = params._positional;
   if (action === 'navigate' && !params.url) params.url = pos[0];
-  if (action === 'click' && !params.ref) params.ref = pos[0];
+  // click: positional is the ref (or text fallback for convenience if it does
+  // not look like a ref). Refs match e<N>#v<M>; anything else is treated as
+  // visible text so `click "Sign in"` Just Works.
+  if (action === 'click') {
+    if (!params.ref && !params.text && !params.selector) {
+      if (/^e\d+#v\d+$/.test(pos[0])) params.ref = pos[0];
+      else params.text = pos[0];
+    }
+  }
   if (action === 'type' && !params.ref) { params.ref = pos[0]; if (pos[1] && !params.text) params.text = pos[1]; }
-  if (action === 'fill' && !params.ref) { params.ref = pos[0]; if (pos[1] && !params.value) params.value = pos[1]; }
+  // fill: positional[0] is ref (when matches ref pattern) else --selector form.
+  // positional[1] is the value when ref-positional is used.
+  if (action === 'fill') {
+    if (!params.ref && !params.selector) {
+      if (/^e\d+#v\d+$/.test(pos[0])) {
+        params.ref = pos[0];
+        if (pos[1] && !params.value) params.value = pos[1];
+      } else {
+        // First positional taken as selector if it contains CSS-y chars.
+        params.selector = pos[0];
+        if (pos[1] && !params.value) params.value = pos[1];
+      }
+    } else if (params.selector && !params.value && pos[0]) {
+      params.value = pos[0];
+    }
+  }
   if (action === 'hover' && !params.ref) params.ref = pos[0];
   if (action === 'focus' && !params.ref) params.ref = pos[0];
   if (action === 'evaluate' && !params.js) params.js = pos[0];
@@ -206,9 +257,33 @@ if (params._positional?.length) {
   if (action === 'events' && !params.ref) params.ref = pos[0];
   if (action === 'network_detail' && !params.id) params.id = parseInt(pos[0]);
   if (action === 'network_record' && !params.action) params.action = pos[0] || 'status';
+  if (action === 'fetch' && !params.url) params.url = pos[0];
+  if (action === 'health' && pos[0] === '--deep') params.deep = true;
   delete params._positional;
 }
 
+// kebab → camel for new Phase 2 flags.
+if (params['network-idle']) { params.networkIdle = true; delete params['network-idle']; }
+if (params['dom-stable']) { params.domStable = true; delete params['dom-stable']; }
+if (params['extension-ready']) { params.extensionReady = true; delete params['extension-ready']; }
+if (params['quiet-ms'] != null) { params.quietMs = params['quiet-ms']; delete params['quiet-ms']; }
+if (params['max-request-age-ms'] != null) { params.maxRequestAgeMs = params['max-request-age-ms']; delete params['max-request-age-ms']; }
+if (params['fetch-status'] != null) { params.fetchStatus = params['fetch-status']; delete params['fetch-status']; }
+if (params['fetch-method']) { params.fetchMethod = params['fetch-method']; delete params['fetch-method']; }
+if (params['not-contains'] !== undefined) { params.notContains = params['not-contains']; delete params['not-contains']; }
+if (params['no-cache']) { params.noCache = true; delete params['no-cache']; }
+if (params['console-no-errors']) { params.consoleNoErrors = true; delete params['console-no-errors']; }
+if (params['same-site']) { params.sameSite = params['same-site']; delete params['same-site']; }
+if (params['http-only']) { params.httpOnly = true; delete params['http-only']; }
+if (params['verify-ms'] != null) { params.verifyMs = Number(params['verify-ms']); delete params['verify-ms']; }
+
+// kebab → camel for flags that the extension expects camel.
+if (params['include-hidden-text']) { params.includeHiddenText = true; delete params['include-hidden-text']; }
+if (params['max-depth'] != null) { params.maxDepth = params['max-depth']; delete params['max-depth']; }
+if (params['form-selector']) { params.formSelector = params['form-selector']; delete params['form-selector']; }
+if (params['skip-verify']) { params.skipVerify = true; delete params['skip-verify']; }
+if (params['no-verify']) { params.skipVerify = true; delete params['no-verify']; }
+
 // Port: env COCKPIT_PORT > ~/.cockpit/server.json > default 3457
 let port = process.env.COCKPIT_PORT || 3457;
 if (!process.env.COCKPIT_PORT) {
@@ -312,6 +387,43 @@ async function autoResolveChunked(baseUrl, id, data, cmdTimeout) {
 }
 
 // Send request
+// F2.7 — wait --extension-ready: poll the cheap server-side health endpoint
+// until the bridge reports quiet conditions for `quietMs` consecutive ms.
+// Replaces the manual `until cockpit browser X evaluate "1+1"` loop that AI
+// has historically used when an evaluate hangs on a busy page.
+async function waitExtensionReady({ quietMs = 500, timeoutMs = 60000 }) {
+  const start = Date.now();
+  let quietSince = null;
+  while (Date.now() - start < timeoutMs) {
+    let h = null;
+    try {
+      const r = await fetch(`${baseUrl}/api/browser/health`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ id, params: {}, timeout: 1000 }),
+        signal: AbortSignal.timeout(2000),
+      });
+      const j = await r.json();
+      h = j.ok ? j.data : null;
+    } catch { /* network blip — treat as not-ready */ }
+    const ready = h && h.found && h.ws === 'open' && h.pendingCommands === 0;
+    if (ready) {
+      if (quietSince == null) quietSince = Date.now();
+      if (Date.now() - quietSince >= quietMs) {
+        return { waited: `extension-ready (quiet=${quietMs}ms)`, elapsedMs: Date.now() - start };
+      }
+    } else {
+      quietSince = null;
+    }
+    await new Promise(r => setTimeout(r, 100));
+  }
+  throw new Error(
+    `wait --extension-ready timed out after ${timeoutMs}ms.\n` +
+    `  The bridge never reported quiet for ${quietMs}ms.\n` +
+    `  Consider a service-level test if the page is driven by an async LLM/agent flow.`
+  );
+}
+
 async function run() {
   // Only id provided without action → show help + status
   if (action === '_status') {
@@ -340,6 +452,22 @@ async function run() {
     return;
   }
 
+  // F2.7 — wait --extension-ready runs entirely CLI-side: it polls the cheap
+  // server-side `health` endpoint, so it works even when the page is blocked.
+  if (action === 'wait' && params.extensionReady) {
+    try {
+      const r = await waitExtensionReady({
+        quietMs: params.quietMs ?? 500,
+        timeoutMs: timeout,
+      });
+      console.log(`waited: ${r.waited} (elapsed ${formatMs(r.elapsedMs)})`);
+      return;
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  }
+
   const url = `${baseUrl}/api/browser/${action}`;
   const body = { id, params, timeout };
 
@@ -427,13 +555,18 @@ async function run() {
       }
     }
 
+    // F1.7 — post-verify silent failures for click / key / submit.
+    if (POST_VERIFY_ACTIONS.has(action)) {
+      try { await postVerify(action, params, resolved); } catch { /* never fail the command */ }
+    }
+
     // Format output
     await formatOutput(action, resolved);
   } catch (err) {
     if (err.name === 'TimeoutError' || err.code === 'ABORT_ERR') {
-      console.error(`Timeout: No response within ${timeout}ms. Is the browser bubble connected?`);
+      console.error(TIMEOUT_MSG(timeout, id));
     } else if (err.cause?.code === 'ECONNREFUSED') {
-      console.error(`Connection refused: Cockpit server not running at ${baseUrl}`);
+      console.error(CONNECT_REFUSED_MSG(baseUrl));
     } else {
       console.error(`Error: ${err.message}`);
     }
@@ -441,6 +574,57 @@ async function run() {
   }
 }
 
+// F1.7 — Post-verify for click / key / submit. CDP reports "success" even when
+// the framework didn't react. Diff a cheap state probe before and after; if
+// nothing observable changed in the window, warn with actionable templates.
+//
+// Default window: 1000ms (BL-1, observation period). Was 200ms but dogfood
+// showed false positives on React pages whose batched re-renders + XHR fire
+// took >200ms to surface. Users can override per command with --verify-ms;
+// --skip-verify (or --no-verify) opts out entirely.
+const POST_VERIFY_ACTIONS = new Set(['click', 'key', 'submit']);
+const POST_VERIFY_WINDOW_MS_DEFAULT = 1000;
+
+async function probeState() {
+  const r = await fetch(`${baseUrl}/api/browser/probe_state`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id, params: {}, timeout: 2000 }),
+    signal: AbortSignal.timeout(3000),
+  });
+  const j = await r.json();
+  return j.ok ? j.data : null;
+}
+
+async function postVerify(action, params, originalResolved) {
+  if (params.skipVerify) return;
+  const windowMs = Number.isFinite(params.verifyMs) && params.verifyMs > 0
+    ? params.verifyMs
+    : POST_VERIFY_WINDOW_MS_DEFAULT;
+  let before;
+  try { before = await probeState(); } catch { return; }
+  if (!before) return;
+  await new Promise(r => setTimeout(r, windowMs));
+  let after;
+  try { after = await probeState(); } catch { return; }
+  if (!after) return;
+  const urlChanged = before.url !== after.url;
+  const domChanged = before.domHash !== after.domHash || before.domLen !== after.domLen;
+  const newRequests = after.lastNetworkId > before.lastNetworkId;
+  if (!urlChanged && !domChanged && !newRequests) {
+    process.stderr.write(
+      '\n' +
+      CLICK_NO_OP_WARN(action, id, {
+        windowMs,
+        urlChanged,
+        domChanged,
+        newRequests,
+      }) +
+      '\n'
+    );
+  }
+}
+
 async function formatOutput(action, data) {
   if (data === undefined || data === null) {
     // evaluate-family silently returning undefined/null is a major source of
@@ -486,6 +670,86 @@ async function formatOutput(action, data) {
       console.log(data);
       return;
 
+    case 'health':
+      // Server-side bridge health snapshot.
+      if (!data.found) {
+        console.log(`browser "${id}" not registered (no bubble open?)`);
+        process.exit(2);
+      }
+      console.log(
+        `extension: ${data.ws === 'open' ? 'alive (ws=open)' : 'unreachable (ws=' + data.ws + ')'}` +
+        `   pending: ${data.pendingCommands}` +
+        (data.lastSuccessMs !== null
+          ? `   last-success: ${formatMs(data.lastSuccessMs)} ago (${data.lastSuccessAction || '?'})`
+          : '   last-success: never')
+      );
+      return;
+
+    case 'fetch':
+      // Default: pretty JSON. If jsonpath was used, print the extracted value plainly.
+      if (data && typeof data === 'object' && 'jsonpath' in data) {
+        console.log(`[${data.status}] ${data.jsonpath} =`);
+        console.log(typeof data.value === 'object' ? JSON.stringify(data.value, null, 2) : data.value);
+      } else if (data && typeof data === 'object' && 'data' in data) {
+        console.log(`[${data.status}] (${data.contentType || 'unknown'})`);
+        console.log(typeof data.data === 'object' ? JSON.stringify(data.data, null, 2) : data.data);
+      } else {
+        console.log(JSON.stringify(data, null, 2));
+      }
+      return;
+
+    case 'submit':
+      console.log(`submitted: ${data.submitted}${data.action ? `   → ${data.action}` : ''}`);
+      return;
+
+    case 'wait':
+      // Extension returned a structured ack — print one line summary.
+      if (data && data.waited) {
+        console.log(`waited: ${data.waited}${data.elapsedMs != null ? ` (elapsed ${formatMs(data.elapsedMs)})` : ''}`);
+        return;
+      }
+      break;
+
+    case 'reset':
+      if (data && Array.isArray(data.cleared)) {
+        console.log(`cleared: ${data.cleared.join(', ') || '(nothing)'}`);
+        if (data.errors?.length) {
+          for (const e of data.errors) process.stderr.write(`  ⚠ ${e}\n`);
+          process.exit(1);
+        }
+        return;
+      }
+      break;
+
+    case 'set':
+      if (data && data.set) {
+        const note = data.verified === false
+          ? '   ⚠ cookie was not accepted (different domain / SameSite / Secure?)'
+          : data.length != null ? `   (${data.length} bytes)` : '';
+        console.log(`set ${data.set}: ${data.name}${note}`);
+        if (data.verified === false) process.exit(1);
+        return;
+      }
+      break;
+
+    case 'status':
+      if (data && data.url != null) {
+        console.log(`URL:    ${data.url}`);
+        console.log(`Title:  ${data.title}   [${data.readyState}]`);
+        if (data.lastConsoleError) {
+          console.log(`Last console error:  ${data.lastConsoleError.text}   (${data.lastConsoleError.ageSec}s ago)`);
+        }
+        if (data.lastFailedRequest) {
+          const r = data.lastFailedRequest;
+          console.log(`Last failed request: ${r.method} ${r.url} [${r.status}]   (${r.ageSec}s ago)`);
+        }
+        if (Array.isArray(data.topActions) && data.topActions.length) {
+          console.log(`Top actions:         ${data.topActions.map(a => `"${a}"`).join('  ')}`);
+        }
+        return;
+      }
+      break;
+
     case 'screenshot':
       if (data.image) {
         // data URL → save as PNG file, output path (for Read tool to view)
@@ -611,5 +875,13 @@ async function formatOutput(action, data) {
   }
 }
 
+function formatMs(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  return `${m}m${s % 60}s`;
+}
+
 // Export promise for external await
 export const done = run();