@askalf/dario 6.9.3 → 6.10.1

package/dist/proxy.js

@@ -9,18 +9,18 @@ import { getAccessToken, getStatus, ignoreCcCredentials } from './oauth.js';
 import { buildHealthResponse, derivePoolStatus, probeRequested, shouldDiscloseHealthInternals, shouldRunServingProbe } from './health-response.js';
 import { getServingProbe } from './serving-probe.js';
 import { darioVersion } from './version.js';
-import { CC_TOOL_DEFINITIONS_UNADVERTISABLE, buildCCRequest, applyCcPromptCaching, isGenuineCCClient, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, overlayTemplateHeaderValues, forwardClientCCIdentityHeaders, isMcpToolName, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
+import { CC_TOOL_DEFINITIONS_UNADVERTISABLE, CC_TEMPLATE_PROMPT_BYTES, resolveMaxTokens, buildCCRequest, applyCcPromptCaching, isGenuineCCClient, parseEffortSuffix, reverseMapResponse, createStreamingReverseMapper, orderHeadersForOutbound, overlayTemplateHeaderValues, forwardClientCCIdentityHeaders, isMcpToolName, CC_TEMPLATE, effectiveCacheControl, withForced1hBeta } from './cc-template.js';
 import { stampCch, hasCchSeed } from './cch.js';
 import { foldTiming, timingHeaders, timingLogFields } from './timing.js';
 import { describeTemplate, detectDrift, checkCCCompat, probeInstalledCCVersion } from './live-fingerprint.js';
-import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reportedAccountStatus, reconcilePoolAccounts, resolvePoolStrategy, resolvePoolHeadroomFloor, DEFAULT_POOL_HEADROOM_FLOOR, utilFreshness, rateLimitWindow, accountAction, accountPeers, distinctAccounts, describeRejection, maskEmail, isAccountEligible } from './pool.js';
+import { AccountPool, computeStickyKey, parseRateLimits, modelFamily, isInAuthCooldown, authCooldownMs, accountIneligibility, reportedAccountStatus, activeParkedBuckets, reconcilePoolAccounts, resolvePoolStrategy, resolvePoolHeadroomFloor, DEFAULT_POOL_HEADROOM_FLOOR, utilFreshness, rateLimitWindow, accountAction, accountPeers, distinctAccounts, describeRejection, maskEmail, isAccountEligible } from './pool.js';
 import { backfillIdentity } from './accounts.js';
 import { PoolSync, DEFAULT_POOL_SYNC_INTERVAL_MS } from './pool-sync.js';
-import { Analytics, billingBucketFromClaim, formatUsageLogLine, SUBSCRIPTION_CLAIMS, consumerFromHeader, consumerFromBody, CONSUMER_HEADER, CODEX_CLAIM } from './analytics.js';
+import { Analytics, billingBucketFromClaim, costOfTokens, formatUsageLogLine, SUBSCRIPTION_CLAIMS, consumerFromHeader, consumerFromBody, CONSUMER_HEADER, CODEX_CLAIM } from './analytics.js';
 import { Ledger, resolveLedgerPath, ledgerDisabledByEnv } from './ledger.js';
 import { renderPrometheus } from './metrics.js';
 import { renderSpendDonuts, renderAnalyticsView, ANALYTICS_UI_SHELL } from './donuts.js';
-import { KeyStore, keyAllowsModel, resolveKeysPath, looksLikeNamedKey } from './keys.js';
+import { KeyStore, keyAllowsModel, resolveKeysPath, looksLikeNamedKey, budgetVerdict, budgetHeaders, requestBudgetReservation, addReservation, subtractReservation, EMPTY_RESERVATION } from './keys.js';
 import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
 import { notify as osNotify } from './notify.js';
 import { grantAge, grantThresholds, worstGrantLevel, describeGrantAge } from './refresh-grant.js';
@@ -2032,6 +2032,38 @@ export async function startProxy(opts = {}) {
         else if (keyStore.size() > 0)
             console.log(`[dario] keys: ${keyStore.size()} named key${keyStore.size() === 1 ? '' : 's'} from ${keyStore.path}`);
     }
+    /**
+     * Per-key daily budgets (dario#1318 follow-up) read the ledger's per-consumer
+     * rows; with the ledger off there is nothing to read, so a budget cannot be
+     * enforced. Say so once at startup rather than silently letting traffic through.
+     */
+    if (keyStore && !ledger) {
+        const budgeted = keyStore.list().filter((k) => k.budget !== null).map((k) => k.name);
+        if (budgeted.length > 0)
+            console.error(`[dario] keys: budgets on ${budgeted.join(', ')} are NOT enforced — the ledger is off (--no-ledger / DARIO_LEDGER=0) and budgets are read from it`);
+    }
+    /**
+     * What is reserved for the requests admitted under a key's budget and not
+     * yet completed, per key: each at an upper bound on its cost (keys.ts
+     * requestBudgetReservation), so a burst can never complete for more than
+     * the cap plus one request (review of #1378). Released in the handler's
+     * finally on every exit.
+     */
+    const keyInflight = new Map();
+    /** Every budgeted key with today's use, for /analytics and /metrics. Empty when keys or the ledger are off. */
+    const keyBudgetsSnapshot = () => {
+        const out = {};
+        if (!keyStore || !ledger)
+            return out;
+        keyStore.load();
+        for (const k of keyStore.list()) {
+            if (!k.budget)
+                continue;
+            const used = ledger.consumerToday(k.name);
+            out[k.name] = { usdPerDay: k.budget.usd_per_day, tokensPerDay: k.budget.tokens_per_day, usedUsd: used.usd, usedTokens: used.tokens };
+        }
+        return out;
+    };
     // Admin API (#599) — opt-in headless account management at /admin/*. Off
     // unless DARIO_ADMIN=1. Auth is ALWAYS required (even on loopback) because
     // these endpoints add/remove OAuth accounts: the admin token is
@@ -2518,6 +2550,7 @@ export async function startProxy(opts = {}) {
                             requestCount: a.requestCount,
                             rejectedCount: a.rejectedCount,
                             lastRejectedAt: a.lastRejectedAt ?? null,
+                            parkedBuckets: activeParkedBuckets(a.rateLimit, snapNow),
                             organizationId: a.organizationId ?? null,
                             sharesWindowWith: peers.get(a.alias) ?? [],
                             sameAccountAs: peers.get(a.alias) ?? [],
@@ -2653,6 +2686,10 @@ export async function startProxy(opts = {}) {
                     // parked seat no longer reads as one that was never called.
                     rejectedCount: a.rejectedCount,
                     lastRejectedAt: a.lastRejectedAt ?? null,
+                    // Per-model buckets keeping their families off this seat while the
+                    // seat itself still serves (`7d_oi` → fable on a Pro seat whose
+                    // included overage is spent). Empty when nothing is parked that way.
+                    parkedBuckets: activeParkedBuckets(a.rateLimit, now),
                     // Which organization the token belongs to, who the token IS (OAuth
                     // account uuid, masked email), and which other seats are the same
                     // account — one subscription under several aliases (dario#1244,
@@ -2737,13 +2774,14 @@ export async function startProxy(opts = {}) {
             // `queue` rides along the summary (dario#905): request-queue.ts always
             // documented snapshot() as "exposed for /analytics", but it was never
             // actually wired in, so slot exhaustion was invisible from outside.
-            res.end(JSON.stringify({ ...analytics.summary(), queue: queue.snapshot(), lifetime: ledger ? ledger.summary() : null }));
+            res.end(JSON.stringify({ ...analytics.summary(), queue: queue.snapshot(), lifetime: ledger ? ledger.summary() : null, budgets: keyBudgetsSnapshot() }));
             return;
         }
         // Prometheus text exposition of the same state (dario#1341). A view, not
         // new collection: a scrape costs what GET /analytics costs. Same gate.
         if (urlPath === '/metrics' && req.method === 'GET') {
             const body = renderPrometheus({
+                budgets: keyBudgetsSnapshot(),
                 summary: analytics.summary(),
                 queue: queue.snapshot(),
                 lifetime: ledger ? ledger.summary() : null,
@@ -3004,6 +3042,11 @@ export async function startProxy(opts = {}) {
         // "overhead" never has to be guessed at (src/timing.ts).
         let queueMs = 0;
         let pacingMs = 0;
+        // The key this request was admitted under with a budget and what was
+        // reserved for it, for the release in the finally below; null when no
+        // budget applied.
+        let budgetInflightKey = null;
+        let budgetReserved = EMPTY_RESERVATION;
         const releaseQueueSlot = () => {
             if (!queueSlotHeld)
                 return;
@@ -3058,6 +3101,11 @@ export async function startProxy(opts = {}) {
         // before that point they remain at their initial values, which is
         // also exactly what we want to log on early-failure paths.
         let requestModel = '';
+        // The Claude family the pool is asked to serve, known once the body's
+        // model is read (before `selectPoolAccount()` runs): a seat parked on a
+        // per-model bucket is off for that family only, so selection, the key's
+        // preferred seat and the all-parked answer all ask with it.
+        let requestFamily = null;
         let detectedClientForLog;
         let preserveToolsEffective = Boolean(opts.preserveTools);
         // Per-request: did isGenuineCCClient recognise the caller as real Claude
@@ -3247,15 +3295,15 @@ export async function startProxy(opts = {}) {
                 // eligible right now, else the pool picks as usual. Failover
                 // mid-request is unchanged either way — a preference, not a pin.
                 const preferredSeat = requestAuth.key?.seat ? (pool.get(requestAuth.key.seat) ?? null) : null;
-                keySeatTaken = preferredSeat !== null && isAccountEligible(preferredSeat, Date.now());
-                poolAccount = keySeatTaken ? preferredSeat : pool.select();
+                keySeatTaken = preferredSeat !== null && isAccountEligible(preferredSeat, Date.now(), requestFamily);
+                poolAccount = keySeatTaken ? preferredSeat : pool.select(requestFamily);
                 if (poolAccount)
                     poolParkedAnnounced = false;
                 // Every seat parked inside a live window (dario#1244): cool the
                 // provider to the earliest reset so a fallback chain sees the Claude
                 // half as what it is, say so once, and — unless a fallback is armed —
                 // answer the client here instead of spending a probe that can only 429.
-                const parkedUntil = poolAccount ? null : pool.parkedUntil();
+                const parkedUntil = poolAccount ? null : pool.parkedUntil(Date.now(), requestFamily);
                 if (parkedUntil !== null) {
                     providerCooldowns.note('claude', parkedUntil - Date.now());
                     if (!poolParkedAnnounced) {
@@ -3473,6 +3521,55 @@ export async function startProxy(opts = {}) {
                     return;
                 }
             }
+            // A named key's daily budget (dario#1318 follow-up): what the ledger has
+            // counted for this key today against its caps, refused here in the
+            // request's own wire shape before anything goes upstream. Checked at
+            // request START against completed rows PLUS what is reserved for the
+            // key's requests still in flight — each at an upper bound on its cost
+            // (keys.ts requestBudgetReservation) until the ledger has the real number
+            // — so a burst can complete for at most the cap plus one request.
+            // `retry-after` is the UTC day boundary. Served responses carry the same
+            // x-dario-budget-* headers so a client can watch its own headroom.
+            let keyBudgetHeaders = {};
+            if (requestAuth.key?.budget && ledger) {
+                const inflightNow = keyInflight.get(requestAuth.key.name) ?? EMPTY_RESERVATION;
+                const verdict = budgetVerdict(requestAuth.key.budget, ledger.consumerToday(requestAuth.key.name), Date.now(), inflightNow);
+                keyBudgetHeaders = budgetHeaders(verdict, requestAuth.key.name);
+                if (!verdict.over) {
+                    // Held at its upper bound until the response is in and the ledger has
+                    // it — bounded by what dario will SEND: the client's body plus the
+                    // template's prompt (passthrough adds nothing), and the max_tokens
+                    // that will go on the wire (the template pins its own default unless
+                    // --max-tokens=client; passthrough forwards the client's).
+                    const pb = parsedBody;
+                    const clientMax = pb ? (pb.max_tokens ?? pb.max_completion_tokens ?? pb.max_output_tokens) : undefined;
+                    const outboundMax = passthrough
+                        ? (typeof clientMax === 'number' ? clientMax : null)
+                        : resolveMaxTokens(opts.maxTokens, { max_tokens: clientMax });
+                    budgetReserved = requestBudgetReservation(typeof pb?.model === 'string' ? pb.model : '', body.length, outboundMax, costOfTokens, Date.now(), passthrough ? 0 : CC_TEMPLATE_PROMPT_BYTES);
+                    budgetInflightKey = requestAuth.key.name;
+                    keyInflight.set(budgetInflightKey, addReservation(inflightNow, budgetReserved));
+                }
+                if (verdict.over) {
+                    requestCount++;
+                    writeLogLine(logFileStream, {
+                        ts: new Date().toISOString(), req: requestCount,
+                        method: req.method ?? '', path: urlPath, status: 429, reject: `key-budget-${verdict.reason}`, consumer: requestAuth.key.name,
+                    });
+                    const inflightNote = verdict.inflight.count > 0
+                        ? (verdict.reason === 'usd' ? ` + $${verdict.inflight.usd.toFixed(2)} reserved for ${verdict.inflight.count} in flight` : ` + ${verdict.inflight.tokens} reserved for ${verdict.inflight.count} in flight`)
+                        : '';
+                    const cap = verdict.reason === 'usd'
+                        ? `$${verdict.budget.usdPerDay} API-equivalent per day (used $${verdict.usage.usd.toFixed(2)}${inflightNote})`
+                        : `${verdict.budget.tokensPerDay} tokens per day (used ${verdict.usage.tokens}${inflightNote})`;
+                    const msg = `key "${requestAuth.key.name}" is over its daily budget of ${cap}; resets at ${new Date(verdict.resetAt).toISOString()} (UTC midnight)`;
+                    res.writeHead(429, { ...JSON_HEADERS, 'Access-Control-Allow-Origin': corsOrigin, 'retry-after': String(verdict.retryAfterSec), ...keyBudgetHeaders });
+                    res.end(JSON.stringify(isOpenAI
+                        ? { error: { message: msg, type: 'rate_limit_error', param: null, code: 'key_budget_exceeded' } }
+                        : { type: 'error', error: { type: 'rate_limit_error', message: msg } }));
+                    return;
+                }
+            }
             // Responses shape → Messages shape, once, before any routing peeks at
             // the body. The translated body is what a continuation re-issues too:
             // the loopback goes to /v1/messages, which is what this body now is.
@@ -3684,6 +3781,7 @@ export async function startProxy(opts = {}) {
                     // Reassignable: the codex effort-suffix strip below rewrites it, and
                     // every routing decision after that point must see the stripped name.
                     let rawModel = (peek.model || '').toString();
+                    requestFamily = modelFamily(rawModel);
                     // Credentials are re-read per request (not cached at startup) because
                     // a refresh rotates them on disk; getFreshCodexAccount refreshes when
                     // inside the expiry buffer, collapsing concurrent refreshes per alias.
@@ -4130,7 +4228,7 @@ export async function startProxy(opts = {}) {
             if (!upstreamApiKey && !poolAccount) {
                 // A fallback was armed but nothing could serve, and the pool itself is
                 // parked: the exact reset beats a cool-down estimate (dario#1244).
-                const parkedNow = pool.parkedUntil();
+                const parkedNow = pool.parkedUntil(Date.now(), requestFamily);
                 if (parkedNow !== null) {
                     writePoolParked(parkedNow);
                     return;
@@ -5230,6 +5328,7 @@ export async function startProxy(opts = {}) {
                     console.log(`[dario] #${requestCount} billing: headers absent (status=${upstream.status})`);
                 }
             }
+            Object.assign(responseHeaders, keyBudgetHeaders);
             Object.assign(responseHeaders, timingHeaders({
                 queueMs, pacingMs, arrivedAt,
                 fetchStartedAt: fetchStartedAt ?? Date.now(),
@@ -5603,6 +5702,13 @@ export async function startProxy(opts = {}) {
             if (onClientClose !== null)
                 req.off('close', onClientClose);
             releaseQueueSlot();
+            if (budgetInflightKey !== null) {
+                const left = subtractReservation(keyInflight.get(budgetInflightKey) ?? budgetReserved, budgetReserved);
+                if (left.count > 0)
+                    keyInflight.set(budgetInflightKey, left);
+                else
+                    keyInflight.delete(budgetInflightKey);
+            }
         }
     });
     server.on('error', async (err) => {

package/docs/keys.md

@@ -32,12 +32,57 @@ on its next request, no restart.
 | `--seat=<alias>` | The pool seat this key's traffic prefers. Taken whenever that seat is eligible right now; when it is parked on a 429, cooling down after an auth failure, or missing, the request routes like any other. A preference, not a pin: in-flight failover is unchanged, and the sticky binding follows the key so a conversation stays on the developer's own subscription. |
 | `--models=a,b,prefix*` | An allowlist. A request for any other model is refused with `403` — in the request's own wire shape, before anything goes upstream. Entries are exact ids or `prefix*`, case-insensitive. |
 | `--expires=30d` | Refused after this, like a revoked key. `12h`, `2w`, or an ISO date. |
+| `--budget=$5/day` | A daily cap on the API-equivalent price of the key's traffic. See **Budgets**. |
+| `--budget-tokens=2M/day` | A daily cap on tokens, every bucket counted. See **Budgets**. |
 
 `dario keys revoke <name>` refuses a key from now on and keeps it in the list;
 `dario keys rotate <name>` prints a new secret under the same name, seat,
 models and expiry, and the old secret stops at once; `dario keys remove
 <name>` forgets it.
 
+## Budgets
+
+`dario keys create alice --budget=$5/day --budget-tokens=2M/day` — or
+`dario keys budget alice --budget=$5/day` on an existing key, `--clear` to
+remove it — caps what a key may use **per UTC day**:
+
+- **`--budget=$5/day`**: the API-equivalent price of the key's traffic, the
+  same number `dario usage --by-key` prints — covered and metered rows both
+  count, because a budget is about what the key caused, not who paid.
+- **`--budget-tokens=2M/day`** (`250k`, `2000000`): every token the key sent
+  or received, cache reads included.
+
+The check runs at request **start** against the ledger's completed rows plus
+what is **reserved** for the key's requests still in flight. A request is
+reserved at an upper bound on what it can cost, from what dario will *send*:
+the client's body plus the template's own system prompt and tool definitions,
+at 3 bytes per token priced as cache-create (the highest input-side rate, so
+any mix of input, cache-read and cache-create tokens — all prompt tokens —
+costs no more), plus the `max_tokens` that will go on the wire (the template's
+default, 64,000, unless `--max-tokens=client`; passthrough forwards the
+client's; 8,192 when nothing is set) at the output rate — until its response is
+in and the ledger has the real number. So the most a key can complete in a day
+is the cap plus one request, whatever the size of a burst or of the requests
+in it. The reservation is deliberately pessimistic: on a $5/day key in template
+mode it admits roughly four requests at once until the first completes and its
+real cost replaces the reservation. `--max-tokens=client` shrinks it. A request past the cap is refused
+with `429`
+in the request's own wire shape (`rate_limit_error`; OpenAI shape adds
+`code: "key_budget_exceeded"`), a `retry-after` at the UTC day boundary, and
+`reject: "key-budget-usd"` / `"key-budget-tokens"` on the log line. Served
+responses carry the same `x-dario-budget-*` headers (`-key`, `-usd`,
+`-used-usd`, `-tokens`, `-used-tokens`, `-inflight`, `-resets-at`) so a client can watch
+its own headroom. `GET /analytics` lists every budgeted key under `budgets`
+with today's use; `GET /metrics` exports `dario_key_budget_usd_per_day`,
+`_used_usd`, `_tokens_per_day`, `_used_tokens` per key.
+
+Budgets are **read from the ledger**. With the ledger off (`--no-ledger`,
+`DARIO_LEDGER=0`) there is nothing to read; the proxy says so at startup
+(`budgets on alice are NOT enforced`) and the key is served as if it had none.
+Over HTTP: `budget_usd_per_day` / `budget_tokens_per_day` on
+`POST /admin/keys`, and `POST /admin/keys/<name>/budget` with the same
+fields (an empty body clears), audited as `key_budget`.
+
 ## Where it shows
 
 - **`GET /analytics`** — `perConsumer` (the rolling window) and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.9.3",
+  "version": "6.10.1",
   "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, with automatic failover when one hits its limit.",
   "type": "module",
   "bin": {
@@ -87,7 +87,7 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.1",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   }