surf-cli 2.14.0 → 2.15.1

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.14.0",
+  "version": "2.15.1",
   "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"
@@ -69,11 +70,12 @@
     "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "^4.1.9",
     "@vitest/ui": "^4.1.9",
-    "puppeteer": "25.5.0",
+    "pi-subagents": "^0.52.0",
+    "puppeteer": "25.6.0",
+    "typebox": "^1.3.11",
     "typescript": "^7.0.2",
     "vite": "^8.1.4",
-    "vitest": "^4.1.9",
-    "typebox": "^1.3.11"
+    "vitest": "^4.1.9"
   },
   "pi": {
     "extensions": [
@@ -81,7 +83,12 @@
     ],
     "skills": [
       "./skills"
-    ]
+    ],
+    "subagents": {
+      "agents": [
+        "./agents"
+      ]
+    }
   },
   "peerDependencies": {
     "typebox": "*"

package/pi-extension/surf.ts

@@ -1,5 +1,4 @@
 import { createRequire } from "node:module";
-import { createHash } from "node:crypto";
 import { Type } from "typebox";
 
 const require = createRequire(import.meta.url);
@@ -73,29 +72,31 @@ type BackgroundWorkRegistry = {
 };
 
 type OracleExternalJob = {
-  provider: "surf-oracle";
   id: string;
   state: string;
   conversationUrl: string | null;
-  requestedModel: string | null;
-  verifiedModel: string | null;
-  requestedEffort: string | null;
-  verifiedEffort: string | null;
-  promptDigest: string | null;
   resultText?: string;
-  resultArtifact?: { kind: "inline-text"; bytes: number };
   failure?: { code: string; message: string };
 };
 
+type PiExternalJobState = "queued" | "running" | "completed" | "failed";
+
+type PiExternalJobHandle = {
+  providerJobId: string;
+  state: PiExternalJobState;
+  conversationUrl?: string;
+  failureCode?: string;
+  failureMessage?: string;
+};
+
+type PiExternalJobResult = PiExternalJobHandle & { output?: string };
+
 type OracleExternalJobProvider = {
   name: "surf-oracle";
-  kind: "external-job";
-  wakeChannels: string[];
-  start(input: Record<string, unknown>): Promise<OracleExternalJob>;
-  status(id: string): Promise<OracleExternalJob>;
-  result(id: string, input?: Record<string, unknown>): Promise<OracleExternalJob>;
-  reattach(id: string, input?: Record<string, unknown>): Promise<OracleExternalJob>;
-  follow(id: string, message: string, input?: Record<string, unknown>): Promise<OracleExternalJob>;
+  start(input: Record<string, unknown>): Promise<PiExternalJobHandle>;
+  status(id: string): Promise<PiExternalJobHandle>;
+  result(id: string): Promise<PiExternalJobResult>;
+  reattach(id: string): Promise<PiExternalJobHandle>;
 };
 
 type RegisterExternalJobProvider = (provider: OracleExternalJobProvider) => () => void;
@@ -251,15 +252,11 @@ export async function resolveExternalJobProviderRegister(
       return module.registerExternalJobProvider as RegisterExternalJobProvider;
     }
   } catch {
-    // The provider bridge is optional until pi-subagents ships this consumer API.
+    // The Pi bridge is optional. Surf also runs in other coding-agent harnesses and as a direct CLI.
   }
   return registerGlobalExternalJobProvider;
 }
 
-function digestPrompt(prompt: string) {
-  return `sha256:${createHash("sha256").update(prompt).digest("hex")}`;
-}
-
 function asOracleJob(value: unknown): OracleJob {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Surf oracle response did not include job metadata");
   const job = value as Partial<OracleJob>;
@@ -272,22 +269,53 @@ function oracleExternalJob(job: OracleJob): OracleExternalJob {
   const failure = job.error
     ? { code: job.error.code || "failed", message: job.error.message || "Surf oracle job failed" }
     : undefined;
-  const requestedModel = Object.hasOwn(job, "modelRequested") ? job.modelRequested ?? null : job.model ?? null;
   return {
-    provider: "surf-oracle",
     id: job.id,
     state: job.state,
     conversationUrl: job.conversationUrl ?? null,
-    requestedModel,
-    verifiedModel: job.modelVerified ?? null,
-    requestedEffort: job.effortRequested ?? null,
-    verifiedEffort: job.effortVerified ?? null,
-    promptDigest: job.promptDigest ?? null,
-    ...(resultText === undefined ? {} : { resultText, resultArtifact: { kind: "inline-text", bytes: Buffer.byteLength(resultText, "utf8") } }),
+    ...(resultText === undefined ? {} : { resultText }),
     ...(failure ? { failure } : {}),
   };
 }
 
+// pi-subagents' external-job contract rejects unknown fields, null values,
+// untrimmed strings, and non-contract states, so map oracle payloads at this
+// boundary instead of passing them through.
+const PI_STATE_BY_ORACLE_STATE: Record<string, PiExternalJobState> = {
+  created: "queued",
+  dispatched: "running",
+  awaiting: "running",
+  captured: "completed",
+  failed: "failed",
+};
+const PI_MAX_FAILURE_CODE_CHARS = 128;
+const PI_MAX_FAILURE_MESSAGE_CHARS = 4_096;
+const PI_MAX_OUTPUT_CHARS = 1024 * 1024;
+
+function piBounded(value: string, maxChars: number): string {
+  return value.slice(0, maxChars).trim();
+}
+
+export function piExternalJobHandle(job: OracleExternalJob): PiExternalJobHandle {
+  const state = PI_STATE_BY_ORACLE_STATE[job.state];
+  if (!state) throw new Error(`Surf oracle job ${job.id} reported unknown state '${job.state}'`);
+  const conversationUrl = job.conversationUrl ?? undefined;
+  const failureCode = job.failure ? piBounded(job.failure.code, PI_MAX_FAILURE_CODE_CHARS) : "";
+  const failureMessage = job.failure ? piBounded(job.failure.message, PI_MAX_FAILURE_MESSAGE_CHARS) : "";
+  return {
+    providerJobId: job.id,
+    state,
+    ...(conversationUrl ? { conversationUrl } : {}),
+    ...(failureCode ? { failureCode } : {}),
+    ...(failureMessage ? { failureMessage } : {}),
+  };
+}
+
+export function piExternalJobResult(job: OracleExternalJob): PiExternalJobResult {
+  const output = job.resultText === undefined ? "" : piBounded(job.resultText, PI_MAX_OUTPUT_CHARS);
+  return { ...piExternalJobHandle(job), ...(output ? { output } : {}) };
+}
+
 async function requestOracleJob(request: typeof requestSurf, tool: string, args: Record<string, unknown>) {
   const result = await request(tool, args);
   if (result.isError) {
@@ -298,6 +326,7 @@ async function requestOracleJob(request: typeof requestSurf, tool: string, args:
     const error = new Error(message);
     if (typeof details?.code === "string") Object.assign(error, { code: details.code });
     if (typeof details?.jobId === "string") Object.assign(error, { jobId: details.jobId });
+    if (details?.code === "capacity" && typeof details?.jobId === "string") Object.assign(error, { blockingJobId: details.jobId });
     throw error;
   }
   return oracleExternalJob(asOracleJob(result.details));
@@ -308,6 +337,16 @@ function emitFailedOracleJob(error: unknown, emitTerminal: EmitOracleJob) {
   emitTerminal({ id: error.jobId, state: "failed" });
 }
 
+function oracleOption(input: Record<string, unknown>, key: "model" | "effort"): string | undefined {
+  const options = input.options;
+  if (options && typeof options === "object" && !Array.isArray(options)) {
+    const value = (options as Record<string, unknown>)[key];
+    if (typeof value === "string") return value;
+  }
+  const direct = input[key];
+  return typeof direct === "string" ? direct : undefined;
+}
+
 export function createOracleExternalJobProvider(
   sessionId: string,
   jobIds: Set<string>,
@@ -320,56 +359,45 @@ export function createOracleExternalJobProvider(
 ): OracleExternalJobProvider {
   return {
     name: "surf-oracle",
-    kind: "external-job",
-    wakeChannels: [ORACLE_FINISHED_CHANNEL],
     async start(input) {
       const prompt = typeof input.prompt === "string" ? input.prompt : "";
       if (!prompt.trim()) throw new Error("prompt required");
+      const model = oracleOption(input, "model");
+      const effort = oracleOption(input, "effort");
       const job = await requestOracleJob(request, "oracle.ask", {
         prompt,
-        ...(typeof input.model === "string" ? { model: input.model } : {}),
-        ...(typeof input.effort === "string" ? { effort: input.effort } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(effort !== undefined ? { effort } : {}),
       });
       rememberJob(job.id);
-      return { ...job, promptDigest: job.promptDigest ?? digestPrompt(prompt) };
+      return piExternalJobHandle(job);
     },
-    status(id) {
-      return requestOracleJob(request, "oracle.status", { id });
+    async status(id) {
+      return piExternalJobHandle(await requestOracleJob(request, "oracle.status", { id }));
     },
-    result(id, input = {}) {
-      return requestOracleJob(request, "oracle.result", { id, ...(typeof input.timeout === "number" ? { timeout: input.timeout } : {}) })
+    result(id) {
+      return requestOracleJob(request, "oracle.result", { id })
         .then((job) => {
           emitTerminal({ id: job.id, state: job.state });
-          return job;
+          return piExternalJobResult(job);
         })
         .catch((error) => {
           emitFailedOracleJob(error, emitTerminal);
           throw error;
         });
     },
-    reattach(id, input = {}) {
-      return requestOracleJob(request, "oracle.result", { id, ...(typeof input.timeout === "number" ? { timeout: input.timeout } : {}) })
+    reattach(id) {
+      return requestOracleJob(request, "oracle.result", { id })
         .then((job) => {
           rememberJob(job.id);
           emitTerminal({ id: job.id, state: job.state });
-          return job;
+          return piExternalJobHandle(job);
         })
         .catch((error) => {
           emitFailedOracleJob(error, emitTerminal);
           throw error;
         });
     },
-    async follow(id, message, input = {}) {
-      if (!message.trim()) throw new Error("message required");
-      const job = await requestOracleJob(request, "oracle.ask", {
-        follow: id,
-        prompt: message,
-        ...(typeof input.model === "string" ? { model: input.model } : {}),
-        ...(typeof input.effort === "string" ? { effort: input.effort } : {}),
-      });
-      rememberJob(job.id);
-      return { ...job, promptDigest: job.promptDigest ?? digestPrompt(message) };
-    },
   };
 }
 

package/skills/surf/SKILL.md

@@ -40,13 +40,24 @@ Remote paths are client-local by default. `local:./file` is explicit client-loca
 ## CLI Quick Reference
 
 ```bash
-surf --help                    # Full help
+surf --help                    # Basic help
 surf <group>                   # Group help (tab, scroll, page, wait, dialog, emulate, form, perf, ai)
 surf --help-full               # All commands
 surf --find <term>             # Search tools
 surf --help-topic <topic>      # Topic guide (refs, semantic, frames, devices, windows)
 ```
 
+## First Command for Independent Agents
+
+Before the first browser command in each independent agent shell, choose a unique valid session name and ensure its target exists:
+
+```bash
+export SURF_SESSION="$(basename "$PWD" | sed 's/[^A-Za-z0-9._-]/-/g')"
+surf session.ensure "$SURF_SESSION" about:blank
+```
+
+`session.ensure` is idempotent. It creates a missing session, reuses a live binding, and reopens a stale or closed tab. Keep `SURF_SESSION` set for every later tab-scoped command in that shell. Use a distinct worktree/directory name per agent; when agents share one directory, append a stable agent identifier. Use `surf session.info "$SURF_SESSION"` to inspect the target and queue state.
+
 ## Core Workflow
 
 ```bash
@@ -103,7 +114,9 @@ surf oracle result <job-id> --wait --json
 
 Treat Pro quota as scarce. Oracle never selects Pro implicitly; request it with `--model pro` or `--effort pro`. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`. Accepted `--effort` values are `light`, `standard`, `extended`, `heavy`, and `pro`. Requested model and effort selections are read back before submission, and an unverifiable selection fails with `model_verification_failed` instead of silently continuing. Capacity is one non-terminal oracle job. A `capacity` error includes the in-flight job ID; poll that job or wait for it to finish rather than submitting the same consult again.
 
-When loaded as a Pi extension, Surf also registers a `surf-oracle` external-job provider when the runtime exposes that bridge. The provider maps `start`, `status`, `result`, `reattach`, and `follow` to durable Surf Oracle jobs. It returns the conversation URL, requested and verified model and effort, prompt digest, result text, and failure details. `reattach` only harvests an existing job by ID; it never submits the prompt again.
+When loaded as a Pi extension, Surf also registers a `surf-oracle` external-job provider when the runtime exposes that bridge. The provider maps `start`, `status`, `result`, and `reattach` to durable Surf Oracle jobs and returns pi-subagents' external-job contract shape: `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the conversation URL, the captured result text as `output`, and failure code and message. It honors `options.model` and `options.effort` for starts, so `model: pro` selects ChatGPT GPT-5.6 Sol Pro web mode through the browser. `reattach` only harvests an existing job by ID; it never submits the prompt again.
+
+When Surf is installed as a Pi package, it exposes an optional `gpt-pro` package agent for `pi-subagents`. That profile uses `runner.type: external-job`, provider `surf-oracle`, and `options.model: pro`. Surf remains useful without Pi or `pi-subagents`.
 
 Context comes from repeatable `--files` globs. Surf fails closed when a glob matches nothing or a matched file is unreadable, binary, or invalid UTF-8. It also blocks gitignored files and basenames matching `.env*`, `*.pem`, `*.key`, `id_rsa*`, `id_ed25519*`, `*.p12`, `*.pfx`, `credentials*`, or `secrets*`. Use `--allow-sensitive` only after intentionally reviewing those files; it overrides the block rather than redacting content. Context up to 60,000 evidence characters is inserted inline, while larger context becomes one private text attachment. The assembly manifest records each path, byte count, SHA-256, inline or bundle disposition, and deny-list outcome.
 
@@ -247,20 +260,27 @@ surf window.resize --id 123 --width 1920 --height 1080
 surf window.resize --id 123 --state maximized # States: normal, minimized, maximized, fullscreen
 ```
 
-**Multi-agent isolation:**
+**Concurrent agent sessions:**
+
 ```bash
-# Create a separate window for one agent and keep using its ID
-surf window.new "https://example.com"
-surf --window-id 123 tab.list
-surf --window-id 123 go "https://other.com"
+# Required first command rule for each independent agent shell
+export SURF_SESSION="$(basename "$PWD" | sed 's/[^A-Za-z0-9._-]/-/g')"
+surf session.ensure "$SURF_SESSION" about:blank
+
+# Explicit form when an environment variable is inconvenient
+surf --session research go "https://example.com"
+surf --session research read
 
-# Pin work to a specific tab, or name it for easier handoff
-surf read --tab-id 456
-surf tab.name agent-a --tab-id 456
-surf tab.switch agent-a
+# Inspect bindings and scheduler state
+surf session.list --refresh
+surf session.info research --refresh
 ```
 
-Use `window.new`, `--window-id`, `--tab-id`, and named tabs to keep parallel agents on separate targets. Surf serializes non-streaming browser CLI requests per socket with a file-based lock, so agents sharing one native host wait instead of interleaving commands. Use `--no-lock` only for intentional bypasses. For hard isolation, run separate browser/profile instances with separate native hosts and `SURF_SOCKET` values; each socket gets its own lock. Surf does not yet have `session.new`, session IDs, or independent per-agent CDP sessions.
+Each session owns one explicit tab and defaults to a separate unfocused window. Commands for the same tab are FIFO; different session tabs may run concurrently. Browser-wide writers wait for tab lanes to drain. `--no-wait` returns `tab_busy` or `browser_busy` immediately. On `tab_gone` or `session_epoch_stale`, run the exact command printed after `Recovery:`—normally `surf session.reopen <name>`.
+
+Browser-login provider commands (`chatgpt`, `gemini`, `perplexity`, `grok`, `kimi`, `aistudio`, and `oracle ask`) take exclusive browser access and print a warning before dispatch. Do not assume Surf is hung while that warning is visible; inspect `surf session.info <name>` from another shell to see the active writer.
+
+Sessions share cookies, authentication, same-origin storage, downloads, history, bookmarks, and other Chrome-profile state. Use separate browser/profile instances and `SURF_SOCKET` values only when hard isolation is required. Explicit `--tab-id`, `--window-id`, and named tabs remain available for one-off targeting.
 
 ## Input Methods
 
@@ -439,14 +459,16 @@ surf upload --ref e5 --files "/path/file1.txt,/path/file2.txt"
 
 ```bash
 surf frame.list                # List frames with IDs
-surf frame.switch "FRAME_ID"   # Switch to iframe context
+surf frame.switch --selector "#payment-iframe"
+surf frame.switch --name "checkout"
+surf frame.switch --index 0    # First iframe
 surf frame.main                # Return to main frame
-surf frame.js --id "FRAME_ID" --code "return document.title"
+surf frame.js "return document.title" --id "FRAME_ID"
 
 # After frame.switch, subsequent commands target that frame:
-surf frame.switch "iframe-1"
+surf frame.switch --selector "#payment-iframe"
 surf page.read                 # Reads iframe content
-surf click e5                  # Clicks in iframe
+surf click --selector "#pay"   # Clicks in iframe
 surf frame.main                # Back to main page
 ```
 
@@ -550,6 +572,9 @@ surf do 'go "https://example.com" | click e5 | screenshot'
 # Multi-step login flow
 surf do 'go "https://example.com/login" | type "user@example.com" --selector "#email" | type "pass" --selector "#password" | click --selector "button[type=submit]"'
 
+# JSON action batch. Uses SURF_SESSION when it is set.
+surf batch --actions '[{"type":"frame.switch","index":0},{"type":"click","selector":"#pay"}]'
+
 # Validate without executing
 surf do 'go "url" | click e5' --dry-run
 ```
@@ -683,9 +708,11 @@ surf wait.element ".missing" --auto-capture --timeout 2000
 ## Common Options
 
 ```bash
---tab-id <id>         # Target specific tab
---window-id <id>      # Target specific window
---json                # Raw JSON output  
+--session <name>      # Target a durable named session (or set SURF_SESSION)
+--tab-id <id>         # Target a specific tab
+--window-id <id>      # Target a specific window
+--no-wait             # Return tab_busy/browser_busy instead of queueing
+--json                # Raw JSON including target metadata
 --auto-capture        # Screenshot + console on error
 --timeout <ms>        # Override default timeout
 ```
@@ -703,12 +730,12 @@ surf wait.element ".missing" --auto-capture --timeout 2000
 9. **AI Studio for unrestricted Gemini** - `surf aistudio` gives less filtered responses than `surf gemini` for the same models
 10. **Use `surf do` for multi-step tasks** - Reduces token overhead and improves reliability
 11. **Dry-run workflows first** - `surf do '...' --dry-run` validates without executing
-12. **Window isolation** - Use `window.new` + `--window-id` or `--tab-id` to keep agent work separate from your browsing
-13. **Request lock** - Non-streaming browser CLI requests serialize per socket; use `--no-lock` only when you intentionally want to bypass it
+12. **Session first** - Set a unique `SURF_SESSION` and run `session.ensure` before the first browser command in every independent agent shell
+13. **Queue diagnostics** - `session.info` distinguishes the session's own tab queue, other active tabs, and browser-wide writers; use `--no-wait` for immediate busy errors
 14. **Native host diagnostics** - If commands fail with socket/native-host errors, run `surf doctor` or `surf doctor --browser all` before guessing at reinstall steps
 15. **HTML export** - Use `surf page.html > artifact.html` to save Claude artifacts or any rendered page as static HTML
 16. **Animation capture** - Use `surf record --duration 2000 --fps 10 --output /tmp/anim.gif` when the agent needs to see motion; use `animate-audit` for numeric timelines and `perf-audit` for jank/layout-shift snapshots
-17. **Hard isolation** - Use separate browser/profile instances plus separate `SURF_SOCKET` values when agents must not share a host or target
+17. **Hard isolation** - Sessions share a Chrome profile; use separate browser/profile instances plus separate `SURF_SOCKET` values when profile state must not be shared
 18. **Semantic locators** - `locate.role`, `locate.text`, `locate.label` for more robust element finding
 19. **Frame context** - Use `frame.switch` before interacting with iframe content