surf-cli 2.8.0 → 2.10.0

package/README.md

@@ -43,7 +43,7 @@ Surf takes a different approach:
 |---------|------|-------|------------------|--------------|-------------|
 | Agent-agnostic | Yes | No (Manus only) | No (Claude only) | Partial | No (Claude skill) |
 | Zero config | Yes | No (subscription) | No (subscription) | No (MCP setup) | No (relay server) |
-| Local-only | Yes | No (cloud) | Partial | Yes | Partial |
+| Self-hosted (local or Tailnet) | Yes | No (cloud) | Partial | Yes | Partial |
 | CLI interface | Yes | No | No | No | No |
 | Free | Yes | No | No | Yes | Yes |
 | AI via browser cookies | Yes | No | No | No | No |
@@ -108,6 +108,88 @@ surf uninstall --all            # All browsers + wrapper files
 surf uninstall --target linux   # Remove WSLg/Linux-browser config from WSL2
 ```
 
+### Remote Surf over Tailscale
+
+Remote Surf runs the browser and native host on one Tailnet machine while the CLI runs on another. The listener is available only while the browser extension's native-messaging connection is alive. Tailnet reachability is not authorization: every remote client also needs its own Surf credential.
+
+On the browser host, authorize a client before installing the listener:
+
+```bash
+surf remote authorize agent-macbook --output ~/agent-macbook.surf-credential.json
+surf remote list
+surf install <extension-id> --listen 100.101.102.103:4321
+```
+
+`authorize` creates a mode-0600 credential containing the client's Ed25519 private identity and the pinned host identity. Move it to that client through an existing secure channel, then remove the generated copy from the host if it is no longer needed there. The host keeps only the client's public identity in `~/.surf/remote/remote-clients.json`.
+
+From the authorized client:
+
+```bash
+surf --remote 100.101.102.103:4321 \
+  --remote-credential ~/.config/surf/agent-macbook.json \
+  tab.list
+
+# Environment equivalent
+SURF_REMOTE=100.101.102.103:4321 \
+SURF_REMOTE_CREDENTIAL=~/.config/surf/agent-macbook.json \
+  surf tab.list
+```
+
+Surf performs mutual Ed25519 challenge-response with fresh nonces and checks authorization throughout the connection. A credential grants the same browser and host-file authority as a trusted local Surf user. Give each client its own credential, do not share it, and revoke it immediately if the client or file is lost:
+
+```bash
+surf remote revoke agent-macbook
+surf remote list
+```
+
+`--remote <host>:<port>` takes precedence over `SURF_REMOTE`; `--remote-credential` takes precedence over `SURF_REMOTE_CREDENTIAL`. A selected remote endpoint overrides `SURF_SOCKET` and the default local socket. Local and remote requests share one bounded FIFO browser lease, so they cannot race each other. Disconnects and timeouts abort queued or in-flight work and hold the lease until request-owned cleanup drains or the hard deadline is reached. Browser side effects that already completed are not rolled back.
+
+`surf install --listen` persists the explicit Tailnet address in the native-host wrapper. Re-run `surf install` without `--listen` to remove it. The address must be a Tailscale IPv4 or IPv6 address with a port; Surf does not bind every interface. Remote listeners currently require a POSIX browser host and are not supported by Windows native-host wrappers.
+
+Keep Tailscale policy restrictions as defense in depth. For example:
+
+```json
+{
+  "acls": [
+    {
+      "action": "accept",
+      "src": ["tag:surf-agent"],
+      "dst": ["tag:surf-browser:4321"]
+    }
+  ]
+}
+```
+
+Adapt tags and ports to your Tailnet. Surf authentication does not replace Tailnet policy, and Surf does not add a separate TLS or SSH tunnel.
+
+**Operations and troubleshooting**
+
+```bash
+tailscale status
+tailscale ping 100.101.102.103
+surf doctor --remote 100.101.102.103:4321 \
+  --remote-credential ~/.config/surf/agent-macbook.json
+```
+
+Use `tailscale status` and `tailscale ping` to confirm reachability, then use `doctor` to verify endpoint selection and authentication.
+
+**Remote filesystem and transfer semantics**
+
+Unprefixed paths and `local:` paths refer to the client. Only `remote:/absolute/path` refers directly to the browser host. For example:
+
+```bash
+surf --remote "$SURF_REMOTE" --remote-credential "$SURF_REMOTE_CREDENTIAL" \
+  upload --ref e5 --files ./client-file.pdf
+surf --remote "$SURF_REMOTE" --remote-credential "$SURF_REMOTE_CREDENTIAL" \
+  screenshot --output local:./shot.png
+surf --remote "$SURF_REMOTE" --remote-credential "$SURF_REMOTE_CREDENTIAL" \
+  network.export --output remote:/var/tmp/network.har --har
+```
+
+Client-local inputs are staged privately on the host and removed after the request. Client-local outputs are downloaded with size/hash verification and atomic destination replacement. `surf js --file` and `perf-audit --output` are handled by the client itself. `network.export` defaults to a generated client-local `.json`, `.jsonl`, or `.har` path. Gemini edits default to client-local `edited.png`. Successful remote actions transfer their automatic screenshot to a generated client-local path; `--auto-capture` on failure remains a separate screenshot and console diagnostic.
+
+The remote single-file boundary supports one `upload` file, one ChatGPT attachment, or one Gemini attachment/edit input, plus one screenshot, network export, or Gemini image output. Transfers are limited to 256 MiB per file, 512 MiB and 32 files per connection, with 256 KiB decoded chunks. Remote `record`, `aistudio.build`, smoke screenshot directories, directory transfer, and multi-file inputs are intentionally rejected. A `remote:` path bypasses transfer and gives the trusted client direct authority over that absolute host path.
+
 ### Development Setup
 
 ```bash
@@ -146,6 +228,7 @@ surf read --no-text                 # Accessibility tree only (no text)
 surf read --depth 3                 # Limit tree depth (smaller output)
 surf read --compact                 # Remove empty structural elements
 surf read --depth 3 --compact       # Both (60% smaller output)
+surf read --max-bytes 2000          # Cap visible text on a UTF-8 byte boundary
 surf page.text                      # Raw text content only
 surf page.state                     # Modals, loading state, scroll position
 ```
@@ -184,6 +267,7 @@ surf frame.switch --selector "#checkout-frame"  # Switch by CSS selector
 # Now all commands target the iframe
 surf read                           # Read iframe content
 surf click e5                       # Click in iframe
+surf type "4242" --into "#card-number"
 surf locate.role button --action click
 
 surf frame.main                     # Return to main page
@@ -195,8 +279,9 @@ surf frame.main                     # Return to main page
 surf click e5                       # Click by element ref
 surf click --selector ".btn"        # Click by CSS selector
 surf click 100 200                  # Click by coordinates
-surf type "hello" --submit          # Type and press Enter
-surf type "email@example.com" --ref e12  # Type into specific element
+surf type "hello" --submit          # Type at the current focus with CDP events
+surf type "email@example.com" --ref e12  # Fill an element from page.read
+surf type "hello" --into "#message"     # Fill a selector in the active frame
 surf key Escape                     # Press key
 surf scroll down 800                # Scroll down 800px
 surf scroll bottom                  # Scroll to bottom
@@ -252,6 +337,7 @@ surf tab.list
 surf tab.new "https://example.com"
 surf tab.switch 123
 surf tab.close 123
+surf tab.move 123 --to-window 456   # Move one tab; use --ids 123,124 for several
 surf tab.name "dashboard"           # Name current tab
 surf tab.switch "dashboard"         # Switch by name
 surf tab.group --name "Work" --color blue
@@ -377,7 +463,7 @@ surf gemini "analyze" --file data.csv                         # Attach file
 surf gemini "a robot surfing" --generate-image /tmp/robot.png # Generate image
 surf gemini "add sunglasses" --edit-image photo.jpg --output out.jpg
 surf gemini "summarize" --youtube "https://youtube.com/..."   # YouTube analysis
-surf gemini "hello" --model gemini-2.5-flash                  # Model selection
+surf gemini "hello" --model gemini-3.5-flash                  # Model selection
 
 # Perplexity
 surf perplexity "what is quantum computing"
@@ -450,6 +536,7 @@ surf network --type json              # Only JSON responses
 surf network --status 4xx,5xx         # Only errors
 surf network --since 5m               # Last 5 minutes
 surf network --exclude-static         # Skip images/fonts/css/js
+surf network -vv --body-mode text      # Full entries with capped text bodies
 
 # Drill down
 surf network.get r_001                # Full request/response details
@@ -460,10 +547,12 @@ surf network.origins                  # List captured domains
 # Management
 surf network.clear                    # Clear captured data
 surf network.stats                    # Capture statistics
+surf network.export --har --output ./trace.har
 ```
 
-Storage location: `/tmp/surf/` (override with `--network-path` or `SURF_NETWORK_PATH` env).
-Auto-cleanup: 24 hours TTL, 200MB max.
+Response bodies are fetched at `Network.loadingFinished` when capture is enabled. `--body-mode none|text|all`, `--per-body-bytes`, and `--total-body-bytes` control content and caps; exports include completeness metadata.
+
+Storage location: `~/.surf/state/network/` (override with `SURF_NETWORK_PATH` in the native host environment). Surf creates private `0700` directories and `0600` files and rejects symlink targets. Auto-cleanup: 24 hours TTL, 200MB max.
 
 ### Workflows
 
@@ -591,6 +680,48 @@ surf workflow.validate ./my-workflow.json
 
 **Supported commands:** All surf commands work in workflows. Use aliases (`go`, `snap`, `read`) or full names (`navigate`, `screenshot`, `page.read`).
 
+### Playbooks
+
+Use `surf do` for a direct sequence of browser commands. Use a playbook for a reusable site capability that can try a browser-session network request and fall back to a workflow when the endpoint drifts.
+
+```bash
+surf playbook list
+surf pb show page
+surf pb ops page
+surf use page read --json
+
+# Write ops require explicit authorization and a durable duplicate-safety receipt.
+surf use <site> <write-op> --write --resource-id 123
+```
+
+Project playbooks in `./.surf/playbooks/` override user playbooks in `~/.surf/playbooks/`; built-ins are the final fallback. `show` reports the selected source. Provider compatibility commands continue to use their validated command paths until provider playbooks have real login-flow validation.
+
+Author a playbook from redacted recent activity or an explicit evidence record:
+
+```bash
+surf pb suggest --since 1h
+surf pb save example --op read --from-recent 1h
+surf pb record start example --op read --network --watch
+surf pb record mark "loaded results"
+surf pb record stop --draft
+surf pb save --from-record <record-id>
+surf pb trace export --from-record <record-id> --har ./trace.har
+surf pb export example --out ./example-playbook
+surf pb import ./example-playbook
+```
+
+Records, traces, receipts, and recent-use journals live under private Surf state. Input values and authentication headers are redacted by default; `--include-input-values` is an explicit recording choice.
+
+Generate a standalone client only from an observed or validated read endpoint:
+
+```bash
+surf pb client derive example --op read --from-record <record-id> --request-id <request-id> --out ./client
+surf pb client export example --op read --out ./client
+surf pb client verify ./client
+```
+
+Generated manifests declare provenance and authentication environment inputs. Surf excludes cookies, bearer tokens, and captured credentials and does not export write-capable clients without explicit review.
+
 ## Global Options
 
 ```bash
@@ -601,14 +732,17 @@ surf workflow.validate ./my-workflow.json
 --no-lock          # Bypass the per-socket browser request lock
 --no-screenshot    # Skip auto-screenshot after actions
 --full             # Full resolution screenshots (skip resize)
---network-path <path>  # Custom path for network logs (default: /tmp/surf, or SURF_NETWORK_PATH env)
 ```
 
 ## Environment Variables
 
 ```bash
-SURF_NETWORK_PATH         # Path for network capture logs (default: /tmp/surf)
+SURF_NETWORK_PATH         # Native-host network state root (default: ~/.surf/state/network)
 SURF_SOCKET               # Socket path or named pipe (default: /tmp/surf.sock, Windows: //./pipe/surf)
+SURF_REMOTE               # Remote Surf endpoint as host:port (overrides SURF_SOCKET)
+SURF_REMOTE_CREDENTIAL    # Client Ed25519 credential for the selected remote endpoint
+SURF_REMOTE_STATE_DIR     # Host identity/authorization directory (default: ~/.surf/remote)
+SURF_LISTEN               # Native-host Tailnet bind address as <tailscale-ip>:<port>
 SURF_NODE_PATH            # Path to node binary (for native host wrapper)
 SURF_HOST_PATH            # Path to native/host.cjs (for native host wrapper)
 SURF_EXTENSION_PATH       # Path to extension dist/ directory
@@ -616,6 +750,10 @@ SURF_EXTENSION_PATH       # Path to extension dist/ directory
 
 **Use cases:**
 - `SURF_SOCKET`: Advanced socket override. Set it for both the native host and CLI if you need a non-default socket, including separate sockets for separate browser/profile instances in hard-isolated multi-agent workflows. Each socket gets an independent request lock.
+- `SURF_REMOTE`: Remote client endpoint. `--remote <host>:<port>` overrides it; both override `SURF_SOCKET`.
+- `SURF_REMOTE_CREDENTIAL`: Credential used for mutual remote authentication. `--remote-credential <path>` overrides it.
+- `SURF_REMOTE_STATE_DIR`: Advanced host-side override for the mode-0700 identity and client registry directory.
+- `SURF_LISTEN`: Native-host listener address on the browser machine. Use `surf install ... --listen <tailscale-ip>:<port>` to persist it in that host's wrapper.
 - `SURF_NODE_PATH` / `SURF_HOST_PATH`: Package manager installs (e.g., Nix) that store binaries in non-standard locations
 - `SURF_EXTENSION_PATH`: Package managers that create stable symlinks instead of changing paths on reinstall
 

package/native/abort.cjs

@@ -0,0 +1,65 @@
+class RequestAbortError extends Error {
+  constructor(message = "Request cancelled") {
+    super(message);
+    this.name = "RequestAbortError";
+    this.code = "SURF_REQUEST_ABORTED";
+  }
+}
+
+function abortError(signal, fallback = "Request cancelled") {
+  if (signal?.reason instanceof Error && signal.reason.name !== "AbortError") return signal.reason;
+  return new RequestAbortError(fallback);
+}
+
+function throwIfAborted(signal, fallback) {
+  if (signal?.aborted) throw abortError(signal, fallback);
+}
+
+function raceAbort(promiseOrFactory, signal, fallback) {
+  if (!signal) return typeof promiseOrFactory === "function" ? promiseOrFactory() : promiseOrFactory;
+  throwIfAborted(signal, fallback);
+  const promise = typeof promiseOrFactory === "function" ? promiseOrFactory() : promiseOrFactory;
+  if (signal.aborted) return Promise.reject(abortError(signal, fallback));
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      reject(abortError(signal, fallback));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+function abortableDelay(ms, signal, fallback) {
+  throwIfAborted(signal, fallback);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      reject(abortError(signal, fallback));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+module.exports = { RequestAbortError, abortError, abortableDelay, raceAbort, throwIfAborted };

package/native/activity-journal.cjs

@@ -0,0 +1,55 @@
+const fs = require("fs");
+const path = require("path");
+const { appendPrivateJsonLine, atomicWriteFile, ensurePrivateDir, getPrivateStateRoot, readPrivateFile } = require("./private-state.cjs");
+const { commandMetadata, redactCommandArgs } = require("./workflow-definition.cjs");
+
+const MAX_JOURNAL_BYTES = 1024 * 1024;
+const MAX_JOURNAL_EVENTS = 500;
+
+function journalPath(root = getPrivateStateRoot()) {
+  return path.join(root, "activity-journal", "events.jsonl");
+}
+
+function compactJournal(filePath, root) {
+  const stat = fs.statSync(filePath);
+  if (stat.size <= MAX_JOURNAL_BYTES) return;
+  const lines = readPrivateFile(filePath, { root, encoding: "utf8" }).trim().split("\n").filter(Boolean).slice(-MAX_JOURNAL_EVENTS);
+  atomicWriteFile(filePath, `${lines.join("\n")}\n`, { root, encoding: "utf8" });
+}
+
+function appendActivity(event, { root = getPrivateStateRoot() } = {}) {
+  const filePath = journalPath(root);
+  ensurePrivateDir(path.dirname(filePath), root);
+  appendPrivateJsonLine(filePath, { version: 1, ...event }, { root });
+  compactJournal(filePath, root);
+}
+
+function journalCommand(command, args, options = {}) {
+  const metadata = commandMetadata(command);
+  if (!metadata.recordable) return;
+  appendActivity({
+    type: "tool.issued",
+    command: metadata.name,
+    argsRedacted: redactCommandArgs(command, args, options.includeInputValues === true),
+    effect: metadata.effect,
+    ...(options.tabId ? { tabId: options.tabId } : {}),
+    ...(options.origin ? { origin: options.origin } : {}),
+    startedAt: new Date().toISOString(),
+  }, options);
+}
+
+function sinceMilliseconds(value) {
+  if (!value) return 60 * 60 * 1000;
+  const match = String(value).match(/^(\d+)(m|h|d)$/);
+  if (!match) throw new Error("--since must be a duration such as 30m, 1h, or 2d");
+  return Number(match[1]) * { m: 60000, h: 3600000, d: 86400000 }[match[2]];
+}
+
+function readRecent({ since = "1h", root = getPrivateStateRoot() } = {}) {
+  const filePath = journalPath(root);
+  const content = readPrivateFile(filePath, { root, allowMissing: true, fallback: "", encoding: "utf8" });
+  const cutoff = Date.now() - sinceMilliseconds(since);
+  return content.split("\n").filter(Boolean).map((line) => JSON.parse(line)).filter((event) => Date.parse(event.startedAt || event.timestamp) >= cutoff);
+}
+
+module.exports = { appendActivity, journalCommand, journalPath, readRecent };

package/native/ai-queue.cjs

@@ -0,0 +1,64 @@
+const { abortError } = require("./abort.cjs");
+
+class BoundedAiQueue {
+  constructor({ maxQueued = 8, spacingMs = 2000, audit = () => {}, run = (handler) => handler() } = {}) {
+    this.maxQueued = maxQueued;
+    this.spacingMs = spacingMs;
+    this.audit = audit;
+    this.run = run;
+    this.items = [];
+    this.active = false;
+  }
+
+  enqueue(handler, request) {
+    return new Promise((resolve, reject) => {
+      if (request?.signal.aborted) {
+        reject(abortError(request.signal));
+        return;
+      }
+      if (this.items.length >= this.maxQueued) {
+        reject(new Error("AI request queue is full"));
+        return;
+      }
+      const item = { handler, request, resolve, reject, abortCleanup: null };
+      const onAbort = () => {
+        const index = this.items.indexOf(item);
+        if (index === -1) return;
+        this.items.splice(index, 1);
+        item.abortCleanup = null;
+        reject(abortError(request.signal));
+        this.audit({ event: "request", context: request.context, request, outcome: "queued-cancel" });
+      };
+      if (request?.signal) {
+        request.signal.addEventListener("abort", onAbort, { once: true });
+        item.abortCleanup = () => request.signal.removeEventListener("abort", onAbort);
+      }
+      this.items.push(item);
+      this.#process();
+    });
+  }
+
+  get queued() {
+    return this.items.length;
+  }
+
+  async #process() {
+    if (this.active || this.items.length === 0) return;
+    this.active = true;
+    const item = this.items.shift();
+    item.abortCleanup?.();
+    try {
+      if (item.request?.signal.aborted) throw abortError(item.request.signal);
+      const result = await this.run(item.handler, item.request);
+      if (item.request?.signal.aborted) throw abortError(item.request.signal);
+      item.resolve(result);
+    } catch (error) {
+      item.reject(error);
+    } finally {
+      this.active = false;
+      setTimeout(() => this.#process(), this.spacingMs);
+    }
+  }
+}
+
+module.exports = { BoundedAiQueue };

package/native/aistudio-build.cjs

@@ -1,4 +1,5 @@
 const fs = require("fs");
+const { raceAbort, throwIfAborted } = require("./abort.cjs");
 const { execFileSync } = require("child_process");
 const {
   delay,
@@ -483,26 +484,29 @@ async function build({
   cdpCommand,
   searchDownloads,
   log = () => {},
+  signal,
 }) {
+  throwIfAborted(signal);
+  const guardedSearchDownloads = (...args) => raceAbort(() => searchDownloads(...args), signal);
   const startedAt = Date.now();
   const timeoutMs = Number.isFinite(timeout) ? timeout : 600000;
   const requestedModel = normalizeModelString(model || "");
   const resolvedModel = requestedModel || DEFAULT_MODEL;
 
-  const cookieResult = await getCookies();
+  const cookieResult = await raceAbort(getCookies, signal);
   const cookies = cookieResult?.cookies || [];
   if (!hasRequiredCookies(cookies)) {
     throw new Error("Sign into Google in Chrome first.");
   }
 
-  const tabInfo = await createTab(AISTUDIO_APPS_URL);
+  const tabInfo = await raceAbort(() => createTab(AISTUDIO_APPS_URL), signal);
   const tabId = tabInfo?.tabId;
   if (!tabId) {
     throw new Error(`Failed to create AI Studio tab: ${JSON.stringify(tabInfo)}`);
   }
 
-  const cdp = (expression) => cdpEvaluate(tabId, expression);
-  const inputCdp = (method, params) => cdpCommand(tabId, method, params);
+  const cdp = (expression) => raceAbort(() => cdpEvaluate(tabId, expression), signal);
+  const inputCdp = (method, params) => raceAbort(() => cdpCommand(tabId, method, params), signal);
 
   let buildDuration = null;
   let zipPath = null;
@@ -510,7 +514,7 @@ async function build({
   let modelUsed = resolvedModel;
 
   try {
-    await waitForBuildPageReady(cdp, 30000);
+    await raceAbort(waitForBuildPageReady(cdp, 30000), signal);
 
     if (requestedModel) {
       const applied = await selectModelInAdvancedSettings(cdp, inputCdp, requestedModel, log);
@@ -518,20 +522,20 @@ async function build({
     }
 
     await typePromptAndBuild(cdp, inputCdp, prompt);
-    const completion = await waitForBuildCompletion(cdp, timeoutMs, log);
+    const completion = await raceAbort(waitForBuildCompletion(cdp, timeoutMs, log), signal);
     buildDuration = completion.buildDuration;
 
-    await activateCodeTab(cdp, inputCdp);
-    await waitForDownloadButton(cdp, 5000);
+    await raceAbort(activateCodeTab(cdp, inputCdp), signal);
+    await raceAbort(waitForDownloadButton(cdp, 5000), signal);
 
-    const beforeDownloads = await searchDownloads({
+    const beforeDownloads = await guardedSearchDownloads({
       limit: 1,
       orderBy: ["-startTime"],
     });
     const latestIdBefore = beforeDownloads?.[0]?.id || 0;
 
-    await clickDownloadButton(cdp);
-    zipPath = await waitForDownloadComplete(searchDownloads, latestIdBefore, 30000);
+    await raceAbort(clickDownloadButton(cdp), signal);
+    zipPath = await waitForDownloadComplete(guardedSearchDownloads, latestIdBefore, 30000);
 
     if (output) {
       const outputDir = String(output);
@@ -553,8 +557,12 @@ async function build({
       tookMs: Date.now() - startedAt,
     };
   } finally {
-    if (!keepOpen) {
-      await closeTab(tabId).catch(() => {});
+    if (!keepOpen || signal?.aborted) {
+      try {
+        await closeTab(tabId);
+      } catch (error) {
+        log(`Failed to close AI Studio Build tab ${tabId}: ${error?.message || error}`);
+      }
     }
   }
 }