@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/usage/log.ts

@@ -7,11 +7,36 @@ import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { sanitizeLogMetadataString } from "../lib/redact";
 import { usageDisplayTotalTokens } from "./totals";
+import { normalizeAttemptDeliverySummary } from "./attempt-delivery";
+import {
+  isRequestCloseReason,
+  isRequestTerminalStatus,
+  type RequestCloseReason,
+  type RequestTerminalStatus,
+} from "./request-outcome";
 import type { AttemptTierOutcome, OcxUsage } from "../types";
 import { normalizeRouteDecisionTrace, type RouteDecisionTraceV1 } from "../routing/trace";
 import { ACCOUNT_LOG_LABEL_RE, CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
 import { claudeCompatibilityReason, normalizeClaudeFeatureCodes, type ClaudeFeatureCode } from "../claude/compatibility";
 import type { CodexWsStageRecord } from "../server/responses/codex-ws-wire";
+import {
+  ATTEMPT_RECOVERY_KIND_ROSTER,
+  ATTEMPT_RECOVERY_WITHHELD_ROSTER,
+  REQUEST_FAILURE_CAUSES,
+  REQUEST_FAILURE_STAGES,
+  REQUEST_TRANSPORT_PHASES,
+  type AttemptRecoveryKind,
+  type AttemptRecoveryWithheld,
+  type AttemptDeliverySummary,
+  type RequestFailureCause,
+  type RequestFailureStage,
+  type RequestSpendTotals,
+} from "./telemetry-contract";
+
+// Re-exported so every existing importer keeps its path. The declarations moved to a leaf the
+// dashboard can import without pulling node:fs and the config barrel into the browser build.
+export { ATTEMPT_RECOVERY_KIND_ROSTER, ATTEMPT_RECOVERY_WITHHELD_ROSTER, REQUEST_FAILURE_CAUSES, REQUEST_FAILURE_STAGES };
+export type { AttemptRecoveryKind, AttemptRecoveryWithheld, RequestFailureCause, RequestFailureStage, RequestSpendTotals };
 
 export interface PersistedClaudeCompatibilityLog {
   decision: "shadow";
@@ -58,45 +83,6 @@ export function isCodexPoolAccountLogLabel(value: unknown): value is "main" | `p
   return value === "main" || (typeof value === "string" && CODEX_ACCOUNT_LOG_LABEL_RE.test(value));
 }
 
-/**
- * Recovery kinds recorded per attempt in the usage log; the GUI renders localized labels
- * for these wire values.
- */
-export type AttemptRecoveryKind =
-  | "transient-5xx"
-  | "connection-reset"
-  | "oauth-401"
-  | "key-401"
-  | "key-429"
-  | "rate-limit-429"
-  | "anthropic-oauth-429"
-  | "oauth-account-429"
-  | "image-413"
-  | "console-go-upload-retry"
-  | "opaque-blob-rejection"
-  | "empty-completion"
-  | "reasoning-effort-downgrade";
-
-/**
- * Why a recovery this request was otherwise willing to make did not happen.
- *
- * Recorded separately from `recoveryKinds` and from `sendCount`, because the question it
- * answers is different from either. A log showing one physical send and no recovery kind used
- * to be ambiguous: it could mean nothing was eligible, or that something was eligible and the
- * send budget withheld it. Those need opposite follow-ups, and the second one was invisible
- * (#5044).
- *
- * `sendCount` deliberately does not move for these. A refused attempt is not a physical send,
- * and inflating the count to signal the refusal would corrupt the one number that means
- * "requests this proxy actually made".
- *
- * Bounded vocabulary on purpose: it is a wire value a maintainer reads, never a credential, an
- * account id, an upstream body, prompt content, or exception text.
- */
-export type AttemptRecoveryWithheld =
-  | "retry-send-budget"
-  | "rotation-send-budget";
-
 /** Request-time upstream credential class, never a credential or account identifier. */
 export type UsageCredentialSource = "grok-oauth" | "xai-api-key";
 
@@ -200,6 +186,21 @@ export interface PersistedUsageAttempt {
    * account identifiers.
    */
   codexWsStage?: CodexWsStageRecord;
+  /**
+   * What this attempt delivered, as five bounded counts (#3983). Absent on attempts whose
+   * transport does not pass through the Responses bridge and on pre-instrumentation rows.
+   */
+  deliverySummary?: AttemptDeliverySummary;
+  /**
+   * How far this attempt's exchange got and why it failed, in the shared vocabulary (#2366).
+   *
+   * Both values are closed roster members, so the pair can be a metric label and a grouping key
+   * without a masking pass. Absent on a completed attempt and on every row written before the
+   * attribution existed. The resend verdict these two imply is NOT stored: it is derived at read
+   * time, so a stored row can never carry a verdict the current table would no longer reach.
+   */
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
 }
 
 /**
@@ -210,19 +211,7 @@ export interface PersistedUsageAttempt {
  * operator needs is the total that reached upstream carrying the full prompt. These fields are
  * that total, decomposed by how much of it is explained.
  */
-export interface PersistedRequestSpend {
-  /** Physical upstream sends summed across every attempt of this logical request, combo children included. */
-  sends: number;
-  /** Sends whose attempt reached a terminal status, so the spend has a known outcome. */
-  settled: number;
-  /**
-   * Sends charged with no terminal outcome behind them: an attempt abandoned mid-flight, or a
-   * budget charge no attempt row ever accounted for. Never folded into `settled` — an unexplained
-   * send is the exact quantity this record exists to make visible.
-   */
-  unresolved: number;
-  /** Model sends the request execution budget charged. Absent when no budget was attached. */
-  reserved?: number;
+export interface PersistedRequestSpend extends RequestSpendTotals {
   /** Budget profile that produced `reserved`, so a count can be read against the policy it obeyed. */
   policyVersion?: string;
   /**
@@ -329,8 +318,13 @@ export interface PersistedUsageEntry {
   // Failure diagnostics (devlog/_plan/260716_claudecode_hardening/030): persisted for
   // status>=400 or non-completed terminals so incidents survive the in-memory ring buffer.
   errorCode?: string;
-  terminalStatus?: string;
-  closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow";
+  /**
+   * Closed, like `closeReason` beside it has always been. It was `string` while it was only
+   * rendered; it is a grouping-key slot now, and the value is assembled from an upstream
+   * terminal frame, so an open type here is the one way upstream text could reach that key.
+   */
+  terminalStatus?: RequestTerminalStatus;
+  closeReason?: RequestCloseReason;
   /** Already redacted + capped at capture (request-log.ts redactSecretString().slice(0,500)). */
   upstreamError?: string;
   /** Where the terminal/failure was observed; absent on historic rows. */
@@ -357,6 +351,53 @@ export interface PersistedUsageEntry {
   routeDecision?: RouteDecisionTraceV1;
   /** Closed Claude protocol codes only; absent on older rows. */
   claudeCompatibility?: PersistedClaudeCompatibilityLog;
+  /**
+   * How far this request got and why it failed (#2366). Projected from the attempt that ended
+   * the request so every surface reads the answer off the same row. Absent on a completed
+   * request and on rows written before the attribution existed.
+   */
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
+}
+
+/**
+ * Attribution for the logical request, projected from the attempt that ended it (#2366).
+ *
+ * Carried on the entry as well as the attempt because the three surfaces that have to agree read
+ * the entry: a projection that had to reach into `attempts` to answer "why did this fail" would
+ * be reading a different row from the exporter, which is the disagreement the landed terminal
+ * classifier already removed once.
+ */
+export interface PersistedRequestFailureAttribution {
+  failureStage?: RequestFailureStage;
+  failureCause?: RequestFailureCause;
+}
+
+const KNOWN_REQUEST_FAILURE_STAGES: ReadonlySet<string> = new Set(REQUEST_FAILURE_STAGES);
+const KNOWN_REQUEST_FAILURE_CAUSES: ReadonlySet<string> = new Set(REQUEST_FAILURE_CAUSES);
+
+/**
+ * Same closed-set discipline as `isKnownTransportPhase`, with the set DERIVED from the roster
+ * rather than restated. The recovery vocabulary was written twice once -- as a union and as the
+ * read-back whitelist -- and a member present in only one of them is written to disk and dropped
+ * on the next read, which loses exactly the field that says why the row failed.
+ */
+export function isKnownRequestFailureStage(value: unknown): value is RequestFailureStage {
+  return typeof value === "string" && KNOWN_REQUEST_FAILURE_STAGES.has(value);
+}
+
+export function isKnownRequestFailureCause(value: unknown): value is RequestFailureCause {
+  return typeof value === "string" && KNOWN_REQUEST_FAILURE_CAUSES.has(value);
+}
+
+/** The stage/cause pair a normalizer keeps, dropping either half that is not a roster member. */
+export function normalizeRequestFailureAttribution(
+  raw: { failureStage?: unknown; failureCause?: unknown },
+): PersistedRequestFailureAttribution {
+  return {
+    ...(isKnownRequestFailureStage(raw.failureStage) ? { failureStage: raw.failureStage } : {}),
+    ...(isKnownRequestFailureCause(raw.failureCause) ? { failureCause: raw.failureCause } : {}),
+  };
 }
 
 const KNOWN_USAGE_SURFACES = new Set<NonNullable<PersistedUsageEntry["surface"]>>([
@@ -394,12 +435,10 @@ export function isKnownInboundProtocol(value: unknown): value is NonNullable<Per
   return typeof value === "string" && KNOWN_INBOUND_PROTOCOLS.has(value as NonNullable<PersistedUsageEntry["inboundProtocol"]>);
 }
 
-const KNOWN_TRANSPORT_PHASES = new Set<NonNullable<PersistedUsageEntry["transportPhase"]>>([
-  "pre_headers", "mid_stream", "terminal_sse",
-]);
+const KNOWN_TRANSPORT_PHASES: ReadonlySet<string> = new Set(REQUEST_TRANSPORT_PHASES);
 
 export function isKnownTransportPhase(value: unknown): value is NonNullable<PersistedUsageEntry["transportPhase"]> {
-  return typeof value === "string" && KNOWN_TRANSPORT_PHASES.has(value as NonNullable<PersistedUsageEntry["transportPhase"]>);
+  return typeof value === "string" && KNOWN_TRANSPORT_PHASES.has(value);
 }
 
 const KNOWN_TERMINAL_SOURCES = new Set<NonNullable<PersistedUsageEntry["terminalSource"]>>([
@@ -497,25 +536,8 @@ function normalizeUsageValue(usage: OcxUsage | undefined): OcxUsage | undefined
   };
 }
 
-const ATTEMPT_RECOVERY_KINDS = new Set<AttemptRecoveryKind>([
-  "transient-5xx",
-  "connection-reset",
-  "oauth-401",
-  "key-401",
-  "key-429",
-  "rate-limit-429",
-  "anthropic-oauth-429",
-  "oauth-account-429",
-  "image-413",
-  "console-go-upload-retry",
-  "opaque-blob-rejection",
-  "empty-completion",
-  "reasoning-effort-downgrade",
-]);
-const ATTEMPT_RECOVERY_WITHHELD = new Set<AttemptRecoveryWithheld>([
-  "retry-send-budget",
-  "rotation-send-budget",
-]);
+const ATTEMPT_RECOVERY_KINDS: ReadonlySet<AttemptRecoveryKind> = new Set(ATTEMPT_RECOVERY_KIND_ROSTER);
+const ATTEMPT_RECOVERY_WITHHELD: ReadonlySet<AttemptRecoveryWithheld> = new Set(ATTEMPT_RECOVERY_WITHHELD_ROSTER);
 const USAGE_STATUSES = new Set<UsageStatus>([
   "reported",
   "unreported",
@@ -643,6 +665,9 @@ function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
   const codexWsStage = "codexWsStage" in attempt
     ? normalizeCodexWsStageRecord(attempt.codexWsStage)
     : undefined;
+  const deliverySummary = "deliverySummary" in attempt
+    ? normalizeAttemptDeliverySummary(attempt.deliverySummary)
+    : undefined;
   const recoveryKinds = Array.isArray(attempt.recoveryKinds)
     ? [...new Set(attempt.recoveryKinds.filter(
       (value): value is AttemptRecoveryKind => typeof value === "string"
@@ -711,6 +736,8 @@ function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
       : {}),
     ...(tierOutcome ? { tierOutcome } : {}),
     ...(codexWsStage ? { codexWsStage } : {}),
+    ...(deliverySummary ? { deliverySummary } : {}),
+    ...normalizeRequestFailureAttribution(attempt),
   };
 }
 
@@ -882,11 +909,15 @@ function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
     ...(affinityReason ? { affinityReason } : {}),
     ...(conversationStateScrub ? { conversationStateScrub } : {}),
     ...(entry.errorCode ? { errorCode: entry.errorCode } : {}),
-    ...(entry.terminalStatus ? { terminalStatus: entry.terminalStatus } : {}),
-    ...(entry.closeReason ? { closeReason: entry.closeReason } : {}),
+    // Validated rather than copied on truthiness, like the inbound protocol and transport phase
+    // above. Harmless while these were only rendered; not harmless once the terminal status is
+    // a grouping-key slot, because the string is assembled from an upstream frame.
+    ...(isRequestTerminalStatus(entry.terminalStatus) ? { terminalStatus: entry.terminalStatus } : {}),
+    ...(isRequestCloseReason(entry.closeReason) ? { closeReason: entry.closeReason } : {}),
     ...(entry.upstreamError ? { upstreamError: entry.upstreamError } : {}),
     ...(routeDecision ? { routeDecision } : {}),
     ...(claudeCompatibility ? { claudeCompatibility } : {}),
+    ...normalizeRequestFailureAttribution(entry),
   };
 }
 
@@ -921,6 +952,20 @@ function ensureUsageLogDir(now: number): void {
   ensuredUsageLogDir = { path: dir, checkedAt: now };
 }
 
+/**
+ * One owner hook, run after an append lands.
+ *
+ * A slot rather than a direct call, because the only consumer -- ledger retention -- reads this
+ * module's revision helpers, and importing it back here would be a static cycle. The hook runs
+ * INSIDE the synchronous append call stack on purpose: that is what makes "no in-process append
+ * can interleave with a compaction" true rather than merely likely.
+ */
+let afterUsageLedgerAppend: (() => void) | null = null;
+
+export function setUsageLedgerAppendHook(hook: (() => void) | null): void {
+  afterUsageLedgerAppend = hook;
+}
+
 export function appendUsageEntry(entry: PersistedUsageEntry): void {
   const line = `${JSON.stringify(normalizeUsageEntry(entry))}\n`;
   const path = usageLogPath();
@@ -941,10 +986,12 @@ export function appendUsageEntry(entry: PersistedUsageEntry): void {
       ensuredUsageLogDir = null;
       ensuredUsageLogFile = null;
       doAppend();
+      afterUsageLedgerAppend?.();
       return;
     }
     throw error;
   }
+  afterUsageLedgerAppend?.();
 }
 
 export type UsageLogRevision = {

package/src/usage/request-outcome.ts

@@ -0,0 +1,150 @@
+/**
+ * One terminal classification for a finished logical request, and the counts that go with it.
+ *
+ * Three surfaces answer "how did this request end" and they used to answer it three different
+ * ways. The durable row carries `terminalStatus` and `closeReason`; the Prometheus exporter had
+ * its own private `classifyResult`; the dashboard read the numeric HTTP status and nothing else.
+ * That is not a cosmetic difference. A turn cut short by `max_output_tokens` is durably
+ * `status: 200, terminalStatus: "incomplete"`, which the exporter reports as `incomplete` and the
+ * dashboard rendered as a green 200 — the operator and the metric disagreed about whether the
+ * user got an answer.
+ *
+ * The fix is not a third classifier. It is this one, which the exporter imports, the management
+ * payload carries, and the dashboard renders, so agreement is structural rather than a rule
+ * someone has to keep.
+ *
+ * Leaf module: its only import is a type, erased at runtime.
+ */
+import type { RequestSpendTotals } from "./telemetry-contract";
+
+/**
+ * Ordered by how much of an answer the caller received. The order is not a ranking of severity;
+ * `aborted` is last because the caller chose it, not because it is the worst outcome.
+ */
+export const REQUEST_OUTCOME_CLASSES = Object.freeze([
+  /** A terminal event settled the turn and the caller received the answer. */
+  "completed",
+  /** The turn ended without an answer. */
+  "failed",
+  /** The turn produced part of an answer and stopped. */
+  "incomplete",
+  /** The caller went away before the turn finished. */
+  "aborted",
+] as const);
+
+export type RequestOutcomeClass = typeof REQUEST_OUTCOME_CLASSES[number];
+
+/**
+ * The terminal statuses a Responses turn can settle on.
+ *
+ * Derived from the outcome classes rather than restated: a turn reports whether it completed,
+ * failed or stopped short, and `aborted` is not one of them because the caller leaving is not a
+ * terminal the origin emits. Deriving it means a fifth outcome class cannot leave this list
+ * stale, and restating the three would be the same copy that let the recovery roster drift.
+ */
+export type RequestTerminalStatus = Exclude<RequestOutcomeClass, "aborted">;
+
+/**
+ * The same three members as a runtime list, filtered out of the outcome roster rather than
+ * typed out again, so the guard below cannot disagree with the type above it.
+ */
+export const REQUEST_TERMINAL_STATUSES: readonly RequestTerminalStatus[] = Object.freeze(
+  REQUEST_OUTCOME_CLASSES.filter((value): value is RequestTerminalStatus => value !== "aborted"),
+);
+
+/** Why the response body stopped being read. Closed, and persisted as such. */
+export const REQUEST_CLOSE_REASONS = Object.freeze([
+  "terminal",
+  "client_cancel",
+  "non_stream",
+  "body_stall",
+  "body_overflow",
+] as const);
+
+export type RequestCloseReason = typeof REQUEST_CLOSE_REASONS[number];
+
+/**
+ * Read-back guards for the two facts that reach a durable row as strings.
+ *
+ * `terminalStatus` was typed `string` on the persisted entry and copied through the normalizer
+ * on truthiness alone, unlike the inbound protocol, transport phase and terminal source beside
+ * it. That was harmless while the value was only rendered; it stops being harmless the moment
+ * the value becomes part of a grouping key, because the string is assembled from an upstream
+ * frame and an unvalidated one would put upstream-controlled text into the key.
+ */
+export function isRequestTerminalStatus(value: unknown): value is RequestTerminalStatus {
+  return typeof value === "string"
+    && (REQUEST_TERMINAL_STATUSES as readonly string[]).includes(value);
+}
+
+export function isRequestCloseReason(value: unknown): value is RequestCloseReason {
+  return typeof value === "string"
+    && (REQUEST_CLOSE_REASONS as readonly string[]).includes(value);
+}
+
+/**
+ * The facts a terminal classification is allowed to read.
+ *
+ * Deliberately narrow, and deliberately NOT the whole durable row: an outcome that could consult
+ * a provider name or an error message would be a different answer per provider, which is how the
+ * three surfaces drifted apart in the first place.
+ */
+export interface RequestOutcomeFacts {
+  readonly status: number;
+  readonly terminalStatus?: string | undefined;
+  readonly closeReason?: "terminal" | "client_cancel" | "non_stream" | "body_stall" | "body_overflow" | undefined;
+}
+
+/**
+ * Classify one finished logical request.
+ *
+ * Semantic terminal facts are read BEFORE the numeric status, which is the whole point. An HTTP
+ * 200 that carried an incomplete terminal is incomplete; a 502 that carried an incomplete
+ * terminal is also incomplete, and reading the status first would have called them success and
+ * failure. The numeric status is consulted only when no terminal event was recorded at all.
+ */
+export function classifyRequestOutcome(facts: RequestOutcomeFacts): RequestOutcomeClass {
+  if (facts.closeReason === "client_cancel" || facts.status === 499) return "aborted";
+  if (facts.terminalStatus === "failed") return "failed";
+  if (facts.terminalStatus === "incomplete"
+    || facts.closeReason === "body_stall"
+    || facts.closeReason === "body_overflow") return "incomplete";
+  if (facts.terminalStatus === "completed") return "completed";
+  if (facts.terminalStatus === undefined
+    && (facts.status === 101 || (facts.status >= 200 && facts.status < 400))) return "completed";
+  return "failed";
+}
+
+/** A count is reportable only when the writer recorded a non-negative integer. */
+function reportableCount(value: number | undefined): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
+/**
+ * Physical sends a finished request made, as the one number every surface shows.
+ *
+ * This READS the recorded total rather than recomputing one. An earlier draft returned
+ * `max(sends, reserved)` on the reasoning that a budget charge with no attempt row behind it is
+ * still a send that left — true, but it made the dashboard report four where the exporter, which
+ * sums the same attempts the recorder summed, reported three. Two defensible formulas are still
+ * two answers. The recorder already decided this, and `unresolved` below is where a charge with
+ * no attempt behind it becomes visible.
+ */
+export function requestPhysicalSends(spend: RequestSpendTotals | undefined): number {
+  return reportableCount(spend?.sends);
+}
+
+/**
+ * Sends whose attempt reached a terminal status, and sends that did not.
+ *
+ * Kept beside {@link requestPhysicalSends} because an operator reading a send total needs to know
+ * how much of it is explained. An unresolved send is the quantity a duplicate-send incident shows
+ * up in, and folding it into the total is what made #4546 invisible for so long.
+ */
+export function requestSettledSends(spend: RequestSpendTotals | undefined): number {
+  return reportableCount(spend?.settled);
+}
+
+export function requestUnresolvedSends(spend: RequestSpendTotals | undefined): number {
+  return reportableCount(spend?.unresolved);
+}

package/src/usage/retention-contract.ts

@@ -0,0 +1,28 @@
+/**
+ * The usage-ledger retention limits, stated once for the schema, the server and the dashboard.
+ *
+ * Import-free, for the reason `telemetry-contract.ts` gives: the dashboard is a separate
+ * TypeScript project, and a type-only import still drags the imported file's whole graph into
+ * the browser build. Anything added here must keep that property.
+ */
+
+/**
+ * Below this a ceiling cannot hold even one large row plus its successor, so a value under it is
+ * treated as unset rather than enforced into an empty ledger.
+ */
+export const MIN_USAGE_LEDGER_MAX_BYTES = 1024 * 1024;
+
+/** What the dashboard offers when a user turns the limit on. Not a default for the proxy. */
+export const SUGGESTED_USAGE_LEDGER_MAX_BYTES = 1024 * 1024 * 1024;
+
+/**
+ * Trim to this fraction of the ceiling rather than to the ceiling itself, so the next append does
+ * not immediately re-cross it and charge every subsequent append a full rewrite.
+ */
+export const USAGE_LEDGER_RETENTION_TARGET_RATIO = 0.9;
+
+export interface UsageLedgerRetentionStatus {
+  /** Absent when no limit is configured. */
+  maxBytes?: number;
+  currentBytes: number;
+}

package/src/usage/summary.ts

@@ -410,7 +410,7 @@ function isMeasuredStatus(status: UsageStatus): boolean {
   return status === "reported" || status === "estimated";
 }
 
-interface UsageAttribution {
+export interface UsageAttribution {
   requestId: string;
   provider: string;
   model: string;
@@ -454,7 +454,7 @@ function usageModelKey(providerKey: string, model: string): string {
   return `${providerKey}\0${model}`;
 }
 
-function usageAttributions(entry: PersistedUsageEntry): UsageAttribution[] {
+export function usageAttributions(entry: PersistedUsageEntry): UsageAttribution[] {
   if (!entry.attempts?.length) {
     return [{
       requestId: entry.requestId,