surf-cli 2.10.0 → 2.12.0

package/native/cli.cjs

@@ -19,6 +19,11 @@ const {
 const { executeDoSteps } = require("./do-executor.cjs");
 const { openClientTransport } = require("./client-transport.cjs");
 const { version: VERSION } = require("../package.json");
+const {
+  formatOracleError,
+  formatOracleOutput,
+  handleOracleCli,
+} = require("./oracle-cli.cjs");
 const { formatPlaybookOutput, handlePlaybookCli, playbookCommandNeedsBrowser } = require("./playbook-cli.cjs");
 
 const IS_WIN = process.platform === "win32";
@@ -73,6 +78,28 @@ function installBrowserLock({ noLock, timeoutMs }, endpoint) {
   });
 }
 
+async function runWithBrowserLock(lockOptions, endpoint, operation) {
+  let releaseBrowserLock = () => {};
+  if (!lockOptions.noLock) {
+    const lock = acquireBrowserLock(endpoint.key, SURF_TMP, {
+      timeoutMs: lockOptions.timeoutMs,
+    });
+    releaseBrowserLock = lock.release;
+  }
+  const release = () => {
+    const releaseCurrent = releaseBrowserLock;
+    releaseBrowserLock = () => {};
+    releaseCurrent();
+  };
+  process.once("exit", release);
+  try {
+    return await operation();
+  } finally {
+    process.removeListener("exit", release);
+    release();
+  }
+}
+
 // Cross-platform image resize (macOS: sips, Linux: ImageMagick)
 function resizeImage(filePath, maxSize) {
   const platform = process.platform;
@@ -153,6 +180,28 @@ try {
   process.exit(1);
 }
 
+if (args[0] === "oracle") {
+  handleOracleCli(args, {
+    endpoint,
+    cwd: process.cwd(),
+    withBrowserLock: (operation) => runWithBrowserLock(
+      parseBrowserLockOptions(args.includes("--no-lock")),
+      endpoint,
+      operation,
+    ),
+  })
+    .then((result) => {
+      if (!result.handled) throw new Error("Oracle command was not handled");
+      if (result.value !== undefined) console.log(formatOracleOutput(result.value, result.json));
+      process.exit(0);
+    })
+    .catch((error) => {
+      console.error(formatOracleError(error, args.includes("--json")));
+      process.exit(1);
+    });
+  return;
+}
+
 if (["playbook", "pb", "use"].includes(args[0])) {
   if (playbookCommandNeedsBrowser(args)) {
     installBrowserLock(parseBrowserLockOptions(args.includes("--no-lock")), endpoint);
@@ -484,7 +533,7 @@ const TOOLS = {
       "scroll": {
         desc: "Scroll in direction",
         args: ["direction", "pixels"],
-        opts: { direction: "up|down|left|right", amount: "Scroll amount (1-10)" },
+        opts: { direction: "up|down|left|right", amount: "Scroll amount in 100 px steps (1-10)" },
         examples: [
           { cmd: "scroll down 800", desc: "Scroll down 800px" },
           { cmd: "scroll --direction down --amount 3", desc: "Scroll down" },
@@ -527,6 +576,18 @@ const TOOLS = {
       },
       "read": { desc: "Alias for page.read", args: [], alias: "page.read" },
       "page.text": { desc: "Extract all text from page", args: [] },
+      "page.html": {
+        desc: "Print rendered document HTML",
+        args: [],
+        opts: { selector: "Export matching CSS selector", "strip-scripts": "Remove script elements" },
+        examples: [{ cmd: "page.html", desc: "Print current document HTML" }],
+      },
+      "page.save": {
+        desc: "Save rendered document HTML",
+        args: [],
+        opts: { output: "File path", selector: "Export matching CSS selector", "strip-scripts": "Remove script elements" },
+        examples: [{ cmd: "page.save --output page.html", desc: "Save current document HTML" }],
+      },
       "page.state": { desc: "Get page state (modals, loading, etc.)", args: [] },
     }
   },
@@ -1415,7 +1476,7 @@ const ALL_SOCKET_TOOLS = [
   "click_type", "click_type_submit", "type", "key", "type_submit",
   "scroll", "scroll_to", "hover", "left_click_drag", "drag", "wait",
   "computer",
-  "page.read", "page.text", "page.state",
+  "page.read", "page.text", "page.html", "page.save", "page.state",
   "locate.role", "locate.text", "locate.label",
   "tab.list", "tab.new", "tab.switch", "tab.close", "tab.move", "tab.name", "tab.unname", "tab.named",
   "tab.group", "tab.ungroup", "tab.groups", "tab.reload",
@@ -1496,6 +1557,7 @@ Common Commands:
   search <term>      Search for text in page (alias: find)
   window.new <url>   Create isolated browser window
   doctor             Diagnose native host/socket setup
+  oracle ask <prompt> Start a durable ChatGPT consult
   wait <seconds>     Wait N seconds
 
 Quick Examples:
@@ -1555,6 +1617,9 @@ const showFullHelp = () => {
 
 Usage: surf <command> [args] [options]
 
+Oracle:
+  surf oracle <ask|status|result|follow|list>
+
 Playbooks:
   surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>
   surf use <playbook> <op> [--arg value]
@@ -2765,11 +2830,16 @@ if (tool === "network.export" && outputPath !== undefined) {
   toolArgs.output = outputPath;
 }
 
-if ((tool === "screenshot" || tool === "record" || tool === "perf-audit") && outputPath && typeof outputPath !== "string") {
+if ((tool === "screenshot" || tool === "record" || tool === "perf-audit" || tool === "page.save") && outputPath && typeof outputPath !== "string") {
   console.error("Error: --output requires a file path");
   process.exit(1);
 }
 
+if (tool === "page.save" && !outputPath) {
+  console.error("Error: page.save requires --output <path>");
+  process.exit(1);
+}
+
 if (tool === "screenshot" && outputPath) {
   toolArgs.savePath = outputPath;
   if (options.full) toolArgs.full = true;
@@ -3241,6 +3311,17 @@ async function handleResponse(response) {
     data = { response: data };
   }
 
+  if (tool === "page.save" && typeof data?.html === "string") {
+    const saveTo = path.resolve(outputPath);
+    fs.mkdirSync(path.dirname(saveTo), { recursive: true });
+    fs.writeFileSync(saveTo, data.html);
+    if (!wantJson) {
+      console.log(`Saved rendered page HTML to ${saveTo}`);
+      socket.end();
+      process.exit(0);
+    }
+  }
+
   if (tool === "perf-audit" && outputPath) {
     const saveTo = path.resolve(outputPath);
     fs.mkdirSync(path.dirname(saveTo), { recursive: true });
@@ -3322,6 +3403,8 @@ async function handleResponse(response) {
     console.log(data.pageContent);
   } else if (tool === "page.text" && data?.text) {
     console.log(data.text);
+  } else if (tool === "page.html" && typeof data?.html === "string") {
+    console.log(data.html);
   } else if (tool === "emulate.device" && data?.devices) {
     console.log("Available devices:\n");
     const devices = data.devices;

package/native/host-helpers.cjs

@@ -13,6 +13,21 @@ function normalizeModelString(model) {
   return String(model || "").trim().toLowerCase();
 }
 
+function formatToolError(error) {
+  const message = error instanceof Error
+    ? error.message
+    : typeof error === "string"
+      ? error
+      : error?.message || String(error);
+  const result = { content: [{ type: "text", text: message }] };
+  if (error && typeof error === "object") {
+    result.message = message;
+    if (typeof error.code === "string") result.code = error.code;
+    if (typeof error.jobId === "string") result.jobId = error.jobId;
+  }
+  return result;
+}
+
 /**
  * Format tool result content for MCP response
  * @param {*} result - The result object from the extension
@@ -921,6 +936,18 @@ function mapToolToMessage(tool, args, tabId) {
     }
     case "page.text":
       return { type: "GET_PAGE_TEXT", ...baseMsg };
+    case "page.html":
+    case "page.save": {
+      if (a.selector !== undefined && (typeof a.selector !== "string" || a.selector.length === 0)) {
+        throw new Error("selector must be a non-empty string");
+      }
+      return {
+        type: "GET_PAGE_HTML",
+        selector: a.selector,
+        stripScripts: a["strip-scripts"] === true,
+        ...baseMsg,
+      };
+    }
     case "page.state":
       return { type: "PAGE_STATE", ...baseMsg };
     case "locate.role":
@@ -1082,6 +1109,16 @@ function mapToolToMessage(tool, args, tabId) {
     case "history.search":
       if (!a.query) throw new Error("query required");
       return { type: "HISTORY_SEARCH", query: a.query, limit: a.limit !== undefined ? parseInt(a.limit, 10) : 20 };
+    case "oracle.ask":
+      if (!a.prompt) throw new Error("prompt required");
+      return { ...a, type: "ORACLE_ASK" };
+    case "oracle.status":
+      return { ...a, type: "ORACLE_STATUS" };
+    case "oracle.result":
+      if (!a.id) throw new Error("id required");
+      return { ...a, type: "ORACLE_RESULT" };
+    case "oracle.list":
+      return { type: "ORACLE_LIST" };
     case "chatgpt":
       if (!a.query) throw new Error("query required");
       return { 
@@ -1196,4 +1233,4 @@ function mapToolToMessage(tool, args, tabId) {
   }
 }
 
-module.exports = { mapToolToMessage, mapComputerAction, formatToolContent, buildProviderUploadMessage };
+module.exports = { mapToolToMessage, mapComputerAction, formatToolContent, formatToolError, buildProviderUploadMessage };

package/native/host-sessions.cjs

@@ -23,6 +23,7 @@ const PROVIDER_DEFAULT_TIMEOUT_SECONDS = {
   gemini: 300,
   grok: 300,
   perplexity: 120,
+  "oracle.result": 300,
   "playbook.run": 600,
 };
 

package/native/host.cjs

@@ -14,7 +14,8 @@ const perplexityClient = require("./perplexity-client.cjs");
 const grokClient = require("./grok-client.cjs");
 const aistudioClient = require("./aistudio-client.cjs");
 const aistudioBuild = require("./aistudio-build.cjs");
-const { mapToolToMessage, mapComputerAction, formatToolContent, buildProviderUploadMessage } = require("./host-helpers.cjs");
+const { mapToolToMessage, mapComputerAction, formatToolContent, formatToolError, buildProviderUploadMessage } = 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");
@@ -402,6 +403,15 @@ aiQueue = new BoundedAiQueue({
     : handler(),
 });
 
+const oracleHost = createOracleHost({
+  queueAiRequest,
+  requestCallExtension,
+  buildProviderUploadMessage,
+  log,
+});
+const adoptedOracleJobs = oracleHost.adoptOrphans();
+log(`Oracle adoption: ${adoptedOracleJobs.length} job(s); ids=${adoptedOracleJobs.map((job) => job.id).join(",") || "none"}`);
+
 function sendSocket(socket, value, options = {}) {
   const writer = socketWriters.get(socket);
   return writer ? writer.send(value, options) : writeFrame(socket, value);
@@ -513,6 +523,7 @@ async function runHostPlaybook(msg, request) {
     onEvent: report,
     beforeDispatch: async () => updateReceipt(receipt, "dispatched"),
     afterDispatch: async ({ status, error }) => updateReceipt(receipt, status, { error }),
+    allowScript: params.allowScript === true,
   });
 }
 
@@ -672,8 +683,14 @@ function sendToolResponse(socket, id, result, error) {
     } catch (transferFailure) {
       finalError = transferFailure.message;
     }
-    if (finalError && request) {
-      finalError = rewriteTransferPaths(finalError, request.pathRewrites || []);
+    const formattedError = finalError ? formatToolError(finalError) : null;
+    if (formattedError && request) {
+      const rewrittenMessage = rewriteTransferPaths(
+        formattedError.content[0].text,
+        request.pathRewrites || [],
+      );
+      formattedError.content[0].text = rewrittenMessage;
+      if (formattedError.message) formattedError.message = rewrittenMessage;
     }
     if (request?.tool && !request.tool.startsWith("playbook.")) {
       const metadata = commandMetadata(request.tool);
@@ -697,7 +714,7 @@ function sendToolResponse(socket, id, result, error) {
       : finalError ? "error" : "completed";
     await completeOwnedRequest(context, id, outcome);
     const response = { type: "tool_response", id };
-    if (finalError) response.error = { content: [{ type: "text", text: finalError }] };
+    if (formattedError) response.error = formattedError;
     else response.result = { content: formatToolContent(output, log, { suppressImages: Boolean(context?.isRemote) }) };
     if (!context?.closed) await sendSocket(socket, response);
   })().catch((sendError) => log(`Error sending tool_response: ${sendError.message}`));
@@ -800,6 +817,13 @@ function handleToolRequest(msg, socket, requestContext = requestStorage.getStore
       .catch((error) => sendToolResponse(socket, originalId, null, error.message));
     return;
   }
+
+  if (extensionMsg.type.startsWith("ORACLE_")) {
+    Promise.resolve(oracleHost.handle(requestContext, extensionMsg))
+      .then((result) => sendToolResponse(socket, originalId, result, null))
+      .catch((error) => sendToolResponse(socket, originalId, null, error));
+    return;
+  }
   
   if (extensionMsg.type === "BATCH_EXECUTE") {
     executeBatch(extensionMsg.actions, extensionMsg.tabId, socket, originalId, requestContext);
@@ -1948,6 +1972,7 @@ const handleClient = (socket) => {
       }
       log(`Handling tool_request: ${msg.method} ${tool}${principal ? ` for ${principal.label}` : ""}`);
       try {
+        if (tool.startsWith("oracle.")) oracleHost.assertLocal(request);
         if (isRemote) {
           await applyRequestTransfers(msg, request, transferState, ensureTransferState);
         }
@@ -1955,7 +1980,7 @@ const handleClient = (socket) => {
         requestStorage.run(request, () => handleToolRequest(msg, socket, request));
       } catch (e) {
         await discardRequestTransfers(msg, transferState);
-        sendToolResponse(socket, msg.id || null, null, e.message || "Request failed");
+        sendToolResponse(socket, msg.id || null, null, e?.code ? e : e.message || "Request failed");
       }
       return;
     }