surf-cli 2.17.0 → 2.19.0

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: {
@@ -269,7 +294,7 @@ const TOOL_SCHEMAS = {
     desc: "Ask ChatGPT through the browser session",
     schema: {
       query: z.string().describe("Question or prompt"),
-      model: z.string().optional().describe("ChatGPT model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol, or a visible model label"),
+      model: z.string().optional().describe("ChatGPT model: gpt-6-astra, latest, gpt-5.6-sol, gpt-5.5"),
       "with-page": z.boolean().optional().describe("Include current page context"),
       file: z.string().optional().describe("One attachment path"),
       timeout: z.number().optional().describe("Timeout in seconds")

package/native/oracle-cli.cjs

@@ -45,8 +45,8 @@ Commands:
 Ask/follow options:
   --files <glob>          Add context files (repeatable)
   --file <path>           Attach one local file
-  --model <model>         Select model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol
-  --effort <effort>       Select effort: light, standard, extended, heavy, pro
+  --model <model>         Select model: gpt-6-astra, latest, gpt-5.6-sol, gpt-5.5
+  --effort <effort>       Select effort: instant, medium, high, xhigh, pro
   --github                Require the ChatGPT Chat tab and GitHub tool
   --detach                Return after dispatch
   --allow-sensitive       Allow deny-listed context files

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/socket-permissions.cjs

@@ -0,0 +1,114 @@
+const fs = require("fs");
+const { execFileSync } = require("child_process");
+
+const DEFAULT_SOCKET_MODE = 0o600;
+const ALLOWED_SOCKET_MODES = new Set([0o600, 0o660]);
+const MAX_GID = 0xfffffffe;
+const SOCKET_GROUP_PATTERN = /^(?:\d+|[A-Za-z_][A-Za-z0-9_.-]*)$/;
+
+function parseSocketMode(value) {
+  if (value === undefined) return DEFAULT_SOCKET_MODE;
+  if (typeof value === "number" && ALLOWED_SOCKET_MODES.has(value)) return value;
+  if (value === 600) return DEFAULT_SOCKET_MODE;
+  if (value === 660) return 0o660;
+  const text = String(value).trim();
+  if (!/^0?(?:600|660)$/.test(text)) {
+    throw new Error("SURF_SOCKET_MODE must be 600 or 660");
+  }
+  return Number.parseInt(text, 8);
+}
+
+function validateSocketGroup(value) {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value === "boolean") {
+    throw new Error("SURF_SOCKET_GROUP must be a numeric gid or a simple group name");
+  }
+  const group = String(value).trim();
+  if (!SOCKET_GROUP_PATTERN.test(group)) {
+    throw new Error("SURF_SOCKET_GROUP must be a numeric gid or a simple group name");
+  }
+  if (/^\d+$/.test(group)) {
+    const gid = Number(group);
+    if (!Number.isSafeInteger(gid) || gid < 0 || gid > MAX_GID) {
+      throw new Error("SURF_SOCKET_GROUP gid is out of range");
+    }
+  }
+  return group;
+}
+
+function normalizeSocketConfig(socketMode, socketGroup) {
+  const mode = socketMode === undefined ? undefined : parseSocketMode(socketMode);
+  const group = socketGroup === undefined ? undefined : validateSocketGroup(socketGroup);
+  if (mode === 0o660 && !group) {
+    throw new Error("SURF_SOCKET_MODE=660 requires SURF_SOCKET_GROUP");
+  }
+  return { mode, group };
+}
+
+function resolveSocketGroup(value) {
+  const group = validateSocketGroup(value);
+  if (group === undefined) return undefined;
+  if (/^\d+$/.test(group)) return Number(group);
+
+  const command = process.platform === "darwin" ? "dscl" : "getent";
+  const args = process.platform === "darwin"
+    ? [".", "-read", `/Groups/${group}`, "PrimaryGroupID"]
+    : ["group", group];
+  let output;
+  try {
+    output = execFileSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    throw new Error(`could not resolve socket group ${group}: ${error.message}`);
+  }
+  const match = process.platform === "darwin"
+    ? output.match(/\bPrimaryGroupID:\s*(\d+)\b/)
+    : output.trim().split(/\r?\n/, 1)[0]?.split(":")[2]?.match(/^\d+$/);
+  const gid = Number(match?.[1] || match?.[0]);
+  if (!Number.isSafeInteger(gid) || gid < 0 || gid > MAX_GID) {
+    throw new Error(`could not resolve socket group ${group}`);
+  }
+  return gid;
+}
+
+function resolveSocketPermissions(socketMode, socketGroup) {
+  const config = normalizeSocketConfig(socketMode, socketGroup);
+  const mode = config.mode ?? DEFAULT_SOCKET_MODE;
+  const gid = resolveSocketGroup(config.group);
+  return { mode, group: config.group, gid };
+}
+
+function assertSocketPath(socketPath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(socketPath);
+  } catch (error) {
+    throw new Error(`could not inspect local socket: ${error.message}`);
+  }
+  if (stat.isSymbolicLink()) throw new Error("refusing symbolic-link local socket");
+  if (!stat.isSocket()) throw new Error("local socket path is not a Unix socket");
+  return stat;
+}
+
+function applySocketPermissions(socketPath, permissions) {
+  const before = assertSocketPath(socketPath);
+  if (permissions.gid !== undefined) {
+    fs.chownSync(socketPath, before.uid, permissions.gid);
+  }
+  fs.chmodSync(socketPath, permissions.mode);
+  const after = assertSocketPath(socketPath);
+  if ((after.mode & 0o7777) !== permissions.mode) {
+    throw new Error(`local socket mode is not ${permissions.mode.toString(8)}`);
+  }
+  if (permissions.gid !== undefined && after.gid !== permissions.gid) {
+    throw new Error(`local socket group is not ${permissions.group}`);
+  }
+  return after;
+}
+
+module.exports = {
+  applySocketPermissions,
+  normalizeSocketConfig,
+  parseSocketMode,
+  resolveSocketPermissions,
+  validateSocketGroup,
+};

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

@@ -21,7 +21,7 @@ const BROWSER_READ_TOOLS = new Set([
 ]);
 
 const BROWSER_WRITE_TOOLS = new Set([
-  "session.new", "session.ensure", "session.close", "session.rebind", "session.reopen",
+  "session.new", "session.ensure", "session.cleanup", "session.close", "session.rebind", "session.reopen",
   "tab.new", "new_tab", "tabs_create",
   "tab.move", "tab.switch", "switch_tab",
   "tab.group", "tab.ungroup",
@@ -36,7 +36,7 @@ const BROWSER_WRITE_TARGETED_TOOLS = new Set([
 ]);
 
 const TAB_TOOLS = new Set([
-  "ai", "computer", "batch", "record", "animate-audit", "perf-audit",
+  "ai", "computer", "batch", "record", "video.start", "animate-audit", "perf-audit",
   "navigate", "go", "back", "forward", "reload", "tab.reload",
   "screenshot", "snap", "resize",
   "page.read", "read_page", "page.text", "get_page_text", "page.html", "page.save", "page.state",
@@ -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",
@@ -87,10 +87,14 @@ function classifyTool(tool, args = {}) {
     return { scope: "browser-write", targetUse: "default-tab" };
   }
   if (BROWSER_WRITE_TOOLS.has(tool)) return { scope: "browser-write", targetUse: "browser" };
+  if (tool === "video.stop" || tool === "video.status" || tool === "video.restart") {
+    return { scope: "host", targetUse: "host", resourceKeys: ["video-recorder"] };
+  }
   if (TAB_TOOLS.has(tool)) {
     const resourceKeys = [];
     if (tool === "network.export" && typeof args.output === "string") resourceKeys.push(`file:${path.resolve(args.output)}`);
     if (tool.startsWith("playbook.record.")) resourceKeys.push("playbook-recorder");
+    if (tool === "video.start") resourceKeys.push("video-recorder");
     return { scope: "tab", targetUse: "default-tab", resourceKeys };
   }
   return { scope: "browser-write", targetUse: "browser", conservative: true };