surf-cli 2.13.1 → 2.14.0

package/native/chatgpt-client-selection.cjs

@@ -1,15 +1,25 @@
-const CHATGPT_EFFORT_CHOICES = ["light", "standard", "extended", "heavy"];
+const CHATGPT_EFFORT_CHOICES = ["light", "standard", "extended", "heavy", "pro"];
+const CHATGPT_MODEL_ALIASES = new Map([
+  ["instant", "instant"],
+  ["gpt53", "instant"],
+  ["thinking", "thinking"],
+  ["gpt54thinking", "thinking"],
+  ["pro", "gpt56sol"],
+  ["gpt54pro", "pro"],
+  ["55", "gpt55"],
+  ["gpt55", "gpt55"],
+  ["chatgpt55", "gpt55"],
+  ["56sol", "gpt56sol"],
+  ["gpt56sol", "gpt56sol"],
+  ["chatgpt56sol", "gpt56sol"],
+]);
 
 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;
+  return CHATGPT_MODEL_ALIASES.get(normalized) || normalized;
 }
 
 function normalizeChatGPTEffortChoice(desiredEffort) {
@@ -29,7 +39,9 @@ function normalizedWords(value) {
 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 normalizedValue = normalizeChatGPTModelChoice(value);
+    if (normalizedValue === targetModel) return true;
+    if (targetModel.startsWith("gpt") && normalizedValue.includes(targetModel)) return true;
     const variants = ["instant", "thinking", "pro"].filter((variant) =>
       normalizedWords(value).includes(variant),
     );
@@ -58,9 +70,7 @@ function resolveChatGPTModelMenuOption(items, desiredModel) {
   return uniqueMatch(
     items,
     (item) =>
-      item?.role === "menuitemradio" &&
-      typeof item?.testId === "string" &&
-      item.testId.startsWith("model-switcher-") &&
+      ["button", "menuitem", "menuitemradio", "radio"].includes(item?.role) &&
       modelCandidateMatches(item, targetModel),
   );
 }

package/native/chatgpt-client-ui.cjs

@@ -18,9 +18,10 @@ const SELECTORS = {
   loginCta: 'a[href*="/auth/login"], button',
   sendButton:
     'button[data-testid="send-button"], button[data-testid*="composer-send"], form button[type="submit"]',
-  modelButton: '[data-testid="model-switcher-dropdown-button"]',
+  modelButton:
+    '[data-testid="model-switcher-dropdown-button"], [data-testid="composer-footer-actions"] button[aria-haspopup="menu"], button.__composer-pill[aria-haspopup="menu"], .__composer-pill-composite button[aria-haspopup="menu"]',
   modelMenu: '[role="menu"][data-radix-menu-content]',
-  modelMenuItem: '[role="menuitemradio"][data-testid^="model-switcher-"]',
+  modelMenuItem: 'button, [role="menuitem"], [role="menuitemradio"]',
   menuItemPrimaryLabel: '.min-w-0 > span',
   effortButton:
     '[data-testid="composer-footer-actions"] button[aria-haspopup="menu"], button.__composer-pill[aria-haspopup="menu"], .__composer-pill-composite button[aria-haspopup="menu"]',
@@ -191,8 +192,8 @@ async function readPicker(cdp, kind, click = false) {
       ${buildClickDispatcher()}
       const kind = ${JSON.stringify(kind)};
       const nodes = Array.from(document.querySelectorAll(${JSON.stringify(selector)})).filter((node) => {
-        if (kind === 'model') return true;
         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');
       });
       const items = nodes.map((node) => {
@@ -224,13 +225,31 @@ async function readMenu(cdp, kind, allowSubmenu) {
       const choices = ${JSON.stringify(CHATGPT_EFFORT_CHOICES)};
       const containers = Array.from(document.querySelectorAll(${JSON.stringify(menuSelector)}));
       const normalize = (value) => String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
-      let menu = isModel ? containers[0] : containers.find((container) => {
+      let menu = isModel ? containers.find((container) => {
+        const labels = Array.from(container.querySelectorAll(${JSON.stringify(itemSelector)}))
+          .filter((item) => item.getAttribute?.('aria-haspopup') !== 'menu')
+          .map((item) => normalize((item.getAttribute?.('aria-label') || '') + ' ' + (item.textContent || '')));
+        return labels.some((label) => label.includes('gpt') || /^o[0-9]/.test(label));
+      }) : containers.find((container) => {
         const label = normalize(container.querySelector?.(${JSON.stringify(SELECTORS.effortMenuLabel)})?.textContent);
         const levels = new Set(Array.from(container.querySelectorAll(${JSON.stringify(itemSelector)}))
           .flatMap((item) => normalize(item.textContent).split(/\\s+/))
           .filter((word) => choices.includes(word)));
         return label.includes('thinking time') || levels.size >= 2;
       });
+      if (!menu && isModel && ${allowSubmenu}) {
+        for (const container of containers) {
+          const trigger = Array.from(container.querySelectorAll(${JSON.stringify(SELECTORS.effortSubmenuTrigger)}))
+            .find((item) => {
+              const label = normalize((item.getAttribute?.('aria-label') || '') + ' ' + (item.textContent || ''));
+              return label.includes('model') || label.includes('advanced');
+            });
+          if (trigger) {
+            dispatchClickSequence(trigger);
+            return { found: false, submenuOpened: true, items: [] };
+          }
+        }
+      }
       if (!menu && !isModel && ${allowSubmenu}) {
         for (const container of containers) {
           const trigger = Array.from(container.querySelectorAll(${JSON.stringify(SELECTORS.effortSubmenuTrigger)}))
@@ -299,7 +318,7 @@ async function clickMenuItem(cdp, kind, match) {
           .replace(/\\s+/g, ' ').trim().slice(0, 80);
         return label === expectedLabel;
       });
-      return matches.length === 1 ? dispatchClickSequence(matches[0]) : false;
+      return matches.length >= 1 ? dispatchClickSequence(matches[0]) : false;
     })()`,
   );
 }
@@ -317,8 +336,17 @@ async function selectModel(cdp, desiredModel, timeoutMs = 8000, signal) {
   await delay(200, signal);
   const state = await readPicker(cdp, "model");
   const verified = verifyChatGPTModelSelection(state?.items, desiredModel);
-  if (!verified) throw verificationError("model", desiredModel, menu.items);
-  return verified.displayLabel || verified.label;
+  if (verified) return verified.displayLabel || verified.label;
+
+  const reopened = await readPicker(cdp, "model", true);
+  if (reopened?.items?.length !== 1) throw verificationError("model", desiredModel, menu.items);
+  const readbackMenu = await waitForMenu(cdp, "model", timeoutMs, signal);
+  const readbackVerified = verifyChatGPTModelSelection(
+    readbackMenu.items.filter((item) => item.selected),
+    desiredModel,
+  );
+  if (!readbackVerified) throw verificationError("model", desiredModel, readbackMenu.items);
+  return readbackVerified.label;
 }
 
 async function selectEffort(cdp, desiredEffort, timeoutMs = 8000, signal) {

package/native/cli.cjs

@@ -270,7 +270,7 @@ const TOOLS = {
         args: ["query"],
         opts: {
           "with-page": "Include current page context",
-          model: "Model: gpt-4o, o1, etc.",
+          model: "Model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol, or a visible model label",
           file: "Attach file",
           timeout: "Timeout in seconds (default: 2700 = 45min)"
         },
@@ -278,7 +278,7 @@ const TOOLS = {
           { cmd: 'chatgpt "explain this code"', desc: "Basic query" },
           { cmd: 'chatgpt "summarize" --with-page', desc: "With page context" },
           { cmd: 'chatgpt "review" --file code.ts', desc: "With file" },
-          { cmd: 'chatgpt "analyze" --model gpt-4o', desc: "Specify model" },
+          { cmd: 'chatgpt "analyze" --model gpt-5.5', desc: "Specify model" },
         ]
       },
       "gemini": {

package/native/mcp-server.cjs

@@ -269,7 +269,7 @@ const TOOL_SCHEMAS = {
     desc: "Ask ChatGPT through the browser session",
     schema: {
       query: z.string().describe("Question or prompt"),
-      model: z.string().optional().describe("ChatGPT model"),
+      model: z.string().optional().describe("ChatGPT model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol, or a visible model label"),
       "with-page": z.boolean().optional().describe("Include current page context"),
       file: z.string().optional().describe("One attachment path"),
       timeout: z.number().optional().describe("Timeout in seconds")

package/native/oracle-cli.cjs

@@ -30,8 +30,8 @@ Commands:
 
 Ask/follow options:
   --files <glob>          Add context files (repeatable)
-  --model <model>         Select a ChatGPT model
-  --effort <effort>       Select reasoning effort
+  --model <model>         Select model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol
+  --effort <effort>       Select effort: light, standard, extended, heavy, pro
   --detach                Return after dispatch
   --allow-sensitive       Allow deny-listed context files
 

package/native/oracle-jobs.cjs

@@ -35,6 +35,24 @@ function codedError(code, message, details = {}) {
   return error;
 }
 
+function promptDigest(prompt) {
+  return `sha256:${crypto.createHash("sha256").update(prompt).digest("hex")}`;
+}
+
+function hydrateJobMetadata(job, root = getPrivateStateRoot()) {
+  const prompt = job.promptDigest ? null : readPrivateFile(path.join(jobDirectory(job.id, root), "request.md"), {
+    root,
+    encoding: "utf8",
+  });
+  const legacyModel = job.modelRequested === undefined && job.modelVerified === undefined;
+  return {
+    ...job,
+    modelRequested: job.modelRequested ?? (legacyModel && job.state === "created" ? job.model ?? null : null),
+    modelVerified: job.modelVerified ?? (legacyModel && job.state !== "created" ? job.model ?? null : null),
+    promptDigest: job.promptDigest ?? promptDigest(prompt),
+  };
+}
+
 function readJobs(root = getPrivateStateRoot()) {
   const base = oracleRoot(root);
   if (!fs.existsSync(base)) return [];
@@ -44,7 +62,8 @@ function readJobs(root = getPrivateStateRoot()) {
     .filter((id) => JOB_ID_PATTERN.test(id))
     .sort((a, b) => b.localeCompare(a))
     .map((id) => readPrivateJson(path.join(base, id, "job.json"), null, { root }))
-    .filter(Boolean);
+    .filter(Boolean)
+    .map((job) => hydrateJobMetadata(job, root));
 }
 
 function createJob({ prompt, contextManifest = {}, model = null, effortRequested = null, follow = null }) {
@@ -84,8 +103,11 @@ function createJob({ prompt, contextManifest = {}, model = null, effortRequested
       id,
       state: "created",
       model,
+      modelRequested: model,
+      modelVerified: null,
       effortRequested,
       effortVerified: null,
+      promptDigest: promptDigest(prompt),
       createdAt: now.toISOString(),
       dispatchedAt: null,
       awaitingAt: null,
@@ -110,7 +132,7 @@ function getJob(id) {
   const root = getPrivateStateRoot();
   const job = readPrivateJson(path.join(jobDirectory(id, root), "job.json"), null, { root });
   if (!job) throw codedError("not_found", `oracle job not found: ${id}`);
-  return job;
+  return hydrateJobMetadata(job, root);
 }
 
 function getResponse(id) {
@@ -141,7 +163,7 @@ function markDispatched(id, { tabId, promptEcho, modelVerified, effortVerified }
     dispatchedAt: new Date().toISOString(),
     tabId,
     ...(promptEcho ? { promptEcho } : {}),
-    ...(modelVerified ? { model: modelVerified } : {}),
+    ...(modelVerified ? { model: modelVerified, modelVerified } : {}),
     ...(effortVerified ? { effortVerified } : {}),
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",

package/pi-extension/surf.ts

@@ -1,4 +1,5 @@
 import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
 import { Type } from "typebox";
 
 const require = createRequire(import.meta.url);
@@ -26,6 +27,9 @@ const ORACLE_FINISHED_CHANNEL = "surf-oracle:finished";
 const BACKGROUND_WORK_PROTOCOL_VERSION = 1;
 const BACKGROUND_WORK_REGISTRY_KEY = "pi-subagents.background-work.v1";
 const BACKGROUND_WORK_MODULE_SPECIFIER = "pi-subagents/background-work";
+const EXTERNAL_JOB_PROVIDER_PROTOCOL_VERSION = 1;
+const EXTERNAL_JOB_PROVIDER_REGISTRY_KEY = "pi-subagents.external-job-providers.v1";
+const EXTERNAL_JOB_PROVIDER_MODULE_SPECIFIER = "pi-subagents/external-job-provider";
 
 type Pi = {
   registerTool(tool: Record<string, unknown>): void;
@@ -37,6 +41,20 @@ type SurfEndpoint = { kind?: string };
 
 type ToolResult = { content: Array<{ type: "text" | "image"; text?: string; data?: string; mimeType?: string }>; details?: unknown; isError?: boolean };
 
+type OracleJob = {
+  id: string;
+  state: string;
+  conversationUrl?: string | null;
+  model?: string | null;
+  modelRequested?: string | null;
+  modelVerified?: string | null;
+  effortRequested?: string | null;
+  effortVerified?: string | null;
+  promptDigest?: string | null;
+  response?: string;
+  error?: { code?: string; message?: string } | null;
+};
+
 type BackgroundWorkProvider = {
   name: string;
   wakeChannels: string[];
@@ -54,6 +72,46 @@ type BackgroundWorkRegistry = {
   providers: Map<string, BackgroundWorkProvider>;
 };
 
+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 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>;
+};
+
+type RegisterExternalJobProvider = (provider: OracleExternalJobProvider) => () => void;
+
+type ExternalJobProviderModule = {
+  registerExternalJobProvider?: unknown;
+};
+
+type ExternalJobProviderRegistry = {
+  version: typeof EXTERNAL_JOB_PROVIDER_PROTOCOL_VERSION;
+  providers: Map<string, OracleExternalJobProvider>;
+};
+
+type RememberOracleJob = (jobId: string) => boolean;
+type EmitOracleJob = (job: Pick<OracleExternalJob, "id" | "state">) => boolean;
+
 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
@@ -64,7 +122,12 @@ function textResult(value: unknown, isError = false): ToolResult {
 
 export 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);
+  if (error) {
+    return {
+      ...textResult(error.content?.map((item) => item.text ?? "").join("\n") || "Surf request failed", true),
+      details: error,
+    };
+  }
   const result = response.result as { content?: ToolResult["content"] } | undefined;
   if (!result?.content) return textResult(result ?? "OK");
   const text = result.content.find((item) => item.type === "text")?.text;
@@ -138,6 +201,33 @@ export function registerGlobalBackgroundProvider(provider: BackgroundWorkProvide
   };
 }
 
+export function registerGlobalExternalJobProvider(provider: OracleExternalJobProvider): () => void {
+  const key = Symbol.for(EXTERNAL_JOB_PROVIDER_REGISTRY_KEY);
+  const globalObject = globalThis as Record<PropertyKey, unknown>;
+  const existing = globalObject[key];
+  let registry: ExternalJobProviderRegistry;
+
+  if (existing === undefined) {
+    registry = { version: EXTERNAL_JOB_PROVIDER_PROTOCOL_VERSION, providers: new Map() };
+    globalObject[key] = registry;
+  } else if (
+    existing &&
+    typeof existing === "object" &&
+    !Array.isArray(existing) &&
+    (existing as Partial<ExternalJobProviderRegistry>).version === EXTERNAL_JOB_PROVIDER_PROTOCOL_VERSION &&
+    (existing as Partial<ExternalJobProviderRegistry>).providers instanceof Map
+  ) {
+    registry = existing as ExternalJobProviderRegistry;
+  } else {
+    throw new Error(`Unsupported external-job provider registry at Symbol.for("${EXTERNAL_JOB_PROVIDER_REGISTRY_KEY}").`);
+  }
+
+  registry.providers.set(provider.name, provider);
+  return () => {
+    if (registry.providers.get(provider.name) === provider) registry.providers.delete(provider.name);
+  };
+}
+
 export async function resolveBackgroundWorkRegister(
   loadModule: () => Promise<BackgroundWorkModule> = () => import(BACKGROUND_WORK_MODULE_SPECIFIER) as Promise<BackgroundWorkModule>,
 ): Promise<RegisterBackgroundWorkProvider> {
@@ -152,6 +242,137 @@ export async function resolveBackgroundWorkRegister(
   return registerGlobalBackgroundProvider;
 }
 
+export async function resolveExternalJobProviderRegister(
+  loadModule: () => Promise<ExternalJobProviderModule> = () => import(EXTERNAL_JOB_PROVIDER_MODULE_SPECIFIER) as Promise<ExternalJobProviderModule>,
+): Promise<RegisterExternalJobProvider> {
+  try {
+    const module = await loadModule();
+    if (typeof module.registerExternalJobProvider === "function") {
+      return module.registerExternalJobProvider as RegisterExternalJobProvider;
+    }
+  } catch {
+    // The provider bridge is optional until pi-subagents ships this consumer API.
+  }
+  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>;
+  if (typeof job.id !== "string" || typeof job.state !== "string") throw new Error("Surf oracle response did not include job id and state");
+  return job as OracleJob;
+}
+
+function oracleExternalJob(job: OracleJob): OracleExternalJob {
+  const resultText = typeof job.response === "string" ? job.response : undefined;
+  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") } }),
+    ...(failure ? { failure } : {}),
+  };
+}
+
+async function requestOracleJob(request: typeof requestSurf, tool: string, args: Record<string, unknown>) {
+  const result = await request(tool, args);
+  if (result.isError) {
+    const details = result.details as { code?: unknown; jobId?: unknown; message?: unknown } | undefined;
+    const message = typeof details?.message === "string"
+      ? details.message
+      : result.content.map((item) => item.text ?? "").join("\n") || "Surf oracle request failed";
+    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 });
+    throw error;
+  }
+  return oracleExternalJob(asOracleJob(result.details));
+}
+
+function emitFailedOracleJob(error: unknown, emitTerminal: EmitOracleJob) {
+  if (!error || typeof error !== "object" || !("jobId" in error) || typeof error.jobId !== "string") return;
+  emitTerminal({ id: error.jobId, state: "failed" });
+}
+
+export function createOracleExternalJobProvider(
+  sessionId: string,
+  jobIds: Set<string>,
+  request: typeof requestSurf = requestSurf,
+  rememberJob: RememberOracleJob = (jobId) => {
+    jobIds.add(jobId);
+    return true;
+  },
+  emitTerminal: EmitOracleJob = () => false,
+): 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");
+      const job = await requestOracleJob(request, "oracle.ask", {
+        prompt,
+        ...(typeof input.model === "string" ? { model: input.model } : {}),
+        ...(typeof input.effort === "string" ? { effort: input.effort } : {}),
+      });
+      rememberJob(job.id);
+      return { ...job, promptDigest: job.promptDigest ?? digestPrompt(prompt) };
+    },
+    status(id) {
+      return requestOracleJob(request, "oracle.status", { id });
+    },
+    result(id, input = {}) {
+      return requestOracleJob(request, "oracle.result", { id, ...(typeof input.timeout === "number" ? { timeout: input.timeout } : {}) })
+        .then((job) => {
+          emitTerminal({ id: job.id, state: job.state });
+          return job;
+        })
+        .catch((error) => {
+          emitFailedOracleJob(error, emitTerminal);
+          throw error;
+        });
+    },
+    reattach(id, input = {}) {
+      return requestOracleJob(request, "oracle.result", { id, ...(typeof input.timeout === "number" ? { timeout: input.timeout } : {}) })
+        .then((job) => {
+          rememberJob(job.id);
+          emitTerminal({ id: job.id, state: job.state });
+          return job;
+        })
+        .catch((error) => {
+          emitFailedOracleJob(error, emitTerminal);
+          throw error;
+        });
+    },
+    async follow(id, message, input = {}) {
+      if (!message.trim()) throw new Error("message required");
+      const job = await requestOracleJob(request, "oracle.ask", {
+        follow: id,
+        prompt: message,
+        ...(typeof input.model === "string" ? { model: input.model } : {}),
+        ...(typeof input.effort === "string" ? { effort: input.effort } : {}),
+      });
+      rememberJob(job.id);
+      return { ...job, promptDigest: job.promptDigest ?? digestPrompt(message) };
+    },
+  };
+}
+
 export function registerOptionalBackgroundProvider(sessionId: string, jobIds: Set<string>, listJobs: () => Array<{ id: string; state: string }>, register: RegisterBackgroundWorkProvider) {
   return register({
     name: "surf-oracle",
@@ -162,6 +383,17 @@ export function registerOptionalBackgroundProvider(sessionId: string, jobIds: Se
   });
 }
 
+export function registerOptionalExternalJobProvider(
+  sessionId: string,
+  jobIds: Set<string>,
+  register: RegisterExternalJobProvider,
+  request: typeof requestSurf = requestSurf,
+  rememberJob?: RememberOracleJob,
+  emitTerminal?: EmitOracleJob,
+) {
+  return register(createOracleExternalJobProvider(sessionId, jobIds, request, rememberJob, emitTerminal));
+}
+
 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);
@@ -219,7 +451,12 @@ export default function surfExtension(pi: Pi) {
     async execute(_id: string, args: Record<string, unknown>) {
       try {
         const result = await requestSurf("oracle.result", args);
-        emitOracleFinished(pi, result.details ?? { id: args.id, state: result.isError ? "failed" : undefined });
+        const errorDetails = result.details as { jobId?: unknown } | undefined;
+        if (result.isError) {
+          if (typeof errorDetails?.jobId === "string") emitOracleFinished(pi, { id: errorDetails.jobId, state: "failed" });
+        } else {
+          emitOracleFinished(pi, result.details);
+        }
         return result;
       } catch (error) {
         return textResult(error instanceof Error ? error.message : String(error), true);
@@ -249,12 +486,15 @@ export default function surfExtension(pi: Pi) {
   });
 
   let dispose: (() => void) | undefined;
+  let disposeExternal: (() => void) | undefined;
   pi.on("session_start", (_event, ctx) => {
     sessionGeneration++;
     const generation = sessionGeneration;
     sessionActive = false;
     dispose?.();
+    disposeExternal?.();
     dispose = undefined;
+    disposeExternal = undefined;
     oracleJobIds.clear();
 
     const session = ctx as { sessionManager?: { getSessionId?: () => string }; sessionId?: string };
@@ -262,7 +502,10 @@ export default function surfExtension(pi: Pi) {
     if (!sessionId) return;
     try {
       const jobs = require("../native/oracle-jobs.cjs") as { listJobs(): Array<{ id: string; state: string }> };
+      const rememberForGeneration = (jobId: string) => rememberOracleJobForSession(oracleJobIds, jobId, generation, sessionGeneration, sessionActive);
+      const emitFinished = (job: Pick<OracleExternalJob, "id" | "state">) => emitOracleFinished(pi, job);
       dispose = registerOptionalBackgroundProvider(sessionId, oracleJobIds, jobs.listJobs, registerGlobalBackgroundProvider);
+      disposeExternal = registerOptionalExternalJobProvider(sessionId, oracleJobIds, registerGlobalExternalJobProvider, requestSurf, rememberForGeneration, emitFinished);
       sessionActive = true;
       void resolveBackgroundWorkRegister().then((register) => {
         try {
@@ -278,6 +521,20 @@ export default function surfExtension(pi: Pi) {
           // Keep the already-registered fallback provider.
         }
       });
+      void resolveExternalJobProviderRegister().then((register) => {
+        try {
+          if (register === registerGlobalExternalJobProvider || generation !== sessionGeneration) return;
+          const nextDispose = registerOptionalExternalJobProvider(sessionId, oracleJobIds, register, requestSurf, rememberForGeneration, emitFinished);
+          if (generation !== sessionGeneration) {
+            nextDispose();
+            return;
+          }
+          disposeExternal?.();
+          disposeExternal = nextDispose;
+        } catch {
+          // Keep the already-registered fallback provider.
+        }
+      });
     } catch {
       // The Pi bridge is optional. Browser tools work without pi-subagents.
     }
@@ -286,7 +543,9 @@ export default function surfExtension(pi: Pi) {
     sessionGeneration++;
     sessionActive = false;
     dispose?.();
+    disposeExternal?.();
     dispose = undefined;
+    disposeExternal = undefined;
     oracleJobIds.clear();
   });
 }

package/skills/surf/SKILL.md

@@ -78,7 +78,7 @@ Query AI models using your browser's logged-in session. Must be logged into the
 ```bash
 surf chatgpt "explain this code"
 surf chatgpt "summarize" --with-page              # Include current page context
-surf chatgpt "review" --model gpt-4o              # Specify model
+surf chatgpt "review" --model gpt-5.5             # Specify model
 surf chatgpt "analyze" --file document.pdf        # With file attachment
 ```
 
@@ -91,7 +91,7 @@ For agent workflows, detach after dispatch and keep the returned `.id`:
 ```bash
 surf oracle ask "Review this change and identify release risks" \
   --files "src/**/*.ts" --files "package.json" \
-  --model pro --effort extended --detach --json
+  --model gpt-5.5 --effort pro --detach --json
 
 surf oracle status <job-id> --json
 surf oracle result <job-id> --json
@@ -101,7 +101,9 @@ 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`. Accepted `--effort` values are `light`, `standard`, `extended`, and `heavy`. 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 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 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.
 
 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.