@askalf/dario 6.9.3 → 6.10.1

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

@@ -122,6 +122,13 @@ export interface AdminAccountLive {
     rejectedCount: number;
     /** Epoch ms of the most recent 429 on this account, or `null` if never. */
     lastRejectedAt: number | null;
+    /**
+     * Per-model buckets keeping their families off this seat while the seat
+     * itself still serves (`['oi']`: Fable parked on a Pro seat whose included
+     * overage is spent, Opus unaffected). Empty when none. Optional: a peer's
+     * snapshot from before the field behaves as before.
+     */
+    parkedBuckets?: string[];
     /** Organization observed on this seat's responses, or `null` if none yet (dario#1244). */
     organizationId: string | null;
     /**
@@ -158,7 +165,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) {
@@ -546,6 +569,7 @@ export async function handleAdminRequest(req, res, urlPath, deps) {
                         request_count: l.requestCount,
                         rejected_count: l.rejectedCount ?? 0,
                         last_rejected_at: l.lastRejectedAt ?? null,
+                        parked_buckets: l.parkedBuckets ?? [],
                         consecutive_auth_failures: l.consecutiveAuthFailures,
                     } : {}),
                 };
@@ -609,8 +633,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 +677,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

@@ -48,6 +48,14 @@ export declare const CC_TOOL_DEFINITIONS: {
 export declare const CC_TOOL_DEFINITIONS_UNION: {
     name: string;
 }[];
+/**
+ * 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

package/dist/cc-template.js

@@ -62,6 +62,18 @@ export const CC_TOOL_DEFINITIONS = filterToolsForPlatform(TEMPLATE.tools.filter(
  *  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.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

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;