llmist 18.0.0 → 18.2.0

package/dist/index.cjs

@@ -1926,7 +1926,8 @@ function resolveRetryConfig(config) {
     onRetriesExhausted: config.onRetriesExhausted,
     shouldRetry: config.shouldRetry,
     respectRetryAfter: config.respectRetryAfter ?? DEFAULT_RETRY_CONFIG.respectRetryAfter,
-    maxRetryAfterMs: config.maxRetryAfterMs ?? DEFAULT_RETRY_CONFIG.maxRetryAfterMs
+    maxRetryAfterMs: config.maxRetryAfterMs ?? DEFAULT_RETRY_CONFIG.maxRetryAfterMs,
+    retryOnEmpty: config.retryOnEmpty ?? DEFAULT_RETRY_CONFIG.retryOnEmpty
   };
 }
 function getErrorStatusCode(error) {
@@ -2178,8 +2179,9 @@ var init_retry = __esm({
       factor: 2,
       randomize: true,
       respectRetryAfter: true,
-      maxRetryAfterMs: 12e4
+      maxRetryAfterMs: 12e4,
       // 2 minutes cap
+      retryOnEmpty: true
     };
   }
 });
@@ -5188,11 +5190,51 @@ var init_output_limit_manager = __esm({
   }
 });
 
+// src/core/errors.ts
+function isAbortError(error) {
+  if (!(error instanceof Error)) return false;
+  if (error.name === "AbortError") return true;
+  if (error.name === "APIConnectionAbortedError") return true;
+  if (error.name === "APIUserAbortError") return true;
+  const message = error.message.toLowerCase();
+  if (message.includes("abort")) return true;
+  if (message.includes("cancelled")) return true;
+  if (message.includes("canceled")) return true;
+  return false;
+}
+var EmptyCompletionError;
+var init_errors = __esm({
+  "src/core/errors.ts"() {
+    "use strict";
+    EmptyCompletionError = class extends Error {
+      /** Agent iteration on which the empty completion was observed. */
+      iteration;
+      /** Finish reason reported alongside the empty body (often null). */
+      finishReason;
+      constructor(params) {
+        super(
+          `LLM returned an empty completion (no text, tool calls, or reasoning) on iteration ${params.iteration}`
+        );
+        this.name = "EmptyCompletionError";
+        this.iteration = params.iteration;
+        this.finishReason = params.finishReason;
+      }
+    };
+  }
+});
+
 // src/agent/retry-orchestrator.ts
+function isEmptyCompletion(meta) {
+  if (meta.didExecuteGadgets) return false;
+  if (meta.rawResponse?.trim() || meta.finalMessage?.trim()) return false;
+  if (meta.thinkingContent?.trim()) return false;
+  return true;
+}
 var RetryOrchestrator;
 var init_retry_orchestrator = __esm({
   "src/agent/retry-orchestrator.ts"() {
     "use strict";
+    init_errors();
     init_retry();
     init_safe_observe();
     init_tree_hook_bridge();
@@ -5258,6 +5300,7 @@ var init_retry_orchestrator = __esm({
         let gadgetCallCount = 0;
         const textOutputs = [];
         const gadgetResults = [];
+        let emptyFailure = null;
         while (streamAttempt < maxStreamAttempts) {
           streamAttempt++;
           try {
@@ -5266,6 +5309,7 @@ var init_retry_orchestrator = __esm({
             for await (const event of processor.process(stream2)) {
               if (event.type === "stream_complete") {
                 streamMetadata = event;
+                continue;
               }
               if (event.type === "llm_response_end") {
                 this.tree.endLLMResponse(llmNodeId, {
@@ -5287,43 +5331,44 @@ var init_retry_orchestrator = __esm({
             for (const id of processor.getFailedInvocationIds()) {
               this.failedInvocationIds.add(id);
             }
+            if (this.retryConfig.enabled && this.retryConfig.retryOnEmpty && streamMetadata !== null && !streamMetadata.finishReason && isEmptyCompletion(streamMetadata)) {
+              const emptyError = new EmptyCompletionError({
+                iteration,
+                finishReason: streamMetadata.finishReason
+              });
+              if (streamAttempt < maxStreamAttempts) {
+                await this.backoffBeforeRetry(
+                  emptyError,
+                  streamAttempt,
+                  maxStreamAttempts,
+                  iteration,
+                  llmNodeId
+                );
+                streamMetadata = null;
+                gadgetCallCount = 0;
+                textOutputs.length = 0;
+                gadgetResults.length = 0;
+                continue;
+              }
+              emptyFailure = emptyError;
+              break;
+            }
+            if (streamMetadata !== null) {
+              yield streamMetadata;
+            }
             break;
           } catch (streamError) {
             const error = streamError;
             const canRetry = this.retryConfig.enabled && streamAttempt < maxStreamAttempts;
             const shouldRetryError = this.retryConfig.shouldRetry ? this.retryConfig.shouldRetry(error) : isRetryableError(error);
             if (canRetry && shouldRetryError) {
-              const retryAfterMs = this.retryConfig.respectRetryAfter ? extractRetryAfterMs(error) : null;
-              const baseDelay = this.retryConfig.minTimeout * this.retryConfig.factor ** (streamAttempt - 1);
-              const cappedBaseDelay = Math.min(baseDelay, this.retryConfig.maxTimeout);
-              const delay = retryAfterMs !== null ? Math.min(retryAfterMs, this.retryConfig.maxRetryAfterMs) : cappedBaseDelay;
-              const finalDelay = this.retryConfig.randomize ? delay * (0.5 + Math.random()) : delay;
-              this.logger.warn(
-                `Stream iteration failed (attempt ${streamAttempt}/${maxStreamAttempts}), retrying...`,
-                {
-                  error: error.message,
-                  retriesLeft: maxStreamAttempts - streamAttempt,
-                  delayMs: Math.round(finalDelay),
-                  retryAfterMs
-                }
+              await this.backoffBeforeRetry(
+                error,
+                streamAttempt,
+                maxStreamAttempts,
+                iteration,
+                llmNodeId
               );
-              this.retryConfig.onRetry?.(error, streamAttempt);
-              await safeObserve(async () => {
-                if (this.hooks.observers?.onRetryAttempt) {
-                  const subagentContext = getSubagentContextForNode(this.tree, llmNodeId);
-                  const hookContext = {
-                    iteration,
-                    attemptNumber: streamAttempt,
-                    retriesLeft: maxStreamAttempts - streamAttempt,
-                    error,
-                    retryAfterMs: retryAfterMs ?? void 0,
-                    logger: this.logger,
-                    subagentContext
-                  };
-                  await this.hooks.observers.onRetryAttempt(hookContext);
-                }
-              }, this.logger);
-              await this.sleep(finalDelay);
               streamMetadata = null;
               gadgetCallCount = 0;
               textOutputs.length = 0;
@@ -5340,8 +5385,55 @@ var init_retry_orchestrator = __esm({
             throw error;
           }
         }
+        if (emptyFailure !== null) {
+          this.logger.error(`LLM returned empty completions on all ${streamAttempt} attempts`, {
+            iteration
+          });
+          this.retryConfig.onRetriesExhausted?.(emptyFailure, streamAttempt);
+          throw emptyFailure;
+        }
         return streamMetadata !== null ? { streamMetadata, textOutputs, gadgetResults, gadgetCallCount } : null;
       }
+      /**
+       * Apply the configured backoff before a retry attempt: compute the delay
+       * (Retry-After hint or exponential backoff, with optional jitter), emit the
+       * retry log, fire the `onRetry` callback and `onRetryAttempt` observer, then
+       * sleep. Shared by the error-retry and empty-completion-retry paths so both
+       * honour identical backoff and observer semantics.
+       */
+      async backoffBeforeRetry(error, streamAttempt, maxStreamAttempts, iteration, llmNodeId) {
+        const retryAfterMs = this.retryConfig.respectRetryAfter ? extractRetryAfterMs(error) : null;
+        const baseDelay = this.retryConfig.minTimeout * this.retryConfig.factor ** (streamAttempt - 1);
+        const cappedBaseDelay = Math.min(baseDelay, this.retryConfig.maxTimeout);
+        const delay = retryAfterMs !== null ? Math.min(retryAfterMs, this.retryConfig.maxRetryAfterMs) : cappedBaseDelay;
+        const finalDelay = this.retryConfig.randomize ? delay * (0.5 + Math.random()) : delay;
+        this.logger.warn(
+          `Stream iteration failed (attempt ${streamAttempt}/${maxStreamAttempts}), retrying...`,
+          {
+            error: error.message,
+            retriesLeft: maxStreamAttempts - streamAttempt,
+            delayMs: Math.round(finalDelay),
+            retryAfterMs
+          }
+        );
+        this.retryConfig.onRetry?.(error, streamAttempt);
+        await safeObserve(async () => {
+          if (this.hooks.observers?.onRetryAttempt) {
+            const subagentContext = getSubagentContextForNode(this.tree, llmNodeId);
+            const hookContext = {
+              iteration,
+              attemptNumber: streamAttempt,
+              retriesLeft: maxStreamAttempts - streamAttempt,
+              error,
+              retryAfterMs: retryAfterMs ?? void 0,
+              logger: this.logger,
+              subagentContext
+            };
+            await this.hooks.observers.onRetryAttempt(hookContext);
+          }
+        }, this.logger);
+        await this.sleep(finalDelay);
+      }
     };
   }
 });
@@ -5548,15 +5640,30 @@ function createLoadSkillGadget(registry) {
   const summaries = registry.getMetadataSummaries();
   const skillNames = registry.getModelInvocable().map((s) => s.name);
   const description = [
-    "Load one or more skill bodies into context. Pass an array even for a",
-    'single skill: `{skills: ["some-skill"]}`. **This gadget is an iteration',
-    "barrier \u2014 no other gadgets in the same tool batch will execute, so load",
-    "every skill you know you'll need in one shot.** The loaded bodies are",
-    "sticky and survive context compaction.",
+    "Load one or more skill bodies into context. Pass `skills` as a JSON",
+    "array of skill-name strings \u2014 NOT a string of a JSON-encoded array.",
+    'Right: `{"skills": ["alpha"]}` or `{"skills": ["alpha", "beta"]}`.',
+    'Wrong: `{"skills": "[\\"alpha\\"]"}` (the value is a string, not an array).',
+    "**This gadget is an iteration barrier \u2014 no other gadgets in the same",
+    "tool batch will execute, so load every skill you know you'll need in",
+    "one shot.** The loaded bodies are sticky and survive context compaction.",
     "",
     "Available skills:",
     summaries
   ].join("\n");
+  const examples = [];
+  if (skillNames.length >= 1) {
+    examples.push({
+      params: { skills: [skillNames[0]] },
+      comment: "Single-skill call \u2014 `skills` is still an array of length 1."
+    });
+  }
+  if (skillNames.length >= 2) {
+    examples.push({
+      params: { skills: [skillNames[0], skillNames[1]] },
+      comment: "Multi-skill call \u2014 load several skills in one shot to avoid round-trips."
+    });
+  }
   return createGadget({
     name: LOAD_SKILL_GADGET_NAME,
     description,
@@ -5570,6 +5677,7 @@ function createLoadSkillGadget(registry) {
     }),
     stickyResult: true,
     iterationBarrier: true,
+    examples,
     execute: async ({ skills: skillNamesArg, arguments: args }) => {
       const sections = [];
       for (const skillName of skillNamesArg) {
@@ -12467,7 +12575,7 @@ var init_model_registry = __esm({
        * Register a provider and collect its model specifications
        */
       registerProvider(provider) {
-        const specs = provider.getModelSpecs?.() ?? [];
+        const specs = [...provider.getModelSpecs?.() ?? []];
         if (specs.length > 0) {
           this.modelSpecs.push(...specs);
           this.providerMap.set(provider.providerId, specs);
@@ -12561,7 +12669,7 @@ var init_model_registry = __esm({
         if (!providerId) {
           return [...this.modelSpecs];
         }
-        return this.providerMap.get(providerId) ?? [];
+        return [...this.providerMap.get(providerId) ?? []];
       }
       /**
        * Get context window and output limits for a model
@@ -16756,7 +16864,7 @@ var init_stream_processor_factory = __esm({
 
 // src/mcp/errors.ts
 var McpError, McpUntrustedCommandError, McpConnectError, McpToolCallError, McpTimeoutError, JsonSchemaConversionError;
-var init_errors = __esm({
+var init_errors2 = __esm({
   "src/mcp/errors.ts"() {
     "use strict";
     McpError = class extends Error {
@@ -16842,7 +16950,7 @@ var init_allowlist = __esm({
   "src/mcp/allowlist.ts"() {
     "use strict";
     import_node_path6 = __toESM(require("path"), 1);
-    init_errors();
+    init_errors2();
     DEFAULT_MCP_COMMAND_ALLOWLIST = /* @__PURE__ */ new Set([
       "npx",
       "node",
@@ -16880,7 +16988,7 @@ var init_client2 = __esm({
   "src/mcp/client.ts"() {
     "use strict";
     init_allowlist();
-    init_errors();
+    init_errors2();
     cachedSdk = null;
     DEFAULT_CLIENT_INFO = { name: "llmist", version: "0.0.0" };
     McpClient = class {
@@ -17462,7 +17570,7 @@ var init_json_schema_to_zod = __esm({
   "src/mcp/json-schema-to-zod.ts"() {
     "use strict";
     import_zod4 = require("zod");
-    init_errors();
+    init_errors2();
   }
 });
 
@@ -18469,6 +18577,7 @@ __export(index_exports, {
   DEFAULT_RATE_LIMIT_CONFIG: () => DEFAULT_RATE_LIMIT_CONFIG,
   DEFAULT_RETRY_CONFIG: () => DEFAULT_RETRY_CONFIG,
   DEFAULT_SUMMARIZATION_PROMPT: () => DEFAULT_SUMMARIZATION_PROMPT,
+  EmptyCompletionError: () => EmptyCompletionError,
   ExecutionTree: () => ExecutionTree,
   FALLBACK_CHARS_PER_TOKEN: () => FALLBACK_CHARS_PER_TOKEN,
   GADGET_ARG_PREFIX: () => GADGET_ARG_PREFIX,
@@ -18754,19 +18863,7 @@ init_stream_processor();
 // src/index.ts
 init_client();
 init_constants();
-
-// src/core/errors.ts
-function isAbortError(error) {
-  if (!(error instanceof Error)) return false;
-  if (error.name === "AbortError") return true;
-  if (error.name === "APIConnectionAbortedError") return true;
-  if (error.name === "APIUserAbortError") return true;
-  const message = error.message.toLowerCase();
-  if (message.includes("abort")) return true;
-  if (message.includes("cancelled")) return true;
-  if (message.includes("canceled")) return true;
-  return false;
-}
+init_errors();
 
 // src/core/execution-events.ts
 function isLLMEvent(event) {
@@ -18826,7 +18923,7 @@ init_typed_gadget();
 // src/mcp/index.ts
 init_allowlist();
 init_client2();
-init_errors();
+init_errors2();
 
 // src/mcp/gadget-exporter.ts
 init_schema_to_json();
@@ -19476,6 +19573,7 @@ function getHostExports2(ctx) {
   DEFAULT_RATE_LIMIT_CONFIG,
   DEFAULT_RETRY_CONFIG,
   DEFAULT_SUMMARIZATION_PROMPT,
+  EmptyCompletionError,
   ExecutionTree,
   FALLBACK_CHARS_PER_TOKEN,
   GADGET_ARG_PREFIX,