surf-cli 2.13.1 → 2.15.0

package/native/mcp-server.cjs

@@ -269,7 +269,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"),
+      model: z.string().optional().describe("ChatGPT model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol, or a visible model label"),
       "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

@@ -30,8 +30,8 @@ Commands:
 
 Ask/follow options:
   --files <glob>          Add context files (repeatable)
-  --model <model>         Select a ChatGPT model
-  --effort <effort>       Select reasoning effort
+  --model <model>         Select model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol
+  --effort <effort>       Select effort: light, standard, extended, heavy, pro
   --detach                Return after dispatch
   --allow-sensitive       Allow deny-listed context files
 

package/native/oracle-jobs.cjs

@@ -35,6 +35,24 @@ function codedError(code, message, details = {}) {
   return error;
 }
 
+function promptDigest(prompt) {
+  return `sha256:${crypto.createHash("sha256").update(prompt).digest("hex")}`;
+}
+
+function hydrateJobMetadata(job, root = getPrivateStateRoot()) {
+  const prompt = job.promptDigest ? null : readPrivateFile(path.join(jobDirectory(job.id, root), "request.md"), {
+    root,
+    encoding: "utf8",
+  });
+  const legacyModel = job.modelRequested === undefined && job.modelVerified === undefined;
+  return {
+    ...job,
+    modelRequested: job.modelRequested ?? (legacyModel && job.state === "created" ? job.model ?? null : null),
+    modelVerified: job.modelVerified ?? (legacyModel && job.state !== "created" ? job.model ?? null : null),
+    promptDigest: job.promptDigest ?? promptDigest(prompt),
+  };
+}
+
 function readJobs(root = getPrivateStateRoot()) {
   const base = oracleRoot(root);
   if (!fs.existsSync(base)) return [];
@@ -44,7 +62,8 @@ function readJobs(root = getPrivateStateRoot()) {
     .filter((id) => JOB_ID_PATTERN.test(id))
     .sort((a, b) => b.localeCompare(a))
     .map((id) => readPrivateJson(path.join(base, id, "job.json"), null, { root }))
-    .filter(Boolean);
+    .filter(Boolean)
+    .map((job) => hydrateJobMetadata(job, root));
 }
 
 function createJob({ prompt, contextManifest = {}, model = null, effortRequested = null, follow = null }) {
@@ -84,8 +103,11 @@ function createJob({ prompt, contextManifest = {}, model = null, effortRequested
       id,
       state: "created",
       model,
+      modelRequested: model,
+      modelVerified: null,
       effortRequested,
       effortVerified: null,
+      promptDigest: promptDigest(prompt),
       createdAt: now.toISOString(),
       dispatchedAt: null,
       awaitingAt: null,
@@ -110,7 +132,7 @@ function getJob(id) {
   const root = getPrivateStateRoot();
   const job = readPrivateJson(path.join(jobDirectory(id, root), "job.json"), null, { root });
   if (!job) throw codedError("not_found", `oracle job not found: ${id}`);
-  return job;
+  return hydrateJobMetadata(job, root);
 }
 
 function getResponse(id) {
@@ -141,7 +163,7 @@ function markDispatched(id, { tabId, promptEcho, modelVerified, effortVerified }
     dispatchedAt: new Date().toISOString(),
     tabId,
     ...(promptEcho ? { promptEcho } : {}),
-    ...(modelVerified ? { model: modelVerified } : {}),
+    ...(modelVerified ? { model: modelVerified, modelVerified } : {}),
     ...(effortVerified ? { effortVerified } : {}),
   });
 }

package/native/playbook-cli.cjs

@@ -36,6 +36,11 @@ async function requestHost(endpoint, tool, args, options = {}) {
   try {
     const request = { type: "tool_request", method: "execute_tool", params: { tool, args }, id: `playbook-${Date.now()}-${Math.random()}` };
     if (options.tabId) request.tabId = options.tabId;
+    if (options.session) {
+      request.session = options.session;
+      request.sessionSource = options.sessionSource || "environment";
+    }
+    if (options.admission) request.admission = options.admission;
     return unwrapResponse(await transport.request(request, options.timeoutMs || 11 * 60 * 1000));
   } finally {
     await transport.close();
@@ -48,7 +53,7 @@ function runSpec(argv) {
   const parsed = parseCommandArgs(argv.slice(offset));
   const [playbook, op] = parsed.positional;
   if (!playbook || !op) throw new Error(direct ? "Usage: surf use <playbook> <op> [--arg value]" : "Usage: surf pb run <playbook> <op> [--arg value]");
-  const reserved = new Set(["json", "no-lock", "tab-id", "write", "repeat", "retry-attempt", "override-in-doubt", "pin-built-in", "allow-script"]);
+  const reserved = new Set(["json", "no-lock", "no-wait", "session", "tab-id", "write", "repeat", "retry-attempt", "override-in-doubt", "pin-built-in", "allow-script"]);
   const args = Object.fromEntries(Object.entries(parsed.options).filter(([name]) => !reserved.has(name)));
   return { playbook, op, args, options: parsed.options };
 }
@@ -73,7 +78,7 @@ function playbookCommandNeedsBrowser(argv) {
   return subcommand === "record" && ["start", "stop", "discard"].includes(argv[2]);
 }
 
-async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
+async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd(), session, sessionSource, admission } = {}) {
   if (!["playbook", "pb", "use"].includes(argv[0])) return { handled: false };
   if (argv[0] === "use" || argv[1] === "run") {
     const spec = runSpec(argv);
@@ -93,6 +98,9 @@ async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
     };
     const value = await requestHost(endpoint, "playbook.run", args, {
       tabId: spec.options["tab-id"],
+      session: spec.options.session || session,
+      sessionSource: spec.options.session ? "explicit" : sessionSource,
+      admission: spec.options["no-wait"] === true ? { wait: false } : admission,
       timeoutMs: resolveRequestDeadlineMs("playbook.run", args),
     });
     return { handled: true, value, json: spec.options.json === true };
@@ -118,7 +126,12 @@ async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
     else if (action === "mark") args = { label: parsed.positional.slice(1).join(" ") };
     else if (action === "stop") args = { draft: parsed.options.draft === true };
     else if (!["status", "pause", "resume", "discard"].includes(action)) throw new Error("Unknown record command");
-    const value = await requestHost(endpoint, tool, args, { tabId: parsed.options["tab-id"] });
+    const value = await requestHost(endpoint, tool, args, {
+      tabId: parsed.options["tab-id"],
+      session: parsed.options.session || session,
+      sessionSource: parsed.options.session ? "explicit" : sessionSource,
+      admission: parsed.options["no-wait"] === true ? { wait: false } : admission,
+    });
     return { handled: true, value, json: parsed.options.json === true };
   }
   if (command === "suggest") return { handled: true, value: suggestions({ since: parsed.options.since || "1h" }), json: parsed.options.json === true };

package/native/surf-error.cjs

@@ -0,0 +1,47 @@
+class SurfError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "SurfError";
+    this.code = code;
+    Object.assign(this, details);
+  }
+
+  toJSON() {
+    const value = { code: this.code, message: this.message };
+    for (const key of [
+      "session", "target", "lastUrl", "laneKey", "resourceKeys", "retryable", "recoveryCommand",
+      "queue", "reason", "browserEpoch", "expectedBrowserEpoch",
+    ]) {
+      if (this[key] !== undefined) value[key] = this[key];
+    }
+    return value;
+  }
+}
+
+function surfError(code, message, details = {}) {
+  return new SurfError(code, message, details);
+}
+
+function isSurfError(error) {
+  return Boolean(error && typeof error === "object" && typeof error.code === "string");
+}
+
+function fromExtensionError(result, fallbackCode = "browser_error") {
+  if (!result?.error) return null;
+  return surfError(result.errorCode || fallbackCode, result.error, result.errorDetails || {});
+}
+
+function recoveryFor(error) {
+  if (!error || typeof error !== "object") return null;
+  if (typeof error.recoveryCommand === "string" && error.recoveryCommand) return error.recoveryCommand;
+  if ((error.code === "tab_gone" || error.code === "session_epoch_stale") && error.session) {
+    return `surf session.reopen ${error.session}`;
+  }
+  if ((error.code === "tab_busy" || error.code === "browser_busy" || error.code === "resource_busy") && error.session) {
+    return `surf session.info ${error.session}`;
+  }
+  if (error.code === "browser_busy") return "surf session.list --refresh";
+  return null;
+}
+
+module.exports = { SurfError, surfError, isSurfError, fromExtensionError, recoveryFor };

package/native/tool-scope.cjs

@@ -0,0 +1,107 @@
+const path = require("path");
+
+const PROVIDER_TOOLS = new Set([
+  "chatgpt", "gemini", "perplexity", "grok", "kimi", "aistudio", "aistudio.build",
+  "oracle.ask", "oracle.result", "oracle.cancel",
+]);
+
+const HOST_TOOLS = new Set([
+  "wait",
+  "session.list",
+  "session.info",
+  "tab.unname", "tabs_unregister", "tab.named", "tabs_list_named",
+]);
+
+const BROWSER_READ_TOOLS = new Set([
+  "tab.list", "tabs_context", "list_tabs",
+  "window.list",
+  "history.list", "history.search",
+  "bookmark.list",
+  "downloads.search",
+]);
+
+const BROWSER_WRITE_TOOLS = new Set([
+  "session.new", "session.ensure", "session.close", "session.rebind", "session.reopen",
+  "tab.new", "new_tab", "tabs_create",
+  "tab.move", "tab.switch", "switch_tab",
+  "tab.group", "tab.ungroup",
+  "window.new", "window.close", "window.focus", "window.resize",
+  "smoke",
+]);
+
+const BROWSER_WRITE_TARGETED_TOOLS = new Set([
+  "cookie.set", "cookie.clear", "cookie.clear-all",
+  "bookmark.add", "bookmark.remove",
+  "playbook.run",
+]);
+
+const TAB_TOOLS = new Set([
+  "ai", "computer", "batch", "record", "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",
+  "click", "left_click", "right_click", "double_click", "triple_click", "drag", "hover", "key", "submit",
+  "type", "smart_type", "find_and_type", "form_input", "form.fill", "select", "upload", "upload_image",
+  "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",
+  "dialog.accept", "dialog.dismiss", "dialog.info",
+  "console", "network", "network.get", "network.body", "network.curl", "network.path",
+  "network.origins", "network.clear", "network.stats", "network.export",
+  "emulate.network", "emulate.cpu", "emulate.geo", "emulate.device", "emulate.viewport", "emulate.touch",
+  "perf.start", "perf.stop", "perf.metrics",
+  "zoom", "cookie.list", "cookie.get",
+  "tab.name", "tabs_register",
+  "playbook.record.start", "playbook.record.stop", "playbook.record.status", "playbook.record.mark",
+  "playbook.record.pause", "playbook.record.resume", "playbook.record.discard",
+]);
+
+function hasExplicitTabCloseTarget(args = {}) {
+  return [args.id, args.tab_id, args.tabId, args.ids, args.tab_ids, args.tabIds]
+    .some((value) => value !== undefined && value !== null && value !== "");
+}
+
+function classifyTool(tool, args = {}) {
+  if (PROVIDER_TOOLS.has(tool) || tool.startsWith("oracle.")) {
+    const hostOnly = tool === "oracle.result" || tool === "oracle.cancel" || tool === "oracle.status" || tool === "oracle.list";
+    return hostOnly
+      ? { scope: "host", targetUse: "host" }
+      : { scope: "provider", targetUse: "default-tab" };
+  }
+  if (tool === "session.list") {
+    return { scope: args.refresh ? "browser-read" : "host", targetUse: "host" };
+  }
+  if (tool === "session.info") {
+    return { scope: args.refresh ? "browser-read" : "host", targetUse: "host" };
+  }
+  if (tool === "tab.close" || tool === "close_tab") {
+    return hasExplicitTabCloseTarget(args)
+      ? { scope: "browser-write", targetUse: "browser" }
+      : { scope: "browser-write", targetUse: "default-tab" };
+  }
+  if (HOST_TOOLS.has(tool)) return { scope: "host", targetUse: "host" };
+  if (BROWSER_READ_TOOLS.has(tool)) return { scope: "browser-read", targetUse: "browser" };
+  if (BROWSER_WRITE_TARGETED_TOOLS.has(tool)) {
+    return { scope: "browser-write", targetUse: "default-tab" };
+  }
+  if (BROWSER_WRITE_TOOLS.has(tool)) return { scope: "browser-write", targetUse: "browser" };
+  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");
+    return { scope: "tab", targetUse: "default-tab", resourceKeys };
+  }
+  return { scope: "browser-write", targetUse: "browser", conservative: true };
+}
+
+module.exports = {
+  BROWSER_READ_TOOLS,
+  BROWSER_WRITE_TARGETED_TOOLS,
+  BROWSER_WRITE_TOOLS,
+  HOST_TOOLS,
+  PROVIDER_TOOLS,
+  TAB_TOOLS,
+  classifyTool,
+};

package/native/workflow-definition.cjs

@@ -36,6 +36,13 @@ const COMMANDS = {
   "tab.close": { primaryArg: "id", effect: "page-write", argKinds: { id: "tab-id" } },
   "tab.name": { primaryArg: "name", effect: "page-write", argKinds: { name: "name" } },
   "tab.unname": { primaryArg: "name", effect: "page-write", argKinds: { name: "name" } },
+  "session.new": { primaryArg: "name", effect: "navigation", recordable: false, argKinds: { name: "name", url: "url" } },
+  "session.ensure": { primaryArg: "name", effect: "navigation", recordable: false, argKinds: { name: "name", url: "url" } },
+  "session.list": { effect: "read", recordable: false },
+  "session.info": { primaryArg: "name", effect: "read", recordable: false, argKinds: { name: "name" } },
+  "session.close": { primaryArg: "name", effect: "page-write", recordable: false, argKinds: { name: "name" } },
+  "session.rebind": { primaryArg: "name", effect: "page-write", recordable: false, argKinds: { name: "name", tabId: "tab-id" } },
+  "session.reopen": { primaryArg: "name", effect: "navigation", recordable: false, argKinds: { name: "name", url: "url" } },
   scroll_to_position: { primaryArg: "position", effect: "page-write", argKinds: { position: "position" } },
   type: { primaryArg: "text", effect: "page-write", argKinds: { selector: "selector", text: "user-input" }, sensitiveArgs: ["text"] },
   smart_type: { primaryArg: "text", effect: "page-write", argKinds: { selector: "selector", text: "user-input" }, sensitiveArgs: ["text"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.13.1",
+  "version": "2.15.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -33,6 +33,7 @@
     "playbooks/",
     "scripts/",
     "dist/",
+    "agents/",
     "skills/",
     "README.md",
     "LICENSE"
@@ -81,7 +82,12 @@
     ],
     "skills": [
       "./skills"
-    ]
+    ],
+    "subagents": {
+      "agents": [
+        "./agents"
+      ]
+    }
   },
   "peerDependencies": {
     "typebox": "*"