surf-cli 2.10.0 → 2.11.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);
@@ -1496,6 +1545,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 +1605,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]

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
@@ -1082,6 +1097,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 +1221,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);
@@ -672,8 +682,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 +713,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 +816,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 +1971,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 +1979,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;
     }

package/native/oracle-cli.cjs

@@ -0,0 +1,434 @@
+const { openClientTransport } = require("./client-transport.cjs");
+const { resolveRequestDeadlineMs } = require("./host-sessions.cjs");
+const { assembleContext } = require("./oracle-context.cjs");
+
+const RESULT_TIMEOUT_SECONDS = 20;
+const POLL_DELAYS_MS = [5000, 10000, 20000, 40000, 60000];
+const ORACLE_ERROR_CODES = new Set([
+  "auth",
+  "capacity",
+  "cloudflare",
+  "context_incomplete",
+  "dispatch_failed",
+  "harvest_failed",
+  "invalid_transition",
+  "model_verification_failed",
+  "not_found",
+  "rate_limit",
+  "remote_unsupported",
+  "sensitive_blocked",
+  "timeout",
+]);
+const HELP = `Usage: surf oracle <ask|status|result|follow|list>
+
+Commands:
+  ask <prompt>            Start a consult and wait for its response
+  follow <id> <prompt>    Continue a captured consult
+  status [id]             Show a job (newest when id is omitted)
+  result <id> [--wait]    Try to capture a result, optionally keep waiting
+  list                    List jobs newest-first
+
+Ask/follow options:
+  --files <glob>          Add context files (repeatable)
+  --model <model>         Select a ChatGPT model
+  --effort <effort>       Select reasoning effort
+  --detach                Return after dispatch
+  --allow-sensitive       Allow deny-listed context files
+
+Options:
+  --json                  Output machine-readable JSON
+  --no-lock               Bypass the browser request lock`;
+
+function codedError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function requireOptionValue(argv, index, name) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw codedError("invalid_transition", `--${name} requires a value`);
+  }
+  return value;
+}
+
+function parseOptions(argv) {
+  const positional = [];
+  const options = { files: [] };
+  const valueOptions = new Set(["files", "model", "effort"]);
+  const booleanOptions = new Set([
+    "allow-sensitive",
+    "detach",
+    "json",
+    "no-lock",
+    "wait",
+  ]);
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const name = value.slice(2);
+    if (valueOptions.has(name)) {
+      const optionValue = requireOptionValue(argv, index, name);
+      if (name === "files") options.files.push(optionValue);
+      else options[name] = optionValue;
+      index += 1;
+    } else if (booleanOptions.has(name)) {
+      options[name] = true;
+    } else {
+      throw codedError("invalid_transition", `Unknown oracle option: --${name}`);
+    }
+  }
+  return { positional, options };
+}
+
+function assertAllowedOptions(command, options) {
+  const common = new Set(["json", "no-lock"]);
+  const ask = new Set([
+    ...common,
+    "allow-sensitive",
+    "detach",
+    "effort",
+    "files",
+    "model",
+  ]);
+  const allowed = command === "ask" || command === "follow"
+    ? ask
+    : command === "result" ? new Set([...common, "wait"]) : common;
+  for (const [name, value] of Object.entries(options)) {
+    if (name === "files" && value.length === 0) continue;
+    if (value !== undefined && !allowed.has(name)) {
+      throw codedError("invalid_transition", `--${name} is not supported by oracle ${command}`);
+    }
+  }
+}
+
+function parseOracleCommand(argv) {
+  if (argv[0] !== "oracle") return { handled: false };
+  const command = argv[1];
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    return { handled: true, command: "help", json: false };
+  }
+  if (!["ask", "follow", "status", "result", "list"].includes(command)) {
+    throw codedError("invalid_transition", `Unknown oracle command: ${command}`);
+  }
+  const parsed = parseOptions(argv.slice(2));
+  assertAllowedOptions(command, parsed.options);
+  const json = parsed.options.json === true;
+
+  if (command === "ask") {
+    const prompt = parsed.positional.join(" ");
+    if (!prompt.trim()) {
+      throw codedError("dispatch_failed", "Usage: surf oracle ask <prompt> [options]");
+    }
+    return {
+      handled: true,
+      command,
+      prompt,
+      files: parsed.options.files,
+      model: parsed.options.model,
+      effort: parsed.options.effort,
+      detach: parsed.options.detach === true,
+      allowSensitive: parsed.options["allow-sensitive"] === true,
+      json,
+    };
+  }
+
+  if (command === "follow") {
+    const id = parsed.positional[0];
+    const prompt = parsed.positional.slice(1).join(" ");
+    if (!id?.trim() || !prompt.trim()) {
+      throw codedError("dispatch_failed", "Usage: surf oracle follow <id> <prompt> [options]");
+    }
+    return {
+      handled: true,
+      command,
+      id,
+      prompt,
+      files: parsed.options.files,
+      model: parsed.options.model,
+      effort: parsed.options.effort,
+      detach: parsed.options.detach === true,
+      allowSensitive: parsed.options["allow-sensitive"] === true,
+      json,
+    };
+  }
+
+  if (command === "status") {
+    if (parsed.positional.length > 1 || parsed.positional[0] === "") {
+      throw codedError("not_found", "Usage: surf oracle status [id]");
+    }
+    return { handled: true, command, id: parsed.positional[0], json };
+  }
+
+  if (command === "result") {
+    if (parsed.positional.length !== 1 || !parsed.positional[0].trim()) {
+      throw codedError("not_found", "Usage: surf oracle result <id> [--wait]");
+    }
+    return {
+      handled: true,
+      command,
+      id: parsed.positional[0],
+      wait: parsed.options.wait === true,
+      json,
+    };
+  }
+
+  if (parsed.positional.length > 0) {
+    throw codedError("invalid_transition", "Usage: surf oracle list");
+  }
+  return { handled: true, command, json };
+}
+
+function composeAskRequest(spec, context) {
+  const prompt = context ? `${spec.prompt}\n\n${context.envelope}` : spec.prompt;
+  return {
+    prompt,
+    ...(spec.model ? { model: spec.model } : {}),
+    ...(spec.effort ? { effort: spec.effort } : {}),
+    ...(context ? { contextManifest: context.manifest } : {}),
+    ...(context?.bundlePath ? { bundlePath: context.bundlePath } : {}),
+    ...(spec.id ? { follow: spec.id } : {}),
+  };
+}
+
+function unwrapResponse(response) {
+  if (response?.error) {
+    const message = response.error.message
+      || response.error.content?.[0]?.text
+      || JSON.stringify(response.error);
+    throw codedError(response.error.code || "timeout", message, {
+      ...(response.error.jobId ? { jobId: response.error.jobId } : {}),
+    });
+  }
+  const text = response?.result?.content?.[0]?.text;
+  if (text === undefined) return response?.result;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+async function requestHost(endpoint, tool, args, withBrowserLock) {
+  const execute = async () => {
+    const timeoutMs = resolveRequestDeadlineMs(tool, args);
+    const transport = await openClientTransport(endpoint, { requestTimeoutMs: timeoutMs });
+    try {
+      const request = {
+        type: "tool_request",
+        method: "execute_tool",
+        params: { tool, args },
+        id: `oracle-${Date.now()}-${Math.random()}`,
+      };
+      return unwrapResponse(await transport.request(request, timeoutMs));
+    } finally {
+      await transport.close();
+    }
+  };
+  return withBrowserLock ? withBrowserLock(execute) : execute();
+}
+
+function recoveryHint(id) {
+  return `Recover with: surf oracle result ${id}`;
+}
+
+function classifyError(error, fallbackCode) {
+  if (!ORACLE_ERROR_CODES.has(error?.code)) error.code = fallbackCode;
+  return error;
+}
+
+function shapeOracleError(error, fallbackCode = "timeout") {
+  const jobId = typeof error?.jobId === "string" ? error.jobId : undefined;
+  let message = error?.message || String(error);
+  if (error?.recoverable && jobId && !message.includes("Recover with:")) {
+    message = `${message}\n${recoveryHint(jobId)}`;
+  }
+  return {
+    error: {
+      code: ORACLE_ERROR_CODES.has(error?.code) ? error.code : fallbackCode,
+      message,
+    },
+    ...(jobId ? { jobId } : {}),
+  };
+}
+
+function formatOracleError(error, json = false) {
+  const shaped = shapeOracleError(error);
+  if (json) return JSON.stringify(shaped, null, 2);
+  return `Error: ${shaped.error.message}`;
+}
+
+function formatOracleOutput(value, json = false) {
+  if (json) return JSON.stringify(value, null, 2);
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "No oracle jobs.";
+    return value.map((job) => `${job.id}\t${job.state}`).join("\n");
+  }
+  const lines = [value.id, value.state];
+  if (value.response !== undefined) lines.push(value.response);
+  return lines.filter((line) => line !== undefined).join("\n");
+}
+
+async function waitForResult(job, spec, io) {
+  const startedAt = Date.now();
+  const interrupt = () => {
+    const message = `Interrupted. ${recoveryHint(job.id)}`;
+    if (spec.json) {
+      io.stderr.write(`${JSON.stringify({
+        error: { code: "timeout", message },
+        jobId: job.id,
+      }, null, 2)}\n`);
+    } else {
+      io.stderr.write(`${recoveryHint(job.id)}\n`);
+    }
+    process.exit(130);
+  };
+  process.once("SIGINT", interrupt);
+
+  try {
+    let current = job;
+    let pollIndex = 0;
+    while (current.state !== "captured") {
+      try {
+        current = await requestHost(
+          io.endpoint,
+          "oracle.result",
+          {
+            id: current.id,
+            timeout: RESULT_TIMEOUT_SECONDS,
+          },
+          io.withBrowserLock,
+        );
+      } catch (error) {
+        error.jobId ||= current.id;
+        error.recoverable = true;
+        throw classifyError(error, "timeout");
+      }
+      if (!spec.json && io.stderr.isTTY) {
+        const elapsedSeconds = Math.round((Date.now() - startedAt) / 1000);
+        io.stderr.write(`[${elapsedSeconds}s] ${current.state}\n`);
+      }
+      if (current.state === "failed") {
+        throw codedError(
+          current.error?.code || "harvest_failed",
+          current.error?.message || `oracle job ${current.id} failed`,
+          { jobId: current.id },
+        );
+      }
+      if (current.state !== "captured") {
+        const delayMs = POLL_DELAYS_MS[Math.min(pollIndex, POLL_DELAYS_MS.length - 1)];
+        pollIndex += 1;
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+    return current;
+  } finally {
+    process.removeListener("SIGINT", interrupt);
+  }
+}
+
+async function handleOracleCli(argv, {
+  endpoint,
+  cwd = process.cwd(),
+  stderr = process.stderr,
+  withBrowserLock,
+} = {}) {
+  const spec = parseOracleCommand(argv);
+  if (!spec.handled) return spec;
+  if (spec.command === "help") return { handled: true, value: HELP, json: false };
+  if (endpoint?.kind === "remote") {
+    throw codedError(
+      "remote_unsupported",
+      "oracle commands are not supported with remote endpoints",
+    );
+  }
+
+  const io = { endpoint, stderr, withBrowserLock };
+  if (spec.command === "status") {
+    try {
+      const value = await requestHost(endpoint, "oracle.status", spec.id ? { id: spec.id } : {});
+      return { handled: true, value, json: spec.json };
+    } catch (error) {
+      throw classifyError(error, "timeout");
+    }
+  }
+  if (spec.command === "list") {
+    try {
+      const value = await requestHost(endpoint, "oracle.list", {});
+      return { handled: true, value, json: spec.json };
+    } catch (error) {
+      throw classifyError(error, "timeout");
+    }
+  }
+  if (spec.command === "result") {
+    if (spec.wait) {
+      const value = await waitForResult({ id: spec.id, state: "created" }, spec, io);
+      return { handled: true, value, json: spec.json };
+    }
+    try {
+      const value = await requestHost(
+        endpoint,
+        "oracle.result",
+        {
+          id: spec.id,
+          timeout: RESULT_TIMEOUT_SECONDS,
+        },
+        withBrowserLock,
+      );
+      return { handled: true, value, json: spec.json };
+    } catch (error) {
+      error.jobId ||= spec.id;
+      throw classifyError(error, "timeout");
+    }
+  }
+
+  const context = spec.files.length > 0
+    ? await assembleContext({
+      files: spec.files,
+      cwd,
+      allowSensitive: spec.allowSensitive,
+    })
+    : null;
+  const request = composeAskRequest(spec, context);
+  const dispatchInterrupt = () => {
+    stderr.write(
+      "Interrupted during dispatch. A job may already have been created. Run surf oracle status or surf oracle list to find it.\n",
+    );
+    process.exit(130);
+  };
+  process.once("SIGINT", dispatchInterrupt);
+  let value;
+  try {
+    value = await requestHost(endpoint, "oracle.ask", request, withBrowserLock);
+  } catch (error) {
+    throw classifyError(error, "dispatch_failed");
+  } finally {
+    process.removeListener("SIGINT", dispatchInterrupt);
+  }
+  if (spec.detach || value.state === "captured") {
+    if (spec.detach && value.state === "dispatched") {
+      stderr.write(
+        `Warning: the durable conversation URL is not yet captured. Run surf oracle result ${value.id} promptly.\n`,
+      );
+    }
+    return { handled: true, value, json: spec.json };
+  }
+  value = await waitForResult(value, spec, io);
+  return { handled: true, value, json: spec.json };
+}
+
+module.exports = {
+  composeAskRequest,
+  formatOracleError,
+  formatOracleOutput,
+  handleOracleCli,
+  parseOracleCommand,
+  shapeOracleError,
+};