@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,984 lines • 100 kB
text/typescript
import { existsSync, readFileSync } from "node:fs";
import { randomBytes } from "node:crypto";
import { normalizeRecordedClient, type UsageClient } from "../usage/client";
import { anthropicAccountTagField, stampApiKeyAccountLabel, usesApiKeyAccount } from "../providers/label";
import { finalizeProviderCacheAffinity } from "./request-log-cache-affinity";
import { aggregateAttemptUsage } from "./request-log-attempt-usage";
export { aggregateAttemptUsage } from "./request-log-attempt-usage";
import { attemptAccountChanged, sealRequestAttemptIdentity } from "./request-log-account-rotation";
export { sealRequestAttemptIdentity };
import { credentialRecoveryStatus, retainRefusedAccount, sealedCredentialRefusals } from "./request-log-attempt-recovery";
export { noteAttemptRecoveryWithheld } from "./request-log-attempt-recovery";
import { bareVerdictRowErrorCode, captureUpstreamTerminalDiagnostics, guardedRowCopy, linkLogField, notifyLinkTurnFinal, upstreamDiagnosticLogFields, type LinkRequestLogCarrier, type UpstreamErrorDiagnostics, type UpstreamErrorPayload } from "./request-log-terminal-status";
export { noteUpstreamRequestId } from "./request-log-terminal-status";
import type { ResponsesTerminalStatus } from "../bridge";
import {
classifyError,
CYBER_POLICY_ERROR_CODE,
httpStatusFromTerminalError as httpStatusFromClassifiedTerminalError,
isClientClosedMessage,
isCyberPolicyCode,
isUpstreamResetReplayRefusedMessage,
responsesCompletionError,
upstreamErrorMessageFromPayload,
} from "../lib/errors";
import { CODEX_CONFIG_PATH, readRootTomlString } from "../codex/paths";
import type { CodexAffinityMove, CodexAffinityReason } from "../codex/routing";
import type { CodexAuthContext } from "../codex/auth-context";
import { readCodexCatalogPath } from "../codex/catalog";
import type { AttemptTierOutcome, CacheAffinityLogReason, CacheAffinityOutcome, OcxProviderConfig, OcxUsage } from "../types";
import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routing/trace";
import { parseProtocolTraceV1, type ProtocolTraceV1 } from "../protocols/dto";
import { protocolTraceForRequest } from "../protocols/trace";
import type { AdapterRequest } from "../adapters/base";
import type { RequestSpendSettlement } from "./responses/request-spend";
import type { AdapterTierMetadata } from "../providers/fastwire";
import { UPSTREAM_RESET_REPLAY_REFUSED_CODE } from "../lib/upstream-retry";
import { redactSecretString, sanitizeLogMetadataString } from "../lib/redact";
export { registerCommittedTerminalCooldownHandler } from "./request-log-committed-terminal";
import { reportCommittedTerminalCooldown, type CommittedComboLogFields } from "./request-log-committed-terminal";
import type { UpstreamCondition } from "../lib/upstream-condition";
import { boundedServiceTier, errorDetailFor, projectErrorDetail } from "../usage/error-detail";
import { incompleteReasonDetail, upstreamErrorIsLocal, type FailureDetail } from "./request-log-failure-detail";
import {
appendUsageEntry,
classifyCacheTelemetryProvenance,
isKnownAdmissionKind,
isKnownAffinityMove,
isKnownAffinityReason,
isKnownCacheAffinity,
isKnownCacheAffinityReason,
isKnownCacheTelemetryProvenance,
isKnownInboundProtocol,
isKnownTerminalSource,
isKnownTransportPhase,
isKnownUsageSurface,
isCodexUsageAccountLogLabel,
isAnthropicAccountTag,
isLogicalRequestId,
isValidReasoningWireValue,
normalizeClaudeCompatibilityUsageLog,
normalizeRequestFailureAttribution,
normalizeRequestSpend,
normalizedAttempts,
readRecentUsageEntries,
modelIdentityLogFields, recordObservedServedModel,
usageForFinalLog,
usageStatusForFinalLog,
usageTotalTokens,
type AttemptRecoveryKind,
type CacheTelemetryProvenance,
type PersistedRequestSpend,
type PersistedUsageAttempt,
type PersistedUsageEntry,
type PersistedClaudeCompatibilityLog,
type RequestFailureCause,
type RequestFailureStage,
type UsageStatus,
} from "../usage/log";
import type { RequestExecutionBudget } from "../lib/request-execution-budget";
import type { WorkflowSpendDenialDetail } from "../lib/workflow-budget";
import { attributeFinalRequest, attributePhysicalAttempt, attributeSealedAttempt } from "./request-log-failure-attribution";
import { debugAttemptDeliverySummary } from "../lib/debug";
import {
appendUsageDebug,
isUsageDebugEnabled,
truncateForDebug,
USAGE_DEBUG_BODY_SAMPLE_BYTES,
type UsageDebugBodyKind,
} from "../usage/debug";
import { MAX_LOG_SIZE } from "./request-log-filter";
export { filterRequestLogs, filteredRequestLogCount, queryRequestLogs } from "./request-log-filter";
import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
import { capEstimateAtContextWindow } from "../lib/token-estimate";
import { inferCursorContextWindow } from "../adapters/cursor/discovery";
import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
import { kiroObservedContextWindow } from "../providers/kiro-model-catalog";
import { DEVIN_MODEL_CONTEXT_WINDOWS } from "../adapters/devin/live-models";
import { modelRecordValue } from "../reasoning-effort";
import {
normalizePersistedJevDecision,
type PersistedJevDecisionV1,
} from "../usage/jev-stats";
import { generationWindowFields, recordGenerationEvent } from "./request-log-generation-window";
import type { RequestMetricsRecorder } from "./request-metrics";
import { requestBodyField, requestBodyLogField, type RequestBodyEntryField, type RequestBodyLogContext } from "./request-body-facts";
import type {
CacheDiagnosticDraft,
CacheDiagnosticFinalFacts,
PromptCacheKeySource,
} from "../usage/cache-diagnostic";
const CACHE_DIAGNOSTIC_HOOK = Symbol.for("opencodex.cache-diagnostic.v1");
interface CacheDiagnosticHooks {
/** Whether inbound bodies are actually recorded; the hook is registered at import either way. */
enabled(): boolean;
observeInbound(body: unknown, headers: Headers, source: PromptCacheKeySource, admissionPrincipal?: string): CacheDiagnosticDraft;
rebind(body: unknown, draft: CacheDiagnosticDraft | undefined): void;
finalize(facts: CacheDiagnosticFinalFacts): void;
}
function cacheDiagnosticHooks(): CacheDiagnosticHooks | undefined {
return (globalThis as Record<symbol, CacheDiagnosticHooks | undefined>)[CACHE_DIAGNOSTIC_HOOK];
}
/** Whether the cache diagnostic recorder will record inbound bodies (`OPENCODEX_CACHE_DEBUG=1`). */
export function cacheDiagnosticsObserving(): boolean {
return cacheDiagnosticHooks()?.enabled() === true;
}
export interface RequestLogContext extends UpstreamErrorDiagnostics, LinkRequestLogCarrier, RequestBodyLogContext, CommittedComboLogFields {
model: string;
provider: string;
client?: UsageClient;
/** Optional process-lifetime aggregate sink, injected by the server composition owner. */
requestMetricsRecorder?: RequestMetricsRecorder;
/** Bounded terminal enum observed while inspecting a buffered response body. */
observedTerminalStatus?: ResponsesTerminalStatus;
/**
* Identity of the ONE logical request this context serves (#4546). Set from the execution
* budget minted at ingress; a retry leg, a repair refetch and a combo child share it.
*/
logicalRequestId?: string;
/** Process-local privacy-bounded cache diagnostic; never persisted with request logs. */
cacheDiagnosticDraft?: CacheDiagnosticDraft;
/**
* Internal live reference to this request's execution budget; omitted from RequestLogEntry and
* JSONL. Read at final-log time so the row reports the budget's FINAL state rather than a
* snapshot taken before the recovery legs that the row is meant to explain.
*/
executionBudget?: RequestExecutionBudget;
/**
* True once usage counts were taken from a response wire rather than reported raw by the
* adapter. It decides cache provenance: the normalizer writes zero-default token-detail
* objects, so an all-zero cache detail from a parsed wire is not a measured cache miss.
*/
usageWireParsed?: boolean;
/**
* Every affinity reason recorded for this request, in order. `affinityReason` keeps the final
* one for the existing row shape; a request that moved twice has two causes and losing the
* first one loses the more expensive half of the story.
*/
affinityMoveReasons?: CodexAffinityReason[];
/** TTFT: ms from request start to the first non-empty model output delta (WP4, devlog 040). */
firstOutputMs?: number;
/** Epoch ms of the first output item and of the last output delta; see request-log-generation-window.ts. */
generationStartedAt?: number;
lastOutputAt?: number;
/** Best-effort chat/session correlation for Logs grouping (#330). Opaque; omit when unknown. */
conversationId?: string;
/** In-memory only: conversationId holds the log-only Hermes digest, which a native id replaces. */
conversationIdIsHermesFallback?: boolean;
surface?: "claude" | "claude-desktop" | "grok";
/** The matched configured key's id. Set ONLY for admissionKind "configured" —
* never a sentinel, so a hand-edited entry whose id happens to be "loopback"
* cannot absorb unrelated traffic. */
apiKeyId?: string;
/** Which kind of admission opened this request. Carries no secret. */
admissionKind?: "configured" | "environment" | "loopback";
/** Which inbound wire was used. Orthogonal to `surface`, which names the client
* product: widening that enum would merge Responses and Chat Completions,
* since both leave it undefined. */
inboundProtocol?: "responses" | "chat" | "messages";
/**
* Set when an adapter answered the turn locally and no upstream request was made
* (`ProviderAdapter.localTerminal`). A fixed identifier naming the code path, never
* conversation-derived: it exists so a request log showing zero sends is explainable
* rather than looking like a lost request.
*/
localTerminalReason?: string;
/** Stable non-PII Codex Pool account identity for durable usage attribution. */
accountLogLabel?: string;
requestedModel?: string;
/** User-facing alias selector when routing resolved one; native model remains `model`. */
requestedAlias?: string;
/** Original bare helper model when the opt-in shadow-call route rewrote this request. */
shadowCallRewrittenFrom?: string;
/** Internal structural combo identity; omitted from RequestLogEntry/JSONL. */
comboId?: string;
requestedEffort?: string;
effectiveEffort?: string;
reasoningWireField?: string;
reasoningWireValue?: string | number | boolean;
callerServiceTier?: string;
requestedServiceTier?: string;
requestedSpeedLabel?: string;
configuredServiceTier?: string;
configuredSpeedLabel?: string;
modelSupportsServiceTier?: boolean;
responseServiceTier?: string;
/** Final-attempt tier summary; attempt rows remain the accounting source of truth. */
tierOutcome?: AttemptTierOutcome;
resolvedModel?: string;
/** Upstream served model, retained beside resolvedModel so an upstream reroute stays visible. */
servedModel?: string;
/** The exact model id sent upstream; recorded when a route/virtual rewrite makes it differ
* from the client-facing `model`, so a served-model mismatch can be judged against the wire. */
wireModel?: string;
/** Internal: client-facing response metadata must not replace the physical routed model. */
preserveResolvedModelFromRoute?: boolean;
/** Internal: client-facing selector written into response.model; never an upstream observation. */
responseModelEcho?: string;
usage?: OcxUsage;
usageLogInputTokens?: number;
/**
* The output ceiling this request may actually spend, for the durable spend reservation
* (#4707). Captured from the caller's `max_output_tokens`; absent when the caller omitted it
* and the adapter's own provider/model default decides, in which case only the input estimate
* is reserved up front and settlement corrects it.
*/
spendOutputCeilingTokens?: number;
/** Pre-send input estimate reserved for spend only; unlike usageLogInputTokens it never enters usage. */
spendInputEstimateTokens?: number;
/** Canonical provider-pool spend identity; independent of mutable, account-specific log labels. */
spendPoolId?: string;
/** Internal safe refusal detail for a request whose ceiling includes unidentified old pool spend. */
spendRefusalDetail?: WorkflowSpendDenialDetail;
/** Settles this request's durable spend entries from `addFinalRequestLog`. */
spendTracker?: RequestSpendSettlement;
attempts?: PersistedUsageAttempt[];
/** Internal mutable final attempt; omitted from RequestLogEntry/JSONL. */
activeAttempt?: PersistedUsageAttempt;
/** Internal wall-clock origin for the committed final attempt; never persisted. */
activeAttemptStartedAt?: number;
/** Internal adapter response observer paired with activeAttempt.tierOutcome. */
activeTierMetadata?: AdapterTierMetadata;
usageDebugBodyKind?: UsageDebugBodyKind;
usageDebugBodySample?: string;
usageDebugContentType?: string;
/** Route adapter type ("cursor"/"kiro"/"anthropic"/…): drives estimated-usage detection
* independent of the user-chosen provider NAME (devlog 130 B2). */
providerAdapter?: string;
/** Set when the bridge reported raw adapter usage via onUsage: the bridged wire now always
* carries synthetic zero-default token-detail objects (strict-client normalization, see
* responsesUsage in src/bridge.ts), so SSE/JSON re-parsing must not overwrite the raw
* provenance — a synthetic cached_tokens:0 is NOT a measured cache read. */
usageFromBridge?: boolean;
/** Process-owned provenance when a later parse of the client body must skip its usage.
* The original provider usage, when present, is already recorded on this context. */
clientResponseUsage?: "estimated" | "synthetic";
/** A committed keepalive's native child owns raw usage; only the outer client-body log tap skips it. */
clientSseUsageAlreadyInspected?: boolean;
/** 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;
failureDetail?: FailureDetail; // closed code + bounded params (src/lib/failure-detail.ts)
upstreamCondition?: UpstreamCondition; // classified at capture where the evidence is not kept on the context
/** HTTP status derived from a terminal `response.failed` SSE payload (429/401/503/etc.). */
terminalHttpStatus?: number;
/** Status of an upstream `error` event that ended a 200 Messages stream; the row stays 200, a combo child reads it. */
streamErrorStatus?: number;
/** Bytes other than a ping followed that upstream `error` event, so a retry would repeat output. */
streamErrorFollowed?: true;
/** Recognized structured terminal code whose exact identity must survive status mapping. */
terminalErrorCode?: typeof CYBER_POLICY_ERROR_CODE;
/**
* Proxy-owned error code for a request OpenCodex terminated locally, before or instead of an
* upstream send. Status-derived classification cannot name these: there is no upstream
* message to classify, and the status alone would read as a provider failure.
*/
errorCode?: string;
/** Structured reason from `response.incomplete`; internal-only input to log classification. */
terminalIncompleteReason?: string;
affinity?: CodexAffinityMove;
/** Why the binding was kept, moved, or released (#4546). */
affinityReason?: CodexAffinityReason;
/**
* Set when this request dropped account-bound continuation because the serving
* Codex pool account was not the issuer. Never an account identifier.
*/
conversationStateScrub?: "account-change";
/** Explicit session lane for provider cache affinity; internal only, never persisted raw. */
affinityLane?: string;
affinityKeyEntryId?: string;
/** Configured provider owning the serving entry, independent of combo display labels. */
affinityProviderName?: string;
/** Whether provider cache affinity applies to this request's provider at all. */
cacheAffinityApplicable?: boolean;
/** Entry the consult kept this request on, when it did; rotation may still move it. */
affinityKeptEntryId?: string;
/** Model identity affinity consults with; recording reuses it so virtual models match. */
affinityModel?: string;
/** Provider cache-affinity outcome for this request (bounded enum, persisted on the entry). */
cacheAffinity?: CacheAffinityOutcome;
cacheAffinityReason?: CacheAffinityLogReason;
transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse";
terminalSource?: "upstream" | "synthetic";
/** Closed failure evidence supplied by the transport, never inferred from provider text. */
causeHint?: RequestFailureCause;
/** Bounded route-decision trace (RI-01); never contains secrets. */
routeDecision?: RouteDecisionTraceV1;
/** Full eligible provider/model membership from a policy route; never logged. */
policyEligibility?: ReadonlySet<string>;
/** Privacy-bounded JEV selection metadata; downstream usage is recorded on attempts[]. */
jevDecision?: PersistedJevDecisionV1;
/** Opt-in shadow evidence, normalized again at the logging boundary. */
claudeCompatibility?: PersistedClaudeCompatibilityLog;
}
export function observeCacheDiagnosticInbound(
logCtx: RequestLogContext,
body: unknown,
headers: Headers,
source: PromptCacheKeySource,
admissionPrincipal?: string,
): void {
const draft = cacheDiagnosticHooks()?.observeInbound(body, headers, source, admissionPrincipal);
if (draft) logCtx.cacheDiagnosticDraft = draft;
}
/** Alias a rebuilt form of the request body to the request's diagnostic draft. */
export function rebindCacheDiagnosticBody(
body: unknown,
draft: CacheDiagnosticDraft | undefined,
): void {
cacheDiagnosticHooks()?.rebind(body, draft);
}
export interface RequestLogEntry extends UpstreamErrorDiagnostics, LinkRequestLogCarrier, RequestBodyEntryField {
requestId: string;
client?: UsageClient;
/** The logical request this row belongs to (#4546); absent on rows written without a budget. */
logicalRequestId?: string;
timestamp: number;
model: string;
provider: string;
/** TTFT: ms from request start to the first non-empty model output delta; unset for non-streaming/tool-only. */
firstOutputMs?: number;
/** Request-relative generation window (#6309): first output item of any kind, then the last output delta. */
genStartMs?: number;
lastOutputMs?: number;
surface?: "claude" | "claude-desktop" | "grok";
/**
* Set when the proxy answered this turn locally and sent nothing upstream. Without it a zero-send
* row is indistinguishable from a request that vanished. A fixed adapter-supplied identifier,
* never conversation-derived.
*/
localTerminalReason?: string;
/** The matched configured key's id. Set ONLY for admissionKind "configured" —
* never a sentinel, so a hand-edited entry whose id happens to be "loopback"
* cannot absorb unrelated traffic. */
apiKeyId?: string;
/** Which kind of admission opened this request. Carries no secret. */
admissionKind?: "configured" | "environment" | "loopback";
/** Which inbound wire was used. Orthogonal to `surface`, which names the client
* product: widening that enum would merge Responses and Chat Completions,
* since both leave it undefined. */
inboundProtocol?: "responses" | "chat" | "messages";
accountLogLabel?: string;
/** Anthropic pool account of `provider` (#8383): its p-label, beside the unchanged `accountLogLabel`. */
accountTag?: `p${string}`;
/** Best-effort chat/session correlation for Logs grouping (#330). */
conversationId?: string;
requestedModel?: string;
requestedAlias?: string;
/** Original bare helper model when the opt-in shadow-call route rewrote this request. */
shadowCallRewrittenFrom?: string;
requestedEffort?: string;
effectiveEffort?: string;
reasoningWireField?: string;
reasoningWireValue?: string | number | boolean;
callerServiceTier?: string;
requestedServiceTier?: string;
requestedSpeedLabel?: string;
configuredServiceTier?: string;
configuredSpeedLabel?: string;
modelSupportsServiceTier?: boolean;
responseServiceTier?: string;
tierOutcome?: AttemptTierOutcome;
resolvedModel?: string;
/** Model the upstream actually served (openai-model header or response body). */
servedModel?: string;
/** The exact model id sent upstream when it differs from the client-facing `model`. */
wireModel?: string;
status: number;
durationMs: number;
errorCode?: string;
terminalStatus?: ResponsesTerminalStatus;
closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow";
/** Input only: addRequestLog derives the two fields below from it, then removes it. */
upstreamError?: string;
upstreamCondition?: UpstreamCondition; // closed enum, src/lib/upstream-condition.ts
failureDetail?: FailureDetail; // closed code + bounded params, see request-log-failure-detail.ts
rateLimitResetAt?: number; // provider quota window end, epoch ms, bounded
usageStatus: UsageStatus;
usage?: OcxUsage;
totalTokens?: number;
attempts?: PersistedUsageAttempt[];
/** True when persistence normalization drops any attempt. */
attemptNormalizationDropped?: boolean;
/**
* Upstream spend for the whole logical request: sends aggregated across attempts and combo
* children, split into settled and unresolved, with the budget state and move reasons that
* explain them. Per-attempt `sendCount` stays the accounting source; this is the total.
*/
spend?: PersistedRequestSpend;
/** Whether this row's cache detail was observed, synthesized for the wire, or absent. */
cacheProvenance?: CacheTelemetryProvenance;
/** Codex pool affinity decision for this request (diagnostics for #186). */
affinity?: CodexAffinityMove;
/** Why that decision was made (#4546): a move is the expensive event, so it names its cause. */
affinityReason?: CodexAffinityReason;
/** Provider cache-affinity outcome: kept on, newly bound to, or released from a key-pool credential. */
cacheAffinity?: CacheAffinityOutcome;
cacheAffinityReason?: CacheAffinityLogReason;
/**
* Set when this request dropped account-bound continuation after a Codex pool
* account change. Never an account identifier.
*/
conversationStateScrub?: "account-change";
/** Where the upstream terminal/failure was observed. */
transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse";
/**
* Whether the HTTP status and message originated upstream or were synthesized by this
* proxy. Covers SSE tails and pre-stream JSON refusals. Management surfaces this so a
* local refusal cannot be presented as an upstream reason.
*/
terminalSource?: "upstream" | "synthetic";
/** Bounded route-decision trace (RI-01); never contains secrets. */
routeDecision?: RouteDecisionTraceV1;
/** Privacy-bounded JEV selection metadata; downstream usage is recorded on attempts[]. */
jevDecision?: PersistedJevDecisionV1;
/** Closed Claude protocol codes; no request or header values. */
claudeCompatibility?: PersistedClaudeCompatibilityLog;
/**
* How far this request got and why it failed, in the shared stage and cause vocabulary
* (#2366). Derived once at the single finalization seam and carried on the row so the
* dashboard, the durable ledger and the exporter read one answer instead of three.
*/
failureStage?: RequestFailureStage;
failureCause?: RequestFailureCause;
/** Observed protocol path (PF-02, `src/protocols/trace.ts`); absent when nothing was observed. */
protocolTrace?: ProtocolTraceV1;
}
const requestLog: RequestLogEntry[] = [];
const requestLogObserversForTests = new Set<(entry: RequestLogEntry) => void>();
const requestLogEntryBytes = new WeakMap<RequestLogEntry, number>();
let requestLogBytes = 0;
/** True after hydrateRequestLogsFromDisk ran once in this process. */
let requestLogsHydratedFromDisk = false;
function retainedRequestLogBytes(entry: RequestLogEntry): number {
return Buffer.byteLength(JSON.stringify(entry), "utf8");
}
function removeOldestRequestLogEntry(): number {
const entry = requestLog.shift();
if (!entry) return 0;
const bytes = requestLogEntryBytes.get(entry) ?? retainedRequestLogBytes(entry);
requestLogEntryBytes.delete(entry);
requestLogBytes = Math.max(0, requestLogBytes - bytes);
return bytes;
}
function retainRequestLogEntry(entry: RequestLogEntry): void {
const bytes = retainedRequestLogBytes(entry);
requestLog.push(entry);
requestLogEntryBytes.set(entry, bytes);
requestLogBytes += bytes;
while (requestLog.length > MAX_LOG_SIZE) removeOldestRequestLogEntry();
enforceAppOwnedMemoryBudget();
}
export function requestLogRetainedStoreSnapshot(): RetainedStoreSnapshot {
return {
count: requestLog.length,
bytes: requestLogBytes,
evictableBytes: requestLogBytes,
pinnedBytes: 0,
oldestAt: requestLog[0]?.timestamp ?? null,
};
}
export function evictOldestRequestLogForBudget(): number {
return removeOldestRequestLogEntry();
}
function asTerminalStatus(value: string | undefined): ResponsesTerminalStatus | undefined {
if (value === "completed" || value === "failed" || value === "incomplete") return value;
return undefined;
}
function asCloseReason(value: string | undefined): RequestLogEntry["closeReason"] | undefined {
switch (value) {
case "terminal":
case "client_cancel":
case "non_stream":
case "body_stall":
case "body_overflow":
return value;
default:
return undefined;
}
}
/** Project a persisted usage.jsonl row back into the in-memory /api/logs shape. */
export function requestLogEntryFromPersistedUsage(entry: PersistedUsageEntry): RequestLogEntry {
const terminalStatus = asTerminalStatus(entry.terminalStatus);
const closeReason = asCloseReason(entry.closeReason);
const routeDecision = normalizeRouteDecisionTraceForLog(entry.routeDecision);
const jevDecision = normalizePersistedJevDecision(entry.jevDecision);
const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
const spend = normalizeRequestSpend(entry.spend);
const protocolTrace = parseProtocolTraceV1(entry.protocolTrace);
// projectErrorDetail bounds the tier fields (top-level and per attempt) itself, so this stays safe
// for a row that did not come through the disk reader; attempts are copied before it edits them.
const attempts = Array.isArray(entry.attempts) ? entry.attempts.map(({ accountTag, ...attempt }) => ({ ...attempt,
...(isAnthropicAccountTag(accountTag) ? { accountTag } : {}) })) : entry.attempts;
return projectErrorDetail({
requestId: entry.requestId,
...(isLogicalRequestId(entry.logicalRequestId) ? { logicalRequestId: entry.logicalRequestId } : {}),
timestamp: entry.timestamp,
model: entry.model,
provider: entry.provider,
...(Object.hasOwn(entry, "client") ? { client: normalizeRecordedClient(entry.client) ?? "unknown" } : {}),
...(entry.firstOutputMs !== undefined ? { firstOutputMs: entry.firstOutputMs } : {}),
...(entry.genStartMs !== undefined ? { genStartMs: entry.genStartMs } : {}),
...(entry.lastOutputMs !== undefined ? { lastOutputMs: entry.lastOutputMs } : {}),
...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}), ...linkLogField(entry.link), ...requestBodyField(entry.requestBody),
...(entry.conversationId ? { conversationId: entry.conversationId } : {}),
...(isCodexUsageAccountLogLabel(entry.accountLogLabel)
? { accountLogLabel: entry.accountLogLabel }
: {}),
...(isAnthropicAccountTag(entry.accountTag) ? { accountTag: entry.accountTag } : {}),
...(entry.requestedModel ? { requestedModel: entry.requestedModel } : {}),
...(entry.requestedAlias ? { requestedAlias: entry.requestedAlias } : {}),
...(entry.shadowCallRewrittenFrom
? { shadowCallRewrittenFrom: entry.shadowCallRewrittenFrom }
: {}),
...(entry.requestedEffort ? { requestedEffort: entry.requestedEffort } : {}),
...(entry.effectiveEffort ? { effectiveEffort: entry.effectiveEffort } : {}),
...(entry.reasoningWireField ? { reasoningWireField: entry.reasoningWireField } : {}),
...(entry.reasoningWireValue !== undefined ? { reasoningWireValue: entry.reasoningWireValue } : {}),
...(entry.callerServiceTier ? { callerServiceTier: entry.callerServiceTier } : {}),
...(entry.requestedServiceTier ? { requestedServiceTier: entry.requestedServiceTier } : {}),
...(entry.requestedSpeedLabel ? { requestedSpeedLabel: entry.requestedSpeedLabel } : {}),
...(entry.configuredServiceTier ? { configuredServiceTier: entry.configuredServiceTier } : {}),
...(entry.configuredSpeedLabel ? { configuredSpeedLabel: entry.configuredSpeedLabel } : {}),
...(entry.modelSupportsServiceTier !== undefined
? { modelSupportsServiceTier: entry.modelSupportsServiceTier }
: {}),
...(entry.responseServiceTier ? { responseServiceTier: entry.responseServiceTier } : {}),
...(entry.tierOutcome ? { tierOutcome: entry.tierOutcome } : {}),
...modelIdentityLogFields(entry),
status: entry.status,
durationMs: entry.durationMs,
// Closed code, condition, failure detail and quota reset; legacy upstream text is read once and dropped.
...errorDetailFor(entry),
...(terminalStatus ? { terminalStatus } : {}),
...(closeReason ? { closeReason } : {}),
usageStatus: entry.usageStatus,
...(entry.usage ? { usage: entry.usage } : {}),
...(entry.totalTokens !== undefined ? { totalTokens: entry.totalTokens } : {}),
...(attempts !== undefined ? { attempts } : {}),
...(entry.attemptNormalizationDropped === true
? { attemptNormalizationDropped: true } : {}),
...(spend ? { spend } : {}),
...(isKnownCacheTelemetryProvenance(entry.cacheProvenance)
? { cacheProvenance: entry.cacheProvenance }
: {}),
...persistedAffinityFields(entry),
...persistedCacheAffinityFields(entry),
...(isKnownTransportPhase(entry.transportPhase) ? { transportPhase: entry.transportPhase } : {}),
...(isKnownTerminalSource(entry.terminalSource) ? { terminalSource: entry.terminalSource } : {}),
...(routeDecision ? { routeDecision } : {}),
...(jevDecision ? { jevDecision } : {}),
...(claudeCompatibility ? { claudeCompatibility } : {}),
...(entry.conversationStateScrub === "account-change"
? { conversationStateScrub: "account-change" }
: {}),
...normalizeRequestFailureAttribution(entry),
...(protocolTrace ? { protocolTrace } : {}),
});
}
/**
* Affinity survived only in memory before this: `addFinalRequestLog` set it on the row and the
* field-by-field disk projection never named it, so the move that discarded a warm prefix was
* gone at the next restart — the same whitelist trap #4592 hit one layer up.
*/
function persistedAffinityFields(
entry: Pick<RequestLogEntry, "affinity" | "affinityReason">,
): Pick<PersistedUsageEntry, "affinity" | "affinityReason"> {
if (!isKnownAffinityMove(entry.affinity)) return {};
return {
affinity: entry.affinity,
...(isKnownAffinityReason(entry.affinityReason) ? { affinityReason: entry.affinityReason } : {}),
};
}
function persistedCacheAffinityFields(
entry: Pick<RequestLogEntry, "cacheAffinity" | "cacheAffinityReason">,
): Pick<PersistedUsageEntry, "cacheAffinity" | "cacheAffinityReason"> {
if (!isKnownCacheAffinity(entry.cacheAffinity)) return {};
return {
cacheAffinity: entry.cacheAffinity,
...(isKnownCacheAffinityReason(entry.cacheAffinityReason) ? { cacheAffinityReason: entry.cacheAffinityReason } : {}),
};
}
/**
* Hydration guard: persisted traces are re-normalized before they enter the
* in-memory ring buffer so a hand-edited or corrupt row cannot poison the DTO.
* A row that fails validation is dropped, never forwarded unvalidated.
*/
function normalizeRouteDecisionTraceForLog(
entry: RouteDecisionTraceV1 | undefined,
): RouteDecisionTraceV1 | null {
return entry ? normalizeRouteDecisionTrace(entry) : null;
}
/**
* Seed the in-memory Logs ring buffer from usage.jsonl so GUI /api/logs survives
* `ocx stop` / `ocx start` (process restart). Idempotent per process; no-ops when
* the buffer already has live entries. Read failures are non-fatal (same as /api/usage).
*/
export function hydrateRequestLogsFromDisk(
reader: () => PersistedUsageEntry[] = () => readRecentUsageEntries(MAX_LOG_SIZE),
): number {
if (requestLogsHydratedFromDisk) return 0;
if (requestLog.length > 0) {
requestLogsHydratedFromDisk = true;
return 0;
}
try {
const persisted = reader();
requestLogsHydratedFromDisk = true;
if (persisted.length === 0) return 0;
const slice = persisted.length > MAX_LOG_SIZE
? persisted.slice(persisted.length - MAX_LOG_SIZE)
: persisted;
for (const entry of slice) retainRequestLogEntry(requestLogEntryFromPersistedUsage(entry));
return slice.length;
} catch (err) {
requestLogsHydratedFromDisk = true;
console.warn(
`[request-log] failed to hydrate from usage.jsonl: ${err instanceof Error ? err.message : String(err)}`,
);
return 0;
}
}
/**
* Rebuild the Logs ring after retention deleted rows from the ledger.
*
* Without this a compaction is invisible where an operator actually looks: the ring holds up to
* 2,000 entries independently of the file, so rows deleted from disk keep serving through
* /api/logs until eviction or a restart -- the dashboard showing history the ledger no longer
* has. Observers are deliberately not replayed; they exist to watch NEW rows arrive, and
* replaying a rehydration through them would announce two thousand arrivals that did not happen.
*/
export function rehydrateRequestLogsAfterLedgerReplacement(
reader: () => PersistedUsageEntry[] = () => readRecentUsageEntries(MAX_LOG_SIZE),
): number {
requestLog.length = 0;
requestLogBytes = 0;
requestLogsHydratedFromDisk = false;
return hydrateRequestLogsFromDisk(reader);
}
export function addRequestLog(entry: RequestLogEntry) {
// Rows keep proxy-owned error facts only; upstream error text and tokens stop here (both the
// retained ring row and the usage.jsonl projection below read the projected entry).
const attemptNormalizationDropped = entry.attemptNormalizationDropped === true, client = normalizeRecordedClient(entry.client) ?? "unknown";
const clientDescriptor = Object.getOwnPropertyDescriptor(entry, "client");
if (!Object.isFrozen(entry) || !clientDescriptor?.enumerable || !("value" in clientDescriptor) || clientDescriptor.value !== client || Object.values(Object.getOwnPropertyDescriptors(entry)).some(descriptor => !("value" in descriptor))) {
entry = { ...entry, ...errorDetailFor(entry), client, ...(attemptNormalizationDropped ? { attemptNormalizationDropped: true } : {}) };
}
entry = projectErrorDetail(entry);
if (attemptNormalizationDropped && entry.attemptNormalizationDropped !== true) entry = { ...entry, attemptNormalizationDropped: true };
// Sanitize ONCE, at the ingress, and use that one value for both destinations.
//
// `addFinalRequestLog` is not the only way in: `addRequestLog` is exported and callable
// directly, and it retained the caller's entry verbatim in the in-memory ring while only the
// field-by-field disk projection below saw a sanitized value. That split let `/api/logs`
// serve a raw upstream-supplied marker — a newline in it can forge a record boundary in a
// line-oriented viewer — while `usage.jsonl` looked clean, which is the worst shape for a
// sanitization bug because the safe surface is the one you check.
const shadowCallRewrittenFrom = sanitizeLogMetadataString(entry.shadowCallRewrittenFrom);
const identity = modelIdentityLogFields(entry), servedModel = identity.servedModel;
const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
const jevDecision = normalizePersistedJevDecision(entry.jevDecision);
const attempts = normalizedAttempts(entry.attempts);
const attemptsDropped = Array.isArray(entry.attempts) && attempts.length < entry.attempts.length;
const retained: RequestLogEntry = shadowCallRewrittenFrom === entry.shadowCallRewrittenFrom
&& servedModel === entry.servedModel && identity.resolvedModel === entry.resolvedModel
&& entry.claudeCompatibility === undefined
&& entry.jevDecision === undefined
&& !attemptsDropped
? entry
: { ...entry, ...(entry.attemptNormalizationDropped === true || attemptsDropped ? { attemptNormalizationDropped: true } : {}),
...(shadowCallRewrittenFrom ? { shadowCallRewrittenFrom } : {}) };
if (!shadowCallRewrittenFrom && retained !== entry) delete retained.shadowCallRewrittenFrom;
if (retained !== entry) { if (!servedModel) delete retained.servedModel; if (!identity.resolvedModel) delete retained.resolvedModel; }
if (claudeCompatibility) retained.claudeCompatibility = claudeCompatibility;
else if (retained !== entry) delete retained.claudeCompatibility;
if (jevDecision) retained.jevDecision = jevDecision;
else if (retained !== entry) delete retained.jevDecision;
entry = retained;
retainRequestLogEntry(entry);
for (const observer of requestLogObserversForTests) {
try { observer(entry); } catch { /* test observation must never fail request logging */ }
}
try {
// Failure diagnostics survive the 200-entry ring buffer by riding the persisted
// usage entry (devlog/_plan/260716_claudecode_hardening/030). Success rows stay
// in their existing shape; the >=400 gate deliberately includes 499 client-cancels.
const failureDiagnostics = entry.status >= 400 || (entry.terminalStatus && entry.terminalStatus !== "completed")
? {
...(entry.errorCode ? { errorCode: entry.errorCode } : {}),
...(entry.terminalStatus ? { terminalStatus: entry.terminalStatus } : {}),
...(entry.closeReason ? { closeReason: entry.closeReason } : {}),
...(entry.upstreamCondition ? { upstreamCondition: entry.upstreamCondition } : {}), ...(entry.failureDetail ? { failureDetail: entry.failureDetail } : {}),
...(entry.rateLimitResetAt !== undefined ? { rateLimitResetAt: entry.rateLimitResetAt } : {}),
}
: {};
appendUsageEntry({
requestId: entry.requestId,
...(isLogicalRequestId(entry.logicalRequestId) ? { logicalRequestId: entry.logicalRequestId } : {}),
timestamp: entry.timestamp,
provider: entry.provider,
model: entry.model,
client: entry.client ?? "unknown",
...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
// This function REBUILDS the persisted row field by field rather than
// spreading it, so a field missing here reaches /api/logs and never
// reaches usage.jsonl — which is where the per-key rollup reads from.
...(entry.apiKeyId ? { apiKeyId: entry.apiKeyId } : {}),
...(isKnownAdmissionKind(entry.admissionKind) ? { admissionKind: entry.admissionKind } : {}),
...(isKnownInboundProtocol(entry.inboundProtocol) ? { inboundProtocol: entry.inboundProtocol } : {}), ...linkLogField(entry.link), ...requestBodyField(entry.requestBody),
...(isCodexUsageAccountLogLabel(entry.accountLogLabel)
? { accountLogLabel: entry.accountLogLabel }
: {}),
...(isAnthropicAccountTag(entry.accountTag) ? { accountTag: entry.accountTag } : {}),
...(entry.conversationId ? { conversationId: entry.conversationId } : {}),
...(entry.resolvedModel ? { resolvedModel: entry.resolvedModel } : {}),
...(entry.servedModel ? { servedModel: entry.servedModel } : {}),
...(entry.wireModel ? { wireModel: entry.wireModel } : {}),
...(entry.requestedModel ? { requestedModel: entry.requestedModel } : {}),
...(entry.requestedAlias ? { requestedAlias: entry.requestedAlias } : {}),
...(entry.shadowCallRewrittenFrom
? { shadowCallRewrittenFrom: entry.shadowCallRewrittenFrom }
: {}),
...(entry.requestedEffort ? { requestedEffort: entry.requestedEffort } : {}),
...(entry.effectiveEffort ? { effectiveEffort: entry.effectiveEffort } : {}),
...(entry.reasoningWireField ? { reasoningWireField: entry.reasoningWireField } : {}),
...(entry.reasoningWireValue !== undefined ? { reasoningWireValue: entry.reasoningWireValue } : {}),
...(entry.callerServiceTier ? { callerServiceTier: entry.callerServiceTier } : {}),
...(entry.requestedServiceTier ? { requestedServiceTier: entry.requestedServiceTier } : {}),
...(entry.requestedSpeedLabel ? { requestedSpeedLabel: entry.requestedSpeedLabel } : {}),
...(entry.configuredServiceTier ? { configuredServiceTier: entry.configuredServiceTier } : {}),
...(entry.configuredSpeedLabel ? { configuredSpeedLabel: entry.configuredSpeedLabel } : {}),
...(entry.modelSupportsServiceTier !== undefined
? { modelSupportsServiceTier: entry.modelSupportsServiceTier }
: {}),
...(entry.responseServiceTier ? { responseServiceTier: entry.responseServiceTier } : {}),
...(entry.tierOutcome ? { tierOutcome: entry.tierOutcome } : {}),
status: entry.status,
durationMs: entry.durationMs,
...(entry.firstOutputMs !== undefined ? { firstOutputMs: entry.firstOutputMs } : {}),
...(entry.genStartMs !== undefined ? { genStartMs: entry.genStartMs } : {}),
...(entry.lastOutputMs !== undefined ? { lastOutputMs: entry.lastOutputMs } : {}),
usageStatus: entry.usageStatus,
...(entry.usage ? { usage: entry.usage } : {}),
...(entry.totalTokens !== undefined ? { totalTokens: entry.totalTokens } : {}),
...(entry.attempts !== undefined ? { attempts: entry.attempts } : {}),
...(entry.attemptNormalizationDropped === true
? { attemptNormalizationDropped: true } : {}),
...(entry.spend ? { spend: entry.spend } : {}),
...(isKnownCacheTelemetryProvenance(entry.cacheProvenance)
? { cacheProvenance: entry.cacheProvenance }
: {}),
...persistedAffinityFields(entry),
...persistedCacheAffinityFields(entry),
...(isKnownTransportPhase(entry.transportPhase) ? { transportPhase: entry.transportPhase } : {}),
...(isKnownTerminalSource(entry.terminalSource) ? { terminalSource: entry.terminalSource } : {}),
...failureDiagnostics,
// Rebuilt explicitly, like every other field here: this function does not spread the
// entry, so a pair omitted at this line would reach /api/logs and never reach
// usage.jsonl, which is the surface the derived failure projection reads.
...normalizeRequestFailureAttribution(entry),
...(entry.routeDecision ? { routeDecision: entry.routeDecision } : {}),
...(entry.jevDecision ? { jevDecision: entry.jevDecision } : {}),
...(entry.claudeCompatibility ? { claudeCompatibility: entry.claudeCompatibility } : {}),
...(entry.protocolTrace ? { protocolTrace: entry.protocolTrace } : {}),
...(entry.conversationStateScrub === "account-change"
? { conversationStateScrub: "account-change" }
: {}),
});
} catch {
/* request logging must never fail a user request */
}
}
/** Test-only finalized-row observation without polling the management projection. */
export function observeRequestLogsForTests(observer: (entry: RequestLogEntry) => void): () => void {
requestLogObserversForTests.add(observer);
return () => { requestLogObserversForTests.delete(observer); };
}
export function nextRequestLogId(_timestamp = Date.now()): string {
return `ocx-${randomBytes(16).toString("hex")}`;
}
/**
* One-shot TTFT recorder (WP4). Records the first non-empty model output moment
* relative to the request start, and — when a combo attempt is in flight —
* relative to that attempt's start as well. Later calls are no-ops, so both the
* bridge callback and the deferred SSE tap may fire without double-recording.
*/
export function recordFirstOutput(
logCtx: RequestLogContext,
requestStartedAt: number,
now = Date.now(),
): void {
if (!Number.isFinite(requestStartedAt) || !Number.isFinite(now)) return;
const requestElapsed = Math.max(0, now - requestStartedAt);
if (logCtx.firstOutputMs === undefined) logCtx.firstOutputMs = requestElapsed;
if (logCtx.activeAttempt && !sealedCredentialRefusals.has(logCtx.activeAttempt) && logCtx.activeAttempt.firstOutputMs === undefined) {
const attemptStartedAt = logCtx.activeAttemptStartedAt ?? requestStartedAt;
logCtx.activeAttempt.firstOutputMs = Math.max(0, now - attemptStartedAt);
}
}
/** Snapshot target-specific requested effort even for runTurn adapters with no AdapterRequest. */
export function recordAttemptRequestedEffort(logCtx: RequestLogContext): void {
const attempt = logCtx.activeAttempt;
if (!attempt || sealedCredentialRefusals.has(attempt)) return;
delete attempt.requestedEffort;
try {
if (typeof logCtx.requestedEffort === "string" && logCtx.requestedEffort) {
attempt.requestedEffort = redactSecretString(logCtx.requestedEffort).slice(0, 64);
}
} catch {
// Request logging is best-effort and must not affect request delivery.
}
}
/** Copy the adapter's exact outbound reasoning parameter into the durable request log. */
export function recordAdapterReasoning(
logCtx: RequestLogContext,
request: AdapterRequest,
): void {
if (logCtx.activeAttempt && sealedCredentialRefusals.has(logCtx.activeAttempt)) return;
delete logCtx.effectiveEffort;
delete logCtx.reasoningWireField;
delete logCtx.reasoningWireValue;
const attempt = logCtx.activeAttempt;
if (attempt) {
delete attempt.effectiveEffort;
delete attempt.reasoningWireField;
delete attempt.reasoningWireValue;
}
recordAttemptRequestedEffort(logCtx);
// Diagnostics must never make an otherwise valid upstream request fail. Config files
// written by older versions (or edited by hand) can contain values that violate the
// current TypeScript shape, so validate the runtime object before redacting strings.
try {
const raw: unknown = request.reasoningLog;
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
const reasoning = raw as Record<string, unknown>;
if (typeof reasoning.effectiveEffort !== "string" || !reasoning.effectiveEffort
|| (reasoning.wireField !== "reasoning_effort"
&& reasoning.wireField !== "reasoning.enabled"
&& reasoning.wireField !== "reasoning.effort"
&& reasoning.wireField !== "thinking_budget"
&& reasoning.wireField !== "thinking.type")
|| !isValidReasoningWireValue(reasoning.wireField, reasoning.wireValue)) {
return;
}
const effectiveEffort = redactSecretString(reasoning.effectiveEffort).slice(0, 64);
const wireValue = typeof reasoning.wireValue === "string"
? redactSecretString(reasoning.wireValue).slice(0, 64)
: reasoning.wireValue;
logCtx.effectiveEffort = effectiveEffort;
logCtx.reasoningWireField = reasoning.wireField;
logCtx.reasoningWireValue = wireValue;
if (attempt) {
attempt.effectiveEffort = effectiveEffort;
attempt.reasoningWireField = reasoning.wireField;
attempt.reasoningWireValue = wireValue;
}
} catch {
// Request logging is best-effort and must not affect request delivery.
}
}
/** Attach the serializing adapter's tier observation to the active durable attempt. */
export function recordAdapterTier(
logCtx: RequestLogContext,
request: AdapterRequest,
): void {
recordAdapterTierMetadata(logCtx, request.tierLog);
}
/** Attach adapter-owned metadata for transports that expose no AdapterRequest (runTurn). */
export function recordAdapterTierMetadata(
logCtx: RequestLogContext,
metadata: AdapterTierMetadata | undefined,
): void {
if (logCtx.activeAttempt && sealedCredentialRefusals.has(logCtx.activeAttempt)) return;
delete logCtx.tierOutcome;
delete logCtx.activeTierMetadata;
const attempt = logCtx.activeAttempt;
if (attempt) delete attempt.tierOutcome;
try {
const outcome = metadata?.outcome;
if (!metadata || !outcome) return;
logCtx.tierOutcome = outcome;
logCtx.activeTierMetadata = metadata;
if (attempt) attempt.tierOutcome = outcome;
} catch {
// Request logging is best-effort and must not affect request delivery.
}
}
export function requestLogErrorCode(
status: number,
upstreamError?: string,
terminalErrorCode?: string,
replayRefusal = false,
): string | undefined {
if (status >= 200 && status < 400) return undefined;
// A structured terminal code is authoritative even when the provider message is localized,
// generic, or absent. Only preserve the one narrowly recognized policy code here: broadly
// forwarding arbitrary upstream codes would change unrelated request-log taxonomy.
if (isCyberPolicyCode(terminalErrorCode)) return CYBER_POLICY_ERROR_CODE;
const classifiedCode = upstreamError?.trim()
? classifyError(status, "upstream_error", upstreamError).code
: undefined;
// Defense in depth: mid-stream web-search aborts used to land as 502 with this message.
if (status === 499 || classifiedCode === "client_closed_request") {
return "client_closed_request";
}
// Keep the high-confidence message fallback for runtimes/providers that stripped the
// structured code before emitting response.failed.
if (classifiedCode === CYBER_POLICY_ERROR_CODE) return CYBER_POLICY_ERROR_CODE;
if (status === 400 || status === 409) return "invalid_request_error";
if (status === 401) return "invalid_api_key";
if (status === 403) {
// Prefer message-aware codes (e.g. Ollama Cloud subscription gates) over a blunt
// invalid_api_key — 403 usually means authenticated but not allowed.
if (upstreamError?.trim()) {
const code = classifyError(403, "upstream_error", upstreamError).code;
if (code) return code;
}
return "permission_denied";
}
if (status === 429) {
// Prefer transport provenance; retain the legacy message fallback for older callers.
if (replayRefusal || (upstreamError?.trim() && isUpstreamResetReplayRefusedMessage(upstreamError))) {
return UPSTREAM_RESET_REPLAY_REFUSED_CODE;
}
return "rate_limit_exceeded";
}
if (status === 503) return "server_is_overloaded";
if (status >= 500) return "upstream_server_error";
return `http_${status}`;
}
export function requestLogSpeedLabel(serviceTier: string | undefined): string | undefined {
const normalized = serviceTier?.trim().toLowerCase();
if (normalized === "priority" || normalized === "fast") return "fast";
// Ultra Fast is labelled even though nothing in the shipped catalog advertises it: the
// reporter on #3429 reached it by hand-editing their own catalog, the request completed,
// and the Logs column stayed empty because this returned undefined. A tier the proxy
// forwarded but refuses to name is an observability hole, not a feature gate — the flag
// decides whether the tier survives, not whether we admit to carrying it.
if (normalized === "ultrafast") return "ultrafast";
return undefined;
}
export function readConfiguredCodexServiceTier(): string | undefined {
try {
if (!existsSync(CODEX_CONFIG_PATH)) return undefined;
return readRootTomlString(readFileSync(CODEX_CONFIG_PATH, "utf-8"), "service_tier") ?? undefined;
} catch {
return undefined;
}
}
export function catalogModelSupportsServiceTier(modelId: string, serviceTier: string | undefined): boolean | undefined {
if (!serviceTier) return undefined;
const requestTier = serviceTier.trim().toLowerCase() === "fast" ? "priority" : serviceTier.trim();
try {
const catalogPath = readCodexCatalogPath();
if (!existsSync(catalogPath)) return undefined;
const catalog = JSON.parse(readFileSync(catalogPath, "utf-8")) as { models?: unknown };
const models = Array.isArray(catalog.models) ? catalog.models : [];
const entry = models.find(model => {
if (!model || typeof model !== "object") return false;
return (model as { slug?: unknown; id?: unknown }).slug === modelId
|| (model as { slug?: unknown; id?: unknown }).id === modelId;
});
if (!entry || typeof entry !== "object") return undefined;
const tiers = (entry as { service_tiers?: unknown }).service_tiers;
return Array.isArray(tiers) && tiers.some(tier => (
tier && typeof tier === "object" && (tier as { id?: unknown }).id === requestTier
));
} catch {
return undefined;
}
}
export function applyResponseLogMetadata(logCtx: RequestLogContext, payload: unknown, collectUsage = true): void {
if (!payload || typeof payload !== "object") return;
if (logCtx.observedTerminalStatus === undefined) {
const eventType = (payload as { type?: unknown }).type;
const response = (payload as { response?: unknown }).response;
const responseStatus = response && typeof response === "object"
? (response as { status?: unknown }).status
: (payload as { status?: unknown }).status;
if (eventType === "response.completed") {
logCtx.observedTerminalStatus = responsesCompletionError(payload) == null ? "completed" : "failed";
} else if (eventType === "response.failed") {
logCtx.observedTerminalStatus = "failed";
} else if (eventType === "response.incomplete") {
logCtx.observedTerminalStatus = "incomplete";
} else if (responseStatus === "completed" || responseStatus === "failed" || responseStatus === "incomplete") {
logCtx.observedTerminalStatus = responseStatus;
}
}
const source = "response" in payload && typeof (payload as { response?: unknown }).response === "object"
? (payload as { response?: unknown }).response
: payload;
if (!source || typeof source !== "object") return;
recordObservedServedModel(logCtx, (source as { model?: unknown }).model);
const serviceTier = (source as { service_tier?: unknown }).service_tier;
if (typeof serviceTier === "string" && serviceTier.trim()) {
const sanitized = boundedServiceTier(serviceTier);
if (sanitized) logCtx.responseServiceTier = sanitized;
logCtx.activeTierMetadata?.observeResponseServiceTier(serviceTier);
} else if (Object.prototype.hasOwnProperty.call(source, "service_tier")) {
logCtx.activeTierMetadata?.observeResponseServiceTier(serviceTier);
}
const usage = collectUsage && !logCtx.usageFromBridge && !logCtx.clientResponseUsage
? usageFromResponsesPayload((source as { usage?: unknown }).usage) : undefined;
if (usage) {
if (!recordKeyWireAttemptUsage(logCtx, usage)) {
logCtx.usage = usage;
if (logCtx.activeAttempt && !sealedCredentialRefusals.has(logCtx.activeAttempt)) logCtx.activeAttempt.usage = usage;
}
// Counts taken off a wire, not reported raw. The zero-default token-detail objects strict
// clients require are indistinguishable here from a measured zero, so the cache detail these
// counts carry is recorded as synthesized rather than as an observed miss.
logCtx.usageWireParsed = true;
}
}
export function usageFromResponsesPayload(usage: unknown): OcxUsage | undefined {
if (!usage || typeof usage !== "object") return undefined;
const raw = usage as {
input_tokens?: unknown;
output_tokens?: unknown;
input_tokens_details?: { cached_tokens?: unknown; cache_write_tokens?: unknown; cache_write_1h_tokens?: unknown };
output_tokens_details?: { reasoning_tokens?: unknown };
total_tokens?: unknown;
prompt_tokens?: unknown;
completion_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") {
return {
inputTokens: raw.input_tokens,
outputTokens: raw.output_tokens,
...(typeof raw.total_tokens === "number" ? { totalTokens: raw.total_tokens } : {}),
...(typeof raw.input_tokens_details?.cached_tokens === "number"
? {
cachedInputTokens: raw.input_tokens_details.cached_tokens,
cacheReadInputTokens: 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.input_tokens_details?.cache_write_1h_tokens === "number"
? { cacheCreation1hInputTokens: raw.input_tokens_details.cache_write_1h_tokens }
: {}),
...(typeof raw.output_tokens_details?.reasoning_tokens === "number"
? { reasoningOutputTokens: raw.output_tokens_details.reasoning_tokens }
: {}),
};
}
if (typeof raw.prompt_tokens === "number" && typeof raw.completion_tokens === "number") {
return {
inputTokens: raw.prompt_tokens,
outputTokens: raw.completion_tokens,
...(typeof raw.total_tokens === "number" ? { totalTokens: raw.total_tokens } : {}),
...(typeof raw.prompt_tokens_details?.cached_tokens === "number"
? {
cachedInputTokens: raw.prompt_tokens_details.cached_tokens,
cacheReadInputTokens: 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 }
: {}),
};
}
return undefined;
}
/**
* Mark a refusal this proxy synthesized locally. Sets origin to `synthetic` and a
* distinct local reason so the request log cannot be read as an upstream overload.
*/
// Typed by the two fields it writes rather than by the whole context: the durable-spend tracker
// has to mark a row from a narrow view of it, and widening that view to the full context there
// would pull the entire log shape into a module that touches two of its fields.
export function markLocalRequestLogRefusal(
logCtx: Pick<RequestLogContext, "localTerminalReason" | "terminalSource">,
reason: string,
): void {
logCtx.localTerminalReason = reason;
logCtx.terminalSource = "synthetic";
}
export function inspectResponseLogJson(logCtx: RequestLogContext, text: string): void {
try {
applyResponseLogMetadata(logCtx, JSON.parse(text));
} catch {
logCtx.activeTierMetadata?.markResponseUnparseable();
/* 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);
}
}
export function inspectResponseLogSsePayload(logCtx: RequestLogContext, payload: string | null): void {
if (!payload || payload.trim() === "[DONE]") return;
let parsed: unknown | undefined;
try {
parsed = JSON.parse(payload);
} catch {
/* SSE block payload may not be JSON; metadata inspection is best-effort */
}
inspectResponseLogSsePayloadParsed(logCtx, payload, parsed);
}
/** Inspect an SSE payload using the caller's single best-effort JSON parse. */
export function inspectResponseLogSsePayloadParsed(
logCtx: RequestLogContext,
payload: string | null,
parsed: unknown | undefined,
collectUsage = true,
): void {
if (!payload || payload.trim() === "[DONE]") return;
const debugEnabled = isUsageDebugEnabled();
const sseAlreadyMarked = logCtx.usageDebugBodyKind === "sse";
if (parsed !== undefined) recordGenerationEvent(logCtx, (parsed as { type?: unknown } | null)?.type);
if (parsed !== undefined) applyResponseLogMetadata(logCtx, parsed, collectUsage);
else logCtx.activeTierMetadata?.markResponseUnparseable();
captureUpstreamErrorParsed(logCtx, payload, parsed, true);
if (debugEnabled) {
if (!sseAlreadyMarked) {
logCtx.usageDebugBodyKind = "sse";
logCtx.usageDebugBodySample = truncateForDebug(payload);
} else if (typeof logCtx.usageDebugBodySample === "string"
&& logCtx.usageDebugBodySample.length < USAGE_DEBUG_BODY_SAMPLE_BYTES) {
const combined = `${logCtx.usageDebugBodySample}\n${payload}`;
logCtx.usageDebugBodySample = truncateForDebug(combined);
}
}
}
/**
* 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) return;
let parsed: unknown | undefined;
try {
parsed = JSON.parse(text);
} catch {
/* retain the raw malformed payload for the bounded fallback below */
}
captureUpstreamErrorParsed(logCtx, text, parsed);
}
function captureUpstreamErrorParsed(
logCtx: RequestLogContext,
text: string,
parsed: unknown | undefined, untypedSse = false,
): void {
if (parsed !== undefined && parsed !== null) {
const json = parsed as UpstreamErrorPayload;
if (!captureUpstreamTerminalDiagnostics(logCtx, json, untypedSse)) return;
const reason = json?.response?.incomplete_details?.reason;
if (json.type === "response.incomplete"
&& logCtx.terminalIncompleteReason === undefined
&& typeof reason === "string"
&& reason.trim()) {
logCtx.terminalIncompleteReason = reason.trim();
}
if (logCtx.upstreamError) return;
const message = upstreamErrorMessageFromPayload(parsed);
if (typeof message === "string" && message.trim()) {
logCtx.upstreamError = guardedRowCopy(logCtx, message);
return;
}
// No human-readable error message: fall back to the structured incomplete reason emitted by
// the bridge on a stall-timeout or adapter EOF (response.incomplete). Maps the raw reason to a
// reader-facing label so a generic 502 in /api/logs explains WHY the turn ended, not just the
// mapped HTTP code.
if (typeof reason === "string" && reason.trim()) {
const incomplete = incompleteReasonDetail(reason.trim()); // A known reason also gets a closed row detail.
logCtx.upstreamError = guardedRowCopy(logCtx, incomplete.text);
if (incomplete.detail) logCtx.failureDetail = incomplete.detail;
}
return;
}
if (logCtx.upstreamError) return;
const trimmed = text.trim();
if (trimmed) {
logCtx.upstreamError = guardedRowCopy(logCtx, trimmed);
}
}
/** 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 === "incomplete" && (logCtx?.terminalHttpStatus === 429 || logCtx?.terminalHttpStatus === 402)) {
return logCtx.terminalHttpStatus;
}
/**
* [Decision Log]
* - 목적과 의도: Keep request logs aligned with the successful HTTP/SSE contract.
* - 기존 구현 및 제약 조건: All incomplete terminals were recorded as 502 even when the
* client-requested output limit was reached normally.
* - 검토한 주요 대안: Treat every incomplete as success, or infer the reason from display text.
* - 선택한 방식: Only structured max_output_tokens incompletes map to 200.
* - 다른 대안 대신 이 방식을 선택한 이유: Stall, EOF, and unknown incompletes must remain
* visible failures, and display text is not a stable classification contract.
* - 장점, 단점 및 영향: Logs stop reporting false upstream errors while retaining the
* incomplete terminal detail; native callers without a structured reason keep old behavior.
*/
if (status === "incomplete" && logCtx?.terminalIncompleteReason === "max_output_tokens") {
return 200;
}
if (status === "failed" && logCtx?.terminalHttpStatus !== undefined) {
return logCtx.terminalHttpStatus;
}
return httpStatusForTerminalStatus(status);
}
/**
* Aggregate one logical request's upstream spend from the rows that recorded it.
*
* Attempts are the accounting source and combo children are attempts of the same context, so a
* sum over `logCtx.attempts` is the send count for one user turn — the number the amplification
* in #4546 is measured in. A terminal status is what makes a send explainable, so the split is
* drawn there rather than at success: a 502 is settled spend, an attempt abandoned in flight is
* not. The budget's own counter is folded in as `reserved` because a leg that re-sent without
* opening an attempt row is charged and unobserved, and that difference belongs in
* `unresolved` rather than quietly inflating `settled`.
*/
export function requestSpendRecord(
logCtx: Pick<RequestLogContext, "executionBudget" | "affinityMoveReasons" | "affinityReason" | "affinity">,
attempts: readonly PersistedUsageAttempt[] | undefined,
): PersistedRequestSpend | undefined {
const rows = attempts ?? [];
const budget = logCtx.executionBudget;
const reasons = [...new Set(
(logCtx.affinityMoveReasons ?? (logCtx.affinity !== "unbound" && logCtx.affinityReason ? [logCtx.affinityReason] : []))
.filter(isKnownAffinityReason),
)];
if (rows.length === 0 && !budget && reasons.length === 0) return undefined;
const sends = rows.reduce((total, attempt) => total + attempt.sendCount, 0);
const settled = rows.reduce(
(total, attempt) => attempt.status >= 100 ? total + attempt.sendCount : total,
0,
);
const charged = Math.max(sends, budget?.used ?? 0);
return {
sends,
settled,
unresolved: Math.max(0, charged - settled),
...(budget ? { reserved: budget.used, policyVersion: budget.policyVersion } : {}),
...(reasons.length > 0 ? { moveReasons: reasons } : {}),
};
}
/**
* Record an affinity decision so both the row's final answer and the sequence survive. A request
* that moved for `quota_refusal` and then again for `transient` paid for two discarded prefixes,
* and the single-valued field can only report the second.
*/
export function noteAffinityMove(
logCtx: RequestLogContext,
move: CodexAffinityMove,
reason: CodexAffinityReason,
): void {
logCtx.affinity = move;
logCtx.affinityReason = reason;
(logCtx.affinityMoveReasons ??= []).push(reason);
}
/**
* Copy the selection's own affinity decision onto the request log. Both Pool-served kinds carry
* one: a stored Pool account and the main login rotating as `main-pool` (#4546, #7799). A keyed
* caller-owned main can also carry one. A move reads as an event with its cause.
*/
export function noteCodexSelectionAffinity(logCtx: RequestLogContext, authCtx: CodexAuthContext): void {
const decision = authCtx.affinityDecision;
if (!decision) return;
logCtx.affinity = decision.move;
logCtx.affinityReason = decision.reason;
}
/**
* The affinity scope a released binding belonged to: one thread, one model lane.
*
* Both halves are part of the key. A thread holds a separate binding per model lane, so a
* quota refusal on one lane and a transient streak on another are two releases; keyed by thread
* alone the second overwrites the first and one of the two rows reports a cause that never
* happened on it.
*/
export interface AffinityModelLane {
model: string;
/** Thread/conversation that owns the binding; omitted when the caller has no thread identity. */
conversationId?: string;
}
/**
* Release reasons waiting for the request that can report them (#4546, #4598).
*
* Bounded like the routing-side map it mirrors: this is a diagnostic, and an unbounded map keyed
* by conversation is a leak.
*/
const pendingNoAccountReasons = new Map<string, CodexAffinityReason>();
const MAX_PENDING_NO_ACCOUNT_REASONS = 1024;
function affinityLaneKey(lane: AffinityModelLane): string {
return `${lane.conversationId ?? ""}\u0000${lane.model}`;
}
export function noteNoAccountAffinityReason(lane: AffinityModelLane, reason: CodexAffinityReason): void {
if (!isKnownAffinityReason(reason)) return;
const key = affinityLaneKey(lane);
if (!pendingNoAccountReasons.has(key) && pendingNoAccountReasons.size >= MAX_PENDING_NO_ACCOUNT_REASONS) {
const oldest = pendingNoAccountReasons.keys().next();
if (!oldest.done) pendingNoAccountReasons.delete(oldest.value);
}
pendingNoAccountReasons.set(key, reason);
}
/** Read and forget one lane's reason. Other lanes on the same thread keep theirs. */
export function takeNoAccountAffinityReason(lane: AffinityModelLane): CodexAffinityReason | undefined {
const key = affinityLaneKey(lane);
const reason = pendingNoAccountReasons.get(key);
if (reason !== undefined) pendingNoAccountReasons.delete(key);
return reason;
}
/** Test-only process-state reset for isolated harnesses. */
export function clearNoAccountAffinityReasonsForTests(): void {
pendingNoAccountReasons.clear();
}
/**
* Report a selection that produced no account, on the request that failed because of it.
*
* A no-account resolve reaches no auth context, so until now its cause was handed to whichever
* later resolve happened to succeed — and a pool that stays exhausted never produces one, leaving
* the failure permanently unexplained. Attaching the reason to THIS request's own record is what
* makes the failure self-describing: the row is written, persisted and hydrated like any other,
* and it survives a restart.
*
* Deliberately not a separate synthetic row. `/api/usage` counts one row as one request, so an
* extra event row would report a request that never existed and skew the very cost totals this
* work exists to make trustworthy.
*/
export function recordNoAccountAffinityFailure(
logCtx: RequestLogContext,
lane: AffinityModelLane,
reason?: CodexAffinityReason,
): CodexAffinityReason | undefined {
const resolved = isKnownAffinityReason(reason) ? reason : takeNoAccountAffinityReason(lane);
if (resolved === undefined) return undefined;
noteAffinityMove(logCtx, "cleared", resolved);
logCtx.errorCode ??= "codex_no_account";
return resolved;
}
// Attempt identity can change in place while a combo parent retains an older context copy.
// These objects own their usage even after a rotation to an unknown key identity.
const keyUsageOwners = new WeakSet<PersistedUsageAttempt>();
const keyWireUsageBaselines = new WeakMap<PersistedUsageAttempt, OcxUsage | undefined>();
function cloneKeyUsage(usage: OcxUsage | undefined): OcxUsage | undefined {
return usage ? { ...usage } : undefined;
}
/** Replace this physical send's wire snapshot against the pre-send baseline; repeats do not sum. */
export function recordKeyWireAttemptUsage(logCtx: RequestLogContext, usage: OcxUsage | undefined): boolean {
if (!usage) return false;
const attempt = logCtx.activeAttempt;
if (!attempt || sealedCredentialRefusals.has(attempt) || !keyUsageOwners.has(attempt) || !keyWireUsageBaselines.has(attempt)) return false;
const baseline = keyWireUsageBaselines.get(attempt);
const current = { ...usage };
attempt.usage = baseline
? aggregateAttemptUsage([
{ ...attempt, usage: baseline, usageStatus: baseline.estimated ? "estimated" : "reported" },
{ ...attempt, usage: current, usageStatus: current.estimated ? "estimated" : "reported" },
]).usage
: current;
logCtx.usage = attempt.usage;
return true;
}
type FinalRequestLogMetaArg = Pick<RequestLogEntry, "terminalStatus" | "closeReason">;
const finalRequestLogInterceptors = new WeakMap<RequestLogContext, (status: number, meta?: FinalRequestLogMetaArg) => void>();
/** Route inner final-log requests to an outer owner (native ingress) instead of writing them. */
export function interceptFinalRequestLog(logCtx: RequestLogContext, onRequest: (status: number, meta?: FinalRequestLogMetaArg) => void): void {
finalRequestLogInterceptors.set(logCtx, onRequest);
}
/** The outer owner's write: request-level status from the outer outcome, the physical attempt's from the inner one. */
export function commitInterceptedFinalRequestLog(
requestId: string, start: number, logCtx: RequestLogContext, status: number, meta: FinalRequestLogMetaArg | undefined,
attemptStatus: number, addLog: (entry: RequestLogEntry) => void = addRequestLog,
): void {
writeFinalRequestLog(requestId, start, logCtx, status, meta, addLog, attemptStatus);
}
export function addFinalRequestLog(
requestId: string,
start: number,
logCtx: RequestLogContext,
status: number,
meta?: Pick<RequestLogEntry, "terminalStatus" | "closeReason">,
addLog: (entry: RequestLogEntry) => void = addRequestLog,
): void {
const intercept = finalRequestLogInterceptors.get(logCtx);
if (intercept) { intercept(status, meta); return; }
writeFinalRequestLog(requestId, start, logCtx, status, meta, addLog); notifyLinkTurnFinal(logCtx, meta?.terminalStatus);
}
function writeFinalRequestLog(
requestId: string,
start: number,
logCtx: RequestLogContext,
status: number,
meta?: Pick<RequestLogEntry, "terminalStatus" | "closeReason">,
addLog: (entry: RequestLogEntry) => void = addRequestLog,
attemptStatus?: number,
): void {
// Mid-stream web-search aborts used to emit response.failed and land as 502/upstream_server_error.
// Prefer the client-close classification whenever the captured reason says so.
// A coordinated (attemptStatus) write carries an authoritative outer outcome; skip the heuristic.
const effectiveStatus = attemptStatus === undefined && status >= 500 && logCtx.upstreamError && isClientClosedMessage(logCtx.upstreamError)
? 499
: status;
// Locally assigned codes name proxy refusals that status and upstream text cannot reconstruct.
const errorCode = logCtx.errorCode ?? bareVerdictRowErrorCode(logCtx) ?? requestLogErrorCode(
effectiveStatus,
logCtx.upstreamError,
logCtx.terminalErrorCode,
logCtx.causeHint === "transport-ambiguous" && logCtx.terminalSource === "synthetic",
);
// A response.failed whose classified status is 499 is still a client cancel, not an upstream
// terminal failure — keep /api/logs closeReason aligned with that.
const closeReason = effectiveStatus === 499
? "client_cancel"
: meta?.closeReason;
const sealedRefusal = retainRefusedAccount(logCtx);
if (logCtx.activeAttempt && !sealedRefusal) {
finishRequestAttempt(
logCtx.activeAttempt,
attemptStatus ?? effectiveStatus,
Date.now() - (logCtx.activeAttemptStartedAt ?? start),
keyUsageOwners.has(logCtx.activeAttempt)
? logCtx.activeAttempt.usage
: logCtx.usage,
);
// The final row and its active physical attempt describe the same terminal. Preserve the
// semantic code on both so detailed attempt telemetry cannot regress to a generic status code.
const attemptErrorCode = attemptStatus === undefined ? errorCode : attemptStatus < 400 ? undefined
: logCtx.errorCode ?? bareVerdictRowErrorCode(logCtx) ?? requestLogErrorCode(attemptStatus, logCtx.upstreamError, logCtx.terminalErrorCode, false);
if (attemptErrorCode) logCtx.activeAttempt.errorCode = attemptErrorCode;
else delete logCtx.activeAttempt.errorCode;
}
// Derived and stamped in a sibling module, before the attempt snapshot below. Every input is
// a closed value; the open error strings are deliberately not among them.
const attribution = attributeFinalRequest({
status: effectiveStatus,
...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
...(closeReason ? { closeReason } : {}),
...(logCtx.transportPhase ? { transportPhase: logCtx.transportPhase } : {}),
...(logCtx.terminalSource ? { terminalSource: logCtx.terminalSource } : {}),
outputObserved: logCtx.firstOutputMs !== undefined,
...(logCtx.causeHint ? { causeHint: logCtx.causeHint } : {}),
locallyAnswered: logCtx.localTerminalReason !== undefined,
// A coordinated write derives the request pair from a copy and re-derives the attempt's own.
...(logCtx.activeAttempt ? { attempt: attemptStatus === undefined ? logCtx.activeAttempt : { ...logCtx.activeAttempt } } : {}),
});
if (attemptStatus !== undefined && logCtx.activeAttempt && !sealedRefusal) attributePhysicalAttempt(logCtx.activeAttempt);
// The one seam every request passes exactly once, whatever transport served it and however
// it ended. The ledger gives per-send usage precedence over terminal usage and keeps unknown
// physical spend unresolved.
logCtx.spendTracker?.settle(logCtx.usage);
const existing = finalizedUsage(
logCtx.providerAdapter ?? logCtx.provider,
logCtx.usage,
logCtx.usageLogInputTokens,
contextWindowForModel(logCtx.providerAdapter ?? logCtx.provider, logCtx.model),
logCtx.localTerminalReason !== undefined,
);
const attempts = logCtx.attempts?.map(attempt => ({
...attempt,
recoveryKinds: [...attempt.recoveryKinds],
...(attempt.recoveryWithheld?.length ? { recoveryWithheld: [...attempt.recoveryWithheld] } : {}),
...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
...(attempt.tierOutcome ? { tierOutcome: { ...attempt.tierOutcome } } : {}),
// Detached, like every mutable field beside it: the live summary keeps counting if the
// stream is still draining, and a shared reference would let a finalized row change after
// it was written.
...(attempt.deliverySummary ? { deliverySummary: { ...attempt.deliverySummary } } : {}),
}));
const isCombo = logCtx.comboId !== undefined && (attempts?.length ?? 0) > 0;
// Rotations split usage across attempts. A detached recovery can be the only send, with no
// active attempt or request-level usage. An ordinary single attempt keeps the row's usage.
const aggregate = attempts?.length && (isCombo || (logCtx.localTerminalReason === undefined
&& (attempts.length > 1 || (!logCtx.activeAttempt && attempts[0]?.usage))))
? aggregateAttemptUsage(attempts)
: null;
const loggedUsage = aggregate?.usage ?? existing.usage;
const usageStatus = aggregate?.status ?? existing.status;
const totalTokens = aggregate?.totalTokens ?? existing.totalTokens;
const spend = requestSpendRecord(logCtx, attempts);
const durationMs = Date.now() - start;
logCtx.requestMetricsRecorder?.recordFinalRequest({
...(logCtx.inboundProtocol ? { protocol: logCtx.inboundProtocol } : {}),
status: effectiveStatus,
durationMs,
...(logCtx.firstOutputMs !== undefined ? { firstOutputMs: logCtx.firstOutputMs } : {}),
...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
...(closeReason ? { closeReason } : {}),
...(attempts !== undefined ? { attempts } : {}),
...(spend ? { spendSends: spend.sends } : {}),
...(attribution.failureCause ? { failureCause: attribution.failureCause } : {}),
});
const cacheProvenance = classifyCacheTelemetryProvenance(loggedUsage, {
wireParsed: logCtx.usageWireParsed === true,
});
const logicalRequestId = logCtx.logicalRequestId ?? logCtx.executionBudget?.logicalRequestId;
const normalizedCacheValue = loggedUsage?.cacheReadInputTokens ?? loggedUsage?.cachedInputTokens;
cacheDiagnosticHooks()?.finalize({
requestId,
...(isLogicalRequestId(logicalRequestId) ? { logicalRequestId } : {}),
protocol: logCtx.inboundProtocol ?? "responses",
provider: logCtx.provider,
model: logCtx.model,
...(isCodexUsageAccountLogLabel(logCtx.accountLogLabel) ? { accountLogLabel: logCtx.accountLogLabel } : {}),
...(logCtx.affinity ? { affinityMove: logCtx.affinity } : {}),
...(logCtx.affinityReason ? { affinityReason: logCtx.affinityReason } : {}),
// loggedUsage carries the upstream cache counter by reference all the way from the
// adapter extraction for the native Responses route, so an undefined read here is a
// genuinely absent counter rather than a defaulted one.
...(normalizedCacheValue !== undefined ? { rawCacheCounterValue: normalizedCacheValue } : {}),
...(normalizedCacheValue !== undefined ? { normalizedCacheValue } : {}),
cacheProvenance,
...(logCtx.cacheDiagnosticDraft ? { draft: logCtx.cacheDiagnosticDraft } : {}),
});
// Provider cache affinity: this is the one seam every request passes exactly
// once with its terminal status, the credential that ultimately served (the
// entry id captured beside the account label at each stamp, rotations
// included), and cache usage already normalized from whichever adapter
// answered. A success binds or refreshes the conversation on that
// credential; a quota/auth terminal releases it so the next request is
// placed fresh instead of re-offered a credential that just refused.
finalizeProviderCacheAffinity(logCtx, effectiveStatus, logCtx.usage ?? loggedUsage);
// Sanitize at the logging layer, not only at the one call site that populates this today.
// The value originates in an upstream-supplied model id, so an unsanitized newline would
// let a single field forge a record boundary in any line-oriented log viewer. Doing it here
// means a future caller cannot reintroduce the hole by forgetting to sanitize first, and
// the in-memory /api/logs row matches what usage.jsonl already stores.
const shadowCallRewrittenFrom = sanitizeLogMetadataString(logCtx.shadowCallRewrittenFrom);
const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(logCtx.claudeCompatibility);
const jevDecision = normalizePersistedJevDecision(logCtx.jevDecision);
// Keyed by the live attempt objects, not the detached copies above.
const protocolTrace = protocolTraceForRequest(logCtx, logCtx.attempts);
// Projected before any writer (an injected one too): the row keeps only proxy-owned error facts.
reportCommittedTerminalCooldown(logCtx, meta, attempts, effectiveStatus);
addLog(projectErrorDetail({
requestId,
...(isLogicalRequestId(logicalRequestId) ? { logicalRequestId } : {}),
timestamp: start,
model: isCombo ? logCtx.requestedModel! : logCtx.model,
provider: isCombo ? "combo" : logCtx.provider,
client: normalizeRecordedClient(logCtx.client) ?? "unknown",
...(logCtx.surface ? { surface: logCtx.surface } : {}),
...(logCtx.apiKeyId ? { apiKeyId: logCtx.apiKeyId } : {}),
...(logCtx.admissionKind ? { admissionKind: logCtx.admissionKind } : {}),
...(logCtx.inboundProtocol ? { inboundProtocol: logCtx.inboundProtocol } : {}), ...linkLogField(logCtx.link), ...requestBodyLogField(logCtx),
...(logCtx.localTerminalReason
? { localTerminalReason: sanitizeLogMetadataString(logCtx.localTerminalReason) }
: {}),
...(isCodexUsageAccountLogLabel(logCtx.accountLogLabel)
? { accountLogLabel: logCtx.accountLogLabel }
: {}),
...anthropicAccountTagField(isCombo ? undefined : logCtx.provider),
...(logCtx.conversationId ? { conversationId: logCtx.conversationId } : {}),
...(logCtx.requestedModel ? { requestedModel: logCtx.requestedModel } : {}),
...(logCtx.requestedAlias ? { requestedAlias: logCtx.requestedAlias } : {}),
...(shadowCallRewrittenFrom ? { shadowCallRewrittenFrom } : {}),
...(logCtx.requestedEffort ? { requestedEffort: logCtx.requestedEffort } : {}),
...(logCtx.effectiveEffort ? { effectiveEffort: logCtx.effectiveEffort } : {}),
...(logCtx.reasoningWireField ? { reasoningWireField: logCtx.reasoningWireField } : {}),
...(logCtx.reasoningWireValue !== undefined ? { reasoningWireValue: logCtx.reasoningWireValue } : {}),
...(logCtx.callerServiceTier ? { callerServiceTier: logCtx.callerServiceTier } : {}),
...(logCtx.requestedServiceTier ? { requestedServiceTier: logCtx.requestedServiceTier } : {}),
...(logCtx.requestedSpeedLabel ? { requestedSpeedLabel: logCtx.requestedSpeedLabel } : {}),
...(logCtx.configuredServiceTier ? { configuredServiceTier: logCtx.configuredServiceTier } : {}),
...(logCtx.configuredSpeedLabel ? { configuredSpeedLabel: logCtx.configuredSpeedLabel } : {}),
...(logCtx.modelSupportsServiceTier !== undefined ? { modelSupportsServiceTier: logCtx.modelSupportsServiceTier } : {}),
...(logCtx.responseServiceTier ? { responseServiceTier: logCtx.responseServiceTier } : {}),
...((attempts?.at(-1)?.tierOutcome ?? logCtx.tierOutcome)
? { tierOutcome: attempts?.at(-1)?.tierOutcome ?? { ...logCtx.tierOutcome! } }
: {}),
...modelIdentityLogFields(logCtx),
status: effectiveStatus,
durationMs,
...(logCtx.firstOutputMs !== undefined ? { firstOutputMs: logCtx.firstOutputMs } : {}),
...generationWindowFields(logCtx, start),
...(errorCode ? { errorCode } : {}),
...(meta?.terminalStatus ? { terminalStatus: meta.terminalStatus } : {}),
...(closeReason ? { closeReason } : {}),
...(logCtx.upstreamError && !upstreamErrorIsLocal(logCtx) ? { upstreamError: logCtx.upstreamError } : {}), ...(logCtx.failureDetail ? { failureDetail: logCtx.failureDetail } : {}),
...(logCtx.upstreamCondition && !upstreamErrorIsLocal(logCtx) ? { upstreamCondition: logCtx.upstreamCondition } : {}),
// A local verdict's failed frame is proxy-authored; its code/type are not upstream diagnostics.
...(upstreamErrorIsLocal(logCtx) ? {} : upstreamDiagnosticLogFields(logCtx)), usageStatus,
...(loggedUsage ? { usage: loggedUsage } : {}),
...(totalTokens !== undefined ? { totalTokens } : {}),
...(attempts !== undefined ? { attempts } : {}),
...(spend ? { spend } : {}),
// "unknown" is recorded rather than omitted whenever usage exists: a row that reported tokens
// with no cache detail at all is a different fact from a row with no usage, and the summary
// has to refuse both as a hit-rate denominator.
...(loggedUsage || cacheProvenance !== "unknown" ? { cacheProvenance } : {}),
...(logCtx.affinity ? { affinity: logCtx.affinity } : {}),
...(logCtx.affinityReason ? { affinityReason: logCtx.affinityReason } : {}),
...(logCtx.cacheAffinity ? { cacheAffinity: logCtx.cacheAffinity } : {}),
...(logCtx.cacheAffinityReason ? { cacheAffinityReason: logCtx.cacheAffinityReason } : {}),
...(logCtx.conversationStateScrub === "account-change"
? { conversationStateScrub: "account-change" }
: {}),
...(logCtx.transportPhase ? { transportPhase: logCtx.transportPhase } : {}),
...(logCtx.terminalSource ? { terminalSource: logCtx.terminalSource } : {}),
...(logCtx.routeDecision ? { routeDecision: logCtx.routeDecision } : {}),
...(jevDecision ? { jevDecision } : {}),
...(claudeCompatibility ? { claudeCompatibility } : {}),
...(protocolTrace ? { protocolTrace } : {}),
...attribution,
}));
// Formatted from the finalized snapshot, so the ring shows exactly what the ledger holds.
for (const attempt of attempts ?? []) debugAttemptDeliverySummary(requestId, attempt);
if (isUsageDebugEnabled()) {
appendUsageDebug({
ts: Date.now(),
requestId,
provider: logCtx.provider,
model: logCtx.model,
upstreamContentType: logCtx.usageDebugContentType ?? null,
upstreamStatus: effectiveStatus,
bodyKind: logCtx.usageDebugBodyKind ?? "none",
bodySample: logCtx.usageDebugBodySample ?? "",
extractedUsage: loggedUsage ?? null,
});
}
}
interface FinalizedUsageResult {
usage?: OcxUsage;
status: UsageStatus;
totalTokens?: number;
}
/**
* Context window for the routed model, used to cap the token estimate (codex-router PR #140):
* a request the provider answered cannot have exceeded the window, so the estimate must never
* claim it did. The family is picked by the route ADAPTER, not the model id alone, because
* claude-family ids are shared between Kiro and Cursor with different windows. Kiro "auto" is
* a router with no fixed window and is never guessed; unknown adapters/models stay uncapped.
*/
function contextWindowForModel(adapter: string, modelId: string | undefined): number | undefined {
if (!modelId) return undefined;
if (adapter === "kiro" || adapter.startsWith("kiro-")) {
const normalized = normalizeKiroModelId(modelId);
if (normalized === "auto") return undefined;
return kiroObservedContextWindow(modelId)
?? modelRecordValue(KIRO_MODEL_CONTEXT_WINDOWS, modelId)
?? modelRecordValue(KIRO_MODEL_CONTEXT_WINDOWS, normalized);
}
if (adapter === "cursor" || adapter.startsWith("cursor-")) {
return inferCursorContextWindow(modelId);
}
if (adapter === "devin") {
return modelRecordValue(DEVIN_MODEL_CONTEXT_WINDOWS, modelId);
}
return undefined;
}
function finalizedUsage(
adapter: string,
usage: OcxUsage | undefined,
inputTokenEstimate: number | undefined,
contextWindow: number | undefined,
locallyAnswered = false,
): FinalizedUsageResult {
// The ESTIMATE itself is capped at the model's context window (codex-router PR #140). The
// combined value below keeps its max(inputTokens, estimate) behavior — a provider-reported
// positive count is never reduced by this cap, only the estimate that could substitute it.
const estimate = typeof inputTokenEstimate === "number"
&& Number.isFinite(inputTokenEstimate)
&& inputTokenEstimate >= 0
? capEstimateAtContextWindow(inputTokenEstimate, contextWindow)
: undefined;
const finalUsage = usageForFinalLog(adapter, usage, locallyAnswered);
const usageFallback = !finalUsage && estimate !== undefined
? { inputTokens: estimate, outputTokens: 0, estimated: true }
: undefined;
// The estimate is a floor under a count the adapter could only guess. A count the adapter read
// off the upstream's own usage frame stays exact: max() against a larger local estimate would
// replace it and mark it estimated.
const combinedInputTokens = finalUsage && !finalUsage.upstreamReported && estimate !== undefined
? Math.max(finalUsage.inputTokens, estimate)
: undefined;
const loggedUsage = finalUsage && combinedInputTokens !== undefined
? {
...finalUsage,
inputTokens: combinedInputTokens,
totalTokens: combinedInputTokens + finalUsage.outputTokens,
estimated: true,
}
: finalUsage
// When the adapter alone produced an estimated count and no local estimate
// exists, cap it at the context window — an adapter estimate above the window
// misleads the usage dashboard. The combined branch (above) already caps the
// ESTIMATE via capEstimateAtContextWindow, and Math.max preserves a real
// provider-reported count, so it needs no further reduction.
? (finalUsage.estimated && contextWindow !== undefined && finalUsage.inputTokens > contextWindow
? {
...finalUsage,
inputTokens: contextWindow,
totalTokens: contextWindow + finalUsage.outputTokens,
}
: finalUsage)
: usageFallback;
const totalTokens = usageTotalTokens(loggedUsage);
return {
status: usageStatusForFinalLog(loggedUsage),
...(loggedUsage ? { usage: loggedUsage } : {}),
...(totalTokens !== undefined ? { totalTokens } : {}),
};
}
export function beginRequestAttempt(
ordinal: number,
provider: string,
model: string,
adapter: string,
): PersistedUsageAttempt {
return {
ordinal,
provider,
model,
adapter,
status: 0,
durationMs: 0,
sendCount: 0,
recoveryKinds: [],
usageStatus: "unreported",
};
}
/** Add raw per-response usage before a bridge combines multiple rounds for the client. */
export function recordKeyAttemptUsage(logCtx: RequestLogContext, usage: OcxUsage | undefined): void {
const attempt = logCtx.activeAttempt;
if (!attempt || sealedCredentialRefusals.has(attempt) || !usage) return;
attempt.usage = attempt.usage
? aggregateAttemptUsage([{ ...attempt, usageStatus: attempt.usage.estimated ? "estimated" : "reported" },
{ ...attempt, usage, usageStatus: usage.estimated ? "estimated" : "reported" }]).usage
: { ...usage };
logCtx.usage = attempt.usage;
}
/** A stable active object lets combo/stream callbacks keep pointing at the final attempt.
* Earlier key segments are immutable, flat snapshots inserted before that active object. */
export function noteProviderAttemptSend(
logCtx: RequestLogContext,
providerName: string,
provider: OcxProviderConfig,
inputTokenEstimate: number | undefined,
recovery?: AttemptRecoveryKind,
resolved?: { model: string; adapter: string },
): void {
const attempt = logCtx.activeAttempt;
const previous = attempt?.accountLogLabel;
stampApiKeyAccountLabel(logCtx, providerName, provider);
const next = logCtx.accountLogLabel;
if (attempt && usesApiKeyAccount(provider)) keyUsageOwners.add(attempt);
const recoveryStatus = credentialRecoveryStatus(recovery);
if (attempt && attempt.sendCount > 0 && (sealedCredentialRefusals.has(attempt) || recoveryStatus !== undefined
|| attemptAccountChanged(previous, next, attempt.provider, logCtx.provider)
|| resolved && (attempt.model !== resolved.model || attempt.adapter !== resolved.adapter))) {
if (!sealedCredentialRefusals.delete(attempt)) {
delete attempt.inputTokenEstimate;
finishRequestAttempt(attempt, attempt.status >= 100 ? attempt.status
: recoveryStatus ?? (recovery === "rate-limit-429" ? 429 : 502),
Date.now() - (logCtx.activeAttemptStartedAt ?? Date.now()), attempt.usage);
// Finalization sees only the live segment, so attribute this refusal before snapshotting it.
attributeSealedAttempt(attempt, recovery);
}
const completed = { ...attempt, recoveryKinds: [...attempt.recoveryKinds],
...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
...(attempt.deliverySummary ? { deliverySummary: { ...attempt.deliverySummary } } : {}),
...(attempt.tierOutcome ? { tierOutcome: { ...attempt.tierOutcome } } : {}) };
const attempts = logCtx.attempts ??= [attempt];
const index = attempts.indexOf(attempt);
if (index >= 0) attempts.splice(index, 0, completed);
else attempts.push(completed, attempt);
const fresh = beginRequestAttempt(completed.ordinal + 1, providerName, completed.model, completed.adapter);
if (completed.labRouteSubjectId && completed.provider === logCtx.provider
&& (!resolved || (completed.model === resolved.model && completed.adapter === resolved.adapter))) {
fresh.labRouteSubjectId = completed.labRouteSubjectId;
}
// Effort/tier metadata describes the request and is captured before the physical send.
for (const key of ["requestedEffort", "effectiveEffort", "reasoningWireField", "reasoningWireValue"] as const) {
if (completed[key] !== undefined) Object.assign(fresh, { [key]: completed[key] });
}
// The response observer owns this live object; the sealed row keeps its snapshot.
if (attempt.tierOutcome) fresh.tierOutcome = attempt.tierOutcome;
for (const key of Object.keys(attempt)) delete (attempt as unknown as Record<string, unknown>)[key];
Object.assign(attempt, fresh);
delete logCtx.usage;
logCtx.activeAttemptStartedAt = Date.now();
}
if (attempt) {
if (resolved) { attempt.model = resolved.model; attempt.adapter = resolved.adapter; }
sealRequestAttemptIdentity(attempt, logCtx.provider, attempt.adapter, next);
recordAttemptCredentialSource(attempt, providerName, provider, attempt.adapter);
}
noteAttemptSend(attempt, inputTokenEstimate, recovery);
if (attempt && keyUsageOwners.has(attempt)) {
keyWireUsageBaselines.set(attempt, cloneKeyUsage(attempt.usage));
}
}
/** Capture only the resolved upstream route; inbound auth and today's config cannot label old usage. */
export function recordAttemptCredentialSource(
attempt: PersistedUsageAttempt | undefined,
providerName: string,
provider: Pick<OcxProviderConfig, "authMode" | "baseUrl" | "adapter">,
adapterName: string = provider.adapter,
): void {
if (!attempt || sealedCredentialRefusals.has(attempt)) return;
// Rebinding an attempt to an unrecognized route must not retain its previous attribution.
delete attempt.credentialSource;
if (providerName !== "xai"
|| !["openai-chat", "openai-responses"].includes(adapterName)) return;
try {
const url = new URL(provider.baseUrl ?? "");
if (url.protocol !== "https:" || url.port || url.username || url.password
|| url.search || url.hash || !["/v1", "/v1/"].includes(url.pathname)) return;
if (provider.authMode === "oauth" && url.hostname === "cli-chat-proxy.grok.com") {
attempt.credentialSource = "grok-oauth";
} else if ((provider.authMode === "key" || provider.authMode === undefined)
&& url.hostname === "api.x.ai") {
attempt.credentialSource = "xai-api-key";
}
} catch {
// Invalid/custom destinations have no known subscription provenance.
}
}
export function noteAttemptSend(
attempt: PersistedUsageAttempt | undefined,
inputTokenEstimate: number | undefined,
recovery?: AttemptRecoveryKind,
): void {
if (!attempt || sealedCredentialRefusals.has(attempt)) return;
attempt.sendCount += 1;
if (typeof inputTokenEstimate === "number"
&& Number.isFinite(inputTokenEstimate)
&& inputTokenEstimate >= 0) {
// Store the ESTIMATE field already capped at the model's window (codex-router PR #140):
// what gets persisted, and later merged into usage, never claims a count above the window.
attempt.inputTokenEstimate = capEstimateAtContextWindow(
inputTokenEstimate,
contextWindowForModel(attempt.adapter, attempt.model),
);
}
if (recovery && !attempt.recoveryKinds.includes(recovery)) {
attempt.recoveryKinds.push(recovery);
}
}
export function finishRequestAttempt(
attempt: PersistedUsageAttempt,
status: number,
durationMs: number,
usage?: OcxUsage,
): PersistedUsageAttempt {
if (sealedCredentialRefusals.has(attempt)) return attempt;
const finalized = finalizedUsage(
attempt.adapter,
usage ?? attempt.usage,
attempt.inputTokenEstimate,
contextWindowForModel(attempt.adapter, attempt.model),
attempt.locallyAnswered === true,
);
attempt.status = status;
attempt.durationMs = Math.max(0, durationMs);
attempt.usageStatus = finalized.status;
if (finalized.usage) attempt.usage = finalized.usage;
else delete attempt.usage;
if (finalized.totalTokens !== undefined) attempt.totalTokens = finalized.totalTokens;
else delete attempt.totalTokens;
const errorCode = requestLogErrorCode(status);
if (errorCode) attempt.errorCode = errorCode;
else delete attempt.errorCode;
return attempt;
}
export function getRequestLogEntries(): RequestLogEntry[] { return requestLog; }
/** Test-only process-state reset for isolated integration harnesses. */
export function clearRequestLogsForTests(): void {
requestLog.length = 0;
requestLogBytes = 0;
requestLogsHydratedFromDisk = false;
requestLogObserversForTests.clear();
}