llmist 15.14.2 → 15.15.1

package/dist/index.cjs

@@ -10625,6 +10625,7 @@ var init_builder = __esm({
       textWithGadgetsHandler;
       defaultGadgetTimeoutMs;
       gadgetExecutionMode;
+      maxGadgetsPerResponse;
       gadgetOutputLimit;
       gadgetOutputLimitPercent;
       compactionConfig;
@@ -11025,6 +11026,37 @@ var init_builder = __esm({
         this.gadgetExecutionMode = mode;
         return this;
       }
+      /**
+       * Set the maximum number of gadgets to execute per LLM response.
+       *
+       * When the limit is reached, remaining gadgets are skipped with an informative
+       * message visible to the LLM, allowing it to adjust on the next iteration.
+       * Gadgets already in-flight (executing in parallel) are allowed to complete.
+       *
+       * @param max - Maximum gadgets per response (0 = unlimited, default)
+       * @returns This builder for chaining
+       * @throws {Error} If max is negative or non-integer
+       *
+       * @example
+       * ```typescript
+       * // Limit to 5 gadgets per response
+       * LLMist.createAgent()
+       *   .withModel("sonnet")
+       *   .withGadgets(ReadFile, WriteFile, Search)
+       *   .withMaxGadgetsPerResponse(5)
+       *   .ask("Process these files...");
+       * ```
+       */
+      withMaxGadgetsPerResponse(max) {
+        if (max < 0) {
+          throw new Error("maxGadgetsPerResponse must be a non-negative number");
+        }
+        if (!Number.isInteger(max)) {
+          throw new Error("maxGadgetsPerResponse must be an integer");
+        }
+        this.maxGadgetsPerResponse = max;
+        return this;
+      }
       /**
        * Enable or disable gadget output limiting.
        *
@@ -11623,6 +11655,7 @@ ${endPrefix}`
           textWithGadgetsHandler: this.textWithGadgetsHandler,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
           gadgetExecutionMode: this.gadgetExecutionMode,
+          maxGadgetsPerResponse: this.maxGadgetsPerResponse,
           gadgetOutputLimit: this.gadgetOutputLimit,
           gadgetOutputLimitPercent: this.gadgetOutputLimitPercent,
           compactionConfig: this.compactionConfig,
@@ -11812,6 +11845,7 @@ ${endPrefix}`
           textWithGadgetsHandler: this.textWithGadgetsHandler,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
           gadgetExecutionMode: this.gadgetExecutionMode,
+          maxGadgetsPerResponse: this.maxGadgetsPerResponse,
           gadgetOutputLimit: this.gadgetOutputLimit,
           gadgetOutputLimitPercent: this.gadgetOutputLimitPercent,
           compactionConfig: this.compactionConfig,
@@ -13449,6 +13483,10 @@ var init_stream_processor = __esm({
       priorFailedInvocations;
       // Parent observer hooks for subagent visibility
       parentObservers;
+      // Gadget limiting per response
+      maxGadgetsPerResponse;
+      gadgetStartedCount = 0;
+      limitExceeded = false;
       constructor(options) {
         this.iteration = options.iteration;
         this.registry = options.registry;
@@ -13462,6 +13500,7 @@ var init_stream_processor = __esm({
         this.priorFailedInvocations = options.priorFailedInvocations ?? /* @__PURE__ */ new Set();
         this.subagentConfig = options.subagentConfig;
         this.parentObservers = options.parentObservers;
+        this.maxGadgetsPerResponse = options.maxGadgetsPerResponse ?? 0;
         this.parser = new GadgetCallParser({
           startPrefix: options.gadgetStartPrefix,
           endPrefix: options.gadgetEndPrefix,
@@ -13575,6 +13614,10 @@ var init_stream_processor = __esm({
               }
             }
           }
+          if (this.limitExceeded) {
+            this.logger.info("Breaking stream loop due to gadget limit");
+            break;
+          }
         }
         yield { type: "llm_response_end", finishReason, usage };
         for (const event of this.parser.finalize()) {
@@ -13678,6 +13721,9 @@ var init_stream_processor = __esm({
        * enabling real-time UI feedback.
        */
       async *processGadgetCallGenerator(call) {
+        if (this.limitExceeded) {
+          return;
+        }
         yield { type: "gadget_call", call };
         if (this.tree) {
           this.tree.addGadget({
@@ -13757,6 +13803,15 @@ var init_stream_processor = __esm({
             this.gadgetsAwaitingDependencies.set(call.invocationId, call);
             return;
           }
+          const limitCheckGen2 = this.checkGadgetLimitExceeded(call);
+          let limitResult2 = await limitCheckGen2.next();
+          while (!limitResult2.done) {
+            yield limitResult2.value;
+            limitResult2 = await limitCheckGen2.next();
+          }
+          if (limitResult2.value === true) {
+            return;
+          }
           for await (const evt of this.executeGadgetGenerator(call)) {
             yield evt;
           }
@@ -13765,6 +13820,15 @@ var init_stream_processor = __esm({
           }
           return;
         }
+        const limitCheckGen = this.checkGadgetLimitExceeded(call);
+        let limitResult = await limitCheckGen.next();
+        while (!limitResult.done) {
+          yield limitResult.value;
+          limitResult = await limitCheckGen.next();
+        }
+        if (limitResult.value === true) {
+          return;
+        }
         const limit = this.getConcurrencyLimit(call.gadgetName);
         const activeCount = this.activeCountByGadget.get(call.gadgetName) ?? 0;
         if (limit > 0 && activeCount >= limit) {
@@ -14200,6 +14264,81 @@ var init_stream_processor = __esm({
         }
         return events;
       }
+      /**
+       * Check if gadget execution should be skipped due to maxGadgetsPerResponse limit.
+       * If limit is exceeded, yields skip events and returns true.
+       * If execution can proceed, increments counter and returns false.
+       *
+       * @returns true if gadget should be skipped, false if execution can proceed
+       */
+      async *checkGadgetLimitExceeded(call) {
+        if (this.maxGadgetsPerResponse <= 0) {
+          this.gadgetStartedCount++;
+          return false;
+        }
+        if (this.gadgetStartedCount >= this.maxGadgetsPerResponse) {
+          const errorMessage = `Gadget limit (${this.maxGadgetsPerResponse}) exceeded. Consider calling fewer gadgets per response.`;
+          this.limitExceeded = true;
+          this.logger.info("Gadget limit exceeded, stopping stream processing", {
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            limit: this.maxGadgetsPerResponse,
+            currentCount: this.gadgetStartedCount
+          });
+          this.failedInvocations.add(call.invocationId);
+          if (this.tree) {
+            const gadgetNode = this.tree.getNodeByInvocationId(call.invocationId);
+            if (gadgetNode) {
+              this.tree.skipGadget(
+                gadgetNode.id,
+                "maxGadgetsPerResponse",
+                errorMessage,
+                "limit_exceeded"
+              );
+            }
+          }
+          const skipEvent = {
+            type: "gadget_skipped",
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            parameters: call.parameters ?? {},
+            failedDependency: "maxGadgetsPerResponse",
+            failedDependencyError: errorMessage
+          };
+          yield skipEvent;
+          const limitSkipNode = this.tree?.getNodeByInvocationId(call.invocationId);
+          const limitSkipSubagentContext = this.tree && limitSkipNode ? getSubagentContextForNode(this.tree, limitSkipNode.id) : void 0;
+          if (this.hooks.observers?.onGadgetSkipped) {
+            const context = {
+              iteration: this.iteration,
+              gadgetName: call.gadgetName,
+              invocationId: call.invocationId,
+              parameters: call.parameters ?? {},
+              failedDependency: "maxGadgetsPerResponse",
+              failedDependencyError: errorMessage,
+              logger: this.logger,
+              subagentContext: limitSkipSubagentContext
+            };
+            await this.safeObserve(() => this.hooks.observers.onGadgetSkipped(context));
+          }
+          if (this.parentObservers?.onGadgetSkipped) {
+            const context = {
+              iteration: this.iteration,
+              gadgetName: call.gadgetName,
+              invocationId: call.invocationId,
+              parameters: call.parameters ?? {},
+              failedDependency: "maxGadgetsPerResponse",
+              failedDependencyError: errorMessage,
+              logger: this.logger,
+              subagentContext: limitSkipSubagentContext
+            };
+            await this.safeObserve(() => this.parentObservers.onGadgetSkipped(context));
+          }
+          return true;
+        }
+        this.gadgetStartedCount++;
+        return false;
+      }
       /**
        * Process pending gadgets whose dependencies are now satisfied.
        * Yields events in real-time as gadgets complete.
@@ -14208,6 +14347,9 @@ var init_stream_processor = __esm({
        * but results are yielded as they become available.
        */
       async *processPendingGadgetsGenerator() {
+        if (this.limitExceeded) {
+          return;
+        }
         let progress = true;
         while (progress && this.gadgetsAwaitingDependencies.size > 0) {
           progress = false;
@@ -14246,6 +14388,15 @@ var init_stream_processor = __esm({
                 invocationIds: readyToExecute.map((c) => c.invocationId)
               });
               for (const call of readyToExecute) {
+                const limitCheckGen = this.checkGadgetLimitExceeded(call);
+                let limitResult = await limitCheckGen.next();
+                while (!limitResult.done) {
+                  yield limitResult.value;
+                  limitResult = await limitCheckGen.next();
+                }
+                if (limitResult.value === true) {
+                  continue;
+                }
                 for await (const evt of this.executeGadgetGenerator(call)) {
                   yield evt;
                 }
@@ -14258,6 +14409,15 @@ var init_stream_processor = __esm({
               const eventSets = await Promise.all(
                 readyToExecute.map(async (call) => {
                   const events = [];
+                  const limitCheckGen = this.checkGadgetLimitExceeded(call);
+                  let limitResult = await limitCheckGen.next();
+                  while (!limitResult.done) {
+                    events.push(limitResult.value);
+                    limitResult = await limitCheckGen.next();
+                  }
+                  if (limitResult.value === true) {
+                    return events;
+                  }
                   for await (const evt of this.executeGadgetGenerator(call)) {
                     events.push(evt);
                   }
@@ -14443,6 +14603,8 @@ var init_agent = __esm({
       // Subagent configuration
       agentContextConfig;
       subagentConfig;
+      // Gadget limiting
+      maxGadgetsPerResponse;
       // Counter for generating synthetic invocation IDs for wrapped text content
       syntheticInvocationCounter = 0;
       // Cross-iteration dependency tracking - allows gadgets to depend on results from prior iterations
@@ -14543,6 +14705,7 @@ var init_agent = __esm({
           temperature: this.temperature
         };
         this.subagentConfig = options.subagentConfig;
+        this.maxGadgetsPerResponse = options.maxGadgetsPerResponse ?? 0;
         this.tree = options.parentTree ?? new ExecutionTree();
         this.parentNodeId = options.parentNodeId ?? null;
         this.baseDepth = options.baseDepth ?? 0;
@@ -14830,7 +14993,9 @@ var init_agent = __esm({
                     parentObservers: this.parentObservers,
                     // Shared rate limit tracker and retry config for subagents
                     rateLimitTracker: this.rateLimitTracker,
-                    retryConfig: this.retryConfig
+                    retryConfig: this.retryConfig,
+                    // Gadget limiting
+                    maxGadgetsPerResponse: this.maxGadgetsPerResponse
                   });
                   for await (const event of processor.process(stream2)) {
                     if (event.type === "stream_complete") {