@hiper2d/ai-agents 0.3.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @hiper2d/ai-agents
 
-Multi-provider AI agent layer for TypeScript apps: one `AbstractAgent` interface over 11 LLM
+Multi-provider AI agent layer for TypeScript apps: one `AbstractAgent` interface over 12 LLM
 providers, schema-validated JSON asks (zod), reasoning/thinking extraction, a model catalog
 with per-model tuning defaults, and token cost accounting (cache tiers, extended context,
 peak-valley pricing).

package/dist/index.d.mts

@@ -15,6 +15,7 @@ interface AIMessage {
     anthropicThinkingSignature?: string;
     googleThoughtSignature?: string;
     grokEncryptedReasoning?: string;
+    metaEncryptedReasoning?: string;
 }
 interface TokenUsage$1 {
     inputTokens: number;
@@ -331,6 +332,7 @@ declare const API_KEY_CONSTANTS: {
     readonly FUGU: "FUGU_API_KEY";
     readonly QWEN: "QWEN_API_KEY";
     readonly MINIMAX: "MINIMAX_API_KEY";
+    readonly META: "META_API_KEY";
 };
 declare const SupportedAiKeyNames: Record<string, string>;
 declare const LLM_CONSTANTS: {
@@ -359,6 +361,7 @@ declare const LLM_CONSTANTS: {
     QWEN_MAX: string;
     QWEN_FLASH: string;
     MINIMAX: string;
+    MUSE_SPARK: string;
 };
 /**
  * Per-request output ceiling for ordinary requests. Reasoning tokens are billed inside this
@@ -493,6 +496,7 @@ declare function getProviderSignatureFields(aiType: string, signature?: string):
     anthropicThinkingSignature?: string;
     googleThoughtSignature?: string;
     grokEncryptedReasoning?: string;
+    metaEncryptedReasoning?: string;
 };
 
 /**
@@ -512,6 +516,8 @@ declare function getProviderSignatureFields(aiType: string, signature?: string):
  * - Z.AI GLM-5.3 / 5.3-Flash: low|high|max only
  * - DeepSeek V4: low|high|max (the API itself aliases medium → high)
  * - Sakana Fugu: high|xhigh
+ * - Meta Muse Spark (verified 2026-09-12): minimal|low|medium|high|xhigh|max ("none" → 400; max is
+ *   Standard tier only)
  * Qwen accepts reasoning_effort but ignores it (thinking_budget is its knob); MiniMax, Kimi,
  * Grok and Mistral expose no effort parameter.
  */
@@ -521,6 +527,7 @@ type GeminiReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
 type GlmReasoningEffort = 'low' | 'high' | 'max';
 type DeepSeekReasoningEffort = 'low' | 'high' | 'max';
 type FuguReasoningEffort = 'high' | 'xhigh';
+type MetaReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 /** The shared scale, lowest first. */
 declare const REASONING_EFFORT_SCALE: readonly ReasoningEffort[];
 declare const OPENAI_REASONING_EFFORTS: readonly OpenAIReasoningEffort[];
@@ -529,6 +536,7 @@ declare const GEMINI_REASONING_EFFORTS: readonly GeminiReasoningEffort[];
 declare const GLM_REASONING_EFFORTS: readonly GlmReasoningEffort[];
 declare const DEEPSEEK_REASONING_EFFORTS: readonly DeepSeekReasoningEffort[];
 declare const FUGU_REASONING_EFFORTS: readonly FuguReasoningEffort[];
+declare const META_REASONING_EFFORTS: readonly MetaReasoningEffort[];
 /** 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;
@@ -536,6 +544,7 @@ declare const toAnthropicEffort: (effort: ReasoningEffort) => AnthropicReasoning
 declare const toGeminiEffort: (effort: ReasoningEffort) => GeminiReasoningEffort;
 declare const toGlmEffort: (effort: ReasoningEffort) => GlmReasoningEffort;
 declare const toDeepSeekEffort: (effort: ReasoningEffort) => DeepSeekReasoningEffort;
+declare const toMetaEffort: (effort: ReasoningEffort) => MetaReasoningEffort;
 declare const toFuguEffort: (effort: ReasoningEffort) => FuguReasoningEffort;
 
 /**
@@ -601,6 +610,11 @@ declare function extractKimiTokenUsage(response: any): TokenUsage | null;
  * Grok uses OpenAI-compatible format
  */
 declare function extractGrokTokenUsage(response: any): TokenUsage | null;
+/**
+ * Meta-specific token usage extraction
+ * The Meta Model API uses the OpenAI-compatible format
+ */
+declare function extractMetaTokenUsage(response: any): TokenUsage | null;
 /**
  * Anthropic-specific token usage extraction
  * Anthropic may have different response format
@@ -643,7 +657,7 @@ interface OpenAITokenUsage {
     cacheHitTokens?: number;
     reasoningTokens?: number;
 }
-declare function extractTokenUsageFromResponse$6(response: any): OpenAITokenUsage | null;
+declare function extractTokenUsageFromResponse$7(response: any): OpenAITokenUsage | null;
 
 /**
  * DeepSeek pricing utilities
@@ -671,7 +685,7 @@ interface DeepSeekTokenUsage {
     cacheMissTokens?: number;
     reasoningTokens?: number;
 }
-declare function extractTokenUsageFromResponse$5(response: any): DeepSeekTokenUsage | null;
+declare function extractTokenUsageFromResponse$6(response: any): DeepSeekTokenUsage | null;
 
 /**
  * Kimi (Moonshot AI) pricing utilities
@@ -696,7 +710,7 @@ interface KimiTokenUsage {
     completionTokens: number;
     totalTokens: number;
 }
-declare function extractTokenUsageFromResponse$4(response: any): KimiTokenUsage | null;
+declare function extractTokenUsageFromResponse$5(response: any): KimiTokenUsage | null;
 
 /**
  * Grok (xAI) pricing utilities
@@ -723,7 +737,29 @@ interface GrokTokenUsage {
     cacheHitTokens?: number;
     reasoningTokens?: number;
 }
-declare function extractTokenUsageFromResponse$3(response: any): GrokTokenUsage | null;
+declare function extractTokenUsageFromResponse$4(response: any): GrokTokenUsage | null;
+
+/**
+ * Meta Model API (Muse Spark) pricing utilities
+ * Re-exports unified utilities with Meta-specific naming, like the other providers
+ */
+/**
+ * Calculate the cost for token usage based on Meta pricing
+ * @param model - The Meta model name (e.g. muse-spark-1.3)
+ * @param inputTokens - Number of input tokens used (cached tokens are a subset of these)
+ * @param outputTokens - Number of output tokens used (includes reasoning tokens)
+ * @param cacheHitTokens - Number of cached input tokens (input_tokens_details.cached_tokens)
+ * @returns Cost in USD
+ */
+declare function calculateMetaCost(model: string, inputTokens: number, outputTokens: number, cacheHitTokens?: number): number;
+interface MetaTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheHitTokens?: number;
+    reasoningTokens?: number;
+}
+declare function extractTokenUsageFromResponse$3(response: any): MetaTokenUsage | null;
 
 /**
  * Anthropic pricing utilities
@@ -1460,6 +1496,57 @@ declare class GrokAgent extends AbstractAgent {
     private extractTokenUsage;
 }
 
+/**
+ * Meta Model API agent (Muse Spark) on the Responses API at api.meta.ai.
+ *
+ * Muse Spark is an always-on reasoning model: `reasoning.effort` picks the depth
+ * (minimal … max; "none" is rejected with a 400) and the catalog pins a default per entry.
+ * The chain of thought itself is never returned; a summary is requested with
+ * `reasoning.summary: "auto"` and surfaces as the thinking string. Each response's encrypted
+ * reasoning items (requested via `include: ["reasoning.encrypted_content"]`) come back as the
+ * 4th tuple element, are stored on the message as `metaEncryptedReasoning`, and are replayed
+ * into `input` on later turns so the model keeps its reasoning across the conversation —
+ * the same contract as the Grok agent.
+ *
+ * Prompt caching is automatic on Meta's side; `prompt_cache_key` only routes requests that
+ * share a prefix to the same backend, so it is derived from the bot's identity + system
+ * prompt (stable within a game day, like Grok's conversation id).
+ *
+ * Structured output uses the documented `text.format` json_schema mode (strict: false —
+ * Meta's strict subset forbids optional keys and unions that game schemas use), with the
+ * schema description also appended to the prompt and the lenient parser on the way back.
+ */
+declare class MetaAgent extends AbstractAgent {
+    private readonly client;
+    private readonly promptCacheKey;
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    /**
+     * Structured output: json_schema format on the Responses API plus the schema described
+     * in the prompt, parsed leniently and validated with Zod.
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no JSON mode and no schema appended to the prompt.
+     * Reasoning extraction and token accounting are identical to askWithZodSchema.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    private createResponse;
+    /**
+     * Converts history to Responses API input items. The system instruction is merged into
+     * the leading system message; assistant messages carrying stored encrypted reasoning get
+     * their reasoning items replayed right before them.
+     */
+    private buildResponsesInput;
+    /**
+     * Walks the response output items: reasoning items yield the human-readable summary
+     * plus the encrypted items (serialized for storage/replay); message items yield text.
+     */
+    private extractResponseParts;
+    private extractTokenUsage;
+}
+
 declare class KimiAgent extends AbstractAgent {
     private readonly client;
     private get defaultParams();
@@ -1582,4 +1669,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, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, type SpendInput, type SpendKind, type SpendLedger, type SpendLedgers, type SpendStore, type SpendWindow, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, ZodSchemaConverter, applySpend, buildGoogleTtsPrompt, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };
+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 };

package/dist/index.d.ts

@@ -15,6 +15,7 @@ interface AIMessage {
     anthropicThinkingSignature?: string;
     googleThoughtSignature?: string;
     grokEncryptedReasoning?: string;
+    metaEncryptedReasoning?: string;
 }
 interface TokenUsage$1 {
     inputTokens: number;
@@ -331,6 +332,7 @@ declare const API_KEY_CONSTANTS: {
     readonly FUGU: "FUGU_API_KEY";
     readonly QWEN: "QWEN_API_KEY";
     readonly MINIMAX: "MINIMAX_API_KEY";
+    readonly META: "META_API_KEY";
 };
 declare const SupportedAiKeyNames: Record<string, string>;
 declare const LLM_CONSTANTS: {
@@ -359,6 +361,7 @@ declare const LLM_CONSTANTS: {
     QWEN_MAX: string;
     QWEN_FLASH: string;
     MINIMAX: string;
+    MUSE_SPARK: string;
 };
 /**
  * Per-request output ceiling for ordinary requests. Reasoning tokens are billed inside this
@@ -493,6 +496,7 @@ declare function getProviderSignatureFields(aiType: string, signature?: string):
     anthropicThinkingSignature?: string;
     googleThoughtSignature?: string;
     grokEncryptedReasoning?: string;
+    metaEncryptedReasoning?: string;
 };
 
 /**
@@ -512,6 +516,8 @@ declare function getProviderSignatureFields(aiType: string, signature?: string):
  * - Z.AI GLM-5.3 / 5.3-Flash: low|high|max only
  * - DeepSeek V4: low|high|max (the API itself aliases medium → high)
  * - Sakana Fugu: high|xhigh
+ * - Meta Muse Spark (verified 2026-09-12): minimal|low|medium|high|xhigh|max ("none" → 400; max is
+ *   Standard tier only)
  * Qwen accepts reasoning_effort but ignores it (thinking_budget is its knob); MiniMax, Kimi,
  * Grok and Mistral expose no effort parameter.
  */
@@ -521,6 +527,7 @@ type GeminiReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
 type GlmReasoningEffort = 'low' | 'high' | 'max';
 type DeepSeekReasoningEffort = 'low' | 'high' | 'max';
 type FuguReasoningEffort = 'high' | 'xhigh';
+type MetaReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 /** The shared scale, lowest first. */
 declare const REASONING_EFFORT_SCALE: readonly ReasoningEffort[];
 declare const OPENAI_REASONING_EFFORTS: readonly OpenAIReasoningEffort[];
@@ -529,6 +536,7 @@ declare const GEMINI_REASONING_EFFORTS: readonly GeminiReasoningEffort[];
 declare const GLM_REASONING_EFFORTS: readonly GlmReasoningEffort[];
 declare const DEEPSEEK_REASONING_EFFORTS: readonly DeepSeekReasoningEffort[];
 declare const FUGU_REASONING_EFFORTS: readonly FuguReasoningEffort[];
+declare const META_REASONING_EFFORTS: readonly MetaReasoningEffort[];
 /** 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;
@@ -536,6 +544,7 @@ declare const toAnthropicEffort: (effort: ReasoningEffort) => AnthropicReasoning
 declare const toGeminiEffort: (effort: ReasoningEffort) => GeminiReasoningEffort;
 declare const toGlmEffort: (effort: ReasoningEffort) => GlmReasoningEffort;
 declare const toDeepSeekEffort: (effort: ReasoningEffort) => DeepSeekReasoningEffort;
+declare const toMetaEffort: (effort: ReasoningEffort) => MetaReasoningEffort;
 declare const toFuguEffort: (effort: ReasoningEffort) => FuguReasoningEffort;
 
 /**
@@ -601,6 +610,11 @@ declare function extractKimiTokenUsage(response: any): TokenUsage | null;
  * Grok uses OpenAI-compatible format
  */
 declare function extractGrokTokenUsage(response: any): TokenUsage | null;
+/**
+ * Meta-specific token usage extraction
+ * The Meta Model API uses the OpenAI-compatible format
+ */
+declare function extractMetaTokenUsage(response: any): TokenUsage | null;
 /**
  * Anthropic-specific token usage extraction
  * Anthropic may have different response format
@@ -643,7 +657,7 @@ interface OpenAITokenUsage {
     cacheHitTokens?: number;
     reasoningTokens?: number;
 }
-declare function extractTokenUsageFromResponse$6(response: any): OpenAITokenUsage | null;
+declare function extractTokenUsageFromResponse$7(response: any): OpenAITokenUsage | null;
 
 /**
  * DeepSeek pricing utilities
@@ -671,7 +685,7 @@ interface DeepSeekTokenUsage {
     cacheMissTokens?: number;
     reasoningTokens?: number;
 }
-declare function extractTokenUsageFromResponse$5(response: any): DeepSeekTokenUsage | null;
+declare function extractTokenUsageFromResponse$6(response: any): DeepSeekTokenUsage | null;
 
 /**
  * Kimi (Moonshot AI) pricing utilities
@@ -696,7 +710,7 @@ interface KimiTokenUsage {
     completionTokens: number;
     totalTokens: number;
 }
-declare function extractTokenUsageFromResponse$4(response: any): KimiTokenUsage | null;
+declare function extractTokenUsageFromResponse$5(response: any): KimiTokenUsage | null;
 
 /**
  * Grok (xAI) pricing utilities
@@ -723,7 +737,29 @@ interface GrokTokenUsage {
     cacheHitTokens?: number;
     reasoningTokens?: number;
 }
-declare function extractTokenUsageFromResponse$3(response: any): GrokTokenUsage | null;
+declare function extractTokenUsageFromResponse$4(response: any): GrokTokenUsage | null;
+
+/**
+ * Meta Model API (Muse Spark) pricing utilities
+ * Re-exports unified utilities with Meta-specific naming, like the other providers
+ */
+/**
+ * Calculate the cost for token usage based on Meta pricing
+ * @param model - The Meta model name (e.g. muse-spark-1.3)
+ * @param inputTokens - Number of input tokens used (cached tokens are a subset of these)
+ * @param outputTokens - Number of output tokens used (includes reasoning tokens)
+ * @param cacheHitTokens - Number of cached input tokens (input_tokens_details.cached_tokens)
+ * @returns Cost in USD
+ */
+declare function calculateMetaCost(model: string, inputTokens: number, outputTokens: number, cacheHitTokens?: number): number;
+interface MetaTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheHitTokens?: number;
+    reasoningTokens?: number;
+}
+declare function extractTokenUsageFromResponse$3(response: any): MetaTokenUsage | null;
 
 /**
  * Anthropic pricing utilities
@@ -1460,6 +1496,57 @@ declare class GrokAgent extends AbstractAgent {
     private extractTokenUsage;
 }
 
+/**
+ * Meta Model API agent (Muse Spark) on the Responses API at api.meta.ai.
+ *
+ * Muse Spark is an always-on reasoning model: `reasoning.effort` picks the depth
+ * (minimal … max; "none" is rejected with a 400) and the catalog pins a default per entry.
+ * The chain of thought itself is never returned; a summary is requested with
+ * `reasoning.summary: "auto"` and surfaces as the thinking string. Each response's encrypted
+ * reasoning items (requested via `include: ["reasoning.encrypted_content"]`) come back as the
+ * 4th tuple element, are stored on the message as `metaEncryptedReasoning`, and are replayed
+ * into `input` on later turns so the model keeps its reasoning across the conversation —
+ * the same contract as the Grok agent.
+ *
+ * Prompt caching is automatic on Meta's side; `prompt_cache_key` only routes requests that
+ * share a prefix to the same backend, so it is derived from the bot's identity + system
+ * prompt (stable within a game day, like Grok's conversation id).
+ *
+ * Structured output uses the documented `text.format` json_schema mode (strict: false —
+ * Meta's strict subset forbids optional keys and unions that game schemas use), with the
+ * schema description also appended to the prompt and the lenient parser on the way back.
+ */
+declare class MetaAgent extends AbstractAgent {
+    private readonly client;
+    private readonly promptCacheKey;
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    /**
+     * Structured output: json_schema format on the Responses API plus the schema described
+     * in the prompt, parsed leniently and validated with Zod.
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no JSON mode and no schema appended to the prompt.
+     * Reasoning extraction and token accounting are identical to askWithZodSchema.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    private createResponse;
+    /**
+     * Converts history to Responses API input items. The system instruction is merged into
+     * the leading system message; assistant messages carrying stored encrypted reasoning get
+     * their reasoning items replayed right before them.
+     */
+    private buildResponsesInput;
+    /**
+     * Walks the response output items: reasoning items yield the human-readable summary
+     * plus the encrypted items (serialized for storage/replay); message items yield text.
+     */
+    private extractResponseParts;
+    private extractTokenUsage;
+}
+
 declare class KimiAgent extends AbstractAgent {
     private readonly client;
     private get defaultParams();
@@ -1582,4 +1669,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, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelInvalidResponseError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type OpenAiSttOptions, type OpenAiSttResult, type OpenAiTtsAudioOptions, type OpenAiTtsVoice, OpenAiVoiceAgent, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SUPPORTED_VOICE_PROVIDERS, type SpeechRequest, type SpeechResult, type SpeechUsage, type SpendInput, type SpendKind, type SpendLedger, type SpendLedgers, type SpendStore, type SpendWindow, SupportedAiKeyNames, SupportedAiModels, type TokenPairUsage, type TokenUsage$1 as TokenUsage, type TranscriptionRequest, type TranscriptionResult, type TranscriptionUsage, VOICE_MODEL_CONSTANTS, VOICE_MODEL_PRICING, VOICE_PROVIDER_API_KEY, type VoiceAgent, VoiceAgentFactory, type VoiceModelPricing, type VoiceProvider, ZodSchemaConverter, applySpend, buildGoogleTtsPrompt, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGeminiSttCost, calculateGeminiTtsCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, calculateOpenAiSttCost, calculateOpenAiTtsCost, clampReasoningEffort, cleanResponse, createCatalog, createVoiceAgent, evaluateBudget, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, firstRefusal, generateGoogleTtsAudio, generateOpenAiTtsAudio, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isBudgetExceededError, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, ledgerSpend, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, pcmToWav, periodEnd, periodKey, safeValidateResponse, setBeforeAskHook, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, transcribeWithGemini, transcribeWithOpenAi, validateResponse };
+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 };