surf-cli 2.11.0 → 2.12.0

package/README.md

@@ -230,9 +230,14 @@ 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.html                      # Rendered document HTML
+surf page.html --strip-scripts > artifact.html # Save a safe static Claude artifact
+surf page.save --selector "#artifact" --strip-scripts --output artifact.html # Save one rendered element
 surf page.state                     # Modals, loading state, scroll position
 ```
 
+Use `surf page.html --strip-scripts` after the page loads when you need a static export of a Claude artifact or other rendered DOM. Use `--selector <css>` to export one element. Both commands target the active frame when `frame.switch` is active.
+
 Element refs (`e1`, `e2`, `e3`...) are stable identifiers from the accessibility tree - semantic, predictable, and resilient to DOM changes.
 
 ### Semantic Locators
@@ -707,6 +712,21 @@ surf use page read --json
 surf use <site> <write-op> --write --resource-id 123
 ```
 
+Playbook read ops can also use a trusted `script` strategy when fixed JSON steps are too rigid. Scripts require `--allow-script` at run time. Only run scripts from playbooks you trust. This is not a security sandbox.
+
+The script gets `input`, `tools.run`, `tools.all`, `tools.ref`/`refs`, `emit`, and `console`. Tool calls still use Surf workflow step behavior, including auto-waits unless `autoWait` is `false`.
+
+```json
+{
+  "using": "script",
+  "script": [
+    "const page = await tools.run('page', { tool: 'page.text', args: {} });",
+    "const clicked = await tools.all(input.selectors.map((selector) => ({ key: selector.slice(1), tool: 'click', args: { selector } })));",
+    "return { page: page.output, clicked: clicked.map((link) => link.output) };"
+  ]
+}
+```
+
 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:
@@ -932,6 +952,19 @@ cp -r skills/surf ~/.pi/agent/skills/
 
 See [`skills/README.md`](skills/README.md) for details.
 
+### Pi extension
+
+Surf also includes an optional Pi extension. Install or load Surf as a Pi package, or load it from a checkout:
+
+```bash
+pi install npm:surf-cli
+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.
+
+Surf agents share one browser session. Use read tools for parallel scouts when possible. `surf_click` and `surf_type` can interfere with another agent's browser actions. Browser leases are not available yet.
+
 ## Development
 
 ```bash

package/native/cli.cjs

@@ -533,7 +533,7 @@ const TOOLS = {
       "scroll": {
         desc: "Scroll in direction",
         args: ["direction", "pixels"],
-        opts: { direction: "up|down|left|right", amount: "Scroll amount (1-10)" },
+        opts: { direction: "up|down|left|right", amount: "Scroll amount in 100 px steps (1-10)" },
         examples: [
           { cmd: "scroll down 800", desc: "Scroll down 800px" },
           { cmd: "scroll --direction down --amount 3", desc: "Scroll down" },
@@ -576,6 +576,18 @@ const TOOLS = {
       },
       "read": { desc: "Alias for page.read", args: [], alias: "page.read" },
       "page.text": { desc: "Extract all text from page", args: [] },
+      "page.html": {
+        desc: "Print rendered document HTML",
+        args: [],
+        opts: { selector: "Export matching CSS selector", "strip-scripts": "Remove script elements" },
+        examples: [{ cmd: "page.html", desc: "Print current document HTML" }],
+      },
+      "page.save": {
+        desc: "Save rendered document HTML",
+        args: [],
+        opts: { output: "File path", selector: "Export matching CSS selector", "strip-scripts": "Remove script elements" },
+        examples: [{ cmd: "page.save --output page.html", desc: "Save current document HTML" }],
+      },
       "page.state": { desc: "Get page state (modals, loading, etc.)", args: [] },
     }
   },
@@ -1464,7 +1476,7 @@ const ALL_SOCKET_TOOLS = [
   "click_type", "click_type_submit", "type", "key", "type_submit",
   "scroll", "scroll_to", "hover", "left_click_drag", "drag", "wait",
   "computer",
-  "page.read", "page.text", "page.state",
+  "page.read", "page.text", "page.html", "page.save", "page.state",
   "locate.role", "locate.text", "locate.label",
   "tab.list", "tab.new", "tab.switch", "tab.close", "tab.move", "tab.name", "tab.unname", "tab.named",
   "tab.group", "tab.ungroup", "tab.groups", "tab.reload",
@@ -2818,11 +2830,16 @@ if (tool === "network.export" && outputPath !== undefined) {
   toolArgs.output = outputPath;
 }
 
-if ((tool === "screenshot" || tool === "record" || tool === "perf-audit") && outputPath && typeof outputPath !== "string") {
+if ((tool === "screenshot" || tool === "record" || tool === "perf-audit" || tool === "page.save") && outputPath && typeof outputPath !== "string") {
   console.error("Error: --output requires a file path");
   process.exit(1);
 }
 
+if (tool === "page.save" && !outputPath) {
+  console.error("Error: page.save requires --output <path>");
+  process.exit(1);
+}
+
 if (tool === "screenshot" && outputPath) {
   toolArgs.savePath = outputPath;
   if (options.full) toolArgs.full = true;
@@ -3294,6 +3311,17 @@ async function handleResponse(response) {
     data = { response: data };
   }
 
+  if (tool === "page.save" && typeof data?.html === "string") {
+    const saveTo = path.resolve(outputPath);
+    fs.mkdirSync(path.dirname(saveTo), { recursive: true });
+    fs.writeFileSync(saveTo, data.html);
+    if (!wantJson) {
+      console.log(`Saved rendered page HTML to ${saveTo}`);
+      socket.end();
+      process.exit(0);
+    }
+  }
+
   if (tool === "perf-audit" && outputPath) {
     const saveTo = path.resolve(outputPath);
     fs.mkdirSync(path.dirname(saveTo), { recursive: true });
@@ -3375,6 +3403,8 @@ async function handleResponse(response) {
     console.log(data.pageContent);
   } else if (tool === "page.text" && data?.text) {
     console.log(data.text);
+  } else if (tool === "page.html" && typeof data?.html === "string") {
+    console.log(data.html);
   } else if (tool === "emulate.device" && data?.devices) {
     console.log("Available devices:\n");
     const devices = data.devices;

package/native/host-helpers.cjs

@@ -936,6 +936,18 @@ function mapToolToMessage(tool, args, tabId) {
     }
     case "page.text":
       return { type: "GET_PAGE_TEXT", ...baseMsg };
+    case "page.html":
+    case "page.save": {
+      if (a.selector !== undefined && (typeof a.selector !== "string" || a.selector.length === 0)) {
+        throw new Error("selector must be a non-empty string");
+      }
+      return {
+        type: "GET_PAGE_HTML",
+        selector: a.selector,
+        stripScripts: a["strip-scripts"] === true,
+        ...baseMsg,
+      };
+    }
     case "page.state":
       return { type: "PAGE_STATE", ...baseMsg };
     case "locate.role":

package/native/host.cjs

@@ -523,6 +523,7 @@ async function runHostPlaybook(msg, request) {
     onEvent: report,
     beforeDispatch: async () => updateReceipt(receipt, "dispatched"),
     afterDispatch: async ({ status, error }) => updateReceipt(receipt, status, { error }),
+    allowScript: params.allowScript === true,
   });
 }
 

package/native/playbook-cli.cjs

@@ -48,7 +48,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"]);
+  const reserved = new Set(["json", "no-lock", "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 };
 }
@@ -89,6 +89,7 @@ async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
       retryAttempt: spec.options["retry-attempt"],
       overrideInDoubt: spec.options["override-in-doubt"] === true,
       pinBuiltIn: spec.options["pin-built-in"] === true,
+      allowScript: spec.options["allow-script"] === true,
     };
     const value = await requestHost(endpoint, "playbook.run", args, {
       tabId: spec.options["tab-id"],
@@ -98,7 +99,7 @@ async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
   }
   const command = argv[1];
   const parsed = parseCommandArgs(argv.slice(2));
-  if (!command || command === "help") return { handled: true, value: "Usage: surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>" };
+  if (!command || command === "help") return { handled: true, value: "Usage: surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>\nRun trusted script strategies with: surf use <playbook> <op> --allow-script" };
   if (endpoint?.kind === "remote" && ["list", "show", "ops"].includes(command)) throw new Error(`playbook ${command} is local-only with --remote because runs resolve on the browser host`);
   if (command === "list") return { handled: true, value: listPlaybooks({ cwd }), json: parsed.options.json === true };
   if (command === "show") {

package/native/playbook-runtime.cjs

@@ -1,4 +1,5 @@
-const { executeWorkflow } = require("./workflow-runtime.cjs");
+const { executeSingleStep, executeWorkflow } = require("./workflow-runtime.cjs");
+const { runWorkflowScript } = require("./workflow-script-runtime.cjs");
 
 function applyTemplate(value, args) {
   if (typeof value === "string") {
@@ -93,6 +94,31 @@ return { status: response.status, ok: response.ok, url: response.url, headers: O
 }
 
 async function runStrategy(strategy, context) {
+  if (strategy.using === "script") {
+    if (context.allowScript !== true) throw new Error("script strategy requires --allow-script");
+    const vars = { ...context.args };
+    const result = await runWorkflowScript({
+      script: strategy.script,
+      input: context.args,
+      timeoutMs: strategy.timeoutMs ?? 10 * 60 * 1000,
+      signal: context.signal,
+      onEvent: context.onEvent,
+      executeTool: async (tool, args, options = {}) => {
+        await context.markDispatched?.();
+        const step = await executeSingleStep({ cmd: tool, args, as: "value" }, vars, {
+          autoWait: strategy.autoWait !== false,
+          executeTool: context.executeTool,
+          onEvent: context.onEvent,
+          signal: options.signal || context.signal,
+          sleep: context.sleep,
+          stepDelay: strategy.stepDelay ?? 100,
+        });
+        if (!step.success) throw new Error(step.error || `tool ${tool} failed`);
+        return step.output;
+      },
+    });
+    return result.value;
+  }
   if (strategy.using === "workflow") {
     const result = await executeWorkflow(applyTemplate(strategy.steps, context.args), {
       autoWait: strategy.autoWait !== false,
@@ -130,7 +156,7 @@ async function runStrategy(strategy, context) {
   throw new Error(`unsupported strategy: ${strategy.using}`);
 }
 
-async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId, executeTool, executeNative, signal, sleep, onEvent = () => {}, beforeDispatch = async () => {}, afterDispatch = async () => {} }) {
+async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId, executeTool, executeNative, signal, sleep, onEvent = () => {}, beforeDispatch = async () => {}, afterDispatch = async () => {}, allowScript = false }) {
   const args = resolveArgs(op, providedArgs);
   const attempts = [];
   for (let index = 0; index < op.run.length; index++) {
@@ -154,6 +180,7 @@ async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId,
         allowedOrigins: op.origins || playbook.origins || [],
         markDispatched: op.effect === "write" ? markDispatched : undefined,
         serverIdempotency: op.effect === "write" ? op.safety?.serverIdempotency : undefined,
+        allowScript,
       });
       const value = extractResult(raw, strategy.extract);
       verifyResult(value, strategy.verify || strategy.expect || op.on?.success?.expect, raw);

package/native/playbooks.cjs

@@ -75,8 +75,21 @@ function validateWriteWorkflowSteps(steps, opId) {
   }
 }
 
+function normalizeScript(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.every((line) => typeof line === "string")) return value.join("\n");
+  return null;
+}
+
 function validateStrategy(strategy, effect, opId) {
   if (!strategy || typeof strategy !== "object" || Array.isArray(strategy)) throw new Error("playbook strategy must be an object");
+  if (strategy.using === "script") {
+    if (effect === "write") throw new Error(`write op ${opId} script strategy is not supported`);
+    const script = normalizeScript(strategy.script);
+    if (!script?.trim()) throw new Error("script strategy requires script");
+    if (strategy.timeoutMs !== undefined && (!Number.isInteger(strategy.timeoutMs) || strategy.timeoutMs < 1)) throw new Error("script strategy timeoutMs must be a positive integer");
+    return { ...strategy, script };
+  }
   if (strategy.using === "workflow") {
     if (!Array.isArray(strategy.steps) || strategy.steps.length === 0) throw new Error("workflow strategy requires steps");
     const steps = strategy.steps.map(normalizeStep);

package/native/workflow-script-runtime.cjs

@@ -0,0 +1,294 @@
+const { Worker } = require("node:worker_threads");
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+const WORKER_SOURCE = String.raw`
+const { parentPort } = require("node:worker_threads");
+const vm = require("node:vm");
+const { inspect } = require("node:util");
+
+let nextCallId = 0;
+const pending = new Map();
+const keyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const fingerprints = new Map();
+let contextObjectPrototype;
+
+function stableJson(value) {
+  if (Array.isArray(value)) return "[" + value.map(stableJson).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.keys(value).sort().map((key) => JSON.stringify(key) + ":" + stableJson(value[key])).join(",") + "}";
+  return JSON.stringify(value) ?? "undefined";
+}
+
+function assertJsonValue(value, path = "value", seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(path + " must contain only finite JSON numbers.");
+    return;
+  }
+  if (typeof value !== "object") throw new Error(path + " must be a JSON value; received " + typeof value + ".");
+  if (seen.has(value)) throw new Error(path + " must not contain cycles.");
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(value, index)) throw new Error(path + " must not contain sparse array entries.");
+      assertJsonValue(value[index], path + "[" + index + "]", seen);
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype && prototype !== contextObjectPrototype) throw new Error(path + " must contain only plain JSON objects.");
+    if (Object.getOwnPropertySymbols(value).length > 0) throw new Error(path + " must not contain symbol keys.");
+    for (const [key, entry] of Object.entries(value)) assertJsonValue(entry, path + "." + key, seen);
+  }
+  seen.delete(value);
+}
+
+function hostCall(method, args) {
+  return new Promise((resolve, reject) => {
+    const callId = ++nextCallId;
+    pending.set(callId, { resolve, reject });
+    parentPort.postMessage({ type: "call", callId, method, args });
+  });
+}
+
+function validateRunCall(key, params, label, nextFingerprints = fingerprints) {
+  if (typeof key !== "string" || !keyPattern.test(key)) throw new Error(label + " has an invalid key.");
+  if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error(label + " requires a params object.");
+  const tool = params.tool ?? params.cmd;
+  if (typeof tool !== "string" || !tool) throw new Error(label + " requires a tool string.");
+  if (params.args !== undefined && (!params.args || typeof params.args !== "object" || Array.isArray(params.args))) throw new Error(label + " args must be an object.");
+  assertJsonValue(params, label + " params");
+  const fingerprint = stableJson(params);
+  const existing = nextFingerprints.get(key);
+  if (existing !== undefined && existing !== fingerprint) throw new Error("Duplicate script key '" + key + "' used with incompatible tool params.");
+  nextFingerprints.set(key, fingerprint);
+}
+
+const tools = Object.freeze({
+  run(key, params) {
+    validateRunCall(key, params, "tools.run");
+    return hostCall("run", { key, params });
+  },
+  all(items) {
+    if (!Array.isArray(items)) throw new Error("tools.all(items) requires an array.");
+    const nextFingerprints = new Map(fingerprints);
+    const calls = [];
+    for (let index = 0; index < items.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(items, index)) throw new Error("tools.all items must not contain sparse entries.");
+      const item = items[index];
+      if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("tools.all item " + index + " must be an object.");
+      const { key, ...params } = item;
+      validateRunCall(key, params, "tools.all item " + index, nextFingerprints);
+      calls.push({ key, params });
+    }
+    for (const { key, params } of calls) fingerprints.set(key, stableJson(params));
+    return Promise.all(calls.map(({ key, params }) => hostCall("run", { key, params, collectFailure: true })));
+  },
+  ref(result) {
+    if (!result || typeof result !== "object") throw new Error("tools.ref(result) requires a tool result object.");
+    return "[tool " + (result.key || "unknown") + "]";
+  },
+  refs(results) {
+    if (!Array.isArray(results)) throw new Error("tools.refs(results) requires an array.");
+    return results.map(tools.ref).join("\n");
+  },
+});
+
+const capturedConsole = Object.freeze(Object.fromEntries(
+  ["log", "info", "warn", "error"].map((level) => [level, (...args) => {
+    parentPort.postMessage({ type: "console", level, text: args.map((value) => typeof value === "string" ? value : inspect(value, { depth: 4, breakLength: 120 })).join(" ") });
+  }]),
+));
+
+parentPort.on("message", async (message) => {
+  if (message.type === "response") {
+    const entry = pending.get(message.callId);
+    if (!entry) return;
+    pending.delete(message.callId);
+    if (message.ok) entry.resolve(message.value);
+    else entry.reject(new Error(message.error));
+    return;
+  }
+  if (message.type !== "start") return;
+  try {
+    const sandbox = {
+      input: Object.freeze(message.input ?? {}),
+      tools,
+      surf: tools,
+      emit(value) { assertJsonValue(value, "emit"); parentPort.postMessage({ type: "emit", value }); },
+      console: capturedConsole,
+    };
+    const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
+    contextObjectPrototype = vm.runInContext("Object.prototype", context);
+    const compiled = new vm.Script("(async () => {\n" + message.script + "\n})()", { filename: "surf-workflow-script.js" });
+    const value = await compiled.runInContext(context);
+    const persistedValue = value === undefined ? null : value;
+    assertJsonValue(persistedValue, "return");
+    parentPort.postMessage({ type: "complete", value: persistedValue });
+  } catch (error) {
+    parentPort.postMessage({ type: "error", error: error && error.stack ? error.stack : String(error) });
+  }
+});
+`;
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertJsonValue(value, path = "value", seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${path} must contain only finite JSON numbers.`);
+    return;
+  }
+  if (typeof value !== "object") throw new Error(`${path} must be a JSON value; received ${typeof value}.`);
+  if (seen.has(value)) throw new Error(`${path} must not contain cycles.`);
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      if (!Object.hasOwn(value, index)) throw new Error(`${path} must not contain sparse array entries.`);
+      assertJsonValue(value[index], `${path}[${index}]`, seen);
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype) throw new Error(`${path} must contain only plain JSON objects.`);
+    if (Object.getOwnPropertySymbols(value).length > 0) throw new Error(`${path} must not contain symbol keys.`);
+    for (const [key, entry] of Object.entries(value)) assertJsonValue(entry, `${path}.${key}`, seen);
+  }
+  seen.delete(value);
+}
+
+function omitUndefined(value, seen = new Set()) {
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  const next = Array.isArray(value)
+    ? value.map((entry) => entry === undefined ? null : omitUndefined(entry, seen))
+    : Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => entry === undefined ? [] : [[key, omitUndefined(entry, seen)]]));
+  seen.delete(value);
+  return next;
+}
+
+function validateKey(value) {
+  if (typeof value !== "string" || !KEY_PATTERN.test(value)) {
+    throw new Error("tool key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+  }
+  return value;
+}
+
+async function runWorkflowScript({ script, input = {}, timeoutMs = 10 * 60 * 1000, signal, executeTool, onEvent = () => {}, onEmit = () => {}, onConsole = () => {} }) {
+  if (typeof script !== "string" || !script.trim()) throw new Error("script strategy requires a non-empty script string");
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1) throw new Error("script timeoutMs must be a positive integer");
+  if (typeof executeTool !== "function") throw new Error("script strategy requires executeTool");
+  assertJsonValue(input, "input");
+
+  const worker = new Worker(WORKER_SOURCE, { eval: true });
+  const emits = [];
+  const consoleEntries = [];
+  const trace = [];
+  const childController = new AbortController();
+  let settled = false;
+
+  return await new Promise((resolve, reject) => {
+    const finish = (outcome) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      void worker.terminate();
+      childController.abort(outcome.error || new Error("Script strategy completed."));
+      if (outcome.error) reject(outcome.error);
+      else resolve({ value: outcome.value, emits, console: consoleEntries, trace });
+    };
+    const onAbort = () => finish({ error: new Error(signal.reason instanceof Error ? signal.reason.message : String(signal.reason || "Script strategy aborted")) });
+    const timer = setTimeout(() => finish({ error: new Error(`Script strategy timed out after ${timeoutMs}ms.`) }), timeoutMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) return onAbort();
+
+    const respond = (callId, promise) => {
+      void promise.then(
+        (value) => {
+          try {
+            const clean = omitUndefined(value);
+            assertJsonValue(clean, "tool result");
+            worker.postMessage({ type: "response", callId, ok: true, value: clean });
+          } catch (error) {
+            worker.postMessage({ type: "response", callId, ok: false, error: error instanceof Error ? error.message : String(error) });
+          }
+        },
+        (error) => worker.postMessage({ type: "response", callId, ok: false, error: error instanceof Error ? error.message : String(error) }),
+      );
+    };
+
+    worker.on("error", (error) => finish({ error: new Error(`Script worker failed: ${error.message}`) }));
+    worker.on("exit", (code) => {
+      if (!settled && code !== 0) finish({ error: new Error(`Script worker exited with code ${code}.`) });
+    });
+    worker.on("message", (message) => {
+      if (message.type === "emit") {
+        try {
+          assertJsonValue(message.value, "emit");
+          emits.push(message.value);
+          onEmit([...emits]);
+        } catch (error) {
+          finish({ error: new Error(`Script emit could not be persisted: ${error.message}`) });
+        }
+        return;
+      }
+      if (message.type === "console") {
+        if (["log", "info", "warn", "error"].includes(message.level) && typeof message.text === "string") {
+          const entry = { level: message.level, text: message.text };
+          consoleEntries.push(entry);
+          onConsole(entry);
+        }
+        return;
+      }
+      if (message.type === "complete") {
+        try {
+          assertJsonValue(message.value, "return");
+          finish({ value: message.value });
+        } catch (error) {
+          finish({ error: new Error(`Script return could not be persisted: ${error.message}`) });
+        }
+        return;
+      }
+      if (message.type === "error") return finish({ error: new Error(typeof message.error === "string" ? message.error : "Script strategy failed.") });
+      if (message.type !== "call" || typeof message.callId !== "number" || message.method !== "run" || !isRecord(message.args)) return;
+      let key;
+      try {
+        key = validateKey(message.args.key);
+      } catch (error) {
+        return respond(message.callId, Promise.reject(error));
+      }
+      const params = message.args.params;
+      if (!isRecord(params)) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}', params) requires a params object.`)));
+      const tool = params.tool ?? params.cmd;
+      if (typeof tool !== "string" || !tool) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}') requires a tool string.`)));
+      const args = params.args === undefined ? {} : params.args;
+      if (!isRecord(args)) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}') args must be an object.`)));
+      const collectFailure = message.args.collectFailure === true;
+      const startedAt = Date.now();
+      trace.push({ key, tool, state: "started" });
+      onEvent({ type: "script.tool.started", key, tool, startedAt: new Date().toISOString() });
+      respond(message.callId, Promise.resolve().then(async () => {
+        try {
+          const output = await executeTool(tool, args, { signal: childController.signal });
+          const result = { key, tool, ok: true, output };
+          trace.push({ key, tool, state: "completed", durationMs: Date.now() - startedAt });
+          onEvent({ type: "script.tool.completed", key, tool, endedAt: new Date().toISOString() });
+          return result;
+        } catch (error) {
+          const text = error instanceof Error ? error.message : String(error);
+          const result = { key, tool, ok: false, error: text };
+          trace.push({ key, tool, state: "failed", durationMs: Date.now() - startedAt, error: text });
+          onEvent({ type: "script.tool.failed", key, tool, error: text, endedAt: new Date().toISOString() });
+          if (!collectFailure) throw new Error(`Tool '${key}' failed: ${text}`);
+          return result;
+        }
+      }));
+    });
+
+    worker.postMessage({ type: "start", script, input });
+  });
+}
+
+module.exports = { runWorkflowScript };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -10,7 +10,8 @@
     "agent",
     "cli",
     "cdp",
-    "devtools"
+    "devtools",
+    "pi-package"
   ],
   "author": "Nico Bailon",
   "license": "MIT",
@@ -28,6 +29,7 @@
   },
   "files": [
     "native/",
+    "pi-extension/",
     "playbooks/",
     "scripts/",
     "dist/",
@@ -38,7 +40,7 @@
   "scripts": {
     "dev": "vite build --watch --mode development",
     "build": "vite build",
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && tsc --noEmit -p tsconfig.pi-extension.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "lint:test": "biome check test/",
@@ -64,11 +66,24 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.4",
     "@types/chrome": "^0.2.2",
+    "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "^4.1.9",
     "@vitest/ui": "^4.1.9",
-    "puppeteer": "25.3.0",
+    "puppeteer": "25.4.0",
     "typescript": "^7.0.2",
     "vite": "^8.1.4",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "typebox": "^1.3.11"
+  },
+  "pi": {
+    "extensions": [
+      "./pi-extension/surf.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "typebox": "*"
   }
 }

package/pi-extension/surf.ts

@@ -0,0 +1,230 @@
+import { createRequire } from "node:module";
+import { Type } from "typebox";
+
+const require = createRequire(import.meta.url);
+const { openClientTransport } = require("../native/client-transport.cjs") as {
+  openClientTransport(endpoint: SurfEndpoint, options?: { requestTimeoutMs?: number }): Promise<{
+    request(message: Record<string, unknown>, timeoutMs?: number, transferPlan?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+  }>;
+};
+const { selectEndpoint } = require("../native/endpoint.cjs") as {
+  selectEndpoint(args: string[], env?: Record<string, string | undefined>): { endpoint: SurfEndpoint };
+};
+const { resolveRequestDeadlineMs } = require("../native/host-sessions.cjs") as {
+  resolveRequestDeadlineMs(tool: string, args: Record<string, unknown>): number;
+};
+const { prepareRemoteTool, validateLocalToolPaths } = require("../native/file-transfer.cjs") as {
+  prepareRemoteTool(tool: string, args: Record<string, unknown>): { args: Record<string, unknown>; uploads?: unknown[]; downloads?: unknown[]; pathRefs?: unknown[] };
+  validateLocalToolPaths(tool: string, args: Record<string, unknown>): Record<string, unknown>;
+};
+
+const MAX_OUTPUT_CHARS = 20_000;
+const ORACLE_ACTIVE_STATES = new Set(["created", "dispatched", "awaiting"]);
+const BACKGROUND_WORK_PROTOCOL_VERSION = 1;
+const BACKGROUND_WORK_REGISTRY_KEY = "pi-subagents.background-work.v1";
+
+type Pi = {
+  registerTool(tool: Record<string, unknown>): void;
+  on(event: "session_start" | "session_shutdown", handler: (event: unknown, ctx: unknown) => void | Promise<void>): void;
+};
+
+type SurfEndpoint = { kind?: string };
+
+type ToolResult = { content: Array<{ type: "text" | "image"; text?: string; data?: string; mimeType?: string }>; details?: unknown; isError?: boolean };
+
+type BackgroundWorkProvider = {
+  name: string;
+  wakeChannels: string[];
+  listActiveWork(): Array<{ id: string; sessionId: string }>;
+};
+
+type BackgroundWorkRegistry = {
+  version: typeof BACKGROUND_WORK_PROTOCOL_VERSION;
+  providers: Map<string, BackgroundWorkProvider>;
+};
+
+function textResult(value: unknown, isError = false): ToolResult {
+  const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  const bounded = text.length > MAX_OUTPUT_CHARS
+    ? `${text.slice(0, MAX_OUTPUT_CHARS)}\n\n[Surf output truncated at ${MAX_OUTPUT_CHARS} characters]`
+    : text;
+  return { content: [{ type: "text", text: bounded }], ...(isError ? { isError: true } : {}) };
+}
+
+function resultFromHost(response: Record<string, unknown>): ToolResult {
+  const error = response.error as { content?: Array<{ text?: string }> } | undefined;
+  if (error) return textResult(error.content?.map((item) => item.text ?? "").join("\n") || "Surf request failed", true);
+  const result = response.result as { content?: ToolResult["content"] } | undefined;
+  if (!result?.content) return textResult(result ?? "OK");
+  const content = result.content.map((item) => item.type === "text" && item.text && item.text.length > MAX_OUTPUT_CHARS
+    ? { ...item, text: `${item.text.slice(0, MAX_OUTPUT_CHARS)}\n\n[Surf output truncated at ${MAX_OUTPUT_CHARS} characters]` }
+    : item);
+  const text = content.find((item) => item.type === "text")?.text;
+  let details: unknown;
+  try {
+    details = text ? JSON.parse(text) : undefined;
+  } catch {
+    details = undefined;
+  }
+  return { content, details };
+}
+
+export function createToolRequest(tool: string, args: Record<string, unknown>, tabId?: number) {
+  return {
+    type: "tool_request",
+    method: "execute_tool",
+    params: { tool, args, ...(tabId === undefined ? {} : { tabId }) },
+    id: `pi-surf-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  };
+}
+
+function prepareRequest(endpoint: SurfEndpoint, tool: string, args: Record<string, unknown>) {
+  if (endpoint.kind === "remote") return prepareRemoteTool(tool, args);
+  return { args: validateLocalToolPaths(tool, args), uploads: [], downloads: [], pathRefs: [] };
+}
+
+export async function requestSurf(tool: string, args: Record<string, unknown>, tabId?: number): Promise<ToolResult> {
+  const { endpoint } = selectEndpoint([], process.env);
+  const timeoutMs = resolveRequestDeadlineMs(tool, args);
+  const transport = await openClientTransport(endpoint, { requestTimeoutMs: timeoutMs });
+  try {
+    const prepared = prepareRequest(endpoint, tool, args);
+    const response = await transport.request(createToolRequest(tool, prepared.args, tabId), timeoutMs, prepared);
+    return resultFromHost(response);
+  } finally {
+    await transport.close();
+  }
+}
+
+export function surfRequest(tool: string, args: Record<string, unknown>, tabId?: number) {
+  return requestSurf(tool, args, tabId);
+}
+
+export function registerGlobalBackgroundProvider(provider: BackgroundWorkProvider): () => void {
+  const key = Symbol.for(BACKGROUND_WORK_REGISTRY_KEY);
+  const globalObject = globalThis as Record<PropertyKey, unknown>;
+  const existing = globalObject[key];
+  let registry: BackgroundWorkRegistry;
+
+  if (existing === undefined) {
+    registry = { version: BACKGROUND_WORK_PROTOCOL_VERSION, providers: new Map() };
+    globalObject[key] = registry;
+  } else if (
+    existing &&
+    typeof existing === "object" &&
+    !Array.isArray(existing) &&
+    (existing as Partial<BackgroundWorkRegistry>).version === BACKGROUND_WORK_PROTOCOL_VERSION &&
+    (existing as Partial<BackgroundWorkRegistry>).providers instanceof Map
+  ) {
+    registry = existing as BackgroundWorkRegistry;
+  } else {
+    throw new Error(`Unsupported background-work registry at Symbol.for("${BACKGROUND_WORK_REGISTRY_KEY}").`);
+  }
+
+  registry.providers.set(provider.name, provider);
+  return () => {
+    if (registry.providers.get(provider.name) === provider) registry.providers.delete(provider.name);
+  };
+}
+
+export function registerOptionalBackgroundProvider(sessionId: string, jobIds: Set<string>, listJobs: () => Array<{ id: string; state: string }>, register: (provider: BackgroundWorkProvider) => () => void) {
+  return register({
+    name: "surf-oracle",
+    wakeChannels: ["surf-oracle:finished"],
+    listActiveWork: () => listJobs()
+      .filter((job) => jobIds.has(job.id) && ORACLE_ACTIVE_STATES.has(job.state))
+      .map((job) => ({ id: job.id, sessionId })),
+  });
+}
+
+export function rememberOracleJobForSession(jobIds: Set<string>, jobId: unknown, requestGeneration: number, currentGeneration: number, sessionActive: boolean): boolean {
+  if (typeof jobId !== "string" || !sessionActive || requestGeneration !== currentGeneration) return false;
+  jobIds.add(jobId);
+  return true;
+}
+
+function registerTool(pi: Pi, name: string, description: string, parameters: unknown, map: (args: Record<string, unknown>) => [string, Record<string, unknown>, number | undefined]) {
+  pi.registerTool({
+    name,
+    label: name,
+    description,
+    parameters,
+    async execute(_id: string, args: Record<string, unknown>) {
+      try {
+        const [tool, toolArgs, tabId] = map(args);
+        return await requestSurf(tool, toolArgs, tabId);
+      } catch (error) {
+        return textResult(error instanceof Error ? error.message : String(error), true);
+      }
+    },
+  });
+}
+
+export default function surfExtension(pi: Pi) {
+  registerTool(pi, "surf_read", "Read the current Surf browser page. Read tools are safer for parallel scouts than browser actions.", Type.Object({
+    tabId: Type.Optional(Type.Number()), filter: Type.Optional(Type.String()), depth: Type.Optional(Type.Number()), ref: Type.Optional(Type.String()), compact: Type.Optional(Type.Boolean()), maxBytes: Type.Optional(Type.Number()),
+  }), (args) => ["page.read", { filter: args.filter, depth: args.depth, ref: args.ref, compact: args.compact, "max-bytes": args.maxBytes }, args.tabId as number | undefined]);
+  registerTool(pi, "surf_screenshot", "Capture a bounded Surf browser screenshot.", Type.Object({
+    tabId: Type.Optional(Type.Number()), output: Type.Optional(Type.String()), fullpage: Type.Optional(Type.Boolean()), annotate: Type.Optional(Type.Boolean()), maxSize: Type.Optional(Type.Number()),
+  }), (args) => ["screenshot", { output: args.output, fullpage: args.fullpage, annotate: args.annotate, "max-size": args.maxSize }, args.tabId as number | undefined]);
+  registerTool(pi, "surf_click", "Click a Surf browser element by ref, selector, or coordinates. This can interfere with other agents in the shared browser session.", Type.Object({
+    tabId: Type.Optional(Type.Number()), ref: Type.Optional(Type.String()), selector: Type.Optional(Type.String()), x: Type.Optional(Type.Number()), y: Type.Optional(Type.Number()), button: Type.Optional(Type.String({ description: "left, right, or double" })),
+  }), (args) => [args.button === "right" ? "right_click" : args.button === "double" ? "double_click" : "click", args, args.tabId as number | undefined]);
+  registerTool(pi, "surf_type", "Type text in the Surf browser. This can interfere with other agents in the shared browser session.", Type.Object({
+    tabId: Type.Optional(Type.Number()), text: Type.String(), ref: Type.Optional(Type.String()), selector: Type.Optional(Type.String()), clear: Type.Optional(Type.Boolean()), submit: Type.Optional(Type.Boolean()),
+  }), (args) => ["type", args, args.tabId as number | undefined]);
+  registerTool(pi, "surf_tool", "Run one existing Surf browser tool through the native host. Prefer the dedicated read, screenshot, click, and type tools when they fit.", Type.Object({
+    tool: Type.String(), args: Type.Optional(Type.Record(Type.String(), Type.Unknown())), tabId: Type.Optional(Type.Number()),
+  }), (args) => [args.tool as string, (args.args as Record<string, unknown>) ?? {}, args.tabId as number | undefined]);
+  registerTool(pi, "surf_oracle_status", "Get the status of a Surf oracle job, or the newest job.", Type.Object({ id: Type.Optional(Type.String()) }), (args) => ["oracle.status", args, undefined]);
+  registerTool(pi, "surf_oracle_result", "Capture the result of a Surf oracle job.", Type.Object({ id: Type.String(), timeout: Type.Optional(Type.Number()) }), (args) => ["oracle.result", args, undefined]);
+
+  const oracleJobIds = new Set<string>();
+  let sessionGeneration = 0;
+  let sessionActive = false;
+  pi.registerTool({
+    name: "surf_oracle_ask",
+    label: "surf_oracle_ask",
+    description: "Start a durable local Surf ChatGPT oracle job.",
+    parameters: Type.Object({ prompt: Type.String(), model: Type.Optional(Type.String()), effort: Type.Optional(Type.String()), follow: Type.Optional(Type.String()) }),
+    async execute(_id: string, args: Record<string, unknown>) {
+      const requestGeneration = sessionGeneration;
+      try {
+        const result = await requestSurf("oracle.ask", args);
+        const job = result.details as { id?: string } | undefined;
+        rememberOracleJobForSession(oracleJobIds, job?.id, requestGeneration, sessionGeneration, sessionActive);
+        return result;
+      } catch (error) {
+        return textResult(error instanceof Error ? error.message : String(error), true);
+      }
+    },
+  });
+
+  let dispose: (() => void) | undefined;
+  pi.on("session_start", (_event, ctx) => {
+    sessionGeneration++;
+    sessionActive = false;
+    dispose?.();
+    dispose = undefined;
+    oracleJobIds.clear();
+
+    const session = ctx as { sessionManager?: { getSessionId?: () => string }; sessionId?: string };
+    const sessionId = session.sessionId ?? session.sessionManager?.getSessionId?.();
+    if (!sessionId) return;
+    try {
+      const jobs = require("../native/oracle-jobs.cjs") as { listJobs(): Array<{ id: string; state: string }> };
+      dispose = registerOptionalBackgroundProvider(sessionId, oracleJobIds, jobs.listJobs, registerGlobalBackgroundProvider);
+      sessionActive = true;
+    } catch {
+      // pi-subagents is optional. Browser tools work without it.
+    }
+  });
+  pi.on("session_shutdown", () => {
+    sessionGeneration++;
+    sessionActive = false;
+    dispose?.();
+    dispose = undefined;
+    oracleJobIds.clear();
+  });
+}

package/skills/surf/SKILL.md

@@ -63,8 +63,8 @@ surf click --x 100 --y 200
 # 4. Type text
 surf type --text "hello"
 
-# 5. Screenshot
-surf screenshot --output /tmp/shot.png
+# 5. Full-page screenshot
+surf screenshot --full-page --output /tmp/shot.png
 
 # Inspect animation/style changes as JSON
 surf animate-audit --selector ".thing" --duration 2000 --fps 10
@@ -292,9 +292,26 @@ surf page.read --depth 3       # Limit tree depth
 surf page.read --compact       # Minimal output for LLM efficiency
 surf page.read --max-bytes 2000 # Cap visible text at a UTF-8 byte boundary
 surf page.text                 # Plain text content only
+surf page.html --strip-scripts # Rendered HTML without scripts
+surf page.save --selector "#artifact" --strip-scripts --output page.html # Save one static element
 surf page.state                # Modals, loading state, scroll info
 ```
 
+### Export Rendered HTML
+
+Use `page.html` when the user wants a static copy of the current rendered DOM. This works for Claude artifact pages and ordinary web pages.
+
+```bash
+# Save the active page as HTML.
+surf page.save --output page.html
+
+# Save a Claude artifact or other preview page after it loads, without scripts.
+surf wait.dom --stable 500
+surf page.html --selector "#artifact" --strip-scripts > artifact.html
+```
+
+Use `--selector <css>` to export its matching element only. A selector miss fails with an error. `--strip-scripts` removes scripts from exported markup without changing the page. Without `--selector`, `page.html` exports the whole document with its doctype. `page.html` exports the selected frame when `frame.switch` is active. Use `page.read` first when you need refs or visible text.
+
 ## Semantic Element Location
 
 Find and act on elements by role, text, or label instead of refs:
@@ -687,10 +704,11 @@ surf wait.element ".missing" --auto-capture --timeout 2000
 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
 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. **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
-16. **Hard isolation** - Use separate browser/profile instances plus separate `SURF_SOCKET` values when agents must not share a host or target
-17. **Semantic locators** - `locate.role`, `locate.text`, `locate.label` for more robust element finding
-18. **Frame context** - Use `frame.switch` before interacting with iframe content
+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
+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
 
 ## Socket API