@bitkyc08/opencodex 2.6.31-preview.20260707 → 2.7.0

package/src/server/index.ts

@@ -69,6 +69,7 @@ export {
   addFinalRequestLog,
   filterRequestLogs,
   httpStatusForTerminalStatus,
+  httpStatusFromTerminalError,
   nextRequestLogId,
   requestLogErrorCode,
   requestLogSpeedLabel,
@@ -157,6 +158,24 @@ export function startServer(port?: number) {
     config.subagentModels = [...DEFAULT_SUBAGENT_MODELS];
     saveConfig(config);
   }
+  // Sidecar model migration (KST 2026-07-10 06:00 = UTC 2026-07-09 21:00): auto-migrate the old
+  // gpt-5.4-mini default to gpt-5.6-luna for both search and vision sidecars. Only touches configs
+  // still on the old default — explicit user choices are preserved.
+  {
+    const SIDECAR_MIGRATION_CUTOFF = Date.UTC(2026, 6, 9, 21, 0); // July 9 21:00 UTC = KST July 10 06:00
+    if (Date.now() >= SIDECAR_MIGRATION_CUTOFF) {
+      let migrated = false;
+      if (config.webSearchSidecar?.model === "gpt-5.4-mini") {
+        config.webSearchSidecar = { ...config.webSearchSidecar, model: "gpt-5.6-luna" };
+        migrated = true;
+      }
+      if (config.visionSidecar?.model === "gpt-5.4-mini") {
+        config.visionSidecar = { ...config.visionSidecar, model: "gpt-5.6-luna" };
+        migrated = true;
+      }
+      if (migrated) saveConfig(config);
+    }
+  }
   invalidateCodexModelsCache();
 
   const listenPort = port ?? config.port ?? 10100;
@@ -247,7 +266,7 @@ export function startServer(port?: number) {
           return withCors(formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked"), req, config);
         }
         const goModels = await fetchAllModels(config);
-        const { buildCatalogEntries, loadCatalogTemplate, nativeOpenAiSlugs, orderForSubagents, filterCatalogVisibleModels } = await import("../codex/catalog");
+        const { applyNativeVisibility, buildCatalogEntries, disabledNativeSlugs, loadCatalogTemplate, nativeOpenAiSlugs, orderForSubagents, filterCatalogVisibleModels, visibleNativeSlugs } = await import("../codex/catalog");
         const nativeSlugs = nativeOpenAiSlugs();
         const goEnabled = filterCatalogVisibleModels(goModels, config);
         const goOrdered = orderForSubagents(goEnabled, config.subagentModels);
@@ -255,11 +274,16 @@ export function startServer(port?: number) {
           // Codex client → Codex catalog shape: native gpt + namespaced routed models,
           // cloned from a native template so required fields (base_instructions, etc.) are present.
           // Pass the subagent picks so featured models lead by priority (matches the on-disk file).
-          return jsonResponse({ models: buildCatalogEntries(loadCatalogTemplate(), nativeSlugs, goOrdered, config.subagentModels, websocketsEnabled(config)) }, 200, req, config);
+          // Disabled natives stay in the catalog shape with visibility "hide" (mirrors the
+          // on-disk sync; codex-rs keeps them out of the picker itself).
+          const maMode = config.multiAgentMode === "v1" || config.multiAgentMode === "v2" ? config.multiAgentMode : "default";
+          const entries = buildCatalogEntries(loadCatalogTemplate(), nativeSlugs, goOrdered, config.subagentModels, websocketsEnabled(config), maMode as "v1" | "default" | "v2");
+          return jsonResponse({ models: applyNativeVisibility(entries, disabledNativeSlugs(config)) }, 200, req, config);
         }
         // OpenAI list shape: native gpt bare + routed models namespaced "<provider>/<id>"
+        // (pure availability list — disabled natives are omitted entirely).
         const data = [
-          ...nativeSlugs.map(id => ({ id, object: "model", created: 0, owned_by: "openai" })),
+          ...visibleNativeSlugs(config).map(id => ({ id, object: "model", created: 0, owned_by: "openai" })),
           ...goOrdered.map(m => ({ id: `${m.provider}/${m.id}`, object: "model", created: 0, owned_by: m.owned_by ?? m.provider })),
         ];
         return jsonResponse({ object: "list", data }, 200, req, config);

package/src/server/management-api.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../codex/catalog";
-import { invalidateCodexModelsCache } from "../codex/catalog";
+import { invalidateCodexModelsCache, nativeModelRows } from "../codex/catalog";
 import {
   DEFAULT_SUBAGENT_MODELS,
   codexAutoStartEnabled,
@@ -24,8 +24,17 @@ import { deriveProviderPresets } from "../providers/derive";
 import { fetchProviderQuotaReports } from "../providers/quota";
 import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../providers/context-cap";
 import { readUsageEntries } from "../usage/log";
+import { getUsageDebugLogEntries } from "../usage/debug";
 import { parseRange, summarizeUsage } from "../usage/summary";
 import { stripCodexRuntimeProviderFields } from "../codex/auth-context";
+import { getDebugLogEntries } from "../lib/debug-log-buffer";
+import {
+  clearDebugSettings,
+  clearDebugSetting,
+  getDebugSettings,
+  setDebugSettings,
+  type DebugFlag,
+} from "../lib/debug-settings";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import { drainAndShutdown } from "./lifecycle";
 import { filterRequestLogs, getRequestLogEntries } from "./request-log";
@@ -41,6 +50,15 @@ export const VERSION = (() => {
   }
 })();
 
+function parseDebugLogQuery(url: URL): { after: number; limit: number } {
+  const after = Number(url.searchParams.get("after") ?? url.searchParams.get("since") ?? "0");
+  const limit = Number(url.searchParams.get("limit") ?? "500");
+  return {
+    after: Number.isFinite(after) && after > 0 ? after : 0,
+    limit: Number.isFinite(limit) && limit > 0 ? Math.min(limit, 2000) : 500,
+  };
+}
+
 export async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): Promise<Response | null> {
   if (!isAllowedRequestOrigin(req, config)) {
     return jsonResponse({ error: "cross-origin request blocked" }, 403, req, config);
@@ -89,6 +107,12 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     return jsonResponse({ ok: true, codexAutoStart: codexAutoStartEnabled(config) });
   }
 
+  if (url.pathname === "/api/diagnostics/project-config" && req.method === "GET") {
+    const { getCachedProjectConfigDiagnostics } = await import("../codex/project-config-warnings");
+    const { warnings, grouped } = getCachedProjectConfigDiagnostics();
+    return jsonResponse({ warnings, grouped });
+  }
+
   if (url.pathname === "/api/sync" && req.method === "POST") {
     const { syncModelsToCodex } = await import("../codex/sync");
     const result = await syncModelsToCodex(undefined, config, null);
@@ -138,8 +162,8 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     const ws = config.webSearchSidecar ?? {};
     const vs = config.visionSidecar ?? {};
     return jsonResponse({
-      webSearch: { model: ws.model ?? "gpt-5.4-mini", reasoning: ws.reasoning ?? "low" },
-      vision: { model: vs.model ?? "gpt-5.4-mini" },
+      webSearch: { model: ws.model ?? "gpt-5.6-luna", reasoning: ws.reasoning ?? "low" },
+      vision: { model: vs.model ?? "gpt-5.6-luna" },
     });
   }
 
@@ -160,8 +184,8 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     const vs = config.visionSidecar ?? {};
     return jsonResponse({
       ok: true,
-      webSearch: { model: ws.model ?? "gpt-5.4-mini", reasoning: ws.reasoning ?? "low" },
-      vision: { model: vs.model ?? "gpt-5.4-mini" },
+      webSearch: { model: ws.model ?? "gpt-5.6-luna", reasoning: ws.reasoning ?? "low" },
+      vision: { model: vs.model ?? "gpt-5.6-luna" },
     });
   }
 
@@ -169,6 +193,38 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     return jsonResponse(filterRequestLogs(getRequestLogEntries(), url.searchParams));
   }
 
+  if (url.pathname === "/api/debug" && req.method === "GET") {
+    return jsonResponse(getDebugSettings());
+  }
+
+  if (url.pathname === "/api/debug/logs" && req.method === "GET") {
+    const { after, limit } = parseDebugLogQuery(url);
+    return jsonResponse(getDebugLogEntries({ after, limit }));
+  }
+
+  if (url.pathname === "/api/debug/usage-logs" && req.method === "GET") {
+    const { after, limit } = parseDebugLogQuery(url);
+    return jsonResponse(getUsageDebugLogEntries({ after, limit }));
+  }
+
+  if (url.pathname === "/api/debug" && req.method === "PUT") {
+    let body: { debug?: unknown; usage?: unknown; reset?: unknown };
+    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (body.reset === true) return jsonResponse(clearDebugSettings());
+    if (body.reset === "debug" || body.reset === "provider") return jsonResponse(clearDebugSetting("debug"));
+    if (body.reset === "usage") return jsonResponse(clearDebugSetting("usage"));
+    const partial: Partial<Record<DebugFlag, boolean>> = {};
+    for (const key of ["debug", "usage"] as const) {
+      if (body[key] === undefined) continue;
+      if (typeof body[key] !== "boolean") return jsonResponse({ error: `${key} must be a boolean` }, 400);
+      partial[key] = body[key];
+    }
+    if (Object.keys(partial).length === 0) {
+      return jsonResponse({ error: "provide debug/usage booleans or reset:true" }, 400);
+    }
+    return jsonResponse(setDebugSettings(partial));
+  }
+
   if (url.pathname === "/api/usage" && req.method === "GET") {
     const range = parseRange(url.searchParams.get("range"));
     const now = Date.now();
@@ -284,7 +340,17 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
   if (url.pathname === "/api/models" && req.method === "GET") {
     const models = await fetchAllModels(config);
     const disabled = new Set(config.disabledModels ?? []);
-    return jsonResponse(models.map(m => {
+    // Native GPT passthrough rows lead (provider "openai", bare-slug namespaced ids): sourced
+    // from the static supported set so a disabled model stays listed and re-enableable.
+    const native = nativeModelRows(config).map(row => ({
+      provider: "openai",
+      id: row.slug,
+      namespaced: row.slug,
+      disabled: row.disabled,
+      native: true,
+      ...(row.contextWindow !== undefined ? { contextWindow: row.contextWindow } : {}),
+    }));
+    return jsonResponse([...native, ...models.map(m => {
       const namespaced = `${m.provider}/${m.id}`;
       const contextCap = providerContextCap(config, m.provider);
       return {
@@ -293,7 +359,7 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
         disabled: disabled.has(namespaced),
         ...(contextCap !== undefined ? { contextCap, contextCapped: m.contextCapped === true } : {}),
       };
-    }));
+    })]);
   }
 
   if (url.pathname === "/api/provider-context-caps" && req.method === "GET") {
@@ -365,6 +431,76 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     return jsonResponse({ ok: true, disabled });
   }
 
+  // multi_agent_v2 surface toggle. GET reports the flag + the agents.max_threads
+  // boot conflict; PUT flips it via the official `codex features` CLI and RESYNCS
+  // the catalog so multi-agent surface metadata stays fresh. The catalog build
+  // itself never writes config — this endpoint is the only server-side mutation
+  // surface for the flag.
+  if (url.pathname === "/api/v2" && req.method === "GET") {
+    const { isMultiAgentV2Enabled, hasAgentsMaxThreads, getMaxConcurrentThreads } = await import("../codex/features");
+    return jsonResponse({
+      enabled: isMultiAgentV2Enabled(),
+      agentsMaxThreadsConflict: hasAgentsMaxThreads(),
+      maxConcurrentThreadsPerSession: getMaxConcurrentThreads(),
+      multiAgentMode: config.multiAgentMode ?? "default",
+    });
+  }
+  if (url.pathname === "/api/v2" && req.method === "PUT") {
+    let body: { enabled?: unknown; maxConcurrentThreadsPerSession?: unknown; multiAgentMode?: unknown };
+    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    const wantsFlag = body.enabled !== undefined;
+    const wantsThreads = body.maxConcurrentThreadsPerSession !== undefined;
+    const wantsMode = body.multiAgentMode !== undefined;
+    if (!wantsFlag && !wantsThreads && !wantsMode) return jsonResponse({ error: "body must set enabled, multiAgentMode, and/or maxConcurrentThreadsPerSession" }, 400);
+    if (wantsFlag && typeof body.enabled !== "boolean") return jsonResponse({ error: "body.enabled must be a boolean" }, 400);
+    if (wantsMode && body.multiAgentMode !== "v1" && body.multiAgentMode !== "default" && body.multiAgentMode !== "v2") {
+      return jsonResponse({ error: "body.multiAgentMode must be 'v1', 'default', or 'v2'" }, 400);
+    }
+    if (wantsThreads && (typeof body.maxConcurrentThreadsPerSession !== "number" || !Number.isInteger(body.maxConcurrentThreadsPerSession) || body.maxConcurrentThreadsPerSession < 1)) {
+      return jsonResponse({ error: "body.maxConcurrentThreadsPerSession must be an integer >= 1" }, 400);
+    }
+    const { isMultiAgentV2Enabled, hasAgentsMaxThreads, getMaxConcurrentThreads, setMaxConcurrentThreads } = await import("../codex/features");
+    const warnings: string[] = [];
+    if (wantsFlag && isMultiAgentV2Enabled() !== body.enabled) {
+      const { execFileSync } = await import("node:child_process");
+      const command = process.env.CODEX_CLI_PATH?.trim() || "codex";
+      try {
+        execFileSync(command, ["features", body.enabled ? "enable" : "disable", "multi_agent_v2"],
+          { stdio: ["ignore", "pipe", "pipe"], timeout: 15_000, windowsHide: true });
+      } catch (err) {
+        return jsonResponse({ error: `codex features ${body.enabled ? "enable" : "disable"} failed: ${err instanceof Error ? err.message : String(err)}` }, 502);
+      }
+      await refreshCodexCatalogBestEffort();
+    }
+    if (wantsThreads) {
+      // setMaxConcurrentThreads is idempotent (equal value -> no write) and refuses
+      // when the [features.multi_agent_v2] table is missing, so a threads-only PUT
+      // against a never-enabled config fails loudly instead of inventing state.
+      const result = setMaxConcurrentThreads(body.maxConcurrentThreadsPerSession as number);
+      if (!result.ok) return jsonResponse({ error: result.error }, 409);
+      if (result.changed) warnings.push("Thread limit applies to new sessions.");
+    }
+    if (wantsMode) {
+      const mode = body.multiAgentMode as "v1" | "default" | "v2";
+      if (mode === "default") delete config.multiAgentMode;
+      else config.multiAgentMode = mode;
+      saveConfig(config);
+      await refreshCodexCatalogBestEffort();
+      warnings.push(`Multi-agent mode set to '${mode}'. Applies to new sessions.`);
+    }
+    if ((wantsFlag ? body.enabled === true : isMultiAgentV2Enabled()) && hasAgentsMaxThreads()) {
+      warnings.push("[agents] max_threads is set — codex refuses to start while multi_agent_v2 is enabled; remove it (features.multi_agent_v2.max_concurrent_threads_per_session replaces it).");
+    }
+    if (wantsFlag) warnings.push("Applies to new sessions; restart the Codex app or wait out its picker cache to see the ladder change.");
+    return jsonResponse({
+      ok: true,
+      enabled: isMultiAgentV2Enabled(),
+      maxConcurrentThreadsPerSession: getMaxConcurrentThreads(),
+      multiAgentMode: config.multiAgentMode ?? "default",
+      warnings,
+    });
+  }
+
   // Which providers support real OAuth login (drives the GUI's "Log in with …" buttons).
   if (url.pathname === "/api/oauth/providers" && req.method === "GET") {
     return jsonResponse({ providers: listOAuthProviders() });
@@ -381,6 +517,31 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     return jsonResponse({ providers: deriveProviderPresets() });
   }
 
+  // Subagent prompt injection model: single native or routed model whose info is
+  // dynamically injected into the v1 proactive prompt. GET returns the current pick
+  // + available models; PUT sets or clears the pick.
+  if (url.pathname === "/api/injection-model" && req.method === "GET") {
+    const models = await fetchAllModels(config);
+    const disabled = new Set(config.disabledModels ?? []);
+    const { listCatalogNativeSlugs } = await import("../codex/catalog");
+    const nativeModels = listCatalogNativeSlugs()
+      .filter(slug => !disabled.has(slug))
+      .map(slug => ({ provider: "openai", model: slug, namespaced: slug }));
+    const routedModels = models
+      .map(m => ({ provider: m.provider, model: m.id, namespaced: `${m.provider}/${m.id}` }))
+      .filter(m => !disabled.has(m.namespaced));
+    return jsonResponse({ model: config.injectionModel ?? null, available: [...nativeModels, ...routedModels] });
+  }
+  if (url.pathname === "/api/injection-model" && req.method === "PUT") {
+    let body: { model?: unknown };
+    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    const model = typeof body.model === "string" && body.model.length > 0 ? body.model : undefined;
+    if (model) config.injectionModel = model;
+    else delete config.injectionModel;
+    saveConfig(config);
+    return jsonResponse({ ok: true, model: config.injectionModel ?? null });
+  }
+
   // Subagent model picker: which ≤5 routed models Codex's spawn_agent advertises (it shows the
   // first 5 routed catalog entries). PUT reorders the injected catalog so the chosen ones lead.
   if (url.pathname === "/api/subagent-models" && req.method === "GET") {

package/src/server/relay.ts

@@ -3,7 +3,7 @@ import { isUsageDebugEnabled } from "../usage/debug";
 import {
   addRequestLog,
   addFinalRequestLog,
-  httpStatusForTerminalStatus,
+  httpStatusForRequestLogTerminal,
   inspectResponseLogJson,
   inspectResponseLogSsePayload,
   type RequestLogContext,
@@ -249,7 +249,7 @@ export function responseWithDeferredRequestLog(
     status => {
       if (logged) return;
       logged = true;
-      addFinalRequestLog(requestId, start, logCtx, httpStatusForTerminalStatus(status), {
+      addFinalRequestLog(requestId, start, logCtx, httpStatusForRequestLogTerminal(status, logCtx), {
         terminalStatus: status,
         closeReason: "terminal",
       }, addLog);

package/src/server/request-log.ts

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import type { ResponsesTerminalStatus } from "../bridge";
+import { httpStatusFromTerminalError as httpStatusFromClassifiedTerminalError } from "../lib/errors";
 import { CODEX_CONFIG_PATH, readRootTomlString } from "../codex/paths";
 import { readCodexCatalogPath } from "../codex/catalog";
 import type { OcxUsage } from "../types";
+import { redactSecretString } from "../lib/redact";
 import {
   appendUsageEntry,
   usageForFinalLog,
@@ -35,6 +37,12 @@ export interface RequestLogContext {
   usageDebugBodyKind?: UsageDebugBodyKind;
   usageDebugBodySample?: string;
   usageDebugContentType?: string;
+  /** Secret-redacted upstream error reason (e.g. the granular Cursor "rate limit exceeded…"
+   * message) extracted from a `response.failed` SSE payload or non-streaming error body, so the
+   * request log / GUI shows the actual upstream failure rather than only the HTTP-mapped code. */
+  upstreamError?: string;
+  /** HTTP status derived from a terminal `response.failed` SSE payload (429/401/503/etc.). */
+  terminalHttpStatus?: number;
 }
 
 export interface RequestLogEntry {
@@ -56,6 +64,8 @@ export interface RequestLogEntry {
   errorCode?: string;
   terminalStatus?: ResponsesTerminalStatus;
   closeReason?: "terminal" | "client_cancel" | "non_stream";
+  /** Secret-redacted upstream error reason, surfaced in /api/logs and the GUI detail modal. */
+  upstreamError?: string;
   usageStatus: UsageStatus;
   usage?: OcxUsage;
   totalTokens?: number;
@@ -159,12 +169,12 @@ export function usageFromResponsesPayload(usage: unknown): OcxUsage | undefined
   const raw = usage as {
     input_tokens?: unknown;
     output_tokens?: unknown;
-    input_tokens_details?: { cached_tokens?: unknown };
+    input_tokens_details?: { cached_tokens?: unknown; cache_write_tokens?: unknown };
     output_tokens_details?: { reasoning_tokens?: unknown };
     total_tokens?: unknown;
     prompt_tokens?: unknown;
     completion_tokens?: unknown;
-    prompt_tokens_details?: { cached_tokens?: unknown };
+    prompt_tokens_details?: { cached_tokens?: unknown; cache_write_tokens?: unknown };
     completion_tokens_details?: { reasoning_tokens?: unknown };
   };
   if (typeof raw.input_tokens === "number" && typeof raw.output_tokens === "number") {
@@ -175,6 +185,9 @@ export function usageFromResponsesPayload(usage: unknown): OcxUsage | undefined
       ...(typeof raw.input_tokens_details?.cached_tokens === "number"
         ? { cachedInputTokens: raw.input_tokens_details.cached_tokens }
         : {}),
+      ...(typeof raw.input_tokens_details?.cache_write_tokens === "number"
+        ? { cacheCreationInputTokens: raw.input_tokens_details.cache_write_tokens }
+        : {}),
       ...(typeof raw.output_tokens_details?.reasoning_tokens === "number"
         ? { reasoningOutputTokens: raw.output_tokens_details.reasoning_tokens }
         : {}),
@@ -188,6 +201,9 @@ export function usageFromResponsesPayload(usage: unknown): OcxUsage | undefined
       ...(typeof raw.prompt_tokens_details?.cached_tokens === "number"
         ? { cachedInputTokens: raw.prompt_tokens_details.cached_tokens }
         : {}),
+      ...(typeof raw.prompt_tokens_details?.cache_write_tokens === "number"
+        ? { cacheCreationInputTokens: raw.prompt_tokens_details.cache_write_tokens }
+        : {}),
       ...(typeof raw.completion_tokens_details?.reasoning_tokens === "number"
         ? { reasoningOutputTokens: raw.completion_tokens_details.reasoning_tokens }
         : {}),
@@ -202,6 +218,7 @@ export function inspectResponseLogJson(logCtx: RequestLogContext, text: string):
   } catch {
     /* body may not be JSON; request log metadata is best-effort only */
   }
+  captureUpstreamError(logCtx, text);
   if (isUsageDebugEnabled() && logCtx.usageDebugBodyKind === undefined) {
     logCtx.usageDebugBodyKind = "json";
     logCtx.usageDebugBodySample = truncateForDebug(text);
@@ -217,6 +234,7 @@ export function inspectResponseLogSsePayload(logCtx: RequestLogContext, payload:
   } catch {
     /* SSE block payload may not be JSON; metadata inspection is best-effort */
   }
+  captureUpstreamError(logCtx, payload);
   if (debugEnabled) {
     if (!sseAlreadyMarked) {
       logCtx.usageDebugBodyKind = "sse";
@@ -229,10 +247,75 @@ export function inspectResponseLogSsePayload(logCtx: RequestLogContext, payload:
   }
 }
 
+/**
+ * Capture the upstream error reason into the request log context. Codex/consumer surfaces only
+ * see an HTTP-mapped error code (502 → upstream_server_error); the granular reason lives inside
+ * a `response.failed` SSE payload's `error.message` (the adapter's redacted upstream message) or
+ * a non-streaming JSON error body. We keep the FIRST non-empty reason (the original failure) and
+ * run it through redactSecretString so secrets never reach /api/logs. Pure; safe on any text.
+ */
+function captureUpstreamError(logCtx: RequestLogContext, text: string | null): void {
+  if (!text || logCtx.upstreamError) return;
+  try {
+    const json = JSON.parse(text) as {
+      type?: unknown;
+      error?: { message?: unknown };
+      last_error?: { message?: unknown };
+      response?: { error?: { type?: unknown; code?: unknown; message?: unknown } };
+    };
+    captureTerminalHttpStatus(logCtx, json);
+    const message = json?.error?.message
+      ?? json?.last_error?.message
+      ?? json?.response?.error?.message;
+    if (typeof message === "string" && message.trim()) {
+      logCtx.upstreamError = redactSecretString(message).slice(0, 500);
+    }
+  } catch {
+    /* not JSON; nothing to capture */
+  }
+}
+
+function captureTerminalHttpStatus(
+  logCtx: RequestLogContext,
+  json: {
+    type?: unknown;
+    response?: { error?: { type?: unknown; code?: unknown; message?: unknown } };
+  },
+): void {
+  if (logCtx.terminalHttpStatus !== undefined) return;
+  if (json.type !== "response.failed") return;
+  const error = json.response?.error;
+  if (!error || typeof error !== "object") return;
+  logCtx.terminalHttpStatus = httpStatusFromTerminalError({
+    type: typeof error.type === "string" ? error.type : undefined,
+    code: error.code === null || typeof error.code === "string" ? error.code : undefined,
+    message: typeof error.message === "string" ? error.message : undefined,
+  });
+}
+
+/** Map a terminal Responses error object to the HTTP status we record in /api/logs. */
+export function httpStatusFromTerminalError(error: {
+  type?: string;
+  code?: string | null;
+  message?: string;
+} | undefined): number {
+  return httpStatusFromClassifiedTerminalError(error);
+}
+
 export function httpStatusForTerminalStatus(status: ResponsesTerminalStatus): number {
   return status === "completed" ? 200 : 502;
 }
 
+export function httpStatusForRequestLogTerminal(
+  status: ResponsesTerminalStatus,
+  logCtx?: RequestLogContext,
+): number {
+  if (status === "failed" && logCtx?.terminalHttpStatus !== undefined) {
+    return logCtx.terminalHttpStatus;
+  }
+  return httpStatusForTerminalStatus(status);
+}
+
 export function addFinalRequestLog(
   requestId: string,
   start: number,
@@ -270,6 +353,7 @@ export function addFinalRequestLog(
     ...(errorCode ? { errorCode } : {}),
     ...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
     ...(meta?.closeReason ? { closeReason: meta.closeReason } : {}),
+    ...(logCtx.upstreamError ? { upstreamError: logCtx.upstreamError } : {}),
     usageStatus,
     ...(loggedUsage ? { usage: loggedUsage } : {}),
     ...(totalTokens !== undefined ? { totalTokens } : {}),