@hiper2d/ai-agents 0.5.0 → 0.5.2

package/dist/index.d.mts

@@ -272,15 +272,29 @@ declare class ModelInvalidResponseError extends ModelError {
     constructor(modelType: string, detail: string, truncated?: boolean);
 }
 /**
- * The model declined to answer: Anthropic returns `stop_reason: "refusal"` with no content
- * blocks when its safety layer rejects the request as a whole. Not retryable as-is — the
- * same prompt will refuse again — the caller has to change the prompt or the model.
- * Observed 2026-08-30 on Claude Fable 5: a persona system prompt plus a narrated multi-turn
- * history that ends by asking the character what it does refuses, while either half alone
- * answers; Sonnet 5 and Opus 4.8 answer the same requests.
+ * The model declined to answer. Not retryable as-is — the same prompt will refuse again —
+ * the caller has to change the prompt or the model. `reason` is the provider's own label
+ * for the refusal, when it gives one:
+ *
+ *   Anthropic  `stop_reason: "refusal"` with no content blocks when its safety layer rejects
+ *              the request as a whole. Observed 2026-08-30 on Claude Fable 5: a persona
+ *              system prompt plus a narrated multi-turn history that ends by asking the
+ *              character what it does refuses, while either half alone answers; Sonnet 5
+ *              and Opus 4.8 answer the same requests. `reason` = "refusal".
+ *   Google     a 200 with no candidates and `promptFeedback.blockReason` set (the prompt
+ *              itself was rejected: PROHIBITED_CONTENT, SAFETY, BLOCKLIST, JAILBREAK,
+ *              MODEL_ARMOR, OTHER), or a candidate whose `finishReason` is a content
+ *              block (SAFETY, PROHIBITED_CONTENT, BLOCKLIST, RECITATION, SPII,
+ *              IMAGE_SAFETY, ...). Observed 2026-09-13 in production: an explicit
+ *              sexual roleplay game was refused by Gemini 3.8 Flash and 3.1 Pro with
+ *              blockReason PROHIBITED_CONTENT in ~200ms and zero output tokens, while
+ *              Mistral, MiniMax and Muse answered the same prompt. PROHIBITED_CONTENT is
+ *              Google's non-configurable filter — no safetySettings change lifts it.
+ *              `reason` = the blockReason or finishReason string.
  */
 declare class ModelRefusalError extends ModelError {
-    constructor(modelType: string, message?: string);
+    reason?: string;
+    constructor(modelType: string, message?: string, reason?: string);
 }
 
 /**
@@ -1022,6 +1036,13 @@ interface GoogleTtsResult {
 declare function buildGoogleTtsPrompt(text: string, voiceStyle?: string): string;
 /** Wraps raw 16-bit mono PCM in a WAV header. */
 declare function pcmToWav(pcmData: Uint8Array, sampleRate?: number): ArrayBuffer;
+/**
+ * Why a 200 came back without audio. Gemini occasionally returns an empty candidate
+ * (a transient `OTHER` / `RECITATION` finish, a safety block reported in
+ * promptFeedback, or a text part instead of audio); naming it in the error is the
+ * difference between a diagnosable log line and "no audio data".
+ */
+declare function describeEmptyTtsResponse(response: any): string;
 /**
  * Core Gemini TTS call: text + API key in, WAV + token usage out.
  *
@@ -1669,4 +1690,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, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, 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, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, 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, 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, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, 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, 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, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.d.ts

@@ -272,15 +272,29 @@ declare class ModelInvalidResponseError extends ModelError {
     constructor(modelType: string, detail: string, truncated?: boolean);
 }
 /**
- * The model declined to answer: Anthropic returns `stop_reason: "refusal"` with no content
- * blocks when its safety layer rejects the request as a whole. Not retryable as-is — the
- * same prompt will refuse again — the caller has to change the prompt or the model.
- * Observed 2026-08-30 on Claude Fable 5: a persona system prompt plus a narrated multi-turn
- * history that ends by asking the character what it does refuses, while either half alone
- * answers; Sonnet 5 and Opus 4.8 answer the same requests.
+ * The model declined to answer. Not retryable as-is — the same prompt will refuse again —
+ * the caller has to change the prompt or the model. `reason` is the provider's own label
+ * for the refusal, when it gives one:
+ *
+ *   Anthropic  `stop_reason: "refusal"` with no content blocks when its safety layer rejects
+ *              the request as a whole. Observed 2026-08-30 on Claude Fable 5: a persona
+ *              system prompt plus a narrated multi-turn history that ends by asking the
+ *              character what it does refuses, while either half alone answers; Sonnet 5
+ *              and Opus 4.8 answer the same requests. `reason` = "refusal".
+ *   Google     a 200 with no candidates and `promptFeedback.blockReason` set (the prompt
+ *              itself was rejected: PROHIBITED_CONTENT, SAFETY, BLOCKLIST, JAILBREAK,
+ *              MODEL_ARMOR, OTHER), or a candidate whose `finishReason` is a content
+ *              block (SAFETY, PROHIBITED_CONTENT, BLOCKLIST, RECITATION, SPII,
+ *              IMAGE_SAFETY, ...). Observed 2026-09-13 in production: an explicit
+ *              sexual roleplay game was refused by Gemini 3.8 Flash and 3.1 Pro with
+ *              blockReason PROHIBITED_CONTENT in ~200ms and zero output tokens, while
+ *              Mistral, MiniMax and Muse answered the same prompt. PROHIBITED_CONTENT is
+ *              Google's non-configurable filter — no safetySettings change lifts it.
+ *              `reason` = the blockReason or finishReason string.
  */
 declare class ModelRefusalError extends ModelError {
-    constructor(modelType: string, message?: string);
+    reason?: string;
+    constructor(modelType: string, message?: string, reason?: string);
 }
 
 /**
@@ -1022,6 +1036,13 @@ interface GoogleTtsResult {
 declare function buildGoogleTtsPrompt(text: string, voiceStyle?: string): string;
 /** Wraps raw 16-bit mono PCM in a WAV header. */
 declare function pcmToWav(pcmData: Uint8Array, sampleRate?: number): ArrayBuffer;
+/**
+ * Why a 200 came back without audio. Gemini occasionally returns an empty candidate
+ * (a transient `OTHER` / `RECITATION` finish, a safety block reported in
+ * promptFeedback, or a text part instead of audio); naming it in the error is the
+ * difference between a diagnosable log line and "no audio data".
+ */
+declare function describeEmptyTtsResponse(response: any): string;
 /**
  * Core Gemini TTS call: text + API key in, WAV + token usage out.
  *
@@ -1669,4 +1690,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, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, 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, calculateMetaCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, 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, 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, MODEL_PRICING, MetaAgent, type MetaReasoningEffort, type MetaTokenUsage, 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, 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, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };

package/dist/index.js

@@ -103,6 +103,7 @@ __export(src_exports, {
   cleanResponse: () => cleanResponse,
   createCatalog: () => createCatalog,
   createVoiceAgent: () => createVoiceAgent,
+  describeEmptyTtsResponse: () => describeEmptyTtsResponse,
   evaluateBudget: () => evaluateBudget,
   extractAnthropicTokenUsage: () => extractAnthropicTokenUsage,
   extractAnthropicTokenUsageFromResponse: () => extractTokenUsageFromResponse6,
@@ -882,9 +883,11 @@ var ModelInvalidResponseError = class extends ModelError {
   }
 };
 var ModelRefusalError = class extends ModelError {
-  constructor(modelType, message = `${modelType} refused to answer (stop_reason: refusal)`) {
+  reason;
+  constructor(modelType, message = `${modelType} refused to answer (stop_reason: refusal)`, reason) {
     super(message, modelType);
     this.name = "ModelRefusalError";
+    this.reason = reason;
   }
 };
 
@@ -1998,6 +2001,21 @@ function pcmToWav(pcmData, sampleRate = SAMPLE_RATE) {
   new Uint8Array(buffer, headerSize).set(pcmData);
   return buffer;
 }
+function describeEmptyTtsResponse(response) {
+  const candidate = response?.candidates?.[0];
+  const parts = candidate?.content?.parts ?? [];
+  const bits = [];
+  bits.push(`finishReason=${candidate?.finishReason ?? "none"}`);
+  if (!response?.candidates?.length) bits.push("no candidates");
+  const block = response?.promptFeedback?.blockReason;
+  if (block) bits.push(`blockReason=${block}`);
+  const text = parts.map((p) => typeof p?.text === "string" ? p.text : "").join(" ").trim();
+  if (text) bits.push(`text="${text.slice(0, 120)}"`);
+  const otherMimes = parts.map((p) => p?.inlineData?.mimeType).filter(Boolean);
+  if (otherMimes.length) bits.push(`inlineData=${otherMimes.join(",")}`);
+  if (!parts.length) bits.push("no parts");
+  return bits.join(", ");
+}
 async function generateGoogleTtsAudio(text, apiKey, options) {
   const client = new import_genai.GoogleGenAI({ apiKey });
   const response = await client.models.generateContent({
@@ -2008,10 +2026,11 @@ async function generateGoogleTtsAudio(text, apiKey, options) {
       speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: options.voiceName } } }
     }
   });
-  const parts = response.candidates?.[0]?.content?.parts ?? [];
+  const candidate = response.candidates?.[0];
+  const parts = candidate?.content?.parts ?? [];
   const audioPart = parts.find((part) => part.inlineData?.mimeType?.startsWith("audio/"));
   if (!audioPart?.inlineData?.data) {
-    throw new Error("No audio data in Google TTS response");
+    throw new Error(`No audio data in Google TTS response (${describeEmptyTtsResponse(response)})`);
   }
   const pcmData = new Uint8Array(Buffer.from(audioPart.inlineData.data, "base64"));
   const usageMetadata = response.usageMetadata ?? {};
@@ -2806,7 +2825,7 @@ ${schemaDescription}`;
         throw new Error(this.errorMessages.apiError(apiError));
       }
       if (response.stop_reason === "refusal") {
-        throw new ModelRefusalError(this.model);
+        throw new ModelRefusalError(this.model, void 0, "refusal");
       }
       if (!("content" in response) || !Array.isArray(response.content) || response.content.length === 0) {
         throw new Error(this.errorMessages.emptyResponse);
@@ -2900,7 +2919,7 @@ ${schemaDescription}`;
         throw new Error(this.errorMessages.apiError(apiError));
       }
       if (response.stop_reason === "refusal") {
-        throw new ModelRefusalError(this.model);
+        throw new ModelRefusalError(this.model, void 0, "refusal");
       }
       if (!("content" in response) || !Array.isArray(response.content) || response.content.length === 0) {
         throw new Error(this.errorMessages.emptyResponse);
@@ -2956,6 +2975,45 @@ ${schemaDescription}`;
 
 // src/agents/google-agent.ts
 var import_genai3 = require("@google/genai");
+var GEMINI_REFUSAL_FINISH_REASONS = /* @__PURE__ */ new Set([
+  "SAFETY",
+  "RECITATION",
+  "BLOCKLIST",
+  "PROHIBITED_CONTENT",
+  "SPII",
+  "IMAGE_SAFETY",
+  "IMAGE_PROHIBITED_CONTENT",
+  "IMAGE_RECITATION"
+]);
+function throwForEmptyGeminiResponse(model, response, fallback) {
+  const blockReason = response?.promptFeedback?.blockReason;
+  const candidate = response?.candidates?.[0];
+  const finishReason = candidate?.finishReason;
+  const finishMessage = candidate?.finishMessage;
+  const ratings = (candidate?.safetyRatings ?? response?.promptFeedback?.safetyRatings ?? []).filter((r) => r?.blocked || r?.probability && r.probability !== "NEGLIGIBLE");
+  const ratingText = ratings.length ? `; safetyRatings: ${ratings.map((r) => `${r.category}=${r.probability ?? (r.blocked ? "blocked" : "?")}`).join(", ")}` : "";
+  if (blockReason) {
+    throw new ModelRefusalError(
+      model,
+      `${model} refused the prompt (blockReason: ${blockReason}${finishMessage ? `, ${finishMessage}` : ""}${ratingText})`,
+      blockReason
+    );
+  }
+  if (finishReason && GEMINI_REFUSAL_FINISH_REASONS.has(finishReason)) {
+    throw new ModelRefusalError(
+      model,
+      `${model} refused to answer (finishReason: ${finishReason}${finishMessage ? `, ${finishMessage}` : ""}${ratingText})`,
+      finishReason
+    );
+  }
+  if (finishReason === "MAX_TOKENS") {
+    throw new ModelInvalidResponseError(model, "empty response, finishReason MAX_TOKENS (thinking consumed the whole output budget)", true);
+  }
+  const bits = [`finishReason=${finishReason ?? "none"}`];
+  if (!response?.candidates?.length) bits.push("no candidates");
+  if (finishMessage) bits.push(`finishMessage="${finishMessage}"`);
+  throw new Error(`${fallback} (${bits.join(", ")})`);
+}
 var GoogleAgent = class extends AbstractAgent {
   client;
   defaultConfig = {
@@ -2967,7 +3025,7 @@ var GoogleAgent = class extends AbstractAgent {
   };
   // Error message templates
   errorMessages = {
-    emptyResponse: "Empty response from Google API - check logs for detailed response info",
+    emptyResponse: "Empty response from Google API",
     invalidFormat: "Invalid response format from Google API",
     apiError: (error) => `Failed to get response from Google API: ${error instanceof Error ? error.message : String(error)}`,
     unsupportedRole: (role) => `Unsupported role type: ${role}`
@@ -3139,7 +3197,7 @@ var GoogleAgent = class extends AbstractAgent {
       }
       this.logger(`Zod schema response received - hasText: ${!!response.text}, textLength: ${response.text ? response.text.length : 0}`);
       if (!response.text) {
-        throw new Error(this.errorMessages.emptyResponse);
+        throwForEmptyGeminiResponse(this.model, response, this.errorMessages.emptyResponse);
       }
       const parsedData = parseAndValidateLlmJson(response.text, zodSchema, (m) => this.logger(m));
       if (parsedData) {
@@ -3227,7 +3285,7 @@ var GoogleAgent = class extends AbstractAgent {
       }
       this.logger(`Plain text response received - hasText: ${!!response.text}, textLength: ${response.text ? response.text.length : 0}`);
       if (!response.text) {
-        throw new Error(this.errorMessages.emptyResponse);
+        throwForEmptyGeminiResponse(this.model, response, this.errorMessages.emptyResponse);
       }
       this.logReply(response.text, thinkingContent || void 0, tokenUsage);
       return [response.text, thinkingContent, tokenUsage, googleThoughtSignature || void 0];
@@ -5262,6 +5320,7 @@ var AgentFactory = class {
   cleanResponse,
   createCatalog,
   createVoiceAgent,
+  describeEmptyTtsResponse,
   evaluateBudget,
   extractAnthropicTokenUsage,
   extractAnthropicTokenUsageFromResponse,