surf-cli 2.11.0 → 2.13.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
@@ -485,6 +490,12 @@ surf aistudio "explain quantum computing"
 surf aistudio "redteam this" --with-page                      # Include page context
 surf aistudio "quick answer" --model gemini-3-flash-preview   # Model selection
 
+# Kimi (queries kimi.com - Moonshot K-series - using your browser login)
+surf kimi "explain quantum computing"
+surf kimi "summarize" --with-page                             # Include page context
+surf kimi "quick answer" --model thinking                     # Models: instant (default), thinking, high
+surf kimi --validate                                           # Check kimi.com UI and available models
+
 # AI Studio App Builder (generates full web apps from a prompt)
 surf aistudio.build "build a portfolio site"
 surf aistudio.build "todo app" --model gemini-3.1-pro-preview # Model override
@@ -707,6 +718,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 +958,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

@@ -355,6 +355,22 @@ const TOOLS = {
           { cmd: 'aistudio "quick answer" --model gemini-3-flash-preview', desc: "Model selection" },
         ]
       },
+      "kimi": {
+        desc: "Query Kimi AI (kimi.com, Moonshot K-series) using your browser session",
+        args: ["query"],
+        opts: {
+          "with-page": "Include current page context",
+          model: "Model: instant (default), thinking, high - or any model label shown in kimi.com's model picker",
+          timeout: "Timeout in seconds (default: 300)",
+          validate: "Check kimi.com UI and available models (no query sent)"
+        },
+        examples: [
+          { cmd: 'kimi "explain quantum computing"', desc: "Basic query" },
+          { cmd: 'kimi "summarize" --with-page', desc: "With page context" },
+          { cmd: 'kimi "deep dive" --model thinking', desc: "Try the Thinking model" },
+          { cmd: 'kimi --validate', desc: "Check UI and list available models" },
+        ]
+      },
       "aistudio.build": {
         desc: "Build an app via Google AI Studio App Builder (uses browser session)",
         args: ["query"],
@@ -533,7 +549,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 +592,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 +1492,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",
@@ -2613,6 +2641,7 @@ const PRIMARY_ARG_MAP = {
   grok: "query",
   aistudio: "query",
   "aistudio.build": "query",
+  kimi: "query",
   navigate: "url",
   go: "url",
   js: "code",
@@ -2818,11 +2847,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 +3328,21 @@ async function handleResponse(response) {
     data = { response: data };
   }
 
+  if (tool === 'kimi' && typeof data === 'string') {
+    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 +3424,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;
@@ -3500,7 +3551,18 @@ async function handleResponse(response) {
     if (meta.length > 0) {
       console.error(`[${meta.join(" | ")}]`);
     }
-  } else if (tool === "perplexity" && data?.response) {
+      } else if (tool === "kimi" && data?.response) {
+        console.log(data.response);
+        const meta = [];
+        if (data.model) meta.push(data.model);
+        if (data.partial) meta.push("partial");
+        if (Number.isFinite(data.tookMs)) meta.push(`${(data.tookMs / 1000).toFixed(1)}s`);
+        if (meta.length > 0) console.error(`\n[${meta.join(' | ')}]`);
+        if (data.url) console.error(`URL: ${data.url}`);
+        if (data.warnings?.length) {
+          for (const w of data.warnings) console.warn(`Warning: ${w}`);
+        }
+      } else if (tool === "perplexity" && data?.response) {
     console.log(data.response);
     const meta = [];
     if (data.sources) meta.push(`${data.sources} sources`);

package/native/host-helpers.cjs

@@ -77,8 +77,23 @@ function formatToolContent(result, log = () => {}, options = {}) {
     return text(output);
   }
   
-  // Handle Grok validation results
-  if (result.authenticated !== undefined && result.models !== undefined && result.expectedModels !== undefined) {
+      // Handle Kimi validation results (must precede the Grok branch - same field names)
+      if (result.kimiValidate) {
+        let output = "## Kimi Validation Results\n\n";
+        output += `**Authenticated:** ${result.authenticated ? 'Yes' : 'No'}\n`;
+        output += `**Input Field:** ${result.inputFound ? 'Found' : 'Not Found'}\n`;
+        output += `**Send Button:** ${result.sendButtonFound ? 'Found' : 'Not Found'}\n\n`;
+        output += `**Available Models:** ${result.models.length > 0 ? result.models.join(', ') : 'None found'}\n`;
+        output += `**Expected Models:** ${result.expectedModels.join(', ')}\n\n`;
+        if (result.errors && result.errors.length > 0) {
+          output += `**Errors:**\n${result.errors.map(e => `- ${e}`).join('\n')}\n\n`;
+        }
+        output += `*Completed in ${result.tookMs}ms*`;
+        return text(output);
+      }
+
+      // Handle Grok validation results
+      if (result.authenticated !== undefined && result.models !== undefined && result.expectedModels !== undefined) {
     let output = "## Grok Validation Results\n\n";
     output += `**Authenticated:** ${result.authenticated ? 'Yes' : 'No'}\n`;
     output += `**Premium:** ${result.premium ? 'Yes' : 'No'}\n`;
@@ -936,6 +951,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":
@@ -1188,6 +1215,22 @@ function mapToolToMessage(tool, args, tabId) {
         ...baseMsg,
       };
     }
+        case "kimi":
+          if (a.validate) {
+            return {
+              type: "KIMI_VALIDATE",
+              ...baseMsg
+            };
+          }
+          if (!a.query) throw new Error("query required");
+          return {
+            type: "KIMI_QUERY",
+            query: a.query,
+            model: a.model,
+            withPage: a["with-page"],
+            timeout: a.timeout ? parseInt(a.timeout, 10) * 1000 : 300000,
+            ...baseMsg
+          };
     case "window.new":
       return { 
         type: "WINDOW_NEW", 

package/native/host-sessions.cjs

@@ -22,6 +22,7 @@ const PROVIDER_DEFAULT_TIMEOUT_SECONDS = {
   chatgpt: 2700,
   gemini: 300,
   grok: 300,
+  kimi: 300,
   perplexity: 120,
   "oracle.result": 300,
   "playbook.run": 600,

package/native/host.cjs

@@ -12,6 +12,7 @@ const chatgptClient = require("./chatgpt-client.cjs");
 const geminiClient = require("./gemini-client.cjs");
 const perplexityClient = require("./perplexity-client.cjs");
 const grokClient = require("./grok-client.cjs");
+const kimiClient = require("./kimi-client.cjs");
 const aistudioClient = require("./aistudio-client.cjs");
 const aistudioBuild = require("./aistudio-build.cjs");
 const { mapToolToMessage, mapComputerAction, formatToolContent, formatToolError, buildProviderUploadMessage } = require("./host-helpers.cjs");
@@ -523,6 +524,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,
   });
 }
 
@@ -1236,13 +1238,115 @@ function handleToolRequest(msg, socket, requestContext = requestStorage.getStore
       }
       sendToolResponse(socket, originalId, result, null);
     }).catch((err) => {
-      sendToolResponse(socket, originalId, null, err.message);
-    });
-    
-    return;
-  }
+          sendToolResponse(socket, originalId, null, err.message);
+        });
+
+        return;
+      }
+
+      if (extensionMsg.type === "KIMI_QUERY") {
+        const { query, model, withPage, timeout } = extensionMsg;
+
+        queueAiRequest(async () => {
+          // 1. Get page context if requested
+          let pageContext = null;
+          if (withPage) {
+            const pageResult = await requestCallExtension(
+              requestContext,
+              "get_page_text",
+              { type: "GET_PAGE_TEXT", tabId: extensionMsg.tabId },
+              45000,
+            );
+            if (pageResult && !pageResult.error) {
+              pageContext = {
+                url: pageResult.url,
+                text: pageResult.text || pageResult.pageContent || ""
+              };
+            }
+          }
+
+          // 2. Build full prompt
+          let fullPrompt = query || "";
+          if (pageContext) {
+            fullPrompt = `Page: ${pageContext.url}\n\n${pageContext.text}\n\n---\n\n${fullPrompt}`;
+          }
+
+          // 3. Call Kimi client (uses generic browser primitives, no provider CDP types)
+          const result = await kimiClient.query({
+            prompt: fullPrompt,
+            extractionPrompt: query,
+            signal: requestContext.signal,
+            model: model,
+            timeout: timeout || 300000,
+            createTab: () => requestCallExtension(
+              requestContext,
+              "create_tab",
+              { type: "NEW_TAB", url: "https://www.kimi.com/" },
+            ),
+            closeTab: (tabIdToClose) => requestCallExtension(requestContext, "close_tab", { type: "CLOSE_TAB", tabId: tabIdToClose }, 45000, true),
+            jsEval: (tabId, code) => requestCallExtension(
+              requestContext,
+              "js_eval",
+              { type: "EXECUTE_JAVASCRIPT", tabId, code },
+            ),
+            log: (msg) => log(`[kimi] ${msg}`)
+          });
+
+          return result;
+        }).then((result) => {
+          const response = {
+            response: result.response,
+            model: result.model,
+            tookMs: result.tookMs
+          };
+          if (result.partial) {
+            response.partial = true;
+          }
+          if (result.warnings && result.warnings.length > 0) {
+            response.warnings = result.warnings;
+          }
+          if (result.modelSelectionFailed) {
+            response.modelSelectionFailed = true;
+          }
+          if (result.url) {
+            response.url = result.url;
+          }
+          sendToolResponse(socket, originalId, response, null);
+        }).catch((err) => {
+          sendToolResponse(socket, originalId, null, err.message);
+        });
+
+        return;
+      }
+
+      if (extensionMsg.type === "KIMI_VALIDATE") {
+        queueAiRequest(async () => {
+          const result = await kimiClient.validate({
+            signal: requestContext.signal,
+            createTab: () => requestCallExtension(
+              requestContext,
+              "create_tab",
+              { type: "NEW_TAB", url: "https://www.kimi.com/" },
+            ),
+            closeTab: (tabIdToClose) => requestCallExtension(requestContext, "close_tab", { type: "CLOSE_TAB", tabId: tabIdToClose }, 45000, true),
+            jsEval: (tabId, code) => requestCallExtension(
+              requestContext,
+              "js_eval",
+              { type: "EXECUTE_JAVASCRIPT", tabId, code },
+            ),
+            log: (msg) => log(`[kimi] ${msg}`)
+          });
+          return result;
+        }).then((result) => {
+          sendToolResponse(socket, originalId, result, null);
+        }).catch((err) => {
+          sendToolResponse(socket, originalId, null, err.message);
+        });
+
+        return;
+      }
 
-  if (extensionMsg.type === "AISTUDIO_QUERY") {
+      if (extensionMsg.type === "AISTUDIO_QUERY") {
     const { query, model, withPage, timeout } = extensionMsg;
     
     queueAiRequest(async () => {