pi-oracle 0.3.4 → 0.5.0

package/extensions/oracle/worker/auth-bootstrap.mjs

@@ -1,3 +1,8 @@
+// Purpose: Bootstrap isolated oracle browser auth by importing real Chrome cookies and validating ChatGPT session readiness.
+// Responsibilities: Copy/import cookies, classify auth pages, drive lightweight account-selection flows, and persist diagnostics for auth failures.
+// Scope: Auth bootstrap worker only; long-running oracle job execution stays in run-job.mjs and shared lifecycle/state helpers stay elsewhere.
+// Usage: Spawned by /oracle-auth to prepare the shared auth seed profile used by future oracle jobs.
+// Invariants/Assumptions: Runs against a local macOS Chrome profile, preserves private diagnostics, and must fail clearly when auth state cannot be verified.
 import { withLock } from "./state-locks.mjs";
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -7,6 +12,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { getCookies } from "@steipete/sweet-cookie";
 import { ensureAccountCookie, filterImportableAuthCookies } from "./auth-cookie-policy.mjs";
 import { buildAllowedChatGptOrigins } from "./chatgpt-ui-helpers.mjs";
+import { buildAccountChooserCandidateLabels, classifyChatAuthPage, normalizeLoginProbeResult } from "./auth-flow-helpers.mjs";
 
 const rawConfig = process.argv[2];
 if (!rawConfig) {
@@ -14,7 +20,23 @@ if (!rawConfig) {
   process.exit(1);
 }
 
-const config = JSON.parse(rawConfig);
+const parsedConfigPayload = JSON.parse(rawConfig);
+const config =
+  parsedConfigPayload &&
+    typeof parsedConfigPayload === "object" &&
+    !Array.isArray(parsedConfigPayload) &&
+    Object.hasOwn(parsedConfigPayload, "config")
+    ? parsedConfigPayload.config
+    : parsedConfigPayload;
+const configLoad =
+  parsedConfigPayload &&
+    typeof parsedConfigPayload === "object" &&
+    !Array.isArray(parsedConfigPayload) &&
+    Object.hasOwn(parsedConfigPayload, "configLoad") &&
+    parsedConfigPayload.configLoad &&
+    typeof parsedConfigPayload.configLoad === "object"
+    ? parsedConfigPayload.configLoad
+    : undefined;
 const CHATGPT_LABELS = {
   composer: "Chat with ChatGPT",
   addFiles: "Add files and more",
@@ -42,12 +64,51 @@ const AGENT_BROWSER_BIN = [process.env.AGENT_BROWSER_PATH, "/opt/homebrew/bin/ag
   (candidate) => typeof candidate === "string" && candidate && existsSync(candidate),
 ) || "agent-browser";
 
+function readPositiveIntEnv(name, fallback) {
+  const value = process.env[name]?.trim();
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+const AGENT_BROWSER_COMMAND_TIMEOUT_MS = readPositiveIntEnv("PI_ORACLE_AUTH_AGENT_BROWSER_TIMEOUT_MS", 30_000);
+const AGENT_BROWSER_CLOSE_TIMEOUT_MS = readPositiveIntEnv("PI_ORACLE_AUTH_CLOSE_TIMEOUT_MS", 10_000);
+const AGENT_BROWSER_KILL_GRACE_MS = readPositiveIntEnv("PI_ORACLE_AUTH_KILL_GRACE_MS", 2_000);
+
 let runtimeProfileDir = config.browser.authSeedProfileDir;
 
 function authSessionName() {
   return `${config.browser.sessionPrefix}-auth`;
 }
 
+function effectiveAuthConfigPath() {
+  return typeof configLoad?.effectiveAuthConfigPath === "string" && configLoad.effectiveAuthConfigPath
+    ? configLoad.effectiveAuthConfigPath
+    : join(process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent"), "extensions", "oracle.json");
+}
+
+function authConfigRemediation() {
+  if (typeof configLoad?.remediation === "string" && configLoad.remediation) return configLoad.remediation;
+  if (typeof configLoad?.projectConfigPath === "string" && configLoad.projectConfigPath && configLoad.projectConfigExists) {
+    return (
+      `Set auth.chromeProfile / auth.chromeCookiePath in ${effectiveAuthConfigPath()}. ` +
+      `Project overrides are also read from ${configLoad.projectConfigPath}, but auth.* is loaded from ${effectiveAuthConfigPath()}.`
+    );
+  }
+  return `Set auth.chromeProfile / auth.chromeCookiePath in ${effectiveAuthConfigPath()}.`;
+}
+
+function authConfigSummary() {
+  if (typeof configLoad?.summary === "string" && configLoad.summary) return configLoad.summary;
+  const agentDirSuffix = typeof configLoad?.agentDir === "string" && configLoad.agentDir ? ` (agent dir: ${configLoad.agentDir})` : "";
+  const createSuffix = configLoad?.agentConfigExists === false ? " [create this file to override auth.*]" : "";
+  const lines = [`Effective oracle auth config: ${effectiveAuthConfigPath()}${agentDirSuffix}${createSuffix}`];
+  if (typeof configLoad?.projectConfigPath === "string" && configLoad.projectConfigPath && configLoad.projectConfigExists) {
+    lines.push(`Project oracle config also loaded: ${configLoad.projectConfigPath} (auth.* still comes from ${effectiveAuthConfigPath()}).`);
+  }
+  return lines.join("\n");
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -78,12 +139,25 @@ async function log(message) {
 
 function spawnCommand(command, args, options = {}) {
   return new Promise((resolve, reject) => {
+    const { timeoutMs = AGENT_BROWSER_COMMAND_TIMEOUT_MS, ...spawnOptions } = options;
     const child = spawn(command, args, {
       stdio: ["pipe", "pipe", "pipe"],
-      ...options,
+      ...spawnOptions,
     });
     let stdout = "";
     let stderr = "";
+    let timedOut = false;
+    let killTimer;
+    let killGraceTimer;
+    if (typeof timeoutMs === "number" && timeoutMs > 0) {
+      killTimer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        killGraceTimer = setTimeout(() => child.kill("SIGKILL"), AGENT_BROWSER_KILL_GRACE_MS);
+        killGraceTimer.unref?.();
+      }, timeoutMs);
+      killTimer.unref?.();
+    }
     if (options.input) child.stdin.end(options.input);
     else child.stdin.end();
     child.stdout.on("data", (data) => {
@@ -92,8 +166,20 @@ function spawnCommand(command, args, options = {}) {
     child.stderr.on("data", (data) => {
       stderr += String(data);
     });
-    child.on("error", reject);
+    child.on("error", (error) => {
+      if (killTimer) clearTimeout(killTimer);
+      if (killGraceTimer) clearTimeout(killGraceTimer);
+      reject(error);
+    });
     child.on("close", (code) => {
+      if (killTimer) clearTimeout(killTimer);
+      if (killGraceTimer) clearTimeout(killGraceTimer);
+      if (timedOut) {
+        const error = new Error(stderr || stdout || `${command} timed out after ${timeoutMs}ms`);
+        if (options.allowFailure) resolve({ code, stdout: stdout.trim(), stderr: error.message });
+        else reject(error);
+        return;
+      }
       if (code === 0 || options.allowFailure) resolve({ code, stdout: stdout.trim(), stderr: stderr.trim() });
       else reject(new Error(stderr || stdout || `${command} exited with code ${code}`));
     });
@@ -114,7 +200,10 @@ function targetBrowserBaseArgs(options = {}) {
 
 async function closeTargetBrowser() {
   await log(`Closing target browser session ${authSessionName()} if present`);
-  const result = await spawnCommand(AGENT_BROWSER_BIN, [...targetBrowserBaseArgs(), "close"], { allowFailure: true });
+  const result = await spawnCommand(AGENT_BROWSER_BIN, [...targetBrowserBaseArgs(), "close"], {
+    allowFailure: true,
+    timeoutMs: AGENT_BROWSER_CLOSE_TIMEOUT_MS,
+  });
   await log(`close result: code=${result.code} stdout=${JSON.stringify(result.stdout)} stderr=${JSON.stringify(result.stderr)}`);
 }
 
@@ -131,7 +220,10 @@ async function ensureNotSymlink(path, label) {
 }
 
 async function isAuthBrowserConnected() {
-  const result = await spawnCommand(AGENT_BROWSER_BIN, [...targetBrowserBaseArgs(), "--json", "stream", "status"], { allowFailure: true });
+  const result = await spawnCommand(AGENT_BROWSER_BIN, [...targetBrowserBaseArgs(), "--json", "stream", "status"], {
+    allowFailure: true,
+    timeoutMs: AGENT_BROWSER_COMMAND_TIMEOUT_MS,
+  });
   try {
     const parsed = JSON.parse(result.stdout || "{}");
     return parsed?.data?.connected === true;
@@ -223,7 +315,7 @@ async function launchTargetBrowser() {
   await closeTargetBrowser();
   const args = [...targetBrowserBaseArgs({ withLaunchOptions: true, mode: "headed" }), "open", "about:blank"];
   await log(`Launching isolated browser: agent-browser ${JSON.stringify(args)}`);
-  const result = await spawnCommand(AGENT_BROWSER_BIN, args, { allowFailure: true });
+  const result = await spawnCommand(AGENT_BROWSER_BIN, args, { allowFailure: true, timeoutMs: AGENT_BROWSER_COMMAND_TIMEOUT_MS });
   await log(`launch result: code=${result.code} stdout=${JSON.stringify(result.stdout)} stderr=${JSON.stringify(result.stderr)}`);
   if (result.code !== 0) {
     throw new Error(result.stderr || result.stdout || "Failed to launch isolated oracle browser");
@@ -231,7 +323,10 @@ async function launchTargetBrowser() {
 }
 
 async function streamStatus() {
-  const result = await spawnCommand(AGENT_BROWSER_BIN, [...targetBrowserBaseArgs(), "--json", "stream", "status"], { allowFailure: true });
+  const result = await spawnCommand(AGENT_BROWSER_BIN, [...targetBrowserBaseArgs(), "--json", "stream", "status"], {
+    allowFailure: true,
+    timeoutMs: AGENT_BROWSER_COMMAND_TIMEOUT_MS,
+  });
   await log(`stream status: code=${result.code} stdout=${JSON.stringify(result.stdout)} stderr=${JSON.stringify(result.stderr)}`);
   try {
     const parsed = JSON.parse(result.stdout || "{}");
@@ -255,7 +350,11 @@ async function targetCommand(...args) {
     maybeOptions &&
     typeof maybeOptions === "object" &&
     !Array.isArray(maybeOptions) &&
-    (Object.hasOwn(maybeOptions, "allowFailure") || Object.hasOwn(maybeOptions, "input") || Object.hasOwn(maybeOptions, "cwd") || Object.hasOwn(maybeOptions, "logLabel"))
+    (Object.hasOwn(maybeOptions, "allowFailure") ||
+      Object.hasOwn(maybeOptions, "input") ||
+      Object.hasOwn(maybeOptions, "cwd") ||
+      Object.hasOwn(maybeOptions, "logLabel") ||
+      Object.hasOwn(maybeOptions, "timeoutMs"))
   ) {
     options = args.pop();
   }
@@ -402,7 +501,7 @@ async function readSourceCookies() {
 
   if (!hasSessionToken) {
     throw new Error(
-      `No ChatGPT session-token cookies were found in ${cookieSourceLabel()}. Make sure ChatGPT is logged into that Chrome profile, or set auth.chromeProfile / auth.chromeCookiePath in ~/.pi/agent/extensions/oracle.json.`,
+      `No ChatGPT session-token cookies were found in ${cookieSourceLabel()}. Make sure ChatGPT is logged into that Chrome profile. ${authConfigRemediation()}`,
     );
   }
 
@@ -545,22 +644,7 @@ function buildLoginProbeScript(timeoutMs) {
 
 async function loginProbe() {
   const result = await evalPage(buildLoginProbeScript(LOGIN_PROBE_TIMEOUT_MS), "login probe eval");
-  if (!result || typeof result !== "object") {
-    return { ok: false, status: 0, error: "invalid-probe-result" };
-  }
-  return {
-    ok: result.ok === true,
-    status: typeof result.status === "number" ? result.status : 0,
-    pageUrl: typeof result.pageUrl === "string" ? result.pageUrl : undefined,
-    domLoginCta: result.domLoginCta === true,
-    onAuthPage: result.onAuthPage === true,
-    error: typeof result.error === "string" ? result.error : undefined,
-    bodyKeys: Array.isArray(result.bodyKeys) ? result.bodyKeys : [],
-    bodyHasId: result.bodyHasId === true,
-    bodyHasEmail: result.bodyHasEmail === true,
-    name: typeof result.name === "string" ? result.name : undefined,
-    responsePreview: typeof result.responsePreview === "string" ? result.responsePreview : undefined,
-  };
+  return normalizeLoginProbeResult(result);
 }
 
 async function captureDiagnostics(reason) {
@@ -580,116 +664,22 @@ async function captureDiagnostics(reason) {
 }
 
 function classifyChatPage({ url, snapshot, body, probe }) {
-  const text = `${snapshot}\n${body}`;
-  const allowedOrigins = buildAllowedChatGptOrigins(config.browser.chatUrl, config.browser.authUrl);
-
-  const challengePatterns = [
-    /just a moment/i,
-    /verify you are human/i,
-    /cloudflare/i,
-    /captcha|turnstile|hcaptcha/i,
-    /unusual activity detected/i,
-    /we detect suspicious activity/i,
-  ];
-  if (challengePatterns.some((pattern) => pattern.test(text))) {
-    return {
-      state: "challenge_blocking",
-      message:
-        `ChatGPT challenge detected after syncing cookies from ${cookieSourceLabel()}. ` +
-        `The isolated oracle browser was left open on profile ${runtimeProfileDir}; complete the challenge there, then rerun /oracle-auth. Logs: ${LOG_PATH}`,
-    };
-  }
-
-  if (/http error 431|request header or cookie too large/i.test(text)) {
-    return {
-      state: "login_required",
-      message:
-        `Imported auth hit HTTP 431 during ChatGPT auth resolution, which usually means the imported cookie set is too large or stale. ` +
-        `Inspect ${LOG_PATH}.`,
-    };
-  }
-
-  const outagePatterns = [
-    /something went wrong/i,
-    /a network error occurred/i,
-    /an error occurred while connecting to the websocket/i,
-    /try again later/i,
-  ];
-  if (outagePatterns.some((pattern) => pattern.test(text))) {
-    return { state: "transient_outage_error", message: `ChatGPT is showing a transient outage/error page. Logs: ${LOG_PATH}` };
-  }
-
-  const onAllowedOrigin = allowedOrigins.some((origin) => url.startsWith(origin));
-  const hasComposer = snapshot.includes(`textbox \"${CHATGPT_LABELS.composer}\"`);
-  const hasAddFiles = snapshot.includes(`button \"${CHATGPT_LABELS.addFiles}\"`);
-  const hasModelControl =
-    snapshot.includes('button "Model selector"') ||
-    /button "(Instant|Thinking|Pro)(?: [^"]*)?"/.test(snapshot);
-
-  if (probe?.status === 401 || probe?.status === 403) {
-    return {
-      state: "login_required",
-      message:
-        `Synced cookies from ${cookieSourceLabel()}, but ChatGPT still rejected the session ` +
-        `(status=${probe?.status ?? 0}). Check auth.chromeProfile/auth.chromeCookiePath and inspect ${LOG_PATH}.`,
-    };
-  }
-
-  if (probe?.onAuthPage) {
-    if (probe?.bodyHasId || probe?.bodyHasEmail) {
-      return {
-        state: "auth_transitioning",
-        message:
-          `ChatGPT is on /auth/login, but /backend-api/me returned a partial authenticated session. ` +
-          `Trying to drive the login resolution flow. Logs: ${LOG_PATH}`,
-      };
-    }
-    return {
-      state: "login_required",
-      message:
-        `Synced cookies from ${cookieSourceLabel()}, but ChatGPT still rejected the session ` +
-        `(status=${probe?.status ?? 0}). Check auth.chromeProfile/auth.chromeCookiePath and inspect ${LOG_PATH}.`,
-    };
-  }
-
-  if (onAllowedOrigin && probe?.status === 200 && hasComposer && hasAddFiles && hasModelControl) {
-    if (!probe?.domLoginCta) {
-      return {
-        state: "authenticated_and_ready",
-        message: `Imported ChatGPT auth from ${cookieSourceLabel()} into the isolated oracle profile. Logs: ${LOG_PATH}`,
-      };
-    }
-
-    return {
-      state: "auth_transitioning",
-      message:
-        probe?.bodyHasId || probe?.bodyHasEmail
-          ? `ChatGPT backend session is authenticated but the shell still shows public CTA chrome. Logs: ${LOG_PATH}`
-          : `ChatGPT accepted cookies but is still hydrating/auth-selecting. Logs: ${LOG_PATH}`,
-    };
-  }
-
-  if (onAllowedOrigin && probe?.ok && hasComposer && hasAddFiles && hasModelControl) {
-    return {
-      state: "authenticated_and_ready",
-      message: `Imported ChatGPT auth from ${cookieSourceLabel()} into the isolated oracle profile. Logs: ${LOG_PATH}`,
-    };
-  }
-
-  if (url && !onAllowedOrigin) {
-    return { state: "login_required", message: `Imported auth redirected away from the expected ChatGPT origin. Logs: ${LOG_PATH}` };
-  }
-
-  return { state: "unknown", message: `ChatGPT page state is not yet ready. Logs: ${LOG_PATH}` };
+  return classifyChatAuthPage({
+    url,
+    snapshot,
+    body,
+    probe,
+    allowedOrigins: buildAllowedChatGptOrigins(config.browser.chatUrl, config.browser.authUrl),
+    cookieSourceLabel: cookieSourceLabel(),
+    runtimeProfileDir,
+    logPath: LOG_PATH,
+    composerLabel: CHATGPT_LABELS.composer,
+    addFilesLabel: CHATGPT_LABELS.addFiles,
+  });
 }
 
 async function maybeSelectAccountIdentity(snapshot, probe) {
-  const candidates = [];
-  if (typeof probe?.name === "string" && probe.name.trim()) {
-    candidates.push(probe.name.trim());
-    const firstToken = probe.name.trim().split(/\s+/)[0];
-    if (firstToken && firstToken !== probe.name.trim()) candidates.push(firstToken);
-  }
+  const candidates = buildAccountChooserCandidateLabels(probe?.name);
 
   for (const label of candidates) {
     const entry = findEntry(
@@ -785,7 +775,7 @@ async function waitForImportedAuthReady() {
     }
     if (classification.state === "login_required") {
       await captureDiagnostics("login-required");
-      throw new Error(classification.message);
+      throw new Error(`${classification.message} ${authConfigRemediation()}`);
     }
     await sleep(config.auth.pollMs);
   }
@@ -805,6 +795,7 @@ async function run() {
       await log(
         `Config summary: session=${authSessionName()} seedProfileDir=${profilePlan.targetDir} stagingProfileDir=${profilePlan.stagingDir} executable=${config.browser.executablePath || "(default)"} source=${cookieSourceLabel()}`,
       );
+      await log(authConfigSummary());
       const cookies = await readSourceCookies();
       await prepareStagedProfile(profilePlan);
       await launchTargetBrowser();
@@ -837,7 +828,7 @@ async function run() {
 
 run().catch((error) => {
   process.stderr.write(
-    `${error instanceof Error ? error.message : String(error)}\nSee ${LOG_PATH} and diagnostics in ${DIAGNOSTICS_DIR || "(oracle-auth diagnostics dir unavailable)"}\nIf needed, ensure the configured real Chrome profile is already logged into ChatGPT and grant macOS Keychain access when prompted.`,
+    `${error instanceof Error ? error.message : String(error)}\nSee ${LOG_PATH} and diagnostics in ${DIAGNOSTICS_DIR || "(oracle-auth diagnostics dir unavailable)"}\n${authConfigSummary()}\nIf needed, ensure the configured real Chrome profile is already logged into ChatGPT and grant macOS Keychain access when prompted.`,
   );
   process.exit(1);
 });

package/extensions/oracle/worker/auth-cookie-policy.mjs

@@ -1,3 +1,8 @@
+// Purpose: Define the allowlist/drop policy for importing ChatGPT/OpenAI auth cookies into the isolated oracle browser profile.
+// Responsibilities: Recognize required auth cookies, drop noisy/irrelevant cookies, and normalize cookie import decisions.
+// Scope: Pure cookie-policy logic only; reading cookies from Chrome and writing them into the isolated profile happen elsewhere.
+// Usage: Imported by auth-bootstrap and sanity tests to keep cookie import behavior deterministic and reviewable.
+// Invariants/Assumptions: Security-sensitive auth cookies are allowlisted intentionally, and analytics/ambient cookies should be excluded by default.
 const AUTH_COOKIE_NAME_PATTERNS = [
   /^__Secure-next-auth\.session-token(?:\.|$)/,
   /^__Secure-next-auth\.callback-url$/,

package/extensions/oracle/worker/auth-flow-helpers.d.mts

@@ -0,0 +1,41 @@
+export interface OracleAuthLoginProbe {
+  ok: boolean;
+  status: number;
+  pageUrl?: string;
+  domLoginCta?: boolean;
+  onAuthPage?: boolean;
+  error?: string;
+  bodyKeys?: string[];
+  bodyHasId?: boolean;
+  bodyHasEmail?: boolean;
+  name?: string;
+  responsePreview?: string;
+}
+
+export type OracleAuthPageState =
+  | "challenge_blocking"
+  | "login_required"
+  | "transient_outage_error"
+  | "auth_transitioning"
+  | "authenticated_and_ready"
+  | "unknown";
+
+export interface OracleAuthPageClassification {
+  state: OracleAuthPageState;
+  message: string;
+}
+
+export declare function normalizeLoginProbeResult(result: unknown): OracleAuthLoginProbe;
+export declare function buildAccountChooserCandidateLabels(name?: string): string[];
+export declare function classifyChatAuthPage(args: {
+  url: string;
+  snapshot: string;
+  body: string;
+  probe?: OracleAuthLoginProbe;
+  allowedOrigins: readonly string[];
+  cookieSourceLabel: string;
+  runtimeProfileDir: string;
+  logPath: string;
+  composerLabel?: string;
+  addFilesLabel?: string;
+}): OracleAuthPageClassification;

package/extensions/oracle/worker/auth-flow-helpers.mjs

@@ -0,0 +1,165 @@
+// Purpose: Provide pure auth-bootstrap classification helpers for ChatGPT browser state handling.
+// Responsibilities: Normalize login-probe payloads, classify ChatGPT auth page states, and derive account chooser candidate labels.
+// Scope: Pure worker/auth decision logic only; browser I/O, logging, and side effects stay in auth-bootstrap.mjs.
+// Usage: Imported by auth-bootstrap.mjs and sanity tests to exercise auth classification behavior without driving a browser.
+// Invariants/Assumptions: Inputs are already captured snapshots/probe results from the live browser session; outputs are deterministic and side-effect free.
+
+/** @typedef {import("./auth-flow-helpers.d.mts").OracleAuthLoginProbe} OracleAuthLoginProbe */
+/** @typedef {import("./auth-flow-helpers.d.mts").OracleAuthPageClassification} OracleAuthPageClassification */
+
+const DEFAULT_COMPOSER_LABEL = "Chat with ChatGPT";
+const DEFAULT_ADD_FILES_LABEL = "Add files and more";
+
+/**
+ * @param {unknown} result
+ * @returns {OracleAuthLoginProbe}
+ */
+export function normalizeLoginProbeResult(result) {
+  if (!result || typeof result !== "object") {
+    return { ok: false, status: 0, error: "invalid-probe-result" };
+  }
+  const value = /** @type {Record<string, unknown>} */ (result);
+  return {
+    ok: value.ok === true,
+    status: typeof value.status === "number" ? value.status : 0,
+    pageUrl: typeof value.pageUrl === "string" ? value.pageUrl : undefined,
+    domLoginCta: value.domLoginCta === true,
+    onAuthPage: value.onAuthPage === true,
+    error: typeof value.error === "string" ? value.error : undefined,
+    bodyKeys: Array.isArray(value.bodyKeys) ? value.bodyKeys.filter((entry) => typeof entry === "string") : [],
+    bodyHasId: value.bodyHasId === true,
+    bodyHasEmail: value.bodyHasEmail === true,
+    name: typeof value.name === "string" ? value.name : undefined,
+    responsePreview: typeof value.responsePreview === "string" ? value.responsePreview : undefined,
+  };
+}
+
+/**
+ * @param {string | undefined} name
+ * @returns {string[]}
+ */
+export function buildAccountChooserCandidateLabels(name) {
+  const normalized = typeof name === "string" ? name.trim() : "";
+  if (!normalized) return [];
+  const firstToken = normalized.split(/\s+/)[0] || "";
+  return firstToken && firstToken !== normalized ? [normalized, firstToken] : [normalized];
+}
+
+/**
+ * @param {{
+ *   url: string;
+ *   snapshot: string;
+ *   body: string;
+ *   probe?: OracleAuthLoginProbe;
+ *   allowedOrigins: readonly string[];
+ *   cookieSourceLabel: string;
+ *   runtimeProfileDir: string;
+ *   logPath: string;
+ *   composerLabel?: string;
+ *   addFilesLabel?: string;
+ * }} args
+ * @returns {OracleAuthPageClassification}
+ */
+export function classifyChatAuthPage(args) {
+  const text = `${args.snapshot}\n${args.body}`;
+  const composerLabel = args.composerLabel || DEFAULT_COMPOSER_LABEL;
+  const addFilesLabel = args.addFilesLabel || DEFAULT_ADD_FILES_LABEL;
+  const onAllowedOrigin = args.allowedOrigins.some((origin) => args.url.startsWith(origin));
+  const hasComposer = args.snapshot.includes(`textbox "${composerLabel}"`);
+  const hasAddFiles = args.snapshot.includes(`button "${addFilesLabel}"`);
+  const hasModelControl =
+    args.snapshot.includes('button "Model selector"') ||
+    /button "(Instant|Thinking|Pro)(?: [^"]*)?"/.test(args.snapshot);
+
+  const challengePatterns = [
+    /just a moment/i,
+    /verify you are human/i,
+    /cloudflare/i,
+    /captcha|turnstile|hcaptcha/i,
+    /unusual activity detected/i,
+    /we detect suspicious activity/i,
+  ];
+  if (challengePatterns.some((pattern) => pattern.test(text))) {
+    return {
+      state: "challenge_blocking",
+      message:
+        `ChatGPT challenge detected after syncing cookies from ${args.cookieSourceLabel}. ` +
+        `The isolated oracle browser was left open on profile ${args.runtimeProfileDir}; complete the challenge there, then rerun /oracle-auth. Logs: ${args.logPath}`,
+    };
+  }
+
+  if (/http error 431|request header or cookie too large/i.test(text)) {
+    return {
+      state: "login_required",
+      message:
+        `Imported auth hit HTTP 431 during ChatGPT auth resolution, which usually means the imported cookie set is too large or stale. ` +
+        `Inspect ${args.logPath}.`,
+    };
+  }
+
+  const outagePatterns = [
+    /something went wrong/i,
+    /a network error occurred/i,
+    /an error occurred while connecting to the websocket/i,
+    /try again later/i,
+  ];
+  if (outagePatterns.some((pattern) => pattern.test(text))) {
+    return { state: "transient_outage_error", message: `ChatGPT is showing a transient outage/error page. Logs: ${args.logPath}` };
+  }
+
+  if (args.probe?.status === 401 || args.probe?.status === 403) {
+    return {
+      state: "login_required",
+      message:
+        `Synced cookies from ${args.cookieSourceLabel}, but ChatGPT still rejected the session ` +
+        `(status=${args.probe?.status ?? 0}). Check auth.chromeProfile/auth.chromeCookiePath and inspect ${args.logPath}.`,
+    };
+  }
+
+  if (args.probe?.onAuthPage) {
+    if (args.probe?.bodyHasId || args.probe?.bodyHasEmail) {
+      return {
+        state: "auth_transitioning",
+        message:
+          `ChatGPT is on /auth/login, but /backend-api/me returned a partial authenticated session. ` +
+          `Trying to drive the login resolution flow. Logs: ${args.logPath}`,
+      };
+    }
+    return {
+      state: "login_required",
+      message:
+        `Synced cookies from ${args.cookieSourceLabel}, but ChatGPT still rejected the session ` +
+        `(status=${args.probe?.status ?? 0}). Check auth.chromeProfile/auth.chromeCookiePath and inspect ${args.logPath}.`,
+    };
+  }
+
+  if (onAllowedOrigin && args.probe?.status === 200 && hasComposer && hasAddFiles && hasModelControl) {
+    if (!args.probe?.domLoginCta) {
+      return {
+        state: "authenticated_and_ready",
+        message: `Imported ChatGPT auth from ${args.cookieSourceLabel} into the isolated oracle profile. Logs: ${args.logPath}`,
+      };
+    }
+
+    return {
+      state: "auth_transitioning",
+      message:
+        args.probe?.bodyHasId || args.probe?.bodyHasEmail
+          ? `ChatGPT backend session is authenticated but the shell still shows public CTA chrome. Logs: ${args.logPath}`
+          : `ChatGPT accepted cookies but is still hydrating/auth-selecting. Logs: ${args.logPath}`,
+    };
+  }
+
+  if (onAllowedOrigin && args.probe?.ok && hasComposer && hasAddFiles && hasModelControl) {
+    return {
+      state: "authenticated_and_ready",
+      message: `Imported ChatGPT auth from ${args.cookieSourceLabel} into the isolated oracle profile. Logs: ${args.logPath}`,
+    };
+  }
+
+  if (args.url && !onAllowedOrigin) {
+    return { state: "login_required", message: `Imported auth redirected away from the expected ChatGPT origin. Logs: ${args.logPath}` };
+  }
+
+  return { state: "unknown", message: `ChatGPT page state is not yet ready. Logs: ${args.logPath}` };
+}

package/extensions/oracle/worker/chatgpt-flow-helpers.d.mts

@@ -0,0 +1,13 @@
+export interface OracleStableValueState {
+  lastValue: string;
+  stableCount: number;
+}
+
+export declare function assistantSnapshotSlice(snapshot: string, composerLabel: string, responseIndex: number): string | undefined;
+export declare function stripUrlQueryAndHash(url: string | undefined): string;
+export declare function isConversationPathUrl(url: string): boolean;
+export declare function resolveStableConversationUrlCandidate(url: string, previousChatUrl?: string): string | undefined;
+export declare function nextStableValueState(
+  state: Partial<OracleStableValueState> | undefined,
+  nextValue: string,
+): OracleStableValueState;