@hiper2d/ai-agents 0.9.0 → 0.11.0

package/dist/index.d.mts

@@ -537,8 +537,11 @@ declare function getProviderSignatureFields(aiType: string, signature?: string):
  *   not on the shared scale and means "don't reason", which an agent expresses by omitting the
  *   field, so the exported slice starts at minimal. Only "high" is documented to return the
  *   thinking chunk; the intermediate levels are accepted but unverified.
- * Qwen accepts reasoning_effort but ignores it (thinking_budget is its knob); MiniMax, Kimi and
- * Grok expose no effort parameter.
+ * - xAI Grok 4.7 (docs.x.ai/developers/model-capabilities/text/reasoning, 2026-09-22):
+ *   low|medium|high|xhigh, default high, sent on the Responses API as `reasoning: {effort}`.
+ *   Chat Completions has no equivalent. Grok 4.6 and earlier had no knob at all.
+ * Qwen accepts reasoning_effort but ignores it (thinking_budget is its knob); MiniMax and Kimi
+ * expose no effort parameter.
  */
 type OpenAIReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 type AnthropicReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
@@ -548,6 +551,7 @@ type DeepSeekReasoningEffort = 'low' | 'high' | 'max';
 type FuguReasoningEffort = 'high' | 'xhigh' | 'max';
 type MetaReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 type MistralReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+type XaiReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
 /** The shared scale, lowest first. */
 declare const REASONING_EFFORT_SCALE: readonly ReasoningEffort[];
 declare const OPENAI_REASONING_EFFORTS: readonly OpenAIReasoningEffort[];
@@ -558,6 +562,7 @@ declare const DEEPSEEK_REASONING_EFFORTS: readonly DeepSeekReasoningEffort[];
 declare const FUGU_REASONING_EFFORTS: readonly FuguReasoningEffort[];
 declare const META_REASONING_EFFORTS: readonly MetaReasoningEffort[];
 declare const MISTRAL_REASONING_EFFORTS: readonly MistralReasoningEffort[];
+declare const XAI_REASONING_EFFORTS: readonly XaiReasoningEffort[];
 /** Clamps `effort` to the nearest level in `allowed` (by rank on the shared scale, ties go up). */
 declare function clampReasoningEffort<T extends ReasoningEffort>(effort: ReasoningEffort, allowed: readonly T[]): T;
 declare const toOpenAIEffort: (effort: ReasoningEffort) => OpenAIReasoningEffort;
@@ -568,6 +573,7 @@ declare const toDeepSeekEffort: (effort: ReasoningEffort) => DeepSeekReasoningEf
 declare const toMetaEffort: (effort: ReasoningEffort) => MetaReasoningEffort;
 declare const toFuguEffort: (effort: ReasoningEffort) => FuguReasoningEffort;
 declare const toMistralEffort: (effort: ReasoningEffort) => MistralReasoningEffort;
+declare const toXaiEffort: (effort: ReasoningEffort) => XaiReasoningEffort;
 
 /**
  * Unified token usage utilities for all AI providers
@@ -1535,6 +1541,14 @@ declare class GrokAgent extends AbstractAgent {
      * Reasoning extraction and token accounting are identical to askWithZodSchema.
      */
     doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    /**
+     * A stable key per (game, bot) so xAI routes this conversation's requests to the same
+     * server. Without it a request often lands on a cache-cold machine and the whole prompt
+     * bills at full input price — xAI calls this out as the most common caching mistake.
+     * Falls back to the bot name alone outside a game (story generation, tests), which is
+     * still stabler than sending nothing.
+     */
+    private get promptCacheKey();
     private createResponse;
     /**
      * Converts game history to Responses API input items. The system instruction is
@@ -1722,4 +1736,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, KimiAgent, 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, ZodSchemaConverter, applySpend, buildGoogleTtsPrompt, 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, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toMetaEffort, toMistralEffort, 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, 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, buildGoogleTtsPrompt, 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, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toMetaEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.d.ts

@@ -537,8 +537,11 @@ declare function getProviderSignatureFields(aiType: string, signature?: string):
  *   not on the shared scale and means "don't reason", which an agent expresses by omitting the
  *   field, so the exported slice starts at minimal. Only "high" is documented to return the
  *   thinking chunk; the intermediate levels are accepted but unverified.
- * Qwen accepts reasoning_effort but ignores it (thinking_budget is its knob); MiniMax, Kimi and
- * Grok expose no effort parameter.
+ * - xAI Grok 4.7 (docs.x.ai/developers/model-capabilities/text/reasoning, 2026-09-22):
+ *   low|medium|high|xhigh, default high, sent on the Responses API as `reasoning: {effort}`.
+ *   Chat Completions has no equivalent. Grok 4.6 and earlier had no knob at all.
+ * Qwen accepts reasoning_effort but ignores it (thinking_budget is its knob); MiniMax and Kimi
+ * expose no effort parameter.
  */
 type OpenAIReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 type AnthropicReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
@@ -548,6 +551,7 @@ type DeepSeekReasoningEffort = 'low' | 'high' | 'max';
 type FuguReasoningEffort = 'high' | 'xhigh' | 'max';
 type MetaReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 type MistralReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+type XaiReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
 /** The shared scale, lowest first. */
 declare const REASONING_EFFORT_SCALE: readonly ReasoningEffort[];
 declare const OPENAI_REASONING_EFFORTS: readonly OpenAIReasoningEffort[];
@@ -558,6 +562,7 @@ declare const DEEPSEEK_REASONING_EFFORTS: readonly DeepSeekReasoningEffort[];
 declare const FUGU_REASONING_EFFORTS: readonly FuguReasoningEffort[];
 declare const META_REASONING_EFFORTS: readonly MetaReasoningEffort[];
 declare const MISTRAL_REASONING_EFFORTS: readonly MistralReasoningEffort[];
+declare const XAI_REASONING_EFFORTS: readonly XaiReasoningEffort[];
 /** Clamps `effort` to the nearest level in `allowed` (by rank on the shared scale, ties go up). */
 declare function clampReasoningEffort<T extends ReasoningEffort>(effort: ReasoningEffort, allowed: readonly T[]): T;
 declare const toOpenAIEffort: (effort: ReasoningEffort) => OpenAIReasoningEffort;
@@ -568,6 +573,7 @@ declare const toDeepSeekEffort: (effort: ReasoningEffort) => DeepSeekReasoningEf
 declare const toMetaEffort: (effort: ReasoningEffort) => MetaReasoningEffort;
 declare const toFuguEffort: (effort: ReasoningEffort) => FuguReasoningEffort;
 declare const toMistralEffort: (effort: ReasoningEffort) => MistralReasoningEffort;
+declare const toXaiEffort: (effort: ReasoningEffort) => XaiReasoningEffort;
 
 /**
  * Unified token usage utilities for all AI providers
@@ -1535,6 +1541,14 @@ declare class GrokAgent extends AbstractAgent {
      * Reasoning extraction and token accounting are identical to askWithZodSchema.
      */
     doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    /**
+     * A stable key per (game, bot) so xAI routes this conversation's requests to the same
+     * server. Without it a request often lands on a cache-cold machine and the whole prompt
+     * bills at full input price — xAI calls this out as the most common caching mistake.
+     * Falls back to the bot name alone outside a game (story generation, tests), which is
+     * still stabler than sending nothing.
+     */
+    private get promptCacheKey();
     private createResponse;
     /**
      * Converts game history to Responses API input items. The system instruction is
@@ -1722,4 +1736,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, KimiAgent, 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, ZodSchemaConverter, applySpend, buildGoogleTtsPrompt, 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, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toMetaEffort, toMistralEffort, 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, 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, buildGoogleTtsPrompt, 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, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toMetaEffort, toMistralEffort, toOpenAIEffort, toXaiEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.js

@@ -83,6 +83,7 @@ __export(src_exports, {
   VOICE_MODEL_PRICING: () => VOICE_MODEL_PRICING,
   VOICE_PROVIDER_API_KEY: () => VOICE_PROVIDER_API_KEY,
   VoiceAgentFactory: () => VoiceAgentFactory,
+  XAI_REASONING_EFFORTS: () => XAI_REASONING_EFFORTS,
   ZodSchemaConverter: () => ZodSchemaConverter,
   applySpend: () => applySpend,
   buildGoogleTtsPrompt: () => buildGoogleTtsPrompt,
@@ -163,6 +164,7 @@ __export(src_exports, {
   toMetaEffort: () => toMetaEffort,
   toMistralEffort: () => toMistralEffort,
   toOpenAIEffort: () => toOpenAIEffort,
+  toXaiEffort: () => toXaiEffort,
   transcribeWithGemini: () => transcribeWithGemini,
   transcribeWithOpenAi: () => transcribeWithOpenAi,
   validateResponse: () => validateResponse
@@ -1129,10 +1131,15 @@ var SupportedAiModels = {
     reasoningEffort: "minimal",
     tags: ["fast", "cheap"]
   },
-  // Always-on reasoning (xAI default effort "high", cannot be disabled) — no non-thinking sibling
+  // Always-on reasoning — no non-thinking sibling. Bumped 4.6 → 4.7 on 2026-09-22 (id verified
+  // against GET /v1/models). Same price, same 200K extended-context boundary; the context
+  // window is 500K. NOTE 4.7 newly accepts `reasoning_effort` (low | medium | high | xhigh,
+  // default high) where 4.6 had no knob at all. GrokAgent still sends none, so behaviour is
+  // unchanged — but Grok is the app's most expensive model per turn (94% of its output is
+  // reasoning), so a lower pin is the obvious lever to measure before anything else.
   [LLM_CONSTANTS.GROK]: {
-    displayName: "Grok 4.6",
-    modelApiName: "grok-4.6",
+    displayName: "Grok 4.7",
+    modelApiName: "grok-4.7",
     apiKeyName: API_KEY_CONSTANTS.GROK,
     hasThinking: true,
     temperature: 0.7
@@ -1544,8 +1551,9 @@ var MODEL_PRICING = {
     cacheHitPrice: 0.015
   },
   // Grok models. Cached price is per-model on xAI (not a uniform ratio):
-  // grok-4.6 is $0.50/M cached vs $2.00/M input, and all rates double for prompts
-  // >= 200K tokens, per docs.x.ai/developers/models (verified 2026-08-12).
+  // grok-4.7 is $0.50/M cached vs $2.00/M input, and all rates double for prompts
+  // >= 200K tokens, per docs.x.ai/docs/models (re-verified 2026-09-22 for 4.7).
+  // 4.7 carries over 4.6's rates unchanged — the bump is capability-only, not a reprice.
   [SupportedAiModels[LLM_CONSTANTS.GROK].modelApiName]: {
     inputPrice: 2,
     outputPrice: 6,
@@ -1695,6 +1703,7 @@ var DEEPSEEK_REASONING_EFFORTS = ["low", "high", "max"];
 var FUGU_REASONING_EFFORTS = ["high", "xhigh", "max"];
 var META_REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"];
 var MISTRAL_REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh"];
+var XAI_REASONING_EFFORTS = ["low", "medium", "high", "xhigh"];
 function clampReasoningEffort(effort, allowed) {
   const rank = REASONING_EFFORT_SCALE.indexOf(effort);
   let best = allowed[0];
@@ -1716,6 +1725,7 @@ var toDeepSeekEffort = (effort) => clampReasoningEffort(effort, DEEPSEEK_REASONI
 var toMetaEffort = (effort) => clampReasoningEffort(effort, META_REASONING_EFFORTS);
 var toFuguEffort = (effort) => clampReasoningEffort(effort, FUGU_REASONING_EFFORTS);
 var toMistralEffort = (effort) => clampReasoningEffort(effort, MISTRAL_REASONING_EFFORTS);
+var toXaiEffort = (effort) => clampReasoningEffort(effort, XAI_REASONING_EFFORTS);
 
 // src/pricing/token-usage-utils.ts
 function extractTokenUsage(response) {
@@ -3953,6 +3963,16 @@ ${schemaDescription}`;
       throw new Error(this.errorMessages.apiError(error));
     }
   }
+  /**
+   * A stable key per (game, bot) so xAI routes this conversation's requests to the same
+   * server. Without it a request often lands on a cache-cold machine and the whole prompt
+   * bills at full input price — xAI calls this out as the most common caching mistake.
+   * Falls back to the bot name alone outside a game (story generation, tests), which is
+   * still stabler than sending nothing.
+   */
+  get promptCacheKey() {
+    return this.gameId ? `${this.gameId}:${this.name}` : this.name;
+  }
   createResponse(input, jsonMode) {
     return this.client.responses.create({
       model: this.model,
@@ -3963,9 +3983,16 @@ ${schemaDescription}`;
       // ever starts truncating — measured turns peak far below the shared default.
       max_output_tokens: this.maxOutputTokens,
       // We manage conversation state ourselves; encrypted reasoning is only
-      // returned for unstored responses.
+      // returned for unstored responses. Grok 4.7 returns reasoning.encrypted_content
+      // on the Responses API whether or not `include` asks for it; we keep asking so
+      // the behaviour is identical if the model is ever pointed back at 4.6.
       store: false,
       include: ["reasoning.encrypted_content"],
+      prompt_cache_key: this.promptCacheKey,
+      // Grok 4.7 is the first Grok with an effort knob (4.6 had none) and defaults to
+      // "high". Only send it when the catalog asks for a level, so an unset entry keeps
+      // the provider default rather than us silently picking one.
+      ...this.reasoningEffort ? { reasoning: { effort: toXaiEffort(this.reasoningEffort) } } : {},
       ...jsonMode ? { text: { format: { type: "json_object" } } } : {}
     });
   }
@@ -5379,6 +5406,7 @@ var AgentFactory = class {
   VOICE_MODEL_PRICING,
   VOICE_PROVIDER_API_KEY,
   VoiceAgentFactory,
+  XAI_REASONING_EFFORTS,
   ZodSchemaConverter,
   applySpend,
   buildGoogleTtsPrompt,
@@ -5459,6 +5487,7 @@ var AgentFactory = class {
   toMetaEffort,
   toMistralEffort,
   toOpenAIEffort,
+  toXaiEffort,
   transcribeWithGemini,
   transcribeWithOpenAi,
   validateResponse