surf-cli 2.19.0 → 2.20.0

package/native/host-helpers.cjs

@@ -228,6 +228,21 @@ function formatToolContent(result, log = () => {}, options = {}) {
     ];
   }
   
+  if (result.semanticObservation !== undefined) {
+    return text(JSON.stringify({
+      pageContent: result.pageContent,
+      viewport: result.viewport,
+      semanticObservation: result.semanticObservation,
+    }));
+  }
+
+  if (
+    result.identity !== undefined && result.matches !== undefined ||
+    result.scopeToken !== undefined && result.geometry !== undefined
+  ) {
+    return text(JSON.stringify(result));
+  }
+
   if (result.pageContent !== undefined) {
     const content = result.pageContent || "No content";
     let output = '';
@@ -442,6 +457,11 @@ function formatToolContent(result, log = () => {}, options = {}) {
 
   // Bug fix: Handle success with metrics/frames/readyState/hint in one block
   if (result.success) {
+    // Keep the response envelope intact so the CLI can print body bytes verbatim
+    // for text output while still producing structured output under --json.
+    if (typeof result.body === "string" && Object.hasOwn(result, "base64Encoded")) {
+      return text(JSON.stringify(result));
+    }
     if (result.metrics) {
       return text(JSON.stringify(result.metrics, null, 2));
     }
@@ -501,7 +521,7 @@ function mapComputerAction(args, tabId) {
   const { action, text, scroll_direction, scroll_amount, 
           start_coordinate, ref, duration, modifiers } = a;
   const coordinate = a.coordinate || (a.x !== undefined && a.y !== undefined ? [a.x, a.y] : undefined);
-  const baseMsg = { tabId };
+  const baseMsg = { tabId, ...(Number.isInteger(a.semanticFrameId) ? { frameId: a.semanticFrameId } : {}) };
   
   if (!action) {
     return { type: "UNSUPPORTED_ACTION", action: null, message: "No action specified for computer tool" };
@@ -512,7 +532,7 @@ function mapComputerAction(args, tabId) {
       return { type: "EXECUTE_SCREENSHOT", ...baseMsg };
     
     case "left_click":
-      if (ref) return { type: "CLICK_REF", ref, button: "left", ...baseMsg };
+      if (ref) return { type: "CLICK_REF", ref, button: "left", expectedIdentity: a.semanticExpectedIdentity, ...baseMsg };
       if (a.selector) return { type: "CLICK_SELECTOR", selector: a.selector, index: a.index || 0, button: "left", ...baseMsg };
       return { type: "EXECUTE_CLICK", x: coordinate?.[0], y: coordinate?.[1], modifiers, ...baseMsg };
     
@@ -530,7 +550,7 @@ function mapComputerAction(args, tabId) {
     
     case "type": {
       if (ref) {
-        return { type: "FORM_FILL", data: [{ ref, value: text }], ...baseMsg };
+        return { type: "FORM_FILL", data: [{ ref, value: text }], expectedIdentity: a.semanticExpectedIdentity, ...baseMsg };
       }
       const typeSelector = a.selector || a.into;
       if (typeSelector) {
@@ -570,7 +590,7 @@ function mapComputerAction(args, tabId) {
         right: { deltaX: amount, deltaY: 0 },
       };
       const { deltaX, deltaY } = deltas[direction] || { deltaX: 0, deltaY: 0 };
-      return { type: "EXECUTE_SCROLL", deltaX, deltaY, x: coordinate?.[0], y: coordinate?.[1], ...baseMsg };
+      return { type: "EXECUTE_SCROLL", deltaX, deltaY, x: coordinate?.[0], y: coordinate?.[1], expectedIdentity: a.semanticExpectedIdentity, ...baseMsg };
     }
     
     case "scroll_to":
@@ -609,14 +629,14 @@ function mapComputerAction(args, tabId) {
  * Map tool name and args to extension message
  */
 function mapToolToMessage(tool, args, tabId) {
-  const baseMsg = { tabId };
   const a = args || {};
+  const baseMsg = { tabId, ...(Number.isInteger(a.semanticFrameId) ? { frameId: a.semanticFrameId } : {}) };
   
   switch (tool) {
     case "computer":
       return mapComputerAction(args, tabId);
     case "navigate":
-      return { type: "EXECUTE_NAVIGATE", url: a.url, ...baseMsg };
+      return { type: "EXECUTE_NAVIGATE", url: a.url, expectedIdentity: a.semanticExpectedIdentity, ...baseMsg };
     case "read_page":
       return { 
         type: "READ_PAGE", 
@@ -880,9 +900,9 @@ function mapToolToMessage(tool, args, tabId) {
     case "js":
       return { type: "EXECUTE_JAVASCRIPT", code: a.code, ...baseMsg };
     case "scroll.top":
-      return { type: "SCROLL_TO_POSITION", position: "top", selector: a.selector, ...baseMsg };
+      return { type: "SCROLL_TO_POSITION", position: "top", selector: a.selector, expectedIdentity: a.semanticExpectedIdentity, ...baseMsg };
     case "scroll.bottom":
-      return { type: "SCROLL_TO_POSITION", position: "bottom", selector: a.selector, ...baseMsg };
+      return { type: "SCROLL_TO_POSITION", position: "bottom", selector: a.selector, expectedIdentity: a.semanticExpectedIdentity, ...baseMsg };
     case "scroll.info":
       return { type: "GET_SCROLL_INFO", selector: a.selector, ...baseMsg };
     case "scroll.to":
@@ -966,7 +986,7 @@ function mapToolToMessage(tool, args, tabId) {
       if (typeof fillData === "string") {
         try { fillData = JSON.parse(fillData); } catch (e) { throw new Error("invalid --data JSON"); }
       }
-      return { type: "FORM_FILL", data: fillData, ...baseMsg };
+      return { type: "FORM_FILL", data: fillData, expectedIdentity: a.semanticExpectedIdentity, ...baseMsg };
     case "perf.start":
       return { type: "PERF_START", categories: a.categories ? a.categories.split(",") : undefined, ...baseMsg };
     case "perf.stop":
@@ -998,10 +1018,30 @@ function mapToolToMessage(tool, args, tabId) {
           compact: a.compact || false,
           maxBytes,
           forceFullSnapshot: a.compact === true || maxBytes !== undefined,
+          ...(a.semanticObservation === true ? { semanticObservation: true } : {}),
         },
         ...baseMsg
       };
     }
+    case "semantic.localCompare":
+      return {
+        type: "SEMANTIC_LOCAL_COMPARE",
+        ref: a.ref,
+        predicate: a.predicate,
+        expectedIdentity: a.semanticExpectedIdentity,
+        ...baseMsg,
+      };
+    case "semantic.scrollScope":
+      if (!["inspect", "top", "advance"].includes(a.action)) {
+        throw new Error("semantic scroll scope action must be inspect, top, or advance");
+      }
+      return {
+        type: "SEMANTIC_SCROLL_SCOPE",
+        action: a.action,
+        scopeToken: a.scopeToken,
+        expectedIdentity: a.semanticExpectedIdentity,
+        ...baseMsg,
+      };
     case "page.text":
       return { type: "GET_PAGE_TEXT", ...baseMsg };
     case "page.html":
@@ -1317,4 +1357,49 @@ function mapToolToMessage(tool, args, tabId) {
   }
 }
 
-module.exports = { mapToolToMessage, mapComputerAction, formatToolContent, formatToolError, buildProviderUploadMessage, readinessExpectations };
+function applySemanticExpectedIdentity(request, extensionMessage, args) {
+  const fail = (code, message) => {
+    const error = new Error(message);
+    error.code = code;
+    throw error;
+  };
+  const expected = args?.semanticExpectedIdentity;
+  const identityRequired = ["SEMANTIC_LOCAL_COMPARE", "SEMANTIC_SCROLL_SCOPE"].includes(extensionMessage?.type);
+  if (expected === undefined) {
+    if (identityRequired) fail("invalid_expected_identity", "semantic expected identity is required for this action");
+    return;
+  }
+  const guardedTypes = [
+    "CLICK_REF", "FORM_FILL", "EXECUTE_NAVIGATE", "EXECUTE_SCROLL", "SCROLL_TO_POSITION",
+    "SEMANTIC_LOCAL_COMPARE", "SEMANTIC_SCROLL_SCOPE",
+  ];
+  if (!extensionMessage || !guardedTypes.includes(extensionMessage.type)) {
+    fail("invalid_expected_identity", "semantic expected identity is not valid for this action");
+  }
+  const domAction = ["CLICK_REF", "FORM_FILL", "SEMANTIC_LOCAL_COMPARE"].includes(extensionMessage.type);
+  const stringFields = ["browserEpoch", "fullUrl", "documentToken", ...(domAction ? ["ref", "role", "name", "type"] : [])];
+  if (!expected || typeof expected !== "object" || stringFields.some((field) => typeof expected[field] !== "string")) {
+    fail("invalid_expected_identity", "invalid semantic expected identity");
+  }
+  if (!Number.isInteger(expected.tabId) || !Number.isInteger(expected.frameId)) {
+    fail("invalid_expected_identity", "invalid semantic expected identity");
+  }
+  const actualFrameId = Number.isInteger(extensionMessage.frameId) ? extensionMessage.frameId : 0;
+  if (
+    request?.browserIdentity?.browserEpoch !== expected.browserEpoch ||
+    request?.target?.tabId !== expected.tabId ||
+    actualFrameId !== expected.frameId ||
+    domAction && extensionMessage.ref && extensionMessage.ref !== expected.ref ||
+    extensionMessage.type === "FORM_FILL" &&
+      (!Array.isArray(extensionMessage.data) || extensionMessage.data.length !== 1 || extensionMessage.data[0]?.ref !== expected.ref)
+  ) {
+    fail("stale_observation", "stale_observation");
+  }
+  extensionMessage.expectedIdentity = {
+    fullUrl: expected.fullUrl,
+    documentToken: expected.documentToken,
+    ...(domAction ? { ref: expected.ref, role: expected.role, name: expected.name, type: expected.type } : {}),
+  };
+}
+
+module.exports = { mapToolToMessage, mapComputerAction, formatToolContent, formatToolError, buildProviderUploadMessage, readinessExpectations, applySemanticExpectedIdentity };

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,7 +27,7 @@ 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";
@@ -844,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) {
@@ -1497,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);
@@ -1720,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;
     }
@@ -1905,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);

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