llmist 15.7.1 → 15.8.1

package/dist/index.cjs

@@ -1487,6 +1487,8 @@ var init_rate_limit = __esm({
       dailyTokens = 0;
       /** Date string (YYYY-MM-DD UTC) for daily reset tracking */
       dailyResetDate;
+      /** Count of pending reservations (for backward compatibility) */
+      pendingReservations = 0;
       constructor(config) {
         this.config = resolveRateLimitConfig(config);
         this.dailyResetDate = this.getCurrentDateUTC();
@@ -1494,13 +1496,21 @@ var init_rate_limit = __esm({
       /**
        * Record a completed request with its token usage.
        *
+       * If reserveRequest() was called before the LLM call (recommended for concurrent
+       * scenarios), the request timestamp was already recorded. Otherwise, this method
+       * will add it for backward compatibility.
+       *
        * @param inputTokens - Number of input tokens used
        * @param outputTokens - Number of output tokens generated
        */
       recordUsage(inputTokens, outputTokens) {
         const now = Date.now();
         const totalTokens = inputTokens + outputTokens;
-        this.requestTimestamps.push(now);
+        if (this.pendingReservations > 0) {
+          this.pendingReservations--;
+        } else {
+          this.requestTimestamps.push(now);
+        }
         this.tokenUsage.push({ timestamp: now, tokens: totalTokens });
         this.checkDailyReset();
         this.dailyTokens += totalTokens;
@@ -1632,6 +1642,7 @@ var init_rate_limit = __esm({
         this.tokenUsage = [];
         this.dailyTokens = 0;
         this.dailyResetDate = this.getCurrentDateUTC();
+        this.pendingReservations = 0;
       }
       /**
        * Update configuration dynamically.
@@ -1642,6 +1653,37 @@ var init_rate_limit = __esm({
       updateConfig(config) {
         this.config = resolveRateLimitConfig(config);
       }
+      /**
+       * Reserve a request slot before making an LLM call.
+       *
+       * This is critical for concurrent subagents sharing a rate limiter.
+       * Without reservation, multiple subagents checking getRequiredDelayMs()
+       * simultaneously would all see zero usage and proceed, causing rate limit errors.
+       *
+       * Call this AFTER waiting for getRequiredDelayMs() but BEFORE making the LLM call.
+       * The reservation ensures subsequent concurrent checks see the pending request.
+       *
+       * @example
+       * ```typescript
+       * // Proactive rate limiting with reservation
+       * const delay = tracker.getRequiredDelayMs();
+       * if (delay > 0) await sleep(delay);
+       *
+       * tracker.reserveRequest(); // Claim slot BEFORE making call
+       * try {
+       *   const result = await llm.call();
+       *   tracker.recordUsage(result.inputTokens, result.outputTokens);
+       * } catch (error) {
+       *   // Request already reserved; recordUsage updates token count
+       *   throw error;
+       * }
+       * ```
+       */
+      reserveRequest() {
+        const now = Date.now();
+        this.requestTimestamps.push(now);
+        this.pendingReservations++;
+      }
       // ─────────────────────────────────────────────────────────────────────────
       // Private methods
       // ─────────────────────────────────────────────────────────────────────────
@@ -9131,6 +9173,13 @@ var init_builder = __esm({
       // When a gadget calls withParentContext(ctx), these observers are
       // also called for gadget events in the subagent
       parentObservers;
+      // Shared rate limit tracker from parent for coordinated throttling
+      // When a gadget calls withParentContext(ctx), this tracker is shared
+      // so all agents in the tree respect aggregate RPM/TPM limits
+      sharedRateLimitTracker;
+      // Shared retry config from parent for consistent backoff behavior
+      // When a gadget calls withParentContext(ctx), this config is shared
+      sharedRetryConfig;
       constructor(client) {
         this.client = client;
       }
@@ -9777,6 +9826,12 @@ var init_builder = __esm({
         if (ctx.parentObservers && !this.parentObservers) {
           this.parentObservers = ctx.parentObservers;
         }
+        if (ctx.rateLimitTracker && !this.sharedRateLimitTracker) {
+          this.sharedRateLimitTracker = ctx.rateLimitTracker;
+        }
+        if (ctx.retryConfig && !this.sharedRetryConfig) {
+          this.sharedRetryConfig = ctx.retryConfig;
+        }
         return this;
       }
       /**
@@ -10156,7 +10211,10 @@ ${endPrefix}`
           parentNodeId: this.parentContext?.nodeId,
           baseDepth: this.parentContext ? (this.parentContext.depth ?? 0) + 1 : 0,
           // Parent observer hooks for subagent visibility
-          parentObservers: this.parentObservers
+          parentObservers: this.parentObservers,
+          // Shared rate limit tracker and retry config (for coordinated limits across subagents)
+          sharedRateLimitTracker: this.sharedRateLimitTracker,
+          sharedRetryConfig: this.sharedRetryConfig
         };
         return new Agent(AGENT_INTERNAL_KEY, options);
       }
@@ -11068,7 +11126,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) {
+      constructor(registry, requestHumanInput, logger, defaultGadgetTimeoutMs, errorFormatterOptions, client, mediaStore, agentConfig, subagentConfig, tree, parentNodeId, baseDepth, parentObservers, currentObservers, rateLimitTracker, retryConfig) {
         this.registry = registry;
         this.requestHumanInput = requestHumanInput;
         this.defaultGadgetTimeoutMs = defaultGadgetTimeoutMs;
@@ -11081,6 +11139,8 @@ var init_executor = __esm({
         this.baseDepth = baseDepth;
         this.parentObservers = parentObservers;
         this.currentObservers = currentObservers;
+        this.rateLimitTracker = rateLimitTracker;
+        this.retryConfig = retryConfig;
         this.logger = logger ?? createLogger({ name: "llmist:executor" });
         this.errorFormatter = new GadgetExecutionErrorFormatter(errorFormatterOptions);
         this.argPrefix = errorFormatterOptions?.argPrefix ?? GADGET_ARG_PREFIX;
@@ -11251,7 +11311,11 @@ var init_executor = __esm({
             // When a subagent uses withParentContext(ctx), it will receive these
             // and call them for gadget events in addition to its own hooks
             // Merge child and parent observers so both get called (child first, then parent)
-            parentObservers: mergeObservers(this.currentObservers, this.parentObservers)
+            parentObservers: mergeObservers(this.currentObservers, this.parentObservers),
+            // Shared rate limit tracker for coordinated throttling across subagents
+            rateLimitTracker: this.rateLimitTracker,
+            // Shared retry config for consistent backoff behavior across subagents
+            retryConfig: this.retryConfig
           };
           let rawResult;
           if (timeoutMs && timeoutMs > 0) {
@@ -11792,7 +11856,11 @@ var init_stream_processor = __esm({
           // Parent observer hooks for subagent visibility
           options.parentObservers,
           // Current agent's observers for subagent inheritance
-          options.hooks?.observers
+          options.hooks?.observers,
+          // Shared rate limit tracker for coordinated throttling across subagents
+          options.rateLimitTracker,
+          // Shared retry config for consistent backoff behavior across subagents
+          options.retryConfig
         );
       }
       /**
@@ -12799,10 +12867,14 @@ var init_agent = __esm({
           );
         }
         this.signal = options.signal;
-        this.retryConfig = resolveRetryConfig(options.retryConfig);
-        const rateLimitConfig = resolveRateLimitConfig(options.rateLimitConfig);
-        if (rateLimitConfig.enabled) {
-          this.rateLimitTracker = new RateLimitTracker(options.rateLimitConfig);
+        this.retryConfig = options.sharedRetryConfig ?? resolveRetryConfig(options.retryConfig);
+        if (options.sharedRateLimitTracker) {
+          this.rateLimitTracker = options.sharedRateLimitTracker;
+        } else {
+          const rateLimitConfig = resolveRateLimitConfig(options.rateLimitConfig);
+          if (rateLimitConfig.enabled) {
+            this.rateLimitTracker = new RateLimitTracker(options.rateLimitConfig);
+          }
         }
         this.agentContextConfig = {
           model: this.model,
@@ -13092,7 +13164,10 @@ var init_agent = __esm({
                     priorCompletedInvocations: this.completedInvocationIds,
                     priorFailedInvocations: this.failedInvocationIds,
                     // Parent observer hooks for subagent visibility
-                    parentObservers: this.parentObservers
+                    parentObservers: this.parentObservers,
+                    // Shared rate limit tracker and retry config for subagents
+                    rateLimitTracker: this.rateLimitTracker,
+                    retryConfig: this.retryConfig
                   });
                   for await (const event of processor.process(stream2)) {
                     if (event.type === "stream_complete") {
@@ -13312,6 +13387,7 @@ var init_agent = __esm({
             });
             await this.sleep(throttleDelay);
           }
+          this.rateLimitTracker.reserveRequest();
         }
         return this.client.stream(llmOptions);
       }