@hiper2d/ai-agents 0.18.0 → 0.19.0

package/dist/index.d.mts

@@ -293,6 +293,17 @@ declare class ModelInvalidResponseError extends ModelError {
  *              Google's non-configurable filter — no safetySettings change lifts it.
  *              `reason` = the blockReason or finishReason string.
  */
+/**
+ * The provider did not answer within the agent's `requestTimeoutMs`. The ask gives up
+ * instead of hanging until the host's serverless function is killed, which leaves no log
+ * line and no error for the player to retry from. Observed 2026-10-01: `deepseek-flash`
+ * accepted requests and never answered (no tokens, even streaming) while `deepseek-v4-pro`
+ * on the same key answered in 0.5s. Retryable — usually on another model.
+ */
+declare class ModelTimeoutError extends ModelError {
+    timeoutMs: number;
+    constructor(modelType: string, timeoutMs: number);
+}
 declare class ModelRefusalError extends ModelError {
     reason?: string;
     constructor(modelType: string, message?: string, reason?: string);
@@ -364,6 +375,7 @@ declare const LLM_CONSTANTS: {
     GEMINI_PRO: string;
     GEMINI_FLASH: string;
     GEMINI_LITE: string;
+    MISTRAL_LARGE: string;
     MISTRAL_MEDIUM: string;
     MISTRAL_SMALL: string;
     GROK: string;
@@ -388,6 +400,13 @@ declare const LLM_CONSTANTS: {
  * runaway one. Reasoning effort and thinking budgets are the knobs that change spend.
  */
 declare const DEFAULT_MAX_OUTPUT_TOKENS = 8192;
+/**
+ * Wall-clock limit on one ask, retries inside the provider SDK included. Past it the ask
+ * throws ModelTimeoutError. Measured 2026-10-01 over 7k production calls (14 days): 0.5%
+ * ran past 60s — mostly Grok turns and story generation. Callers that legitimately need
+ * longer raise `requestTimeoutMs` on the instance, like maxOutputTokens.
+ */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
 type ModelTag = 'very-fast' | 'fast' | 'slow' | 'very-slow' | 'extremely-slow' | 'cheap' | 'expensive';
 type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 /**
@@ -1286,6 +1305,12 @@ declare abstract class AbstractAgent {
      */
     reasoningEffort?: ReasoningEffort;
     thinkingBudgetTokens?: number;
+    /**
+     * Wall-clock limit on one ask (DEFAULT_REQUEST_TIMEOUT_MS). Past it the ask throws
+     * ModelTimeoutError; the provider request is abandoned, not cancelled. Raise it per
+     * instance for calls that legitimately run long, like maxOutputTokens.
+     */
+    requestTimeoutMs: number;
     protected readonly instruction: string;
     /**
      * The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
@@ -1306,6 +1331,11 @@ declare abstract class AbstractAgent {
      */
     askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
     askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    /**
+     * Races the provider call against requestTimeoutMs. A hung provider (accepts the request,
+     * never answers) otherwise runs until the host kills the function with no error to show.
+     */
+    private withTimeout;
     private stampDuration;
     /** Failed calls carry their duration too — a 35s provider stall that errors is still signal. */
     private stampErrorDuration;
@@ -1804,4 +1834,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, 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, KIMI_REASONING_EFFORTS, KimiAgent, type KimiReasoningEffort, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, META_REASONING_EFFORTS, MISTRAL_REASONING_EFFORTS, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, MiniMaxAgent, MistralAgent, type MistralReasoningEffort, 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, XAI_REASONING_EFFORTS, type XaiReasoningEffort, ZodSchemaConverter, applySpend, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, describeEmptyTtsResponse, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$6 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$4 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$5 as extractKimiTokenUsageFromResponse, extractMetaTokenUsage, extractTokenUsageFromResponse$3 as extractMetaTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$7 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isSafetyBlocked, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, normalizeTtsStyle, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toKimiEffort, toMetaEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, 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, DEFAULT_REQUEST_TIMEOUT_MS, 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, KIMI_REASONING_EFFORTS, KimiAgent, type KimiReasoningEffort, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, META_REASONING_EFFORTS, MISTRAL_REASONING_EFFORTS, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, MiniMaxAgent, MistralAgent, type MistralReasoningEffort, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelTimeoutError, 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, XAI_REASONING_EFFORTS, type XaiReasoningEffort, ZodSchemaConverter, applySpend, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, describeEmptyTtsResponse, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$6 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$4 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$5 as extractKimiTokenUsageFromResponse, extractMetaTokenUsage, extractTokenUsageFromResponse$3 as extractMetaTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$7 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isSafetyBlocked, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, normalizeTtsStyle, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toKimiEffort, toMetaEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.d.ts

@@ -293,6 +293,17 @@ declare class ModelInvalidResponseError extends ModelError {
  *              Google's non-configurable filter — no safetySettings change lifts it.
  *              `reason` = the blockReason or finishReason string.
  */
+/**
+ * The provider did not answer within the agent's `requestTimeoutMs`. The ask gives up
+ * instead of hanging until the host's serverless function is killed, which leaves no log
+ * line and no error for the player to retry from. Observed 2026-10-01: `deepseek-flash`
+ * accepted requests and never answered (no tokens, even streaming) while `deepseek-v4-pro`
+ * on the same key answered in 0.5s. Retryable — usually on another model.
+ */
+declare class ModelTimeoutError extends ModelError {
+    timeoutMs: number;
+    constructor(modelType: string, timeoutMs: number);
+}
 declare class ModelRefusalError extends ModelError {
     reason?: string;
     constructor(modelType: string, message?: string, reason?: string);
@@ -364,6 +375,7 @@ declare const LLM_CONSTANTS: {
     GEMINI_PRO: string;
     GEMINI_FLASH: string;
     GEMINI_LITE: string;
+    MISTRAL_LARGE: string;
     MISTRAL_MEDIUM: string;
     MISTRAL_SMALL: string;
     GROK: string;
@@ -388,6 +400,13 @@ declare const LLM_CONSTANTS: {
  * runaway one. Reasoning effort and thinking budgets are the knobs that change spend.
  */
 declare const DEFAULT_MAX_OUTPUT_TOKENS = 8192;
+/**
+ * Wall-clock limit on one ask, retries inside the provider SDK included. Past it the ask
+ * throws ModelTimeoutError. Measured 2026-10-01 over 7k production calls (14 days): 0.5%
+ * ran past 60s — mostly Grok turns and story generation. Callers that legitimately need
+ * longer raise `requestTimeoutMs` on the instance, like maxOutputTokens.
+ */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
 type ModelTag = 'very-fast' | 'fast' | 'slow' | 'very-slow' | 'extremely-slow' | 'cheap' | 'expensive';
 type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 /**
@@ -1286,6 +1305,12 @@ declare abstract class AbstractAgent {
      */
     reasoningEffort?: ReasoningEffort;
     thinkingBudgetTokens?: number;
+    /**
+     * Wall-clock limit on one ask (DEFAULT_REQUEST_TIMEOUT_MS). Past it the ask throws
+     * ModelTimeoutError; the provider request is abandoned, not cancelled. Raise it per
+     * instance for calls that legitimately run long, like maxOutputTokens.
+     */
+    requestTimeoutMs: number;
     protected readonly instruction: string;
     /**
      * The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
@@ -1306,6 +1331,11 @@ declare abstract class AbstractAgent {
      */
     askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
     askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    /**
+     * Races the provider call against requestTimeoutMs. A hung provider (accepts the request,
+     * never answers) otherwise runs until the host kills the function with no error to show.
+     */
+    private withTimeout;
     private stampDuration;
     /** Failed calls carry their duration too — a 35s provider stall that errors is still signal. */
     private stampErrorDuration;
@@ -1804,4 +1834,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, 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, KIMI_REASONING_EFFORTS, KimiAgent, type KimiReasoningEffort, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, META_REASONING_EFFORTS, MISTRAL_REASONING_EFFORTS, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, MiniMaxAgent, MistralAgent, type MistralReasoningEffort, 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, XAI_REASONING_EFFORTS, type XaiReasoningEffort, ZodSchemaConverter, applySpend, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, describeEmptyTtsResponse, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$6 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$4 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$5 as extractKimiTokenUsageFromResponse, extractMetaTokenUsage, extractTokenUsageFromResponse$3 as extractMetaTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$7 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isSafetyBlocked, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, normalizeTtsStyle, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toKimiEffort, toMetaEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, 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, DEFAULT_REQUEST_TIMEOUT_MS, 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, KIMI_REASONING_EFFORTS, KimiAgent, type KimiReasoningEffort, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, META_REASONING_EFFORTS, MISTRAL_REASONING_EFFORTS, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, MiniMaxAgent, MistralAgent, type MistralReasoningEffort, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelTimeoutError, 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, XAI_REASONING_EFFORTS, type XaiReasoningEffort, ZodSchemaConverter, applySpend, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, describeEmptyTtsResponse, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$6 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$4 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$5 as extractKimiTokenUsageFromResponse, extractMetaTokenUsage, extractTokenUsageFromResponse$3 as extractMetaTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$7 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isSafetyBlocked, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, normalizeTtsStyle, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toKimiEffort, toMetaEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.js

@@ -43,6 +43,7 @@ __export(src_exports, {
   DEEPSEEK_REASONING_EFFORTS: () => DEEPSEEK_REASONING_EFFORTS,
   DEFAULT_LOGGING_CONFIG: () => DEFAULT_LOGGING_CONFIG,
   DEFAULT_MAX_OUTPUT_TOKENS: () => DEFAULT_MAX_OUTPUT_TOKENS,
+  DEFAULT_REQUEST_TIMEOUT_MS: () => DEFAULT_REQUEST_TIMEOUT_MS,
   DeepSeekV2Agent: () => DeepSeekV2Agent,
   FUGU_REASONING_EFFORTS: () => FUGU_REASONING_EFFORTS,
   FuguAgent: () => FuguAgent,
@@ -72,6 +73,7 @@ __export(src_exports, {
   ModelQuotaExceededError: () => ModelQuotaExceededError,
   ModelRateLimitError: () => ModelRateLimitError,
   ModelRefusalError: () => ModelRefusalError,
+  ModelTimeoutError: () => ModelTimeoutError,
   ModelUnavailableError: () => ModelUnavailableError,
   OPENAI_REASONING_EFFORTS: () => OPENAI_REASONING_EFFORTS,
   OpenAiVoiceAgent: () => OpenAiVoiceAgent,
@@ -889,6 +891,14 @@ var ModelInvalidResponseError = class extends ModelError {
     this.truncated = truncated;
   }
 };
+var ModelTimeoutError = class extends ModelError {
+  timeoutMs;
+  constructor(modelType, timeoutMs) {
+    super(`${modelType} did not respond within ${Math.round(timeoutMs / 1e3)}s`, modelType);
+    this.name = "ModelTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
 var ModelRefusalError = class extends ModelError {
   reason;
   constructor(modelType, message = `${modelType} refused to answer (stop_reason: refusal)`, reason) {
@@ -974,6 +984,9 @@ var LLM_CONSTANTS = {
   GEMINI_PRO: "gemini-pro",
   GEMINI_FLASH: "gemini-flash",
   GEMINI_LITE: "gemini-lite",
+  // Reused 2026-10-06 for Mistral Large 4: the old id (Large 3) was retired 2026-09-18 and
+  // consumers had mapped it away, so the version-free id was free again.
+  MISTRAL_LARGE: "mistral-large",
   MISTRAL_MEDIUM: "mistral-medium",
   MISTRAL_SMALL: "mistral-small",
   GROK: "grok",
@@ -992,6 +1005,7 @@ var LLM_CONSTANTS = {
   MUSE_SPARK: "muse-spark"
 };
 var DEFAULT_MAX_OUTPUT_TOKENS = 8192;
+var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
 var SupportedAiModels = {
   // Claude Fable 5.1 (2026-09-02, was Fable 5) - frontier reasoning model. Thinking is always on (no non-thinking variant).
   [LLM_CONSTANTS.CLAUDE_FABLE]: {
@@ -1180,6 +1194,21 @@ var SupportedAiModels = {
   // returns `mistral-medium-3-5`, `mistral-medium-3`, `mistral-medium-latest` and
   // `magistral-medium-latest` as one entry — so Magistral seats had silently become Medium
   // seats already. Consumers map both retired ids onto the surviving pair.
+  //
+  // Mistral Large 4 added 2026-10-06 under the freed `mistral-large` picker id. The model list
+  // reports reasoning: true (Large 3 said false), 512K context; same reasoning_effort switch,
+  // but only 'high' and 'none' are accepted (medium/low are a 400). Live 2026-10-06 at high:
+  // a chat-turn schema ask took 14-21s with 1.3-2k output tokens (~$0.003), one constrained
+  // pick took 49s — it thinks long, so it is cheap but slow.
+  [LLM_CONSTANTS.MISTRAL_LARGE]: {
+    displayName: "Mistral Large 4",
+    // `mistral-large-4-0` is the same entry; `mistral-large-latest` still points at Large 3.
+    modelApiName: "mistral-large-4",
+    apiKeyName: API_KEY_CONSTANTS.MISTRAL,
+    hasThinking: true,
+    reasoningEffort: "high",
+    tags: ["slow", "cheap"]
+  },
   [LLM_CONSTANTS.MISTRAL_MEDIUM]: {
     displayName: "Mistral Medium 3.5",
     // The docs' explicit 3.5 id. It was `mistral-medium-3` until 2026-09-18, which Mistral
@@ -1569,7 +1598,13 @@ var MODEL_PRICING = {
   // Mistral models (mistral.ai/pricing/api, verified 2026-09-18). Cached tokens bill at 10% of
   // the input price (documented on the prompt_cache_key param; no per-model cached prices
   // published). Reasoning tokens are counted inside completion_tokens — no separate
-  // reasoning_tokens field — so the output rate already covers the trace.
+  // reasoning_tokens field — so the output rate already covers the trace. Large 4 added
+  // 2026-10-06 at its published rates ($0.07 cached, not an exact 10%).
+  [SupportedAiModels[LLM_CONSTANTS.MISTRAL_LARGE].modelApiName]: {
+    inputPrice: 0.68,
+    outputPrice: 2.09,
+    cacheHitPrice: 0.07
+  },
   [SupportedAiModels[LLM_CONSTANTS.MISTRAL_MEDIUM].modelApiName]: {
     inputPrice: 1.5,
     outputPrice: 7.5,
@@ -1667,6 +1702,7 @@ var HYBRID_THINKING_API_NAMES = /* @__PURE__ */ new Set([
   SupportedAiModels[LLM_CONSTANTS.MINIMAX].modelApiName,
   // Mistral reasons only when asked (`reasoning_effort`), and we always ask — hybrid by the
   // same definition as Qwen. Added 2026-09-18 when the two entries went thinking-on.
+  SupportedAiModels[LLM_CONSTANTS.MISTRAL_LARGE].modelApiName,
   SupportedAiModels[LLM_CONSTANTS.MISTRAL_MEDIUM].modelApiName,
   SupportedAiModels[LLM_CONSTANTS.MISTRAL_SMALL].modelApiName
 ]);
@@ -2403,6 +2439,12 @@ var AbstractAgent = class {
    */
   reasoningEffort;
   thinkingBudgetTokens;
+  /**
+   * Wall-clock limit on one ask (DEFAULT_REQUEST_TIMEOUT_MS). Past it the ask throws
+   * ModelTimeoutError; the provider request is abandoned, not cancelled. Raise it per
+   * instance for calls that legitimately run long, like maxOutputTokens.
+   */
+  requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS;
   instruction;
   /**
    * The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
@@ -2437,7 +2479,7 @@ var AbstractAgent = class {
     if (beforeAskHook) await beforeAskHook(this);
     const startedAt = Date.now();
     try {
-      const [result, thinking, usage, signature] = await this.doAskWithZodSchema(zodSchema, messages);
+      const [result, thinking, usage, signature] = await this.withTimeout(this.doAskWithZodSchema(zodSchema, messages));
       return [result, thinking, this.stampDuration(usage, startedAt), signature];
     } catch (error) {
       this.stampErrorDuration(error, startedAt);
@@ -2448,13 +2490,25 @@ var AbstractAgent = class {
     if (beforeAskHook) await beforeAskHook(this);
     const startedAt = Date.now();
     try {
-      const [content, thinking, usage, signature] = await this.doAskText(messages);
+      const [content, thinking, usage, signature] = await this.withTimeout(this.doAskText(messages));
       return [content, thinking, this.stampDuration(usage, startedAt), signature];
     } catch (error) {
       this.stampErrorDuration(error, startedAt);
       throw error;
     }
   }
+  /**
+   * Races the provider call against requestTimeoutMs. A hung provider (accepts the request,
+   * never answers) otherwise runs until the host kills the function with no error to show.
+   */
+  withTimeout(call) {
+    const timeoutMs = this.requestTimeoutMs;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new ModelTimeoutError(this.model, timeoutMs)), timeoutMs);
+    });
+    return Promise.race([call, timeout]).finally(() => clearTimeout(timer));
+  }
   stampDuration(usage, startedAt) {
     return usage ? { ...usage, durationMs: Date.now() - startedAt } : usage;
   }
@@ -5470,6 +5524,7 @@ var AgentFactory = class {
       case LLM_CONSTANTS.DEEPSEEK_PRO:
         return new DeepSeekV2Agent(name, instruction, model.modelApiName, key, model.temperature ?? 0, shouldEnableThinking);
       // Mistral models
+      case LLM_CONSTANTS.MISTRAL_LARGE:
       case LLM_CONSTANTS.MISTRAL_MEDIUM:
       case LLM_CONSTANTS.MISTRAL_SMALL:
         return new MistralAgent(name, instruction, model.modelApiName, key, shouldEnableThinking);
@@ -5520,6 +5575,7 @@ var AgentFactory = class {
   DEEPSEEK_REASONING_EFFORTS,
   DEFAULT_LOGGING_CONFIG,
   DEFAULT_MAX_OUTPUT_TOKENS,
+  DEFAULT_REQUEST_TIMEOUT_MS,
   DeepSeekV2Agent,
   FUGU_REASONING_EFFORTS,
   FuguAgent,
@@ -5549,6 +5605,7 @@ var AgentFactory = class {
   ModelQuotaExceededError,
   ModelRateLimitError,
   ModelRefusalError,
+  ModelTimeoutError,
   ModelUnavailableError,
   OPENAI_REASONING_EFFORTS,
   OpenAiVoiceAgent,