@hiper2d/ai-agents 0.3.0 → 0.4.0

package/dist/index.js

@@ -58,7 +58,9 @@ __export(index_exports, {
   KimiAgent: () => KimiAgent,
   LLM_CONSTANTS: () => LLM_CONSTANTS,
   MESSAGE_ROLE: () => MESSAGE_ROLE,
+  META_REASONING_EFFORTS: () => META_REASONING_EFFORTS,
   MODEL_PRICING: () => MODEL_PRICING,
+  MetaAgent: () => MetaAgent,
   MiniMaxAgent: () => MiniMaxAgent,
   MistralAgent: () => MistralAgent,
   ModelAuthenticationError: () => ModelAuthenticationError,
@@ -91,6 +93,7 @@ __export(index_exports, {
   calculateGoogleCost: () => calculateGoogleCost,
   calculateGrokCost: () => calculateGrokCost,
   calculateKimiCost: () => calculateKimiCost,
+  calculateMetaCost: () => calculateMetaCost,
   calculateMistralCost: () => calculateMistralCost,
   calculateModelCost: () => calculateModelCost,
   calculateOpenAICost: () => calculateOpenAICost,
@@ -102,18 +105,20 @@ __export(index_exports, {
   createVoiceAgent: () => createVoiceAgent,
   evaluateBudget: () => evaluateBudget,
   extractAnthropicTokenUsage: () => extractAnthropicTokenUsage,
-  extractAnthropicTokenUsageFromResponse: () => extractTokenUsageFromResponse5,
+  extractAnthropicTokenUsageFromResponse: () => extractTokenUsageFromResponse6,
   extractDeepSeekTokenUsage: () => extractDeepSeekTokenUsage,
   extractDeepSeekTokenUsageFromResponse: () => extractTokenUsageFromResponse2,
   extractFirstJsonObject: () => extractFirstJsonObject,
   extractGoogleTokenUsage: () => extractGoogleTokenUsage,
-  extractGoogleTokenUsageFromResponse: () => extractTokenUsageFromResponse6,
+  extractGoogleTokenUsageFromResponse: () => extractTokenUsageFromResponse7,
   extractGrokTokenUsage: () => extractGrokTokenUsage,
   extractGrokTokenUsageFromResponse: () => extractTokenUsageFromResponse4,
   extractKimiTokenUsage: () => extractKimiTokenUsage,
   extractKimiTokenUsageFromResponse: () => extractTokenUsageFromResponse3,
+  extractMetaTokenUsage: () => extractMetaTokenUsage,
+  extractMetaTokenUsageFromResponse: () => extractTokenUsageFromResponse5,
   extractMistralTokenUsage: () => extractMistralTokenUsage,
-  extractMistralTokenUsageFromResponse: () => extractTokenUsageFromResponse7,
+  extractMistralTokenUsageFromResponse: () => extractTokenUsageFromResponse8,
   extractOpenAITokenUsage: () => extractOpenAITokenUsage,
   extractOpenAITokenUsageFromResponse: () => extractTokenUsageFromResponse,
   extractTokenUsage: () => extractTokenUsage,
@@ -143,6 +148,7 @@ __export(index_exports, {
   periodEnd: () => periodEnd,
   periodKey: () => periodKey,
   safeValidateResponse: () => safeValidateResponse,
+  setBeforeAskHook: () => setBeforeAskHook,
   setLlmLogger: () => setLlmLogger,
   stableHashHex: () => stableHashHex,
   stripInlineThinking: () => stripInlineThinking,
@@ -152,6 +158,7 @@ __export(index_exports, {
   toFuguEffort: () => toFuguEffort,
   toGeminiEffort: () => toGeminiEffort,
   toGlmEffort: () => toGlmEffort,
+  toMetaEffort: () => toMetaEffort,
   toOpenAIEffort: () => toOpenAIEffort,
   transcribeWithGemini: () => transcribeWithGemini,
   transcribeWithOpenAi: () => transcribeWithOpenAi,
@@ -919,7 +926,8 @@ var API_KEY_CONSTANTS = {
   Z_AI: "Z_AI_API_KEY",
   FUGU: "FUGU_API_KEY",
   QWEN: "QWEN_API_KEY",
-  MINIMAX: "MINIMAX_API_KEY"
+  MINIMAX: "MINIMAX_API_KEY",
+  META: "META_API_KEY"
 };
 var SupportedAiKeyNames = {
   [API_KEY_CONSTANTS.OPENAI]: "OpenAI",
@@ -932,7 +940,8 @@ var SupportedAiKeyNames = {
   [API_KEY_CONSTANTS.Z_AI]: "Z.AI",
   [API_KEY_CONSTANTS.FUGU]: "Sakana Fugu",
   [API_KEY_CONSTANTS.QWEN]: "Qwen",
-  [API_KEY_CONSTANTS.MINIMAX]: "MiniMax"
+  [API_KEY_CONSTANTS.MINIMAX]: "MiniMax",
+  [API_KEY_CONSTANTS.META]: "Meta"
 };
 var LLM_CONSTANTS = {
   // Thinking-only catalog since 2026-08-05: models whose API offers a thinking toggle used to
@@ -969,7 +978,9 @@ var LLM_CONSTANTS = {
   QWEN_MAX: "qwen-max",
   QWEN_FLASH: "qwen-flash",
   // MiniMax. Single M3 entry; stable id without the version for the same repoint reason.
-  MINIMAX: "minimax"
+  MINIMAX: "minimax",
+  // Meta Model API (api.meta.ai). Muse Spark; version-free id so a 1.3 → 1.4 repoint is entry-only.
+  MUSE_SPARK: "muse-spark"
 };
 var DEFAULT_MAX_OUTPUT_TOKENS = 8192;
 var SupportedAiModels = {
@@ -1254,6 +1265,22 @@ var SupportedAiModels = {
     hasThinking: true,
     temperature: 1,
     tags: ["very-slow", "cheap"]
+  },
+  // Meta Muse Spark 1.3 (added 2026-09-12) on Meta's own Model API — Standard tier, i.e.
+  // the private model id (the `-contributor` id is a quarter of the price but Meta trains
+  // on the prompts). Always-on reasoning with an effort dial (minimal … max, "none" is
+  // rejected); the chain of thought is never returned, only an optional summary, plus
+  // encrypted reasoning items replayed across turns like Grok. 'medium' is pinned as the
+  // game default: turns are short and every reasoning token bills as output.
+  // Temperature: Meta documents the model as tuned to its 1.0 default.
+  // Speed/tags: unmeasured until the first live run — no tag rather than a guess.
+  [LLM_CONSTANTS.MUSE_SPARK]: {
+    displayName: "Muse Spark 1.3",
+    modelApiName: "muse-spark-1.3",
+    apiKeyName: API_KEY_CONSTANTS.META,
+    hasThinking: true,
+    temperature: 1,
+    reasoningEffort: "medium"
   }
 };
 function createCatalog(overrides = {}) {
@@ -1521,6 +1548,14 @@ var MODEL_PRICING = {
     extendedContextOutputPrice: 2.4,
     extendedContextCacheHitPrice: 0.12,
     extendedContextThresholdTokens: 512e3
+  },
+  // Meta Muse Spark 1.3, Standard tier. Rates from ai.developer.meta.com/docs/pricing-rate-limits
+  // (2026-09-12): no long-context premium at any point of the 1M window; reasoning tokens bill
+  // as output; caching is automatic, hits reported in input_tokens_details.cached_tokens.
+  [SupportedAiModels[LLM_CONSTANTS.MUSE_SPARK].modelApiName]: {
+    inputPrice: 1.25,
+    outputPrice: 4.25,
+    cacheHitPrice: 0.15
   }
 };
 var HYBRID_THINKING_API_NAMES = /* @__PURE__ */ new Set([
@@ -1584,6 +1619,9 @@ function getProviderSignatureFields(aiType, signature) {
   if (aiType.startsWith("grok")) {
     return { grokEncryptedReasoning: signature };
   }
+  if (aiType.startsWith("muse-")) {
+    return { metaEncryptedReasoning: signature };
+  }
   return {};
 }
 
@@ -1595,6 +1633,7 @@ var GEMINI_REASONING_EFFORTS = ["minimal", "low", "medium", "high"];
 var GLM_REASONING_EFFORTS = ["low", "high", "max"];
 var DEEPSEEK_REASONING_EFFORTS = ["low", "high", "max"];
 var FUGU_REASONING_EFFORTS = ["high", "xhigh"];
+var META_REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"];
 function clampReasoningEffort(effort, allowed) {
   const rank = REASONING_EFFORT_SCALE.indexOf(effort);
   let best = allowed[0];
@@ -1613,6 +1652,7 @@ var toAnthropicEffort = (effort) => clampReasoningEffort(effort, ANTHROPIC_REASO
 var toGeminiEffort = (effort) => clampReasoningEffort(effort, GEMINI_REASONING_EFFORTS);
 var toGlmEffort = (effort) => clampReasoningEffort(effort, GLM_REASONING_EFFORTS);
 var toDeepSeekEffort = (effort) => clampReasoningEffort(effort, DEEPSEEK_REASONING_EFFORTS);
+var toMetaEffort = (effort) => clampReasoningEffort(effort, META_REASONING_EFFORTS);
 var toFuguEffort = (effort) => clampReasoningEffort(effort, FUGU_REASONING_EFFORTS);
 
 // src/pricing/token-usage-utils.ts
@@ -1667,6 +1707,9 @@ function extractKimiTokenUsage(response) {
 function extractGrokTokenUsage(response) {
   return extractTokenUsage(response);
 }
+function extractMetaTokenUsage(response) {
+  return extractTokenUsage(response);
+}
 function extractAnthropicTokenUsage(response) {
   if (!response?.usage) {
     return null;
@@ -1755,11 +1798,19 @@ function extractTokenUsageFromResponse4(response) {
   return extractGrokTokenUsage(response);
 }
 
+// src/pricing/meta-pricing.ts
+function calculateMetaCost(model, inputTokens, outputTokens, cacheHitTokens = 0) {
+  return calculateCost(model, inputTokens, outputTokens, { cacheHitTokens });
+}
+function extractTokenUsageFromResponse5(response) {
+  return extractMetaTokenUsage(response);
+}
+
 // src/pricing/anthropic-pricing.ts
 function calculateAnthropicCost(model, inputTokens, outputTokens, cacheHitTokens = 0) {
   return calculateCost(model, inputTokens, outputTokens, { cacheHitTokens });
 }
-function extractTokenUsageFromResponse5(response) {
+function extractTokenUsageFromResponse6(response) {
   return extractAnthropicTokenUsage(response);
 }
 
@@ -1767,7 +1818,7 @@ function extractTokenUsageFromResponse5(response) {
 function calculateGoogleCost(model, inputTokens, outputTokens, options = {}) {
   return calculateCost(model, inputTokens, outputTokens, options);
 }
-function extractTokenUsageFromResponse6(response) {
+function extractTokenUsageFromResponse7(response) {
   return extractGoogleTokenUsage(response);
 }
 
@@ -1775,7 +1826,7 @@ function extractTokenUsageFromResponse6(response) {
 function calculateMistralCost(model, inputTokens, outputTokens, cacheHitTokens = 0) {
   return calculateCost(model, inputTokens, outputTokens, { cacheHitTokens });
 }
-function extractTokenUsageFromResponse7(response) {
+function extractTokenUsageFromResponse8(response) {
   return extractMistralTokenUsage(response);
 }
 
@@ -2183,6 +2234,10 @@ var BudgetController = class {
 };
 
 // src/agents/abstract-agent.ts
+var beforeAskHook;
+function setBeforeAskHook(hook) {
+  beforeAskHook = hook;
+}
 var AbstractAgent = class {
   name;
   gameId;
@@ -2234,6 +2289,7 @@ var AbstractAgent = class {
    * must NOT override these.
    */
   async askWithZodSchema(zodSchema, messages) {
+    if (beforeAskHook) await beforeAskHook(this);
     const startedAt = Date.now();
     try {
       const [result, thinking, usage, signature] = await this.doAskWithZodSchema(zodSchema, messages);
@@ -2244,6 +2300,7 @@ var AbstractAgent = class {
     }
   }
   async askText(messages) {
+    if (beforeAskHook) await beforeAskHook(this);
     const startedAt = Date.now();
     try {
       const [content, thinking, usage, signature] = await this.doAskText(messages);
@@ -4839,6 +4896,212 @@ ${openAIMessages[0].content}`;
   }
 };
 
+// src/agents/meta-agent.ts
+var import_openai11 = require("openai");
+var MetaAgent = class extends AbstractAgent {
+  client;
+  promptCacheKey;
+  // Log message templates
+  logTemplates = {
+    error: (name, error) => `Error in ${name} agent: ${error}`
+  };
+  // Error message templates
+  errorMessages = {
+    emptyResponse: "Empty or undefined response from Meta API",
+    invalidFormat: "Invalid response format from Meta API",
+    apiError: (error) => `Failed to get response from Meta API: ${error instanceof Error ? error.message : String(error)}`
+  };
+  constructor(name, instruction, model, apiKey, temperature, enableThinking = false, agentLoggingConfig = DEFAULT_LOGGING_CONFIG.agents) {
+    super(name, instruction, model, temperature, enableThinking, agentLoggingConfig);
+    this.promptCacheKey = stableHashHex(`${name}
+${instruction}`);
+    this.client = new import_openai11.OpenAI({
+      apiKey,
+      baseURL: "https://api.meta.ai/v1",
+      timeout: 12e5
+    });
+  }
+  /**
+   * Structured output: json_schema format on the Responses API plus the schema described
+   * in the prompt, parsed leniently and validated with Zod.
+   */
+  async doAskWithZodSchema(zodSchema, messages) {
+    try {
+      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
+      const input = this.buildResponsesInput(this.prepareMessages(messages));
+      const lastMessage = input[input.length - 1];
+      if (lastMessage && typeof lastMessage.content === "string") {
+        lastMessage.content += `
+
+Your response must be a valid JSON object matching this schema:
+${schemaDescription}`;
+      }
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const response = await this.createResponse(input, zodSchema);
+      const { text, reasoningSummary, encryptedReasoning } = this.extractResponseParts(response);
+      if (!text) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      this.logger(`Meta Agent - Found reasoning summary: ${!!reasoningSummary}, encrypted reasoning: ${!!encryptedReasoning}`);
+      const parsedData = parseAndValidateLlmJson(text, zodSchema, (m) => this.logger(m));
+      this.logger(`\u2705 Response validated successfully with Zod schema`);
+      const tokenUsage = this.extractTokenUsage(response);
+      if (parsedData) {
+        this.logReply(parsedData, reasoningSummary, tokenUsage);
+      }
+      return [parsedData, reasoningSummary, tokenUsage, encryptedReasoning];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  /**
+   * Plain-text ask: no JSON mode and no schema appended to the prompt.
+   * Reasoning extraction and token accounting are identical to askWithZodSchema.
+   */
+  async doAskText(messages) {
+    try {
+      const input = this.buildResponsesInput(this.prepareMessages(messages));
+      this.logAsking(messages);
+      this.logMessages(messages);
+      const response = await this.createResponse(input);
+      const { text, reasoningSummary, encryptedReasoning } = this.extractResponseParts(response);
+      if (!text) {
+        throw new Error(this.errorMessages.emptyResponse);
+      }
+      const tokenUsage = this.extractTokenUsage(response);
+      this.logReply(text, reasoningSummary, tokenUsage);
+      return [text, reasoningSummary, tokenUsage, encryptedReasoning];
+    } catch (error) {
+      this.logger(this.logTemplates.error(this.name, error));
+      throw new Error(this.errorMessages.apiError(error));
+    }
+  }
+  createResponse(input, zodSchema) {
+    return this.client.responses.create({
+      model: this.model,
+      temperature: this.temperature,
+      input,
+      // Reasoning bills against the output budget on top of the visible answer, so this
+      // has to cover both. Raise it with a catalog `maxOutputTokens` override if Muse
+      // ever starts truncating.
+      max_output_tokens: this.maxOutputTokens,
+      // Effort read at request time so a per-instance override (story generation runs
+      // deeper) is honored; omitted entirely when nothing is pinned, leaving Meta's default.
+      reasoning: {
+        ...this.reasoningEffort ? { effort: toMetaEffort(this.reasoningEffort) } : {},
+        summary: "auto"
+      },
+      // We manage conversation state ourselves; encrypted reasoning is only
+      // returned for unstored responses.
+      store: false,
+      include: ["reasoning.encrypted_content"],
+      prompt_cache_key: this.promptCacheKey,
+      ...zodSchema ? {
+        text: {
+          format: {
+            type: "json_schema",
+            name: "response_schema",
+            schema: ZodSchemaConverter.toJsonSchema(zodSchema),
+            strict: false
+          }
+        }
+      } : {}
+    });
+  }
+  /**
+   * 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.
+   */
+  buildResponsesInput(messages) {
+    const input = [];
+    for (const msg of messages) {
+      if (msg.role === "assistant" && msg.metaEncryptedReasoning) {
+        try {
+          const reasoningItems = JSON.parse(msg.metaEncryptedReasoning);
+          if (Array.isArray(reasoningItems)) {
+            input.push(...reasoningItems);
+          }
+        } catch {
+          this.logger(`Failed to parse stored encrypted reasoning, replaying message without it`);
+        }
+      }
+      input.push({ role: msg.role, content: msg.content });
+    }
+    if (input.length > 0 && input[0].role !== "system") {
+      input.unshift({ role: "system", content: this.instruction });
+    } else if (input.length > 0 && input[0].role === "system") {
+      input[0].content = `${this.instruction}
+
+${input[0].content}`;
+    }
+    return input;
+  }
+  /**
+   * Walks the response output items: reasoning items yield the human-readable summary
+   * plus the encrypted items (serialized for storage/replay); message items yield text.
+   */
+  extractResponseParts(response) {
+    const textParts = [];
+    const summaryParts = [];
+    const encryptedItems = [];
+    for (const item of response?.output ?? []) {
+      if (!item) {
+        continue;
+      }
+      if (item.type === "reasoning") {
+        for (const summary of item.summary ?? []) {
+          if (typeof summary?.text === "string" && summary.text) {
+            summaryParts.push(summary.text);
+          }
+        }
+        if (item.encrypted_content) {
+          encryptedItems.push(item);
+        }
+      } else if (item.type === "message") {
+        for (const part of item.content ?? []) {
+          if (part?.type === "output_text" && typeof part.text === "string") {
+            textParts.push(part.text);
+          }
+        }
+      }
+    }
+    return {
+      text: textParts.join("\n").trim(),
+      reasoningSummary: summaryParts.join("\n").trim(),
+      encryptedReasoning: encryptedItems.length > 0 ? JSON.stringify(encryptedItems) : void 0
+    };
+  }
+  extractTokenUsage(response) {
+    const usage = response?.usage;
+    if (!usage) {
+      return void 0;
+    }
+    const inputTokens = usage.input_tokens || 0;
+    const outputTokens = usage.output_tokens || 0;
+    const reasoningTokens = usage.output_tokens_details?.reasoning_tokens || 0;
+    const cachedTokens = usage.input_tokens_details?.cached_tokens || 0;
+    const cost = calculateMetaCost(this.model, inputTokens, outputTokens, cachedTokens);
+    if (reasoningTokens > 0) {
+      this.logger(`Output breakdown: ${reasoningTokens} reasoning tokens, ${outputTokens - reasoningTokens} final answer tokens, ${outputTokens} total output tokens`);
+    }
+    if (cachedTokens > 0) {
+      this.logger(`Input breakdown: ${cachedTokens} cached tokens of ${inputTokens} input tokens`);
+    }
+    return {
+      inputTokens,
+      outputTokens,
+      totalTokens: inputTokens + outputTokens,
+      costUSD: cost,
+      // Omitted when zero so we never hand Firestore an undefined value.
+      ...reasoningTokens > 0 ? { reasoningTokens } : {},
+      ...cachedTokens > 0 ? { cachedInputTokens: cachedTokens } : {}
+    };
+  }
+};
+
 // src/agents/agent-factory.ts
 var AgentFactory = class {
   static createAgent(name, instruction, llmType, apiKeys, enableThinking = false) {
@@ -4892,6 +5155,9 @@ var AgentFactory = class {
       // MiniMax M3 — adaptive thinking (the model decides per-request)
       case LLM_CONSTANTS.MINIMAX:
         return new MiniMaxAgent(name, instruction, model.modelApiName, key, model.temperature, shouldEnableThinking);
+      // Meta Muse Spark — Responses API with encrypted reasoning replay, effort from the catalog
+      case LLM_CONSTANTS.MUSE_SPARK:
+        return new MetaAgent(name, instruction, model.modelApiName, key, model.temperature, shouldEnableThinking);
       default:
         throw new Error(`Unknown Key: ${modelName}`);
     }
@@ -4934,7 +5200,9 @@ var AgentFactory = class {
   KimiAgent,
   LLM_CONSTANTS,
   MESSAGE_ROLE,
+  META_REASONING_EFFORTS,
   MODEL_PRICING,
+  MetaAgent,
   MiniMaxAgent,
   MistralAgent,
   ModelAuthenticationError,
@@ -4967,6 +5235,7 @@ var AgentFactory = class {
   calculateGoogleCost,
   calculateGrokCost,
   calculateKimiCost,
+  calculateMetaCost,
   calculateMistralCost,
   calculateModelCost,
   calculateOpenAICost,
@@ -4988,6 +5257,8 @@ var AgentFactory = class {
   extractGrokTokenUsageFromResponse,
   extractKimiTokenUsage,
   extractKimiTokenUsageFromResponse,
+  extractMetaTokenUsage,
+  extractMetaTokenUsageFromResponse,
   extractMistralTokenUsage,
   extractMistralTokenUsageFromResponse,
   extractOpenAITokenUsage,
@@ -5019,6 +5290,7 @@ var AgentFactory = class {
   periodEnd,
   periodKey,
   safeValidateResponse,
+  setBeforeAskHook,
   setLlmLogger,
   stableHashHex,
   stripInlineThinking,
@@ -5028,6 +5300,7 @@ var AgentFactory = class {
   toFuguEffort,
   toGeminiEffort,
   toGlmEffort,
+  toMetaEffort,
   toOpenAIEffort,
   transcribeWithGemini,
   transcribeWithOpenAi,