surf-cli 2.17.0 → 2.18.0

package/native/cli.cjs

@@ -33,6 +33,7 @@ const { selectEndpoint, connectEndpoint, formatEndpointError } = require("./endp
 const { createFrameParser, createSocketWriter, writeFrame } = require("./remote-transport.cjs");
 const { resolveRequestDeadlineMs } = require("./host-sessions.cjs");
 const { classifyTool } = require("./tool-scope.cjs");
+const { parseVideoFps, validateVideoOutputPath } = require("./video-recorder.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 {} }
@@ -313,6 +314,14 @@ const TOOLS = {
         args: [],
         opts: { refresh: "Validate every binding against Chrome" },
       },
+      "session.cleanup": {
+        desc: "Remove idle session bindings and close only Surf-created targets",
+        args: [],
+        opts: {
+          "idle-after": "Required threshold such as 30s, 5m, 1h, or 1d",
+          "dry-run": "Report matches without removing bindings or closing targets",
+        },
+      },
       "session.info": {
         desc: "Show one session, target, and scheduler queue state",
         args: ["name"],
@@ -346,7 +355,7 @@ const TOOLS = {
         args: ["query"],
         opts: {
           "with-page": "Include current page context",
-          model: "Model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol, or a visible model label",
+          model: "Model: gpt-6-astra, latest, gpt-5.6-sol, gpt-5.5",
           file: "Attach file",
           timeout: "Timeout in seconds (default: 2700 = 45min)"
         },
@@ -619,6 +628,37 @@ const TOOLS = {
       "snap": { desc: "Alias for screenshot (auto-saves to /tmp)", args: [], alias: "screenshot" },
     }
   },
+  video: {
+    desc: "Local WebM recording",
+    commands: {
+      "video.start": {
+        desc: "Start local WebM recording",
+        args: ["output"],
+        opts: {
+          fps: "Frames per second (default: 30, max: 60)",
+        },
+        examples: [{ cmd: "video start ./demo.webm --fps 30", desc: "Start recording" }],
+      },
+      "video.stop": {
+        desc: "Stop local WebM recording",
+        args: [],
+        examples: [{ cmd: "video stop", desc: "Stop recording" }],
+      },
+      "video.status": {
+        desc: "Show local WebM recording status",
+        args: [],
+        examples: [{ cmd: "video status", desc: "Show status" }],
+      },
+      "video.restart": {
+        desc: "Restart local WebM recording",
+        args: ["output"],
+        opts: {
+          fps: "Frames per second (default: 30, max: 60)",
+        },
+        examples: [{ cmd: "video restart ./take2.webm --fps 60", desc: "Restart recording" }],
+      },
+    },
+  },
   scroll: {
     desc: "Scrolling",
     commands: {
@@ -1561,8 +1601,8 @@ 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",
+  "session.new", "session.ensure", "session.list", "session.cleanup", "session.info", "session.close", "session.rebind", "session.reopen",
+  "ai", "screenshot", "record", "video.start", "video.stop", "video.status", "video.restart", "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",
   "javascript_tool", "health", "smoke",
@@ -1621,6 +1661,10 @@ const SEE_ALSO = {
   "navigate": ["wait.load", "page.read"],
   "screenshot": ["page.read", "scroll.bottom for fullpage"],
   "record": ["screenshot", "animate-audit", "perf-audit"],
+  "video.start": ["video.stop", "video.status"],
+  "video.stop": ["video.status", "video.restart"],
+  "video.status": ["video.start", "video.stop"],
+  "video.restart": ["video.stop", "video.status"],
   "animate-audit": ["screenshot", "record", "perf-audit", "js"],
   "perf-audit": ["record", "animate-audit", "perf.metrics", "console"],
   "search": ["locate.text", "page.read"],
@@ -1641,11 +1685,16 @@ Usage: surf <command> [args] [options]
 
 Common Commands:
   session.ensure <name> [url]  Idempotently create or reuse a tab-bound session
+  session.cleanup --idle-after <duration>  Remove idle sessions (opt-in; use --dry-run first)
   navigate <url>     Go to URL (alias: go)
   click <ref>        Click element by ref or selector
   type <text>        Type text at cursor or into element
   screenshot         Capture screenshot (alias: snap)
   record             Capture screenshot frames into an animated GIF
+  video start <path> Start a long-running local WebM recording
+  video stop         Stop the active WebM recording
+  video status       Show WebM recording status
+  video restart <path> Replace the active WebM recording
   animate-audit      JSON timeline of element animation/style samples
   perf-audit         PerformanceObserver snapshot for motion/jank debugging
   page.read          Get page accessibility tree (alias: read)
@@ -1698,6 +1747,7 @@ Type: surf type "text" --submit                  # use --ref e5 to target a fiel
 Screenshot: surf screenshot /tmp/shot.png         # auto-saves to /tmp if no path
 Full page screenshot: surf screenshot --full-page /tmp/full.png
 Record animation: surf record --duration 2000 --fps 10 --output /tmp/anim.gif
+Video recording: surf video start ./demo.webm --fps 30; surf video stop
 Animation audit: surf animate-audit --selector ".thing" --duration 2000 --fps 10
 Performance audit: surf perf-audit --duration 3000 --trigger "click:.cta" --output /tmp/perf.json
 JavaScript: surf js "return document.title"
@@ -1707,6 +1757,7 @@ Device/viewport: surf emulate.device "iPhone 14" | surf resize 375 812
 Cookies: surf cookie list | surf cookie get "name" | surf cookie delete "name"
 Session targeting: surf --session research read | SURF_SESSION=research surf read
 Session status/queue: surf session.info research | surf session.list --refresh
+Session cleanup: surf session.cleanup --idle-after 1h [--dry-run]
 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
@@ -2014,12 +2065,17 @@ Options:
                   On WSL2, auto installs for Windows Chrome. Use linux for WSLg/Linux browsers.
   --listen <tailscale-ip>:<port>
                   Requires surf remote authorize <label> --output <path> first.
+  --socket-mode <600|660>
+                  Persist the local POSIX socket mode (default: 600); 660 requires --socket-group.
+  --socket-group <group-or-gid>
+                  Persist the local POSIX socket group for mode 660.
 
 Examples:
   surf install hnfbepgmaoklhekckbpjnleifhahkcpl
   surf install hnfbepgmaoklhekckbpjnleifhahkcpl --browser brave
   surf install hnfbepgmaoklhekckbpjnleifhahkcpl --browser all
   surf install hnfbepgmaoklhekckbpjnleifhahkcpl --target linux
+  surf install hnfbepgmaoklhekckbpjnleifhahkcpl --socket-mode 660 --socket-group surf
 `);
     process.exit(0);
   }
@@ -2686,6 +2742,7 @@ if (tool === "session" && firstArg) {
     new: "session.new",
     ensure: "session.ensure",
     list: "session.list",
+    cleanup: "session.cleanup",
     info: "session.info",
     close: "session.close",
     rebind: "session.rebind",
@@ -2715,6 +2772,21 @@ if (tool === "cookie" && firstArg) {
   }
 }
 
+if (tool === "video" && firstArg) {
+  const videoSubcommands = {
+    start: "video.start",
+    stop: "video.stop",
+    status: "video.status",
+    restart: "video.restart",
+  };
+  const videoTool = videoSubcommands[firstArg];
+  if (videoTool) {
+    tool = videoTool;
+    positional = [tool, ...positional.slice(2)];
+    firstArg = positional[1];
+  }
+}
+
 if (!tool) {
   console.error("Error: No command specified");
   process.exit(1);
@@ -2879,6 +2951,11 @@ if (tool === "record" && firstArg !== undefined && toolArgs.output === undefined
   firstArg = undefined;
 }
 
+if ((tool === "video.start" || tool === "video.restart") && firstArg !== undefined && toolArgs.output === undefined) {
+  toolArgs.output = firstArg;
+  firstArg = undefined;
+}
+
 if (firstArg !== undefined) {
   const primaryKey = PRIMARY_ARG_MAP[tool];
   if (primaryKey && toolArgs[primaryKey] === undefined) {
@@ -3007,8 +3084,11 @@ if (tool === "gemini") {
 if (tool === "network.export" && outputPath !== undefined) {
   toolArgs.output = outputPath;
 }
+if ((tool === "video.start" || tool === "video.restart") && outputPath !== undefined) {
+  toolArgs.output = outputPath;
+}
 
-if ((tool === "screenshot" || tool === "record" || tool === "perf-audit" || tool === "page.save") && outputPath && typeof outputPath !== "string") {
+if ((tool === "screenshot" || tool === "record" || tool === "perf-audit" || tool === "page.save" || tool === "video.start" || tool === "video.restart") && outputPath && typeof outputPath !== "string") {
   console.error("Error: --output requires a file path");
   process.exit(1);
 }
@@ -3018,6 +3098,16 @@ if (tool === "page.save" && !outputPath) {
   process.exit(1);
 }
 
+if (tool === "video.start" || tool === "video.restart") {
+  try {
+    parseVideoFps(toolArgs.fps);
+    validateVideoOutputPath(toolArgs.output, { createParent: false });
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
 if (tool === "screenshot" && outputPath) {
   toolArgs.savePath = outputPath;
   if (options.full) toolArgs.full = true;
@@ -3615,6 +3705,21 @@ async function handleResponse(response) {
         ].join("\t"));
       }
     }
+  } else if (finalTool === "session.cleanup" && data?.success) {
+    const removed = Array.isArray(data.removed) ? data.removed : [];
+    if (removed.length === 0) {
+      console.log("No browser sessions matched the idle cleanup threshold.");
+    } else {
+      const verb = data.dryRun ? "Would remove" : "Removed";
+      for (const entry of removed) {
+        const target = entry.targetAction === "close"
+          ? "target closed"
+          : entry.targetAction === "keep"
+            ? "target kept"
+            : "target already gone";
+        console.log(`${verb} session ${entry.name} tab=${entry.tabId ?? "-"} (${target})`);
+      }
+    }
   } else if (finalTool === "session.info" && data?.session) {
     const entry = data.session;
     console.log(`Session: ${entry.name}`);
@@ -3631,6 +3736,18 @@ async function handleResponse(response) {
     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 (finalTool === "video.start" && data?.status === "active") {
+    console.log(`Video recording started: ${data.path} (${data.fps}fps)`);
+  } else if (finalTool === "video.restart" && data?.status === "active") {
+    console.log(`Video recording restarted: ${data.path} (${data.fps}fps)`);
+  } else if (finalTool === "video.stop" && data?.status === "stopped") {
+    console.log(`Saved video recording to ${data.path} (${data.frames} frames, ${data.capturedFrames} captured frames @ ${data.fps}fps)`);
+  } else if (finalTool === "video.status") {
+    if (data?.status === "active") {
+      console.log(`Video recording active: ${data.path} (${data.fps}fps, ${data.frames} frames, ${data.capturedFrames} captured frames)`);
+    } else {
+      console.log("No active video recording");
+    }
   } 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/file-transfer.cjs

@@ -279,6 +279,9 @@ function validateLocalToolPaths(tool, args = {}) {
     if (args.savePath !== undefined && args.output !== undefined) throw transferError("screenshot accepts only one output path", "SURF_PATH_FIELD");
     for (const field of ["savePath", "output"]) if (args[field] !== undefined) normalized[field] = normalize(field, args[field]);
   }
+  if (tool === "video.start" || tool === "video.restart") {
+    if (args.output !== undefined) normalized.output = normalize("output", args.output);
+  }
   if (tool === "network.export") {
     if (args.har !== undefined && typeof args.har !== "boolean") throw transferError("network.export har must be boolean", "SURF_PATH_FIELD");
     if (args.jsonl !== undefined && typeof args.jsonl !== "boolean") throw transferError("network.export jsonl must be boolean", "SURF_PATH_FIELD");
@@ -356,6 +359,7 @@ function prepareRemoteTool(tool, args = {}) {
   if (args.autoScreenshot === true && !AUTO_SCREENSHOT_TOOLS.includes(tool)) throw transferError(`autoScreenshot is not supported for ${tool}`, "SURF_PATH_DESCRIPTOR");
   if (args.autoScreenshotOutput !== undefined) throw transferError("autoScreenshotOutput is internal", "SURF_PATH_DESCRIPTOR");
   if (tool === "record") throw transferError("record is not supported with remote endpoint", "SURF_REMOTE_UNSUPPORTED");
+  if (typeof tool === "string" && tool.startsWith("video.")) throw transferError("video recording is not supported with remote endpoint", "SURF_REMOTE_UNSUPPORTED");
   if (tool === "aistudio.build") throw transferError("aistudio.build is not supported for remote connections", "SURF_REMOTE_UNSUPPORTED");
   if (tool === "smoke" && args.screenshot !== undefined) throw transferError("smoke screenshots are not supported for remote connections", "SURF_REMOTE_UNSUPPORTED");
   if (tool === "network.export") {
@@ -437,7 +441,7 @@ async function materializeRemoteTool({ tool, args: rawArgs = {}, metadata = null
   const uploads = meta.uploads === undefined ? [] : meta.uploads;
   const downloads = meta.downloads === undefined ? [] : meta.downloads;
   if (!Array.isArray(pathRefs) || !Array.isArray(uploads) || !Array.isArray(downloads) || uploads.length > 1 || downloads.length > 1) throw transferError("invalid transfer metadata", "SURF_PATH_DESCRIPTOR");
-  if (tool === "record" || tool === "aistudio.build") throw transferError(`${tool} is not supported for remote connections`, "SURF_REMOTE_UNSUPPORTED");
+  if (tool === "record" || (typeof tool === "string" && tool.startsWith("video.")) || tool === "aistudio.build") throw transferError(`${tool} is not supported for remote connections`, "SURF_REMOTE_UNSUPPORTED");
   if (tool === "smoke" && args.screenshot !== undefined) throw transferError("smoke screenshots are not supported for remote connections", "SURF_REMOTE_UNSUPPORTED");
   if (tool === "network.export") {
     if (args.har !== undefined && typeof args.har !== "boolean") throw transferError("network.export har must be boolean", "SURF_PATH_FIELD");

package/native/host-helpers.cjs

@@ -51,7 +51,7 @@ function formatToolContent(result, log = () => {}, options = {}) {
   
   if (!result) return text("OK");
 
-  if (result.session || Array.isArray(result.sessions) || Object.hasOwn(result, "targetClosed")) {
+  if (result.session || Array.isArray(result.sessions) || Array.isArray(result.removed) || Object.hasOwn(result, "targetClosed")) {
     return text(JSON.stringify(result, null, 2));
   }