@askalf/dario 6.4.0 → 6.6.0

package/dist/codex-backend.d.ts

@@ -48,6 +48,9 @@ export interface CodexForwardOutcome {
 export interface CodexDecline {
     status: number;
     retryAfterMs: number | null;
+    /** The seat that declined. Without it a caller can cool the provider but
+     *  not the account, which is the whole point of a pool. */
+    alias: string;
 }
 /** The cached slug list for an alias WITHOUT fetching. For the admin surface:
  *  a status read must never cost an upstream call or a token refresh. */
@@ -275,7 +278,16 @@ export declare function buildCodexHeaders(creds: CodexAccountCredentials): Recor
  * into a buffered response object is not built yet. A non-streaming client
  * gets a 400 saying so.
  */
-export declare function forwardResponsesToCodex(res: ServerResponse, body: Record<string, unknown>, creds: CodexAccountCredentials, corsOrigin: string, securityHeaders: Record<string, string>, upstreamTimeoutMs: number, verbose: boolean, fetchImpl?: typeof fetch, onDone?: (outcome: CodexForwardOutcome) => void): Promise<boolean>;
+export declare function forwardResponsesToCodex(res: ServerResponse, body: Record<string, unknown>, creds: CodexAccountCredentials, corsOrigin: string, securityHeaders: Record<string, string>, upstreamTimeoutMs: number, verbose: boolean, fetchImpl?: typeof fetch, onDone?: (outcome: CodexForwardOutcome) => void, 
+/** Mirrors forwardToCodex. A 429 or 5xx is the SEAT saying no, and the
+ *  caller needs to know which seat and for how long — without it the pool
+ *  cannot cool a limited seat on this path, so selection hands the same
+ *  rate-limited account back on every following request. */
+onDecline?: (info: CodexDecline) => void, 
+/** When true a decline returns false WITHOUT writing, so the caller can
+ *  retry the request on a healthy peer. False keeps the old behaviour: the
+ *  upstream error is written through as the backend sent it. */
+deferOnUnavailable?: boolean): Promise<boolean>;
 /**
  * Serve a request from a stored Codex account, in either client wire shape.
  *

package/dist/codex-backend.js

@@ -759,7 +759,16 @@ export function buildCodexHeaders(creds) {
  * into a buffered response object is not built yet. A non-streaming client
  * gets a 400 saying so.
  */
-export async function forwardResponsesToCodex(res, body, creds, corsOrigin, securityHeaders, upstreamTimeoutMs, verbose, fetchImpl = fetch, onDone) {
+export async function forwardResponsesToCodex(res, body, creds, corsOrigin, securityHeaders, upstreamTimeoutMs, verbose, fetchImpl = fetch, onDone, 
+/** Mirrors forwardToCodex. A 429 or 5xx is the SEAT saying no, and the
+ *  caller needs to know which seat and for how long — without it the pool
+ *  cannot cool a limited seat on this path, so selection hands the same
+ *  rate-limited account back on every following request. */
+onDecline, 
+/** When true a decline returns false WITHOUT writing, so the caller can
+ *  retry the request on a healthy peer. False keeps the old behaviour: the
+ *  upstream error is written through as the backend sent it. */
+deferOnUnavailable = false) {
     const startedAt = Date.now();
     const model = String(body.model ?? '');
     let reported = false;
@@ -804,6 +813,23 @@ export async function forwardResponsesToCodex(res, body, creds, corsOrigin, secu
             const detail = await upstream.text().catch(() => '');
             if (verbose)
                 console.error(`[dario] codex backend ${upstream.status}: ${detail.slice(0, 300)}`);
+            // Same rule as the Messages path: a 429 or a 5xx is the seat declining,
+            // and that is true whether or not anything is waiting to take over.
+            const unavailable = upstream.status === 429 || upstream.status >= 500;
+            if (unavailable) {
+                try {
+                    onDecline?.({ status: upstream.status, retryAfterMs: parseRetryAfterMs(upstream.headers.get('retry-after')), alias: creds.alias });
+                }
+                catch { /* a reporting failure must never break a request */ }
+            }
+            if (deferOnUnavailable && unavailable) {
+                if (verbose)
+                    console.log(`[dario] codex account ${creds.alias} unavailable (${upstream.status}) — deferring`);
+                // Nothing written, so the caller is free to retry this same request
+                // on a peer. Reporting nothing here matches forwardToCodex: a
+                // declined attempt is not a served request.
+                return false;
+            }
             if (!clientGone) {
                 res.writeHead(upstream.status, { 'Content-Type': 'application/json', ...securityHeaders });
                 // The backend's own error body, already in the client's shape.
@@ -1048,16 +1074,25 @@ midstream) {
             // own fault (a bad body, an unsupported parameter) is NOT: failing over
             // would just reproduce it somewhere else and hide the real error.
             const unavailable = upstream.status === 429 || upstream.status >= 500;
+            // The seat said no, and that is true whether or not a fallback exists
+            // to defer to. Recording it outside the defer branch is what lets the
+            // POOL rotate on a deployment with no --pool-fallback configured: with
+            // the notice inside the branch, a 429 went straight to the client and
+            // the seat was never cooled, so selection returned the same limited
+            // account forever (found writing the proxy-level test for #1288).
+            if (unavailable) {
+                try {
+                    onDecline?.({ status: upstream.status, retryAfterMs: parseRetryAfterMs(upstream.headers.get('retry-after')), alias: creds.alias });
+                }
+                catch { /* a reporting failure must never break a request */ }
+            }
             if (deferOnUnavailable && unavailable) {
                 console.log(`[dario] codex account ${creds.alias} unavailable (${upstream.status}) — deferring to the next provider`);
                 // A decline is the only exit that tells the caller nothing was served,
                 // and until now it carried no WHY: a 429 and a 503 were the same false.
                 // The chain needs the status (to cool a rate limit but not an outage)
                 // and the upstream's own `retry-after` (to cool it for the right long).
-                try {
-                    onDecline?.({ status: upstream.status, retryAfterMs: parseRetryAfterMs(upstream.headers.get('retry-after')) });
-                }
-                catch { /* a reporting failure must never break a declined request */ }
+                // (the decline was already recorded above, for both exits)
                 return false;
             }
             res.writeHead(upstream.status, { 'Content-Type': 'application/json', ...securityHeaders });
@@ -1251,7 +1286,7 @@ midstream) {
             // status 0: no HTTP status ever arrived. Reported so the caller can tell
             // an outage from a rate limit — an unreachable backend is not quota.
             try {
-                onDecline?.({ status: 0, retryAfterMs: null });
+                onDecline?.({ status: 0, retryAfterMs: null, alias: creds.alias });
             }
             catch { /* as above */ }
             return false;

package/dist/ledger.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The ledger — what the traffic dario has served would have cost on the
+ * metered API, kept across restarts.
+ *
+ * /analytics is a rolling in-memory window: it forgets on every restart and
+ * caps at 10k records, so the one number a subscription user actually wants
+ * — "what has this saved me" — was never answerable past the last few hours.
+ * The ledger keeps one small row per (UTC day, model, bucket): a request
+ * count and the four token buckets. It never stores a price. Rows are priced
+ * at read time through `costOfTokens` at the day's own timestamp, so a
+ * pricing correction (#1047, #1048 — both happened) reprices history instead
+ * of freezing the wrong number in.
+ *
+ * Two buckets per row. `covered` is traffic a subscription paid for — the
+ * API-equivalent cost of that is the headline, the invoice that never
+ * arrived. `metered` is traffic billed per token anyway (an API key, or
+ * Anthropic's paid `extra_usage` overage) — that money was spent, and it is
+ * reported separately rather than counted as saved. Only 2xx responses
+ * count: a 429 carries no tokens and a 5xx bills nothing.
+ *
+ * On disk: `~/.dario/ledger.json` for the default port, `ledger-<port>.json`
+ * for any other, so two instances sharing a home (the box's live-test rig
+ * runs one on :3999 next to production) do not overwrite each other's file.
+ * Writes are debounced and durable (`durableWriteFile`); the shutdown hook
+ * flushes what the debounce still holds, so at most the last few seconds
+ * before a SIGKILL are lost.
+ */
+import { type PricingProvider, type RequestRecord } from './analytics.js';
+export declare const LEDGER_VERSION = 1;
+/** Days kept before the oldest roll off — two years at one row per model per day. */
+export declare const LEDGER_MAX_DAYS = 730;
+/** How long after the last record the file is rewritten. */
+export declare const LEDGER_FLUSH_DELAY_MS = 3000;
+export type LedgerBucket = 'covered' | 'metered';
+export interface LedgerCell {
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreateTokens: number;
+}
+export type LedgerRow = Partial<Record<LedgerBucket, LedgerCell>>;
+export interface LedgerFile {
+    version: number;
+    /** ISO timestamp of the first record the ledger ever saw. */
+    since: string;
+    /** ISO timestamp of the last write. */
+    updated: string;
+    /** `YYYY-MM-DD` (UTC) → model id → per-bucket totals. */
+    days: Record<string, Record<string, LedgerRow>>;
+}
+export interface LedgerModelSummary {
+    provider: PricingProvider;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreateTokens: number;
+    /** API-equivalent cost of this model's covered traffic, USD. */
+    apiEquivalentCost: number;
+    /** What this model's metered traffic cost at list price, USD. */
+    meteredCost: number;
+}
+export interface LedgerSummary {
+    /** Where the file lives — so `dario usage` can say what it read. */
+    path: string;
+    since: string;
+    /** Distinct UTC days with traffic. */
+    days: number;
+    /** Covered + metered, 2xx only. */
+    requests: number;
+    /**
+     * The headline: what subscription-covered traffic would have been billed
+     * on the metered API at today's list prices, USD.
+     */
+    apiEquivalentCost: number;
+    /** What metered traffic (API key, paid overage) actually cost at list price, USD. */
+    meteredCost: number;
+    /** Covered token totals. */
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheCreate: number;
+    };
+    perProvider: Record<PricingProvider, {
+        requests: number;
+        apiEquivalentCost: number;
+    }>;
+    perModel: Record<string, LedgerModelSummary>;
+    /** apiEquivalentCost over the trailing windows, UTC days. */
+    recent: {
+        today: number;
+        last7d: number;
+        last30d: number;
+    };
+}
+export declare function ledgerPathFor(port: number, home?: string): string;
+/**
+ * `DARIO_LEDGER_PATH` names the file; `DARIO_LEDGER=0` (or `--no-ledger`)
+ * turns the ledger off. Off, /analytics reports `lifetime: null` and the
+ * usage command says so.
+ */
+export declare function resolveLedgerPath(port: number, env?: NodeJS.ProcessEnv): string;
+export declare function ledgerDisabledByEnv(env?: NodeJS.ProcessEnv): boolean;
+export declare function emptyLedger(now?: number): LedgerFile;
+/** UTC calendar day of an epoch-ms timestamp. */
+export declare function dayKey(atMs: number): string;
+/**
+ * Which bucket a record lands in, or null when it should not be counted.
+ * `api` and `extra_usage` are metered; every subscription claim, the codex
+ * claim, and an absent claim on a 2xx (stream aborts, api-key mode without
+ * the header) are covered — the request was served, and nothing says it was
+ * billed per token.
+ */
+export declare function ledgerBucketFor(record: Pick<RequestRecord, 'status' | 'claim'>): LedgerBucket | null;
+/**
+ * Parse a ledger file's text, keeping only well-formed rows. A file that is
+ * not a ledger at all throws; the caller moves it aside and starts fresh.
+ */
+export declare function parseLedger(text: string): LedgerFile;
+/** Add one record's tokens to the file in place. Returns false when it was not counted. */
+export declare function addToLedger(file: LedgerFile, record: RequestRecord): boolean;
+/** Drop the oldest days past LEDGER_MAX_DAYS. */
+export declare function pruneLedger(file: LedgerFile, maxDays?: number): void;
+export declare function summarizeLedger(file: LedgerFile, path: string, now?: number): LedgerSummary;
+/**
+ * Read a ledger file for display without a running proxy (`dario usage`
+ * when the proxy is down). Missing file → null; unreadable → null with the
+ * reason, never a throw.
+ */
+export declare function readLedgerFile(path: string): Promise<{
+    file: LedgerFile | null;
+    error?: string;
+}>;
+export declare class Ledger {
+    readonly path: string;
+    private readonly log;
+    private file;
+    private dirty;
+    private timer;
+    private writing;
+    private closed;
+    private constructor();
+    /**
+     * Load the ledger at `path`, or start one. A file that cannot be parsed is
+     * moved aside (`<path>.corrupt-<ts>`) rather than overwritten, so a bad
+     * write never silently zeroes two years of history.
+     */
+    static open(path: string, log?: (line: string) => void): Promise<Ledger>;
+    /** Count a request. Returns false when it was not ledger material. */
+    add(record: RequestRecord): boolean;
+    summary(now?: number): LedgerSummary;
+    /** The raw per-day table, for /analytics/ledger. */
+    snapshot(): LedgerFile;
+    private scheduleFlush;
+    /** Write now if anything changed. Serialized; a failure is logged, not thrown. */
+    flush(): Promise<void>;
+    /** Final flush for the shutdown hook. */
+    close(): Promise<void>;
+}
+export declare function formatUsd(usd: number): string;
+/** `claude-opus-5` → `Opus 5`, `claude-haiku-4-5-20251001` → `Haiku 4.5`, `gpt-5.6-terra` → `gpt-5.6-terra`. */
+export declare function shortModelName(model: string): string;
+/**
+ * The block `dario usage` prints above the rolling window. Two-space indent
+ * to match the rest of that command's output.
+ */
+export declare function formatLedgerSummary(s: LedgerSummary): string[];
+/**
+ * A share card: one SVG, 640×320, dark, the number in the middle. Plain
+ * system monospace so it renders the same in a README, a tweet screenshot
+ * and an <img> tag with nothing to fetch.
+ */
+export declare function renderLedgerCard(s: LedgerSummary): string;