llmist 0.3.1 → 0.4.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createGadget
-} from "./chunk-I55AV3WV.js";
+} from "./chunk-QVDGTUQN.js";
 import {
   AgentBuilder,
   BaseGadget,
@@ -22,7 +22,7 @@ import {
   init_model_shortcuts,
   init_registry,
   resolveModel
-} from "./chunk-VYBRYR2S.js";
+} from "./chunk-LQE7TKKW.js";
 
 // src/cli/constants.ts
 var CLI_NAME = "llmist";
@@ -45,7 +45,8 @@ var OPTION_FLAGS = {
   parameterFormat: "--parameter-format <format>",
   logLevel: "--log-level <level>",
   logFile: "--log-file <path>",
-  noBuiltins: "--no-builtins"
+  noBuiltins: "--no-builtins",
+  noBuiltinInteraction: "--no-builtin-interaction"
 };
 var OPTION_DESCRIPTIONS = {
   model: "Model identifier, e.g. openai:gpt-5-nano or anthropic:claude-sonnet-4-5.",
@@ -57,7 +58,8 @@ var OPTION_DESCRIPTIONS = {
   parameterFormat: "Format for gadget parameter schemas: 'json', 'yaml', or 'auto'.",
   logLevel: "Log level: silly, trace, debug, info, warn, error, fatal.",
   logFile: "Path to log file. When set, logs are written to file instead of stderr.",
-  noBuiltins: "Disable built-in gadgets (AskUser, TellUser)."
+  noBuiltins: "Disable built-in gadgets (AskUser, TellUser).",
+  noBuiltinInteraction: "Disable interactive gadgets (AskUser) while keeping TellUser."
 };
 var SUMMARY_PREFIX = "[llmist]";
 
@@ -67,7 +69,7 @@ import { Command, InvalidArgumentError as InvalidArgumentError3 } from "commande
 // package.json
 var package_default = {
   name: "llmist",
-  version: "0.3.0",
+  version: "0.4.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",
@@ -179,7 +181,6 @@ init_builder();
 init_registry();
 init_constants();
 import { createInterface } from "node:readline/promises";
-import chalk2 from "chalk";
 import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
 
 // src/cli/builtin-gadgets.ts
@@ -317,8 +318,66 @@ async function loadGadgets(specifiers, cwd, importer = (specifier) => import(spe
 
 // src/cli/utils.ts
 init_constants();
-import chalk from "chalk";
+import chalk2 from "chalk";
 import { InvalidArgumentError } from "commander";
+
+// src/cli/ui/formatters.ts
+import chalk from "chalk";
+function formatTokens(tokens) {
+  return tokens >= 1e3 ? `${(tokens / 1e3).toFixed(1)}k` : `${tokens}`;
+}
+function formatCost(cost) {
+  if (cost < 1e-3) {
+    return cost.toFixed(5);
+  }
+  if (cost < 0.01) {
+    return cost.toFixed(4);
+  }
+  if (cost < 1) {
+    return cost.toFixed(3);
+  }
+  return cost.toFixed(2);
+}
+function renderSummary(metadata) {
+  const parts = [];
+  if (metadata.iterations !== void 0) {
+    parts.push(chalk.cyan(`#${metadata.iterations}`));
+  }
+  if (metadata.usage) {
+    const { inputTokens, outputTokens } = metadata.usage;
+    parts.push(chalk.dim("\u2191") + chalk.yellow(` ${formatTokens(inputTokens)}`));
+    parts.push(chalk.dim("\u2193") + chalk.green(` ${formatTokens(outputTokens)}`));
+  }
+  if (metadata.elapsedSeconds !== void 0 && metadata.elapsedSeconds > 0) {
+    parts.push(chalk.dim(`${metadata.elapsedSeconds}s`));
+  }
+  if (metadata.cost !== void 0 && metadata.cost > 0) {
+    parts.push(chalk.cyan(`$${formatCost(metadata.cost)}`));
+  }
+  if (metadata.finishReason) {
+    parts.push(chalk.dim(metadata.finishReason));
+  }
+  if (parts.length === 0) {
+    return null;
+  }
+  return parts.join(chalk.dim(" | "));
+}
+function formatGadgetSummary(result) {
+  const gadgetLabel = chalk.magenta.bold(result.gadgetName);
+  const timeLabel = chalk.dim(`${Math.round(result.executionTimeMs)}ms`);
+  if (result.error) {
+    return `${chalk.red("\u2717")} ${gadgetLabel} ${chalk.red("error:")} ${result.error} ${timeLabel}`;
+  }
+  if (result.breaksLoop) {
+    return `${chalk.yellow("\u23F9")} ${gadgetLabel} ${chalk.yellow("finished:")} ${result.result} ${timeLabel}`;
+  }
+  const maxLen = 80;
+  const shouldTruncate = result.gadgetName !== "TellUser";
+  const resultText = result.result ? shouldTruncate && result.result.length > maxLen ? `${result.result.slice(0, maxLen)}...` : result.result : "";
+  return `${chalk.green("\u2713")} ${gadgetLabel} ${chalk.dim("\u2192")} ${resultText} ${timeLabel}`;
+}
+
+// src/cli/utils.ts
 function createNumericParser({
   label,
   integer = false,
@@ -401,15 +460,20 @@ var StreamProgress = class {
   totalTokens = 0;
   totalCost = 0;
   iterations = 0;
+  currentIteration = 0;
   /**
    * Starts a new LLM call. Switches to streaming mode.
    * @param model - Model name being used
-   * @param estimatedInputTokens - Estimated input tokens based on prompt length
+   * @param estimatedInputTokens - Initial input token count. Should come from
+   *   client.countTokens() for accuracy (provider-specific counting), not
+   *   character-based estimation. Will be updated with provider-returned counts
+   *   via setInputTokens() during streaming if available.
    */
   startCall(model, estimatedInputTokens) {
     this.mode = "streaming";
     this.model = model;
     this.callStartTime = Date.now();
+    this.currentIteration++;
     this.callInputTokens = estimatedInputTokens ?? 0;
     this.callInputTokensEstimated = true;
     this.callOutputTokens = 0;
@@ -446,8 +510,10 @@ var StreamProgress = class {
   }
   /**
    * Sets the input token count for current call (from stream metadata).
-   * @param tokens - Token count
-   * @param estimated - If true, shown with ~ prefix until actual count arrives
+   * @param tokens - Token count from provider or client.countTokens()
+   * @param estimated - If true, this is a fallback estimate (character-based).
+   *   If false, this is an accurate count from the provider API or client.countTokens().
+   *   Display shows ~ prefix only when estimated=true.
    */
   setInputTokens(tokens, estimated = false) {
     if (estimated && !this.callInputTokensEstimated) {
@@ -458,8 +524,10 @@ var StreamProgress = class {
   }
   /**
    * Sets the output token count for current call (from stream metadata).
-   * @param tokens - Token count
-   * @param estimated - If true, shown with ~ prefix until actual count arrives
+   * @param tokens - Token count from provider streaming response
+   * @param estimated - If true, this is a fallback estimate (character-based).
+   *   If false, this is an accurate count from the provider's streaming metadata.
+   *   Display shows ~ prefix only when estimated=true.
    */
   setOutputTokens(tokens, estimated = false) {
     if (estimated && !this.callOutputTokensEstimated) {
@@ -468,6 +536,14 @@ var StreamProgress = class {
     this.callOutputTokens = tokens;
     this.callOutputTokensEstimated = estimated;
   }
+  /**
+   * Get total elapsed time in seconds since the first call started.
+   * @returns Elapsed time in seconds with 1 decimal place
+   */
+  getTotalElapsedSeconds() {
+    if (this.totalStartTime === 0) return 0;
+    return Number(((Date.now() - this.totalStartTime) / 1e3).toFixed(1));
+  }
   /**
    * Starts the progress indicator animation after a brief delay.
    */
@@ -502,40 +578,38 @@ var StreamProgress = class {
     const elapsed = ((Date.now() - this.callStartTime) / 1e3).toFixed(1);
     const outTokens = this.callOutputTokensEstimated ? Math.round(this.callOutputChars / FALLBACK_CHARS_PER_TOKEN) : this.callOutputTokens;
     const parts = [];
-    if (this.model) {
-      parts.push(chalk.cyan(this.model));
-    }
+    parts.push(chalk2.cyan(`#${this.currentIteration}`));
     if (this.callInputTokens > 0) {
       const prefix = this.callInputTokensEstimated ? "~" : "";
-      parts.push(chalk.dim("out:") + chalk.yellow(` ${prefix}${this.callInputTokens}`));
+      parts.push(chalk2.dim("\u2191") + chalk2.yellow(` ${prefix}${formatTokens(this.callInputTokens)}`));
     }
     if (this.isStreaming || outTokens > 0) {
       const prefix = this.callOutputTokensEstimated ? "~" : "";
-      parts.push(chalk.dim("in:") + chalk.green(` ${prefix}${outTokens}`));
+      parts.push(chalk2.dim("\u2193") + chalk2.green(` ${prefix}${formatTokens(outTokens)}`));
     }
+    parts.push(chalk2.dim(`${elapsed}s`));
     if (this.totalCost > 0) {
-      parts.push(chalk.dim("cost:") + chalk.cyan(` $${this.formatCost(this.totalCost)}`));
+      parts.push(chalk2.cyan(`$${formatCost(this.totalCost)}`));
     }
-    parts.push(chalk.dim(`${elapsed}s`));
-    this.target.write(`\r${chalk.cyan(spinner)} ${parts.join(chalk.dim(" | "))}`);
+    this.target.write(`\r${chalk2.cyan(spinner)} ${parts.join(chalk2.dim(" | "))}`);
   }
   renderCumulativeMode(spinner) {
     const elapsed = ((Date.now() - this.totalStartTime) / 1e3).toFixed(1);
     const parts = [];
     if (this.model) {
-      parts.push(chalk.cyan(this.model));
+      parts.push(chalk2.cyan(this.model));
     }
     if (this.totalTokens > 0) {
-      parts.push(chalk.dim("total:") + chalk.magenta(` ${this.totalTokens}`));
+      parts.push(chalk2.dim("total:") + chalk2.magenta(` ${this.totalTokens}`));
     }
     if (this.iterations > 0) {
-      parts.push(chalk.dim("iter:") + chalk.blue(` ${this.iterations}`));
+      parts.push(chalk2.dim("iter:") + chalk2.blue(` ${this.iterations}`));
     }
     if (this.totalCost > 0) {
-      parts.push(chalk.dim("cost:") + chalk.cyan(` $${this.formatCost(this.totalCost)}`));
+      parts.push(chalk2.dim("cost:") + chalk2.cyan(` $${formatCost(this.totalCost)}`));
     }
-    parts.push(chalk.dim(`${elapsed}s`));
-    this.target.write(`\r${chalk.cyan(spinner)} ${parts.join(chalk.dim(" | "))}`);
+    parts.push(chalk2.dim(`${elapsed}s`));
+    this.target.write(`\r${chalk2.cyan(spinner)} ${parts.join(chalk2.dim(" | "))}`);
   }
   /**
    * Pauses the progress indicator and clears the line.
@@ -583,49 +657,28 @@ var StreamProgress = class {
       if (this.callInputTokens > 0) {
         const prefix = this.callInputTokensEstimated ? "~" : "";
         parts.push(
-          chalk.dim("out:") + chalk.yellow(` ${prefix}${this.formatTokens(this.callInputTokens)}`)
+          chalk2.dim("\u2191") + chalk2.yellow(` ${prefix}${formatTokens(this.callInputTokens)}`)
         );
       }
       if (outTokens > 0) {
         const prefix = outEstimated ? "~" : "";
-        parts.push(chalk.dim("in:") + chalk.green(` ${prefix}${this.formatTokens(outTokens)}`));
+        parts.push(chalk2.dim("\u2193") + chalk2.green(` ${prefix}${formatTokens(outTokens)}`));
       }
-      parts.push(chalk.dim(`${elapsed}s`));
+      parts.push(chalk2.dim(`${elapsed}s`));
     } else {
       const elapsed = Math.round((Date.now() - this.totalStartTime) / 1e3);
       if (this.totalTokens > 0) {
-        parts.push(chalk.magenta(this.formatTokens(this.totalTokens)));
+        parts.push(chalk2.magenta(formatTokens(this.totalTokens)));
       }
       if (this.iterations > 0) {
-        parts.push(chalk.blue(`i${this.iterations}`));
+        parts.push(chalk2.blue(`i${this.iterations}`));
       }
       if (this.totalCost > 0) {
-        parts.push(chalk.cyan(`$${this.formatCost(this.totalCost)}`));
+        parts.push(chalk2.cyan(`$${formatCost(this.totalCost)}`));
       }
-      parts.push(chalk.dim(`${elapsed}s`));
-    }
-    return `${parts.join(chalk.dim(" \u2502 "))} ${chalk.green(">")} `;
-  }
-  /**
-   * Formats token count compactly (3625 -> "3.6k").
-   */
-  formatTokens(tokens) {
-    return tokens >= 1e3 ? `${(tokens / 1e3).toFixed(1)}k` : `${tokens}`;
-  }
-  /**
-   * Formats cost compactly (0.0001234 -> "0.00012", 0.1234 -> "0.12", 1.234 -> "1.23").
-   */
-  formatCost(cost) {
-    if (cost < 1e-3) {
-      return cost.toFixed(5);
-    }
-    if (cost < 0.01) {
-      return cost.toFixed(4);
-    }
-    if (cost < 1) {
-      return cost.toFixed(3);
+      parts.push(chalk2.dim(`${elapsed}s`));
     }
-    return cost.toFixed(2);
+    return `${parts.join(chalk2.dim(" | "))} ${chalk2.green(">")} `;
   }
 };
 async function readStream(stream) {
@@ -655,44 +708,12 @@ async function resolvePrompt(promptArg, env) {
   }
   return pipedInput;
 }
-function renderSummary(metadata) {
-  const parts = [];
-  if (metadata.iterations !== void 0) {
-    parts.push(chalk.dim(`iterations: ${metadata.iterations}`));
-  }
-  if (metadata.finishReason) {
-    parts.push(chalk.dim(`finish: ${metadata.finishReason}`));
-  }
-  if (metadata.usage) {
-    const { inputTokens, outputTokens, totalTokens } = metadata.usage;
-    parts.push(
-      chalk.dim(`tokens: `) + chalk.cyan(`${totalTokens}`) + chalk.dim(` (in: ${inputTokens}, out: ${outputTokens})`)
-    );
-  }
-  if (metadata.cost !== void 0 && metadata.cost > 0) {
-    let formattedCost;
-    if (metadata.cost < 1e-3) {
-      formattedCost = metadata.cost.toFixed(5);
-    } else if (metadata.cost < 0.01) {
-      formattedCost = metadata.cost.toFixed(4);
-    } else if (metadata.cost < 1) {
-      formattedCost = metadata.cost.toFixed(3);
-    } else {
-      formattedCost = metadata.cost.toFixed(2);
-    }
-    parts.push(chalk.dim(`cost: `) + chalk.cyan(`$${formattedCost}`));
-  }
-  if (parts.length === 0) {
-    return null;
-  }
-  return parts.join(chalk.dim(" \u2502 "));
-}
 async function executeAction(action, env) {
   try {
     await action();
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    env.stderr.write(`${chalk.red.bold("Error:")} ${message}
+    env.stderr.write(`${chalk2.red.bold("Error:")} ${message}
 `);
     env.setExitCode(1);
   }
@@ -735,26 +756,15 @@ ${statsPrompt}` : statsPrompt;
     }
   };
 }
-function formatGadgetSummary(result) {
-  const gadgetLabel = chalk2.magenta.bold(result.gadgetName);
-  const timeLabel = chalk2.dim(`${Math.round(result.executionTimeMs)}ms`);
-  if (result.error) {
-    return `${chalk2.red("\u2717")} ${gadgetLabel} ${chalk2.red("error:")} ${result.error} ${timeLabel}`;
-  }
-  if (result.breaksLoop) {
-    return `${chalk2.yellow("\u23F9")} ${gadgetLabel} ${chalk2.yellow("finished:")} ${result.result} ${timeLabel}`;
-  }
-  const maxLen = 80;
-  const shouldTruncate = result.gadgetName !== "TellUser";
-  const resultText = result.result ? shouldTruncate && result.result.length > maxLen ? `${result.result.slice(0, maxLen)}...` : result.result : "";
-  return `${chalk2.green("\u2713")} ${gadgetLabel} ${chalk2.dim("\u2192")} ${resultText} ${timeLabel}`;
-}
 async function handleAgentCommand(promptArg, options, env) {
   const prompt = await resolvePrompt(promptArg, env);
   const client = env.createClient();
   const registry = new GadgetRegistry();
   if (options.builtins !== false) {
     for (const gadget of builtinGadgets) {
+      if (options.builtinInteraction === false && gadget.name === "AskUser") {
+        continue;
+      }
       registry.registerByClass(gadget);
     }
   }
@@ -771,16 +781,28 @@ async function handleAgentCommand(promptArg, options, env) {
   let finishReason;
   let usage;
   let iterations = 0;
-  const estimateMessagesTokens = (messages) => {
-    const totalChars = messages.reduce((sum, m) => sum + (m.content?.length ?? 0), 0);
-    return Math.round(totalChars / FALLBACK_CHARS_PER_TOKEN);
+  const countMessagesTokens = async (model, messages) => {
+    try {
+      return await client.countTokens(model, messages);
+    } catch {
+      const totalChars = messages.reduce((sum, m) => sum + (m.content?.length ?? 0), 0);
+      return Math.round(totalChars / FALLBACK_CHARS_PER_TOKEN);
+    }
   };
   const builder = new AgentBuilder(client).withModel(options.model).withLogger(env.createLogger("llmist:cli:agent")).withHooks({
     observers: {
+      // onLLMCallStart: Start progress indicator for each LLM call
+      // This showcases how to react to agent lifecycle events
       onLLMCallStart: async (context) => {
-        const estimate = estimateMessagesTokens(context.options.messages);
-        progress.startCall(context.options.model, estimate);
+        const inputTokens = await countMessagesTokens(
+          context.options.model,
+          context.options.messages
+        );
+        progress.startCall(context.options.model, inputTokens);
+        progress.setInputTokens(inputTokens, false);
       },
+      // onStreamChunk: Real-time updates as LLM generates tokens
+      // This enables responsive UIs that show progress during generation
       onStreamChunk: async (context) => {
         progress.update(context.accumulatedText.length);
         if (context.usage) {
@@ -792,10 +814,20 @@ async function handleAgentCommand(promptArg, options, env) {
           }
         }
       },
+      // onLLMCallComplete: Finalize metrics after each LLM call
+      // This is where you'd typically log metrics or update dashboards
       onLLMCallComplete: async (context) => {
         finishReason = context.finishReason;
         usage = context.usage;
         iterations = Math.max(iterations, context.iteration + 1);
+        if (context.usage) {
+          if (context.usage.inputTokens) {
+            progress.setInputTokens(context.usage.inputTokens, false);
+          }
+          if (context.usage.outputTokens) {
+            progress.setOutputTokens(context.usage.outputTokens, false);
+          }
+        }
         progress.endCall(context.usage);
       }
     }
@@ -837,7 +869,8 @@ async function handleAgentCommand(promptArg, options, env) {
       finishReason,
       usage,
       iterations,
-      cost: progress.getTotalCost()
+      cost: progress.getTotalCost(),
+      elapsedSeconds: progress.getTotalElapsedSeconds()
     });
     if (summary) {
       env.stderr.write(`${summary}
@@ -864,7 +897,7 @@ function registerAgentCommand(program, env) {
     OPTION_DESCRIPTIONS.parameterFormat,
     parseParameterFormat,
     DEFAULT_PARAMETER_FORMAT
-  ).option(OPTION_FLAGS.noBuiltins, OPTION_DESCRIPTIONS.noBuiltins).action(
+  ).option(OPTION_FLAGS.noBuiltins, OPTION_DESCRIPTIONS.noBuiltins).option(OPTION_FLAGS.noBuiltinInteraction, OPTION_DESCRIPTIONS.noBuiltinInteraction).action(
     (prompt, options) => executeAction(() => handleAgentCommand(prompt, options, env), env)
   );
 }
@@ -1002,7 +1035,7 @@ function renderCompactTable(models, stream) {
   );
   stream.write(chalk3.dim("\u2500".repeat(idWidth + nameWidth + contextWidth + inputWidth + outputWidth + 8)) + "\n");
   for (const model of models) {
-    const contextFormatted = formatTokens(model.contextWindow);
+    const contextFormatted = formatTokens2(model.contextWindow);
     const inputPrice = `$${model.pricing.input.toFixed(2)}`;
     const outputPrice = `$${model.pricing.output.toFixed(2)}`;
     stream.write(
@@ -1021,9 +1054,9 @@ function renderVerboseTable(models, stream) {
     stream.write(chalk3.dim("  " + "\u2500".repeat(60)) + "\n");
     stream.write(`  ${chalk3.dim("Name:")}         ${chalk3.white(model.displayName)}
 `);
-    stream.write(`  ${chalk3.dim("Context:")}      ${chalk3.yellow(formatTokens(model.contextWindow))}
+    stream.write(`  ${chalk3.dim("Context:")}      ${chalk3.yellow(formatTokens2(model.contextWindow))}
 `);
-    stream.write(`  ${chalk3.dim("Max Output:")}   ${chalk3.yellow(formatTokens(model.maxOutputTokens))}
+    stream.write(`  ${chalk3.dim("Max Output:")}   ${chalk3.yellow(formatTokens2(model.maxOutputTokens))}
 `);
     stream.write(`  ${chalk3.dim("Pricing:")}      ${chalk3.cyan(`$${model.pricing.input.toFixed(2)} input`)} ${chalk3.dim("/")} ${chalk3.cyan(`$${model.pricing.output.toFixed(2)} output`)} ${chalk3.dim("(per 1M tokens)")}
 `);
@@ -1086,7 +1119,7 @@ function renderJSON(models, stream) {
   };
   stream.write(JSON.stringify(output, null, 2) + "\n");
 }
-function formatTokens(count) {
+function formatTokens2(count) {
   if (count >= 1e6) {
     return `${(count / 1e6).toFixed(1)}M tokens`;
   } else if (count >= 1e3) {