surf-cli 2.15.0 → 2.15.2

package/native/aistudio-parser.cjs

@@ -327,8 +327,11 @@ function parseAiStudioGenerateContentText(rawText) {
   let parsed;
   try {
     parsed = JSON.parse(normalized);
-  } catch (e) {
-    throw new Error(`Invalid GenerateContent JSON (${normalized.length} chars): ${e.message}`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid GenerateContent JSON (${normalized.length} chars): ${message}`, {
+      cause: error,
+    });
   }
 
   const segments = [];

package/native/chatgpt-client-selection.cjs

@@ -4,7 +4,7 @@ const CHATGPT_MODEL_ALIASES = new Map([
   ["gpt53", "instant"],
   ["thinking", "thinking"],
   ["gpt54thinking", "thinking"],
-  ["pro", "gpt56sol"],
+  ["pro", "pro"],
   ["gpt54pro", "pro"],
   ["55", "gpt55"],
   ["gpt55", "gpt55"],

package/native/chatgpt-client-ui.cjs

@@ -191,11 +191,22 @@ async function readPicker(cdp, kind, click = false) {
     `(() => {
       ${buildClickDispatcher()}
       const kind = ${JSON.stringify(kind)};
-      const nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) => {
+      let nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) => {
         const value = ((node.getAttribute?.('aria-label') || '') + ' ' + (node.textContent || '')).toLowerCase();
-        if (kind === 'model') return value.includes('gpt') || value.includes('pro') || value.includes('thinking') || value.includes('instant');
-        return value.includes('thinking') || value.includes('pro');
+        if (kind !== 'model') return value.includes('thinking') || value.includes('pro');
+        return value.includes('gpt') || value.includes('thinking') || value.includes('instant');
       });
+      if (kind === 'model' && nodes.length === 0) {
+        nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) => {
+          const value = ((node.getAttribute?.('aria-label') || '') + ' ' + (node.textContent || '')).toLowerCase();
+          return value.includes('pro');
+        });
+      }
+      if (kind === 'model' && nodes.length === 0) {
+        nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) =>
+          node.getAttribute?.('aria-haspopup') === 'menu' || node.getAttribute?.('aria-expanded') !== null
+        );
+      }
       const items = nodes.map((node) => {
         const text = (node.textContent || '').replace(/\\s+/g, ' ').trim();
         const aria = (node.getAttribute?.('aria-label') || '').replace(/\\s+/g, ' ').trim();
@@ -329,6 +340,12 @@ async function selectModel(cdp, desiredModel, timeoutMs = 8000, signal) {
   if (picker?.items?.length !== 1) throw verificationError("model", desiredModel);
   await delay(300, signal);
   const menu = await waitForMenu(cdp, "model", timeoutMs, signal);
+  const currentAdvancedModel = verifyChatGPTModelSelection(
+    menu.items.filter((item) => /\bmodel\b/i.test(String(item?.label || ""))),
+    desiredModel,
+  );
+  if (currentAdvancedModel) return currentAdvancedModel.displayLabel || currentAdvancedModel.label;
+
   const match = resolveChatGPTModelMenuOption(menu.items, desiredModel);
   if (!match || !(await clickMenuItem(cdp, "model", match))) {
     throw verificationError("model", desiredModel, menu.items);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.15.0",
+  "version": "2.15.2",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -70,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": [

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));
@@ -330,8 +359,6 @@ 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");
@@ -343,47 +370,34 @@ export function createOracleExternalJobProvider(
         ...(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 model = oracleOption(input, "model");
-      const effort = oracleOption(input, "effort");
-      const job = await requestOracleJob(request, "oracle.ask", {
-        follow: id,
-        prompt: message,
-        ...(model !== undefined ? { model } : {}),
-        ...(effort !== undefined ? { effort } : {}),
-      });
-      rememberJob(job.id);
-      return { ...job, promptDigest: job.promptDigest ?? digestPrompt(message) };
-    },
   };
 }
 

package/skills/surf/SKILL.md

@@ -40,7 +40,7 @@ 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
@@ -112,11 +112,11 @@ surf oracle result <job-id> --wait --json
 
 `status` reads persisted state without touching Chrome. `result` attempts to harvest the answer and returns the job object with `response` once its state is `captured`. A Ctrl-C during waiting exits with status 130 and prints `Recover with: surf oracle result <id>`. Once the job is `awaiting`, the persisted ChatGPT conversation URL is its durable key, so `surf oracle result <id>` can recover after CLI exit, native-host restart, or Chrome restart by reopening that conversation.
 
-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.
+Treat Pro quota as scarce. Oracle never selects Pro effort implicitly; request it with `--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`. Use `--model gpt-5.6-sol --effort pro` for GPT-5.6 Sol with Pro effort. 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 honors `options.model` and `options.effort` for starts and follows, so `model: pro` selects ChatGPT GPT-5.6 Sol Pro web mode through the browser. 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: gpt-5.6-sol` plus `effort: pro` selects ChatGPT GPT-5.6 Sol with Pro effort 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`.
+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`, `options.model: gpt-5.6-sol`, and `options.effort: 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.