pi-oracle 0.3.3 → 0.4.0

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

@@ -1,11 +1,18 @@
+// 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";
-import { appendFile, chmod, lstat, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { appendFile, chmod, lstat, mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
 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) {
@@ -27,11 +34,12 @@ const CHATGPT_COOKIE_ORIGINS = [
   "https://sentinel.openai.com",
   "https://ws.chatgpt.com",
 ];
-const LOG_PATH = "/tmp/oracle-auth.log";
-const URL_PATH = "/tmp/oracle-auth.url.txt";
-const SNAPSHOT_PATH = "/tmp/oracle-auth.snapshot.txt";
-const BODY_PATH = "/tmp/oracle-auth.body.txt";
-const SCREENSHOT_PATH = "/tmp/oracle-auth.png";
+let DIAGNOSTICS_DIR;
+let LOG_PATH = "(oracle-auth log path unavailable)";
+let URL_PATH = "(oracle-auth url path unavailable)";
+let SNAPSHOT_PATH = "(oracle-auth snapshot path unavailable)";
+let BODY_PATH = "(oracle-auth body path unavailable)";
+let SCREENSHOT_PATH = "(oracle-auth screenshot path unavailable)";
 const REAL_CHROME_USER_DATA_DIR = resolve(homedir(), "Library", "Application Support", "Google", "Chrome");
 const DEFAULT_ORACLE_STATE_DIR = "/tmp/pi-oracle-state";
 const ORACLE_STATE_DIR = process.env.PI_ORACLE_STATE_DIR?.trim() || DEFAULT_ORACLE_STATE_DIR;
@@ -40,6 +48,17 @@ 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() {
@@ -50,12 +69,25 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+async function initDiagnosticsBundle() {
+  if (DIAGNOSTICS_DIR) return;
+  DIAGNOSTICS_DIR = await mkdtemp(join(tmpdir(), "pi-oracle-auth-"));
+  await chmod(DIAGNOSTICS_DIR, 0o700).catch(() => undefined);
+  LOG_PATH = join(DIAGNOSTICS_DIR, "oracle-auth.log");
+  URL_PATH = join(DIAGNOSTICS_DIR, "oracle-auth.url.txt");
+  SNAPSHOT_PATH = join(DIAGNOSTICS_DIR, "oracle-auth.snapshot.txt");
+  BODY_PATH = join(DIAGNOSTICS_DIR, "oracle-auth.body.txt");
+  SCREENSHOT_PATH = join(DIAGNOSTICS_DIR, "oracle-auth.png");
+}
+
 async function initLog() {
+  await initDiagnosticsBundle();
   await writeFile(LOG_PATH, "", { mode: 0o600 });
   await chmod(LOG_PATH, 0o600).catch(() => undefined);
 }
 
 async function log(message) {
+  await initDiagnosticsBundle();
   const line = `[${new Date().toISOString()}] ${message}\n`;
   await appendFile(LOG_PATH, line, { encoding: "utf8", mode: 0o600 });
   await chmod(LOG_PATH, 0o600).catch(() => undefined);
@@ -63,12 +95,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) => {
@@ -77,8 +122,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}`));
     });
@@ -99,7 +156,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)}`);
 }
 
@@ -116,7 +176,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;
@@ -208,7 +271,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");
@@ -216,7 +279,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 || "{}");
@@ -240,7 +306,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();
   }
@@ -530,22 +600,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) {
@@ -565,116 +620,22 @@ async function captureDiagnostics(reason) {
 }
 
 function classifyChatPage({ url, snapshot, body, probe }) {
-  const text = `${snapshot}\n${body}`;
-  const allowedOrigins = [new URL(config.browser.chatUrl).origin, new URL(config.browser.authUrl).origin, "https://auth.openai.com"];
-
-  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(
@@ -804,7 +765,7 @@ async function run() {
       await writeFile(join(profilePlan.targetDir, ".oracle-seed-generation"), `${generation}\n`, { encoding: "utf8", mode: 0o600 });
       committedProfile = true;
       process.stdout.write(
-        `${classification.message} Synced ${appliedCount} cookies into ${profilePlan.targetDir}`,
+        `${classification.message} Synced ${appliedCount} cookies into ${profilePlan.targetDir}. Diagnostics: ${DIAGNOSTICS_DIR}`,
       );
     } catch (error) {
       shouldPreserveBrowser = Boolean(error && typeof error === "object" && error.preserveBrowser === true);
@@ -822,7 +783,7 @@ async function run() {
 
 run().catch((error) => {
   process.stderr.write(
-    `${error instanceof Error ? error.message : String(error)}\nSee ${LOG_PATH} and diagnostics in /tmp/oracle-auth.*\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)"}\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;

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

@@ -0,0 +1,85 @@
+// Purpose: Provide pure ChatGPT conversation-state helpers used by the oracle worker.
+// Responsibilities: Slice assistant snapshot regions, normalize URLs, and track stable conversation URL observations.
+// Scope: Pure worker flow logic only; browser I/O and polling loops stay in run-job.mjs.
+// Usage: Imported by run-job.mjs and sanity tests to validate conversation-state heuristics without driving a browser.
+// Invariants/Assumptions: Snapshot text comes from agent-browser `snapshot -i`; URL inputs may be malformed and must fail safely.
+
+/** @typedef {import("./chatgpt-flow-helpers.d.mts").OracleStableValueState} OracleStableValueState */
+
+/**
+ * @param {string} snapshot
+ * @param {string} composerLabel
+ * @param {number} responseIndex
+ * @returns {string | undefined}
+ */
+export function assistantSnapshotSlice(snapshot, composerLabel, responseIndex) {
+  const lines = snapshot.split("\n");
+  const assistantHeadingIndices = lines.flatMap((line, index) => (line.includes('heading "ChatGPT said:"') ? [index] : []));
+  const startIndex = assistantHeadingIndices[responseIndex];
+  if (startIndex === undefined) return undefined;
+
+  const endCandidates = [];
+  const nextAssistantIndex = assistantHeadingIndices[responseIndex + 1];
+  if (nextAssistantIndex !== undefined) endCandidates.push(nextAssistantIndex);
+
+  const composerIndex = lines.findIndex(
+    (line, index) => index > startIndex && line.includes(`textbox "${composerLabel}"`),
+  );
+  if (composerIndex !== -1) endCandidates.push(composerIndex);
+
+  const endIndex = endCandidates.length > 0 ? Math.min(...endCandidates) : undefined;
+  return lines.slice(startIndex, endIndex).join("\n");
+}
+
+/**
+ * @param {string | undefined} url
+ * @returns {string}
+ */
+export function stripUrlQueryAndHash(url) {
+  if (typeof url !== "string") return "";
+  try {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    parsed.search = "";
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isConversationPathUrl(url) {
+  try {
+    return /\/c\/[A-Za-z0-9-]+$/i.test(new URL(url).pathname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} url
+ * @param {string | undefined} previousChatUrl
+ * @returns {string | undefined}
+ */
+export function resolveStableConversationUrlCandidate(url, previousChatUrl) {
+  const normalizedUrl = stripUrlQueryAndHash(url);
+  if (!normalizedUrl) return undefined;
+  if (isConversationPathUrl(normalizedUrl)) return normalizedUrl;
+  const normalizedPrevious = stripUrlQueryAndHash(previousChatUrl);
+  return normalizedPrevious && normalizedPrevious === normalizedUrl ? normalizedUrl : undefined;
+}
+
+/**
+ * @param {Partial<OracleStableValueState> | undefined} state
+ * @param {string} nextValue
+ * @returns {OracleStableValueState}
+ */
+export function nextStableValueState(state, nextValue) {
+  return {
+    lastValue: nextValue,
+    stableCount: state?.lastValue === nextValue ? (state?.stableCount ?? 0) + 1 : 1,
+  };
+}