surf-cli 2.15.0 → 2.15.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.15.0",
+  "version": "2.15.1",
   "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
@@ -114,7 +114,7 @@ surf oracle result <job-id> --wait --json
 
 Treat Pro quota as scarce. Oracle never selects Pro implicitly; request it with `--model pro` or `--effort pro`. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`. Accepted `--effort` values are `light`, `standard`, `extended`, `heavy`, and `pro`. Requested model and effort selections are read back before submission, and an unverifiable selection fails with `model_verification_failed` instead of silently continuing. Capacity is one non-terminal oracle job. A `capacity` error includes the in-flight job ID; poll that job or wait for it to finish rather than submitting the same consult again.
 
-When loaded as a Pi extension, Surf also registers a `surf-oracle` external-job provider when the runtime exposes that bridge. The provider maps `start`, `status`, `result`, `reattach`, and `follow` to durable Surf Oracle jobs. It 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: pro` selects ChatGPT GPT-5.6 Sol Pro web mode through the browser. `reattach` only harvests an existing job by ID; it never submits the prompt again.
 
 When Surf is installed as a Pi package, it exposes an optional `gpt-pro` package agent for `pi-subagents`. That profile uses `runner.type: external-job`, provider `surf-oracle`, and `options.model: pro`. Surf remains useful without Pi or `pi-subagents`.