surf-cli 2.14.0 → 2.15.1

package/native/cli.cjs

@@ -24,7 +24,7 @@ const {
   formatOracleOutput,
   handleOracleCli,
 } = require("./oracle-cli.cjs");
-const { formatPlaybookOutput, handlePlaybookCli, playbookCommandNeedsBrowser } = require("./playbook-cli.cjs");
+const { formatPlaybookOutput, handlePlaybookCli } = require("./playbook-cli.cjs");
 
 const IS_WIN = process.platform === "win32";
 const { SURF_TMP, formatSocketError } = require("./socket-path.cjs");
@@ -32,6 +32,7 @@ const { acquireBrowserLock } = require("./browser-lock.cjs");
 const { selectEndpoint, connectEndpoint, formatEndpointError } = require("./endpoint.cjs");
 const { createFrameParser, createSocketWriter, writeFrame } = require("./remote-transport.cjs");
 const { resolveRequestDeadlineMs } = require("./host-sessions.cjs");
+const { classifyTool } = require("./tool-scope.cjs");
 const { AUTO_SCREENSHOT_TOOLS, prepareRemoteTool, validateLocalToolPaths } = require("./file-transfer.cjs");
 const { authorizeClient, listClients, revokeClient, getStateDir } = require("./remote-auth.cjs");
 if (IS_WIN) { try { fs.mkdirSync(SURF_TMP, { recursive: true }); } catch {} }
@@ -49,6 +50,46 @@ function parseBrowserLockOptions(noLockFlag) {
   return { noLock, timeoutMs };
 }
 
+function flagValue(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    console.error(`Error: ${flag} requires a value`);
+    process.exit(1);
+  }
+  return value;
+}
+
+function positiveIdFlag(argv, flag) {
+  const value = flagValue(argv, flag);
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    console.error(`Error: ${flag} must be a positive number`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
+function resolveEarlyTargetOptions(argv, { allowWindow = true } = {}) {
+  const explicitSession = flagValue(argv, "--session");
+  const tabId = positiveIdFlag(argv, "--tab-id");
+  const windowId = allowWindow ? positiveIdFlag(argv, "--window-id") : undefined;
+  if (explicitSession && (tabId || windowId)) {
+    console.error("Error: use either --session or --tab-id/--window-id, not both");
+    process.exit(1);
+  }
+  const environmentSession = process.env.SURF_SESSION;
+  const session = explicitSession || (!tabId && !windowId ? environmentSession : undefined);
+  return {
+    ...(session ? { session, sessionSource: explicitSession ? "explicit" : "environment" } : {}),
+    ...(tabId ? { tabId } : {}),
+    ...(windowId ? { windowId } : {}),
+    ...(argv.includes("--no-wait") ? { admission: { wait: false } } : {}),
+  };
+}
+
 function installBrowserLock({ noLock, timeoutMs }, endpoint) {
   let releaseBrowserLock = () => {};
   if (!noLock) {
@@ -78,28 +119,6 @@ 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;
@@ -181,14 +200,13 @@ try {
 }
 
 if (args[0] === "oracle") {
+  if (args[1] === "ask" || args[1] === "follow") {
+    console.error("[surf] Oracle requires exclusive browser access while dispatching; other sessions will queue.");
+  }
   handleOracleCli(args, {
     endpoint,
     cwd: process.cwd(),
-    withBrowserLock: (operation) => runWithBrowserLock(
-      parseBrowserLockOptions(args.includes("--no-lock")),
-      endpoint,
-      operation,
-    ),
+    withBrowserLock: (operation) => operation(),
   })
     .then((result) => {
       if (!result.handled) throw new Error("Oracle command was not handled");
@@ -203,10 +221,8 @@ if (args[0] === "oracle") {
 }
 
 if (["playbook", "pb", "use"].includes(args[0])) {
-  if (playbookCommandNeedsBrowser(args)) {
-    installBrowserLock(parseBrowserLockOptions(args.includes("--no-lock")), endpoint);
-  }
-  handlePlaybookCli(args, { endpoint, cwd: process.cwd() })
+  const targetOptions = resolveEarlyTargetOptions(args, { allowWindow: false });
+  handlePlaybookCli(args, { endpoint, cwd: process.cwd(), ...targetOptions })
     .then((result) => {
       if (!result.handled) throw new Error("Playbook command was not handled");
       if (result.value !== undefined) console.log(formatPlaybookOutput(result.value, result.json));
@@ -262,6 +278,66 @@ const REMOVED_COMMANDS = {
 };
 
 const TOOLS = {
+  session: {
+    desc: "Durable tab-bound browser sessions",
+    commands: {
+      "session.new": {
+        desc: "Create a named session in a separate unfocused window by default",
+        args: ["name", "url"],
+        opts: {
+          window: "Create a separate window (default)",
+          tab: "Create an inactive tab instead of a window",
+          focused: "Focus the new target",
+          "window-id": "Window for --tab mode",
+        },
+        examples: [
+          { cmd: 'session.new research "https://example.com"', desc: "Create a window session" },
+          { cmd: 'session.new research about:blank --tab', desc: "Create an inactive tab session" },
+        ],
+      },
+      "session.ensure": {
+        desc: "Idempotently create, reuse, or reopen a named session",
+        args: ["name", "url"],
+        opts: {
+          window: "Use a separate window (default)",
+          tab: "Use an inactive tab",
+          focused: "Focus a newly created target",
+          "window-id": "Window for --tab mode",
+        },
+        examples: [
+          { cmd: 'session.ensure research about:blank', desc: "Safe first command for an agent" },
+        ],
+      },
+      "session.list": {
+        desc: "List sessions, status, and queue state",
+        args: [],
+        opts: { refresh: "Validate every binding against Chrome" },
+      },
+      "session.info": {
+        desc: "Show one session, target, and scheduler queue state",
+        args: ["name"],
+        opts: { refresh: "Validate the binding against Chrome" },
+      },
+      "session.close": {
+        desc: "Remove a session and close Surf-created targets by default",
+        args: ["name"],
+        opts: {
+          "keep-target": "Unbind without closing the target",
+          "close-target": "Close an adopted target too",
+        },
+      },
+      "session.rebind": {
+        desc: "Bind a stale or gone session to an explicit existing tab",
+        args: ["name"],
+        opts: { "tab-id": "Existing tab ID", replace: "Replace a live binding" },
+      },
+      "session.reopen": {
+        desc: "Create a replacement target using the stored or supplied URL",
+        args: ["name", "url"],
+        opts: { replace: "Replace a live target", tab: "Reopen as an inactive tab", window: "Reopen as a window" },
+      },
+    },
+  },
   ai: {
     desc: "AI assistants (ChatGPT, Gemini)",
     commands: {
@@ -1485,6 +1561,7 @@ Exclude text content:
 };
 
 const ALL_SOCKET_TOOLS = [
+  "session.new", "session.ensure", "session.list", "session.info", "session.close", "session.rebind", "session.reopen",
   "ai", "screenshot", "record", "animate-audit", "perf-audit", "navigate",
   "form_input", "find_and_type", "autocomplete", "set_value", "smart_type",
   "scroll_to_position", "get_scroll_info", "close_dialogs", "page_state",
@@ -1553,6 +1630,8 @@ const SEE_ALSO = {
   "scroll.to": ["click", "page.read"],
   "console": ["network", "perf.metrics"],
   "network": ["console", "network.get"],
+  "session.ensure": ["session.info", "session.list"],
+  "session.info": ["session.reopen", "session.rebind", "session.list"],
 };
 
 const showBasicHelp = () => {
@@ -1561,6 +1640,7 @@ const showBasicHelp = () => {
 Usage: surf <command> [args] [options]
 
 Common Commands:
+  session.ensure <name> [url]  Idempotently create or reuse a tab-bound session
   navigate <url>     Go to URL (alias: go)
   click <ref>        Click element by ref or selector
   type <text>        Type text at cursor or into element
@@ -1577,6 +1657,8 @@ Common Commands:
   wait <seconds>     Wait N seconds
 
 Quick Examples:
+  export SURF_SESSION="$(basename "$PWD" | sed 's/[^A-Za-z0-9._-]/-/g')"
+  surf session.ensure "$SURF_SESSION" about:blank
   surf go "https://example.com"
   surf read
   surf click e5
@@ -1587,6 +1669,8 @@ Quick Examples:
   surf window.new "https://example.com" && surf --window-id 123 go "https://other.com"
 
 More Help:
+  --session <name>          Target a durable named browser session
+  --no-wait                 Return tab_busy/browser_busy instead of queueing
   --remote <host>:<port>    Route requests to a remote native host
   --remote-credential <path>  Use a mode-0600 Ed25519 remote credential file
   surf remote authorize <label> --output <path>
@@ -1621,8 +1705,10 @@ Scroll: surf scroll down 800 | surf scroll up 400 | surf scroll bottom | surf sc
 Find by semantics: surf locate.role button --name "Submit" --action click
 Device/viewport: surf emulate.device "iPhone 14" | surf resize 375 812
 Cookies: surf cookie list | surf cookie get "name" | surf cookie delete "name"
-Window isolation: surf window.new "https://example.com" then pass --window-id <id>
-Concurrency: surf serializes commands per socket; use --no-lock only for intentional bypass
+Session targeting: surf --session research read | SURF_SESSION=research surf read
+Session status/queue: surf session.info research | surf session.list --refresh
+Recovery: run the exact command printed after Recovery: on tab_gone, session_epoch_stale, tab_busy, or browser_busy
+Concurrency: commands for different session tabs can overlap; each tab remains FIFO; provider flows are browser-exclusive
 Doctor: surf doctor --browser all              # native host/socket diagnostics
 Workflow: surf do 'go "https://example.com" | wait 2 | read | click e5 | screenshot'
 More help: surf --help-full | surf <command> --help | surf --help-topic refs | surf --find <query>`);
@@ -1656,12 +1742,14 @@ Playbooks:
 Options:
   --remote <host>:<port>       Route requests to a remote native host
   --remote-credential <path>   Use a mode-0600 Ed25519 remote credential file
+  --session <name>  Target a durable named session (or set SURF_SESSION)
   --tab-id <id>     Target specific tab
-  --window-id <id>  Target specific window (isolate from your browsing)
-  --json            Output raw JSON
+  --window-id <id>  Target specific window
+  --no-wait         Return immediately when the tab/browser is busy
+  --json            Output raw JSON including target metadata
   --auto-capture    On error: capture screenshot + console to /tmp
   --soft-fail       On error: warn and exit 0 (for non-critical commands)
-  --no-lock         Bypass the per-socket browser request lock
+  --no-lock         Bypass the legacy lock for compound client-side commands
 
 Remote Credentials (run on the browser host):
   surf remote authorize <label> --output <credential-file>
@@ -2042,8 +2130,7 @@ if (args.includes("--script")) {
   const dryRun = args.includes("--dry-run");
   const stopOnError = args.includes("--stop-on-error");
 
-  const tabIdIdx = args.indexOf("--tab-id");
-  const scriptTabId = tabIdIdx !== -1 ? args[tabIdIdx + 1] : undefined;
+  const scriptTarget = resolveEarlyTargetOptions(args);
 
   if (!scriptPath || scriptPath.startsWith("--")) {
     console.error("Error: --script requires a file path");
@@ -2077,7 +2164,13 @@ if (args.includes("--script")) {
       params: { tool: toolName, args: toolArgs },
       id: "cli-" + Date.now() + "-" + Math.random(),
     };
-    if (scriptTabId) req.tabId = parseInt(scriptTabId, 10);
+    if (scriptTarget.tabId) req.tabId = scriptTarget.tabId;
+    if (scriptTarget.windowId) req.windowId = scriptTarget.windowId;
+    if (scriptTarget.session) {
+      req.session = scriptTarget.session;
+      req.sessionSource = scriptTarget.sessionSource;
+    }
+    if (scriptTarget.admission) req.admission = scriptTarget.admission;
     const prepared = endpoint.kind === "remote" ? prepareRemoteTool(toolName, toolArgs) : (() => { const args = validateLocalToolPaths(toolName, toolArgs); return { args, uploads: [], downloads: [] }; })();
     req.params.args = prepared.args;
     return scriptTransport.request(req, resolveRequestDeadlineMs(toolName, prepared.args), prepared);
@@ -2150,10 +2243,6 @@ if (args.includes("--script")) {
     }
   };
 
-  if (!dryRun) {
-    installBrowserLock(parseBrowserLockOptions(args.includes("--no-lock")), endpoint);
-  }
-
   runScript()
     .then((code) => process.exit(code))
     .catch((error) => {
@@ -2176,9 +2265,11 @@ if (args[0] === "do") {
   let wantJson = false;
   let tabId = undefined;
   let windowId = undefined;
+  let explicitSession = undefined;
+  let noWait = false;
 
   // Reserved flags that aren't workflow args
-  const reservedFlags = ['file', 'f', 'dry-run', 'on-error', 'no-auto-wait', 'step-delay', 'json', 'tab-id', 'window-id', 'no-lock'];
+  const reservedFlags = ['file', 'f', 'dry-run', 'on-error', 'no-auto-wait', 'step-delay', 'json', 'tab-id', 'window-id', 'session', 'no-lock', 'no-wait'];
 
   // Workflow-specific args (collected for variable substitution)
   const workflowArgs = {};
@@ -2208,6 +2299,16 @@ if (args[0] === "do") {
     } else if (arg === "--window-id") {
       windowId = parseInt(doArgs[i + 1], 10);
       i++;
+    } else if (arg === "--session") {
+      const value = doArgs[i + 1];
+      if (!value || value.startsWith("--")) {
+        console.error("Error: --session requires a value");
+        process.exit(1);
+      }
+      explicitSession = value;
+      i++;
+    } else if (arg === "--no-wait") {
+      noWait = true;
     } else if (arg.startsWith("--")) {
       // Workflow-specific arg (e.g., --email, --password)
       const key = arg.slice(2);
@@ -2231,6 +2332,22 @@ if (args[0] === "do") {
     }
   }
 
+  if (tabId !== undefined && (!Number.isInteger(tabId) || tabId <= 0)) {
+    console.error("Error: --tab-id must be a positive number");
+    process.exit(1);
+  }
+  if (windowId !== undefined && (!Number.isInteger(windowId) || windowId <= 0)) {
+    console.error("Error: --window-id must be a positive number");
+    process.exit(1);
+  }
+  if (explicitSession && (tabId || windowId)) {
+    console.error("Error: use either --session or --tab-id/--window-id, not both");
+    process.exit(1);
+  }
+  const environmentSession = process.env.SURF_SESSION;
+  const session = explicitSession || (!tabId && !windowId ? environmentSession : undefined);
+  const sessionSource = explicitSession ? "explicit" : session ? "environment" : undefined;
+
   if (!commandsInput && !fileInput) {
     console.error("Error: commands string, workflow name, or --file required");
     console.error('Usage: surf do \'go "url" | click e5\'');
@@ -2336,8 +2453,6 @@ if (args[0] === "do") {
     process.exit(0);
   }
 
-  installBrowserLock(parseBrowserLockOptions(doArgs.includes("--no-lock")), endpoint);
-
   if (!wantJson) {
     if (workflowName) {
       console.log(`Running workflow: ${workflowName} (${steps.length} steps)...\n`);
@@ -2359,6 +2474,9 @@ if (args[0] === "do") {
       context: {
         tabId,
         windowId,
+        session,
+        sessionSource,
+        admission: noWait ? { wait: false } : undefined,
         endpoint,
         transport,
       },
@@ -2517,7 +2635,7 @@ if (args[0] === "workflow.validate") {
   }
 }
 
-const BOOLEAN_FLAGS = ["auto-capture", "json", "stream", "dry-run", "stop-on-error", "fail-fast", "clear", "submit", "all", "case-sensitive", "hard", "annotate", "fullpage", "full-page", "reset", "no-screenshot", "full", "soft-fail", "has-body", "exclude-static", "v", "vv", "request", "by-tab", "har", "jsonl", "no-save", "no-auto-wait", "no-lock"];
+const BOOLEAN_FLAGS = ["auto-capture", "json", "stream", "dry-run", "stop-on-error", "fail-fast", "clear", "submit", "all", "case-sensitive", "hard", "annotate", "fullpage", "full-page", "reset", "no-screenshot", "full", "soft-fail", "has-body", "exclude-static", "v", "vv", "request", "by-tab", "har", "jsonl", "no-save", "no-auto-wait", "no-lock", "no-wait", "window", "tab", "focused", "unfocused", "keep-target", "close-target", "replace", "refresh"];
 
 const parseArgs = (rawArgs) => {
   const result = { positional: [], options: {} };
@@ -2563,6 +2681,24 @@ let { positional, options } = parseArgs(args);
 let tool = positional[0];
 let firstArg = positional[1];
 
+if (tool === "session" && firstArg) {
+  const sessionSubcommands = {
+    new: "session.new",
+    ensure: "session.ensure",
+    list: "session.list",
+    info: "session.info",
+    close: "session.close",
+    rebind: "session.rebind",
+    reopen: "session.reopen",
+  };
+  const sessionTool = sessionSubcommands[firstArg];
+  if (sessionTool) {
+    tool = sessionTool;
+    positional = [tool, ...positional.slice(2)];
+    firstArg = positional[1];
+  }
+}
+
 if (tool === "cookie" && firstArg) {
   const cookieSubcommands = {
     list: "cookie.list",
@@ -2678,6 +2814,12 @@ const PRIMARY_ARG_MAP = {
   "window.new": "url",
   "window.focus": "id",
   "window.close": "id",
+  "session.new": "name",
+  "session.ensure": "name",
+  "session.info": "name",
+  "session.close": "name",
+  "session.rebind": "name",
+  "session.reopen": "name",
   "locate.role": "role",
   "locate.text": "text",
   "locate.label": "label",
@@ -2748,6 +2890,10 @@ if (firstArg !== undefined) {
   }
 }
 
+if (["session.new", "session.ensure", "session.reopen"].includes(tool) && positional[2] !== undefined && toolArgs.url === undefined) {
+  toolArgs.url = positional[2];
+}
+
 if ((tool === "js" || tool === "frame.js") && toolArgs.file) {
   try {
     toolArgs.code = fs.readFileSync(toolArgs.file, "utf8");
@@ -2767,6 +2913,13 @@ if (tool === "batch" && toolArgs.file) {
     console.error(`Error: Failed to read batch file: ${e.message}`);
     process.exit(1);
   }
+} else if (tool === "batch" && typeof toolArgs.actions === "string") {
+  try {
+    toolArgs.actions = JSON.parse(toolArgs.actions);
+  } catch (e) {
+    console.error(`Error: Failed to parse batch actions: ${e.message}`);
+    process.exit(1);
+  }
 }
 
 // Handle select command: capture multiple values after selector
@@ -2786,22 +2939,30 @@ if (toolArgs.into && !toolArgs.selector) {
 }
 
 const globalOpts = {};
+const explicitSession = toolArgs.session;
+delete toolArgs.session;
+const environmentSession = process.env.SURF_SESSION;
+const noWait = toolArgs["no-wait"] === true;
+delete toolArgs["no-wait"];
+
 if (toolArgs["tab-id"] !== undefined) {
   const tid = parseInt(toolArgs["tab-id"], 10);
-  if (isNaN(tid)) {
-    console.error("Error: --tab-id must be a number");
+  if (!Number.isInteger(tid) || tid <= 0) {
+    console.error("Error: --tab-id must be a positive number");
     process.exit(1);
   }
-  globalOpts.tabId = tid;
+  if (tool === "session.rebind") toolArgs.tabId = tid;
+  else globalOpts.tabId = tid;
   delete toolArgs["tab-id"];
 }
 if (toolArgs["window-id"] !== undefined) {
   const wid = parseInt(toolArgs["window-id"], 10);
-  if (isNaN(wid)) {
-    console.error("Error: --window-id must be a number");
+  if (!Number.isInteger(wid) || wid <= 0) {
+    console.error("Error: --window-id must be a positive number");
     process.exit(1);
   }
-  globalOpts.windowId = wid;
+  if (["session.new", "session.ensure", "session.reopen"].includes(tool)) toolArgs.windowId = wid;
+  else globalOpts.windowId = wid;
   delete toolArgs["window-id"];
 }
 if (toolArgs["network-path"] !== undefined && typeof toolArgs["network-path"] !== "string") {
@@ -2912,6 +3073,39 @@ if (methodFlag === "js") {
   }
 }
 
+const finalClassification = classifyTool(finalTool, toolArgs);
+if (explicitSession !== undefined) {
+  if (typeof explicitSession !== "string" || !explicitSession) {
+    console.error("Error: --session requires a session name");
+    process.exit(1);
+  }
+  if (finalClassification.targetUse !== "default-tab" || finalTool.startsWith("session.")) {
+    console.error(`Error: --session does not apply to ${finalTool}`);
+    process.exit(1);
+  }
+  if (globalOpts.tabId || globalOpts.windowId) {
+    console.error("Error: use either --session or --tab-id/--window-id, not both");
+    process.exit(1);
+  }
+  globalOpts.session = explicitSession;
+  globalOpts.sessionSource = "explicit";
+} else if (
+  environmentSession &&
+  finalClassification.targetUse === "default-tab" &&
+  !globalOpts.tabId &&
+  !globalOpts.windowId &&
+  !finalTool.startsWith("session.")
+) {
+  globalOpts.session = environmentSession;
+  globalOpts.sessionSource = "environment";
+}
+if (noWait) globalOpts.admission = { wait: false };
+
+if (finalClassification.scope === "provider") {
+  const suffix = globalOpts.session ? ` Session ${globalOpts.session} remains selected for page context.` : "";
+  console.error(`[surf] ${finalTool} requires exclusive browser access; other sessions will queue until it finishes.${suffix}`);
+}
+
 if (streamMode && (tool === "console" || tool === "network")) {
   const streamType = tool === "console" ? "STREAM_CONSOLE" : "STREAM_NETWORK";
   const streamOpts = {
@@ -2967,7 +3161,8 @@ if (streamMode && (tool === "console" || tool === "network")) {
         }
       }
       if (msg.error) {
-        console.error("Error:", msg.error);
+        const text = msg.error?.content?.[0]?.text || msg.error?.message || String(msg.error);
+        console.error("Error:", text);
         sock.end();
         process.exit(1);
       }
@@ -2976,7 +3171,11 @@ if (streamMode && (tool === "console" || tool === "network")) {
         sock.end();
         process.exit(1);
       }
-      if (msg.type === "stream_started") return;
+      if (msg.type === "stream_started") {
+        const context = formatTargetContext(msg.target);
+        if (context) console.error(context);
+        return;
+      }
       if (msg.type === "console_event") {
         const { level, text, timestamp } = msg;
         if (streamLevel && level !== streamLevel) return;
@@ -3227,7 +3426,6 @@ if (finalTool === "record") {
   return;
 }
 
-installBrowserLock(lockOptions, endpoint);
 let socket;
 let timeout;
 
@@ -3254,7 +3452,7 @@ socket = connectEndpoint(endpoint, () => {
   writeFrame(socket, request).catch((error) => socket.destroy(error));
 });
 
-const requestTimeout = resolveRequestDeadlineMs(tool, options);
+const requestTimeout = resolveRequestDeadlineMs(finalTool, toolArgs);
 timeout = setTimeout(() => {
   console.error(`Error: Request timed out (${requestTimeout / 1000}s)`);
   socket.destroy();
@@ -3295,8 +3493,45 @@ socket.on("close", () => {
   clearTimeout(timeout);
 });
 
+function formatTargetContext(target) {
+  if (!target) return null;
+  const fields = [];
+  if (target.session) fields.push(`session=${target.session}`);
+  if (target.tabId !== undefined) fields.push(`tab=${target.tabId}`);
+  if (target.windowId !== undefined) fields.push(`window=${target.windowId}`);
+  if (target.queuedMs > 0) fields.push(`queued=${target.queuedMs}ms`);
+  return fields.length > 0 ? `[surf ${fields.join(" ")}]` : null;
+}
+
+function printResponseContext(response) {
+  const context = formatTargetContext(response.target);
+  if (context) console.error(context);
+  if (response.notice && finalClassification.scope !== "provider") {
+    console.error(`[surf] ${response.notice}`);
+  }
+}
+
+function queueSummary(queue) {
+  if (!queue) return "unknown";
+  const pieces = [
+    `own-tab=${queue.active ? "active" : "idle"}`,
+    `own-queued=${queue.queued || 0}`,
+  ];
+  if (queue.blockedBy) pieces.push(`blocked-by=${queue.blockedBy}`);
+  if (queue.browserWriter) {
+    pieces.push(`writer=${queue.browserWriter.scope}${queue.browserWriter.session ? `:${queue.browserWriter.session}` : ""}`);
+  } else if (queue.queuedBrowserWriters) {
+    pieces.push(`writers-waiting=${queue.queuedBrowserWriters}`);
+  }
+  if (Array.isArray(queue.otherActiveTabLanes) && queue.otherActiveTabLanes.length > 0) {
+    pieces.push(`other-tabs-active=${queue.otherActiveTabLanes.length}`);
+  }
+  return pieces.join(" ");
+}
+
 async function handleResponse(response) {
   clearTimeout(timeout);
+  printResponseContext(response);
 
   if (response.error) {
     const errContent = response.error.content?.[0]?.text || JSON.stringify(response.error);
@@ -3355,12 +3590,48 @@ async function handleResponse(response) {
   }
 
   if (wantJson) {
-    console.log(JSON.stringify(data ?? null, null, 2));
+    const output = response.target || response.notice
+      ? { result: data ?? null, target: response.target || null, notice: response.notice || null }
+      : data ?? null;
+    console.log(JSON.stringify(output, null, 2));
     socket.end();
     process.exit(0);
   }
 
-  if (tool === "screenshot" && data?.base64 && (outputPath || toolArgs.savePath)) {
+  if (finalTool === "session.list") {
+    const sessions = Array.isArray(data?.sessions) ? data.sessions : [];
+    if (sessions.length === 0) {
+      console.log("No browser sessions. Create one with: surf session.ensure <name> about:blank");
+    } else {
+      for (const entry of sessions) {
+        console.log([
+          entry.name,
+          entry.status,
+          `tab=${entry.tabId ?? "-"}`,
+          `window=${entry.windowId ?? "-"}`,
+          `mode=${entry.mode || "-"}`,
+          queueSummary(entry.queue),
+          entry.lastUrl || "",
+        ].join("\t"));
+      }
+    }
+  } else if (finalTool === "session.info" && data?.session) {
+    const entry = data.session;
+    console.log(`Session: ${entry.name}`);
+    console.log(`Status: ${entry.status}`);
+    console.log(`Target: tab=${entry.tabId ?? "-"} window=${entry.windowId ?? "-"} mode=${entry.mode || "-"}`);
+    console.log(`Ownership: ${entry.ownership || "unknown"}`);
+    console.log(`URL: ${entry.currentUrl || entry.lastUrl || "(unknown)"}`);
+    console.log(`Queue: ${queueSummary(entry.queue)}`);
+    if (data.sharedProfile) console.log(`Profile: ${data.sharedProfile}`);
+  } else if (["session.new", "session.ensure", "session.rebind", "session.reopen"].includes(finalTool) && data?.session) {
+    const entry = data.session;
+    const action = data.created ? "created" : data.reopened ? "reopened" : data.rebound ? "rebound" : "ready";
+    console.log(`Session ${entry.name} ${action}: tab=${entry.tabId} window=${entry.windowId} mode=${entry.mode} status=${entry.status}`);
+    console.log(`Use: export SURF_SESSION=${entry.name}`);
+  } else if (finalTool === "session.close" && data?.success) {
+    console.log(`Session ${data.name} closed (${data.targetClosed ? "target closed" : "target kept"})`);
+  } else if (tool === "screenshot" && data?.base64 && (outputPath || toolArgs.savePath)) {
     const saveTo = transferPlan.downloads?.[0]?.destination || toolArgs.savePath || outputPath;
     fs.writeFileSync(saveTo, Buffer.from(data.base64, "base64"));
 

package/native/do-executor.cjs

@@ -13,6 +13,11 @@ function sendDoRequest(toolName, toolArgs, context = {}) {
   };
   if (context.tabId) request.tabId = context.tabId;
   if (context.windowId) request.windowId = context.windowId;
+  if (context.session) {
+    request.session = context.session;
+    request.sessionSource = context.sessionSource || "environment";
+  }
+  if (context.admission) request.admission = context.admission;
   const timeoutMs = context.timeoutMs || resolveRequestDeadlineMs(toolName, toolArgs);
   const endpoint = context.endpoint || selectEndpoint([]).endpoint;
   const prepared = endpoint.kind === "remote"