llmist 1.6.2 → 2.0.0

package/dist/index.cjs

@@ -671,6 +671,44 @@ ${this.endPrefix}`
   }
 });
 
+// src/gadgets/exceptions.ts
+var BreakLoopException, HumanInputException, TimeoutException, AbortError;
+var init_exceptions = __esm({
+  "src/gadgets/exceptions.ts"() {
+    "use strict";
+    BreakLoopException = class extends Error {
+      constructor(message) {
+        super(message ?? "Agent loop terminated by gadget");
+        this.name = "BreakLoopException";
+      }
+    };
+    HumanInputException = class extends Error {
+      question;
+      constructor(question) {
+        super(`Human input required: ${question}`);
+        this.name = "HumanInputException";
+        this.question = question;
+      }
+    };
+    TimeoutException = class extends Error {
+      timeoutMs;
+      gadgetName;
+      constructor(gadgetName, timeoutMs) {
+        super(`Gadget '${gadgetName}' execution exceeded timeout of ${timeoutMs}ms`);
+        this.name = "TimeoutException";
+        this.gadgetName = gadgetName;
+        this.timeoutMs = timeoutMs;
+      }
+    };
+    AbortError = class extends Error {
+      constructor(message) {
+        super(message || "Gadget execution was aborted");
+        this.name = "AbortError";
+      }
+    };
+  }
+});
+
 // src/logging/logger.ts
 function parseLogLevel(value) {
   if (!value) {
@@ -943,6 +981,7 @@ var init_gadget = __esm({
   "src/gadgets/gadget.ts"() {
     "use strict";
     init_constants();
+    init_exceptions();
     init_schema_to_json();
     init_schema_validator();
     BaseGadget = class {
@@ -972,6 +1011,42 @@ var init_gadget = __esm({
        * while maintaining runtime compatibility.
        */
       examples;
+      /**
+       * Throws an AbortError if the execution has been aborted.
+       *
+       * Call this at key checkpoints in long-running gadgets to allow early exit
+       * when the gadget has been cancelled (e.g., due to timeout). This enables
+       * resource cleanup and prevents unnecessary work after cancellation.
+       *
+       * @param ctx - The execution context containing the abort signal
+       * @throws AbortError if ctx.signal.aborted is true
+       *
+       * @example
+       * ```typescript
+       * class DataProcessor extends Gadget({
+       *   description: 'Processes data in multiple steps',
+       *   schema: z.object({ items: z.array(z.string()) }),
+       * }) {
+       *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+       *     const results: string[] = [];
+       *
+       *     for (const item of params.items) {
+       *       // Check before each expensive operation
+       *       this.throwIfAborted(ctx);
+       *
+       *       results.push(await this.processItem(item));
+       *     }
+       *
+       *     return results.join(', ');
+       *   }
+       * }
+       * ```
+       */
+      throwIfAborted(ctx) {
+        if (ctx?.signal?.aborted) {
+          throw new AbortError();
+        }
+      }
       /**
        * Auto-generated instruction text for the LLM.
        * Combines name, description, and parameter schema into a formatted instruction.
@@ -1039,8 +1114,8 @@ function createGadget(config) {
     parameterSchema = config.schema;
     timeoutMs = config.timeoutMs;
     examples = config.examples;
-    execute(params) {
-      return config.execute(params);
+    execute(params, ctx) {
+      return config.execute(params, ctx);
     }
   }
   return new DynamicGadget();
@@ -2376,6 +2451,162 @@ var init_block_params = __esm({
   }
 });
 
+// src/gadgets/cost-reporting-client.ts
+var CostReportingLLMistWrapper;
+var init_cost_reporting_client = __esm({
+  "src/gadgets/cost-reporting-client.ts"() {
+    "use strict";
+    init_model_shortcuts();
+    CostReportingLLMistWrapper = class {
+      constructor(client, reportCost) {
+        this.client = client;
+        this.reportCost = reportCost;
+      }
+      /**
+       * Access to model registry for cost estimation.
+       */
+      get modelRegistry() {
+        return this.client.modelRegistry;
+      }
+      /**
+       * Quick completion with automatic cost reporting.
+       *
+       * Streams internally to track token usage, then reports the calculated cost.
+       *
+       * @param prompt - User prompt
+       * @param options - Optional configuration (model, temperature, etc.)
+       * @returns Complete text response
+       */
+      async complete(prompt, options) {
+        const model = resolveModel(options?.model ?? "haiku");
+        let result = "";
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let cachedInputTokens = 0;
+        let cacheCreationInputTokens = 0;
+        const messages = [
+          ...options?.systemPrompt ? [{ role: "system", content: options.systemPrompt }] : [],
+          { role: "user", content: prompt }
+        ];
+        for await (const chunk of this.client.stream({
+          model,
+          messages,
+          temperature: options?.temperature,
+          maxTokens: options?.maxTokens
+        })) {
+          result += chunk.text ?? "";
+          if (chunk.usage) {
+            inputTokens = chunk.usage.inputTokens;
+            outputTokens = chunk.usage.outputTokens;
+            cachedInputTokens = chunk.usage.cachedInputTokens ?? 0;
+            cacheCreationInputTokens = chunk.usage.cacheCreationInputTokens ?? 0;
+          }
+        }
+        this.reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens, cacheCreationInputTokens);
+        return result;
+      }
+      /**
+       * Quick streaming with automatic cost reporting when stream completes.
+       *
+       * Yields text chunks as they arrive, then reports cost in finally block.
+       *
+       * @param prompt - User prompt
+       * @param options - Optional configuration (model, temperature, etc.)
+       * @returns Async generator yielding text chunks
+       */
+      async *streamText(prompt, options) {
+        const model = resolveModel(options?.model ?? "haiku");
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let cachedInputTokens = 0;
+        let cacheCreationInputTokens = 0;
+        const messages = [
+          ...options?.systemPrompt ? [{ role: "system", content: options.systemPrompt }] : [],
+          { role: "user", content: prompt }
+        ];
+        try {
+          for await (const chunk of this.client.stream({
+            model,
+            messages,
+            temperature: options?.temperature,
+            maxTokens: options?.maxTokens
+          })) {
+            if (chunk.text) {
+              yield chunk.text;
+            }
+            if (chunk.usage) {
+              inputTokens = chunk.usage.inputTokens;
+              outputTokens = chunk.usage.outputTokens;
+              cachedInputTokens = chunk.usage.cachedInputTokens ?? 0;
+              cacheCreationInputTokens = chunk.usage.cacheCreationInputTokens ?? 0;
+            }
+          }
+        } finally {
+          this.reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens, cacheCreationInputTokens);
+        }
+      }
+      /**
+       * Low-level stream access with automatic cost reporting.
+       *
+       * Returns a wrapped stream that reports costs when iteration completes.
+       *
+       * @param options - Full LLM generation options
+       * @returns Wrapped LLM stream that auto-reports costs
+       */
+      stream(options) {
+        return this.createCostReportingStream(options);
+      }
+      /**
+       * Creates a wrapped stream that tracks usage and reports costs on completion.
+       */
+      createCostReportingStream(options) {
+        const innerStream = this.client.stream(options);
+        const reportCostFromUsage = this.reportCostFromUsage.bind(this);
+        const model = options.model;
+        async function* costReportingWrapper() {
+          let inputTokens = 0;
+          let outputTokens = 0;
+          let cachedInputTokens = 0;
+          let cacheCreationInputTokens = 0;
+          try {
+            for await (const chunk of innerStream) {
+              if (chunk.usage) {
+                inputTokens = chunk.usage.inputTokens;
+                outputTokens = chunk.usage.outputTokens;
+                cachedInputTokens = chunk.usage.cachedInputTokens ?? 0;
+                cacheCreationInputTokens = chunk.usage.cacheCreationInputTokens ?? 0;
+              }
+              yield chunk;
+            }
+          } finally {
+            if (inputTokens > 0 || outputTokens > 0) {
+              reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens, cacheCreationInputTokens);
+            }
+          }
+        }
+        return costReportingWrapper();
+      }
+      /**
+       * Calculates and reports cost from token usage.
+       */
+      reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens = 0, cacheCreationInputTokens = 0) {
+        if (inputTokens === 0 && outputTokens === 0) return;
+        const modelName = model.includes(":") ? model.split(":")[1] : model;
+        const estimate = this.client.modelRegistry.estimateCost(
+          modelName,
+          inputTokens,
+          outputTokens,
+          cachedInputTokens,
+          cacheCreationInputTokens
+        );
+        if (estimate && estimate.totalCost > 0) {
+          this.reportCost(estimate.totalCost);
+        }
+      }
+    };
+  }
+});
+
 // src/gadgets/error-formatter.ts
 var GadgetErrorFormatter;
 var init_error_formatter = __esm({
@@ -2459,38 +2690,6 @@ var init_error_formatter = __esm({
   }
 });
 
-// src/gadgets/exceptions.ts
-var BreakLoopException, HumanInputException, TimeoutException;
-var init_exceptions = __esm({
-  "src/gadgets/exceptions.ts"() {
-    "use strict";
-    BreakLoopException = class extends Error {
-      constructor(message) {
-        super(message ?? "Agent loop terminated by gadget");
-        this.name = "BreakLoopException";
-      }
-    };
-    HumanInputException = class extends Error {
-      question;
-      constructor(question) {
-        super(`Human input required: ${question}`);
-        this.name = "HumanInputException";
-        this.question = question;
-      }
-    };
-    TimeoutException = class extends Error {
-      timeoutMs;
-      gadgetName;
-      constructor(gadgetName, timeoutMs) {
-        super(`Gadget '${gadgetName}' execution exceeded timeout of ${timeoutMs}ms`);
-        this.name = "TimeoutException";
-        this.gadgetName = gadgetName;
-        this.timeoutMs = timeoutMs;
-      }
-    };
-  }
-});
-
 // src/gadgets/parser.ts
 function stripMarkdownFences(content) {
   let cleaned = content.trim();
@@ -2676,14 +2875,16 @@ var init_executor = __esm({
     init_constants();
     init_logger();
     init_block_params();
+    init_cost_reporting_client();
     init_error_formatter();
     init_exceptions();
     init_parser();
     GadgetExecutor = class {
-      constructor(registry, onHumanInputRequired, logger, defaultGadgetTimeoutMs, errorFormatterOptions) {
+      constructor(registry, onHumanInputRequired, logger, defaultGadgetTimeoutMs, errorFormatterOptions, client) {
         this.registry = registry;
         this.onHumanInputRequired = onHumanInputRequired;
         this.defaultGadgetTimeoutMs = defaultGadgetTimeoutMs;
+        this.client = client;
         this.logger = logger ?? createLogger({ name: "llmist:executor" });
         this.errorFormatter = new GadgetErrorFormatter(errorFormatterOptions);
         this.argPrefix = errorFormatterOptions?.argPrefix ?? GADGET_ARG_PREFIX;
@@ -2693,14 +2894,27 @@ var init_executor = __esm({
       argPrefix;
       /**
        * Creates a promise that rejects with a TimeoutException after the specified timeout.
+       * Aborts the provided AbortController before rejecting, allowing gadgets to clean up.
        */
-      createTimeoutPromise(gadgetName, timeoutMs) {
+      createTimeoutPromise(gadgetName, timeoutMs, abortController) {
         return new Promise((_, reject) => {
           setTimeout(() => {
-            reject(new TimeoutException(gadgetName, timeoutMs));
+            const timeoutError = new TimeoutException(gadgetName, timeoutMs);
+            abortController.abort(timeoutError.message);
+            reject(timeoutError);
           }, timeoutMs);
         });
       }
+      /**
+       * Normalizes gadget execute result to consistent format.
+       * Handles both string returns (backwards compat) and object returns with cost.
+       */
+      normalizeExecuteResult(raw) {
+        if (typeof raw === "string") {
+          return { result: raw, cost: 0 };
+        }
+        return { result: raw.result, cost: raw.cost ?? 0 };
+      }
       // Execute a gadget call asynchronously
       async execute(call) {
         const startTime = Date.now();
@@ -2795,30 +3009,53 @@ var init_executor = __esm({
             validatedParameters = schemaAwareParameters;
           }
           const timeoutMs = gadget.timeoutMs ?? this.defaultGadgetTimeoutMs;
-          let result;
+          const abortController = new AbortController();
+          let callbackCost = 0;
+          const reportCost = (amount) => {
+            if (amount > 0) {
+              callbackCost += amount;
+              this.logger.debug("Gadget reported cost via callback", {
+                gadgetName: call.gadgetName,
+                amount,
+                totalCallbackCost: callbackCost
+              });
+            }
+          };
+          const ctx = {
+            reportCost,
+            llmist: this.client ? new CostReportingLLMistWrapper(this.client, reportCost) : void 0,
+            signal: abortController.signal
+          };
+          let rawResult;
           if (timeoutMs && timeoutMs > 0) {
             this.logger.debug("Executing gadget with timeout", {
               gadgetName: call.gadgetName,
               timeoutMs
             });
-            result = await Promise.race([
-              Promise.resolve(gadget.execute(validatedParameters)),
-              this.createTimeoutPromise(call.gadgetName, timeoutMs)
+            rawResult = await Promise.race([
+              Promise.resolve(gadget.execute(validatedParameters, ctx)),
+              this.createTimeoutPromise(call.gadgetName, timeoutMs, abortController)
             ]);
           } else {
-            result = await Promise.resolve(gadget.execute(validatedParameters));
+            rawResult = await Promise.resolve(gadget.execute(validatedParameters, ctx));
           }
+          const { result, cost: returnCost } = this.normalizeExecuteResult(rawResult);
+          const totalCost = callbackCost + returnCost;
           const executionTimeMs = Date.now() - startTime;
           this.logger.info("Gadget executed successfully", {
             gadgetName: call.gadgetName,
             invocationId: call.invocationId,
-            executionTimeMs
+            executionTimeMs,
+            cost: totalCost > 0 ? totalCost : void 0,
+            callbackCost: callbackCost > 0 ? callbackCost : void 0,
+            returnCost: returnCost > 0 ? returnCost : void 0
           });
           this.logger.debug("Gadget result", {
             gadgetName: call.gadgetName,
             invocationId: call.invocationId,
             parameters: validatedParameters,
             result,
+            cost: totalCost,
             executionTimeMs
           });
           return {
@@ -2826,7 +3063,8 @@ var init_executor = __esm({
             invocationId: call.invocationId,
             parameters: validatedParameters,
             result,
-            executionTimeMs
+            executionTimeMs,
+            cost: totalCost
           };
         } catch (error) {
           if (error instanceof BreakLoopException) {
@@ -2857,6 +3095,19 @@ var init_executor = __esm({
               executionTimeMs: Date.now() - startTime
             };
           }
+          if (error instanceof AbortError) {
+            this.logger.info("Gadget execution was aborted", {
+              gadgetName: call.gadgetName,
+              executionTimeMs: Date.now() - startTime
+            });
+            return {
+              gadgetName: call.gadgetName,
+              invocationId: call.invocationId,
+              parameters: validatedParameters,
+              error: error.message,
+              executionTimeMs: Date.now() - startTime
+            };
+          }
           if (error instanceof HumanInputException) {
             this.logger.info("Gadget requested human input", {
               gadgetName: call.gadgetName,
@@ -2983,7 +3234,8 @@ var init_stream_processor = __esm({
           options.onHumanInputRequired,
           this.logger.getSubLogger({ name: "executor" }),
           options.defaultGadgetTimeoutMs,
-          { argPrefix: options.gadgetArgPrefix }
+          { argPrefix: options.gadgetArgPrefix },
+          options.client
         );
       }
       /**
@@ -3250,6 +3502,7 @@ var init_stream_processor = __esm({
               error: result.error,
               executionTimeMs: result.executionTimeMs,
               breaksLoop: result.breaksLoop,
+              cost: result.cost,
               logger: this.logger
             };
             await this.hooks.observers.onGadgetExecutionComplete(context);
@@ -3626,7 +3879,8 @@ var init_agent = __esm({
               onHumanInputRequired: this.onHumanInputRequired,
               stopOnGadgetError: this.stopOnGadgetError,
               shouldContinueAfterError: this.shouldContinueAfterError,
-              defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs
+              defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
+              client: this.client
             });
             const result = await processor.process(stream2);
             for (const output of result.outputs) {
@@ -5909,6 +6163,7 @@ var init_builder = __esm({
       gadgetOutputLimitPercent;
       compactionConfig;
       signal;
+      trailingMessage;
       constructor(client) {
         this.client = client;
       }
@@ -6384,6 +6639,31 @@ var init_builder = __esm({
         this.signal = signal;
         return this;
       }
+      /**
+       * Add an ephemeral trailing message that appears at the end of each LLM request.
+       *
+       * The message is NOT persisted to conversation history - it only appears in the
+       * current LLM call. This is useful for injecting context-specific instructions
+       * or reminders without polluting the conversation history.
+       *
+       * @param message - Static string or function that generates the message
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * // Static message
+       * .withTrailingMessage("Always respond in JSON format.")
+       *
+       * // Dynamic message based on iteration
+       * .withTrailingMessage((ctx) =>
+       *   `[Iteration ${ctx.iteration}/${ctx.maxIterations}] Stay focused on the task.`
+       * )
+       * ```
+       */
+      withTrailingMessage(message) {
+        this.trailingMessage = message;
+        return this;
+      }
       /**
        * Add a synthetic gadget call to the conversation history.
        *
@@ -6425,6 +6705,36 @@ ${endPrefix}`
         });
         return this;
       }
+      /**
+       * Compose the final hooks, including trailing message if configured.
+       */
+      composeHooks() {
+        if (!this.trailingMessage) {
+          return this.hooks;
+        }
+        const trailingMsg = this.trailingMessage;
+        const existingBeforeLLMCall = this.hooks?.controllers?.beforeLLMCall;
+        const trailingMessageController = async (ctx) => {
+          const result = existingBeforeLLMCall ? await existingBeforeLLMCall(ctx) : { action: "proceed" };
+          if (result.action === "skip") {
+            return result;
+          }
+          const messages = [...result.modifiedOptions?.messages || ctx.options.messages];
+          const content = typeof trailingMsg === "function" ? trailingMsg({ iteration: ctx.iteration, maxIterations: ctx.maxIterations }) : trailingMsg;
+          messages.push({ role: "user", content });
+          return {
+            action: "proceed",
+            modifiedOptions: { ...result.modifiedOptions, messages }
+          };
+        };
+        return {
+          ...this.hooks,
+          controllers: {
+            ...this.hooks?.controllers,
+            beforeLLMCall: trailingMessageController
+          }
+        };
+      }
       /**
        * Format parameters as block format with JSON Pointer paths.
        */
@@ -6486,7 +6796,7 @@ ${endPrefix}`
           maxIterations: this.maxIterations,
           temperature: this.temperature,
           logger: this.logger,
-          hooks: this.hooks,
+          hooks: this.composeHooks(),
           promptConfig: this.promptConfig,
           initialMessages: this.initialMessages,
           onHumanInputRequired: this.onHumanInputRequired,
@@ -6590,7 +6900,7 @@ ${endPrefix}`
           maxIterations: this.maxIterations,
           temperature: this.temperature,
           logger: this.logger,
-          hooks: this.hooks,
+          hooks: this.composeHooks(),
           promptConfig: this.promptConfig,
           initialMessages: this.initialMessages,
           onHumanInputRequired: this.onHumanInputRequired,
@@ -6616,6 +6926,7 @@ ${endPrefix}`
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AbortError: () => AbortError,
   AgentBuilder: () => AgentBuilder,
   AnthropicMessagesProvider: () => AnthropicMessagesProvider,
   BaseGadget: () => BaseGadget,
@@ -7053,6 +7364,7 @@ var HookPresets = class _HookPresets {
     let totalInputTokens = 0;
     let totalOutputTokens = 0;
     let totalCost = 0;
+    let totalGadgetCost = 0;
     const startTime = Date.now();
     return {
       observers: {
@@ -7090,7 +7402,7 @@ var HookPresets = class _HookPresets {
             totalInputTokens,
             totalOutputTokens,
             totalTokens: totalInputTokens + totalOutputTokens,
-            totalCost,
+            totalCost: totalCost + totalGadgetCost,
             elapsedSeconds: Number(((Date.now() - startTime) / 1e3).toFixed(1))
           };
           if (onProgress) {
@@ -7103,6 +7415,12 @@ var HookPresets = class _HookPresets {
               `\u{1F4CA} Progress: Iteration #${stats.currentIteration} | ${formattedTokens} tokens | ${formattedCost} | ${stats.elapsedSeconds}s`
             );
           }
+        },
+        // Track gadget execution costs
+        onGadgetExecutionComplete: async (ctx) => {
+          if (ctx.cost && ctx.cost > 0) {
+            totalGadgetCost += ctx.cost;
+          }
         }
       }
     };
@@ -8346,6 +8664,7 @@ init_gadget();
 var import_node_stream = require("stream");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AbortError,
   AgentBuilder,
   AnthropicMessagesProvider,
   BaseGadget,