llmist 15.18.1 → 16.0.0

package/dist/index.cjs

@@ -360,7 +360,8 @@ var init_execution_tree = __esm({
             result: params.result ?? "",
             executionTimeMs: params.executionTimeMs ?? 0,
             cost: params.cost,
-            media: params.media
+            media: params.media,
+            storedMedia: params.storedMedia
           });
         }
       }
@@ -1278,8 +1279,9 @@ Produces: { "items": ["first", "second"] }`);
        * @param invocationId - Invocation ID (shown to LLM so it can reference for dependencies)
        * @param media - Optional media outputs from the gadget
        * @param mediaIds - Optional IDs for the media outputs
+       * @param storedMedia - Optional stored media info including file paths
        */
-      addGadgetCallResult(gadget, parameters, result, invocationId, media, mediaIds) {
+      addGadgetCallResult(gadget, parameters, result, invocationId, media, mediaIds, storedMedia) {
         const paramStr = this.formatBlockParameters(parameters, "");
         this.messages.push({
           role: "assistant",
@@ -1288,7 +1290,11 @@ ${paramStr}
 ${this.endPrefix}`
         });
         if (media && media.length > 0 && mediaIds && mediaIds.length > 0) {
-          const idRefs = media.map((m, i) => `[Media: ${mediaIds[i]} (${m.kind})]`).join("\n");
+          const idRefs = media.map((m, i) => {
+            const path = storedMedia?.[i]?.path;
+            const pathInfo = path ? ` \u2192 saved to: ${path}` : "";
+            return `[Media: ${mediaIds[i]} (${m.kind})${pathInfo}]`;
+          }).join("\n");
           const textWithIds = `Result (${invocationId}): ${result}
 ${idRefs}`;
           const parts = [text(textWithIds)];
@@ -2347,7 +2353,7 @@ function createLogger(options = {}) {
     }
   }
   const useFileLogging = Boolean(sharedLogFileStream);
-  const logger = new import_tslog.Logger({
+  const logger2 = new import_tslog.Logger({
     name,
     minLevel,
     type: useFileLogging ? "pretty" : defaultType,
@@ -2373,7 +2379,7 @@ function createLogger(options = {}) {
       }
     } : void 0
   });
-  return logger;
+  return logger2;
 }
 var import_node_fs, import_node_path2, import_tslog, LEVEL_NAME_TO_ID, sharedLogFilePath, sharedLogFileStream, logFileInitialized, writeErrorCount, writeErrorReported, MAX_WRITE_ERRORS_BEFORE_DISABLE, LOG_TEMPLATE, defaultLogger;
 var init_logger = __esm({
@@ -2765,6 +2771,17 @@ var init_gadget = __esm({
        * ```
        */
       maxConcurrent;
+      /**
+       * If true, this gadget must execute alone — no other gadgets in the same
+       * LLM response can run in parallel. When an exclusive gadget arrives and
+       * other gadgets are already in-flight, it is deferred until they complete.
+       *
+       * Use for gadgets that terminate the agent loop (e.g., Finish), where
+       * sibling tool results must be visible to the LLM before the loop ends.
+       *
+       * This is a safety floor: external config cannot weaken it.
+       */
+      exclusive;
       /**
        * Throws an AbortException if the execution has been aborted.
        *
@@ -3601,14 +3618,15 @@ var init_conversation_manager = __esm({
       addAssistantMessage(content) {
         this.historyBuilder.addAssistant(content);
       }
-      addGadgetCallResult(gadgetName, parameters, result, invocationId, media, mediaIds) {
+      addGadgetCallResult(gadgetName, parameters, result, invocationId, media, mediaIds, storedMedia) {
         this.historyBuilder.addGadgetCallResult(
           gadgetName,
           parameters,
           result,
           invocationId,
           media,
-          mediaIds
+          mediaIds,
+          storedMedia
         );
       }
       getMessages() {
@@ -9638,6 +9656,106 @@ var init_openrouter_models = __esm({
   }
 });
 
+// src/providers/openrouter-speech-models.ts
+function getOpenRouterSpeechModelSpec(modelId) {
+  return openrouterSpeechModels.find((m) => m.modelId === modelId);
+}
+function isOpenRouterSpeechModel(modelId) {
+  return openrouterSpeechModels.some((m) => m.modelId === modelId);
+}
+function calculateOpenRouterSpeechCost(modelId, characterCount, estimatedMinutes) {
+  const spec = getOpenRouterSpeechModelSpec(modelId);
+  if (!spec) return void 0;
+  if (spec.pricing.perMinute !== void 0) {
+    const minutes = estimatedMinutes ?? characterCount / 750;
+    return minutes * spec.pricing.perMinute;
+  }
+  if (spec.pricing.perInputToken !== void 0) {
+    const estimatedTokens = Math.ceil(characterCount / 4);
+    const inputCost = estimatedTokens * spec.pricing.perInputToken;
+    if (spec.pricing.perAudioOutputToken !== void 0 && estimatedMinutes !== void 0) {
+      const audioTokens = estimatedMinutes * 60 * 100;
+      return inputCost + audioTokens * spec.pricing.perAudioOutputToken;
+    }
+    return inputCost;
+  }
+  return void 0;
+}
+var OPENROUTER_TTS_VOICES, OPENROUTER_TTS_FORMATS, openrouterSpeechModels;
+var init_openrouter_speech_models = __esm({
+  "src/providers/openrouter-speech-models.ts"() {
+    "use strict";
+    OPENROUTER_TTS_VOICES = ["alloy", "echo", "fable", "onyx", "nova", "shimmer"];
+    OPENROUTER_TTS_FORMATS = ["pcm16"];
+    openrouterSpeechModels = [
+      {
+        provider: "openrouter",
+        modelId: "openai/gpt-4o-audio-preview",
+        displayName: "GPT-4o Audio Preview (via OpenRouter)",
+        pricing: {
+          perInputToken: 25e-7,
+          perAudioOutputToken: 1e-5,
+          perMinute: 0.06
+        },
+        voices: [...OPENROUTER_TTS_VOICES],
+        formats: OPENROUTER_TTS_FORMATS,
+        maxInputLength: 128e3,
+        defaultVoice: "alloy",
+        defaultFormat: "pcm16",
+        features: {
+          voiceInstructions: true
+        }
+      },
+      {
+        provider: "openrouter",
+        modelId: "openai/gpt-audio",
+        displayName: "GPT Audio (via OpenRouter)",
+        pricing: {
+          // Token-based pricing with audio output
+          perInputToken: 25e-7,
+          // $2.50 per 1M
+          perAudioOutputToken: 64e-6,
+          // ~$64 per 1M audio tokens
+          // Approximate per-minute cost for estimation
+          perMinute: 0.08
+        },
+        voices: [...OPENROUTER_TTS_VOICES],
+        formats: OPENROUTER_TTS_FORMATS,
+        maxInputLength: 128e3,
+        // 128K context
+        defaultVoice: "alloy",
+        defaultFormat: "pcm16",
+        features: {
+          voiceInstructions: true
+        }
+      },
+      {
+        provider: "openrouter",
+        modelId: "openai/gpt-audio-mini",
+        displayName: "GPT Audio Mini (via OpenRouter)",
+        pricing: {
+          // More affordable option
+          perInputToken: 6e-7,
+          // $0.60 per 1M
+          perAudioOutputToken: 6e-7,
+          // $0.60 per 1M audio tokens
+          // Approximate per-minute cost for estimation
+          perMinute: 0.015
+        },
+        voices: [...OPENROUTER_TTS_VOICES],
+        formats: OPENROUTER_TTS_FORMATS,
+        maxInputLength: 128e3,
+        // 128K context
+        defaultVoice: "alloy",
+        defaultFormat: "pcm16",
+        features: {
+          voiceInstructions: true
+        }
+      }
+    ];
+  }
+});
+
 // src/providers/openrouter.ts
 function createOpenRouterProviderFromEnv() {
   const apiKey = readEnvVar("OPENROUTER_API_KEY");
@@ -9658,14 +9776,18 @@ function createOpenRouterProviderFromEnv() {
   });
   return new OpenRouterProvider(client, config);
 }
-var import_openai4, OPENROUTER_EFFORT_MAP, OpenRouterProvider;
+var import_openai4, logger, OPENROUTER_EFFORT_MAP, OpenRouterProvider;
 var init_openrouter = __esm({
   "src/providers/openrouter.ts"() {
     "use strict";
     import_openai4 = __toESM(require("openai"), 1);
+    init_model_shortcuts();
+    init_logger();
     init_openai_compatible_provider();
     init_openrouter_models();
+    init_openrouter_speech_models();
     init_utils();
+    logger = createLogger({ name: "openrouter" });
     OPENROUTER_EFFORT_MAP = {
       none: "none",
       low: "low",
@@ -9771,6 +9893,128 @@ Original error: ${error.message}`
         }
         return error;
       }
+      // =========================================================================
+      // Speech Generation (TTS via Chat Completions with Audio Modality)
+      // =========================================================================
+      /**
+       * Get speech model specifications for OpenRouter.
+       */
+      getSpeechModelSpecs() {
+        return openrouterSpeechModels;
+      }
+      /**
+       * Check if this provider supports speech generation for a given model.
+       * Handles both prefixed (openrouter:openai/gpt-audio-mini) and unprefixed model IDs.
+       */
+      supportsSpeechGeneration(modelId) {
+        const bareModelId = getModelId(modelId);
+        return isOpenRouterSpeechModel(bareModelId);
+      }
+      /**
+       * Generate speech audio from text using OpenRouter's audio-capable models.
+       *
+       * OpenRouter TTS works via chat completions with audio modality, not a
+       * dedicated TTS endpoint. The model receives a prompt asking it to say
+       * the text, and returns audio data via streaming.
+       *
+       * @param options - Speech generation options
+       * @returns Promise resolving to the generation result with audio and cost
+       * @throws Error if model is unknown, voice/format are invalid, or no audio is returned
+       */
+      async generateSpeech(options) {
+        const client = this.client;
+        const bareModelId = getModelId(options.model);
+        const spec = getOpenRouterSpeechModelSpec(bareModelId);
+        if (!spec) {
+          throw new Error(`Unknown OpenRouter TTS model: ${options.model}`);
+        }
+        const voice = options.voice ?? spec.defaultVoice ?? "alloy";
+        if (!spec.voices.includes(voice)) {
+          throw new Error(
+            `Invalid voice "${voice}" for ${options.model}. Valid voices: ${spec.voices.join(", ")}`
+          );
+        }
+        const format2 = options.responseFormat ?? spec.defaultFormat ?? "mp3";
+        if (!spec.formats.includes(format2)) {
+          throw new Error(
+            `Invalid format "${format2}" for ${options.model}. Valid formats: ${spec.formats.join(", ")}`
+          );
+        }
+        logger.debug("TTS request", {
+          model: bareModelId,
+          voice,
+          format: format2,
+          inputLength: options.input.length
+        });
+        try {
+          const response = await client.chat.completions.create({
+            model: bareModelId,
+            messages: [
+              {
+                role: "user",
+                content: `Please say the following text exactly: "${options.input}"`
+              }
+            ],
+            // OpenRouter-specific parameters for audio output
+            // Note: OpenRouter TTS via chat completions does NOT support the speed parameter
+            // (unlike OpenAI's dedicated /audio/speech endpoint which does)
+            modalities: ["text", "audio"],
+            audio: {
+              voice,
+              format: format2
+            },
+            stream: true
+          });
+          const audioChunks = [];
+          for await (const chunk of response) {
+            const delta = chunk.choices[0]?.delta;
+            if (!delta || typeof delta !== "object") continue;
+            const audioObj = delta.audio;
+            if (!audioObj || typeof audioObj !== "object") continue;
+            const audioData = audioObj.data;
+            if (typeof audioData !== "string" || audioData.length === 0) continue;
+            const decoded = Buffer.from(audioData, "base64");
+            if (decoded.length === 0) {
+              throw new Error("Invalid base64 audio data received from OpenRouter");
+            }
+            audioChunks.push(decoded);
+          }
+          const audioBuffer = Buffer.concat(audioChunks);
+          if (audioBuffer.length === 0) {
+            throw new Error(
+              "OpenRouter TTS returned no audio data. The model may have failed to generate audio or the stream was interrupted."
+            );
+          }
+          const cost = calculateOpenRouterSpeechCost(bareModelId, options.input.length);
+          return {
+            // Use Uint8Array for clean ArrayBuffer extraction (safer than buffer.slice for Node.js Buffer)
+            audio: new Uint8Array(audioBuffer).buffer,
+            model: options.model,
+            usage: {
+              characterCount: options.input.length
+            },
+            cost,
+            format: format2
+          };
+        } catch (error) {
+          const err = error;
+          const apiError = err.error?.message || err.error?.code || "";
+          const bodyInfo = err.body ? JSON.stringify(err.body) : "";
+          const details = apiError || bodyInfo || err.message || "Unknown error";
+          logger.debug("TTS error", {
+            model: bareModelId,
+            voice,
+            format: format2,
+            status: err.status,
+            error: err.error,
+            body: err.body,
+            message: err.message
+          });
+          throw new Error(
+            `OpenRouter TTS failed for model ${bareModelId}: ${details}` + (err.status ? ` (HTTP ${err.status})` : "")
+          );
+        }
+      }
     };
   }
 });
@@ -10749,8 +10993,8 @@ var init_builder = __esm({
        * @param logger - Logger instance
        * @returns This builder for chaining
        */
-      withLogger(logger) {
-        this.logger = logger;
+      withLogger(logger2) {
+        this.logger = logger2;
         return this;
       }
       /**
@@ -12785,6 +13029,7 @@ function Gadget(config) {
     timeoutMs = config.timeoutMs;
     examples = config.examples;
     maxConcurrent = config.maxConcurrent;
+    exclusive = config.exclusive;
     /**
      * Type helper property for accessing inferred parameter type.
      * This is used in the execute method signature: `execute(params: this['params'])`
@@ -12834,7 +13079,7 @@ var init_executor = __esm({
     init_parser();
     init_typed_gadget();
     GadgetExecutor = class {
-      constructor(registry, requestHumanInput, logger, defaultGadgetTimeoutMs, errorFormatterOptions, client, mediaStore, agentConfig, subagentConfig, tree, parentNodeId, baseDepth, parentObservers, currentObservers, rateLimitTracker, retryConfig) {
+      constructor(registry, requestHumanInput, logger2, defaultGadgetTimeoutMs, errorFormatterOptions, client, mediaStore, agentConfig, subagentConfig, tree, parentNodeId, baseDepth, parentObservers, currentObservers, rateLimitTracker, retryConfig) {
         this.registry = registry;
         this.requestHumanInput = requestHumanInput;
         this.defaultGadgetTimeoutMs = defaultGadgetTimeoutMs;
@@ -12849,7 +13094,7 @@ var init_executor = __esm({
         this.currentObservers = currentObservers;
         this.rateLimitTracker = rateLimitTracker;
         this.retryConfig = retryConfig;
-        this.logger = logger ?? createLogger({ name: "llmist:executor" });
+        this.logger = logger2 ?? createLogger({ name: "llmist:executor" });
         this.errorFormatter = new GadgetExecutionErrorFormatter(errorFormatterOptions);
         this.argPrefix = errorFormatterOptions?.argPrefix ?? GADGET_ARG_PREFIX;
       }
@@ -13249,22 +13494,22 @@ function getSubagentContextForNode(tree, nodeId) {
     depth: node.depth
   };
 }
-async function safeObserve(fn, logger, eventType) {
+async function safeObserve(fn, logger2, eventType) {
   try {
     await fn();
   } catch (error) {
-    logger.warn(`Observer error in ${eventType}:`, error);
+    logger2.warn(`Observer error in ${eventType}:`, error);
   }
 }
-function chainObserverCall(chainMap, key, fn, logger, eventType, cleanup = false) {
+function chainObserverCall(chainMap, key, fn, logger2, eventType, cleanup = false) {
   const previousPromise = chainMap.get(key) ?? Promise.resolve();
-  const newPromise = previousPromise.then(() => safeObserve(fn, logger, eventType));
+  const newPromise = previousPromise.then(() => safeObserve(fn, logger2, eventType));
   chainMap.set(key, newPromise);
   if (cleanup) {
     newPromise.finally(() => chainMap.delete(key));
   }
 }
-function bridgeTreeToHooks(tree, hooks, logger) {
+function bridgeTreeToHooks(tree, hooks, logger2) {
   const gadgetPromiseChains = /* @__PURE__ */ new Map();
   const llmPromiseChains = /* @__PURE__ */ new Map();
   return tree.onAll((event) => {
@@ -13286,14 +13531,14 @@ function bridgeTreeToHooks(tree, hooks, logger) {
             gadgetName: gadgetEvent.name,
             invocationId: gadgetEvent.invocationId,
             parameters: gadgetNode?.parameters ?? {},
-            logger,
+            logger: logger2,
             subagentContext
           };
           chainObserverCall(
             gadgetPromiseChains,
             gadgetEvent.invocationId,
             () => hooks.observers?.onGadgetExecutionStart?.(context),
-            logger,
+            logger2,
             "onGadgetExecutionStart",
             false
             // Don't cleanup - wait for completion event
@@ -13313,14 +13558,14 @@ function bridgeTreeToHooks(tree, hooks, logger) {
             finalResult: gadgetEvent.result,
             executionTimeMs: gadgetEvent.executionTimeMs,
             cost: gadgetEvent.cost,
-            logger,
+            logger: logger2,
             subagentContext
           };
           chainObserverCall(
             gadgetPromiseChains,
             gadgetEvent.invocationId,
             () => hooks.observers?.onGadgetExecutionComplete?.(context),
-            logger,
+            logger2,
             "onGadgetExecutionComplete",
             true
             // Cleanup after completion
@@ -13339,14 +13584,14 @@ function bridgeTreeToHooks(tree, hooks, logger) {
             parameters: gadgetNode?.parameters ?? {},
             error: gadgetEvent.error,
             executionTimeMs: gadgetEvent.executionTimeMs,
-            logger,
+            logger: logger2,
             subagentContext
           };
           chainObserverCall(
             gadgetPromiseChains,
             gadgetEvent.invocationId,
             () => hooks.observers?.onGadgetExecutionComplete?.(context),
-            logger,
+            logger2,
             "onGadgetExecutionComplete",
             true
             // Cleanup after error
@@ -13365,14 +13610,14 @@ function bridgeTreeToHooks(tree, hooks, logger) {
             parameters: gadgetNode?.parameters ?? {},
             failedDependency: gadgetEvent.failedDependency ?? "",
             failedDependencyError: gadgetEvent.failedDependencyError ?? gadgetEvent.error,
-            logger,
+            logger: logger2,
             subagentContext
           };
           chainObserverCall(
             gadgetPromiseChains,
             gadgetEvent.invocationId,
             () => hooks.observers?.onGadgetSkipped?.(context),
-            logger,
+            logger2,
             "onGadgetSkipped",
             true
             // Cleanup after skipped
@@ -13397,14 +13642,14 @@ function bridgeTreeToHooks(tree, hooks, logger) {
               temperature: void 0,
               maxTokens: void 0
             },
-            logger,
+            logger: logger2,
             subagentContext
           };
           chainObserverCall(
             llmPromiseChains,
             event.nodeId,
             () => hooks.observers?.onLLMCallStart?.(context),
-            logger,
+            logger2,
             "onLLMCallStart",
             false
             // Don't cleanup - wait for completion event
@@ -13429,14 +13674,14 @@ function bridgeTreeToHooks(tree, hooks, logger) {
             rawResponse: llmEvent.response,
             // Use rawResponse as finalMessage since interceptor modifications aren't available from tree events
             finalMessage: llmEvent.response,
-            logger,
+            logger: logger2,
             subagentContext
           };
           chainObserverCall(
             llmPromiseChains,
             event.nodeId,
             () => hooks.observers?.onLLMCallComplete?.(context),
-            logger,
+            logger2,
             "onLLMCallComplete",
             true
             // Cleanup after completion
@@ -13458,14 +13703,14 @@ function bridgeTreeToHooks(tree, hooks, logger) {
             },
             error: llmEvent.error,
             recovered: llmEvent.recovered,
-            logger,
+            logger: logger2,
             subagentContext
           };
           chainObserverCall(
             llmPromiseChains,
             event.nodeId,
             () => hooks.observers?.onLLMCallError?.(context),
-            logger,
+            logger2,
             "onLLMCallError",
             true
             // Cleanup after error
@@ -13525,6 +13770,9 @@ var init_stream_processor = __esm({
       activeCountByGadget = /* @__PURE__ */ new Map();
       /** Queue of gadgets waiting for a concurrency slot (per gadget name) */
       concurrencyQueue = /* @__PURE__ */ new Map();
+      // Exclusive gadget support
+      /** Queue of exclusive gadgets deferred until in-flight gadgets complete */
+      exclusiveQueue = [];
       // Cross-iteration dependency tracking
       /** Invocation IDs completed in previous iterations (read-only reference from Agent) */
       priorCompletedInvocations;
@@ -13878,6 +14126,16 @@ var init_stream_processor = __esm({
         if (limitResult.value === true) {
           return;
         }
+        const gadget = this.registry.get(call.gadgetName);
+        if (gadget?.exclusive && this.inFlightExecutions.size > 0) {
+          this.logger.debug("Deferring exclusive gadget until in-flight gadgets complete", {
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            inFlightCount: this.inFlightExecutions.size
+          });
+          this.exclusiveQueue.push(call);
+          return;
+        }
         const limit = this.getConcurrencyLimit(call.gadgetName);
         const activeCount = this.activeCountByGadget.get(call.gadgetName) ?? 0;
         if (limit > 0 && activeCount >= limit) {
@@ -14091,7 +14349,8 @@ var init_stream_processor = __esm({
                 result: result.result,
                 executionTimeMs: result.executionTimeMs,
                 cost: result.cost,
-                media: result.media
+                media: result.media,
+                storedMedia: result.storedMedia
               });
             }
           }
@@ -14163,7 +14422,7 @@ var init_stream_processor = __esm({
        * Clears the inFlightExecutions map after all gadgets complete.
        */
       async *waitForInFlightExecutions() {
-        if (this.inFlightExecutions.size === 0 && !this.hasQueuedGadgets()) {
+        if (this.inFlightExecutions.size === 0 && !this.hasQueuedGadgets() && this.exclusiveQueue.length === 0) {
           return;
         }
         this.logger.debug("Waiting for in-flight gadget executions", {
@@ -14184,6 +14443,18 @@ var init_stream_processor = __esm({
           }
         }
         this.inFlightExecutions.clear();
+        if (this.exclusiveQueue.length > 0) {
+          this.logger.debug("Processing deferred exclusive gadgets", {
+            count: this.exclusiveQueue.length
+          });
+          const queue = this.exclusiveQueue;
+          this.exclusiveQueue = [];
+          for (const call of queue) {
+            for await (const evt of this.executeGadgetGenerator(call)) {
+              yield evt;
+            }
+          }
+        }
       }
       /**
        * Check if there are any gadgets waiting in concurrency queues.
@@ -15672,7 +15943,8 @@ var init_agent = __esm({
                 gadgetResult.error ?? gadgetResult.result ?? "",
                 gadgetResult.invocationId,
                 gadgetResult.media,
-                gadgetResult.mediaIds
+                gadgetResult.mediaIds,
+                gadgetResult.storedMedia
               );
             }
           }