surf-cli 2.16.1 → 2.17.0

package/README.md

@@ -526,13 +526,13 @@ surf aistudio.build "game" --keep-open --timeout 600          # Keep tab open, 1
 
 #### 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. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`. Use `--model gpt-5.6-sol --effort pro` for GPT-5.6 Sol with Pro effort.
+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, one direct local attachment with `--file`, and verifies requested model and reasoning effort before submission. Add `--github` when the consult needs the ChatGPT Chat tab and connected GitHub tool. ChatGPT model aliases include `instant`, `thinking`, `pro`, `gpt-5.5`, and `gpt-5.6-sol`. Use `--model gpt-5.6-sol --effort pro` for GPT-5.6 Sol with Pro effort.
 
 ```bash
-surf oracle ask "review this change" --files "src/**/*.ts" --model gpt-5.5 --effort pro --detach --json
+surf oracle ask "review this change" --files "src/**/*.ts" --file ./design.md --model gpt-5.5 --effort pro --github --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
+surf oracle follow <job-id> "challenge that recommendation" --file ./follow-up.md --github --detach --json
 ```
 
 Only one oracle job can be in flight. Sensitive filename patterns and gitignored context are blocked unless `--allow-sensitive` is explicit.
@@ -996,7 +996,7 @@ 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.
 
-The extension also registers a `surf-oracle` external-job provider when a Pi runtime exposes that provider bridge. The provider implements pi-subagents' external-job contract: `start`, `status`, `result`, and `reattach` operations that return `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the durable conversation URL, the captured result text as `output`, and failure code and message when present. It reads `options.model` and `options.effort` for starts, so a Pi profile can request `model: gpt-5.6-sol` plus `effort: pro` and reach ChatGPT GPT-5.6 Sol with Pro effort through Surf. Capacity stays fail-closed: Surf returns the blocking job id instead of silently queueing a second ChatGPT job.
+The extension also registers a `surf-oracle` external-job provider when a Pi runtime exposes that provider bridge. The provider implements pi-subagents' external-job contract: `start`, `status`, `result`, and `reattach` operations that return `providerJobId`, a contract state (`queued`, `running`, `completed`, `failed`), the durable conversation URL, the captured result text as `output`, and failure code and message when present. It reads `options.model`, `options.effort`, `options.file`, and `options.github` for starts and follow-ups, so a Pi profile can request `model: gpt-5.6-sol` plus `effort: pro` and reach ChatGPT GPT-5.6 Sol with Pro effort through Surf, while `github: true` requires Chat mode and the connected GitHub tool. Capacity stays fail-closed: Surf returns the blocking job id instead of silently queueing a second ChatGPT job.
 
 When Surf is installed as a Pi package, it also 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`; the package agent only wires Surf's browser-backed model alias into Pi's agent picker.
 

package/native/chatgpt-client-ui.cjs

@@ -29,6 +29,8 @@ const SELECTORS = {
   effortMenuItem: 'button, [role="menuitem"], [role="menuitemradio"]',
   effortMenuLabel: '.__menu-label, [class*="menu-label"]',
   effortSubmenuTrigger: '[role="menuitem"][aria-haspopup="menu"], button[aria-haspopup="menu"]',
+  toolsButton:
+    'button[data-testid="composer-plus-btn"], button[aria-label="Add files and more"]',
   selectedMenuIndicator:
     '[aria-checked="true"], [aria-selected="true"], [data-selected="true"], [data-state="checked"], [data-state="selected"], [data-state="on"]',
   assistantMessage:
@@ -170,6 +172,315 @@ async function waitForPromptReady(cdp, timeoutMs = 30000, signal) {
   return false;
 }
 
+function uiError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+async function readChatTabState(cdp, signal) {
+  return evaluate(
+    cdp,
+    `(() => {
+      const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim().toLowerCase();
+      const visible = (node) => {
+        if (!node || node.hasAttribute?.('hidden') || node.getAttribute?.('aria-hidden') === 'true') return false;
+        const style = window.getComputedStyle?.(node);
+        if (style && (style.display === 'none' || style.visibility === 'hidden')) return false;
+        const rect = node.getBoundingClientRect?.();
+        return !rect || (rect.width > 0 && rect.height > 0);
+      };
+      const selected = (node) => node.getAttribute?.('aria-selected') === 'true' ||
+        node.getAttribute?.('aria-current') === 'page' ||
+        node.getAttribute?.('data-state') === 'active' ||
+        node.getAttribute?.('data-state') === 'selected' ||
+        node.getAttribute?.('data-active') === 'true' ||
+        /\\b(active|selected)\\b/i.test(String(node.className || ''));
+      const labelFor = (node) => [
+        node.innerText || node.textContent || '',
+        node.getAttribute?.('aria-label') || '',
+        node.getAttribute?.('title') || '',
+      ].join(' ').replace(/\\s+/g, ' ').trim();
+      const matchesName = (node, name) => [
+        node.innerText || node.textContent || '',
+        node.getAttribute?.('aria-label') || '',
+        node.getAttribute?.('title') || '',
+      ].some((value) => {
+        const normalized = normalize(value);
+        return normalized === name || normalized === name + ' tab' || normalized === 'switch to ' + name;
+      });
+      const nodes = Array.from(new Set([
+        ...document.querySelectorAll('[role="tab"], button, a'),
+      ])).filter(visible);
+      const details = (node) => ({ label: labelFor(node).slice(0, 120), selected: selected(node) });
+      const matches = (name) => nodes
+        .filter((node) => matchesName(node, name))
+        .map(details);
+      return { chat: matches('chat'), work: matches('work') };
+    })()`,
+    signal,
+  );
+}
+
+async function selectChatTab(cdp, timeoutMs = 8000, signal) {
+  throwIfAborted(signal);
+  const read = () => readChatTabState(cdp, signal);
+  let state = await read();
+  if (state?.chat?.length === 1 && state.chat[0].selected) return state.chat[0].label;
+  if (state?.chat?.length === 0 && state?.work?.length > 0) {
+    throw uiError(
+      "chat_mode_unavailable",
+      "ChatGPT only exposes Work mode; the Chat tab is required for Oracle",
+    );
+  }
+  if (state?.chat?.length !== 1) {
+    throw uiError(
+      "chat_mode_selector_drift",
+      state?.chat?.length
+        ? "ChatGPT Chat tab selector drift: Chat tab is ambiguous"
+        : "ChatGPT Chat tab selector drift: Chat tab was not found",
+    );
+  }
+
+  const clicked = await evaluate(
+    cdp,
+    `(() => {
+      ${buildClickDispatcher()}
+      const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim().toLowerCase();
+      const matchesName = (node) => [
+        node.innerText || node.textContent || '',
+        node.getAttribute?.('aria-label') || '',
+        node.getAttribute?.('title') || '',
+      ].some((value) => {
+        const normalized = normalize(value);
+        return normalized === 'chat' || normalized === 'chat tab' || normalized === 'switch to chat';
+      });
+      const nodes = Array.from(new Set([
+        ...document.querySelectorAll('[role="tab"], button, a'),
+      ])).filter(matchesName);
+      return nodes.length === 1 ? dispatchClickSequence(nodes[0]) : false;
+    })()`,
+    signal,
+  );
+  if (!clicked) {
+    throw uiError("chat_mode_selector_drift", "ChatGPT Chat tab selector drift: Chat tab could not be clicked");
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await delay(100, signal);
+    state = await read();
+    if (state?.chat?.length === 1 && state.chat[0].selected) return state.chat[0].label;
+    if (state?.chat?.length === 0 && state?.work?.length > 0) {
+      throw uiError(
+        "chat_mode_unavailable",
+        "ChatGPT only exposes Work mode; the Chat tab is required for Oracle",
+      );
+    }
+  }
+  throw uiError("chat_mode_selection_failed", "ChatGPT Chat tab could not be selected before timeout");
+}
+
+async function readGitHubToolState(cdp, signal) {
+  return evaluate(
+    cdp,
+    `(() => {
+      const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim().toLowerCase();
+      const visible = (node) => {
+        if (!node || node.hasAttribute?.('hidden') || node.getAttribute?.('aria-hidden') === 'true') return false;
+        const style = window.getComputedStyle?.(node);
+        if (style && (style.display === 'none' || style.visibility === 'hidden')) return false;
+        const rect = node.getBoundingClientRect?.();
+        return !rect || (rect.width > 0 && rect.height > 0);
+      };
+      const labelFor = (node) => [
+        node.innerText || node.textContent || '',
+        node.getAttribute?.('aria-label') || '',
+        node.getAttribute?.('title') || '',
+        node.getAttribute?.('data-testid') || '',
+        node.getAttribute?.('data-tool') || '',
+      ].join(' ').replace(/\\s+/g, ' ').trim();
+      const selected = (node, label) => node.getAttribute?.('aria-checked') === 'true' ||
+        node.getAttribute?.('aria-selected') === 'true' ||
+        node.getAttribute?.('aria-pressed') === 'true' ||
+        node.getAttribute?.('data-selected') === 'true' ||
+        node.getAttribute?.('data-active') === 'true' ||
+        ['checked', 'selected', 'on', 'active'].includes(normalize(node.getAttribute?.('data-state'))) ||
+        /\\b(active|selected)\\b/i.test(label);
+      const controls = Array.from(new Set([
+        ...document.querySelectorAll('[role="menuitem"], [role="option"], [role="button"], button, [data-testid*="github" i], [data-tool*="github" i], [aria-label*="github" i], [title*="github" i]'),
+      ])).filter(visible);
+      const github = controls.filter((node) => normalize(labelFor(node)).includes('github'));
+      return {
+        controls: github.map((node) => {
+          const label = labelFor(node).slice(0, 160);
+          return {
+            label,
+            role: node.getAttribute?.('role') || (node.tagName === 'BUTTON' ? 'button' : null),
+            selected: selected(node, label),
+            disconnected: /\\b(disconnected|not connected|connect|authorize|sign in)\\b/i.test(label),
+            testId: node.getAttribute?.('data-testid') || null,
+          };
+        }),
+      };
+    })()`,
+    signal,
+  );
+}
+
+async function openToolsMenu(cdp, signal) {
+  return evaluate(
+    cdp,
+    `(() => {
+      ${buildClickDispatcher()}
+      const selectors = ${JSON.stringify(SELECTORS.toolsButton.split(", "))};
+      const visible = (node) => {
+        if (!node || node.hasAttribute?.('hidden') || node.getAttribute?.('aria-hidden') === 'true') return false;
+        const style = window.getComputedStyle?.(node);
+        return !style || (style.display !== 'none' && style.visibility !== 'hidden');
+      };
+      for (const selector of selectors) {
+        const node = Array.from(document.querySelectorAll(selector)).find(visible);
+        if (node) return dispatchClickSequence(node);
+      }
+      return false;
+    })()`,
+    signal,
+  );
+}
+
+async function clickGitHubTool(cdp, signal) {
+  return evaluate(
+    cdp,
+    `(() => {
+      ${buildClickDispatcher()}
+      const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim().toLowerCase();
+      const labelFor = (node) => [
+        node.innerText || node.textContent || '',
+        node.getAttribute?.('aria-label') || '',
+        node.getAttribute?.('title') || '',
+        node.getAttribute?.('data-testid') || '',
+        node.getAttribute?.('data-tool') || '',
+      ].join(' ').replace(/\\s+/g, ' ').trim();
+      const controls = Array.from(new Set([
+        ...document.querySelectorAll('[role="menuitem"], [role="option"], [role="button"], button, [data-testid*="github" i], [data-tool*="github" i], [aria-label*="github" i], [title*="github" i]'),
+      ])).filter((node) => normalize(labelFor(node)).includes('github'));
+      const menuItems = controls.filter((node) => ['menuitem', 'option'].includes(node.getAttribute?.('role')));
+      const candidates = menuItems.length > 0 ? menuItems : controls;
+      return candidates.length === 1 ? dispatchClickSequence(candidates[0]) : false;
+    })()`,
+    signal,
+  );
+}
+
+async function selectGitHubTool(cdp, timeoutMs = 10000, signal) {
+  throwIfAborted(signal);
+  let state = await readGitHubToolState(cdp, signal);
+  const findConnected = () => state?.controls?.filter((control) => !control.disconnected) || [];
+  if (state?.controls?.some((control) => control.disconnected)) {
+    throw uiError(
+      "github_tool_disconnected",
+      "ChatGPT GitHub tool is missing or disconnected; connect GitHub before running Oracle with --github",
+    );
+  }
+  if (findConnected().length === 1 && state.controls[0].selected) return state.controls[0].label;
+  if (state?.controls?.length > 1) {
+    throw uiError("github_tool_selector_drift", "ChatGPT GitHub tool selector drift: GitHub tool is ambiguous");
+  }
+  if (state?.controls?.length === 0) {
+    const opened = await openToolsMenu(cdp, signal);
+    if (!opened) {
+      throw uiError("github_tool_selector_drift", "ChatGPT tools selector drift: tools menu could not be opened");
+    }
+    const menuDeadline = Date.now() + timeoutMs;
+    while (Date.now() < menuDeadline) {
+      await delay(100, signal);
+      state = await readGitHubToolState(cdp, signal);
+      if (state?.controls?.some((control) => control.disconnected)) {
+        throw uiError(
+          "github_tool_disconnected",
+          "ChatGPT GitHub tool is missing or disconnected; connect GitHub before running Oracle with --github",
+        );
+      }
+      if (state?.controls?.length > 0) break;
+    }
+  }
+  if (!state?.controls?.length) {
+    throw uiError("github_tool_missing", "ChatGPT GitHub tool is not available in the tools menu");
+  }
+  if (state.controls.length === 1 && state.controls[0].selected) return state.controls[0].label;
+  if (state.controls.length !== 1 || !(await clickGitHubTool(cdp, signal))) {
+    throw uiError("github_tool_selector_drift", "ChatGPT GitHub tool selector drift: GitHub tool could not be selected");
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await delay(100, signal);
+    state = await readGitHubToolState(cdp, signal);
+    if (state?.controls?.some((control) => control.disconnected)) {
+      throw uiError(
+        "github_tool_disconnected",
+        "ChatGPT GitHub tool became disconnected while selecting it",
+      );
+    }
+    if (state?.controls?.length === 1 && state.controls[0].selected) return state.controls[0].label;
+  }
+  throw uiError("github_tool_selection_failed", "ChatGPT GitHub tool could not be verified after selection");
+}
+
+async function waitForChatGPTAttachment(cdp, filePaths, timeoutMs = 30000, signal) {
+  const expectedNames = (Array.isArray(filePaths) ? filePaths : [filePaths])
+    .map((filePath) => String(filePath).split(/[\\/]/).pop().toLowerCase());
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const state = await evaluate(
+      cdp,
+      `(() => {
+        const scope = document.querySelector('form') || document.querySelector('[data-testid*="composer"]') || document;
+        const text = (scope.innerText || scope.textContent || '').replace(/\\s+/g, ' ').trim();
+        const inputs = Array.from(scope.querySelectorAll?.('input[type="file"]') || []);
+        const fileCount = inputs.reduce((count, input) => count + (input.files?.length || 0), 0);
+        const attachmentNodes = Array.from(scope.querySelectorAll?.('[data-testid*="attachment" i], [data-testid*="file" i], [aria-label*="remove attachment" i], [aria-label*="remove file" i]') || [])
+          .filter((node) => node.tagName !== 'INPUT' || node.type !== 'file');
+        const hasAttachmentNode = attachmentNodes.some((node) => {
+          const rect = node.getBoundingClientRect?.();
+          return !rect || (rect.width > 0 && rect.height > 0);
+        });
+        const attachmentLabels = attachmentNodes
+          .filter((node) => {
+            const rect = node.getBoundingClientRect?.();
+            return !rect || (rect.width > 0 && rect.height > 0);
+          })
+          .map((node) => [
+            node.innerText || node.textContent || '',
+            node.getAttribute?.('aria-label') || '',
+            node.getAttribute?.('title') || '',
+          ].join(' ').replace(/\\s+/g, ' ').trim().toLowerCase())
+          .filter(Boolean);
+        const processingError = /\\b(upload failed|failed to upload|couldn.t upload|unsupported file|file too large|processing failed|error processing)\\b/i.test(text);
+        return { fileCount, hasAttachmentNode, attachmentLabels, processingError, text: text.slice(-300) };
+      })()`,
+      signal,
+    );
+    if (state?.processingError) {
+      throw uiError(
+        "attachment_processing",
+        `ChatGPT attachment processing failed${state.text ? `: ${state.text}` : ""}`,
+      );
+    }
+    const attachmentLabels = Array.isArray(state?.attachmentLabels) ? state.attachmentLabels : [];
+    const hasExpectedName = expectedNames.every((expected) =>
+      attachmentLabels.some((label) => label.includes(expected)),
+    );
+    const hasPotentialFilename = attachmentLabels.some((label) => /(?:^|\\s)[\\w.-]+\\.[a-z0-9]{1,8}(?:$|\\s|[)\\]])/i.test(label));
+    if (state?.hasAttachmentNode && (hasExpectedName || !hasPotentialFilename)) return true;
+    await delay(250, signal);
+  }
+  throw uiError(
+    "attachment_processing",
+    `ChatGPT attachment processing did not complete for ${expectedNames.filter(Boolean).join(", ") || "the selected file"}`,
+  );
+}
+
 function verificationError(kind, requested, items = [], invalid = false) {
   const safeRequested = String(requested || "").replace(/\s+/g, " ").trim().slice(0, 80);
   const available = boundedOptionLabels(items);
@@ -552,10 +863,13 @@ module.exports = {
   normalizeChatGPTModelChoice,
   resolveChatGPTEffortMenuOption,
   resolveChatGPTModelMenuOption,
+  selectChatTab,
   selectEffort,
+  selectGitHubTool,
   selectModel,
   verifyChatGPTEffortSelection,
   verifyChatGPTModelSelection,
+  waitForChatGPTAttachment,
   typePrompt,
   waitForPageLoad,
   waitForPromptReady,

package/native/chatgpt-client.cjs

@@ -11,10 +11,13 @@ const {
   resolveChatGPTEffortMenuOption,
   resolveChatGPTModelMenuOption,
   selectEffort,
+  selectChatTab,
+  selectGitHubTool,
   selectModel,
   typePrompt,
   verifyChatGPTEffortSelection,
   verifyChatGPTModelSelection,
+  waitForChatGPTAttachment,
   waitForPageLoad,
   waitForPromptReady,
 } = require("./chatgpt-client-ui.cjs");
@@ -32,6 +35,12 @@ const {
 
 const CHATGPT_URL = "https://chatgpt.com/";
 const RESPONSE_STARTED_AT = Symbol("responseStartedAt");
+const ATTACHMENT_ERROR_CODES = new Set([
+  "attachment_chooser_interception",
+  "attachment_file_access",
+  "attachment_processing",
+  "attachment_selector_drift",
+]);
 
 function hasRequiredCookies(cookies) {
   if (!cookies || !Array.isArray(cookies)) return false;
@@ -93,6 +102,7 @@ async function dispatch(options) {
     cdpEvaluate,
     cdpCommand,
     uploadFile,
+    github = false,
     beforeSubmit,
     afterSubmit,
     startUrl,
@@ -141,6 +151,12 @@ async function dispatch(options) {
       throw codedError("ChatGPT login required", "auth");
     }
     log("Login verified");
+    if (github) {
+      await selectChatTab(cdp, 10000, signal);
+      log("Verified Chat tab");
+      await selectGitHubTool(cdp, 10000, signal);
+      log("Verified GitHub tool");
+    }
     const promptReady = await waitForPromptReady(cdp, 30000, signal);
     if (!promptReady) {
       throw new Error("Prompt textarea not ready");
@@ -154,22 +170,46 @@ async function dispatch(options) {
     }
     if (file) {
       if (!uploadFile) {
-        throw new Error(
+        throw codedError(
           "ChatGPT file upload unavailable: native host did not provide upload callback",
+          "attachment_chooser_interception",
         );
       }
       const files = Array.isArray(file) ? file : [file];
       const absFiles = files.map((filePath) => path.resolve(process.cwd(), filePath));
       log(`Uploading ${absFiles.length} file(s) to ChatGPT...`);
-      const uploadResult = await guardedUploadFile(tabId, absFiles);
+      let uploadResult;
+      try {
+        uploadResult = await guardedUploadFile(tabId, absFiles);
+      } catch (error) {
+        throw classifyError(
+          error,
+          "attachment_chooser_interception",
+          ["attachment_file_access", "attachment_processing", "attachment_selector_drift", "attachment_chooser_interception"],
+        );
+      }
       if (uploadResult?.error) {
-        throw new Error(`ChatGPT file upload failed: ${uploadResult.error}`);
+        const uploadCode = ATTACHMENT_ERROR_CODES.has(uploadResult.errorCode)
+          ? uploadResult.errorCode
+          : "attachment_chooser_interception";
+        throw codedError(
+          `ChatGPT file upload failed: ${uploadResult.error}`,
+          uploadCode,
+        );
       }
       if (!uploadResult?.success) {
-        throw new Error("ChatGPT file upload failed: upload did not report success");
+        throw codedError(
+          "ChatGPT attachment processing failed: upload did not report success",
+          "attachment_processing",
+        );
       }
       log("File uploaded, waiting for ChatGPT attachment processing...");
       await delay(1500, signal);
+      try {
+        await waitForChatGPTAttachment(cdp, absFiles, 30000, signal);
+      } catch (error) {
+        throw classifyError(error, "attachment_processing", ["attachment_processing"]);
+      }
     }
     await typePrompt(cdp, inputCdp, prompt, signal);
     log("Prompt typed");
@@ -201,6 +241,17 @@ async function dispatch(options) {
     throw classifyError(error, "dispatch_failed", [
       "auth",
       "cloudflare",
+      "attachment_chooser_interception",
+      "attachment_file_access",
+      "attachment_processing",
+      "attachment_selector_drift",
+      "chat_mode_selection_failed",
+      "chat_mode_selector_drift",
+      "chat_mode_unavailable",
+      "github_tool_disconnected",
+      "github_tool_missing",
+      "github_tool_selection_failed",
+      "github_tool_selector_drift",
       "model_verification_failed",
     ]);
   }
@@ -353,5 +404,8 @@ module.exports = {
   extractConversationUrl,
   verifyChatGPTEffortSelection,
   verifyChatGPTModelSelection,
+  selectChatTab,
+  selectGitHubTool,
+  waitForChatGPTAttachment,
   CHATGPT_URL,
 };

package/native/file-transfer.cjs

@@ -270,6 +270,11 @@ function validateLocalToolPaths(tool, args = {}) {
       ? args.files.map((value) => normalize("files", value))
       : String(args.files).split(",").map((value) => normalize("files", value.trim())).join(",");
   }
+  if (tool === "oracle.ask" && args.file !== undefined) {
+    normalized.file = Array.isArray(args.file)
+      ? args.file.map((value) => normalize("file", value))
+      : normalize("file", args.file);
+  }
   if (tool === "screenshot") {
     if (args.savePath !== undefined && args.output !== undefined) throw transferError("screenshot accepts only one output path", "SURF_PATH_FIELD");
     for (const field of ["savePath", "output"]) if (args[field] !== undefined) normalized[field] = normalize(field, args[field]);

package/native/oracle-cli.cjs

@@ -1,16 +1,30 @@
 const { openClientTransport } = require("./client-transport.cjs");
 const { resolveRequestDeadlineMs } = require("./host-sessions.cjs");
 const { assembleContext } = require("./oracle-context.cjs");
+const fs = require("fs");
+const path = require("path");
 
 const RESULT_TIMEOUT_SECONDS = 20;
 const POLL_DELAYS_MS = [5000, 10000, 20000, 40000, 60000];
 const ORACLE_ERROR_CODES = new Set([
   "auth",
+  "attachment_chooser_interception",
+  "attachment_file_access",
+  "attachment_processing",
+  "attachment_selector_drift",
   "capacity",
+  "chat_mode_selection_failed",
+  "chat_mode_selector_drift",
+  "chat_mode_unavailable",
   "cloudflare",
   "context_incomplete",
   "dispatch_failed",
+  "github_tool_disconnected",
+  "github_tool_missing",
+  "github_tool_selection_failed",
+  "github_tool_selector_drift",
   "harvest_failed",
+  "invalid_request",
   "invalid_transition",
   "model_verification_failed",
   "not_found",
@@ -30,8 +44,10 @@ Commands:
 
 Ask/follow options:
   --files <glob>          Add context files (repeatable)
+  --file <path>           Attach one local file
   --model <model>         Select model: instant, thinking, pro, gpt-5.5, gpt-5.6-sol
   --effort <effort>       Select effort: light, standard, extended, heavy, pro
+  --github                Require the ChatGPT Chat tab and GitHub tool
   --detach                Return after dispatch
   --allow-sensitive       Allow deny-listed context files
 
@@ -56,11 +72,12 @@ function requireOptionValue(argv, index, name) {
 
 function parseOptions(argv) {
   const positional = [];
-  const options = { files: [] };
-  const valueOptions = new Set(["files", "model", "effort"]);
+  const options = { files: [], file: [] };
+  const valueOptions = new Set(["files", "file", "model", "effort"]);
   const booleanOptions = new Set([
     "allow-sensitive",
     "detach",
+    "github",
     "json",
     "no-lock",
     "wait",
@@ -75,7 +92,7 @@ function parseOptions(argv) {
     const name = value.slice(2);
     if (valueOptions.has(name)) {
       const optionValue = requireOptionValue(argv, index, name);
-      if (name === "files") options.files.push(optionValue);
+      if (name === "files" || name === "file") options[name].push(optionValue);
       else options[name] = optionValue;
       index += 1;
     } else if (booleanOptions.has(name)) {
@@ -94,14 +111,16 @@ function assertAllowedOptions(command, options) {
     "allow-sensitive",
     "detach",
     "effort",
+    "file",
     "files",
+    "github",
     "model",
   ]);
   const allowed = command === "ask" || command === "follow"
     ? ask
     : command === "result" ? new Set([...common, "wait"]) : common;
   for (const [name, value] of Object.entries(options)) {
-    if (name === "files" && value.length === 0) continue;
+    if ((name === "files" || name === "file") && value.length === 0) continue;
     if (value !== undefined && !allowed.has(name)) {
       throw codedError("invalid_transition", `--${name} is not supported by oracle ${command}`);
     }
@@ -131,8 +150,12 @@ function parseOracleCommand(argv) {
       command,
       prompt,
       files: parsed.options.files,
+      ...(parsed.options.file.length > 0
+        ? { file: parsed.options.file.length === 1 ? parsed.options.file[0] : parsed.options.file }
+        : {}),
       model: parsed.options.model,
       effort: parsed.options.effort,
+      github: parsed.options.github === true,
       detach: parsed.options.detach === true,
       allowSensitive: parsed.options["allow-sensitive"] === true,
       json,
@@ -151,8 +174,12 @@ function parseOracleCommand(argv) {
       id,
       prompt,
       files: parsed.options.files,
+      ...(parsed.options.file.length > 0
+        ? { file: parsed.options.file.length === 1 ? parsed.options.file[0] : parsed.options.file }
+        : {}),
       model: parsed.options.model,
       effort: parsed.options.effort,
+      github: parsed.options.github === true,
       detach: parsed.options.detach === true,
       allowSensitive: parsed.options["allow-sensitive"] === true,
       json,
@@ -191,12 +218,44 @@ function composeAskRequest(spec, context) {
     prompt,
     ...(spec.model ? { model: spec.model } : {}),
     ...(spec.effort ? { effort: spec.effort } : {}),
+    ...(spec.file ? { file: spec.file } : {}),
+    ...(spec.github ? { github: true } : {}),
     ...(context ? { contextManifest: context.manifest } : {}),
     ...(context?.bundlePath ? { bundlePath: context.bundlePath } : {}),
     ...(spec.id ? { follow: spec.id } : {}),
   };
 }
 
+async function resolveOracleAttachment(value, cwd = process.cwd()) {
+  const values = value === undefined || value === null
+    ? []
+    : Array.isArray(value) ? value : [value];
+  if (values.length > 1) {
+    throw codedError(
+      "attachment_file_access",
+      "Oracle supports one explicit local attachment; provide a single --file path",
+    );
+  }
+  if (values.length === 0) return undefined;
+  const requested = values[0];
+  if (typeof requested !== "string" || !requested.trim()) {
+    throw codedError("attachment_file_access", "Oracle attachment file access failed: --file must be a path");
+  }
+  const resolved = path.resolve(cwd, requested);
+  try {
+    const stats = await fs.promises.stat(resolved);
+    if (!stats.isFile()) throw new Error("not a regular file");
+    await fs.promises.access(resolved, fs.constants.R_OK);
+  } catch (error) {
+    throw codedError(
+      "attachment_file_access",
+      `Oracle attachment file access failed for ${resolved}: ${error?.message || error}`,
+      { path: resolved },
+    );
+  }
+  return resolved;
+}
+
 function unwrapResponse(response) {
   if (response?.error) {
     const message = response.error.message
@@ -389,6 +448,7 @@ async function handleOracleCli(argv, {
     }
   }
 
+  const attachment = await resolveOracleAttachment(spec.file, cwd);
   const context = spec.files.length > 0
     ? await assembleContext({
       files: spec.files,
@@ -396,7 +456,7 @@ async function handleOracleCli(argv, {
       allowSensitive: spec.allowSensitive,
     })
     : null;
-  const request = composeAskRequest(spec, context);
+  const request = composeAskRequest({ ...spec, ...(attachment ? { file: attachment } : {}) }, context);
   const dispatchInterrupt = () => {
     stderr.write(
       "Interrupted during dispatch. A job may already have been created. Run surf oracle status or surf oracle list to find it.\n",
@@ -430,5 +490,6 @@ module.exports = {
   formatOracleOutput,
   handleOracleCli,
   parseOracleCommand,
+  resolveOracleAttachment,
   shapeOracleError,
 };

package/native/oracle-host.cjs

@@ -1,3 +1,5 @@
+const fs = require("fs");
+const path = require("path");
 const chatgptClient = require("./chatgpt-client.cjs");
 const oracleJobs = require("./oracle-jobs.cjs");
 
@@ -23,6 +25,39 @@ function withJobId(error, jobId, fallbackCode) {
   return result;
 }
 
+async function resolveOracleAttachments(args) {
+  const explicit = args?.file === undefined || args?.file === null
+    ? []
+    : Array.isArray(args.file) ? args.file : [args.file];
+  if (explicit.length > 1) {
+    throw codedError(
+      "attachment_file_access",
+      "Oracle supports one explicit local attachment; provide a single --file path",
+    );
+  }
+  const requested = [...explicit, ...(args?.bundlePath ? [args.bundlePath] : [])];
+  const resolved = [];
+  for (const filePath of requested) {
+    if (typeof filePath !== "string" || !filePath.trim()) {
+      throw codedError("attachment_file_access", "Oracle attachment file access failed: file path is required");
+    }
+    const absolutePath = path.resolve(filePath);
+    try {
+      const stats = await fs.promises.stat(absolutePath);
+      if (!stats.isFile()) throw new Error("not a regular file");
+      await fs.promises.access(absolutePath, fs.constants.R_OK);
+    } catch (error) {
+      throw codedError(
+        "attachment_file_access",
+        `Oracle attachment file access failed for ${absolutePath}: ${error?.message || error}`,
+        { path: absolutePath },
+      );
+    }
+    resolved.push(absolutePath);
+  }
+  return resolved;
+}
+
 function createOracleHost({ queueAiRequest, requestCallExtension, buildProviderUploadMessage, log }) {
   const closeTab = (request, tabId) => requestCallExtension(
     request,
@@ -65,6 +100,7 @@ function createOracleHost({ queueAiRequest, requestCallExtension, buildProviderU
   async function ask(request, args) {
     assertLocalOracleRequest(request);
     const model = args.model ? chatgptClient.normalizeChatGPTModelChoice(args.model) : null;
+    const explicitAttachmentPaths = await resolveOracleAttachments({ ...args, bundlePath: undefined });
     const created = oracleJobs.createJob({
       prompt: args.prompt,
       contextManifest: args.contextManifest,
@@ -72,11 +108,16 @@ function createOracleHost({ queueAiRequest, requestCallExtension, buildProviderU
       effortRequested: args.effort ?? null,
       follow: args.follow ?? null,
       requestId: args.requestId ?? null,
+      attachmentPaths: explicitAttachmentPaths,
+      github: args.github === true,
     });
     if (created.requestDeduped) return oracleJobs.getJob(created.id);
     let createdTabId = null;
 
     try {
+      const attachmentPaths = args?.bundlePath
+        ? [...explicitAttachmentPaths, ...(await resolveOracleAttachments({ bundlePath: args.bundlePath }))]
+        : explicitAttachmentPaths;
       let parent = null;
       if (args.follow) {
         parent = oracleJobs.getJob(args.follow);
@@ -93,7 +134,10 @@ function createOracleHost({ queueAiRequest, requestCallExtension, buildProviderU
         prompt: args.prompt,
         model,
         effort: args.effort,
-        file: args.bundlePath,
+        file: attachmentPaths.length > 0
+          ? attachmentPaths.length === 1 ? attachmentPaths[0] : attachmentPaths
+          : undefined,
+        ...(args.github === true ? { github: true } : {}),
         startUrl: parent?.conversationUrl,
         createTab: async () => {
           const tabInfo = await browserOptions(request).createTab();
@@ -304,4 +348,4 @@ function createOracleHost({ queueAiRequest, requestCallExtension, buildProviderU
   };
 }
 
-module.exports = { assertLocalOracleRequest, createOracleHost };
+module.exports = { assertLocalOracleRequest, createOracleHost, resolveOracleAttachments };

package/native/oracle-jobs.cjs

@@ -47,13 +47,15 @@ function stableJson(value) {
   return JSON.stringify(value) ?? "null";
 }
 
-function requestFingerprint({ prompt, contextManifest, model, effortRequested, follow }) {
+function requestFingerprint({ prompt, contextManifest, model, effortRequested, follow, attachmentPaths, github }) {
   return promptDigest(stableJson({
     promptDigest: promptDigest(prompt),
     contextManifest: contextManifest ?? {},
     model: model ?? null,
     effortRequested: effortRequested ?? null,
     follow: follow ?? null,
+    attachmentPaths: attachmentPaths ?? [],
+    github: github === true,
   }));
 }
 
@@ -92,13 +94,13 @@ function readJobs(root = getPrivateStateRoot()) {
     .map((job) => hydrateJobMetadata(job, root));
 }
 
-function createJob({ prompt, contextManifest = {}, model = null, effortRequested = null, follow = null, requestId = null }) {
+function createJob({ prompt, contextManifest = {}, model = null, effortRequested = null, follow = null, requestId = null, attachmentPaths = [], github = false }) {
   const root = getPrivateStateRoot();
   const base = oracleRoot(root);
   ensurePrivateDir(base, root);
   const safeRequestId = normalizedRequestId(requestId);
   const fingerprint = safeRequestId
-    ? requestFingerprint({ prompt, contextManifest, model, effortRequested, follow })
+    ? requestFingerprint({ prompt, contextManifest, model, effortRequested, follow, attachmentPaths, github })
     : null;
   if (safeRequestId) {
     const existing = readJobs(root).find((job) => job.requestId === safeRequestId);

package/package.json

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

package/pi-extension/surf.ts

@@ -375,6 +375,27 @@ function oracleOption(input: Record<string, unknown>, key: "model" | "effort"):
   return typeof direct === "string" ? direct : undefined;
 }
 
+function oracleAttachmentOption(input: Record<string, unknown>): string | string[] | undefined {
+  const options = input.options;
+  const optionRecord = options && typeof options === "object" && !Array.isArray(options)
+    ? options as Record<string, unknown>
+    : undefined;
+  const optionValue = optionRecord?.file;
+  const value = optionValue === undefined ? input.file : optionValue;
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) return value as string[];
+  return undefined;
+}
+
+function oracleBooleanOption(input: Record<string, unknown>, key: string): boolean {
+  const options = input.options;
+  const optionValue = options && typeof options === "object" && !Array.isArray(options)
+    ? (options as Record<string, unknown>)[key]
+    : undefined;
+  const value = optionValue === undefined ? input[key] : optionValue;
+  return value === true;
+}
+
 function optionalString(input: Record<string, unknown>, key: string): string | undefined {
   const value = input[key];
   return typeof value === "string" && value.trim() ? value : undefined;
@@ -426,10 +447,14 @@ export function createOracleExternalJobProvider(
       if (!prompt.trim()) throw new Error("prompt required");
       const model = oracleOption(input, "model");
       const effort = oracleOption(input, "effort");
+      const file = oracleAttachmentOption(input);
+      const github = oracleBooleanOption(input, "github");
       const job = await requestOracleJob(request, "oracle.ask", {
         prompt,
         ...(model !== undefined ? { model } : {}),
         ...(effort !== undefined ? { effort } : {}),
+        ...(file !== undefined ? { file } : {}),
+        ...(github ? { github: true } : {}),
       });
       rememberJob(job.id);
       return piExternalJobHandle(job);
@@ -470,12 +495,16 @@ export function createOracleExternalJobProvider(
       const parentId = parentProviderJobId(input);
       const model = oracleOption(input, "model");
       const effort = oracleOption(input, "effort");
+      const file = oracleAttachmentOption(input);
+      const github = oracleBooleanOption(input, "github");
       const requestId = optionalString(input, "requestId");
       const job = await requestOracleJob(request, "oracle.ask", {
         prompt,
         follow: parentId,
         ...(model !== undefined ? { model } : {}),
         ...(effort !== undefined ? { effort } : {}),
+        ...(file !== undefined ? { file } : {}),
+        ...(github ? { github: true } : {}),
         ...(requestId !== undefined ? { requestId } : {}),
       });
       assertFollowJob(job, parentId);
@@ -590,8 +619,8 @@ export default function surfExtension(pi: Pi) {
   pi.registerTool({
     name: "surf_oracle_ask",
     label: "surf_oracle_ask",
-    description: "Start a durable local Surf ChatGPT oracle job.",
-    parameters: Type.Object({ prompt: Type.String(), model: Type.Optional(Type.String()), effort: Type.Optional(Type.String()), follow: Type.Optional(Type.String()) }),
+    description: "Start a durable local Surf ChatGPT oracle job, optionally with one local file and GitHub context.",
+    parameters: Type.Object({ prompt: Type.String(), model: Type.Optional(Type.String()), effort: Type.Optional(Type.String()), file: Type.Optional(Type.String()), github: Type.Optional(Type.Boolean()), follow: Type.Optional(Type.String()) }),
     async execute(_id: string, args: Record<string, unknown>) {
       const requestGeneration = sessionGeneration;
       try {

package/skills/surf/SKILL.md

@@ -95,14 +95,14 @@ surf chatgpt "analyze" --file document.pdf        # With file attachment
 
 ### Oracle
 
-Use `surf chatgpt` for quick one-shot questions. Use `surf oracle` for long-running or Pro coding consults that need a durable job, explicit model and effort selection, file context, recovery, or follow-up turns. Oracle is local-only.
+Use `surf chatgpt` for quick one-shot questions. Use `surf oracle` for long-running or Pro coding consults that need a durable job, explicit model and effort selection, file context, a direct local attachment, recovery, or follow-up turns. Oracle is local-only.
 
 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 gpt-5.5 --effort pro --detach --json
+  --model gpt-5.5 --effort pro --file ./design.md --github --detach --json
 
 surf oracle status <job-id> --json
 surf oracle result <job-id> --json
@@ -114,16 +114,16 @@ surf oracle result <job-id> --wait --json
 
 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`, 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 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`, `options.effort`, `options.file`, and `options.github` for starts and follow-ups, so `model: gpt-5.6-sol` plus `effort: pro` selects ChatGPT GPT-5.6 Sol with Pro effort through the browser, while `github: true` requires Chat mode and the connected GitHub tool. `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`, `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.
+Context comes from repeatable `--files` globs. Use `--file <path>` for one additional local attachment; `--github` requires Chat mode and a connected GitHub tool. 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.
 
 Continue a captured consult with `follow`. Use the ID returned by each turn for the next turn:
 
 ```bash
-surf oracle follow <job-id> "Challenge your recommendation. What could invalidate it?" --detach --json
+surf oracle follow <job-id> "Challenge your recommendation. What could invalidate it?" --file ./follow-up.md --github --detach --json
 surf oracle result <follow-job-id> --wait --json
 surf oracle follow <follow-job-id> "Give the final decision and concrete next steps." --detach --json
 ```