@askalf/dario 6.9.2 → 6.10.0

package/README.md

@@ -382,7 +382,7 @@ dario keys create alice
 dario keys create bob --seat=bobs-max --models=claude-sonnet-5,claude-haiku*
 ```
 
-The secret is printed once and only its hash is kept, in `~/.dario/keys.json`. The request authenticated with alice's key *is* alice's in `/analytics`, in the ledger (`dario usage --by-key`) and on every log line; a key can prefer one pool seat (taken while it has headroom, normal routing otherwise, so a developer's conversations ride their own subscription) and can be held to a model allowlist (`403` before anything goes upstream, in either wire shape). The running proxy picks up a created, rotated or revoked key on its next request; the root `DARIO_API_KEY` keeps working beside them; `/admin/keys` does the same over HTTP. Details: [keys.md](./docs/keys.md).
+Since 6.10 a key can carry a **daily budget** — `--budget=$5/day`, `--budget-tokens=2M/day` — read from the ledger, refused with a `429` and a `retry-after` at UTC midnight, with the headroom on every response as `x-dario-budget-*` headers ([details](./docs/keys.md#budgets)). The secret is printed once and only its hash is kept, in `~/.dario/keys.json`. The request authenticated with alice's key *is* alice's in `/analytics`, in the ledger (`dario usage --by-key`) and on every log line; a key can prefer one pool seat (taken while it has headroom, normal routing otherwise, so a developer's conversations ride their own subscription) and can be held to a model allowlist (`403` before anything goes upstream, in either wire shape). The running proxy picks up a created, rotated or revoked key on its next request; the root `DARIO_API_KEY` keeps working beside them; `/admin/keys` does the same over HTTP. Details: [keys.md](./docs/keys.md).
 
 ### Watch it happen
 

package/dist/admin-api.d.ts

@@ -158,7 +158,7 @@ export interface AdminCodexAccountRecord extends CodexSeatState {
     needsRefresh: boolean;
 }
 export interface AdminAuditEvent {
-    action: 'login_start' | 'login_complete' | 'account_remove' | 'auth_reject' | 'rate_limited' | 'key_create' | 'key_revoke' | 'key_rotate';
+    action: 'login_start' | 'login_complete' | 'account_remove' | 'auth_reject' | 'rate_limited' | 'key_create' | 'key_revoke' | 'key_rotate' | 'key_budget';
     /** Which engine's credentials the event touched; absent means Claude, the only engine before codex joined (dario#1009). */
     engine?: 'codex';
     ok: boolean;

package/dist/admin-api.js

@@ -4,7 +4,27 @@ import { startAddAccount, completeAddAccount, removeAccount, listAccountAliases,
 import { startAddCodexAccount, completeAddCodexAccount, removeCodexAccount, loadAllCodexAccounts, listCodexAccountAliases, codexAccountNeedsRefresh, codexSeatStatus, parseCodexManualPaste, } from './codex-accounts.js';
 import { parseManualPaste } from './oauth.js';
 import { grantAge } from './refresh-grant.js';
-import { createKey, revokeKey, rotateKey, parseExpiry, publicKey, KEY_NAME_RE } from './keys.js';
+import { createKey, revokeKey, rotateKey, parseExpiry, publicKey, setKeyBudget, normalizeBudget, KEY_NAME_RE } from './keys.js';
+/**
+ * `{ budget_usd_per_day, budget_tokens_per_day }` (numbers, or numeric strings)
+ * → a KeyBudget; undefined when neither is present; throws with a 400-worthy
+ * message when one is present and not a positive number.
+ */
+function budgetFromBody(body) {
+    const num = (v, field) => {
+        if (v === undefined || v === null || v === '')
+            return undefined;
+        const n = typeof v === 'number' ? v : typeof v === 'string' ? Number(v.replace(/^\$/, '')) : NaN;
+        if (!Number.isFinite(n) || n <= 0)
+            throw new Error(`invalid "${field}": a positive number`);
+        return n;
+    };
+    const usdPerDay = num(body.budget_usd_per_day, 'budget_usd_per_day');
+    const tokensPerDay = num(body.budget_tokens_per_day, 'budget_tokens_per_day');
+    if (usdPerDay === undefined && tokensPerDay === undefined)
+        return undefined;
+    return normalizeBudget({ usdPerDay, tokensPerDay });
+}
 const PENDING_TTL_MS = 10 * 60_000;
 const MAX_PENDING = 64; // backstop against unbounded growth (distinct aliases)
 const ACCOUNTS_PREFIX = '/admin/accounts/';
@@ -244,8 +264,10 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
         ? decodeURIComponent(urlPath.slice(KEYS_PREFIX.length))
         : null;
     const isKeyRotate = keyTarget !== null && keyTarget.endsWith('/rotate');
-    const keyName = keyTarget === null ? null : isKeyRotate ? keyTarget.slice(0, -'/rotate'.length) : keyTarget;
-    const isKeyRevoke = keyTarget !== null && !isKeyRotate && method === 'DELETE';
+    // POST /admin/keys/<name>/budget — set or clear a key's daily caps (dario#1318 follow-up).
+    const isKeyBudget = keyTarget !== null && keyTarget.endsWith('/budget');
+    const keyName = keyTarget === null ? null : isKeyRotate ? keyTarget.slice(0, -'/rotate'.length) : isKeyBudget ? keyTarget.slice(0, -'/budget'.length) : keyTarget;
+    const isKeyRevoke = keyTarget !== null && !isKeyRotate && !isKeyBudget && method === 'DELETE';
     const known = urlPath === '/admin/login/start' ||
         urlPath === '/admin/login/start-needed' ||
         urlPath === '/admin/login/complete' ||
@@ -257,6 +279,7 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
         isCodexAccountDelete ||
         isAccountDelete ||
         isKeyRotate ||
+        isKeyBudget ||
         isKeyRevoke;
     if (!known)
         return false;
@@ -289,7 +312,7 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
     // accounts' credentials for the price of one throttle token.
     const isMutation = urlPath === '/admin/login/start' || isAccountDelete
         || urlPath === '/admin/codex/login/start' || isCodexAccountDelete
-        || (urlPath === '/admin/keys' && method === 'POST') || isKeyRotate || isKeyRevoke;
+        || (urlPath === '/admin/keys' && method === 'POST') || isKeyRotate || isKeyBudget || isKeyRevoke;
     if (isMutation) {
         const wait = deps.rateLimit?.('mutation') ?? 0;
         if (wait > 0) {
@@ -609,8 +632,16 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
                     }
                     expiresAt = parsed;
                 }
+                let budget;
+                try {
+                    budget = budgetFromBody(body);
+                }
+                catch (err) {
+                    send(res, 400, { error: err.message });
+                    return true;
+                }
                 try {
-                    const made = store.mutate((file) => createKey(file, name, { seat, models, expiresAt, now }));
+                    const made = store.mutate((file) => createKey(file, name, { seat, models, expiresAt, budget, now }));
                     deps.audit?.({ action: 'key_create', ok: true, status: 201, key: made.record.name, remote, detail: seat ? `seat=${seat}` : undefined });
                     send(res, 201, { key: publicKey(made.record, now), secret: made.secret, note: 'the secret is shown once and is not stored' });
                 }
@@ -645,6 +676,30 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
                 send(res, 200, { key: publicKey(rotated.record, now), secret: rotated.secret, note: 'the secret is shown once and is not stored' });
                 return true;
             }
+            // POST /admin/keys/<name>/budget  { budget_usd_per_day?, budget_tokens_per_day? } — both absent/null clears.
+            if (isKeyBudget) {
+                if (method !== 'POST') {
+                    send(res, 405, { error: 'Method not allowed (use POST)' });
+                    return true;
+                }
+                const body = await readJsonBody(req);
+                let budget;
+                try {
+                    budget = budgetFromBody(body);
+                }
+                catch (err) {
+                    send(res, 400, { error: err.message });
+                    return true;
+                }
+                const updated = store.mutate((file) => setKeyBudget(file, keyName, budget ?? null));
+                deps.audit?.({ action: 'key_budget', ok: updated !== null, status: updated ? 200 : 404, key: keyName, remote, detail: budget ? JSON.stringify(budget) : 'cleared' });
+                if (!updated) {
+                    send(res, 404, { error: `no key named "${keyName}"` });
+                    return true;
+                }
+                send(res, 200, { key: publicKey(updated, now) });
+                return true;
+            }
             // DELETE /admin/keys/<name> — revoked, kept for the list.
             if (isKeyRevoke) {
                 const revoked = store.mutate((file) => revokeKey(file, keyName));

package/dist/cc-template.d.ts

@@ -16,11 +16,22 @@ export declare const CC_TEMPLATE: TemplateData;
 export declare function filterToolsForPlatform<T extends {
     name: string;
 }>(tools: T[], platform: string): T[];
+/**
+ * A tool definition the API will accept: an `input_schema` object with a
+ * string `type`. A capture can carry less — the 2026-09-18T01:26Z rebake on
+ * CC v2.1.275 recorded `advisor` as `{"name":"advisor","description":"",
+ * "input_schema":{}}`, a remote-config tool caught half-loaded — and Fable
+ * refuses any request advertising it (`tools.0.custom.input_schema.type: Field
+ * required`, dario#1376) while other families let it through. The name stays
+ * KNOWN (CC_NATIVE_NAMES_UNION, identity mapping, the config-scoped
+ * preservation); the definition is never put on the wire.
+ */
+export declare function isAdvertisableToolDefinition(def: unknown): boolean;
+/** Names in the bundle whose definition is not advertisable (see above). Empty on a clean bake. */
+export declare const CC_TOOL_DEFINITIONS_UNADVERTISABLE: Set<string>;
 /** CC's exact tool definitions for the current platform — filtered from the bundled union. */
 export declare const CC_TOOL_DEFINITIONS: {
     name: string;
-    description: string;
-    input_schema: Record<string, unknown>;
 }[];
 /** The UNFILTERED bundled union — every tool the bake knows across platforms
  *  (PLATFORM_ONLY_TOOLS keeps the bundle a superset). The identity-mapping,
@@ -36,9 +47,16 @@ export declare const CC_TOOL_DEFINITIONS: {
  *  merge-mode base array, and Fable's no-tools shape. */
 export declare const CC_TOOL_DEFINITIONS_UNION: {
     name: string;
-    description: string;
-    input_schema: Record<string, unknown>;
 }[];
+/**
+ * The most the template can add to an outbound prompt, in bytes: the largest
+ * system prompt the bundle carries plus every advertisable tool definition.
+ * The key-budget reservation (keys.ts requestBudgetReservation) adds this to
+ * the client's own body so a request is bounded by what dario SENDS, not by
+ * what the client sent — the template's prompt is billed to the key too.
+ */
+export declare const CC_TEMPLATE_PROMPT_BYTES: number;
+/** Every name the bundle knows — including one whose definition is not advertisable (dario#1376). */
 export declare const CC_NATIVE_NAMES_UNION: Set<string>;
 /** CC's own tool names, EXACT case ("Read", "Bash", "Agent", …). A CC client's
  *  tools identity-map to themselves and OVERRIDE TOOL_MAP — whose lowercase

package/dist/cc-template.js

@@ -29,8 +29,26 @@ export function filterToolsForPlatform(tools, platform) {
         return true;
     });
 }
+/**
+ * A tool definition the API will accept: an `input_schema` object with a
+ * string `type`. A capture can carry less — the 2026-09-18T01:26Z rebake on
+ * CC v2.1.275 recorded `advisor` as `{"name":"advisor","description":"",
+ * "input_schema":{}}`, a remote-config tool caught half-loaded — and Fable
+ * refuses any request advertising it (`tools.0.custom.input_schema.type: Field
+ * required`, dario#1376) while other families let it through. The name stays
+ * KNOWN (CC_NATIVE_NAMES_UNION, identity mapping, the config-scoped
+ * preservation); the definition is never put on the wire.
+ */
+export function isAdvertisableToolDefinition(def) {
+    if (!def || typeof def !== 'object')
+        return false;
+    const schema = def.input_schema;
+    return !!schema && typeof schema === 'object' && typeof schema.type === 'string';
+}
+/** Names in the bundle whose definition is not advertisable (see above). Empty on a clean bake. */
+export const CC_TOOL_DEFINITIONS_UNADVERTISABLE = new Set(TEMPLATE.tools.filter((t) => !isAdvertisableToolDefinition(t)).map((t) => String(t.name)));
 /** CC's exact tool definitions for the current platform — filtered from the bundled union. */
-export const CC_TOOL_DEFINITIONS = filterToolsForPlatform(TEMPLATE.tools, process.platform);
+export const CC_TOOL_DEFINITIONS = filterToolsForPlatform(TEMPLATE.tools.filter(isAdvertisableToolDefinition), process.platform);
 /** The UNFILTERED bundled union — every tool the bake knows across platforms
  *  (PLATFORM_ONLY_TOOLS keeps the bundle a superset). The identity-mapping,
  *  detection, and advertise paths intersect with what the CLIENT declared,
@@ -43,7 +61,20 @@ export const CC_TOOL_DEFINITIONS = filterToolsForPlatform(TEMPLATE.tools, proces
  *  upstream). Host-filtered CC_TOOL_DEFINITIONS stays correct for the paths
  *  with no client declaration to mirror: the full-template fallback, the
  *  merge-mode base array, and Fable's no-tools shape. */
-export const CC_TOOL_DEFINITIONS_UNION = TEMPLATE.tools;
+export const CC_TOOL_DEFINITIONS_UNION = TEMPLATE.tools.filter(isAdvertisableToolDefinition);
+/**
+ * The most the template can add to an outbound prompt, in bytes: the largest
+ * system prompt the bundle carries plus every advertisable tool definition.
+ * The key-budget reservation (keys.ts requestBudgetReservation) adds this to
+ * the client's own body so a request is bounded by what dario SENDS, not by
+ * what the client sent — the template's prompt is billed to the key too.
+ */
+export const CC_TEMPLATE_PROMPT_BYTES = (() => {
+    const t = TEMPLATE;
+    const sizes = [JSON.stringify(t.system_prompt ?? '').length, ...Object.values(t.system_prompt_variants ?? {}).map((v) => JSON.stringify(v ?? '').length)];
+    return Math.max(0, ...sizes) + JSON.stringify(CC_TOOL_DEFINITIONS_UNION).length;
+})();
+/** Every name the bundle knows — including one whose definition is not advertisable (dario#1376). */
 export const CC_NATIVE_NAMES_UNION = new Set(TEMPLATE.tools.map((t) => String(t.name)));
 /** CC's own tool names, EXACT case ("Read", "Bash", "Agent", …). A CC client's
  *  tools identity-map to themselves and OVERRIDE TOOL_MAP — whose lowercase
@@ -2068,8 +2099,14 @@ export function buildCCRequest(clientBody, billingTag, cacheControl, identity, o
             // authoritative source, never the template.
             const availableCC = CC_TOOL_DEFINITIONS_UNION.filter((t) => !isMcpToolName(t.name) && clientToolNames.has(t.name.toLowerCase()));
             const mcpTools = clientTools.filter((t) => isMcpToolName(t.name));
-            ccRequest.tools = availableCC.length > 0 || mcpTools.length > 0
-                ? dedupeToolsByName([...availableCC, ...mcpTools])
+            // A CC-native name the bundle knows but cannot advertise (dario#1376:
+            // `advisor` captured with an empty schema) is still identity-mapped
+            // above; the only usable definition is the client's own, so it goes out
+            // verbatim, as MCP tools do. The client's schema is what its parser
+            // expects back in any case.
+            const clientOwnNative = clientTools.filter((t) => typeof t.name === 'string' && CC_TOOL_DEFINITIONS_UNADVERTISABLE.has(t.name) && isAdvertisableToolDefinition(t));
+            ccRequest.tools = availableCC.length > 0 || mcpTools.length > 0 || clientOwnNative.length > 0
+                ? dedupeToolsByName([...availableCC, ...clientOwnNative, ...mcpTools])
                 : CC_TOOL_DEFINITIONS;
         }
     }

package/dist/cli.js

@@ -19,7 +19,38 @@
 import { unlink, writeFile } from 'node:fs/promises';
 import { formatLedgerSummary, formatLedgerConsumers, formatUsd, renderLedgerCard, readLedgerFile, resolveLedgerPath, summarizeLedger } from './ledger.js';
 import { renderSpendDonuts } from './donuts.js';
-import { KeyStore, createKey, revokeKey, rotateKey, deleteKey, parseExpiry, publicKey, resolveKeysPath, KEY_NAME_RE } from './keys.js';
+import { KeyStore, createKey, revokeKey, rotateKey, deleteKey, parseExpiry, publicKey, resolveKeysPath, KEY_NAME_RE, setKeyBudget, parseUsdBudget, parseTokenBudget, formatBudget } from './keys.js';
+/**
+ * `--budget=$5/day` / `--budget-tokens=2M/day` → a KeyBudget, or undefined when
+ * neither flag is present. A flag that does not parse exits 1 with the accepted
+ * forms, like --expires does.
+ */
+function readBudgetFlags(args) {
+    const usdArg = args.find((a) => a.startsWith('--budget='));
+    const tokArg = args.find((a) => a.startsWith('--budget-tokens='));
+    if (!usdArg && !tokArg)
+        return undefined;
+    const budget = {};
+    if (usdArg) {
+        const v = usdArg.slice('--budget='.length);
+        const n = parseUsdBudget(v);
+        if (n === null) {
+            console.error(`[dario] --budget: "${v}" is not a dollar amount per day ($5, 5.00, $5/day).`);
+            process.exit(1);
+        }
+        budget.usdPerDay = n;
+    }
+    if (tokArg) {
+        const v = tokArg.slice('--budget-tokens='.length);
+        const n = parseTokenBudget(v);
+        if (n === null) {
+            console.error(`[dario] --budget-tokens: "${v}" is not a token count per day (250k, 2M, 2000000).`);
+            process.exit(1);
+        }
+        budget.tokensPerDay = n;
+    }
+    return budget;
+}
 import { loadAllAccounts as loadAllAccountsForIdentity, regenerateClientIdentity } from './accounts.js';
 import { maskEmail, parsePoolHeadroomFloor } from './pool.js';
 import { realpathSync, readFileSync } from 'node:fs';
@@ -785,9 +816,9 @@ async function keys() {
             return;
         }
         const w = Math.max(4, ...list.map((k) => k.name.length));
-        console.log(`  ${'NAME'.padEnd(w)}  ${'STATUS'.padEnd(7)}  ${'SEAT'.padEnd(12)}  ${'LAST USED'.padEnd(10)}  ${'EXPIRES'.padEnd(10)}  MODELS`);
+        console.log(`  ${'NAME'.padEnd(w)}  ${'STATUS'.padEnd(7)}  ${'SEAT'.padEnd(12)}  ${'LAST USED'.padEnd(10)}  ${'EXPIRES'.padEnd(10)}  ${'BUDGET'.padEnd(20)}  MODELS`);
         for (const k of list) {
-            console.log(`  ${k.name.padEnd(w)}  ${k.status.padEnd(7)}  ${(k.seat ?? '-').padEnd(12)}  ${fmtAgo(k.last_used).padEnd(10)}  ${fmtDay(k.expires).padEnd(10)}  ${k.models.length ? k.models.join(', ') : 'any'}`);
+            console.log(`  ${k.name.padEnd(w)}  ${k.status.padEnd(7)}  ${(k.seat ?? '-').padEnd(12)}  ${fmtAgo(k.last_used).padEnd(10)}  ${fmtDay(k.expires).padEnd(10)}  ${formatBudget(k.budget ? { usdPerDay: k.budget.usd_per_day ?? undefined, tokensPerDay: k.budget.tokens_per_day ?? undefined } : null).padEnd(20)}  ${k.models.length ? k.models.join(', ') : 'any'}`);
         }
         console.log('');
         console.log(`  ${list.length} key${list.length === 1 ? '' : 's'} in ${path}. Spend per key: dario usage --by-key`);
@@ -798,7 +829,7 @@ async function keys() {
         const name = args[2];
         if (!name || name.startsWith('--')) {
             console.error('');
-            console.error('  Usage: dario keys create <name> [--seat=<alias>] [--models=a,b,prefix*] [--expires=30d|12h|2w|<ISO date>]');
+            console.error('  Usage: dario keys create <name> [--seat=<alias>] [--models=a,b,prefix*] [--expires=30d|12h|2w|<ISO date>] [--budget=$5/day] [--budget-tokens=2M/day]');
             console.error('');
             process.exit(1);
         }
@@ -816,8 +847,9 @@ async function keys() {
             }
             expiresAt = parsed;
         }
+        const budget = readBudgetFlags(args);
         try {
-            const made = store.mutate((file) => createKey(file, name, { seat, models, expiresAt, now }));
+            const made = store.mutate((file) => createKey(file, name, { seat, models, expiresAt, budget, now }));
             printSecret('created', publicKey(made.record, now), made.secret);
         }
         catch (err) {
@@ -826,6 +858,33 @@ async function keys() {
         }
         return;
     }
+    // dario keys budget <name> --budget=$5/day --budget-tokens=2M/day | --clear
+    if (sub === 'budget') {
+        const name = args[2];
+        if (!name || !KEY_NAME_RE.test(name) || (!args.includes('--clear') && !args.some((a) => a.startsWith('--budget=') || a.startsWith('--budget-tokens=')))) {
+            console.error('');
+            console.error('  Usage: dario keys budget <name> [--budget=$5/day] [--budget-tokens=2M/day] | --clear');
+            console.error('');
+            console.error('  Caps are per UTC day and read from the ledger (dario usage --by-key); a request that');
+            console.error('  would start past a cap is refused with 429 until midnight UTC.');
+            console.error('');
+            process.exit(1);
+        }
+        try {
+            const budget = args.includes('--clear') ? null : (readBudgetFlags(args) ?? null);
+            const updated = store.mutate((file) => setKeyBudget(file, name, budget));
+            if (!updated) {
+                console.error(`[dario] No key named "${name}".`);
+                process.exit(1);
+            }
+            console.log(budget ? `[dario] Key "${name}" budget: ${formatBudget(updated.budget)}` : `[dario] Key "${name}" budget cleared.`);
+        }
+        catch (err) {
+            console.error(`[dario] ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
     if (sub === 'rotate' || sub === 'revoke' || sub === 'remove' || sub === 'rm' || sub === 'delete') {
         const name = args[2];
         if (!name || !KEY_NAME_RE.test(name)) {
@@ -867,7 +926,7 @@ async function keys() {
         return;
     }
     console.error(`[dario] Unknown keys subcommand: ${sub}`);
-    console.error('Usage: dario keys [list|create <name> [--seat=..] [--models=..] [--expires=..]|revoke <name>|rotate <name>|remove <name>] [--json] [--keys-path=<file>]');
+    console.error('Usage: dario keys [list|create <name> [--seat=..] [--models=..] [--expires=..] [--budget=..] [--budget-tokens=..]|budget <name> ..|revoke <name>|rotate <name>|remove <name>] [--json] [--keys-path=<file>]');
     process.exit(1);
 }
 /**

package/dist/keys.d.ts

@@ -21,7 +21,109 @@ export interface KeyRecord {
     seat?: string;
     /** Model allowlist: exact ids, or `prefix*`. Empty / absent = any model. */
     models?: string[];
+    /** Daily caps, UTC day, enforced from the ledger (dario#1318 follow-up). Absent = unlimited. */
+    budget?: KeyBudget;
 }
+/**
+ * A key's daily budget. Both caps are per UTC day and both are read from the
+ * ledger's per-consumer rows at request time, so they survive a restart and
+ * every dollar can be traced to `dario usage --by-key`. `usdPerDay` is the
+ * API-equivalent price of the key's traffic (covered + metered); `tokensPerDay`
+ * counts every token the key sent or received, cache reads included.
+ */
+export interface KeyBudget {
+    usdPerDay?: number;
+    tokensPerDay?: number;
+}
+/** What the ledger says a key has used today; the budget is compared against this. */
+export interface KeyBudgetUsage {
+    usd: number;
+    tokens: number;
+    requests: number;
+}
+export interface KeyBudgetVerdict {
+    over: boolean;
+    /** Which cap tripped first. */
+    reason: 'usd' | 'tokens' | null;
+    /** Completed rows only — what the ledger has. */
+    usage: KeyBudgetUsage;
+    /** Requests admitted and not yet completed when this verdict was made, and what was reserved for them. */
+    inflight: KeyBudgetReservation;
+    /** `usage` plus the in-flight reservations — what `over` was decided on. */
+    projected: KeyBudgetUsage;
+    budget: KeyBudget;
+    /** Epoch ms of the next UTC midnight — when the day's counters reset. */
+    resetAt: number;
+    retryAfterSec: number;
+}
+/**
+ * What a request is charged against the budget while it is in flight: an
+ * UPPER BOUND on what it can cost, so a burst of admitted requests can never
+ * complete for more than the cap plus one request. The ledger prices a
+ * request only once its response is in; until then what dario will SEND
+ * bounds both sides. Prompt: the client's body plus whatever the template
+ * adds (system prompt, tool definitions), at BUDGET_BYTES_PER_TOKEN bytes per
+ * token, priced as cache-create — the highest input-side rate, so any mix of
+ * input, cache-read and cache-create tokens (all of which are prompt tokens,
+ * and so all inside this byte count) costs no more. Output: the max_tokens
+ * dario will put on the wire (the template's default when it pins one, the
+ * client's when it does not; BUDGET_DEFAULT_MAX_TOKENS when nothing is set),
+ * at the output rate — thinking is billed as output and lives under the same
+ * cap. Tokens reserve the same two counts.
+ */
+export interface KeyBudgetReservation {
+    count: number;
+    usd: number;
+    tokens: number;
+}
+/** A conservative bytes-per-token for the reservation: prose is ~4, code and CJK are lower. */
+export declare const BUDGET_BYTES_PER_TOKEN = 3;
+/** Reserved output when the client sends no max_tokens / max_completion_tokens / max_output_tokens. */
+export declare const BUDGET_DEFAULT_MAX_TOKENS = 8192;
+export declare const EMPTY_RESERVATION: KeyBudgetReservation;
+/**
+ * The reservation for one request, from what is known before it is sent.
+ * `priceOf` is analytics' costOfTokens, injected so this module stays free of
+ * the pricing table (the ledger injects the same way).
+ */
+export declare function requestBudgetReservation(model: string, bodyBytes: number, maxTokens: number | null | undefined, priceOf: (model: string, atMs: number, cell: {
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreateTokens: number;
+}) => number, now?: number, 
+/** Bytes dario adds to the prompt beyond the client's body (the template's system prompt and tools). */
+extraPromptBytes?: number): KeyBudgetReservation;
+export declare function addReservation(a: KeyBudgetReservation, b: KeyBudgetReservation): KeyBudgetReservation;
+export declare function subtractReservation(a: KeyBudgetReservation, b: KeyBudgetReservation): KeyBudgetReservation;
+/** Throws on a cap that is not a positive finite number; returns undefined when neither cap is set. */
+export declare function normalizeBudget(b: KeyBudget | null | undefined): KeyBudget | undefined;
+/** `$5`, `5`, `5.00`, `$5/day`, `5/d` → dollars per day; null when unparseable. */
+export declare function parseUsdBudget(value: string): number | null;
+/** `250000`, `250k`, `2M`, `1.5m/day` → tokens per day (integer); null when unparseable. */
+export declare function parseTokenBudget(value: string): number | null;
+/** `{ usdPerDay: 5, tokensPerDay: 2_000_000 }` → `$5/day · 2.0M tok/day`; `-` for none. */
+export declare function formatBudget(b: KeyBudget | null | undefined): string;
+/** Next UTC midnight after `now`, epoch ms. */
+export declare function nextUtcMidnight(now: number): number;
+/**
+ * Over or under, given what the ledger has counted for the key today AND what
+ * is reserved for the requests already admitted but not yet completed. The
+ * ledger only knows a request once its response is in, so a burst of N
+ * simultaneous requests would all read the same completed total and all
+ * pass; every in-flight request is therefore held at its reservation — an
+ * upper bound on its cost (requestBudgetReservation) — until it completes.
+ * A request is admitted while completed + reserved is under the cap, so the
+ * most a key can complete in a day is the cap plus ONE request, whatever the
+ * burst size or the size of the requests in it. `retryAfterSec` is the time
+ * to the UTC day boundary, when the counters reset.
+ */
+export declare function budgetVerdict(budget: KeyBudget, usage: KeyBudgetUsage, now?: number, inflight?: KeyBudgetReservation): KeyBudgetVerdict;
+/** The response headers a budgeted key's request carries, served or refused. */
+export declare function budgetHeaders(v: KeyBudgetVerdict, keyName: string): Record<string, string>;
+/** Replace (or clear, with null) a key's budget. Null result: no such key. */
+export declare function setKeyBudget(file: KeysFile, name: string, budget: KeyBudget | null): KeyRecord | null;
 export interface KeysFile {
     version: number;
     keys: KeyRecord[];
@@ -53,6 +155,8 @@ export declare function writeKeysFile(path: string, file: KeysFile): void;
 export interface CreateKeyOptions {
     seat?: string;
     models?: string[];
+    /** Daily caps; see KeyBudget. */
+    budget?: KeyBudget;
     /** Absolute expiry, epoch ms. */
     expiresAt?: number;
     now?: number;
@@ -92,6 +196,11 @@ export interface KeyPublic {
     expires: string | null;
     seat: string | null;
     models: string[];
+    /** Daily caps, or null when the key has none. */
+    budget: {
+        usd_per_day: number | null;
+        tokens_per_day: number | null;
+    } | null;
 }
 export declare function publicKey(k: KeyRecord, now?: number): KeyPublic;
 /** `--expires=30d` / `12h` / `2026-12-31` → epoch ms, or null when unparseable. */

package/dist/keys.js

@@ -37,6 +37,131 @@ export const KEY_PREFIX = 'dk_';
 export const KEY_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_\-.]{0,63}$/;
 export const KEYS_FLUSH_DELAY_MS = 3_000;
 const SECRET_BYTES = 24;
+/** A conservative bytes-per-token for the reservation: prose is ~4, code and CJK are lower. */
+export const BUDGET_BYTES_PER_TOKEN = 3;
+/** Reserved output when the client sends no max_tokens / max_completion_tokens / max_output_tokens. */
+export const BUDGET_DEFAULT_MAX_TOKENS = 8_192;
+export const EMPTY_RESERVATION = { count: 0, usd: 0, tokens: 0 };
+/**
+ * The reservation for one request, from what is known before it is sent.
+ * `priceOf` is analytics' costOfTokens, injected so this module stays free of
+ * the pricing table (the ledger injects the same way).
+ */
+export function requestBudgetReservation(model, bodyBytes, maxTokens, priceOf, now = Date.now(), 
+/** Bytes dario adds to the prompt beyond the client's body (the template's system prompt and tools). */
+extraPromptBytes = 0) {
+    const inputTokens = Math.ceil((Math.max(0, bodyBytes) + Math.max(0, extraPromptBytes)) / BUDGET_BYTES_PER_TOKEN);
+    const outputTokens = Number.isFinite(maxTokens) && maxTokens > 0 ? Math.ceil(maxTokens) : BUDGET_DEFAULT_MAX_TOKENS;
+    const usd = priceOf(model, now, { requests: 1, inputTokens: 0, outputTokens, cacheReadTokens: 0, cacheCreateTokens: inputTokens });
+    return { count: 1, usd: Number.isFinite(usd) ? usd : 0, tokens: inputTokens + outputTokens };
+}
+export function addReservation(a, b) {
+    return { count: a.count + b.count, usd: a.usd + b.usd, tokens: a.tokens + b.tokens };
+}
+export function subtractReservation(a, b) {
+    const count = Math.max(0, a.count - b.count);
+    return count === 0 ? { ...EMPTY_RESERVATION } : { count, usd: Math.max(0, a.usd - b.usd), tokens: Math.max(0, a.tokens - b.tokens) };
+}
+/** Throws on a cap that is not a positive finite number; returns undefined when neither cap is set. */
+export function normalizeBudget(b) {
+    if (!b)
+        return undefined;
+    const out = {};
+    if (b.usdPerDay !== undefined && b.usdPerDay !== null) {
+        if (!Number.isFinite(b.usdPerDay) || b.usdPerDay <= 0)
+            throw new Error('budget: usdPerDay must be a positive number');
+        out.usdPerDay = Math.round(b.usdPerDay * 100) / 100;
+    }
+    if (b.tokensPerDay !== undefined && b.tokensPerDay !== null) {
+        if (!Number.isFinite(b.tokensPerDay) || b.tokensPerDay <= 0)
+            throw new Error('budget: tokensPerDay must be a positive number');
+        out.tokensPerDay = Math.round(b.tokensPerDay);
+    }
+    return out.usdPerDay === undefined && out.tokensPerDay === undefined ? undefined : out;
+}
+/** `$5`, `5`, `5.00`, `$5/day`, `5/d` → dollars per day; null when unparseable. */
+export function parseUsdBudget(value) {
+    const m = /^\$?\s*(\d+(?:\.\d{1,2})?)\s*(?:\/\s*(?:day|d))?$/i.exec(value.trim());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/** `250000`, `250k`, `2M`, `1.5m/day` → tokens per day (integer); null when unparseable. */
+export function parseTokenBudget(value) {
+    const m = /^(\d+(?:\.\d+)?)\s*([kKmM]?)\s*(?:tok(?:ens)?)?\s*(?:\/\s*(?:day|d))?$/.exec(value.trim());
+    if (!m)
+        return null;
+    const mult = m[2]?.toLowerCase() === 'k' ? 1_000 : m[2]?.toLowerCase() === 'm' ? 1_000_000 : 1;
+    const n = Math.round(Number(m[1]) * mult);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+/** `{ usdPerDay: 5, tokensPerDay: 2_000_000 }` → `$5/day · 2.0M tok/day`; `-` for none. */
+export function formatBudget(b) {
+    if (!b || (b.usdPerDay === undefined && b.tokensPerDay === undefined))
+        return '-';
+    const parts = [];
+    if (b.usdPerDay !== undefined)
+        parts.push(`$${b.usdPerDay % 1 === 0 ? b.usdPerDay : b.usdPerDay.toFixed(2)}/day`);
+    if (b.tokensPerDay !== undefined) {
+        const t = b.tokensPerDay;
+        const s = t >= 1_000_000 ? `${(t / 1_000_000).toFixed(t % 1_000_000 === 0 ? 0 : 1)}M` : t >= 1_000 ? `${(t / 1_000).toFixed(t % 1_000 === 0 ? 0 : 1)}k` : String(t);
+        parts.push(`${s} tok/day`);
+    }
+    return parts.join(' · ');
+}
+/** Next UTC midnight after `now`, epoch ms. */
+export function nextUtcMidnight(now) {
+    const d = new Date(now);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+}
+/**
+ * Over or under, given what the ledger has counted for the key today AND what
+ * is reserved for the requests already admitted but not yet completed. The
+ * ledger only knows a request once its response is in, so a burst of N
+ * simultaneous requests would all read the same completed total and all
+ * pass; every in-flight request is therefore held at its reservation — an
+ * upper bound on its cost (requestBudgetReservation) — until it completes.
+ * A request is admitted while completed + reserved is under the cap, so the
+ * most a key can complete in a day is the cap plus ONE request, whatever the
+ * burst size or the size of the requests in it. `retryAfterSec` is the time
+ * to the UTC day boundary, when the counters reset.
+ */
+export function budgetVerdict(budget, usage, now = Date.now(), inflight = EMPTY_RESERVATION) {
+    const resetAt = nextUtcMidnight(now);
+    const projected = { usd: usage.usd + inflight.usd, tokens: usage.tokens + inflight.tokens, requests: usage.requests + inflight.count };
+    let reason = null;
+    if (budget.usdPerDay !== undefined && projected.usd >= budget.usdPerDay)
+        reason = 'usd';
+    else if (budget.tokensPerDay !== undefined && projected.tokens >= budget.tokensPerDay)
+        reason = 'tokens';
+    return { over: reason !== null, reason, usage, inflight, projected, budget, resetAt, retryAfterSec: Math.max(1, Math.ceil((resetAt - now) / 1000)) };
+}
+/** The response headers a budgeted key's request carries, served or refused. */
+export function budgetHeaders(v, keyName) {
+    const h = { 'x-dario-budget-key': keyName, 'x-dario-budget-resets-at': new Date(v.resetAt).toISOString(), 'x-dario-budget-inflight': String(v.inflight.count) };
+    if (v.budget.usdPerDay !== undefined) {
+        h['x-dario-budget-usd'] = String(v.budget.usdPerDay);
+        h['x-dario-budget-used-usd'] = v.usage.usd.toFixed(4);
+    }
+    if (v.budget.tokensPerDay !== undefined) {
+        h['x-dario-budget-tokens'] = String(v.budget.tokensPerDay);
+        h['x-dario-budget-used-tokens'] = String(v.usage.tokens);
+    }
+    return h;
+}
+/** Replace (or clear, with null) a key's budget. Null result: no such key. */
+export function setKeyBudget(file, name, budget) {
+    const k = file.keys.find((x) => x.name === name);
+    if (!k)
+        return null;
+    const normalized = normalizeBudget(budget);
+    if (normalized)
+        k.budget = normalized;
+    else
+        delete k.budget;
+    return k;
+}
 export function keysPathFor(home = homedir()) {
     return join(home, '.dario', 'keys.json');
 }
@@ -100,6 +225,16 @@ export function parseKeysFile(text) {
             if (models.length > 0)
                 rec.models = models;
         }
+        // Daily caps (dario#1318 follow-up): kept only when they parse as positive numbers.
+        if (k.budget && typeof k.budget === 'object') {
+            const b = k.budget;
+            try {
+                const budget = normalizeBudget({ usdPerDay: typeof b.usdPerDay === 'number' ? b.usdPerDay : undefined, tokensPerDay: typeof b.tokensPerDay === 'number' ? b.tokensPerDay : undefined });
+                if (budget)
+                    rec.budget = budget;
+            }
+            catch { /* a malformed cap is dropped, never a reason to refuse the whole file */ }
+        }
         seen.add(rec.name);
         keys.push(rec);
     }
@@ -152,6 +287,9 @@ export function createKey(file, name, opts = {}) {
         record.seat = opts.seat;
     if (opts.models && opts.models.length > 0)
         record.models = opts.models.map((m) => m.trim()).filter(Boolean);
+    const budget = normalizeBudget(opts.budget);
+    if (budget)
+        record.budget = budget;
     if (opts.expiresAt !== undefined) {
         if (!Number.isFinite(opts.expiresAt) || opts.expiresAt <= (opts.now ?? Date.now()))
             throw new Error('expiry must be in the future');
@@ -228,7 +366,8 @@ export function keyAllowsModel(k, model) {
 }
 export function publicKey(k, now = Date.now()) {
     const status = k.disabled ? 'revoked' : k.expires && Date.parse(k.expires) <= now ? 'expired' : 'active';
-    return { id: k.id, name: k.name, created: k.created, last_used: k.lastUsed ?? null, status, expires: k.expires ?? null, seat: k.seat ?? null, models: k.models ?? [] };
+    const budget = k.budget ? { usd_per_day: k.budget.usdPerDay ?? null, tokens_per_day: k.budget.tokensPerDay ?? null } : null;
+    return { id: k.id, name: k.name, created: k.created, last_used: k.lastUsed ?? null, status, expires: k.expires ?? null, seat: k.seat ?? null, budget, models: k.models ?? [] };
 }
 /** `--expires=30d` / `12h` / `2026-12-31` → epoch ms, or null when unparseable. */
 export function parseExpiry(value, now = Date.now()) {

package/dist/ledger.d.ts

@@ -155,6 +155,17 @@ export declare function addToLedger(file: LedgerFile, record: RequestRecord): bo
 export declare function pruneLedger(file: LedgerFile, maxDays?: number): void;
 /** The per-consumer split of a file, priced the same way as the headline. */
 export declare function summarizeLedgerConsumers(file: LedgerFile, now?: number): Record<string, LedgerConsumerSummary>;
+/**
+ * What one consumer has used so far TODAY (UTC), priced the same way as the
+ * headline: covered and metered rows both count, because a budget is about the
+ * traffic a key caused, not about who paid for it. Tokens are all four buckets.
+ * The key-budget check (src/keys.ts budgetVerdict) reads this per request.
+ */
+export declare function consumerDayUsage(file: LedgerFile, consumer: string, now?: number): {
+    usd: number;
+    tokens: number;
+    requests: number;
+};
 /** `1234` → `1.2k`, `1234567` → `1.2M`; below a thousand, the number itself. */
 export declare function formatTokenCount(n: number): string;
 export declare function summarizeLedger(file: LedgerFile, path: string, now?: number): LedgerSummary;
@@ -185,6 +196,12 @@ export declare class Ledger {
     /** Count a request. Returns false when it was not ledger material. */
     add(record: RequestRecord): boolean;
     summary(now?: number): LedgerSummary;
+    /** Today's usage for one consumer — the key-budget check's input. */
+    consumerToday(consumer: string, now?: number): {
+        usd: number;
+        tokens: number;
+        requests: number;
+    };
     /** The raw per-day table, for /analytics/ledger. */
     snapshot(): LedgerFile;
     private scheduleFlush;

package/dist/ledger.js

@@ -241,6 +241,31 @@ export function summarizeLedgerConsumers(file, now = Date.now()) {
     }
     return result;
 }
+/**
+ * What one consumer has used so far TODAY (UTC), priced the same way as the
+ * headline: covered and metered rows both count, because a budget is about the
+ * traffic a key caused, not about who paid for it. Tokens are all four buckets.
+ * The key-budget check (src/keys.ts budgetVerdict) reads this per request.
+ */
+export function consumerDayUsage(file, consumer, now = Date.now()) {
+    const day = dayKey(now);
+    const models = file.consumers?.[day]?.[consumer];
+    const out = { usd: 0, tokens: 0, requests: 0 };
+    if (!models)
+        return out;
+    const at = dayMs(day);
+    for (const [model, row] of Object.entries(models)) {
+        for (const cell of [row.covered, row.metered]) {
+            if (!cell)
+                continue;
+            out.usd += costOfTokens(model, at, cell);
+            out.tokens += cell.inputTokens + cell.outputTokens + cell.cacheReadTokens + cell.cacheCreateTokens;
+            out.requests += cell.requests;
+        }
+    }
+    out.usd = round(out.usd);
+    return out;
+}
 function addTokens(into, cell) {
     into.inputTokens += cell.inputTokens;
     into.outputTokens += cell.outputTokens;
@@ -405,6 +430,10 @@ export class Ledger {
     summary(now = Date.now()) {
         return summarizeLedger(this.file, this.path, now);
     }
+    /** Today's usage for one consumer — the key-budget check's input. */
+    consumerToday(consumer, now = Date.now()) {
+        return consumerDayUsage(this.file, consumer, now);
+    }
     /** The raw per-day table, for /analytics/ledger. */
     snapshot() {
         return JSON.parse(JSON.stringify(this.file));

package/dist/metrics.d.ts

@@ -19,6 +19,13 @@ export interface MetricsInput {
     /** Most recent records, newest last — the latency quantiles come from these. */
     recent: readonly RequestRecord[];
     version: string;
+    /** Per-key daily budgets and today's use (keys with a budget only); absent when keys or the ledger are off. */
+    budgets?: Record<string, {
+        usdPerDay: number | null;
+        tokensPerDay: number | null;
+        usedUsd: number;
+        usedTokens: number;
+    }>;
 }
 /** Nearest-rank quantile over a sorted ascending array. */
 export declare function quantile(sorted: readonly number[], q: number): number;

package/dist/metrics.js

@@ -117,6 +117,14 @@ export function renderPrometheus(input) {
             out.push(`${fam.name}_count ${vals.length}`);
         }
     }
+    // ---- per-key daily budgets (dario#1318 follow-up) ----------------------
+    const budgets = Object.entries(input.budgets ?? {});
+    if (budgets.length > 0) {
+        metric('dario_key_budget_usd_per_day', 'Daily API-equivalent cap per named key, USD (keys with a dollar cap).', budgets.filter(([, b]) => b.usdPerDay !== null).map(([key, b]) => [{ key }, b.usdPerDay]));
+        metric('dario_key_budget_used_usd', 'API-equivalent spend per budgeted key today (UTC), USD.', budgets.map(([key, b]) => [{ key }, b.usedUsd]));
+        metric('dario_key_budget_tokens_per_day', 'Daily token cap per named key (keys with a token cap).', budgets.filter(([, b]) => b.tokensPerDay !== null).map(([key, b]) => [{ key }, b.tokensPerDay]));
+        metric('dario_key_budget_used_tokens', 'Tokens per budgeted key today (UTC), all buckets.', budgets.map(([key, b]) => [{ key }, b.usedTokens]));
+    }
     // ---- predictions -------------------------------------------------------
     const p = summary.predictions;
     if (p.estimatedExhaustionMinutes !== null) {

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 { 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 { 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
@@ -2737,13 +2769,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 +3037,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;
@@ -3473,6 +3511,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.
@@ -5230,6 +5317,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 +5691,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) => {
@@ -5650,6 +5745,11 @@ export async function startProxy(opts = {}) {
     // One-line template summary so users can tell at a glance whether they
     // booted on a fresh live capture or a stale bundled fallback.
     console.log(`[dario] template: ${describeTemplate(CC_TEMPLATE)}`);
+    // A bundled definition the API refuses (dario#1376: advisor captured with an
+    // empty schema) is kept as a known name and never advertised; say so once.
+    if (CC_TOOL_DEFINITIONS_UNADVERTISABLE.size > 0) {
+        console.log(`[dario] template: ${CC_TOOL_DEFINITIONS_UNADVERTISABLE.size} tool definition${CC_TOOL_DEFINITIONS_UNADVERTISABLE.size === 1 ? '' : 's'} without input_schema.type — known, never advertised: ${[...CC_TOOL_DEFINITIONS_UNADVERTISABLE].join(', ')}`);
+    }
     // Drift check: compare captured CC version to the installed binary. If
     // they differ, force the background refresh to bypass TTL so the next
     // startup picks up the new capture. Drifted caches still serve the

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.2",
+  "version": "6.10.0",
   "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"
   }