UNPKG

@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
/** * 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; }