surf-cli 2.18.0 → 2.19.0

package/native/host-sessions.cjs

@@ -15,6 +15,9 @@ const QUEUE_TIMEOUT_MS = 60000;
 const DEFAULT_DEADLINE_MS = 60000;
 const MAX_DEADLINE_MS = 50 * 60 * 1000;
 const CLEANUP_GRACE_MS = 60000;
+const READINESS_DEFAULT_TIMEOUT_MS = 20000;
+const READINESS_MAX_TIMEOUT_MS = 120000;
+const READINESS_DEADLINE_GRACE_MS = 5000;
 const PROVIDER_DEFAULT_TIMEOUT_SECONDS = {
   ai: 300,
   aistudio: 300,
@@ -29,6 +32,13 @@ const PROVIDER_DEFAULT_TIMEOUT_SECONDS = {
 };
 
 function resolveRequestDeadlineMs(tool, args = {}) {
+  if (tool === "wait.ready") {
+    const requestedMs = Number(args?.timeout);
+    const timeoutMs = Number.isFinite(requestedMs) && requestedMs > 0
+      ? Math.min(requestedMs, READINESS_MAX_TIMEOUT_MS)
+      : READINESS_DEFAULT_TIMEOUT_MS;
+    return timeoutMs + READINESS_DEADLINE_GRACE_MS;
+  }
   const defaultSeconds = PROVIDER_DEFAULT_TIMEOUT_SECONDS[tool];
   if (defaultSeconds === undefined) return DEFAULT_DEADLINE_MS;
   const rawTimeout = tool === "playbook.run" && args && typeof args === "object" && !Array.isArray(args)

package/native/host.cjs

@@ -20,6 +20,7 @@ const { createOracleHost } = require("./oracle-host.cjs");
 
 const IS_WIN = process.platform === "win32";
 const { SOCKET_PATH, SURF_TMP } = require("./socket-path.cjs");
+const { takeFrames } = require("./stdin-frames.cjs");
 const { parseListenEndpoint } = require("./listener.cjs");
 const { getStateDir } = require("./remote-auth.cjs");
 const { createFrameParser, createServerAuthSession, createSocketWriter, isClientAuthorized, writeFrame, MAX_FRAME_BYTES } = require("./remote-transport.cjs");
@@ -1765,7 +1766,12 @@ function sendToolResponse(socket, id, result, error) {
     }
     if (request?.notice) response.notice = request.notice;
     if (formattedError) response.error = formattedError;
-    else response.result = { content: formatToolContent(output, log, { suppressImages: Boolean(context?.isRemote) }) };
+    else {
+      response.result = { content: formatToolContent(output, log, { suppressImages: Boolean(context?.isRemote) }) };
+      if (request?.tool === "tab.new" && Number.isInteger(output?.tabId) && output.tabId > 0) {
+        response.result.tabId = output.tabId;
+      }
+    }
     if (!context?.closed) await sendSocket(socket, response);
   })().catch((sendError) => log(`Error sending tool_response: ${sendError.message}`));
 }
@@ -2805,25 +2811,23 @@ function writeMessage(msg) {
 let inputBuffer = Buffer.alloc(0);
 
 function processInput() {
-  while (inputBuffer.length >= 4) {
-    const msgLen = inputBuffer.readUInt32LE(0);
-    if (inputBuffer.length < 4 + msgLen) break;
-    
-    const jsonStr = inputBuffer.slice(4, 4 + msgLen).toString("utf8");
-    inputBuffer = inputBuffer.slice(4 + msgLen);
-    
+  // Take every complete frame out of the buffer before dispatching: one
+  // chunk routinely carries a TARGET_EVENT and the reply to a tool request.
+  const { frames, rest } = takeFrames(inputBuffer);
+  inputBuffer = rest;
+  for (const jsonStr of frames) {
     try {
       const msg = JSON.parse(jsonStr);
       log(`Received from extension: ${msg.type || "unknown"}${msg.id !== undefined ? ` id=${msg.id}` : ""}`);
 
       if (msg.type === "EXTENSION_HELLO") {
         setBrowserIdentity(msg);
-        return;
+        continue;
       }
 
       if (msg.type === "TARGET_EVENT") {
         handleTargetEvent(msg);
-        return;
+        continue;
       }
       
       if (msg.type === "GET_AUTH") {
@@ -2847,12 +2851,12 @@ function processInput() {
             hint: "Failed to read auth credentials. Run 'pi --login anthropic' in terminal to authenticate."
           });
         }
-        return;
+        continue;
       }
       
       if (msg.type === "API_REQUEST") {
         handleApiRequest(msg, writeMessage);
-        return;
+        continue;
       }
 
       if (msg.type === "PLAYBOOK_WATCH_EVENT") {
@@ -2865,14 +2869,14 @@ function processInput() {
           tabId: msg.tabId,
           timestamp: msg.timestamp || new Date().toISOString(),
         });
-        return;
+        continue;
       }
 
       if (msg.type === "VIDEO_FRAME") {
         if (activeVideoRecorder && msg.recorderId === activeVideoRecorder.recorderId && msg.tabId === activeVideoRecorder.tabId) {
           activeVideoRecorder.recorder.addFrame(msg.data, Number.isFinite(msg.receivedAt) ? msg.receivedAt : Date.now());
         }
-        return;
+        continue;
       }
 
       if (msg.type === "VIDEO_ERROR") {
@@ -2882,7 +2886,7 @@ function processInput() {
             msg.error || "Video screencast failed",
           ));
         }
-        return;
+        continue;
       }
       
       if (msg.type === "STREAM_EVENT") {
@@ -2894,7 +2898,7 @@ function processInput() {
             stream.socket.destroy(error);
           });
         }
-        return;
+        continue;
       }
 
       if (msg.type === "STREAM_ERROR") {
@@ -2907,7 +2911,7 @@ function processInput() {
             })
             .finally(() => stopActiveStream(msg.streamId));
         }
-        return;
+        continue;
       }
       
       
@@ -2920,13 +2924,13 @@ function processInput() {
           if (topLevelResponse && request?.context) {
             completeOwnedRequest(request.context, request.id, "cleanup-settled");
           }
-          return;
+          continue;
         }
         handleFrameContextFailure(pending.request, msg);
         updateFrameContextFromResult(pending.request, pending.tool, msg);
         if (pending.resolve || pending.onComplete) {
           pendingToolRequests.resolve(msg.id, msg);
-          return;
+          continue;
         }
         pendingToolRequests.delete(msg.id);
         {
@@ -2935,7 +2939,11 @@ function processInput() {
           const tabId = storedTabId || msg._resolvedTabId;
           const failAutoScreenshot = (message) => pending.autoScreenshotOutput
             ? sendToolResponse(socket, originalId, null, `Auto-screenshot failed: ${message}`)
-            : sendToolResponse(socket, originalId, { ...msg, autoScreenshotError: message }, null);
+            : sendToolResponse(socket, originalId, {
+                ...msg,
+                screenshotError: message,
+                autoScreenshotError: message,
+              }, null);
           
           if (pending.networkExport && Array.isArray(msg.entries)) {
             try {
@@ -3026,7 +3034,7 @@ function processInput() {
                 }
               })
               .catch((error) => failAutoScreenshot(error.message));
-            return;
+            continue;
           } else if (autoScreenshot && pending.autoScreenshotOutput && !msg.error) {
             failAutoScreenshot(tabId ? "screenshot response was invalid" : "no tab available");
           } else if (msg.results && msg.savePath) {

package/native/mcp-server.cjs

@@ -159,6 +159,27 @@ const TOOL_SCHEMAS = {
       timeout: z.number().optional().describe("Max wait time in ms")
     }
   },
+  "wait.ready": {
+    desc: "Wait until the page is ready, or fail fast with a typed state (login, challenge, not-found, error)",
+    schema: {
+      selector: z.string().optional().describe("Visible CSS selector that marks a ready page"),
+      text: z.string().optional().describe("Page text that marks a ready page"),
+      urlPrefix: z.string().optional().describe("Expected URL prefix; anything else is a bounce"),
+      emptyText: z.string().optional().describe("Text of an explicit no-results render (state 'empty')"),
+      accept: z.string().optional().describe("Negative states to return instead of fail, comma-separated"),
+      timeout: z.number().optional().describe("Max wait time in ms (default 20000, max 120000)"),
+      interval: z.number().optional().describe("Poll interval in ms (default 400)")
+    }
+  },
+  "page.readiness": {
+    desc: "Classify the page once: ready, empty, loading, login, challenge, not-found, error",
+    schema: {
+      selector: z.string().optional().describe("Visible CSS selector that marks a ready page"),
+      text: z.string().optional().describe("Page text that marks a ready page"),
+      urlPrefix: z.string().optional().describe("Expected URL prefix"),
+      emptyText: z.string().optional().describe("Text of an explicit no-results render")
+    }
+  },
   "wait.load": {
     desc: "Wait for page to fully load",
     schema: { timeout: z.number().optional().describe("Max wait time in ms") }
@@ -242,6 +263,10 @@ const TOOL_SCHEMAS = {
     desc: "List all frames in page",
     schema: {}
   },
+  "frame.diagnose": {
+    desc: "Compare DOM iframes, extension frames (with content-script reachability) and the CDP frame tree, with warnings",
+    schema: {}
+  },
   "frame.js": {
     desc: "Execute JS in specific frame",
     schema: {

package/native/script-options.cjs

@@ -0,0 +1,33 @@
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function parseScriptOptions(input) {
+  if (input === undefined || input === null || input === "") return {};
+  if (input === true) throw new Error("--options needs a JSON object value");
+  let value = input;
+  if (typeof input === "string") {
+    try {
+      value = JSON.parse(input);
+    } catch (error) {
+      throw new Error(`--options is not valid JSON: ${error.message}`);
+    }
+  }
+  if (!isPlainObject(value)) {
+    throw new Error("--options must be a JSON object, e.g. '{\"limit\": 20}'");
+  }
+  // Round-trip so functions, undefined and prototypes cannot leak into the page.
+  return JSON.parse(JSON.stringify(value));
+}
+
+function applyOptionsPrelude(code, options) {
+  const normalized = parseScriptOptions(options);
+  const prelude = `const SURF_OPTIONS = Object.freeze(JSON.parse(${JSON.stringify(JSON.stringify(normalized))}));\n`;
+  const strict = code.match(/^\s*(["'])use strict\1\s*;/);
+  if (!strict) return `${prelude}${code}`;
+  return `${strict[0]}\n${prelude}${code.slice(strict[0].length)}`;
+}
+
+module.exports = { applyOptionsPrelude, parseScriptOptions };

package/native/stdin-frames.cjs

@@ -0,0 +1,33 @@
+/**
+ * Native messaging framing: every message from the extension arrives as a
+ * 4-byte little-endian length followed by that many bytes of UTF-8 JSON.
+ *
+ * One stdin chunk routinely carries several complete frames (a TARGET_EVENT
+ * followed by the reply to a tool request is the common case), so a reader
+ * must take every complete frame out of the buffer before waiting for more
+ * input. Leaving one behind stalls that reply until the extension sends
+ * something else.
+ */
+
+const HEADER_BYTES = 4;
+
+/**
+ * Split `buffer` into complete frames and the unread remainder.
+ *
+ * @param {Buffer} buffer
+ * @returns {{ frames: string[], rest: Buffer }} decoded frame payloads in
+ *   arrival order, and the bytes of any trailing partial frame.
+ */
+function takeFrames(buffer) {
+  const frames = [];
+  let offset = 0;
+  while (buffer.length - offset >= HEADER_BYTES) {
+    const length = buffer.readUInt32LE(offset);
+    if (buffer.length - offset < HEADER_BYTES + length) break;
+    frames.push(buffer.subarray(offset + HEADER_BYTES, offset + HEADER_BYTES + length).toString("utf8"));
+    offset += HEADER_BYTES + length;
+  }
+  return { frames, rest: offset === 0 ? buffer : buffer.subarray(offset) };
+}
+
+module.exports = { takeFrames };

package/native/tool-scope.cjs

@@ -45,8 +45,8 @@ const TAB_TOOLS = new Set([
   "scroll", "scroll.top", "scroll.bottom", "scroll.to", "scroll.info", "scroll_to_position",
   "search", "locate.role", "locate.text", "locate.label", "element.styles",
   "js", "javascript_tool", "eval",
-  "wait.element", "wait.url", "wait.network", "wait.dom", "wait.load", "health",
-  "frame.list", "frame.switch", "frame.main", "frame.js",
+  "wait.element", "wait.url", "wait.network", "wait.dom", "wait.load", "wait.ready", "page.readiness", "health",
+  "frame.list", "frame.diagnose", "frame.switch", "frame.main", "frame.js",
   "dialog.accept", "dialog.dismiss", "dialog.info",
   "console", "network", "network.get", "network.body", "network.curl", "network.path",
   "network.origins", "network.clear", "network.stats", "network.export",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -68,14 +68,14 @@
     "@biomejs/biome": "^2.5.4",
     "@types/chrome": "^0.2.2",
     "@types/node": "^26.1.2",
-    "@vitest/coverage-v8": "^4.1.9",
-    "@vitest/ui": "^4.1.9",
-    "pi-subagents": "^0.58.0",
-    "puppeteer": "25.9.0",
+    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/ui": "^5.0.0",
+    "pi-subagents": "^0.66.0",
+    "puppeteer": "25.10.0",
     "typebox": "^1.3.11",
     "typescript": "^7.0.2",
     "vite": "^8.1.4",
-    "vitest": "^4.1.9"
+    "vitest": "^5.0.0"
   },
   "pi": {
     "extensions": [

package/skills/surf/SKILL.md

@@ -7,6 +7,8 @@ description: Control Chrome browser via CLI for testing, automation, and debuggi
 
 Control Chrome browser via CLI or Unix socket.
 
+Ordinary socket-backed CLI commands report top-level host tool-response errors on stderr with a supplied `[code]` on the first line and exit 1. `--json` additionally writes `{error:{code,message,details?}}` on stdout (missing code becomes `"error"`). `--soft-fail` instead keeps the original stderr warning, empty stdout and exit 0, even with `--json`. This does not cover local validation, transport/parser failures or compound-command errors: do not assume every failure produces JSON. Connection failures remain stderr-only and exit 1, including with `--soft-fail`.
+
 ## Native Host / Socket Notes
 
 For WSL2 with Windows Chrome, run `surf install <extension-id>` inside WSL2. Surf detects WSL2 and writes the Windows-side native messaging manifest plus a wrapper that launches the WSL host. Use `surf install <extension-id> --target linux` only for Linux browsers running inside WSLg.
@@ -34,9 +36,18 @@ surf --remote 100.101.102.103:4321 \
   --remote-credential ~/.config/surf/agent-macbook.json \
   page.read
 
+# TLS is client-side and requires a TLS-terminating reverse proxy in front of SURF_LISTEN
+surf --remote surf.example.com:443 --remote-tls \
+  --remote-tls-ca ~/.config/surf/private-ca.pem \
+  --remote-credential ~/.config/surf/agent-macbook.json page.read
+
 surf remote revoke agent-macbook  # Run on the browser host
 ```
 
+Environment equivalents are `SURF_REMOTE_TLS=1`, `SURF_REMOTE_TLS_CA`, and
+`SURF_REMOTE_TLS_SERVER_NAME`. A custom CA replaces system roots; Ed25519 credentials remain
+mandatory after TLS validation.
+
 Remote paths are client-local by default. `local:./file` is explicit client-local syntax; only `remote:/absolute/path` accesses the browser host directly. Remote transfer supports one upload or ChatGPT/Gemini input and one screenshot, network-export, or Gemini image output. Limits are 256 MiB per file, 512 MiB and 32 files per connection, and 256 KiB decoded chunks. `record`, `aistudio.build`, smoke screenshot directories, directories, and multi-file inputs are not supported remotely. Successful action screenshots and failure `--auto-capture` diagnostics are transferred back to client-local paths.
 
 ## CLI Quick Reference
@@ -321,6 +332,7 @@ surf page.text                 # Plain text content only
 surf page.html --strip-scripts # Rendered HTML without scripts
 surf page.save --selector "#artifact" --strip-scripts --output page.html # Save one static element
 surf page.state                # Modals, loading state, scroll info
+surf frame.diagnose            # Why a selector misses: DOM iframes (incl. open shadow roots) vs extension frames vs CDP tree, with warnings; out-of-process frames need frame.switch, not frame.js
 ```
 
 ### Export Rendered HTML
@@ -398,8 +410,14 @@ surf wait.network              # Wait for network idle
 surf wait.url "/success"       # Wait for URL pattern
 surf wait.dom --stable 100     # Wait for DOM stability
 surf wait.load                 # Wait for page load complete
+surf wait.ready --selector ".results"                 # Ready, or fail fast: login / challenge / not-found / error
+surf wait.ready --url-prefix "https://app.example.com/" --empty-text "No results"  # empty vs blocked
+surf wait.ready --accept login --json                 # Return the negative state instead of failing
+surf page.readiness --json     # Classify the current page once (state + evidence)
 ```
 
+Typed readiness states replace "the selector never appeared": exit codes carry `page_login`, `page_challenge`, `page_not_found`, `page_error` or `page_timeout`. Detection uses visible UI (a rendered password field, a login route, the page's wording, a URL outside `--url-prefix`), not site selectors.
+
 ## Dialog Handling
 
 ```bash