@hiper2d/ai-agents 0.2.1 → 0.3.1

package/README.md

@@ -74,6 +74,37 @@ Transcribe (`VOICE_MODEL_CONSTANTS`, prices in `VOICE_MODEL_PRICING`). The `voic
 direction works for both providers: OpenAI takes it as instructions, Gemini gets it folded
 into the prompt ("Say gravely: …").
 
+### Budget control
+
+Per-subject spend caps (a user, a tenant, a job) over UTC day and month windows. Pure and
+storage-agnostic: period keys, an O(1) rolling ledger that is overwritten when the period
+rolls, a verdict function, and `BudgetExceededError` carrying the verdict (`resetsAt`,
+`remainingUSD`) so the host can render "come back at …" instead of a provider failure.
+
+```ts
+import { BudgetController, InMemorySpendStore, BudgetExceededError } from '@hiper2d/ai-agents';
+
+const budget = new BudgetController(new InMemorySpendStore(), {
+  limits: [{ window: 'day', limitUSD: 5 }, { window: 'month', limitUSD: 20 }],
+});
+await budget.assertWithinBudget(userId);          // cheap pre-call guard, throws BudgetExceededError
+const { costUSD } = await agent.ask(...);
+await budget.record(userId, costUSD);              // re-checks inside the store's atomic update
+```
+
+Hosts that bill inside their own database transaction skip the controller and call the
+pure pieces there: `ledgerSpend` → `evaluateBudget` → `applySpend`. Implement `SpendStore`
+to back the controller with Redis, Postgres, Firestore, etc.
+
+To guard every LLM call without touching call sites, install a process-wide pre-ask hook
+once at startup. It runs before each `askText` / `askWithZodSchema` with the agent, so a
+throwing hook refuses the call before anything reaches the provider:
+
+```ts
+import { setBeforeAskHook } from '@hiper2d/ai-agents';
+setBeforeAskHook(async agent => { if (agent.userId) await budget.assertWithinBudget(agent.userId); });
+```
+
 ### Logging
 
 The library logs through an injectable sink — `setLlmLogger(fn)` — so a host app can route

package/dist/index.d.mts

@@ -1019,6 +1019,155 @@ declare const GEMINI_AUDIO_TOKENS_PER_SECOND = 25;
  */
 declare function transcribeWithGemini(audioBuffer: ArrayBuffer, apiKey: string, options?: GoogleSttOptions): Promise<GoogleSttResult>;
 
+/**
+ * Budget control for agent spend — pure and storage-agnostic.
+ *
+ * The problem this solves: an app that runs LLM/voice/image calls on its own keys needs
+ * to bound what one subject (a user, a tenant, a job) can spend per UTC day or month, and
+ * needs the check to be cheap enough to run before EVERY call. The pieces:
+ *
+ * - `periodKey` / `periodEnd`: UTC window keys (`YYYY-MM-DD`, `YYYY-MM`) and reset times.
+ * - `SpendLedger` + `applySpend`: an O(1) rolling ledger for one window. It is overwritten,
+ *   not appended, when the period changes, so the persisted record never grows; history
+ *   belongs in your per-request stats, not here.
+ * - `evaluateBudget`: the verdict. Pure, no I/O, no throwing.
+ * - `BudgetExceededError`: what to throw when a verdict refuses, carrying the verdict so
+ *   the caller can render "come back at <resetsAt>" instead of treating it as a provider
+ *   failure.
+ * - `BudgetController` over a `SpendStore`: batteries-included wrapper for projects that
+ *   do not need to fold the ledger into their own database transaction. Apps that do
+ *   (the werewolf app charges the user, updates the game and writes a stats row in one
+ *   Firestore transaction) use the pure functions directly inside that transaction.
+ *
+ * Amounts are USD, rounded to 6 decimals like the rest of the cost accounting.
+ */
+type SpendWindow = 'day' | 'month';
+/** Where the money went; free-form beyond the common kinds so apps can add their own. */
+type SpendKind = 'llm' | 'image' | 'tts' | 'stt' | (string & {});
+/** UTC key for the window containing `timestamp`: `2026-09-11` for a day, `2026-09` for a month. */
+declare function periodKey(timestamp: number, window: SpendWindow): string;
+/** First millisecond of the window after the one containing `timestamp` — i.e. when the budget resets. */
+declare function periodEnd(timestamp: number, window: SpendWindow): number;
+/**
+ * Spend recorded for ONE window. `buckets` split the total by whatever the app cares
+ * about (tier, model family, feature); the total is authoritative, buckets are a breakdown.
+ */
+interface SpendLedger {
+    period: string;
+    totalUSD: number;
+    buckets: Record<string, number>;
+}
+interface SpendInput {
+    window: SpendWindow;
+    amountUSD: number;
+    /** Bucket to add the amount to, on top of the total. Omit to update the total only. */
+    bucket?: string;
+    timestamp?: number;
+}
+/**
+ * Pure reducer: add `amountUSD` to the ledger for the window containing `timestamp`.
+ * A ledger from an earlier period is discarded and a fresh one started (overwrite
+ * semantics), so the persisted record stays O(1). Non-positive amounts return the
+ * ledger normalized to the current period without recording anything.
+ */
+declare function applySpend(ledger: Partial<SpendLedger> | null | undefined, input: SpendInput): SpendLedger;
+/**
+ * Spend already recorded in the window containing `timestamp` — the total, or one bucket.
+ * A missing ledger or one from another period counts as 0.
+ */
+declare function ledgerSpend(ledger: Partial<SpendLedger> | null | undefined, window: SpendWindow, timestamp?: number, bucket?: string): number;
+interface BudgetLimit {
+    window: SpendWindow;
+    /** USD ceiling for the window. `Infinity` (or any non-finite) means unlimited. */
+    limitUSD: number;
+    /** Which bucket the limit applies to; informational for the verdict, the caller passes the matching spend. */
+    bucket?: string;
+}
+interface BudgetVerdict {
+    allowed: boolean;
+    window: SpendWindow;
+    bucket?: string;
+    limitUSD: number;
+    spentUSD: number;
+    remainingUSD: number;
+    /** Epoch ms when the window rolls over and the spend counts from zero again. */
+    resetsAt: number;
+}
+/**
+ * The verdict for one limit given the spend already recorded in its window. Refuses when
+ * spent >= limit (a subject exactly at the cap gets no more calls). Pure: no I/O, no throw.
+ */
+declare function evaluateBudget(spentUSD: number, limit: BudgetLimit, timestamp?: number): BudgetVerdict;
+/** The first refusing verdict, or undefined when every window still has room. */
+declare function firstRefusal(verdicts: BudgetVerdict[]): BudgetVerdict | undefined;
+/**
+ * Thrown when a budget refuses a call. Not a `ModelError`: nothing was sent to a provider
+ * and nothing is retryable until `verdict.resetsAt`. Apps typically subclass it to attach
+ * user-facing copy, or map it to their own error at the boundary.
+ */
+declare class BudgetExceededError extends Error {
+    readonly verdict: BudgetVerdict;
+    readonly subject?: string;
+    constructor(verdict: BudgetVerdict, subject?: string, message?: string);
+    static describe(v: BudgetVerdict): string;
+}
+declare function isBudgetExceededError(err: unknown): err is BudgetExceededError;
+type SpendLedgers = Partial<Record<SpendWindow, SpendLedger>>;
+/**
+ * Persistence for per-subject ledgers. `update` must apply `fn` to the current ledgers
+ * and persist the result atomically for that subject (a transaction, a lock, a
+ * single-threaded map — whatever the backend offers). If `fn` throws, nothing is written.
+ */
+interface SpendStore {
+    read(subject: string): Promise<SpendLedgers>;
+    update(subject: string, fn: (current: SpendLedgers) => SpendLedgers): Promise<SpendLedgers>;
+}
+/** Process-local store: fine for tests, CLIs and single-instance jobs. */
+declare class InMemorySpendStore implements SpendStore {
+    private readonly ledgers;
+    read(subject: string): Promise<SpendLedgers>;
+    update(subject: string, fn: (current: SpendLedgers) => SpendLedgers): Promise<SpendLedgers>;
+}
+interface BudgetControllerOptions {
+    limits: BudgetLimit[];
+    /** Bucket every recorded spend is also added to (e.g. the subject's tier). */
+    bucket?: string;
+    clock?: () => number;
+}
+/**
+ * Check-before, record-after budget control for one set of limits.
+ *
+ * `assertWithinBudget` is the cheap pre-call guard; `record` re-evaluates inside the
+ * store's atomic update so concurrent callers cannot all slip past a nearly-exhausted
+ * budget. The overrun that remains is bounded by the calls already in flight when the
+ * cap is crossed — state that bound, do not claim the cap is exact.
+ */
+declare class BudgetController {
+    private readonly store;
+    private readonly limits;
+    private readonly bucket?;
+    private readonly clock;
+    constructor(store: SpendStore, options: BudgetControllerOptions);
+    private verdicts;
+    check(subject: string): Promise<BudgetVerdict[]>;
+    assertWithinBudget(subject: string): Promise<void>;
+    /**
+     * Record `amountUSD` against every limited window. Re-checks the limits on the
+     * ledgers as they are at write time and throws `BudgetExceededError` (writing
+     * nothing) if any window is already exhausted.
+     */
+    record(subject: string, amountUSD: number): Promise<SpendLedgers>;
+}
+
+/**
+ * Runs before every ask on every LLM agent, with the agent about to call the provider.
+ * Throw to refuse the call (nothing is sent). The intended use is budget control: a host
+ * installs one hook that reads `agent.userId` and asserts the subject's spend budget, so
+ * no call site can forget the check. Async hooks are awaited.
+ */
+type BeforeAskHook = (agent: AbstractAgent) => void | Promise<void>;
+/** Install (or clear, with no argument) the process-wide pre-ask hook. Call once at startup. */
+declare function setBeforeAskHook(hook?: BeforeAskHook): void;
 declare abstract class AbstractAgent {
     name: string;
     gameId?: string;
@@ -1433,4 +1582,4 @@ declare class MiniMaxAgent extends AbstractAgent {
     doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
 }
 
-export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, ZodSchemaConverter, buildGoogleTtsPrompt, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };
+export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, type BeforeAskHook, BotResponseError, BudgetController, type BudgetControllerOptions, BudgetExceededError, type BudgetLimit, type BudgetVerdict, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, InMemorySpendStore, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, type SpendInput, type SpendKind, type SpendLedger, type SpendLedgers, type SpendStore, type SpendWindow, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, ZodSchemaConverter, applySpend, buildGoogleTtsPrompt, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.d.ts

@@ -1019,6 +1019,155 @@ declare const GEMINI_AUDIO_TOKENS_PER_SECOND = 25;
  */
 declare function transcribeWithGemini(audioBuffer: ArrayBuffer, apiKey: string, options?: GoogleSttOptions): Promise<GoogleSttResult>;
 
+/**
+ * Budget control for agent spend — pure and storage-agnostic.
+ *
+ * The problem this solves: an app that runs LLM/voice/image calls on its own keys needs
+ * to bound what one subject (a user, a tenant, a job) can spend per UTC day or month, and
+ * needs the check to be cheap enough to run before EVERY call. The pieces:
+ *
+ * - `periodKey` / `periodEnd`: UTC window keys (`YYYY-MM-DD`, `YYYY-MM`) and reset times.
+ * - `SpendLedger` + `applySpend`: an O(1) rolling ledger for one window. It is overwritten,
+ *   not appended, when the period changes, so the persisted record never grows; history
+ *   belongs in your per-request stats, not here.
+ * - `evaluateBudget`: the verdict. Pure, no I/O, no throwing.
+ * - `BudgetExceededError`: what to throw when a verdict refuses, carrying the verdict so
+ *   the caller can render "come back at <resetsAt>" instead of treating it as a provider
+ *   failure.
+ * - `BudgetController` over a `SpendStore`: batteries-included wrapper for projects that
+ *   do not need to fold the ledger into their own database transaction. Apps that do
+ *   (the werewolf app charges the user, updates the game and writes a stats row in one
+ *   Firestore transaction) use the pure functions directly inside that transaction.
+ *
+ * Amounts are USD, rounded to 6 decimals like the rest of the cost accounting.
+ */
+type SpendWindow = 'day' | 'month';
+/** Where the money went; free-form beyond the common kinds so apps can add their own. */
+type SpendKind = 'llm' | 'image' | 'tts' | 'stt' | (string & {});
+/** UTC key for the window containing `timestamp`: `2026-09-11` for a day, `2026-09` for a month. */
+declare function periodKey(timestamp: number, window: SpendWindow): string;
+/** First millisecond of the window after the one containing `timestamp` — i.e. when the budget resets. */
+declare function periodEnd(timestamp: number, window: SpendWindow): number;
+/**
+ * Spend recorded for ONE window. `buckets` split the total by whatever the app cares
+ * about (tier, model family, feature); the total is authoritative, buckets are a breakdown.
+ */
+interface SpendLedger {
+    period: string;
+    totalUSD: number;
+    buckets: Record<string, number>;
+}
+interface SpendInput {
+    window: SpendWindow;
+    amountUSD: number;
+    /** Bucket to add the amount to, on top of the total. Omit to update the total only. */
+    bucket?: string;
+    timestamp?: number;
+}
+/**
+ * Pure reducer: add `amountUSD` to the ledger for the window containing `timestamp`.
+ * A ledger from an earlier period is discarded and a fresh one started (overwrite
+ * semantics), so the persisted record stays O(1). Non-positive amounts return the
+ * ledger normalized to the current period without recording anything.
+ */
+declare function applySpend(ledger: Partial<SpendLedger> | null | undefined, input: SpendInput): SpendLedger;
+/**
+ * Spend already recorded in the window containing `timestamp` — the total, or one bucket.
+ * A missing ledger or one from another period counts as 0.
+ */
+declare function ledgerSpend(ledger: Partial<SpendLedger> | null | undefined, window: SpendWindow, timestamp?: number, bucket?: string): number;
+interface BudgetLimit {
+    window: SpendWindow;
+    /** USD ceiling for the window. `Infinity` (or any non-finite) means unlimited. */
+    limitUSD: number;
+    /** Which bucket the limit applies to; informational for the verdict, the caller passes the matching spend. */
+    bucket?: string;
+}
+interface BudgetVerdict {
+    allowed: boolean;
+    window: SpendWindow;
+    bucket?: string;
+    limitUSD: number;
+    spentUSD: number;
+    remainingUSD: number;
+    /** Epoch ms when the window rolls over and the spend counts from zero again. */
+    resetsAt: number;
+}
+/**
+ * The verdict for one limit given the spend already recorded in its window. Refuses when
+ * spent >= limit (a subject exactly at the cap gets no more calls). Pure: no I/O, no throw.
+ */
+declare function evaluateBudget(spentUSD: number, limit: BudgetLimit, timestamp?: number): BudgetVerdict;
+/** The first refusing verdict, or undefined when every window still has room. */
+declare function firstRefusal(verdicts: BudgetVerdict[]): BudgetVerdict | undefined;
+/**
+ * Thrown when a budget refuses a call. Not a `ModelError`: nothing was sent to a provider
+ * and nothing is retryable until `verdict.resetsAt`. Apps typically subclass it to attach
+ * user-facing copy, or map it to their own error at the boundary.
+ */
+declare class BudgetExceededError extends Error {
+    readonly verdict: BudgetVerdict;
+    readonly subject?: string;
+    constructor(verdict: BudgetVerdict, subject?: string, message?: string);
+    static describe(v: BudgetVerdict): string;
+}
+declare function isBudgetExceededError(err: unknown): err is BudgetExceededError;
+type SpendLedgers = Partial<Record<SpendWindow, SpendLedger>>;
+/**
+ * Persistence for per-subject ledgers. `update` must apply `fn` to the current ledgers
+ * and persist the result atomically for that subject (a transaction, a lock, a
+ * single-threaded map — whatever the backend offers). If `fn` throws, nothing is written.
+ */
+interface SpendStore {
+    read(subject: string): Promise<SpendLedgers>;
+    update(subject: string, fn: (current: SpendLedgers) => SpendLedgers): Promise<SpendLedgers>;
+}
+/** Process-local store: fine for tests, CLIs and single-instance jobs. */
+declare class InMemorySpendStore implements SpendStore {
+    private readonly ledgers;
+    read(subject: string): Promise<SpendLedgers>;
+    update(subject: string, fn: (current: SpendLedgers) => SpendLedgers): Promise<SpendLedgers>;
+}
+interface BudgetControllerOptions {
+    limits: BudgetLimit[];
+    /** Bucket every recorded spend is also added to (e.g. the subject's tier). */
+    bucket?: string;
+    clock?: () => number;
+}
+/**
+ * Check-before, record-after budget control for one set of limits.
+ *
+ * `assertWithinBudget` is the cheap pre-call guard; `record` re-evaluates inside the
+ * store's atomic update so concurrent callers cannot all slip past a nearly-exhausted
+ * budget. The overrun that remains is bounded by the calls already in flight when the
+ * cap is crossed — state that bound, do not claim the cap is exact.
+ */
+declare class BudgetController {
+    private readonly store;
+    private readonly limits;
+    private readonly bucket?;
+    private readonly clock;
+    constructor(store: SpendStore, options: BudgetControllerOptions);
+    private verdicts;
+    check(subject: string): Promise<BudgetVerdict[]>;
+    assertWithinBudget(subject: string): Promise<void>;
+    /**
+     * Record `amountUSD` against every limited window. Re-checks the limits on the
+     * ledgers as they are at write time and throws `BudgetExceededError` (writing
+     * nothing) if any window is already exhausted.
+     */
+    record(subject: string, amountUSD: number): Promise<SpendLedgers>;
+}
+
+/**
+ * Runs before every ask on every LLM agent, with the agent about to call the provider.
+ * Throw to refuse the call (nothing is sent). The intended use is budget control: a host
+ * installs one hook that reads `agent.userId` and asserts the subject's spend budget, so
+ * no call site can forget the check. Async hooks are awaited.
+ */
+type BeforeAskHook = (agent: AbstractAgent) => void | Promise<void>;
+/** Install (or clear, with no argument) the process-wide pre-ask hook. Call once at startup. */
+declare function setBeforeAskHook(hook?: BeforeAskHook): void;
 declare abstract class AbstractAgent {
     name: string;
     gameId?: string;
@@ -1433,4 +1582,4 @@ declare class MiniMaxAgent extends AbstractAgent {
     doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
 }
 
-export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, ZodSchemaConverter, buildGoogleTtsPrompt, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };
+export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, type BeforeAskHook, BotResponseError, BudgetController, type BudgetControllerOptions, BudgetExceededError, type BudgetLimit, type BudgetVerdict, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_AUDIO_TOKENS_PER_SECOND, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleSttOptions, type GoogleSttResult, type GoogleTokenUsage, type GoogleTtsAudioOptions, type GoogleTtsResult, GoogleVoiceAgent, Gpt5Agent, GrokAgent, type GrokTokenUsage, InMemorySpendStore, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, type SpendInput, type SpendKind, type SpendLedger, type SpendLedgers, type SpendStore, type SpendWindow, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, ZodSchemaConverter, applySpend, buildGoogleTtsPrompt, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };