npm - @bitkyc08/opencodex - Versions diffs - 2.6.11 → 2.6.13 - Mend

@bitkyc08/opencodex 2.6.11 → 2.6.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.ko.md +135 -35
package/README.md +6 -0
package/README.zh-CN.md +147 -26
package/gui/dist/assets/{index-DaRQZAM0.js → index-BTTqyZ-C.js} +1 -1
package/gui/dist/index.html +1 -1
package/package.json +1 -1
package/src/cli-help.ts +2 -0
package/src/cli.ts +5 -0
package/src/codex-auth-api.ts +51 -0
package/src/codex-auth-collision.ts +3 -7
package/src/codex-auth-context.ts +11 -0
package/src/codex-routing.ts +64 -2
package/src/doctor.ts +173 -0
package/src/server.ts +8 -0
package/src/web-search/parse.ts +52 -15

package/gui/dist/index.html CHANGED Viewed

@@ -16,7 +16,7 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-DaRQZAM0.js"></script>
+    <script type="module" crossorigin src="/assets/index-BTTqyZ-C.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DIBiVVC0.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.6.11",
+  "version": "2.6.13",
   "description": "Universal provider proxy for OpenAI Codex — use any LLM with Codex CLI/App/SDK",
   "type": "module",
   "main": "./bin/package-main.mjs",

package/src/cli-help.ts CHANGED Viewed

@@ -44,6 +44,7 @@ const helpEntries: Record<string, HelpEntry> = {
   sync: { usage: "ocx sync", summary: "Fetch provider models and inject them into Codex config." },
   "sync-cache": { usage: "ocx sync-cache", summary: "Refresh Codex's model cache from the active catalog." },
   status: { usage: "ocx status", summary: "Check proxy server status." },
+  doctor: { usage: "ocx doctor", summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability)." },
   login: { usage: "ocx login <provider>", summary: "OAuth or API-key login for a provider." },
   logout: { usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
   gui: { usage: "ocx gui", summary: "Open the opencodex dashboard." },
@@ -80,6 +81,7 @@ Usage:
   ocx sync                    Fetch models from providers and inject into Codex config
   ocx sync-cache              Refresh Codex's model cache from the active catalog
   ocx status                  Check proxy server status
+  ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
   ocx login <provider>        OAuth login (xai) — opens browser, stores token in ~/.opencodex/auth.json
   ocx logout <provider>       Remove a stored OAuth login
   ocx gui                     Open the opencodex dashboard

package/src/cli.ts CHANGED Viewed

@@ -396,6 +396,11 @@ switch (command) {
   case "status":
     await handleStatus();
     break;
+  case "doctor": {
+    const { runDoctor } = await import("./doctor");
+    await runDoctor();
+    break;
+  }
   case "ensure":
     await handleEnsure();
     break;

package/src/codex-auth-api.ts CHANGED Viewed

@@ -262,6 +262,57 @@ async function fetchPoolAccountQuota(accountId: string, forceRefresh = false, co
   }
 }
+let primeInFlight: Promise<void> | null = null;
+/**
+ * Best-effort prime of pool-account (and main) quota so the rotation engine has
+ * real usage scores instead of leaving every account at the unknown sentinel.
+ *
+ * Quota is otherwise populated only from live upstream headers (an idle pool
+ * account never serves traffic, so it never gets scored) or from the dashboard
+ * WHAM fetch (a CLI-only user never opens it). Without priming, every account
+ * stays unknown and auto-switch cannot move (see Phase 10). This runs at startup
+ * and lazily before routing when the active account is unknown.
+ *
+ * Single-flight: concurrent callers share one pass instead of stampeding N WHAM
+ * fetches. Per-fetch 8s timeouts and the 5-minute POOL_CACHE_TTL already bound
+ * cost, so the worst case is one WHAM call per account per TTL window. Failures
+ * are swallowed: a blocked WSL network must never crash startup or a request.
+ */
+export async function primeCodexPoolQuotas(config: OcxConfig, reason: string): Promise<void> {
+  if (primeInFlight) return primeInFlight;
+  primeInFlight = (async () => {
+    const runtimeConfig = getRuntimeConfig(config);
+    const pool = (runtimeConfig.codexAccounts ?? []).filter(a => !a.isMain);
+    const stale = pool.filter(a => {
+      const q = getAccountQuota(a.id);
+      return !q || Date.now() - q.updatedAt >= POOL_CACHE_TTL;
+    });
+    const primeMain = !!readCodexTokens() && !getAccountQuota(MAIN_CODEX_ACCOUNT_ID);
+    try {
+      await Promise.allSettled([
+        primeMain ? fetchMainAccountInfo(false) : Promise.resolve(),
+        mapWithConcurrency(stale, POOL_QUOTA_REFRESH_CONCURRENCY, async a => {
+          if (!getCodexAccountCredential(a.id)) return;
+          await fetchPoolAccountQuota(a.id, false, a.plan);
+        }),
+      ]);
+    } catch {
+      // Priming is best-effort; never propagate.
+    }
+    if (process.env.OPENCODEX_DEBUG_QUOTA === "1") {
+      console.warn(`[codex-quota] prime done (reason=${reason}, pool=${pool.length}, refreshed=${stale.length})`);
+    }
+  })().finally(() => { primeInFlight = null; });
+  return primeInFlight;
+}
+/** Test-only: drop any in-flight prime pass so a leaked single-flight promise
+ * from another suite cannot coalesce into the next prime. */
+export function clearCodexQuotaPrimeState(): void {
+  primeInFlight = null;
+}
 export async function handleCodexAuthAPI(
   req: Request,
   url: URL,

package/src/codex-auth-collision.ts CHANGED Viewed

@@ -37,18 +37,14 @@ function isWorkspacePlan(plan: string | undefined | null): boolean {
   return !!plan && /team|business|enterprise|workspace|edu/i.test(plan);
 }
-// Personal and workspace subscriptions are separate duplicate buckets.
-// Within each bucket, keep the original ChatGPT account id + email collision guard.
+// Main login and managed pool accounts are separate duplicate buckets.
+// Inside the pool, personal and workspace subscriptions are also separate buckets.
+// Within each pool bucket, keep the original ChatGPT account id + email collision guard.
 export function checkAccountIdCollision(
   chatgptAccountId: string,
   email?: string | null,
   plan?: string | null,
 ): { collision: true; reason: string } | { collision: false } {
-  const mainAccountId = getMainChatgptAccountId();
-  if (mainAccountId && mainAccountId === chatgptAccountId) {
-    return { collision: true, reason: "Account is already used by the main Codex login." };
-  }
   const candidateEmail = normalizedEmail(email);
   const candidateWorkspace = isWorkspacePlan(plan);
   for (const account of loadConfig().codexAccounts ?? []) {

package/src/codex-auth-context.ts CHANGED Viewed

@@ -8,6 +8,7 @@ import { markAccountNeedsReauth } from "./codex-account-runtime-state";
 import { isCodexAccountUsable } from "./codex-account-usability";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken } from "./codex-main-account";
 import { getCodexAccountCooldownUntil, resolveCodexAccountForThreadDetailed } from "./codex-routing";
+import { getAccountQuota } from "./codex-quota";
 import type { OcxConfig, OcxProviderConfig } from "./types";
 import { FORWARD_HEADERS } from "./adapters/openai-responses";
@@ -76,6 +77,16 @@ export async function resolveCodexAuthContext(headers: Headers, config: OcxConfi
   if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
   const accountId = resolution.status === "selected" ? resolution.accountId : null;
   if (!accountId) return { kind: "main", accountId: null };
+  // Lazy prime: if the selected account has no quota yet, the pool is likely
+  // unprimed (dashboard never opened, or startup prime was blocked). Kick a
+  // best-effort prime so the NEXT routing decision has real scores. This never
+  // blocks the current request, and the helper's single-flight guard collapses
+  // repeated triggers into one pass.
+  if (!getAccountQuota(accountId)) {
+    import("./codex-auth-api")
+      .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, "pre-route"))
+      .catch(() => {});
+  }
   const cooldownUntil = getCodexAccountCooldownUntil(accountId);
   if (cooldownUntil) throw new CodexAccountCooldownError(accountId, cooldownUntil);

package/src/codex-routing.ts CHANGED Viewed

@@ -12,6 +12,9 @@ type ThreadAffinityEntry = {
   generation: number;
   createdAt: number;
   lastUsedAt: number;
+  // Last time the bound account's quota threshold was re-evaluated for this
+  // thread (interval-gated to avoid per-request flapping). See REEVAL_INTERVAL_MS.
+  lastReevalAt: number;
 };
 export type CodexThreadResolution =
@@ -32,6 +35,9 @@ const CODEX_MAX_QUOTA_COOLDOWN_MS = 24 * 60 * 60_000;
 export const CODEX_FAILURE_WINDOW_MS = 5 * 60_000;
 export const CODEX_THREAD_AFFINITY_IDLE_TTL_MS = 24 * 60 * 60_000;
 export const CODEX_THREAD_AFFINITY_MAX_ENTRIES = 2048;
+// Min interval between quota threshold re-evaluations for a single bound thread.
+// Well under the 5h/weekly quota windows, but enough to stop per-request flapping.
+export const CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS = 60_000;
 const upstreamHealth = new Map<string, CodexUpstreamHealth>();
@@ -200,6 +206,7 @@ function bindThreadAffinity(threadId: string, accountId: string, now: number): v
     generation: record.generation,
     createdAt: previous?.createdAt ?? now,
     lastUsedAt: now,
+    lastReevalAt: now,
   });
   pruneLruThreadAffinities();
 }
@@ -260,6 +267,20 @@ function setActiveCodexAccount(config: OcxConfig, accountId: string): void {
   saveConfig(config);
 }
+function isUnknownUsage(usage: number): boolean {
+  return usage >= CODEX_UNKNOWN_USAGE_SCORE;
+}
+// Round-robin among eligible unknown-quota candidates. `getEligiblePoolAccounts`
+// already returns a deterministic order (config order, main unshifted first) and
+// excludes the active id, so taking the first eligible unknown is a stable rotation
+// without any new per-account state.
+function pickNextUnknownAccount(config: OcxConfig, active: string, now: number): string | null {
+  const eligible = getEligiblePoolAccounts(config, active, now)
+    .filter(id => isUnknownUsage(computeCodexUsageScore(getAccountQuota(id), getPoolAccountPlan(config, id))));
+  return eligible.length > 0 ? eligible[0]! : null;
+}
 function applyQuotaAutoSwitch(config: OcxConfig, active: string, now: number): string {
   const threshold = config.autoSwitchThreshold ?? 80;
   if (threshold <= 0) return active;
@@ -267,8 +288,27 @@ function applyQuotaAutoSwitch(config: OcxConfig, active: string, now: number): s
   const activeUsage = computeCodexUsageScore(quota, getPoolAccountPlan(config, active));
   if (activeUsage < threshold) return active;
   const best = pickLowerUsageAccount(config, active, activeUsage, now);
-  if (best !== active) setActiveCodexAccount(config, best);
-  return best;
+  if (best !== active) {
+    setActiveCodexAccount(config, best);
+    return best;
+  }
+  // Deadlock guard: active is over threshold but no candidate scored strictly
+  // lower. When the active itself is unknown, every candidate is likely unknown
+  // too (100 < 100 never fires), which pins the pool to one account whose real
+  // usage we cannot see (e.g. quota never primed on WSL). Rotate to the next
+  // eligible unknown so rotation is not stuck; known-but-saturated accounts are
+  // intentionally left alone so a genuinely hot pool stays visible.
+  if (isUnknownUsage(activeUsage)) {
+    const next = pickNextUnknownAccount(config, active, now);
+    if (next) {
+      console.warn(`[codex-routing] quota unknown for active "${active}"; rotating to "${next}" (all candidates unknown, threshold=${threshold})`);
+      setActiveCodexAccount(config, next);
+      return next;
+    }
+    console.warn(`[codex-routing] quota unknown for active "${active}" and no eligible rotation target; staying put`);
+  }
+  return active;
 }
 function shouldFailover(config: OcxConfig, accountId: string, now: number): boolean {
@@ -314,6 +354,28 @@ export function resolveCodexAccountForThreadDetailed(
       && isCodexAccountSelectable(config, entry.accountId, now)
     ) {
       entry.lastUsedAt = now;
+      // Periodic quota re-eval: a long-lived bound thread must still switch when
+      // it crosses autoSwitchThreshold and a strictly-cooler account exists.
+      // Without this the reuse branch returns before applyQuotaAutoSwitch and the
+      // thread stays pinned for the full idle TTL (the WSL "never switches" report).
+      if (now - entry.lastReevalAt >= CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS) {
+        entry.lastReevalAt = now;
+        const threshold = config.autoSwitchThreshold ?? 80;
+        if (threshold > 0) {
+          const usage = computeCodexUsageScore(
+            getAccountQuota(entry.accountId),
+            getPoolAccountPlan(config, entry.accountId),
+          );
+          if (usage >= threshold) {
+            const best = pickLowerUsageAccount(config, entry.accountId, usage, now);
+            if (best !== entry.accountId) {
+              setActiveCodexAccount(config, best);
+              bindThreadAffinity(threadId, best, now); // rebinds + resets clocks
+              return { status: "selected", accountId: best };
+            }
+          }
+        }
+      }
       return { status: "selected", accountId: entry.accountId };
     }
     threadAccountMap.delete(threadId);

package/src/doctor.ts ADDED Viewed

@@ -0,0 +1,173 @@
+/**
+ * `ocx doctor` - read-only environment diagnostics.
+ *
+ * Explains WHY ChatGPT quota may never populate (and thus why account
+ * auto-switch can appear stuck), especially on WSL2 where outbound fetch to
+ * chatgpt.com can be blocked by NAT/DNS/VPN/proxy differences. Observe-only:
+ * it never sets proxy env, relocates state dirs, mutates quota, or changes
+ * networking. See devlog/_plan/260630_wsl-account-autoswitch/30_*.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { getConfigDir, getConfigPath } from "./config";
+import { readCodexTokens } from "./codex-auth-collision";
+const WHAM_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const PROBE_TIMEOUT_MS = 8000;
+export type PathRow = { label: string; path: string; exists: boolean };
+export function resolveCodexHomeDir(): string {
+  const raw = process.env["CODEX_HOME"]?.trim();
+  return raw ? resolve(raw) : join(homedir(), ".codex");
+}
+export function collectPaths(): PathRow[] {
+  const codexHome = resolveCodexHomeDir();
+  const opencodexHome = getConfigDir();
+  return [
+    { label: "CODEX_HOME", path: codexHome, exists: existsSync(codexHome) },
+    { label: "CODEX_HOME/auth.json", path: join(codexHome, "auth.json"), exists: existsSync(join(codexHome, "auth.json")) },
+    { label: "OPENCODEX_HOME", path: opencodexHome, exists: existsSync(opencodexHome) },
+    { label: "OPENCODEX_HOME/config.json", path: getConfigPath(), exists: existsSync(getConfigPath()) },
+  ];
+}
+export type FsTypeInfo = { fstype: string; mount: string; isDrvfs: boolean; isMntDrive: boolean };
+/**
+ * Parse `/proc/mounts`-shaped content and return the longest mount-point prefix
+ * covering `path`. `mountsContent` is injectable for testing; in production the
+ * caller passes the real file (or null off-Linux -> "n/a").
+ */
+export function detectFsType(path: string, mountsContent: string | null): FsTypeInfo {
+  const isMntDrive = /^\/mnt\/[a-z]\//i.test(path) || /^\/mnt\/[a-z]$/i.test(path);
+  if (!mountsContent) {
+    return { fstype: "n/a", mount: "", isDrvfs: false, isMntDrive };
+  }
+  let best: { mount: string; fstype: string } | null = null;
+  for (const line of mountsContent.split("\n")) {
+    const parts = line.split(/\s+/);
+    if (parts.length < 3) continue;
+    const mount = parts[1]!;
+    const fstype = parts[2]!;
+    if (path === mount || path.startsWith(mount.endsWith("/") ? mount : `${mount}/`) || mount === "/") {
+      if (!best || mount.length > best.mount.length) best = { mount, fstype };
+    }
+  }
+  const fstype = best?.fstype ?? "unknown";
+  return {
+    fstype,
+    mount: best?.mount ?? "",
+    isDrvfs: fstype === "drvfs" || fstype === "9p",
+    isMntDrive,
+  };
+}
+function readMounts(): string | null {
+  try {
+    return process.platform === "linux" ? readFileSync("/proc/mounts", "utf-8") : null;
+  } catch {
+    return null;
+  }
+}
+const PROXY_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY"] as const;
+export type ProxyEnvRow = { key: string; present: boolean };
+/** Report only presence/absence of proxy env vars - never the value (it may
+ * embed credentials). Checks both upper- and lower-case forms. */
+export function collectProxyEnv(): ProxyEnvRow[] {
+  return PROXY_KEYS.map(key => ({
+    key,
+    present: !!(process.env[key]?.trim() || process.env[key.toLowerCase()]?.trim()),
+  }));
+}
+export type WhamProbeResult = {
+  ok: boolean;
+  status: number | null;
+  durationMs: number;
+  classification: "ok" | "timeout" | "connect_error" | string;
+  authenticated: boolean;
+};
+/**
+ * Replicate the runtime WHAM fetch shape (same URL, 8s timeout, main-token
+ * headers when present) so the probe fails exactly where the real path fails.
+ * `fetchImpl` is injectable for testing.
+ */
+export async function probeWham(fetchImpl: typeof fetch = fetch): Promise<WhamProbeResult> {
+  const tokens = readCodexTokens();
+  const headers: Record<string, string> = {};
+  if (tokens) {
+    headers.Authorization = `Bearer ${tokens.access_token}`;
+    headers["ChatGPT-Account-Id"] = tokens.account_id;
+  }
+  const start = performance.now();
+  try {
+    const resp = await fetchImpl(WHAM_USAGE_URL, { headers, signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+    const durationMs = Math.round(performance.now() - start);
+    return {
+      ok: resp.ok,
+      status: resp.status,
+      durationMs,
+      classification: resp.ok ? "ok" : `http_${resp.status}`,
+      authenticated: !!tokens,
+    };
+  } catch (err) {
+    const durationMs = Math.round(performance.now() - start);
+    const name = err instanceof Error ? err.name : String(err);
+    const classification = name === "TimeoutError" || name === "AbortError"
+      ? "timeout"
+      : "connect_error";
+    return { ok: false, status: null, durationMs, classification, authenticated: !!tokens };
+  }
+}
+export async function runDoctor(): Promise<void> {
+  console.log("opencodex doctor\n");
+  const paths = collectPaths();
+  const mounts = readMounts();
+  console.log("Paths");
+  for (const row of paths) {
+    const fs = detectFsType(row.path, mounts);
+    const flags = [fs.fstype !== "n/a" ? `fs=${fs.fstype}` : null, fs.isDrvfs || fs.isMntDrive ? "WSL /mnt drive" : null]
+      .filter(Boolean).join(", ");
+    console.log(`  ${row.exists ? "ok " : "-- "} ${row.label}: ${row.path}${flags ? `  (${flags})` : ""}`);
+  }
+  console.log("\nProxy env (presence only)");
+  for (const row of collectProxyEnv()) {
+    console.log(`  ${row.present ? "set    " : "unset  "} ${row.key}`);
+  }
+  console.log("\nWHAM reachability");
+  const probe = await probeWham();
+  const detail = probe.status !== null ? `status=${probe.status}` : `error=${probe.classification}`;
+  console.log(`  ${probe.ok ? "ok " : "-- "} ${WHAM_USAGE_URL}`);
+  console.log(`       ${detail}, ${probe.durationMs}ms, ${probe.authenticated ? "authenticated" : "unauthenticated"}`);
+  // Hints, not fixes.
+  const hints: string[] = [];
+  const anyDrvfs = paths.some(p => detectFsType(p.path, mounts).isDrvfs || detectFsType(p.path, mounts).isMntDrive);
+  const noProxy = collectProxyEnv().every(p => !p.present);
+  if (anyDrvfs) {
+    hints.push("State dir is on a Windows-mounted (/mnt) drive. Prefer the Linux home (~) under WSL for token/lock reliability.");
+  }
+  if (!probe.ok) {
+    if (probe.classification === "timeout" || probe.classification === "connect_error") {
+      hints.push("WHAM probe could not reach chatgpt.com. On WSL2 this is often NAT/DNS/VPN. Quota cannot prime, so auto-switch stays on unknown scores.");
+      if (noProxy) {
+        hints.push("No *_PROXY env is set in this WSL process. If Windows uses a proxy/VPN, set HTTP(S)_PROXY here or enable WSL autoProxy so Bun fetch can reach the network.");
+      }
+    }
+  }
+  if (hints.length > 0) {
+    console.log("\nHints");
+    for (const h of hints) console.log(`  - ${h}`);
+  }
+}

package/src/server.ts CHANGED Viewed

@@ -2310,5 +2310,13 @@ export function startServer(port?: number) {
   console.log(`   GET  /api/*        → management API`);
   console.log(`   GET  /             → GUI dashboard`);
+  // Prime pool-account quota in the background so the rotation engine has real
+  // usage scores from the first routing decision, even when the dashboard is
+  // never opened (the common CLI/WSL case). Fire-and-forget: never blocks the
+  // listener, and a blocked network silently no-ops (see Phase 30 diagnostics).
+  import("./codex-auth-api")
+    .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, "startup"))
+    .catch(() => {});
   return server;
 }

package/src/web-search/parse.ts CHANGED Viewed

@@ -41,38 +41,75 @@ function collectAnnotation(ann: AnnotationLike | undefined, sources: WebSearchSo
  * answer text with that section stripped so the tool_result renderer doesn't double-print sources.
  *
  * Handles the per-line forms seen from the backend: `- title: url`, `- title (url)`,
- * `- [title](url)`, `- <url>`, `- url`, and numbered `1. ...` variants.
+ * `- [title](url)`, `- <url>`, `- url`, numbered `1. ...` variants, a markdown-prefixed header
+ * (`### Sources:`, `**Sources**`), a title line whose URL sits on the FOLLOWING line, and trailing
+ * URL punctuation (`;`, `,`, `)`, `]`, `.`). Prose that follows the source list is preserved.
  */
-const URL_RE = /https?:\/\/[^\s<>()\]]+/;
+const URL_RE = /https?:\/\/[^\s<>()\[\]]+/;
+// A "Sources:" / "Source:" header, allowing markdown prefixes (#, *, -, >) and bold/italic wrappers.
+const SOURCES_HEADER_RE = /^\s*(?:#{1,6}\s*)?[-*>\s]*\**\s*sources?\s*\**\s*:?\s*\**\s*$/i;
+/** Trim wrapping/trailing noise from a captured URL: angle brackets, then trailing punctuation. */
+function cleanUrl(url: string): string {
+  return url.replace(/^<+/, "").replace(/[)>\].,;:]+$/, "");
+}
+/** Derive a human title from the list-item text preceding the URL (strip markers, md link, seps). */
+function cleanTitle(prefix: string): string {
+  let title = prefix.replace(/^[-*>\d.)\s]+/, "").trim();
+  // `[title](` from a markdown link, or a leading `[`.
+  title = title.replace(/^\[/, "").replace(/\]\(?$/, "").replace(/[:\-—(<]\s*$/, "").trim();
+  return title;
+}
 function extractTrailingSources(text: string): { text: string; sources: WebSearchSource[] } {
   const lines = text.split("\n");
-  // Find the LAST line that is just a "Sources:" / "Source:" header (case-insensitive).
+  // Find the LAST line that is a "Sources:" header (markdown prefixes allowed).
   let headerIdx = -1;
   for (let i = lines.length - 1; i >= 0; i--) {
-    if (/^\s*\**\s*sources?\s*:?\s*\**\s*$/i.test(lines[i])) { headerIdx = i; break; }
+    if (SOURCES_HEADER_RE.test(lines[i])) { headerIdx = i; break; }
   }
   if (headerIdx === -1) return { text, sources: [] };
   const sources: WebSearchSource[] = [];
   const seen = new Set<string>();
+  // Track the last line index actually consumed as part of the source list so trailing prose after
+  // the list survives (we strip the header through the last consumed source line, not to EOF).
+  let lastConsumed = headerIdx;
+  // A title line whose URL is expected on a following line (multiline entry).
+  let pendingTitle: string | null = null;
   for (let i = headerIdx + 1; i < lines.length; i++) {
     const raw = lines[i].trim();
-    if (raw === "") continue;
-    // Only consume list-ish lines that carry a URL; stop at the first non-source line so we don't
-    // swallow trailing prose after the section.
+    if (raw === "") {
+      // Blank line between header and first entry is fine; a blank AFTER entries ends the list.
+      if (sources.length > 0 || pendingTitle !== null) break;
+      continue;
+    }
     const m = raw.match(URL_RE);
-    if (!m) break;
-    const url = m[0].replace(/[).,]+$/, "");
+    if (!m) {
+      // A list-ish line with no URL may be a title whose URL is on the next line. Only treat it as a
+      // pending title when it looks like a list item; otherwise it's prose → stop.
+      if (/^[-*>\d.)]/.test(raw) || pendingTitle === null) {
+        if (/^[-*>\d.)]/.test(raw)) { pendingTitle = raw; lastConsumed = i; continue; }
+      }
+      break;
+    }
+    const url = cleanUrl(m[0]);
+    if (!url) { break; }
+    lastConsumed = i;
+    // Title: text before the URL on this line, else a buffered title from a preceding line.
+    const inlinePrefix = raw.slice(0, m.index);
+    const title = cleanTitle(inlinePrefix) || (pendingTitle ? cleanTitle(pendingTitle) : "");
+    pendingTitle = null;
     if (seen.has(url)) continue;
     seen.add(url);
-    // Derive a title from the text before the URL: strip list markers, [md](), and separators.
-    let title = raw.slice(0, m.index).replace(/^[-*\d.)\s]+/, "").trim();
-    title = title.replace(/^\[/, "").replace(/\]\(?$/, "").replace(/[:\-—(]\s*$/, "").trim();
     sources.push(title ? { url, title } : { url });
   }
   if (sources.length === 0) return { text, sources: [] };
-  // Strip the Sources section (header + consumed lines) from the answer text.
-  const stripped = lines.slice(0, headerIdx).join("\n").replace(/\s+$/, "");
-  return { text: stripped, sources };
+  // Keep text before the header AND any prose after the consumed source lines.
+  const before = lines.slice(0, headerIdx).join("\n").replace(/\s+$/, "");
+  const after = lines.slice(lastConsumed + 1).join("\n").replace(/^\s+/, "");
+  const body = after ? (before ? `${before}\n\n${after}` : after) : before;
+  return { text: body, sources };
 }
 /** Pull final text + url_citation sources from a completed Responses `output[]` array. */