@hiper2d/ai-agents 0.2.1 → 0.3.0

package/README.md

@@ -74,6 +74,28 @@ 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.
+
 ### Logging
 
 The library logs through an injectable sink — `setLlmLogger(fn)` — so a host app can route

package/dist/index.d.mts

@@ -1019,6 +1019,146 @@ 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>;
+}
+
 declare abstract class AbstractAgent {
     name: string;
     gameId?: string;
@@ -1433,4 +1573,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, 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, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.d.ts

@@ -1019,6 +1019,146 @@ 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>;
+}
+
 declare abstract class AbstractAgent {
     name: string;
     gameId?: string;
@@ -1433,4 +1573,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, 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, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.js

@@ -35,6 +35,8 @@ __export(index_exports, {
   AbstractAgent: () => AbstractAgent,
   AgentFactory: () => AgentFactory,
   BotResponseError: () => BotResponseError,
+  BudgetController: () => BudgetController,
+  BudgetExceededError: () => BudgetExceededError,
   CACHE_TIER_MARKER: () => CACHE_TIER_MARKER,
   ClaudeAgent: () => ClaudeAgent,
   DEEPSEEK_PEAK_SCHEDULE: () => DEEPSEEK_PEAK_SCHEDULE,
@@ -52,6 +54,7 @@ __export(index_exports, {
   GoogleVoiceAgent: () => GoogleVoiceAgent,
   Gpt5Agent: () => Gpt5Agent,
   GrokAgent: () => GrokAgent,
+  InMemorySpendStore: () => InMemorySpendStore,
   KimiAgent: () => KimiAgent,
   LLM_CONSTANTS: () => LLM_CONSTANTS,
   MESSAGE_ROLE: () => MESSAGE_ROLE,
@@ -78,6 +81,7 @@ __export(index_exports, {
   VOICE_PROVIDER_API_KEY: () => VOICE_PROVIDER_API_KEY,
   VoiceAgentFactory: () => VoiceAgentFactory,
   ZodSchemaConverter: () => ZodSchemaConverter,
+  applySpend: () => applySpend,
   buildGoogleTtsPrompt: () => buildGoogleTtsPrompt,
   calculateAnthropicCost: () => calculateAnthropicCost,
   calculateCost: () => calculateCost,
@@ -96,6 +100,7 @@ __export(index_exports, {
   cleanResponse: () => cleanResponse,
   createCatalog: () => createCatalog,
   createVoiceAgent: () => createVoiceAgent,
+  evaluateBudget: () => evaluateBudget,
   extractAnthropicTokenUsage: () => extractAnthropicTokenUsage,
   extractAnthropicTokenUsageFromResponse: () => extractTokenUsageFromResponse5,
   extractDeepSeekTokenUsage: () => extractDeepSeekTokenUsage,
@@ -113,6 +118,7 @@ __export(index_exports, {
   extractOpenAITokenUsageFromResponse: () => extractTokenUsageFromResponse,
   extractTokenUsage: () => extractTokenUsage,
   extractUsageAndCalculateCost: () => extractUsageAndCalculateCost,
+  firstRefusal: () => firstRefusal,
   generateGoogleTtsAudio: () => generateGoogleTtsAudio,
   generateOpenAiTtsAudio: () => generateOpenAiTtsAudio,
   generateSchemaInstructions: () => generateSchemaInstructions,
@@ -121,10 +127,12 @@ __export(index_exports, {
   getModelProviderName: () => getModelProviderName,
   getModelTags: () => getModelTags,
   getProviderSignatureFields: () => getProviderSignatureFields,
+  isBudgetExceededError: () => isBudgetExceededError,
   isHybridThinkingModel: () => isHybridThinkingModel,
   isInPeakWindow: () => isInPeakWindow,
   isPeakBilling: () => isPeakBilling,
   isWeekendAt: () => isWeekendAt,
+  ledgerSpend: () => ledgerSpend,
   logger: () => logger,
   mergeThinking: () => mergeThinking,
   modelHasTag: () => modelHasTag,
@@ -132,6 +140,8 @@ __export(index_exports, {
   needsPromptBasedSchema: () => needsPromptBasedSchema,
   parseAndValidateLlmJson: () => parseAndValidateLlmJson,
   pcmToWav: () => pcmToWav,
+  periodEnd: () => periodEnd,
+  periodKey: () => periodKey,
   safeValidateResponse: () => safeValidateResponse,
   setLlmLogger: () => setLlmLogger,
   stableHashHex: () => stableHashHex,
@@ -2026,6 +2036,152 @@ function createVoiceAgent(provider, apiKey) {
   return VoiceAgentFactory.createAgent(provider, apiKey);
 }
 
+// src/budget/index.ts
+function round6(n) {
+  return parseFloat((Number(n) || 0).toFixed(6));
+}
+function periodKey(timestamp, window) {
+  const d = new Date(timestamp);
+  const y = d.getUTCFullYear();
+  const m = String(d.getUTCMonth() + 1).padStart(2, "0");
+  if (window === "month") {
+    return `${y}-${m}`;
+  }
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+function periodEnd(timestamp, window) {
+  const d = new Date(timestamp);
+  if (window === "month") {
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1);
+  }
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+}
+function normalizeLedger(ledger, period) {
+  if (!ledger || ledger.period !== period) {
+    return { period, totalUSD: 0, buckets: {} };
+  }
+  const buckets = {};
+  for (const [k, v] of Object.entries(ledger.buckets ?? {})) {
+    buckets[k] = round6(v);
+  }
+  return { period, totalUSD: round6(ledger.totalUSD ?? 0), buckets };
+}
+function applySpend(ledger, input) {
+  const timestamp = input.timestamp ?? Date.now();
+  const period = periodKey(timestamp, input.window);
+  const current2 = normalizeLedger(ledger, period);
+  const amount = round6(input.amountUSD);
+  if (!(amount > 0)) {
+    return current2;
+  }
+  const buckets = { ...current2.buckets };
+  if (input.bucket) {
+    buckets[input.bucket] = round6((buckets[input.bucket] ?? 0) + amount);
+  }
+  return { period, totalUSD: round6(current2.totalUSD + amount), buckets };
+}
+function ledgerSpend(ledger, window, timestamp = Date.now(), bucket) {
+  const current2 = normalizeLedger(ledger, periodKey(timestamp, window));
+  return bucket ? current2.buckets[bucket] ?? 0 : current2.totalUSD;
+}
+function evaluateBudget(spentUSD, limit, timestamp = Date.now()) {
+  const spent = round6(spentUSD);
+  const unlimited = !Number.isFinite(limit.limitUSD);
+  const remaining = unlimited ? Number.POSITIVE_INFINITY : Math.max(0, round6(limit.limitUSD - spent));
+  return {
+    allowed: unlimited || spent < limit.limitUSD,
+    window: limit.window,
+    ...limit.bucket ? { bucket: limit.bucket } : {},
+    limitUSD: limit.limitUSD,
+    spentUSD: spent,
+    remainingUSD: remaining,
+    resetsAt: periodEnd(timestamp, limit.window)
+  };
+}
+function firstRefusal(verdicts) {
+  return verdicts.find((v) => !v.allowed);
+}
+var BudgetExceededError = class _BudgetExceededError extends Error {
+  verdict;
+  subject;
+  constructor(verdict, subject, message) {
+    super(message ?? _BudgetExceededError.describe(verdict));
+    this.name = "BudgetExceededError";
+    this.verdict = verdict;
+    this.subject = subject;
+  }
+  static describe(v) {
+    const when = v.window === "day" ? "daily" : "monthly";
+    return `${when} budget of $${v.limitUSD} exhausted ($${v.spentUSD} spent); resets at ${new Date(v.resetsAt).toISOString()}`;
+  }
+};
+function isBudgetExceededError(err) {
+  return err instanceof BudgetExceededError || typeof err === "object" && err !== null && err.name === "BudgetExceededError" && !!err.verdict;
+}
+var InMemorySpendStore = class {
+  ledgers = /* @__PURE__ */ new Map();
+  async read(subject) {
+    return { ...this.ledgers.get(subject) ?? {} };
+  }
+  async update(subject, fn) {
+    const next = fn({ ...this.ledgers.get(subject) ?? {} });
+    this.ledgers.set(subject, next);
+    return { ...next };
+  }
+};
+var BudgetController = class {
+  constructor(store, options) {
+    this.store = store;
+    this.limits = options.limits;
+    this.bucket = options.bucket;
+    this.clock = options.clock ?? (() => Date.now());
+  }
+  store;
+  limits;
+  bucket;
+  clock;
+  verdicts(ledgers, now) {
+    return this.limits.map((limit) => {
+      const spent = ledgerSpend(ledgers[limit.window], limit.window, now, limit.bucket ?? this.bucket);
+      return evaluateBudget(spent, limit, now);
+    });
+  }
+  async check(subject) {
+    return this.verdicts(await this.store.read(subject), this.clock());
+  }
+  async assertWithinBudget(subject) {
+    const refused = firstRefusal(await this.check(subject));
+    if (refused) {
+      throw new BudgetExceededError(refused, subject);
+    }
+  }
+  /**
+   * 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.
+   */
+  async record(subject, amountUSD) {
+    const now = this.clock();
+    return this.store.update(subject, (current2) => {
+      const refused = firstRefusal(this.verdicts(current2, now));
+      if (refused) {
+        throw new BudgetExceededError(refused, subject);
+      }
+      const next = { ...current2 };
+      for (const limit of this.limits) {
+        next[limit.window] = applySpend(current2[limit.window], {
+          window: limit.window,
+          amountUSD,
+          bucket: limit.bucket ?? this.bucket,
+          timestamp: now
+        });
+      }
+      return next;
+    });
+  }
+};
+
 // src/agents/abstract-agent.ts
 var AbstractAgent = class {
   name;
@@ -4755,6 +4911,8 @@ var AgentFactory = class {
   AbstractAgent,
   AgentFactory,
   BotResponseError,
+  BudgetController,
+  BudgetExceededError,
   CACHE_TIER_MARKER,
   ClaudeAgent,
   DEEPSEEK_PEAK_SCHEDULE,
@@ -4772,6 +4930,7 @@ var AgentFactory = class {
   GoogleVoiceAgent,
   Gpt5Agent,
   GrokAgent,
+  InMemorySpendStore,
   KimiAgent,
   LLM_CONSTANTS,
   MESSAGE_ROLE,
@@ -4798,6 +4957,7 @@ var AgentFactory = class {
   VOICE_PROVIDER_API_KEY,
   VoiceAgentFactory,
   ZodSchemaConverter,
+  applySpend,
   buildGoogleTtsPrompt,
   calculateAnthropicCost,
   calculateCost,
@@ -4816,6 +4976,7 @@ var AgentFactory = class {
   cleanResponse,
   createCatalog,
   createVoiceAgent,
+  evaluateBudget,
   extractAnthropicTokenUsage,
   extractAnthropicTokenUsageFromResponse,
   extractDeepSeekTokenUsage,
@@ -4833,6 +4994,7 @@ var AgentFactory = class {
   extractOpenAITokenUsageFromResponse,
   extractTokenUsage,
   extractUsageAndCalculateCost,
+  firstRefusal,
   generateGoogleTtsAudio,
   generateOpenAiTtsAudio,
   generateSchemaInstructions,
@@ -4841,10 +5003,12 @@ var AgentFactory = class {
   getModelProviderName,
   getModelTags,
   getProviderSignatureFields,
+  isBudgetExceededError,
   isHybridThinkingModel,
   isInPeakWindow,
   isPeakBilling,
   isWeekendAt,
+  ledgerSpend,
   logger,
   mergeThinking,
   modelHasTag,
@@ -4852,6 +5016,8 @@ var AgentFactory = class {
   needsPromptBasedSchema,
   parseAndValidateLlmJson,
   pcmToWav,
+  periodEnd,
+  periodKey,
   safeValidateResponse,
   setLlmLogger,
   stableHashHex,