surf-cli 2.18.0 → 2.20.0

package/native/host.cjs

@@ -1,4 +1,16 @@
 #!/usr/bin/env node
+const LAUNCH_PROBE_ARGUMENT = "--surf-native-host-launch-probe";
+const LAUNCH_PROBE_MARKER = "SURF_NATIVE_HOST_LAUNCH_PROBE_OK";
+
+if (process.argv.length === 3 && process.argv[2] === LAUNCH_PROBE_ARGUMENT) {
+  process.stdout.write(`${LAUNCH_PROBE_MARKER}\n`);
+  process.exit(0);
+}
+if (process.argv.length === 3 && process.argv[2] === `${LAUNCH_PROBE_ARGUMENT}-distro`) {
+  process.stdout.write(`${LAUNCH_PROBE_MARKER}:${JSON.stringify(process.env.WSL_DISTRO_NAME || null)}\n`);
+  process.exit(0);
+}
+
 const net = require("net");
 const fs = require("fs");
 const path = require("path");
@@ -15,11 +27,12 @@ const grokClient = require("./grok-client.cjs");
 const kimiClient = require("./kimi-client.cjs");
 const aistudioClient = require("./aistudio-client.cjs");
 const aistudioBuild = require("./aistudio-build.cjs");
-const { mapToolToMessage, mapComputerAction, formatToolContent, formatToolError, buildProviderUploadMessage } = require("./host-helpers.cjs");
+const { mapToolToMessage, mapComputerAction, formatToolContent, formatToolError, buildProviderUploadMessage, applySemanticExpectedIdentity } = require("./host-helpers.cjs");
 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");
@@ -843,7 +856,7 @@ function currentFrameContext(request) {
 function applyFrameContextToMessage(request, extensionMessage) {
   if (!extensionMessage || !FRAME_CONTEXT_MESSAGE_TYPES.has(extensionMessage.type)) return;
   const context = currentFrameContext(request);
-  if (context) extensionMessage.frameId = context.frameId;
+  if (context && !Number.isInteger(extensionMessage.frameId)) extensionMessage.frameId = context.frameId;
 }
 
 function persistFrameContext(request, frameId, url) {
@@ -1496,6 +1509,7 @@ async function executeMappedHostTool(request, tool, args, tabId) {
   if (!extensionMsg) throw new Error(`Unknown tool: ${tool}`);
   if (request.target?.strict) extensionMsg.strictTarget = true;
   applyFrameContextToMessage(request, extensionMsg);
+  applySemanticExpectedIdentity(request, extensionMsg, args);
   if (extensionMsg.type === "UNSUPPORTED_ACTION") throw new Error(extensionMsg.message);
   if (extensionMsg.type === "LOCAL_WAIT") {
     await abortableDelay(extensionMsg.seconds * 1000, request.signal);
@@ -1719,6 +1733,9 @@ function sendToolResponse(socket, id, result, error) {
     let output = result;
     try {
       if (!error) output = await sendRequestDownloads(context, request, result);
+      if (!error && output?.semanticObservation?.identity && request?.target) {
+        output.semanticObservation.identity.browserEpoch = request.target.browserEpoch;
+      }
     } catch (transferFailure) {
       finalError = transferFailure.message;
     }
@@ -1765,7 +1782,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}`));
 }
@@ -1899,6 +1921,12 @@ function handleToolRequest(msg, socket, requestContext = requestStorage.getStore
   }
   if (requestContext.target?.strict) extensionMsg.strictTarget = true;
   applyFrameContextToMessage(requestContext, extensionMsg);
+  try {
+    applySemanticExpectedIdentity(requestContext, extensionMsg, args);
+  } catch (error) {
+    sendToolResponse(socket, originalId, null, error);
+    return;
+  }
   
   if (extensionMsg.type === "UNSUPPORTED_ACTION") {
     sendToolResponse(socket, originalId, null, extensionMsg.message);
@@ -2805,25 +2833,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 +2873,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 +2891,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 +2908,7 @@ function processInput() {
             msg.error || "Video screencast failed",
           ));
         }
-        return;
+        continue;
       }
       
       if (msg.type === "STREAM_EVENT") {
@@ -2894,7 +2920,7 @@ function processInput() {
             stream.socket.destroy(error);
           });
         }
-        return;
+        continue;
       }
 
       if (msg.type === "STREAM_ERROR") {
@@ -2907,7 +2933,7 @@ function processInput() {
             })
             .finally(() => stopActiveStream(msg.streamId));
         }
-        return;
+        continue;
       }
       
       
@@ -2920,13 +2946,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 +2961,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 +3056,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/native-host-launch-probe.cjs

@@ -0,0 +1,69 @@
+const { execFileSync } = require("child_process");
+const { runWindowsExecutable } = require("../scripts/windows-interop.cjs");
+
+const LAUNCH_PROBE_ARGUMENT = "--surf-native-host-launch-probe";
+const LAUNCH_PROBE_MARKER = "SURF_NATIVE_HOST_LAUNCH_PROBE_OK";
+const WRAPPER_PROBE_CAPABILITY_MARKER = "rem SURF_NATIVE_HOST_LAUNCH_PROBE_V1";
+const LAUNCH_PROBE_TIMEOUT_MS = 5000;
+
+function renderWslWrapper(nodePath, hostPath, distro) {
+  const path = require("path");
+  for (const value of [nodePath, hostPath, distro].filter((value) => value !== undefined)) {
+    if (/["%!\r\n]/.test(value)) throw new Error("WSL wrapper path or distro contains unsupported batch characters");
+  }
+  const distroArg = distro ? ` -d "${distro}"` : "";
+  return `@echo off\r\n${WRAPPER_PROBE_CAPABILITY_MARKER}\r\nwsl.exe${distroArg} --cd "${path.dirname(hostPath)}" --exec "${nodePath}" "${hostPath}" %*\r\n`;
+}
+
+function probeWindowsWrapper(wrapperPath, deps = {}) {
+  if (!/^[a-z]:\\[^"%\r\n]*\.cmd$/i.test(wrapperPath) || /[&|<>^!]/.test(wrapperPath)) {
+    throw new Error("Native host wrapper path cannot be safely passed to cmd.exe");
+  }
+  let output;
+  try {
+    output = runWindowsExecutable(
+      "cmd.exe",
+      ["/d", "/s", "/c", `""${wrapperPath}" ${LAUNCH_PROBE_ARGUMENT}${deps.verifyDistro ? "-distro" : ""}"`],
+      {
+        execFileSync: deps.execFileSync || execFileSync,
+        allowWslFallback: true,
+        execOptions: {
+          encoding: "utf8",
+          timeout: deps.timeoutMs ?? LAUNCH_PROBE_TIMEOUT_MS,
+          maxBuffer: 64 * 1024,
+          windowsHide: true,
+        },
+      },
+    );
+  } catch (error) {
+    throw new Error(`Native host wrapper launch probe failed: ${error.message}`);
+  }
+
+  const response = String(output).trim();
+  if (deps.verifyDistro) {
+    if (!response.startsWith(`${LAUNCH_PROBE_MARKER}:`)) {
+      throw new Error("Native host wrapper launch probe failed: host returned unexpected output");
+    }
+    let distro;
+    try {
+      distro = JSON.parse(response.slice(LAUNCH_PROBE_MARKER.length + 1));
+    } catch {
+      throw new Error("Native host wrapper launch probe failed: invalid distro identity");
+    }
+    if (distro !== null && (typeof distro !== "string" || !distro)) {
+      throw new Error("Native host wrapper launch probe failed: invalid distro identity");
+    }
+    return distro;
+  }
+  if (response !== LAUNCH_PROBE_MARKER) {
+    throw new Error("Native host wrapper launch probe failed: host returned unexpected output");
+  }
+}
+
+module.exports = {
+  LAUNCH_PROBE_ARGUMENT,
+  LAUNCH_PROBE_MARKER,
+  WRAPPER_PROBE_CAPABILITY_MARKER,
+  renderWslWrapper,
+  probeWindowsWrapper,
+};

package/native/private-state.cjs

@@ -30,6 +30,19 @@ function assertWithin(root, targetPath) {
   return resolvedTarget;
 }
 
+function assertPrivatePath(targetPath, root, allowMissing) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = assertWithin(resolvedRoot, targetPath);
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  let current = resolvedRoot;
+  for (const segment of ["", ...relative.split(path.sep).filter(Boolean)]) {
+    if (segment) current = path.join(current, segment);
+    const stat = assertNotSymlink(current, allowMissing);
+    if (!stat) return null;
+  }
+  return fs.lstatSync(resolvedTarget);
+}
+
 function ensurePrivateDir(dirPath, root = getPrivateStateRoot()) {
   const resolvedRoot = path.resolve(root);
   const resolvedDir = assertWithin(resolvedRoot, dirPath);
@@ -129,13 +142,23 @@ function readPrivateFile(filePath, options = {}) {
   const resolved = path.resolve(filePath);
   const root = options.root || getPrivateStateRoot();
   assertWithin(root, resolved);
-  const stat = assertNotSymlink(resolved, options.allowMissing === true);
+  const stat = assertPrivatePath(resolved, root, options.allowMissing === true);
   if (!stat) return options.fallback;
   if (!stat.isFile()) throw new Error(`private state path is not a file: ${resolved}`);
   if (process.platform !== "win32" && (stat.mode & 0o077) !== 0) throw new Error(`private state file permissions are too broad: ${resolved}`);
   return fs.readFileSync(resolved, options.encoding || null);
 }
 
+function removePrivateFile(filePath, options = {}) {
+  const resolved = path.resolve(filePath);
+  const root = options.root || getPrivateStateRoot();
+  const stat = assertPrivatePath(resolved, root, true);
+  if (!stat) return false;
+  if (!stat.isFile()) throw new Error(`private state path is not a file: ${resolved}`);
+  fs.unlinkSync(resolved);
+  return true;
+}
+
 function readPrivateJson(filePath, fallback = null, options = {}) {
   const content = readPrivateFile(filePath, { ...options, allowMissing: true, fallback: null, encoding: "utf8" });
   return content === null ? fallback : JSON.parse(content);
@@ -152,5 +175,6 @@ module.exports = {
   privateStatePath,
   readPrivateFile,
   readPrivateJson,
+  removePrivateFile,
   writePrivateFileExclusive,
 };

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