surf-cli 2.10.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
@@ -492,6 +497,19 @@ surf aistudio.build "crm dashboard" --output ./out            # Extract zip to d
 surf aistudio.build "game" --keep-open --timeout 600          # Keep tab open, 10min timeout
 ```
 
+#### Oracle
+
+Use `surf oracle` for a durable, local ChatGPT consult instead of a quick `surf chatgpt` one-shot. It persists jobs by conversation URL, supports repeatable file-context globs, and verifies requested model and reasoning effort before submission.
+
+```bash
+surf oracle ask "review this change" --files "src/**/*.ts" --model pro --effort extended --detach --json
+surf oracle status <job-id> --json
+surf oracle result <job-id> --wait --json
+surf oracle follow <job-id> "challenge that recommendation" --detach --json
+```
+
+Only one oracle job can be in flight. Sensitive filename patterns and gitignored context are blocked unless `--allow-sensitive` is explicit.
+
 Each AI tool uses your existing browser login - no API keys needed. Just be logged into the respective service in Chrome (chatgpt.com, gemini.google.com, perplexity.ai, x.com, or aistudio.google.com).
 
 **Grok troubleshooting:** If queries fail, run `surf grok --validate` to check if the UI structure changed. Use `--save-models` to update the model cache in `surf.json`. Default model is `fast`.
@@ -694,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:
@@ -919,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/chatgpt-client-response.cjs

@@ -0,0 +1,336 @@
+const { throwIfAborted } = require("./abort.cjs");
+const { SELECTORS, delay, evaluate } = require("./chatgpt-client-ui.cjs");
+
+function normalizePromptEcho(prompt) {
+  return String(prompt || "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 200);
+}
+
+function matchesPromptEcho(text, promptEcho) {
+  const expected = normalizePromptEcho(promptEcho);
+  return expected.length > 0 && normalizePromptEcho(text) === expected;
+}
+
+function cleanChatGPTResponseText(rawText) {
+  if (!rawText) return "";
+
+  const chromeLines = new Set([
+    "copy",
+    "good response",
+    "bad response",
+    "read aloud",
+    "edit",
+    "retry",
+    "continue generating",
+    "share",
+  ]);
+
+  const lines = [];
+  let inCodeFence = false;
+
+  for (const line of String(rawText).replace(/\r\n?/g, "\n").split("\n")) {
+    const trimmed = line.trim();
+    const isFenceLine = trimmed.startsWith("```");
+    const normalizedLine = inCodeFence || isFenceLine ? line.replace(/[\t ]+$/g, "") : line;
+
+    lines.push({
+      text: normalizedLine,
+      trimmed,
+      isChrome: trimmed.length > 0 && chromeLines.has(trimmed.toLowerCase()),
+      inCodeFence,
+      isFenceLine,
+    });
+
+    if (isFenceLine) {
+      inCodeFence = !inCodeFence;
+    }
+  }
+
+  while (lines.length > 0 && lines[0].trimmed.length === 0) {
+    lines.shift();
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trimmed.length === 0) {
+    lines.pop();
+  }
+
+  let trailingChromeStart = lines.length;
+  while (trailingChromeStart > 0) {
+    const line = lines[trailingChromeStart - 1];
+    if (line.inCodeFence || line.isFenceLine || !line.isChrome) break;
+    trailingChromeStart--;
+  }
+
+  const trailingChromeCount = lines.length - trailingChromeStart;
+  if (trailingChromeCount >= 2) {
+    lines.splice(trailingChromeStart);
+  }
+
+  while (lines.length > 0 && lines[0].trimmed.length === 0) {
+    lines.shift();
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trimmed.length === 0) {
+    lines.pop();
+  }
+
+  return lines.map((line) => line.text).join("\n");
+}
+
+function extractLatestAssistantSnapshot(candidates) {
+  if (!Array.isArray(candidates)) return null;
+
+  let latestEmptyAssistant = null;
+
+  for (let i = candidates.length - 1; i >= 0; i--) {
+    const candidate = candidates[i];
+    if (!candidate?.isAssistant) continue;
+
+    const snapshot = {
+      ...candidate,
+      text: cleanChatGPTResponseText(candidate?.text || ""),
+      turnIndex: i,
+    };
+
+    if (snapshot.text) {
+      return snapshot;
+    }
+
+    if (!latestEmptyAssistant) {
+      latestEmptyAssistant = snapshot;
+    }
+  }
+
+  return latestEmptyAssistant;
+}
+
+function normalizeResponseSnapshot(rawSnapshot) {
+  const candidates = rawSnapshot?.candidates;
+  return {
+    latestAssistant: extractLatestAssistantSnapshot(candidates),
+    assistantCount: Array.isArray(candidates)
+      ? candidates.filter((candidate) => candidate?.isAssistant).length
+      : 0,
+    stopVisible: Boolean(rawSnapshot?.stopVisible),
+  };
+}
+
+function isNewAssistantContent(
+  latestAssistant,
+  baselineAssistant,
+  assistantCount = 0,
+  baselineAssistantCount = 0,
+) {
+  if (!latestAssistant) return false;
+  if (!baselineAssistant) return true;
+  if (
+    latestAssistant.messageId &&
+    baselineAssistant.messageId &&
+    latestAssistant.messageId !== baselineAssistant.messageId
+  ) {
+    return true;
+  }
+
+  const currentText = latestAssistant.text || "";
+  const baselineText = baselineAssistant.text || "";
+
+  if (assistantCount > baselineAssistantCount) {
+    if (latestAssistant.turnIndex !== baselineAssistant.turnIndex) {
+      return true;
+    }
+    if (currentText !== baselineText) {
+      return true;
+    }
+    return false;
+  }
+
+  return currentText !== baselineText;
+}
+
+function isChatGPTResponseComplete(snapshot, stableCycles, stableMs) {
+  if (!snapshot?.text) return false;
+  if (snapshot.stopVisible) return false;
+  if (snapshot.hasFinishedActions) return true;
+  return stableCycles >= 6 && stableMs >= 1200;
+}
+
+function scopeSnapshotToPrompt(rawSnapshot, promptEcho) {
+  const candidates = Array.isArray(rawSnapshot?.candidates) ? rawSnapshot.candidates : [];
+  let userIndex = -1;
+  for (let index = candidates.length - 1; index >= 0; index--) {
+    const candidate = candidates[index];
+    if (candidate?.isUser && matchesPromptEcho(candidate.text, promptEcho)) {
+      userIndex = index;
+      break;
+    }
+  }
+  if (userIndex === -1) return { ...rawSnapshot, candidates: [] };
+
+  const following = candidates.slice(userIndex + 1);
+  const nextUserIndex = following.findIndex((candidate) => candidate?.isUser);
+  return {
+    ...rawSnapshot,
+    candidates: nextUserIndex === -1 ? following : following.slice(0, nextUserIndex),
+  };
+}
+
+async function readChatGPTResponseSnapshot(cdp) {
+  return evaluate(
+    cdp,
+    `(() => {
+      const scope = document.querySelector('main') || document;
+      const CONVERSATION_SELECTOR = ${JSON.stringify(SELECTORS.conversationTurn)};
+      const ASSISTANT_SELECTOR = ${JSON.stringify(SELECTORS.assistantMessage)};
+      const CONTENT_SELECTORS = ${JSON.stringify(SELECTORS.assistantContent.split(", "))};
+      const STOP_SELECTOR = ${JSON.stringify(SELECTORS.stopButton)};
+      const FINISHED_SELECTOR = ${JSON.stringify(SELECTORS.finishedActions)};
+
+      const toCandidate = (turnNode, messageRoot = null) => {
+        const resolvedMessageRoot = messageRoot || (turnNode.matches?.(ASSISTANT_SELECTOR)
+          ? turnNode
+          : turnNode.querySelector(ASSISTANT_SELECTOR));
+        const authorRoot = turnNode.matches?.('[data-message-author-role], [data-turn]')
+          ? turnNode
+          : turnNode.querySelector('[data-message-author-role], [data-turn]');
+        const searchRoot = resolvedMessageRoot || authorRoot || turnNode;
+        let contentRoot = null;
+
+        for (const selector of CONTENT_SELECTORS) {
+          const match = selector === '[dir="auto"]'
+            ? (searchRoot.matches?.(selector) ? searchRoot : null)
+            : (searchRoot.matches?.(selector) ? searchRoot : searchRoot.querySelector(selector));
+          if (match) {
+            contentRoot = match;
+            break;
+          }
+        }
+
+        const role =
+          resolvedMessageRoot?.getAttribute('data-message-author-role') ||
+          authorRoot?.getAttribute('data-message-author-role') ||
+          turnNode.getAttribute('data-message-author-role') ||
+          null;
+        const turn =
+          resolvedMessageRoot?.getAttribute('data-turn') ||
+          authorRoot?.getAttribute('data-turn') ||
+          turnNode.getAttribute('data-turn') ||
+          null;
+        const isAssistant =
+          role === 'assistant' ||
+          turn === 'assistant' ||
+          resolvedMessageRoot !== null;
+        const isUser = role === 'user' || turn === 'user';
+        const text = (contentRoot || turnNode).innerText || (contentRoot || turnNode).textContent || '';
+        const messageId =
+          resolvedMessageRoot?.getAttribute('data-message-id') ||
+          turnNode.getAttribute('data-message-id') ||
+          null;
+        const hasFinishedActions = Boolean(turnNode.querySelector(FINISHED_SELECTOR));
+
+        return {
+          role,
+          turn,
+          isAssistant,
+          isUser,
+          text,
+          messageId,
+          hasFinishedActions,
+        };
+      };
+
+      let candidates = Array.from(scope.querySelectorAll(CONVERSATION_SELECTOR)).map((turnNode) =>
+        toCandidate(turnNode)
+      );
+
+      if (candidates.length === 0) {
+        candidates = Array.from(scope.querySelectorAll(ASSISTANT_SELECTOR)).map((messageRoot) =>
+          toCandidate(messageRoot, messageRoot)
+        );
+      }
+
+      return {
+        candidates,
+        stopVisible: Boolean(scope.querySelector(STOP_SELECTOR)),
+      };
+    })()`,
+  );
+}
+
+async function waitForResponse(
+  cdp,
+  timeoutMs = 2700000,
+  baselineAssistant,
+  baselineAssistantCount,
+  signal,
+  promptEcho,
+) {
+  throwIfAborted(signal);
+  const deadline = Date.now() + timeoutMs;
+  let previousText = baselineAssistant?.text || "";
+  let stableCycles = 0;
+  let lastChangeAt = Date.now();
+
+  while (Date.now() < deadline) {
+    const rawSnapshot = await readChatGPTResponseSnapshot(cdp);
+    const snapshot = promptEcho ? scopeSnapshotToPrompt(rawSnapshot, promptEcho) : rawSnapshot;
+
+    if (!snapshot) {
+      await delay(400, signal);
+      continue;
+    }
+
+    const { latestAssistant, assistantCount, stopVisible } = normalizeResponseSnapshot(snapshot);
+    const currentText = latestAssistant?.text || "";
+    const hasNewAssistantContent = isNewAssistantContent(
+      latestAssistant,
+      baselineAssistant,
+      assistantCount,
+      baselineAssistantCount,
+    );
+
+    if (!hasNewAssistantContent) {
+      await delay(400, signal);
+      continue;
+    }
+
+    if (currentText !== previousText) {
+      previousText = currentText;
+      stableCycles = 0;
+      lastChangeAt = Date.now();
+    } else if (currentText) {
+      stableCycles++;
+    } else {
+      stableCycles = 0;
+      lastChangeAt = Date.now();
+    }
+
+    const stableMs = Date.now() - lastChangeAt;
+    const completionSnapshot = latestAssistant
+      ? { ...latestAssistant, stopVisible }
+      : { text: "", stopVisible, hasFinishedActions: false };
+
+    if (isChatGPTResponseComplete(completionSnapshot, stableCycles, stableMs)) {
+      return {
+        text: latestAssistant.text,
+        messageId: latestAssistant.messageId,
+        turnIndex: latestAssistant.turnIndex,
+      };
+    }
+
+    await delay(400, signal);
+  }
+
+  throw new Error("Response timeout");
+}
+
+module.exports = {
+  cleanChatGPTResponseText,
+  extractLatestAssistantSnapshot,
+  isChatGPTResponseComplete,
+  isNewAssistantContent,
+  matchesPromptEcho,
+  normalizePromptEcho,
+  normalizeResponseSnapshot,
+  readChatGPTResponseSnapshot,
+  waitForResponse,
+};

package/native/chatgpt-client-selection.cjs

@@ -0,0 +1,119 @@
+const CHATGPT_EFFORT_CHOICES = ["light", "standard", "extended", "heavy"];
+
+function normalizeChatGPTModelChoice(desiredModel) {
+  const normalized = String(desiredModel || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+
+  if (["instant", "gpt53"].includes(normalized)) return "instant";
+  if (["thinking", "gpt54thinking"].includes(normalized)) return "thinking";
+  if (["pro", "gpt54pro"].includes(normalized)) return "pro";
+
+  return normalized;
+}
+
+function normalizeChatGPTEffortChoice(desiredEffort) {
+  const normalized = String(desiredEffort || "").toLowerCase().trim();
+  return CHATGPT_EFFORT_CHOICES.includes(normalized) ? normalized : null;
+}
+
+function normalizedWords(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function modelCandidateMatches(item, targetModel) {
+  const values = [item?.label, item?.testId?.replace(/^model-switcher-/, "")].filter(Boolean);
+  return values.some((value) => {
+    if (normalizeChatGPTModelChoice(value) === targetModel) return true;
+    const variants = ["instant", "thinking", "pro"].filter((variant) =>
+      normalizedWords(value).includes(variant),
+    );
+    return variants.length === 1 && variants[0] === targetModel;
+  });
+}
+
+function effortCandidateMatches(item, targetEffort) {
+  const variants = new Set(
+    [item?.label, item?.testId]
+      .flatMap((value) => normalizedWords(value))
+      .filter((word) => CHATGPT_EFFORT_CHOICES.includes(word)),
+  );
+  return variants.size === 1 && variants.has(targetEffort);
+}
+
+function uniqueMatch(items, matches) {
+  if (!Array.isArray(items)) return null;
+  const candidates = items.filter(matches);
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
+function resolveChatGPTModelMenuOption(items, desiredModel) {
+  const targetModel = normalizeChatGPTModelChoice(desiredModel);
+  if (!targetModel) return null;
+  return uniqueMatch(
+    items,
+    (item) =>
+      item?.role === "menuitemradio" &&
+      typeof item?.testId === "string" &&
+      item.testId.startsWith("model-switcher-") &&
+      modelCandidateMatches(item, targetModel),
+  );
+}
+
+function verifyChatGPTModelSelection(items, desiredModel) {
+  const targetModel = normalizeChatGPTModelChoice(desiredModel);
+  if (!targetModel) return null;
+  return uniqueMatch(
+    items,
+    (item) =>
+      (typeof item?.label === "string" || typeof item?.testId === "string") &&
+      modelCandidateMatches(item, targetModel),
+  );
+}
+
+function resolveChatGPTEffortMenuOption(items, desiredEffort) {
+  const targetEffort = normalizeChatGPTEffortChoice(desiredEffort);
+  if (!targetEffort) return null;
+  return uniqueMatch(
+    items,
+    (item) =>
+      ["button", "menuitem", "menuitemradio"].includes(item?.role) &&
+      effortCandidateMatches(item, targetEffort),
+  );
+}
+
+function verifyChatGPTEffortSelection(items, desiredEffort) {
+  const targetEffort = normalizeChatGPTEffortChoice(desiredEffort);
+  if (!targetEffort) return null;
+  return uniqueMatch(
+    items,
+    (item) =>
+      (typeof item?.label === "string" || typeof item?.testId === "string") &&
+      effortCandidateMatches(item, targetEffort),
+  );
+}
+
+function boundedOptionLabels(items) {
+  if (!Array.isArray(items)) return [];
+  return items
+    .map((item) => String(item?.label || "").replace(/\s+/g, " ").trim().slice(0, 80))
+    .filter(Boolean)
+    .filter((label, index, labels) => labels.indexOf(label) === index)
+    .slice(0, 10);
+}
+
+module.exports = {
+  CHATGPT_EFFORT_CHOICES,
+  boundedOptionLabels,
+  normalizeChatGPTEffortChoice,
+  normalizeChatGPTModelChoice,
+  resolveChatGPTEffortMenuOption,
+  resolveChatGPTModelMenuOption,
+  verifyChatGPTEffortSelection,
+  verifyChatGPTModelSelection,
+};