@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,849 lines • 87.6 kB
text/typescript
import { createHash, type Hash } from "node:crypto";
import { chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, appendFileSync } from "node:fs";
import { join } from "node:path";
import { getConfigDir } from "../config";
import type { CodexAffinityMove, CodexAffinityReason } from "../codex/routing";
import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
import { recordOwnedConfigPath } from "../lib/config-ownership";
import { redactSecretString, sanitizeLogMetadataString } from "../lib/redact";
import { usageDisplayTotalTokens } from "./totals";
import {
normalizePersistedJevDecision,
type PersistedJevDecisionV1,
} from "./jev-stats";
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 { parseProtocolTraceV1, type ProtocolTraceV1 } from "../protocols/dto";
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";
featureCodes: ClaudeFeatureCode[];
reason?: string;
}
/** Disk and in-memory callers share a closed-code projection; free-form reasons are discarded. */
export function normalizeClaudeCompatibilityUsageLog(value: unknown): PersistedClaudeCompatibilityLog | undefined {
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
const row = value as Record<string, unknown>;
if (row.decision !== "shadow") return undefined;
const featureCodes = normalizeClaudeFeatureCodes(row.featureCodes);
const reason = claudeCompatibilityReason(featureCodes, true);
if (!reason) return undefined;
return { decision: "shadow", featureCodes, reason };
}
export type UsageStatus = "reported" | "unreported" | "unsupported" | "estimated";
/**
* A persisted account label: a Codex pool account (`main`/`p<hex6>`) or a non-Codex OAuth
* provider account (`o<hex6>`, #2699).
*
* The old name `CodexUsageAccountLogLabel` is kept as an alias because it is exported and used
* across modules; the two predicates below are what callers should choose between.
*/
export type UsageAccountLogLabel = "main" | `p${string}` | `o${string}` | `k${string}`;
export type CodexUsageAccountLogLabel = UsageAccountLogLabel;
/**
* Accepts EITHER label family. This is the predicate the persistence writers use, so widening
* it here is what stops six separate call sites from silently dropping an `o`-label -- including
* two in the live request path (`request-log.ts:972` and `:1187`).
*
* The name is unchanged deliberately: renaming it would touch every call site for no behavior,
* and the widened contract is what every one of those sites wanted.
*/
export function isCodexUsageAccountLogLabel(value: unknown): value is UsageAccountLogLabel {
return value === "main" || (typeof value === "string" && ACCOUNT_LOG_LABEL_RE.test(value));
}
/** Strictly a Codex pool label. Use when the Codex-only distinction actually matters. */
export function isCodexPoolAccountLogLabel(value: unknown): value is "main" | `p${string}` {
return value === "main" || (typeof value === "string" && CODEX_ACCOUNT_LOG_LABEL_RE.test(value));
}
/** Request-time upstream credential class, never a credential or account identifier. */
export type UsageCredentialSource = "grok-oauth" | "xai-api-key";
/**
* Where a row's cache-token detail came from.
*
* Strict-client normalization emits zero-default token-detail objects on every bridged wire
* (`responsesUsage` in src/bridge.ts), so a `cached_tokens: 0` read back off that wire is a
* wire-compatibility artifact and not a measured cache miss. The three values stay distinct all
* the way to the summary because folding `synthesized` or `unknown` into `observed` is what
* lets a pool that discarded every warm prefix still report a plausible cache hit rate (#4546).
*/
export type CacheTelemetryProvenance = "observed" | "synthesized" | "unknown";
const KNOWN_CACHE_PROVENANCE = new Set<CacheTelemetryProvenance>([
"observed", "synthesized", "unknown",
]);
export function isKnownCacheTelemetryProvenance(value: unknown): value is CacheTelemetryProvenance {
return typeof value === "string" && KNOWN_CACHE_PROVENANCE.has(value as CacheTelemetryProvenance);
}
/**
* Classify one usage record's cache detail.
*
* `wireParsed` means the counts were read back off a response wire rather than reported raw by
* the adapter. An all-zero cache detail from that source cannot be told apart from the zero
* defaults the normalizer writes, so it is `synthesized`; the same shape reported raw is a real
* zero and stays `observed`. A record with no cache fields at all is `unknown`, which is not a
* zero either.
*/
export function classifyCacheTelemetryProvenance(
usage: OcxUsage | undefined,
options: { wireParsed?: boolean } = {},
): CacheTelemetryProvenance {
if (!usage) return "unknown";
const present = [usage.cachedInputTokens, usage.cacheReadInputTokens, usage.cacheCreationInputTokens]
.filter((value): value is number => typeof value === "number" && Number.isFinite(value));
if (present.length === 0) return "unknown";
if (present.some(value => value > 0)) return "observed";
return options.wireParsed === true ? "synthesized" : "observed";
}
export interface PersistedUsageAttempt {
ordinal: number;
provider: string;
/** Absent on historic attempts and routes whose subscription attribution is unknown. */
credentialSource?: UsageCredentialSource;
model: string;
adapter: string;
status: number;
durationMs: number;
/**
* True only when the upstream stream died after its 200 head was committed,
* so the row must not meter as a success the client never received.
* Absent on ordinary attempts so old rows keep their exact shape.
*/
streamAborted?: boolean;
/** TTFT relative to THIS attempt's start (WP4); unset for non-streaming/tool-only. */
firstOutputMs?: number;
sendCount: number;
recoveryKinds: AttemptRecoveryKind[];
/**
* Recoveries this attempt was eligible for and did not make. Absent on ordinary attempts so
* old rows keep their exact shape.
*/
recoveryWithheld?: AttemptRecoveryWithheld[];
usageStatus: UsageStatus;
/**
* True when the proxy answered this turn locally and issued no upstream request. It travels on
* the attempt itself rather than as a `finishRequestAttempt` argument because that function is
* called from six places, and a new parameter would silently default to the wrong answer at any
* one of them that was missed. Absent on ordinary attempts so old rows keep their exact shape.
*/
locallyAnswered?: boolean;
/** Stable non-PII identity for the Codex pool account that served this attempt. */
accountLogLabel?: CodexUsageAccountLogLabel;
inputTokenEstimate?: number;
usage?: OcxUsage;
totalTokens?: number;
errorCode?: string;
/**
* Provenance of this attempt's cache detail. Absent on rows written before the distinction
* existed, where `classifyCacheTelemetryProvenance` reconstructs the pre-existing reading.
*/
cacheProvenance?: CacheTelemetryProvenance;
/** Installation-local exact Compatibility Lab route-subject digest for this attempt. */
labRouteSubjectId?: string;
/** Target-specific reasoning intent and exact adapter-normalized wire parameter. */
requestedEffort?: string;
effectiveEffort?: string;
reasoningWireField?: string;
reasoningWireValue?: string | number | boolean;
/** Adapter-produced tier fact for this physical attempt; absent on pre-B0 rows. */
tierOutcome?: AttemptTierOutcome;
/**
* #4191: content-free stage record of a Codex WS upstream exchange that
* served this attempt (frame size, counters, close code, versions). Absent
* on HTTP-transport attempts and pre-instrumentation rows. Numbers,
* booleans, and semver strings only — never reason text, headers, or
* 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;
}
/**
* What one logical request spent upstream, and why (#4546, devlog 040 slice D).
*
* `sendCount` counts physical sends per ATTEMPT, which answers the wrong question: a user turn
* that failed over twice and fanned out to three combo targets is one turn, and the number an
* 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 extends RequestSpendTotals {
/** Budget profile that produced `reserved`, so a count can be read against the policy it obeyed. */
policyVersion?: string;
/**
* Why the pool binding moved during this request. A move discards the warmed prompt-cache
* prefix, so the reason belongs next to the send count rather than a page away from it.
*/
moveReasons?: CodexAffinityReason[];
}
const MAX_PERSISTED_MOVE_REASONS = 8;
// Model selectors are NOT length-bound at admission: configured and discovered
// model ids reach MODEL_DISCOVERY_MAX_MODEL_ID_LENGTH, and the wire `model`
// field is raw client input. Persisting a plain prefix would merge selectors
// that share it, so over-long selectors persist as prefix + a digest of the
// FULL selector — bounded, deterministic, and still exact-matchable.
const MAX_PERSISTED_REQUESTED_MODEL_LEN = 130;
const REQUESTED_MODEL_DIGEST_HEX_LEN = 16;
const LOGICAL_REQUEST_ID_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
/**
* Persisted form of the wire model selector. Selectors within the bound persist
* verbatim; longer selectors persist as a prefix plus a short digest of the full
* value, so two distinct selectors that share the prefix never collapse into one
* persisted identity. Exact-match readers (`requested_model = ?`) must encode
* lookup input through this same function. Idempotent — encoded forms fit the
* bound — which matters because rows are normalized again on read.
*
* Idempotence has one cost: a literal selector that equals another selector's
* persisted form is indistinguishable from it, so both rows share one display
* value and one exact-match filter. Reaching that needs the caller to send the
* exact prefix-and-digest string; keeping them apart would need a separate
* full-selector digest column.
*/
export function encodePersistedRequestedModel(selector: string): string {
if (selector.length <= MAX_PERSISTED_REQUESTED_MODEL_LEN) return selector;
const digest = createHash("sha256")
.update(selector)
.digest("hex")
.slice(0, REQUESTED_MODEL_DIGEST_HEX_LEN);
const prefixLen = MAX_PERSISTED_REQUESTED_MODEL_LEN - REQUESTED_MODEL_DIGEST_HEX_LEN - 1;
return `${selector.slice(0, prefixLen)}~${digest}`;
}
export function isLogicalRequestId(value: unknown): value is string {
return typeof value === "string" && LOGICAL_REQUEST_ID_RE.test(value);
}
/**
* A spend record is trusted only when every count is a non-negative integer and the decomposition
* holds. A hand-edited row that reports more settled spend than it sent would understate exactly
* the quantity the record exists to expose, so the whole record is dropped instead.
*/
export function normalizeRequestSpend(value: unknown): PersistedRequestSpend | undefined {
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
const spend = value as Record<string, unknown>;
const count = (raw: unknown): number | null =>
typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : null;
const sends = count(spend.sends);
const settled = count(spend.settled);
const unresolved = count(spend.unresolved);
if (sends === null || settled === null || unresolved === null) return undefined;
if (settled > sends) return undefined;
const reserved = "reserved" in spend ? count(spend.reserved) : undefined;
if (reserved === null) return undefined;
const moveReasons = Array.isArray(spend.moveReasons)
? [...new Set(spend.moveReasons.filter(isKnownAffinityReason))].slice(0, MAX_PERSISTED_MOVE_REASONS)
: [];
return {
sends,
settled,
unresolved,
...(reserved !== undefined ? { reserved } : {}),
...(typeof spend.policyVersion === "string" && spend.policyVersion
? { policyVersion: capMetadataString(spend.policyVersion) }
: {}),
...(moveReasons.length > 0 ? { moveReasons } : {}),
};
}
export interface PersistedUsageEntry {
requestedAlias?: string;
requestId: string;
/**
* Identity of the ONE logical request this row belongs to (#4546), minted by
* `createRequestExecutionBudget` at ingress. `requestId` identifies a log row; a retry layer,
* a repair leg and a combo child are all the same logical request, and only this field says so.
*/
logicalRequestId?: string;
timestamp: number;
provider: string;
model: string;
surface?: "claude" | "claude-desktop" | "grok";
/** Matched configured key id; absent for environment/loopback admissions and
* for every row written before attribution existed. */
apiKeyId?: string;
admissionKind?: "configured" | "environment" | "loopback";
/** The inbound wire, not the client product — see `surface`. */
inboundProtocol?: "responses" | "chat" | "messages";
/** Stable non-PII identity for Codex Pool usage; absent for Direct/non-Codex traffic. */
accountLogLabel?: CodexUsageAccountLogLabel;
/** Best-effort chat/session correlation for Logs grouping (#330). */
conversationId?: string;
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;
requestedModel?: string;
/** Original bare helper model when the opt-in shadow-call route rewrote this request. */
shadowCallRewrittenFrom?: string;
/** Reasoning effort / service-tier metadata for GUI Logs after restart. */
requestedEffort?: string;
/** Adapter-normalized tier and exact upstream parameter emitted for this request. */
effectiveEffort?: string;
reasoningWireField?: string;
reasoningWireValue?: string | number | boolean;
/** Raw caller tier captured before routing, sanitized and bounded for durable logs. */
callerServiceTier?: string;
requestedServiceTier?: string;
requestedSpeedLabel?: string;
configuredServiceTier?: string;
configuredSpeedLabel?: string;
modelSupportsServiceTier?: boolean;
responseServiceTier?: string;
/** Summary of the final physical attempt for dashboard consumers. */
tierOutcome?: AttemptTierOutcome;
status: number;
durationMs: number;
/** TTFT relative to the request start (WP4); unset for non-streaming/tool-only. */
firstOutputMs?: number;
usageStatus: UsageStatus;
usage?: OcxUsage;
totalTokens?: number;
attempts?: PersistedUsageAttempt[];
/** Aggregated upstream spend for this logical request; additive, older rows omit it. */
spend?: PersistedRequestSpend;
/** Provenance of this row's cache detail; absent rows are reconstructed, never assumed observed. */
cacheProvenance?: CacheTelemetryProvenance;
// 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;
/**
* 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. */
transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse";
/** Whether the terminal came from upstream or a proxy-generated tail. */
terminalSource?: "upstream" | "synthetic";
/**
* What happened to this request's Codex pool binding, and why (#4546). A move discards the
* prompt-cache prefix warmed on the previous account, so it is recorded as an event rather
* than left to be inferred from account labels across rows. Additive; older rows omit it.
*/
affinity?: CodexAffinityMove;
affinityReason?: CodexAffinityReason;
/**
* Set when this request dropped account-bound continuation after a Codex pool
* account change. Never an account identifier.
*/
conversationStateScrub?: "account-change";
/**
* Bounded route-decision trace (RI-01): why this provider/model/account was
* selected. Additive field; old rows without it parse unchanged. Never
* contains prompts, credentials, or hidden reasoning.
*/
routeDecision?: RouteDecisionTraceV1;
/** Privacy-bounded JEV selection metadata; model usage remains in attempts[]. */
jevDecision?: PersistedJevDecisionV1;
/** Closed Claude protocol codes only; absent on older rows. */
claudeCompatibility?: PersistedClaudeCompatibilityLog;
/**
* Observed protocol path (PF-02): fixed vocabulary only. Re-validated on every read; older
* rows and rows that fail validation carry none, and are never back-filled by guessing.
*/
protocolTrace?: ProtocolTraceV1;
/**
* 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"]>>([
"claude",
"claude-desktop",
"grok",
]);
/**
* The serializer guard for `surface`. Two failure modes shaped this: a literal
* whitelist ("claude" | "claude-desktop" only) silently dropped every NEW surface at
* write time, while a plain truthy spread would persist junk values from hand-edited
* logs. Membership in this set is the middle path: adding a surface here is one edit,
* and unknown values are still dropped.
*/
export function isKnownUsageSurface(value: unknown): value is NonNullable<PersistedUsageEntry["surface"]> {
return typeof value === "string" && KNOWN_USAGE_SURFACES.has(value as NonNullable<PersistedUsageEntry["surface"]>);
}
const KNOWN_ADMISSION_KINDS = new Set<NonNullable<PersistedUsageEntry["admissionKind"]>>([
"configured", "environment", "loopback",
]);
const KNOWN_INBOUND_PROTOCOLS = new Set<NonNullable<PersistedUsageEntry["inboundProtocol"]>>([
"responses", "chat", "messages",
]);
/** Same closed-set discipline as `isKnownUsageSurface`: an old or corrupted row
* carrying an unexpected value drops the field instead of poisoning the enum. */
export function isKnownAdmissionKind(value: unknown): value is NonNullable<PersistedUsageEntry["admissionKind"]> {
return typeof value === "string" && KNOWN_ADMISSION_KINDS.has(value as NonNullable<PersistedUsageEntry["admissionKind"]>);
}
export function isKnownInboundProtocol(value: unknown): value is NonNullable<PersistedUsageEntry["inboundProtocol"]> {
return typeof value === "string" && KNOWN_INBOUND_PROTOCOLS.has(value as NonNullable<PersistedUsageEntry["inboundProtocol"]>);
}
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);
}
const KNOWN_TERMINAL_SOURCES = new Set<NonNullable<PersistedUsageEntry["terminalSource"]>>([
"upstream", "synthetic",
]);
export function isKnownTerminalSource(value: unknown): value is NonNullable<PersistedUsageEntry["terminalSource"]> {
return typeof value === "string" && KNOWN_TERMINAL_SOURCES.has(value as NonNullable<PersistedUsageEntry["terminalSource"]>);
}
/**
* The persisted entry is built by an explicit whitelist, so a field the writer sets but this
* normalizer does not name is dropped without a word. #4592 added the affinity record at the
* call site and it never reached disk for exactly that reason.
*/
const KNOWN_AFFINITY_MOVES = new Set<NonNullable<PersistedUsageEntry["affinity"]>>([
"reused", "held", "detour", "rebound", "new_bind", "cleared",
]);
const KNOWN_AFFINITY_REASONS = new Set<NonNullable<PersistedUsageEntry["affinityReason"]>>([
"healthy", "quota_headroom", "quota_refusal", "transient", "transient_hold_expired",
"unusable", "paused", "plan_excluded", "cooldown", "quota_avoided", "generation",
"expired", "model_lane",
]);
const KNOWN_CONVERSATION_STATE_SCRUBS = new Set<NonNullable<PersistedUsageEntry["conversationStateScrub"]>>([
"account-change",
]);
export function isKnownAffinityMove(value: unknown): value is NonNullable<PersistedUsageEntry["affinity"]> {
return typeof value === "string" && KNOWN_AFFINITY_MOVES.has(value as NonNullable<PersistedUsageEntry["affinity"]>);
}
export function isKnownAffinityReason(value: unknown): value is NonNullable<PersistedUsageEntry["affinityReason"]> {
return typeof value === "string" && KNOWN_AFFINITY_REASONS.has(value as NonNullable<PersistedUsageEntry["affinityReason"]>);
}
export function usageLogPath(configDir?: string): string {
return join(configDir ?? getConfigDir(), "usage.jsonl");
}
export function usageTotalTokens(usage: OcxUsage | undefined): number | undefined {
return usageDisplayTotalTokens(usage);
}
/**
* Providers whose adapters can only estimate usage (no authoritative per-turn frame).
* Callers should pass the route ADAPTER when available; the name-prefix match is a
* fallback for paths that only know the configured provider name (e.g. "cursor-mykey").
*/
function isEstimatedUsageProvider(providerOrAdapter: string): boolean {
return providerOrAdapter === "kiro" || providerOrAdapter.startsWith("kiro-")
|| providerOrAdapter === "cursor" || providerOrAdapter.startsWith("cursor-");
}
export function usageForFinalLog(
provider: string,
usage: OcxUsage | undefined,
/**
* True when the proxy answered this turn locally and issued no upstream request. Such a turn's
* zero counts are EXACT, so the provider-wide estimated marking must not apply: Kiro and Cursor
* are marked estimated because their adapters can only guess a real inference's usage, and a
* turn with no inference has nothing to guess. Without this, a no-send turn is indistinguishable
* from a real one whose usage frame never arrived.
*/
locallyAnswered = false,
): OcxUsage | undefined {
if (!usage) return undefined;
if (locallyAnswered) return usage;
if (usage.estimated || isEstimatedUsageProvider(provider)) return { ...usage, estimated: true };
return usage;
}
export function usageStatusForFinalLog(usage: OcxUsage | undefined): UsageStatus {
if (!usage) return "unreported";
return usage.estimated ? "estimated" : "reported";
}
function normalizeUsageValue(usage: OcxUsage | undefined): OcxUsage | undefined {
if (!usage) return undefined;
return {
inputTokens: usage.inputTokens,
outputTokens: usage.outputTokens,
// Absolute active-context checkpoint (types.ts). Stateful providers such as Kiro report
// per-attempt usage only, so this field is the ONLY carrier of the cumulative context
// figure once the log records raw adapter usage instead of re-parsing the bridged wire
// (usageFromBridge, request-log.ts). Omitting it here silently dropped Kiro's context
// growth from every persisted row. It is deliberately NOT folded into totalTokens:
// a checkpoint is not a per-request total and must never be summed across requests.
...(typeof usage.contextTotalTokens === "number" ? { contextTotalTokens: usage.contextTotalTokens } : {}),
...(typeof usage.totalTokens === "number" ? { totalTokens: usage.totalTokens } : {}),
...(typeof usage.cachedInputTokens === "number" ? { cachedInputTokens: usage.cachedInputTokens } : {}),
...(typeof usage.cacheReadInputTokens === "number" ? { cacheReadInputTokens: usage.cacheReadInputTokens } : {}),
...(typeof usage.cacheCreationInputTokens === "number" ? { cacheCreationInputTokens: usage.cacheCreationInputTokens } : {}),
...(typeof usage.reasoningOutputTokens === "number" ? { reasoningOutputTokens: usage.reasoningOutputTokens } : {}),
...(isNonNegativeFiniteNumber(usage.providerCredits) ? { providerCredits: usage.providerCredits } : {}),
...(usage.estimated ? { estimated: true } : {}),
};
}
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",
"unsupported",
"estimated",
]);
const LAB_ROUTE_SUBJECT_ID_RE = /^[0-9a-f]{64}$/;
const FAST_OUTCOMES = new Set<AttemptTierOutcome["fastOutcome"]>([
"not-requested", "applied", "downgraded", "unknown",
]);
const TIER_CONFIRMATIONS = new Set<AttemptTierOutcome["confirmation"]>([
"confirmed", "assumed", "downgraded", "unknown",
]);
const FAST_DOWNGRADE_REASONS = new Set<NonNullable<AttemptTierOutcome["fastDowngradeReason"]>>([
"route-unsupported", "wire-unavailable", "response-declined",
]);
export function isLabRouteSubjectId(value: unknown): value is string {
return typeof value === "string" && LAB_ROUTE_SUBJECT_ID_RE.test(value);
}
function isNonNegativeFiniteNumber(value: unknown): value is number {
return typeof value === "number" && Number.isFinite(value) && value >= 0;
}
function normalizeAttemptUsage(raw: unknown): OcxUsage | null {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
const usage = raw as Record<string, unknown>;
if (!isNonNegativeFiniteNumber(usage.inputTokens)
|| !isNonNegativeFiniteNumber(usage.outputTokens)) return null;
for (const key of [
"contextTotalTokens",
"totalTokens",
"cachedInputTokens",
"cacheReadInputTokens",
"cacheCreationInputTokens",
"reasoningOutputTokens",
"providerCredits",
] as const) {
if (key in usage && !isNonNegativeFiniteNumber(usage[key])) return null;
}
if ("estimated" in usage && typeof usage.estimated !== "boolean") return null;
return normalizeUsageValue(usage as unknown as OcxUsage) ?? null;
}
function normalizeAttemptTierOutcome(raw: unknown): AttemptTierOutcome | null {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
const outcome = raw as Record<string, unknown>;
if (typeof outcome.fastOutcome !== "string"
|| !FAST_OUTCOMES.has(outcome.fastOutcome as AttemptTierOutcome["fastOutcome"])
|| typeof outcome.confirmation !== "string"
|| !TIER_CONFIRMATIONS.has(outcome.confirmation as AttemptTierOutcome["confirmation"])) {
return null;
}
if ("canonical" in outcome && outcome.canonical !== "priority") return null;
if ("wireKind" in outcome
&& outcome.wireKind !== null
&& outcome.wireKind !== "service-tier"
&& outcome.wireKind !== "anthropic-speed"
&& outcome.wireKind !== "cursor-variant"
&& outcome.wireKind !== "model-variant") return null;
if ("wireValue" in outcome && outcome.wireValue !== null && typeof outcome.wireValue !== "string") return null;
if ("fastDowngradeReason" in outcome
&& (typeof outcome.fastDowngradeReason !== "string"
|| !FAST_DOWNGRADE_REASONS.has(outcome.fastDowngradeReason as NonNullable<AttemptTierOutcome["fastDowngradeReason"]>))) {
return null;
}
if ("callerTierDropped" in outcome && typeof outcome.callerTierDropped !== "boolean") return null;
if ("callerFastSuppressedByConfig" in outcome
&& typeof outcome.callerFastSuppressedByConfig !== "boolean") return null;
if ("responseServiceTier" in outcome && typeof outcome.responseServiceTier !== "string") return null;
if ("responseTierAuthoritative" in outcome && typeof outcome.responseTierAuthoritative !== "boolean") return null;
const wireValue = sanitizeLogMetadataString(outcome.wireValue);
const responseServiceTier = sanitizeLogMetadataString(outcome.responseServiceTier);
return {
...(outcome.canonical === "priority" ? { canonical: "priority" as const } : {}),
...(outcome.wireKind === null
|| outcome.wireKind === "service-tier"
|| outcome.wireKind === "anthropic-speed"
|| outcome.wireKind === "cursor-variant"
|| outcome.wireKind === "model-variant"
? { wireKind: outcome.wireKind }
: {}),
...(outcome.wireValue === null
? { wireValue: null }
: wireValue ? { wireValue } : {}),
fastOutcome: outcome.fastOutcome as AttemptTierOutcome["fastOutcome"],
...(typeof outcome.fastDowngradeReason === "string"
? { fastDowngradeReason: outcome.fastDowngradeReason as NonNullable<AttemptTierOutcome["fastDowngradeReason"]> }
: {}),
...(typeof outcome.callerTierDropped === "boolean" ? { callerTierDropped: outcome.callerTierDropped } : {}),
...(typeof outcome.callerFastSuppressedByConfig === "boolean"
? { callerFastSuppressedByConfig: outcome.callerFastSuppressedByConfig }
: {}),
confirmation: outcome.confirmation as AttemptTierOutcome["confirmation"],
...(typeof outcome.responseTierAuthoritative === "boolean"
? { responseTierAuthoritative: outcome.responseTierAuthoritative }
: {}),
...(responseServiceTier ? { responseServiceTier } : {}),
};
}
function normalizeUsageAttempt(raw: unknown): PersistedUsageAttempt | null {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
const attempt = raw as Record<string, unknown>;
if (typeof attempt.ordinal !== "number" || !Number.isInteger(attempt.ordinal)
|| attempt.ordinal < 1
|| typeof attempt.provider !== "string" || !attempt.provider
|| typeof attempt.model !== "string" || !attempt.model
|| typeof attempt.adapter !== "string" || !attempt.adapter
|| typeof attempt.status !== "number" || !Number.isInteger(attempt.status)
|| attempt.status < 100 || attempt.status > 599
|| typeof attempt.durationMs !== "number" || !Number.isFinite(attempt.durationMs)
|| attempt.durationMs < 0
|| typeof attempt.sendCount !== "number" || !Number.isInteger(attempt.sendCount)
|| attempt.sendCount < 0
|| typeof attempt.usageStatus !== "string"
|| !USAGE_STATUSES.has(attempt.usageStatus as UsageStatus)) {
return null;
}
if ("inputTokenEstimate" in attempt
&& !isNonNegativeFiniteNumber(attempt.inputTokenEstimate)) return null;
if ("firstOutputMs" in attempt
&& !isNonNegativeFiniteNumber(attempt.firstOutputMs)) return null;
if ("totalTokens" in attempt
&& !isNonNegativeFiniteNumber(attempt.totalTokens)) return null;
const usage = "usage" in attempt ? normalizeAttemptUsage(attempt.usage) : undefined;
if ("usage" in attempt && usage === null) return null;
const tierOutcome = "tierOutcome" in attempt
? normalizeAttemptTierOutcome(attempt.tierOutcome)
: undefined;
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"
&& ATTEMPT_RECOVERY_KINDS.has(value as AttemptRecoveryKind),
))]
: [];
// Same shape as `recoveryKinds`: unknown values are dropped rather than failing the row, so a
// log written by a newer build stays readable by an older one.
const recoveryWithheld = Array.isArray(attempt.recoveryWithheld)
? [...new Set(attempt.recoveryWithheld.filter(
(value): value is AttemptRecoveryWithheld => typeof value === "string"
&& ATTEMPT_RECOVERY_WITHHELD.has(value as AttemptRecoveryWithheld),
))]
: [];
return {
ordinal: attempt.ordinal as number,
provider: attempt.provider,
...(attempt.provider === "xai"
&& (attempt.credentialSource === "grok-oauth" || attempt.credentialSource === "xai-api-key")
? { credentialSource: attempt.credentialSource }
: {}),
model: attempt.model,
adapter: attempt.adapter,
status: attempt.status,
durationMs: attempt.durationMs,
// Absent by default; only the literal `true` marker survives the round trip.
...(attempt.streamAborted === true ? { streamAborted: true } : {}),
...(attempt.locallyAnswered === true ? { locallyAnswered: true } : {}),
...(isNonNegativeFiniteNumber(attempt.firstOutputMs)
? { firstOutputMs: attempt.firstOutputMs }
: {}),
sendCount: attempt.sendCount as number,
recoveryKinds,
...(recoveryWithheld.length ? { recoveryWithheld } : {}),
usageStatus: attempt.usageStatus as UsageStatus,
...(isCodexUsageAccountLogLabel(attempt.accountLogLabel)
? { accountLogLabel: attempt.accountLogLabel }
: {}),
...(isNonNegativeFiniteNumber(attempt.inputTokenEstimate)
? { inputTokenEstimate: attempt.inputTokenEstimate }
: {}),
...(usage ? { usage } : {}),
...(isNonNegativeFiniteNumber(attempt.totalTokens)
? { totalTokens: attempt.totalTokens }
: {}),
...(typeof attempt.errorCode === "string" ? { errorCode: attempt.errorCode } : {}),
...(isKnownCacheTelemetryProvenance(attempt.cacheProvenance)
? { cacheProvenance: attempt.cacheProvenance }
: {}),
...(isLabRouteSubjectId(attempt.labRouteSubjectId)
? { labRouteSubjectId: attempt.labRouteSubjectId }
: {}),
...(typeof attempt.requestedEffort === "string" && attempt.requestedEffort
? { requestedEffort: capMetadataString(attempt.requestedEffort) }
: {}),
...(typeof attempt.effectiveEffort === "string" && attempt.effectiveEffort
? { effectiveEffort: capMetadataString(attempt.effectiveEffort) }
: {}),
...(typeof attempt.reasoningWireField === "string" && attempt.reasoningWireField
? { reasoningWireField: capMetadataString(attempt.reasoningWireField) }
: {}),
...(isValidReasoningWireValue(attempt.reasoningWireField, attempt.reasoningWireValue)
? typeof attempt.reasoningWireValue === "string"
? { reasoningWireValue: capMetadataString(attempt.reasoningWireValue) }
: { reasoningWireValue: attempt.reasoningWireValue }
: {}),
...(tierOutcome ? { tierOutcome } : {}),
...(codexWsStage ? { codexWsStage } : {}),
...(deliverySummary ? { deliverySummary } : {}),
...normalizeRequestFailureAttribution(attempt),
};
}
/**
* #4191: a persisted stage record is trusted only when every field matches the
* exchange's own shapes. Anything else — a hand-edited number as a string, an
* injected free-form field — drops the whole record rather than passing
* attacker text into the DTO.
*/
function normalizeCodexWsStageRecord(value: unknown): CodexWsStageRecord | undefined {
if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
const stage = value as Record<string, unknown>;
for (const key of ["upstreamFrames", "controlFrames", "relayedEvents", "pings", "pongs"] as const) {
if (!isNonNegativeFiniteNumber(stage[key])) return undefined;
}
if (!(stage.requestBytes === null || isNonNegativeFiniteNumber(stage.requestBytes))) return undefined;
if (!(stage.firstFrameMs === null || isNonNegativeFiniteNumber(stage.firstFrameMs))) return undefined;
// Records written before firstResponseMs existed omit it; read them as unmeasured.
const firstResponseMs = stage.firstResponseMs === undefined ? null : stage.firstResponseMs;
if (!(firstResponseMs === null || isNonNegativeFiniteNumber(firstResponseMs))) return undefined;
if (!(stage.elapsedMs === null || isNonNegativeFiniteNumber(stage.elapsedMs))) return undefined;
if (!(stage.closeCode === null || (typeof stage.closeCode === "number"
&& Number.isInteger(stage.closeCode) && stage.closeCode >= 1000 && stage.closeCode <= 4999))) {
return undefined;
}
if (typeof stage.sent !== "boolean" || typeof stage.reused !== "boolean") return undefined;
if (typeof stage.ocxVersion !== "string" || !stage.ocxVersion || stage.ocxVersion.length > 32) return undefined;
if (typeof stage.bunVersion !== "string" || !stage.bunVersion || stage.bunVersion.length > 32) return undefined;
return {
requestBytes: stage.requestBytes as number | null,
sent: stage.sent,
upstreamFrames: stage.upstreamFrames as number,
controlFrames: stage.controlFrames as number,
relayedEvents: stage.relayedEvents as number,
firstFrameMs: stage.firstFrameMs as number | null,
firstResponseMs: firstResponseMs as number | null,
elapsedMs: stage.elapsedMs as number | null,
pings: stage.pings as number,
pongs: stage.pongs as number,
closeCode: stage.closeCode as number | null,
reused: stage.reused,
ocxVersion: stage.ocxVersion,
bunVersion: stage.bunVersion,
};
}
/**
* Pairing rule for reasoning diagnostics, shared with the live request-log capture path:
* a non-empty string, a non-negative finite number, or a boolean only for
* `reasoning.enabled`. The field name itself is validated separately at capture time;
* persisted rows may carry legacy field names, so this checks only the value shape.
*/
export function isValidReasoningWireValue(
wireField: unknown,
wireValue: unknown,
): wireValue is string | number | boolean {
return (typeof wireValue === "string" && wireValue.length > 0)
|| (typeof wireValue === "number" && Number.isFinite(wireValue) && wireValue >= 0)
|| (wireField === "reasoning.enabled" && typeof wireValue === "boolean");
}
function normalizedAttempts(raw: unknown): PersistedUsageAttempt[] {
if (!Array.isArray(raw)) return [];
return raw.map(normalizeUsageAttempt)
.filter((attempt): attempt is PersistedUsageAttempt => attempt !== null);
}
const MAX_METADATA_STRING_LEN = 64;
function capMetadataString(s: string): string {
return s.length > MAX_METADATA_STRING_LEN ? s.slice(0, MAX_METADATA_STRING_LEN) : s;
}
const MAX_SERVED_MODEL_LENGTH = 200;
/**
* An upstream model is an identifier, never free-form text to truncate into one. A value the
* secret redactor would change is dropped rather than logged, because credential-shaped text can
* fit the identifier alphabet.
*/
export function sanitizeServedModel(value: unknown): string | undefined {
return typeof value === "string"
&& value.length <= MAX_SERVED_MODEL_LENGTH
&& /^[A-Za-z0-9._:/@+-]+$/.test(value)
&& redactSecretString(value) === value
? value
: undefined;
}
/** The identity fields that decide whether a response model is ocx's own echo. */
export interface ServedModelEchoSource {
provider?: string;
model?: string;
wireModel?: string;
requestedAlias?: string;
requestedModel?: string;
/** Client-facing selector this proxy wrote into `response.model` (Anthropic routes keep it). */
responseModelEcho?: string;
}
/**
* True when `served` is the client's own selector echoed back rather than a model the upstream
* reported. Anthropic routes answer with the Codex-facing selector (`anthropic/claude-opus-5-5`),
* and recording that as the served model painted every such row as rerouted. A value equal to
* the wire model is never an echo. On adapter paths the upstream's real model is not observable
* at all, so this only removes a false signal; passthrough `openai-model` observations are kept.
*/
export function isClientSelectorEcho(source: ServedModelEchoSource, served: string | undefined): boolean {
if (served === undefined) return false;
const wire = source.wireModel ?? source.model;
if (served === wire) return false;
return served === source.responseModelEcho
|| served === source.requestedAlias
|| served === source.requestedModel
|| (source.provider !== undefined && wire !== undefined && served === `${source.provider}/${wire}`);
}
/** Record a response-body model as the served model when it is a real upstream observation. */
export function recordObservedServedModel(
target: ServedModelEchoSource & { servedModel?: string; resolvedModel?: string; preserveResolvedModelFromRoute?: boolean },
value: unknown,
): void {
const servedModel = sanitizeServedModel(value);
if (!servedModel || isClientSelectorEcho(target, servedModel)) return;
target.servedModel = servedModel;
if (!target.preserveResolvedModelFromRoute) target.resolvedModel = servedModel;
}
/**
* Model identity fields for a log row. The served model is sanitized, and a resolvedModel that
* only echoed a dropped served model is dropped with it, so the rejected value cannot survive
* under the other name. A client-selector echo is dropped the same way, which also repairs
* rows persisted before the echo was filtered at capture.
*/
export function modelIdentityLogFields(source: ServedModelEchoSource & { resolvedModel?: string; servedModel?: unknown }): {
resolvedModel?: string; servedModel?: string; wireModel?: string;
} {
const sanitized = sanitizeServedModel(source.servedModel);
const servedModel = isClientSelectorEcho(source, sanitized) ? undefined : sanitized;
const resolvedModel = source.servedModel !== undefined && source.resolvedModel === source.servedModel && !servedModel
? undefined : source.resolvedModel;
return {
...(resolvedModel ? { resolvedModel } : {}),
...(servedModel ? { servedModel } : {}),
...(source.wireModel ? { wireModel: source.wireModel } : {}),
};
}
/** Test seam: the normalization branch old rows take is worth asserting directly. */
export function normalizeUsageEntryForTest(entry: PersistedUsageEntry): PersistedUsageEntry {
return normalizeUsageEntry(entry);
}
function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
const attempts = normalizedAttempts(entry.attempts);
const tierOutcome = entry.tierOutcome ? normalizeAttemptTierOutcome(entry.tierOutcome) : undefined;
const callerServiceTier = sanitizeLogMetadataString(entry.callerServiceTier);
const responseServiceTier = sanitizeLogMetadataString(entry.responseServiceTier);
const shadowCallRewrittenFrom = sanitizeLogMetadataString(entry.shadowCallRewrittenFrom);
const { servedModel, resolvedModel } = modelIdentityLogFields(entry);
const claudeCompatibility = normalizeClaudeCompatibilityUsageLog(entry.claudeCompatibility);
const transportPhase = isKnownTransportPhase(entry.transportPhase) ? entry.transportPhase : undefined;
const terminalSource = isKnownTerminalSource(entry.terminalSource) ? entry.terminalSource : undefined;
const affinity = isKnownAffinityMove(entry.affinity) ? entry.affinity : undefined;
// A reason without a move describes nothing, so it is only kept alongside one.
const affinityReason = affinity !== undefined && isKnownAffinityReason(entry.affinityReason)
? entry.affinityReason
: undefined;
const conversationStateScrub = typeof entry.conversationStateScrub === "string"
&& KNOWN_CONVERSATION_STATE_SCRUBS.has(entry.conversationStateScrub)
? entry.conversationStateScrub
: undefined;
const routeDecision = entry.routeDecision
? normalizeRouteDecisionTrace(entry.routeDecision)
: undefined;
const jevDecision = normalizePersistedJevDecision(entry.jevDecision);
const spend = normalizeRequestSpend(entry.spend);
const protocolTrace = parseProtocolTraceV1(entry.protocolTrace);
return {
requestId: entry.requestId,
...(isLogicalRequestId(entry.logicalRequestId) ? { logicalRequestId: entry.logicalRequestId } : {}),
timestamp: entry.timestamp,
provider: entry.provider,
model: entry.model,
...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
...(typeof entry.apiKeyId === "string" && entry.apiKeyId.trim()
// Deliberately NOT capped. `capMetadataString` protects free-form metadata
// from unbounded growth, but this is a lookup key: truncating it makes the
// persisted id stop matching the configured one, and the rollup silently
// reports zero for a key that is very much in use.
? { apiKeyId: entry.apiKeyId }
: {}),
...(isKnownAdmissionKind(entry.admissionKind) ? { admissionKind: entry.admissionKind } : {}),
...(isKnownInboundProtocol(entry.inboundProtocol) ? { inboundProtocol: entry.inboundProtocol } : {}),
...(isCodexUsageAccountLogLabel(entry.accountLogLabel)
? { accountLogLabel: entry.accountLogLabel }
: {}),
...(typeof entry.conversationId === "string" && entry.conversationId.trim()
? { conversationId: entry.conversationId.trim().slice(0, 128) }
: {}),
...(resolvedModel ? { resolvedModel } : {}),
...(servedModel ? { servedModel } : {}),
...(entry.wireModel ? { wireModel: entry.wireModel } : {}),
...(typeof entry.requestedModel === "string" && entry.requestedModel
? { requestedModel: encodePersistedRequestedModel(entry.requestedModel) }
: {}),
...(shadowCallRewrittenFrom ? { shadowCallRewrittenFrom } : {}),
...(typeof entry.requestedEffort === "string" && entry.requestedEffort
? { requestedEffort: capMetadataString(entry.requestedEffort) }
: {}),
...(typeof entry.effectiveEffort === "string" && entry.effectiveEffort
? { effectiveEffort: capMetadataString(entry.effectiveEffort) }
: {}),
...(typeof entry.reasoningWireField === "string" && entry.reasoningWireField
? { reasoningWireField: capMetadataString(entry.reasoningWireField) }
: {}),
...(isValidReasoningWireValue(entry.reasoningWireField, entry.reasoningWireValue)
? typeof entry.reasoningWireValue === "string"
? { reasoningWireValue: capMetadataString(entry.reasoningWireValue) }
: { reasoningWireValue: entry.reasoningWireValue }
: {}),
...(callerServiceTier ? { callerServiceTier } : {}),
...(typeof entry.requestedServiceTier === "string" && entry.requestedServiceTier
? { requestedServiceTier: capMetadataString(entry.requestedServiceTier) }
: {}),
...(typeof entry.requestedSpeedLabel === "string" && entry.requestedSpeedLabel
? { requestedSpeedLabel: capMetadataString(entry.requestedSpeedLabel) }
: {}),
...(typeof entry.configuredServiceTier === "string" && entry.configuredServiceTier
? { configuredServiceTier: capMetadataString(entry.configuredServiceTier) }
: {}),
...(typeof entry.configuredSpeedLabel === "string" && entry.configuredSpeedLabel
? { configuredSpeedLabel: capMetadataString(entry.configuredSpeedLabel) }
: {}),
...(typeof entry.modelSupportsServiceTier === "boolean"
? { modelSupportsServiceTier: entry.modelSupportsServiceTier }
: {}),
...(responseServiceTier ? { responseServiceTier } : {}),
...(tierOutcome ? { tierOutcome } : {}),
status: entry.status,
durationMs: entry.durationMs,
...(isNonNegativeFiniteNumber(entry.firstOutputMs)
? { firstOutputMs: entry.firstOutputMs }
: {}),
usageStatus: entry.usageStatus,
...(entry.usage ? { usage: normalizeUsageValue(entry.usage) } : {}),
...(typeof entry.totalTokens === "number" ? { totalTokens: entry.totalTokens } : {}),
...(Array.isArray(entry.attempts) ? { attempts } : {}),
...(spend ? { spend } : {}),
...(isKnownCacheTelemetryProvenance(entry.cacheProvenance)
? { cacheProvenance: entry.cacheProvenance }
: {}),
...(transportPhase ? { transportPhase } : {}),
...(terminalSource ? { terminalSource } : {}),
...(affinity ? { affinity } : {}),
...(affinityReason ? { affinityReason } : {}),
...(conversationStateScrub ? { conversationStateScrub } : {}),
...(entry.errorCode ? { errorCode: entry.errorCode } : {}),
// 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 } : {}),
...(jevDecision ? { jevDecision } : {}),
...(claudeCompatibility ? { claudeCompatibility } : {}),
...(protocolTrace ? { protocolTrace } : {}),
...normalizeRequestFailureAttribution(entry),
};
}
// Bound hot-path filesystem hardening to once per second while ensuring an external mode
// widening cannot suppress write-triggered repair for the lifetime of the process.
const USAGE_LOG_PERMISSION_RECHECK_MS = 1_000;
type UsageLogPermissionCheck = {
path: string;
checkedAt: number;
};
let ensuredUsageLogDir: UsageLogPermissionCheck | null = null;
let ensuredUsageLogFile: UsageLogPermissionCheck | null = null;
function usageLogPermissionCheckIsCurrent(
check: UsageLogPermissionCheck | null,
path: string,
now: number,
): boolean {
return check?.path === path
&& now >= check.checkedAt
&& now - check.checkedAt < USAGE_LOG_PERMISSION_RECHECK_MS;
}
function ensureUsageLogDir(now: number): void {
const dir = getConfigDir();
if (usageLogPermissionCheckIsCurrent(ensuredUsageLogDir, dir, now)) return;
recordOwnedConfigPath(dir, usageLogPath());
mkdirSync(dir, { recursive: true, mode: 0o700 });
try { chmodSync(dir, 0o700); } catch { /* best-effort on platforms that ignore chmod */ }
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();
const now = Date.now();
const doAppend = (): void => {
ensureUsageLogDir(now);
const filePermissionsCurrent = usageLogPermissionCheckIsCurrent(ensuredUsageLogFile, path, now);
appendFileSync(path, line, { encoding: "utf-8", mode: 0o600 });
if (!filePermissionsCurrent) {
try { chmodSync(path, 0o600); } catch { /* best-effort on platforms that ignore chmod */ }
ensuredUsageLogFile = { path, checkedAt: now };
}
};
try {
doAppend();
} catch (error: any) {
if (error?.code === "ENOENT") {
ensuredUsageLogDir = null;
ensuredUsageLogFile = null;
doAppend();
afterUsageLedgerAppend?.();
return;
}
throw error;
}
afterUsageLedgerAppend?.();
}
export type UsageLogRevision = {
path: string;
dev: number;
ino: number;
birthtimeMs: number;
size: number;
mtimeMs: number;
ctimeMs: number;
};
let usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
const MANAGEMENT_USAGE_MAX_READ_BYTES = 64 * 1024 * 1024;
const RECENT_USAGE_MAX_READ_BYTES = 64 * 1024 * 1024;
const MANAGEMENT_USAGE_READ_CHUNK_BYTES = 1024 * 1024;
const MANAGEMENT_USAGE_MAX_ENTRIES_DEFAULT = 500_000;
/**
* Row cap for a management snapshot. Overridable only so tests can reach the cap without
* building a half-million-row fixture; production always uses the default.
*/
let MANAGEMENT_USAGE_MAX_ENTRIES = MANAGEMENT_USAGE_MAX_ENTRIES_DEFAULT;
export function setManagementUsageMaxEntriesForTests(value: number | null): void {
MANAGEMENT_USAGE_MAX_ENTRIES = value ?? MANAGEMENT_USAGE_MAX_ENTRIES_DEFAULT;
}
const MANAGEMENT_USAGE_FLIGHT_STALE_MS = 30_000;
export interface ManagementUsageSnapshot {
entries: PersistedUsageEntry[];
revision: UsageLogRevision;
truncatedPrefixBytes: number;
entriesTruncated: boolean;
entriesDropped: number;
/** Digest of the covered prefix, used to detect an in-place rewrite before reuse. */
prefixDigest: string;
/**
* Byte offset where the RETAINED ROWS begin.
*
* Distinct from `truncatedPrefixBytes`, which is the API-visible "bytes skipped by the
* byte window" signal and must stay independent of entry-count truncation. When the
* entry cap drops rows, those bytes are not window truncation, but the retained rows do
* start later -- this field tracks that so the byte accounting stays exact.
*/
rowsBeginAtBytes: number;
/**
* Byte length of each returned row, in order, including its newline.
*
* Lets a later read trim rows that have fallen out of the bounded window without
* re-reading or re-parsing them, which is what keeps the returned set equal to the
* window the caller asked for.
*/
entryLengths: number[];
/** Unparseable bytes after the last returned row; the next read folds them forward. */
trailingSkippedBytes: number;
}
let managementUsageReadInflight: {
key: string;
openedSize: number;
promise: Promise<ManagementUsageSnapshot>;
startedAt: number;
abort: AbortController;
} | null = null;
/**
* Append-tolerant snapshot of the last management read.
*
* The management reader parses a 64 MiB tail into ~53k objects, which costs roughly
* 640 MB of transient RSS per cold call. The JS objects are collected promptly, but
* the allocator does not return those pages, so every cold miss ratchets process RSS
* upward and never comes back down (observed: 7.9 GiB RSS against a 130 MB JS heap).
*
* Reparsing an unchanged prefix is what makes that transient recur. `usage.jsonl` is
* append-only under a stable identity, so when the file has only grown we keep the
* previously parsed rows and parse just the appended bytes. This is retained state, so
* it is registered with the app-owned memory budget and is evictable under pressure.
*/
interface RetainedUsageSnapshot {
identityKey: string;
maxReadBytes: number;
/** Absolute end offset in the file that `entries` already covers. */
coveredThroughBytes: number;
/**
* Digest of the last bytes of the covered prefix, re-verified before extending.
*
* Identity (path/dev/ino/birthtime) intentionally ignores size and mtime so appends
* can share work, which also means an in-place rewrite that keeps the inode is
* invisible to it. A hand-edit or external compaction can therefore replace history
* under a stable identity without shrinking the file. Re-reading this trailing window
* catches that: if the bytes behind `coveredThroughBytes` changed, the retained rows
* no longer describe the file and must not be extended.
*/
prefixDigest: string;
/** Bytes of the file skipped ahead of the retained window. */
truncatedPrefixBytes: number;
/** Byte length of each retained row, so out-of-window rows can be trimmed exactly. */
entryLengths: number[];
/** Unparseable bytes after the last retained row; folded into the next row's span. */
trailingSkippedBytes: number;
/** Byte offset where the retained rows begin; see ManagementUsageSnapshot. */
rowsBeginAtBytes: number;
entries: PersistedUsageEntry[];
entriesTruncated: boolean;
entriesDropped: number;
revision: UsageLogRevision;
retainedAt: number;
approxBytes: number;
}
let retainedUsageSnapshot: RetainedUsageSnapshot | null = null;
/** Rough per-row retained cost; exact sizing would cost another full serialization pass. */
const RETAINED_USAGE_ENTRY_BYTES = 512;
/** Chunk size used when digesting a retained region. */
const RETAINED_USAGE_DIGEST_CHUNK_BYTES = 1024 * 1024;
/**
* Digest a byte range into `hash`; false when it cannot be read.
*
* Deliberately not sampled. A sampled digest covers a vanishing fraction of a large
* prefix (32 KiB of 64 MiB is 0.05%), so an ordinary fixed-width in-place edit -- a
* redaction script fixing one field, a compaction rewriting a middle region -- lands in
* a gap by default and the stale rows are served.
*
* Hashing from byte 0 on every call is also wrong: that is O(file) per poll while the
* read it protects is capped at maxReadBytes, so the ratio degrades as the ledger grows
* and becomes SLOWER than a full read past roughly 1-2 GB. Only the retained REGION
* (truncatedPrefixBytes..coveredThroughBytes) is hashed. It is never wider than the
* window, and bytes below the retained start describe no retained row, so reading them
* would prove nothing.
*/
function updateUsageDigest(hash: Hash, fd: number, from: number, to: number): boolean {
if (to <= from) return true;
const buffer = Buffer.allocUnsafe(Math.min(RETAINED_USAGE_DIGEST_CHUNK_BYTES, to - from));
for (let position = from; position < to;) {
const length = Math.min(buffer.byteLength, to - position);
let offset = 0;
while (offset < length) {
const read = readSync(fd, buffer, offset, length - offset, position + offset);
if (read === 0) return false;
offset += read;
}
hash.update(buffer.subarray(0, length));
position += length;
}
return true;
}
/**
* Digest of `from`..`to`; null when it cannot be read.
*
* The range is bound into the digest so a region cannot be confused with an equal-length
* region at a different offset.
*/
function usageRegionDigest(fd: number, from: number, to: number): string | null {
if (to <= from) return `${from}:${to}:empty`;
const hash = createHash("sha256");
if (!updateUsageDigest(hash, fd, from, to)) return null;
return `${from}:${to}:${hash.digest("hex")}`;
}
function retainedUsageSnapshotBytes(entries: PersistedUsageEntry[]): number {
return entries.length * RETAINED_USAGE_ENTRY_BYTES;
}
export function discardRetainedUsageSnapshot(): number {
const released = retainedUsageSnapshot?.approxBytes ?? 0;
retainedUsageSnapshot = null;
return released;
}
export function retainedUsageSnapshotStats(): {
count: number;
bytes: number;
oldestAt: number | null;
} {
if (!retainedUsageSnapshot) return { count: 0, bytes: 0, oldestAt: null };
return {
count: 1,
bytes: retainedUsageSnapshot.approxBytes,
oldestAt: retainedUsageSnapshot.retainedAt,
};
}
/** Test-only observability for proving that unchanged prefixes are not reparsed. */
export function usageReadCacheStatsForTests(): Readonly<typeof usageReadCacheStats> {
return { ...usageReadCacheStats };
}
export function resetUsageReadCacheForTests(): void {
usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
managementUsageReadInflight?.abort.abort();
managementUsageReadInflight = null;
retainedUsageSnapshot = null;
ensuredUsageLogDir = null;
ensuredUsageLogFile = null;
}
function readExactly(fd: number, length: number, position: number): Buffer | null {
const output = Buffer.allocUnsafe(length);
let offset = 0;
while (offset < length) {
const read = readSync(fd, output, offset, length - offset, position + offset);
if (read === 0) return null;
offset += read;
}
return output;
}
function usageLogRevision(path: string, stat: ReturnType<typeof fstatSync>): UsageLogRevision {
if (!stat.isFile()) throw new Error("usage log is not a regular file");
return {
path,
dev: Number(stat.dev),
ino: Number(stat.ino),
birthtimeMs: Number(stat.birthtimeMs),
size: Number(stat.size),
mtimeMs: Number(stat.mtimeMs),
ctimeMs: Number(stat.ctimeMs),
};
}
export function usageLogRevisionKey(revision: UsageLogRevision | null): string {
if (!revision) return "missing";
return [
revision.path,
revision.dev,
revision.ino,
revision.birthtimeMs,
revision.size,
revision.mtimeMs,
revision.ctimeMs,
].join("\0");
}
/** Identity of the usage ledger file, excluding size/mtime/ctime so appends can share work. */
export function usageLogIdentityKey(revision: UsageLogRevision | null): string {
if (!revision) return "missing";
return [revision.path, revision.dev, revision.ino, revision.birthtimeMs].join("\0");
}
export function currentUsageLogRevision(): UsageLogRevision | null {
const path = usageLogPath();
if (!existsSync(path)) return null;
let fd: number | undefined;
try {
fd = openSync(path, "r");
return usageLogRevision(path, fstatSync(fd));
} finally {
if (fd !== undefined) closeSync(fd);
}
}
async function parseUsageTextCooperatively(text: string, signal: AbortSignal): Promise<{
entries: PersistedUsageEntry[];
entriesDropped: number;
entryLengths: number[];
/** Bytes of unparseable lines after the final accepted row. */
trailingSkippedBytes: number;
/** Bytes of rows removed by the entry cap, which move into the skipped prefix. */
cappedPrefixBytes: number;
}> {
// Split on "\n" only, so a CRLF line keeps its "\r" and its byte length stays exact.
// Splitting on /\r?\n/ consumes two bytes but leaves no way to tell that it did, which
// made the recorded lengths short by one byte per line on a CRLF ledger and failed the
// accounting self-check. JSON.parse tolerates the trailing "\r".
const lines = text.split("\n");
usageReadCacheStats.parsedLines += lines.filter(line => line.trim()).length;
const entries: PersistedUsageEntry[] = [];
// Byte length of each accepted row including its newline, so a later read can trim
// rows that fall out of the bounded window without re-reading the file.
const entryLengths: number[] = [];
const batchSize = 1_000;
// Bytes of lines that did not yield an entry (malformed JSON, missing requestId, a
// torn final write). They still occupy space in the file, so they are folded into the
// next accepted row's recorded length. Dropping them would make the recorded lengths
// sum to less than the real byte span, and the window trim -- which walks forward by
// summing those lengths -- would consume extra rows to reach the window start,
// silently hiding history and desynchronizing truncatedPrefixBytes.
let pendingSkippedBytes = 0;
for (let offset = 0; offset < lines.length; offset += batchSize) {
if (signal.aborted) throw signal.reason;
const batch = lines.slice(offset, offset + batchSize);
for (let index = 0; index < batch.length; index++) {
const line = batch[index]!;
// The split leaves a trailing "" after the final newline; it occupies no bytes.
const isLastLine = offset + index === lines.length - 1;
const lineBytes = Buffer.byteLength(line, "utf-8") + (isLastLine && line === "" ? 0 : 1);
const parsed = parseUsageLines([line]);
if (parsed.length === 0) {
pendingSkippedBytes += lineBytes;
continue;
}
entries.push(parsed[0]!);
entryLengths.push(lineBytes + pendingSkippedBytes);
pendingSkippedBytes = 0;
}
if (offset + batchSize < lines.length) {
// JSON parsing dominates large-log startup. Yield between bounded batches so
// Bun can continue serving health and settings requests on the same thread.
await new Promise<void>(resolve => setTimeout(resolve, 0));
}
}
// Skipped bytes AFTER the last accepted row belong to no entry length, so report them
// separately; the trim arithmetic adds them back to keep lengths summing to the span.
const trailingSkippedBytes = pendingSkippedBytes;
if (entries.length <= MANAGEMENT_USAGE_MAX_ENTRIES) {
return { entries, entriesDropped: 0, entryLengths, trailingSkippedBytes, cappedPrefixBytes: 0 };
}
const entriesDropped = entries.length - MANAGEMENT_USAGE_MAX_ENTRIES;
return {
entries: entries.slice(-MANAGEMENT_USAGE_MAX_ENTRIES),
entriesDropped,
entryLengths: entryLengths.slice(-MANAGEMENT_USAGE_MAX_ENTRIES),
trailingSkippedBytes,
// Bytes of the rows the cap removed. The caller adds them to its skipped prefix so
// the recorded lengths keep summing to the byte span they describe.
cappedPrefixBytes: entryLengths
.slice(0, entryLengths.length - MANAGEMENT_USAGE_MAX_ENTRIES)
.reduce((total, length) => total + length, 0),
};
}
async function readUsageEntriesFullCooperatively(
path: string,
signal: AbortSignal,
maxReadBytes: number,
): Promise<ManagementUsageSnapshot> {
let fd: number | undefined;
try {
fd = openSync(path, "r");
const stat = fstatSync(fd);
const size = Number(stat.size);
const start = Math.max(0, size - maxReadBytes);
const chunks: Buffer[] = [];
for (let position = start; position < size;) {
if (signal.aborted) throw signal.reason;
const length = Math.min(MANAGEMENT_USAGE_READ_CHUNK_BYTES, size - position);
const chunk = readExactly(fd, length, position);
if (chunk === null) throw new Error("usage log changed while it was being read");
chunks.push(chunk);
position += length;
}
let bytes = Buffer.concat(chunks);
let truncatedPrefixBytes = start;
if (start > 0) {
const preceding = readExactly(fd, 1, start - 1);
if (preceding === null) throw new Error("usage log changed while it was being read");
if (preceding[0] !== 0x0a) {
const newline = bytes.indexOf(0x0a);
if (newline < 0) {
truncatedPrefixBytes += bytes.byteLength;
bytes = Buffer.alloc(0);
} else {
truncatedPrefixBytes += newline + 1;
bytes = bytes.subarray(newline + 1);
}
}
}
const parsed = await parseUsageTextCooperatively(bytes.toString("utf-8"), signal);
usageReadCacheStats.fullReads += 1;
// Rows removed by the entry cap start the retained rows later in the file. That is
// NOT byte-window truncation, so it must not move truncatedPrefixBytes -- the two
// signals are independent in the API. It is tracked separately for the byte
// accounting the incremental reader relies on.
const rowsBeginAtBytes = truncatedPrefixBytes + parsed.cappedPrefixBytes;
// Digest the exact prefix these rows describe, so a later incremental read can
// prove the file was appended to rather than rewritten under the same inode.
const prefixDigest = usageRegionDigest(fd, rowsBeginAtBytes, Number(stat.size));
if (prefixDigest === null) throw new Error("usage log changed while it was being read");
return {
entries: parsed.entries,
revision: usageLogRevision(path, stat),
truncatedPrefixBytes,
entriesTruncated: parsed.entriesDropped > 0,
entriesDropped: parsed.entriesDropped,
prefixDigest,
entryLengths: parsed.entryLengths,
trailingSkippedBytes: parsed.trailingSkippedBytes,
rowsBeginAtBytes,
};
} finally {
if (fd !== undefined) closeSync(fd);
}
}
/**
* Parse only the bytes appended since the retained snapshot's covered offset.
*
* Returns null when the retained snapshot cannot be extended safely — a different
* identity or read window, a file that shrank (replacement/truncation), or a covered
* offset that no longer sits on a record boundary. Callers then fall back to a full
* bounded read.
*/
async function readUsageEntriesIncrementally(
path: string,
signal: AbortSignal,
maxReadBytes: number,
retained: RetainedUsageSnapshot,
): Promise<ManagementUsageSnapshot | null> {
let fd: number | undefined;
try {
fd = openSync(path, "r");
const stat = fstatSync(fd);
const revision = usageLogRevision(path, stat);
if (usageLogIdentityKey(revision) !== retained.identityKey) return null;
const size = Number(stat.size);
// A shrink means truncation or replacement-in-place; the retained rows may no
// longer correspond to file contents, so refuse to extend them.
if (size < retained.coveredThroughBytes) return null;
// Retained-state reuse is only an optimization. A burst larger than the configured
// window must re-anchor through the bounded full-tail reader instead of reading and
// parsing every byte appended since the previous poll.
if (size - retained.coveredThroughBytes > maxReadBytes) return null;
// Verify the retained REGION is unchanged before anything is reused. Identity keeps
// dev/ino/birthtime, and an append and an in-place rewrite both move mtime/ctime
// forward, so only the bytes themselves settle it.
//
// Only `truncatedPrefixBytes..coveredThroughBytes` is hashed: that is exactly the
// span the retained rows were parsed from, and after trimming it is never wider than
// maxReadBytes. Hashing from byte 0 instead would make every poll O(file) -- cheaper
// than a reparse on a 245 MB ledger but MORE expensive past roughly 1-2 GB, turning
// this optimization into a pessimization on exactly the growth curve an append-only
// ledger follows. Bytes before the retained start are not described by any retained
// row, so re-reading them proves nothing.
const covered = usageRegionDigest(fd, retained.rowsBeginAtBytes, retained.coveredThroughBytes);
if (covered === null || covered !== retained.prefixDigest) return null;
// Read and parse ONLY the appended bytes.
let appendedEntries: PersistedUsageEntry[] = [];
let appendedLengths: number[] = [];
let appendedDropped = 0;
let appendedTrailingSkipped = retained.trailingSkippedBytes;
if (size > retained.coveredThroughBytes) {
// The covered offset must land immediately after a newline, or the retained rows
// and the appended text do not join on a record boundary.
if (retained.coveredThroughBytes > 0) {
const preceding = readExactly(fd, 1, retained.coveredThroughBytes - 1);
if (preceding === null || preceding[0] !== 0x0a) return null;
}
const chunks: Buffer[] = [];
for (let position = retained.coveredThroughBytes; position < size;) {
if (signal.aborted) throw signal.reason;
const length = Math.min(MANAGEMENT_USAGE_READ_CHUNK_BYTES, size - position);
const chunk = readExactly(fd, length, position);
if (chunk === null) throw new Error("usage log changed while it was being read");
chunks.push(chunk);
position += length;
}
const appended = await parseUsageTextCooperatively(Buffer.concat(chunks).toString("utf-8"), signal);
appendedEntries = appended.entries;
appendedLengths = appended.entryLengths;
appendedDropped = appended.entriesDropped;
// A capped appended chunk is not joinable: its dropped rows sit between the
// retained rows and the kept ones, so the lengths no longer describe a contiguous
// span. Fall back to a full read.
if (appended.cappedPrefixBytes > 0) return null;
// If the appended chunk produced rows, its own trailing skipped bytes become the
// new trailing remainder; otherwise the earlier remainder still stands and the new
// skipped bytes add to it.
appendedTrailingSkipped = appended.entries.length > 0
? appended.trailingSkippedBytes
: retained.trailingSkippedBytes + appended.trailingSkippedBytes;
}
// Re-anchor the window in place. Rows that have fallen outside `size - maxReadBytes`
// are dropped using their recorded byte lengths, so the result is exactly the rows a
// fresh bounded read would load -- no superset, and truncatedPrefixBytes and
// snapshotWindow keep describing the read honestly. Refusing here instead would make
// this path dead code on any ledger past the window, which is precisely the case it
// exists for.
const windowStart = Math.max(0, size - maxReadBytes);
let entries = retained.entries.concat(appendedEntries);
// Skipped bytes trailing the retained rows sit BETWEEN them and the appended rows, so
// they belong to the first appended row's span. Folding them in keeps the recorded
// lengths summing to the true byte distance, which is what the trim walk relies on.
const joinedLengths = appendedLengths.slice();
if (retained.trailingSkippedBytes > 0 && joinedLengths.length > 0) {
joinedLengths[0] = joinedLengths[0]! + retained.trailingSkippedBytes;
}
let lengths = retained.entryLengths.concat(joinedLengths);
let rowsBeginAtBytes = retained.rowsBeginAtBytes;
// Byte-window truncation advances ONLY here, so it stays exactly what a cold read of
// this window reports. The entry cap below is entry-count truncation and must not
// move it -- the two are independent signals in the API.
let windowTruncatedBytes = retained.truncatedPrefixBytes;
let dropIndex = 0;
while (dropIndex < lengths.length && rowsBeginAtBytes < windowStart) {
rowsBeginAtBytes += lengths[dropIndex]!;
windowTruncatedBytes += lengths[dropIndex]!;
dropIndex += 1;
}
// If every row is gone and a trailing unparseable remainder still sits before the
// window start, nothing is left to advance the offset with: the retained span would
// keep growing past maxReadBytes on each malformed-only append while the accounting
// still balanced. Re-anchor with a full read instead.
if (rowsBeginAtBytes < windowStart) return null;
if (dropIndex > 0) {
entries = entries.slice(dropIndex);
lengths = lengths.slice(dropIndex);
}
let entriesDropped = retained.entriesDropped + appendedDropped;
if (entries.length > MANAGEMENT_USAGE_MAX_ENTRIES) {
// A cold read applies the entry cap to the whole window and reports byte
// truncation for the window boundary alone. An incremental read arrives at the cap
// by a different route and cannot reconstruct that ordering from retained state, so
// continuing here would report a truncatedPrefixBytes that disagrees with a fresh
// read of the same window. Re-anchor instead.
//
// This is reachable in production, not a theoretical branch: rows average ~118
// bytes on a real ledger, so 500,000 of them occupy ~56 MiB and fit inside the
// 64 MiB window. Both truncations can therefore apply at once.
return null;
}
// The recorded lengths plus the trailing remainder must account for every byte from
// the retained rows' start to EOF; if they do not, the lengths and the file have
// diverged and the retained rows cannot be trusted.
let accounted = appendedTrailingSkipped;
for (const length of lengths) accounted += length;
if (rowsBeginAtBytes + accounted !== size) return null;
usageReadCacheStats.tailReads += 1;
// Byte-window truncation is what the API reports, and it stays independent of
// entry-count truncation. A cold read reports the record boundary it actually landed
// on, which is where the rows begin MINUS whatever the entry cap removed -- the cap
// is not window truncation. When nothing was skipped by the window at all, a cold
// read reports 0.
const truncatedPrefixBytes = windowTruncatedBytes;
return {
entries,
revision,
truncatedPrefixBytes,
// ENTRY-count truncation only. Byte-window truncation is reported by
// truncatedPrefixBytes, and the route ORs the two itself; folding bytes in here
// would make a byte-truncated read claim rows were dropped when none were.
entriesTruncated: entriesDropped > 0,
entriesDropped,
// Reuse this read's verified digest only for identical bounds. Growth or trimming
// needs a new digest of the returned region; metadata alone never proves reuse.
prefixDigest: rowsBeginAtBytes === retained.rowsBeginAtBytes && size === retained.coveredThroughBytes
? covered : usageRegionDigest(fd, rowsBeginAtBytes, size) ?? "",
entryLengths: lengths,
trailingSkippedBytes: appendedTrailingSkipped,
rowsBeginAtBytes,
};
} finally {
if (fd !== undefined) closeSync(fd);
}
}
/**
* Management API reader: full parses yield between bounded batches and concurrent
* callers share work when they observe the same ledger identity and byte window.
* Appends keep that identity; replacements (inode/birthtime change) start a new flight.
* The parsed tail is retained under the app-owned memory budget so an append reparses
* only the appended bytes; the retained rows are evictable and are copied per caller.
*/
export async function readUsageSnapshotForManagement(maxReadBytes = MANAGEMENT_USAGE_MAX_READ_BYTES): Promise<{
entries: PersistedUsageEntry[];
revision: UsageLogRevision | null;
truncatedPrefixBytes: number;
entriesTruncated: boolean;
entriesDropped: number;
}> {
if (!Number.isSafeInteger(maxReadBytes) || maxReadBytes <= 0) throw new RangeError("management usage max read bytes must be positive");
const path = usageLogPath();
if (!existsSync(path)) return { entries: [], revision: null, truncatedPrefixBytes: 0, entriesTruncated: false, entriesDropped: 0 };
const observed = currentUsageLogRevision();
const key = `${usageLogIdentityKey(observed)}\0${maxReadBytes}`;
const observedSize = observed?.size ?? 0;
const existing = managementUsageReadInflight;
const replacement = Boolean(existing && observedSize < existing.openedSize);
if (!replacement && existing?.key === key && Date.now() - existing.startedAt <= MANAGEMENT_USAGE_FLIGHT_STALE_MS) {
const shared = await existing.promise;
return { ...shared, entries: shared.entries.slice() };
}
if (existing && (existing.key !== key || replacement || Date.now() - existing.startedAt > MANAGEMENT_USAGE_FLIGHT_STALE_MS)) {
existing.abort.abort(new Error("management usage read superseded"));
} else if (existing) {
const shared = await existing.promise;
return { ...shared, entries: shared.entries.slice() };
}
const abort = new AbortController();
const retained = retainedUsageSnapshot;
const reusable = retained
&& retained.identityKey === usageLogIdentityKey(observed)
&& retained.maxReadBytes === maxReadBytes
? retained
: null;
const promise = (async (): Promise<ManagementUsageSnapshot> => {
if (reusable) {
const incremental = await readUsageEntriesIncrementally(path, abort.signal, maxReadBytes, reusable);
if (incremental) return incremental;
// The retained rows could not be extended safely; drop them before the full read
// so a stale window is never combined with freshly parsed bytes.
discardRetainedUsageSnapshot();
}
return readUsageEntriesFullCooperatively(path, abort.signal, maxReadBytes);
})();
managementUsageReadInflight = { key, openedSize: observedSize, promise, startedAt: Date.now(), abort };
try {
const snapshot = await promise;
retainedUsageSnapshot = {
identityKey: usageLogIdentityKey(snapshot.revision),
maxReadBytes,
coveredThroughBytes: snapshot.revision.size,
prefixDigest: snapshot.prefixDigest,
truncatedPrefixBytes: snapshot.truncatedPrefixBytes,
entryLengths: snapshot.entryLengths,
trailingSkippedBytes: snapshot.trailingSkippedBytes,
rowsBeginAtBytes: snapshot.rowsBeginAtBytes,
entries: snapshot.entries,
entriesTruncated: snapshot.entriesTruncated,
entriesDropped: snapshot.entriesDropped,
revision: snapshot.revision,
retainedAt: Date.now(),
approxBytes: retainedUsageSnapshotBytes(snapshot.entries),
};
enforceAppOwnedMemoryBudget();
return { ...snapshot, entries: snapshot.entries.slice() };
} finally {
if (managementUsageReadInflight?.promise === promise) managementUsageReadInflight = null;
}
}
export async function readUsageEntriesForManagement(): Promise<PersistedUsageEntry[]> {
return (await readUsageSnapshotForManagement()).entries;
}
/** Keep legacy optional fields permissive, but reject rows that cannot be safely attributed. */
export function normalizePersistedUsageRow(value: unknown): PersistedUsageEntry | undefined {
if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
const row = value as Record<string, unknown>;
if (typeof row.requestId !== "string" || typeof row.provider !== "string") return undefined;
return normalizeUsageEntry(row as unknown as PersistedUsageEntry);
}
export function readUsageEntries(): PersistedUsageEntry[] {
const path = usageLogPath();
if (!existsSync(path)) return [];
const lines = readFileSync(path, "utf-8").split(/\r?\n/);
const entries: PersistedUsageEntry[] = [];
for (const line of lines) {
if (!line.trim()) continue;
try {
const parsed = normalizePersistedUsageRow(JSON.parse(line));
if (parsed) entries.push(parsed);
} catch {
/* keep reading after a partially written or hand-edited line */
}
}
return entries;
}
function parseUsageLines(lines: string[]): PersistedUsageEntry[] {
const entries: PersistedUsageEntry[] = [];
for (const line of lines) {
if (!line.trim()) continue;
try {
const parsed = normalizePersistedUsageRow(JSON.parse(line));
if (parsed) entries.push(parsed);
} catch {
/* skip partial / hand-edited lines */
}
}
return entries;
}
/**
* Read only the newest `limit` usage.jsonl rows without loading the whole append-only
* file into memory. Used by request-log hydration on `ocx start`.
*/
export function readRecentUsageEntries(limit: number, configDir?: string): PersistedUsageEntry[] {
if (!Number.isFinite(limit) || limit <= 0) return [];
const path = usageLogPath(configDir);
if (!existsSync(path)) return [];
let fd: number | undefined;
try {
fd = openSync(path, "r");
const size = fstatSync(fd).size;
if (size <= 0) return [];
// Trace-sized rows need a larger per-row budget than the pre-trace ledger,
// but startup hydration must never grow into an unbounded whole-file read.
const maxWindowBytes = Math.min(size, RECENT_USAGE_MAX_READ_BYTES);
let windowBytes = Math.min(maxWindowBytes, Math.max(64 * 1024, Math.ceil(limit) * 20 * 1024));
while (true) {
const start = Math.max(0, size - windowBytes);
const buf = Buffer.alloc(size - start);
readSync(fd, buf, 0, buf.length, start);
let text = buf.toString("utf-8");
if (start > 0) {
const nl = text.indexOf("\n");
if (nl < 0) {
if (start === 0 || windowBytes >= maxWindowBytes) break;
windowBytes = Math.min(maxWindowBytes, windowBytes * 4);
continue;
}
text = text.slice(nl + 1);
}
const lines = text.split(/\r?\n/).filter(line => line.trim());
// Parse ALL lines first, then take the last N valid entries. This way corrupt
// or partial lines are filtered out during parsing and we always return the
// most recent N valid rows (not N physical lines minus corrupt ones).
const entries = parseUsageLines(lines);
if (entries.length >= limit || start === 0 || windowBytes >= maxWindowBytes) return entries.slice(-limit);
windowBytes = Math.min(maxWindowBytes, windowBytes * 4);
}
return [];
} catch {
return [];
} finally {
if (fd !== undefined) {
try { closeSync(fd); } catch { /* ignore */ }
}
}
}