llmist 1.6.2 → 2.0.0

package/dist/cli.cjs

@@ -644,6 +644,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) {
@@ -916,6 +954,7 @@ var init_gadget = __esm({
   "src/gadgets/gadget.ts"() {
     "use strict";
     init_constants();
+    init_exceptions();
     init_schema_to_json();
     init_schema_validator();
     BaseGadget = class {
@@ -945,6 +984,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.
@@ -1012,8 +1087,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();
@@ -2319,6 +2394,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({
@@ -2402,38 +2633,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();
@@ -2619,14 +2818,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;
@@ -2636,14 +2837,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();
@@ -2738,30 +2952,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 {
@@ -2769,7 +3006,8 @@ var init_executor = __esm({
             invocationId: call.invocationId,
             parameters: validatedParameters,
             result,
-            executionTimeMs
+            executionTimeMs,
+            cost: totalCost
           };
         } catch (error) {
           if (error instanceof BreakLoopException) {
@@ -2800,6 +3038,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,
@@ -2926,7 +3177,8 @@ var init_stream_processor = __esm({
           options.onHumanInputRequired,
           this.logger.getSubLogger({ name: "executor" }),
           options.defaultGadgetTimeoutMs,
-          { argPrefix: options.gadgetArgPrefix }
+          { argPrefix: options.gadgetArgPrefix },
+          options.client
         );
       }
       /**
@@ -3193,6 +3445,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);
@@ -3569,7 +3822,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) {
@@ -5852,6 +6106,7 @@ var init_builder = __esm({
       gadgetOutputLimitPercent;
       compactionConfig;
       signal;
+      trailingMessage;
       constructor(client) {
         this.client = client;
       }
@@ -6327,6 +6582,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.
        *
@@ -6368,6 +6648,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.
        */
@@ -6429,7 +6739,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,
@@ -6533,7 +6843,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,
@@ -6615,7 +6925,7 @@ var import_commander2 = require("commander");
 // package.json
 var package_default = {
   name: "llmist",
-  version: "1.6.1",
+  version: "1.7.0",
   description: "Universal TypeScript LLM client with streaming-first agent framework. Works with any model - no structured outputs or native tool calling required. Implements its own flexible grammar for function calling.",
   type: "module",
   main: "dist/index.cjs",
@@ -7478,38 +7788,46 @@ error: ${message}`;
 var import_zod8 = require("zod");
 var runCommand = createGadget({
   name: "RunCommand",
-  description: "Execute a shell command and return its output. Returns both stdout and stderr combined with the exit status.",
+  description: "Execute a command with arguments and return its output. Uses argv array to bypass shell - arguments are passed directly without interpretation. Returns stdout/stderr combined with exit status.",
   schema: import_zod8.z.object({
-    command: import_zod8.z.string().describe("The shell command to execute"),
+    argv: import_zod8.z.array(import_zod8.z.string()).describe("Command and arguments as array (e.g., ['git', 'commit', '-m', 'message'])"),
     cwd: import_zod8.z.string().optional().describe("Working directory for the command (default: current directory)"),
     timeout: import_zod8.z.number().default(3e4).describe("Timeout in milliseconds (default: 30000)")
   }),
   examples: [
     {
-      params: { command: "ls -la", timeout: 3e4 },
+      params: { argv: ["ls", "-la"], timeout: 3e4 },
       output: "status=0\n\ntotal 24\ndrwxr-xr-x  5 user  staff   160 Nov 27 10:00 .\ndrwxr-xr-x  3 user  staff    96 Nov 27 09:00 ..\n-rw-r--r--  1 user  staff  1024 Nov 27 10:00 package.json",
       comment: "List directory contents with details"
     },
     {
-      params: { command: "echo 'Hello World'", timeout: 3e4 },
+      params: { argv: ["echo", "Hello World"], timeout: 3e4 },
       output: "status=0\n\nHello World",
-      comment: "Simple echo command"
+      comment: "Echo without shell - argument passed directly"
     },
     {
-      params: { command: "cat nonexistent.txt", timeout: 3e4 },
+      params: { argv: ["cat", "nonexistent.txt"], timeout: 3e4 },
       output: "status=1\n\ncat: nonexistent.txt: No such file or directory",
       comment: "Command that fails returns non-zero status"
     },
     {
-      params: { command: "pwd", cwd: "/tmp", timeout: 3e4 },
+      params: { argv: ["pwd"], cwd: "/tmp", timeout: 3e4 },
       output: "status=0\n\n/tmp",
       comment: "Execute command in a specific directory"
+    },
+    {
+      params: { argv: ["gh", "pr", "review", "123", "--comment", "--body", "Review with `backticks` and 'quotes'"], timeout: 3e4 },
+      output: "status=0\n\n(no output)",
+      comment: "Complex arguments with special characters - no escaping needed"
     }
   ],
-  execute: async ({ command, cwd, timeout }) => {
+  execute: async ({ argv, cwd, timeout }) => {
     const workingDir = cwd ?? process.cwd();
+    if (argv.length === 0) {
+      return "status=1\n\nerror: argv array cannot be empty";
+    }
     try {
-      const proc = Bun.spawn(["sh", "-c", command], {
+      const proc = Bun.spawn(argv, {
         cwd: workingDir,
         stdout: "pipe",
         stderr: "pipe"
@@ -10417,9 +10735,11 @@ ${issues}`);
   env.stderr.write(import_chalk7.default.dim("\nExecuting...\n"));
   const startTime = Date.now();
   let result;
+  let cost;
   try {
+    let rawResult;
     if (gadget.timeoutMs && gadget.timeoutMs > 0) {
-      result = await Promise.race([
+      rawResult = await Promise.race([
         Promise.resolve(gadget.execute(params)),
         new Promise(
           (_, reject) => setTimeout(
@@ -10429,15 +10749,18 @@ ${issues}`);
         )
       ]);
     } else {
-      result = await Promise.resolve(gadget.execute(params));
+      rawResult = await Promise.resolve(gadget.execute(params));
     }
+    result = typeof rawResult === "string" ? rawResult : rawResult.result;
+    cost = typeof rawResult === "object" ? rawResult.cost : void 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Execution failed: ${message}`);
   }
   const elapsed = Date.now() - startTime;
+  const costInfo = cost !== void 0 && cost > 0 ? ` (Cost: $${cost.toFixed(6)})` : "";
   env.stderr.write(import_chalk7.default.green(`
-\u2713 Completed in ${elapsed}ms
+\u2713 Completed in ${elapsed}ms${costInfo}
 
 `));
   formatOutput(result, options, env.stdout);