surf-cli 2.16.1 → 2.18.0

package/README.md

@@ -146,6 +146,8 @@ surf remote list
 
 `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.
 
+For advanced local-only sharing, `surf install <extension-id> --socket-mode 660 --socket-group <group>` persists an opt-in group-owned socket. The default remains mode `600`; mode `660` gives every account in that group full Surf authority, so use a dedicated narrow group. Re-run `surf install` without these flags to clear persisted socket settings. Remote Surf credentials remain the revocable per-client alternative.
+
 Keep Tailscale policy restrictions as defense in depth. For example:
 
 ```json
@@ -188,7 +190,7 @@ surf --remote "$SURF_REMOTE" --remote-credential "$SURF_REMOTE_CREDENTIAL" \
 
 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.
+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`, `video`, `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
 
@@ -378,10 +380,14 @@ SURF_SESSION=research surf screenshot               # environment selector
 surf session.list --refresh                         # all bindings + queue state
 surf session.info research --refresh                # target and scheduler details
 surf session.close research                         # closes Surf-created target
+surf session.cleanup --idle-after 1h --dry-run      # preview forgotten sessions
+surf session.cleanup --idle-after 1h                 # remove idle bindings
 surf session.rebind research --tab-id 789            # adopt an existing tab
 surf session.reopen research                         # recreate from last URL
 ```
 
+`session.cleanup` is an explicit, one-shot cleanup operation; `--idle-after` is required. It inspects current bindings first, removes gone or stale records, and removes live inactive bindings older than the threshold. Only Surf-created targets are closed. Adopted targets remain open while their session binding is removed. Use `--dry-run` to report the exact bindings and target actions without changing the store or browser.
+
 Commands for the same session tab run FIFO. Commands for different session tabs can overlap. Browser-wide mutations—such as creating, moving, closing, or focusing tabs/windows and writing cookies—wait for active tab lanes to drain. Add `--no-wait` to return `tab_busy` or `browser_busy` immediately instead of queueing.
 
 Recovery errors print an exact command that can be copied directly:
@@ -440,6 +446,19 @@ surf record --rect 0,200,1440,800 --output /tmp/region.gif
 
 `record` defaults to 2000ms at 10fps and writes to `/tmp/surf-record-*.gif` when no output is provided. `--duration` is capped at 10000ms and `--fps` is capped at 30. `--trigger` supports `click:<selector>`, `scroll:up|down|left|right|top|bottom`, and `scroll:<selector>` to scroll a container to the bottom before capture. `--rect` crops the GIF using `x,y,width,height`. ImageMagick must be available as `magick` or `convert`.
 
+### Local Video Recording
+
+Capture a local tab as WebM/VP9 with ffmpeg:
+
+```bash
+surf video start ./demo.webm --fps 30
+surf video status
+surf video stop
+surf video restart ./take-2.webm --fps 60
+```
+
+`--fps` defaults to 30 and is capped at 60. Video recording is local-only and requires `ffmpeg` on `PATH`.
+
 ### Animation Audit
 
 Sample matching elements over time and return a bounded JSON timeline for agent inspection:
@@ -526,13 +545,15 @@ surf aistudio.build "game" --keep-open --timeout 600          # Keep tab open, 1
 
 #### Oracle
 
-Use `surf oracle` for a durable, local ChatGPT consult instead of a quick `surf chatgpt` one-shot. It persists jobs by conversation URL, supports repeatable file-context globs, and verifies requested model and reasoning effort before submission. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`. Use `--model gpt-5.6-sol --effort pro` for GPT-5.6 Sol with Pro effort.
+Use `surf oracle` for a durable, local ChatGPT consult instead of a quick `surf chatgpt` one-shot. It persists jobs by conversation URL, supports repeatable file-context globs, one direct local attachment with `--file`, and verifies requested model and reasoning effort before submission. Add `--github` when the consult needs the ChatGPT Chat tab and connected GitHub tool. ChatGPT model aliases include `gpt-6-astra`, `latest`, `gpt-5.6-sol`, and `gpt-5.5`; `latest` is an explicit floating choice, while `gpt-6-astra` must read back as model 6 before submission. Accepted efforts are `instant`, `medium`, `high`, `xhigh`/`extra-high`, and `pro`. Use `--model gpt-6-astra --effort pro` for GPT-6 Astra with Pro effort.
+
+ChatGPT can hide the model version at lower effort settings. Use `--model latest` if you want floating model selection there; an explicit `gpt-6-astra` request fails closed when the UI cannot verify model 6.
 
 ```bash
-surf oracle ask "review this change" --files "src/**/*.ts" --model gpt-5.5 --effort pro --detach --json
+surf oracle ask "review this change" --files "src/**/*.ts" --file ./design.md --model gpt-5.5 --effort pro --github --detach --json
 surf oracle status <job-id> --json
 surf oracle result <job-id> --wait --json
-surf oracle follow <job-id> "challenge that recommendation" --detach --json
+surf oracle follow <job-id> "challenge that recommendation" --file ./follow-up.md --github --detach --json
 ```
 
 Only one oracle job can be in flight. Sensitive filename patterns and gitignored context are blocked unless `--allow-sensitive` is explicit.
@@ -807,6 +828,8 @@ SURF_REMOTE               # Remote Surf endpoint as host:port (overrides SURF_SO
 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_SOCKET_MODE          # Advanced POSIX local socket mode: 600 (default) or 660
+SURF_SOCKET_GROUP         # Group name or numeric gid required with mode 660
 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
@@ -820,6 +843,7 @@ SURF_EXTENSION_PATH       # Path to extension dist/ directory
 - `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_SOCKET_MODE` / `SURF_SOCKET_GROUP`: Advanced POSIX native-host settings. Use `surf install ... --socket-mode 660 --socket-group <group>` to persist group access; mode `660` grants full Surf authority to every member of that group.
 - `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
 
@@ -996,9 +1020,9 @@ pi -e /path/to/surf-cli/pi-extension/surf.ts
 
 It registers `surf_read`, `surf_screenshot`, `surf_click`, `surf_type`, `surf_tool`, and the `surf_oracle_*` tools. Browser calls use Surf's native-host socket, not shell commands. If `pi-subagents/background-work` is installed, the extension also reports active oracle jobs started by that Pi session. Pi still loads the browser tools when pi-subagents is not installed.
 
-The extension also registers a `surf-oracle` external-job provider when a Pi runtime exposes that provider bridge. The provider implements pi-subagents' external-job contract: `start`, `status`, `result`, and `reattach` operations that return `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the durable conversation URL, the captured result text as `output`, and failure code and message when present. It reads `options.model` and `options.effort` for starts, so a Pi profile can request `model: gpt-5.6-sol` plus `effort: pro` and reach ChatGPT GPT-5.6 Sol with Pro effort through Surf. Capacity stays fail-closed: Surf returns the blocking job id instead of silently queueing a second ChatGPT job.
+The extension also registers a `surf-oracle` external-job provider when a Pi runtime exposes that provider bridge. The provider implements pi-subagents' external-job contract: `start`, `status`, `result`, and `reattach` operations that return `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the durable conversation URL, the captured result text as `output`, and failure code and message when present. It reads `options.model`, `options.effort`, `options.file`, and `options.github` for starts and follow-ups, so a Pi profile can request `model: gpt-6-astra` plus `effort: pro` and reach ChatGPT GPT-6 Astra with Pro effort through Surf, while `github: true` requires Chat mode and the connected GitHub tool. Capacity stays fail-closed: Surf returns the blocking job id instead of silently queueing a second ChatGPT job.
 
-When Surf is installed as a Pi package, it also exposes an optional `gpt-pro` package agent for `pi-subagents`. That profile uses `runner.type: external-job`, provider `surf-oracle`, `options.model: gpt-5.6-sol`, and `options.effort: pro`. Surf remains useful without Pi or `pi-subagents`; the package agent only wires Surf's browser-backed model alias into Pi's agent picker.
+When Surf is installed as a Pi package, it also exposes an optional `gpt-pro` package agent for `pi-subagents`. That profile uses `runner.type: external-job`, provider `surf-oracle`, `options.model: gpt-6-astra`, and `options.effort: pro`. Surf remains useful without Pi or `pi-subagents`; the package agent only wires Surf's browser-backed model alias into Pi's agent picker.
 
 Shell-based agents should select a unique session with `SURF_SESSION` and call `surf session.ensure` before their first browser command. The optional Pi extension still uses its existing socket-tool interface; callers that coordinate several Pi workers should pass explicit tab targets until session selection is exposed by that integration.
 

package/agents/gpt-pro.md

@@ -1,11 +1,11 @@
 ---
 name: gpt-pro
-description: Surf GPT Pro advisor through ChatGPT GPT-5.6 Sol Pro web mode
+description: Surf GPT Pro advisor through ChatGPT GPT-6 Astra Pro web mode
 runner:
   type: external-job
   provider: surf-oracle
   options:
-    model: gpt-5.6-sol
+    model: gpt-6-astra
     effort: pro
 async: true
 systemPromptMode: replace

package/native/browser-session-store.cjs

@@ -9,6 +9,24 @@ const { surfError } = require("./surf-error.cjs");
 
 const STORE_VERSION = 1;
 const SESSION_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SESSION_DURATION_PATTERN = /^(\d+(?:\.\d+)?)(s|m|h|d)?$/i;
+
+function parseDurationMs(value) {
+  if (typeof value === "boolean" || value === undefined || value === null) {
+    throw new Error("--idle-after requires a positive duration such as 30s, 5m, 1h, or 1d");
+  }
+  const match = String(value).trim().match(SESSION_DURATION_PATTERN);
+  if (!match) {
+    throw new Error("--idle-after must be a duration such as 30s, 5m, 1h, or 1d (plain seconds are also accepted)");
+  }
+  const amount = Number(match[1]);
+  const multiplier = { s: 1000, m: 60000, h: 3600000, d: 86400000 }[(match[2] || "s").toLowerCase()];
+  const milliseconds = amount * multiplier;
+  if (!Number.isFinite(milliseconds) || milliseconds <= 0) {
+    throw new Error("--idle-after must be a positive duration");
+  }
+  return Math.max(1, Math.round(milliseconds));
+}
 
 function normalizeName(name) {
   return String(name || "").toLowerCase();
@@ -114,6 +132,7 @@ class BrowserSessionStore {
       browserEpoch: identity.browserEpoch,
       createdAt: timestamp,
       updatedAt: timestamp,
+      lastAccessedAt: values.lastAccessedAt || timestamp,
       lastValidatedAt: values.lastValidatedAt || timestamp,
     };
     bucket.sessions[key] = record;
@@ -137,6 +156,7 @@ class BrowserSessionStore {
       browserEpoch: identity.browserEpoch,
       createdAt: existing?.createdAt || timestamp,
       updatedAt: timestamp,
+      lastAccessedAt: values.lastAccessedAt || timestamp,
       lastValidatedAt: values.lastValidatedAt || timestamp,
     };
     delete record.invalidReason;
@@ -149,7 +169,13 @@ class BrowserSessionStore {
   update(identity, name, patch) {
     const existing = this.get(identity, name);
     if (!existing) throw surfError("session_unknown", `unknown session: ${name}`, { session: name });
-    return this.replace(identity, name, { ...existing, ...patch, updatedAt: this.now() });
+    const timestamp = this.now();
+    return this.replace(identity, name, {
+      ...existing,
+      ...patch,
+      updatedAt: timestamp,
+      lastAccessedAt: patch?.lastAccessedAt || timestamp,
+    });
   }
 
   remove(identity, name) {
@@ -212,7 +238,8 @@ class BrowserSessionStore {
     let changed = false;
     for (const record of Object.values(bucket.sessions || {})) {
       if (record.tabId !== tabId) continue;
-      Object.assign(record, patch, { updatedAt: this.now() });
+      const timestamp = this.now();
+      Object.assign(record, patch, { updatedAt: timestamp, lastAccessedAt: patch?.lastAccessedAt || timestamp });
       changed = true;
     }
     if (changed) this.save(state);
@@ -266,6 +293,7 @@ module.exports = {
   BrowserSessionStore,
   SESSION_NAME_PATTERN,
   STORE_VERSION,
+  parseDurationMs,
   normalizeName,
   validateSessionName,
 };

package/native/chatgpt-client-selection.cjs

@@ -1,11 +1,19 @@
-const CHATGPT_EFFORT_CHOICES = ["light", "standard", "extended", "heavy", "pro"];
+const CHATGPT_EFFORT_CHOICES = ["instant", "medium", "high", "xhigh", "pro"];
+const CHATGPT_EFFORT_VALUE = new Map([
+  ["instant", 0],
+  ["medium", 1],
+  ["high", 2],
+  ["xhigh", 3],
+  ["pro", 4],
+]);
+
 const CHATGPT_MODEL_ALIASES = new Map([
-  ["instant", "instant"],
-  ["gpt53", "instant"],
-  ["thinking", "thinking"],
-  ["gpt54thinking", "thinking"],
-  ["pro", "pro"],
-  ["gpt54pro", "pro"],
+  ["latest", "latest"],
+  ["gpt6", "gpt6astra"],
+  ["chatgpt6", "gpt6astra"],
+  ["gpt6astra", "gpt6astra"],
+  ["chatgpt6astra", "gpt6astra"],
+  ["6", "gpt6astra"],
   ["55", "gpt55"],
   ["gpt55", "gpt55"],
   ["chatgpt55", "gpt55"],
@@ -14,6 +22,15 @@ const CHATGPT_MODEL_ALIASES = new Map([
   ["chatgpt56sol", "gpt56sol"],
 ]);
 
+const CHATGPT_EFFORT_ALIASES = new Map([
+  ["instant", "instant"],
+  ["medium", "medium"],
+  ["high", "high"],
+  ["xhigh", "xhigh"],
+  ["extrahigh", "xhigh"],
+  ["pro", "pro"],
+]);
+
 function normalizeChatGPTModelChoice(desiredModel) {
   const normalized = String(desiredModel || "")
     .toLowerCase()
@@ -23,43 +40,68 @@ function normalizeChatGPTModelChoice(desiredModel) {
 }
 
 function normalizeChatGPTEffortChoice(desiredEffort) {
-  const normalized = String(desiredEffort || "").toLowerCase().trim();
-  return CHATGPT_EFFORT_CHOICES.includes(normalized) ? normalized : null;
+  const normalized = String(desiredEffort || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+  return CHATGPT_EFFORT_ALIASES.get(normalized) || null;
 }
 
 function normalizedWords(value) {
   return String(value || "")
     .toLowerCase()
-    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/[^a-z0-9.]+/g, " ")
     .trim()
     .split(/\s+/)
     .filter(Boolean);
 }
 
+function normalizedText(value) {
+  return normalizedWords(value).join(" ");
+}
+
+function modelKeyFromValue(value) {
+  const text = normalizedText(value);
+  if (!text) return null;
+  if (/^latest$/.test(text)) return "latest";
+  if (/\b5\.6\b/.test(text) && /\bsol\b/.test(text)) return "gpt56sol";
+  if (/\b5\.5\b/.test(text)) return "gpt55";
+  if (/\bgpt\s*6\b/.test(text) || /\bchatgpt\s*6\b/.test(text) || /^6(?:\s|$)/.test(text)) {
+    return "gpt6astra";
+  }
+  return null;
+}
+
 function modelCandidateMatches(item, targetModel) {
-  const values = [item?.label, item?.testId?.replace(/^model-switcher-/, "")].filter(Boolean);
-  return values.some((value) => {
-    const normalizedValue = normalizeChatGPTModelChoice(value);
-    if (normalizedValue === targetModel) return true;
-    if (targetModel.startsWith("gpt") && normalizedValue.includes(targetModel)) return true;
-    const variants = ["instant", "thinking", "pro"].filter((variant) =>
-      normalizedWords(value).includes(variant),
-    );
-    return variants.length === 1 && variants[0] === targetModel;
-  });
+  if (item?.modelKey === targetModel) return true;
+  const values = [item?.label, item?.displayLabel, item?.testId?.replace(/^model-switcher-/, "")]
+    .filter(Boolean);
+  return values.some((value) => modelKeyFromValue(value) === targetModel);
 }
 
-function effortCandidateMatches(item, targetEffort) {
-  const labelVariants = new Set(
-    normalizedWords(item?.label).filter((word) => CHATGPT_EFFORT_CHOICES.includes(word)),
-  );
-  if (labelVariants.size > 0) {
-    return labelVariants.size === 1 && labelVariants.has(targetEffort);
+function modelSelectableCandidateMatches(item, targetModel) {
+  if (modelCandidateMatches(item, targetModel)) return true;
+  if (targetModel === "gpt6astra") {
+    return [item?.label, item?.displayLabel].filter(Boolean).some((value) => modelKeyFromValue(value) === "latest");
   }
-  const testIdVariants = new Set(
-    normalizedWords(item?.testId).filter((word) => CHATGPT_EFFORT_CHOICES.includes(word)),
-  );
-  return testIdVariants.size === 1 && testIdVariants.has(targetEffort);
+  return false;
+}
+
+function effortKeyFromValue(value) {
+  const text = normalizedText(value);
+  if (!text) return null;
+  if (/\bextra\s+high\b/.test(text) || /\bxhigh\b/.test(text)) return "xhigh";
+  if (/\binstant\b/.test(text)) return "instant";
+  if (/\bmedium\b/.test(text)) return "medium";
+  if (/\bhigh\b/.test(text)) return "high";
+  if (/\bpro\b/.test(text)) return "pro";
+  return null;
+}
+
+function effortCandidateMatches(item, targetEffort) {
+  const labelKey = item?.effortKey || effortKeyFromValue(item?.label || item?.displayLabel);
+  if (!labelKey || labelKey !== targetEffort) return false;
+  if (item?.value === undefined || item?.value === null) return true;
+  return Number(item.value) === CHATGPT_EFFORT_VALUE.get(targetEffort);
 }
 
 function uniqueMatch(items, matches) {
@@ -75,7 +117,7 @@ function resolveChatGPTModelMenuOption(items, desiredModel) {
     items,
     (item) =>
       ["button", "menuitem", "menuitemradio", "radio"].includes(item?.role) &&
-      modelCandidateMatches(item, targetModel),
+      modelSelectableCandidateMatches(item, targetModel),
   );
 }
 
@@ -85,7 +127,8 @@ function verifyChatGPTModelSelection(items, desiredModel) {
   return uniqueMatch(
     items,
     (item) =>
-      (typeof item?.label === "string" || typeof item?.testId === "string") &&
+      (!["menuitemradio", "radio"].includes(item?.role) || item.selected === true) &&
+      (typeof item?.label === "string" || typeof item?.displayLabel === "string" || typeof item?.testId === "string") &&
       modelCandidateMatches(item, targetModel),
   );
 }
@@ -96,7 +139,7 @@ function resolveChatGPTEffortMenuOption(items, desiredEffort) {
   return uniqueMatch(
     items,
     (item) =>
-      ["button", "menuitem", "menuitemradio"].includes(item?.role) &&
+      ["slider", "button", "menuitem", "menuitemradio"].includes(item?.role) &&
       effortCandidateMatches(item, targetEffort),
   );
 }
@@ -107,7 +150,7 @@ function verifyChatGPTEffortSelection(items, desiredEffort) {
   return uniqueMatch(
     items,
     (item) =>
-      (typeof item?.label === "string" || typeof item?.testId === "string") &&
+      (typeof item?.label === "string" || typeof item?.displayLabel === "string" || typeof item?.testId === "string") &&
       effortCandidateMatches(item, targetEffort),
   );
 }
@@ -115,7 +158,7 @@ function verifyChatGPTEffortSelection(items, desiredEffort) {
 function boundedOptionLabels(items) {
   if (!Array.isArray(items)) return [];
   return items
-    .map((item) => String(item?.label || "").replace(/\s+/g, " ").trim().slice(0, 80))
+    .map((item) => String(item?.displayLabel || item?.label || "").replace(/\s+/g, " ").trim().slice(0, 80))
     .filter(Boolean)
     .filter((label, index, labels) => labels.indexOf(label) === index)
     .slice(0, 10);
@@ -123,6 +166,7 @@ function boundedOptionLabels(items) {
 
 module.exports = {
   CHATGPT_EFFORT_CHOICES,
+  CHATGPT_EFFORT_VALUE,
   boundedOptionLabels,
   normalizeChatGPTEffortChoice,
   normalizeChatGPTModelChoice,