@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
240 lines (225 loc) • 11.2 kB
text/typescript
/**
* The telemetry vocabulary both the proxy and the dashboard read.
*
* This module has NO imports, and that is its entire job. The dashboard is a separate TypeScript
* project with `erasableSyntaxOnly`, and a type-only import still pulls the imported file's whole
* import graph into that project. Importing these names from `./log` therefore dragged
* `node:fs`, `node:crypto` and the config barrel into the browser build, where a parameter
* property in `src/config/atomic-write.ts` fails to compile. The names below are the ones a
* browser legitimately needs, so they live where a browser can reach them.
*
* Anything added here must stay free of imports. A contract that acquires a dependency stops
* being a contract.
*/
/**
* Recovery kinds recorded per attempt in the usage log; the dashboard renders localized labels
* for these wire values.
*
* The roster is the single statement of this vocabulary and the type is derived from it. It was
* written twice once -- as a union and as the read-back whitelist -- and the two are not
* interchangeable: a member added only to the union compiles, is written to disk, and is dropped
* on the next read, so the row loses the field that says why it recovered. One declaration cannot
* drift from itself, and the dashboard now reads this one rather than keeping a third copy.
*/
export const ATTEMPT_RECOVERY_KIND_ROSTER = Object.freeze([
"transient-5xx",
"connection-reset",
"oauth-401",
"oauth-account-403",
"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",
"anthropic-fast-downgrade",
] as const);
export type AttemptRecoveryKind = typeof ATTEMPT_RECOVERY_KIND_ROSTER[number];
/**
* 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: nothing was eligible, or something was and the send budget withheld it. Those need
* opposite follow-ups and the second 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".
*/
export const ATTEMPT_RECOVERY_WITHHELD_ROSTER = Object.freeze([
"retry-send-budget",
"rotation-send-budget",
] as const);
export type AttemptRecoveryWithheld = typeof ATTEMPT_RECOVERY_WITHHELD_ROSTER[number];
/**
* How far a failed exchange got, ordered by how much the DOWNSTREAM CLIENT observed.
*
* The order is by client observation rather than by upstream progress, because the question it
* answers is whether resending can duplicate something the caller already saw. An upstream that
* completed a turn we never relayed has committed nothing downstream; an upstream that emitted
* one token has.
*
* The roster lives here rather than beside the resend tables for the reason stated at the top of
* this file: the dashboard renders a label per member, and reaching the table module for the
* names would drag its import graph into the browser project. `src/lib/request-failure-model.ts`
* re-exports it, so every existing importer keeps its path and there is still exactly one
* declaration.
*/
export const REQUEST_FAILURE_STAGES = Object.freeze([
/** No response head exists. Whether the origin began the turn is not known from the stage alone. */
"pre-header",
/** A status line and headers exist, and no protocol body event has been parsed yet. */
"headers-only",
/** The protocol body began with control events only -- `response.created`, quota frames. */
"protocol-prelude",
/** At least one output-bearing event reached the caller. */
"semantic-output",
/** A tool call or other externally visible effect was emitted. */
"side-effect",
/** A terminal event settled the turn after its answer reached the caller. */
"terminal",
] as const);
export type RequestFailureStage = typeof REQUEST_FAILURE_STAGES[number];
/**
* Why the request failed, as one closed dictionary for every layer.
*
* Bounded on purpose: these are wire values a maintainer reads and a metric labels by, never a
* credential, an account identifier, an upstream body or prompt content. That bound is what lets
* the value be a Prometheus label and a grouping key without a masking pass -- a closed roster
* has nothing to mask.
*/
export const REQUEST_FAILURE_CAUSES = Object.freeze([
/** The bytes provably never reached the origin: connect refused, DNS failure, TLS handshake. */
"transport-unsent",
/** The bytes left and the connection died before a head. The origin may be running the turn. */
"transport-ambiguous",
/** The origin answered that it would not start the turn now: 503, overloaded, backpressure. */
"upstream-declined",
/** A 429 rate limit. Capacity is momentarily gone; waiting is the remedy. */
"rate-limit",
/** Plan or credit quota is gone. Waiting out a retry window does not help; the account must change. */
"quota-exhausted",
/** Credentials were rejected: 401, 403 on identity. */
"credential-rejected",
/** The origin evaluated the content and refused it. Identical bytes get the identical refusal. */
"policy-refusal",
/**
* The origin rejected a request PARAMETER rather than the content: an unsupported reasoning
* effort, an unknown field. Distinct from `policy-refusal` because the remedy is opposite --
* the same content succeeds once the parameter is adjusted.
*/
"parameter-rejected",
/** Opaque replay state was rejected as unverifiable. Only a request without it can succeed. */
"ciphertext-refusal",
/**
* The payload exceeded a size the origin accepts. A smaller rebuild of the same turn can
* succeed, which is why this is not the same answer as `payload-rejected`.
*/
"payload-too-large",
/** The payload was rejected on its merits: unsupported media, malformed part. No repair helps. */
"payload-rejected",
/**
* The origin returned a server-side fault. Whether it had already begun the turn is not
* knowable from the status, so this is the honest classification for the mixed 5xx set the
* transient layer retries: 503 really did decline, 500 may not have.
*/
"upstream-fault",
/** The turn settled carrying no usable output. */
"empty-output",
/** The caller went away. */
"client-cancelled",
/** This proxy refused before dispatch: send budget, route policy, replay refusal. */
"local-refusal",
] as const);
export type RequestFailureCause = typeof REQUEST_FAILURE_CAUSES[number];
/**
* Whether this proxy may send the request again. Derived at READ time from the stage and the
* cause and never persisted, so a stored row cannot carry a verdict that the current table
* would no longer reach.
*
* Every refusal names WHY it refused, because the three reasons need different operator
* responses and used to arrive as one undifferentiated "no retry".
*/
export const RESEND_PERMISSIONS = Object.freeze([
/** The same request may be sent again. */
"permitted",
/** Only a modified request may be sent: rotated credential, stripped ciphertext. */
"permitted-after-repair",
/** Upstream execution state is unknown. No AUTOMATIC resend. */
"refused-ambiguous",
/** The caller already observed output or an externally visible effect. */
"refused-committed",
/** Identical bytes would get the identical answer. */
"refused-futile",
] as const);
export type ResendPermission = typeof RESEND_PERMISSIONS[number];
/**
* Where a terminal or failure was observed on the wire.
*
* Declared here because three modules read it as a closed set -- the durable row's validator,
* the failure attribution and the failure fingerprint -- and a fourth restatement in a test is
* how a member added later leaves an "exhaustive" cross product green without exercising it.
*/
export const REQUEST_TRANSPORT_PHASES = Object.freeze([
"pre_headers",
"mid_stream",
"terminal_sse",
] as const);
export type RequestTransportPhase = typeof REQUEST_TRANSPORT_PHASES[number];
/**
* What an attempt actually delivered, as five bounded counts (#3983).
*
* #3983 wanted these signals and emitted one debug line per event to get them. That is a second
* durable record: `emitDebugLine` writes the in-process ring AND stderr, and stderr is redirected
* to the service log under both launchd and systemd, so an installed service ends up with a
* per-event history beside the ledger, carrying its own retention, sequencing and identity. It
* also fingerprinted each payload under a process-global random key, which makes every repeated
* prompt fragment, tool name and error message correlatable for the process lifetime.
*
* Counts answer the same questions -- a missing terminal, adapter-to-client loss, empty output,
* partial output size -- and cannot carry content at all. They ride the attempt, so they inherit
* the ledger's normalization, masking and retention rather than acquiring their own.
*
* Counted where the event is DELIVERED, not where it is read. An adapter event the client never
* received is exactly the discrepancy worth seeing, and counting both ends at the reader would
* make the two numbers equal by construction.
*/
export interface AttemptDeliverySummary {
/** Events this attempt's adapter produced. */
adapterEvents: number;
/** Frames that reached the client transport, after a successful enqueue. */
relayedEvents: number;
/** UTF-8 bytes of output-bearing delta actually relayed. Never the content itself. */
semanticBytes: number;
/** Externally visible effects relayed: a tool call or a search call starting. */
sideEffectEvents: number;
/** Terminal frames relayed. Zero on a delivered stream is the missing-terminal signal. */
terminalEvents: number;
}
/**
* What one logical request spent upstream, decomposed by how much of it is explained.
*
* The counting half of the durable spend record, without the routing detail that sits beside it.
* Every surface that reports a send total reads these three numbers and none of them recomputes a
* total of its own -- a recomputed total is how the exporter and the dashboard ended up reporting
* different send counts for the same request.
*/
export interface RequestSpendTotals {
/** Physical upstream sends summed across every attempt, 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;
}