llmist 0.1.4 → 0.1.5

package/README.md

@@ -1,8 +1,8 @@
 # llmist
 
 [![CI](https://github.com/zbigniewsobiecki/llmist/actions/workflows/ci.yml/badge.svg)](https://github.com/zbigniewsobiecki/llmist/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/zbigniewsobiecki/llmist/branch/main/graph/badge.svg)](https://codecov.io/gh/zbigniewsobiecki/llmist)
-[![npm version](https://badge.fury.io/js/llmist.svg)](https://www.npmjs.com/package/llmist)
+[![codecov](https://codecov.io/gh/zbigniewsobiecki/llmist/graph/badge.svg)](https://codecov.io/gh/zbigniewsobiecki/llmist)
+[![npm version](https://img.shields.io/npm/v/llmist.svg)](https://www.npmjs.com/package/llmist)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 > **Universal TypeScript LLM client with streaming-first tool execution and simple, extensible agent framework**
@@ -153,31 +153,85 @@ const calculator = createGadget({
 
 ### 🪝 Lifecycle Hooks
 
+Monitor, transform, and control agent execution with ready-to-use presets or custom hooks:
+
+**Quick start with presets:**
+
 ```typescript
-import { HookPresets } from 'llmist';
+import { LLMist, HookPresets } from 'llmist';
+
+// Full monitoring suite (recommended for development)
+await LLMist.createAgent()
+  .withHooks(HookPresets.monitoring())
+  .ask('Your prompt');
+// Output: Logs + timing + token tracking + error logging
 
-// Use presets for instant monitoring
+// Combine specific presets for focused monitoring
 await LLMist.createAgent()
-  .withHooks(HookPresets.monitoring())  // Logs + timing + tokens + errors
+  .withHooks(HookPresets.merge(
+    HookPresets.timing(),
+    HookPresets.tokenTracking()
+  ))
   .ask('Your prompt');
+```
 
-// Or combine specific presets
-.withHooks(HookPresets.merge(
-  HookPresets.timing(),
-  HookPresets.tokenTracking()
-))
+**Available presets:**
+- `logging()` / `logging({ verbose: true })` - Event logging with optional details
+- `timing()` - Execution time measurements
+- `tokenTracking()` - Cumulative token usage and cost tracking
+- `errorLogging()` - Detailed error information
+- `silent()` - No output (for testing)
+- `monitoring()` - All-in-one preset combining logging, timing, tokens, and errors
+- `merge()` - Combine multiple presets or add custom hooks
 
-// Or write custom hooks
+**Production vs Development patterns:**
+
+```typescript
+// Environment-based configuration
+const isDev = process.env.NODE_ENV === 'development';
+const hooks = isDev
+  ? HookPresets.monitoring({ verbose: true })  // Full visibility in dev
+  : HookPresets.merge(
+      HookPresets.errorLogging(),              // Only errors in prod
+      HookPresets.tokenTracking()              // Track costs
+    );
+
+await LLMist.createAgent()
+  .withHooks(hooks)
+  .ask('Your prompt');
+```
+
+**Custom hooks for advanced control:**
+
+```typescript
+// Observers: read-only monitoring
 .withHooks({
   observers: {
     onLLMCallComplete: async (ctx) => {
       console.log(`Used ${ctx.usage?.totalTokens} tokens`);
+      await sendMetricsToDataDog(ctx);
     },
   },
+})
+
+// Interceptors: transform data in flight
+.withHooks({
   interceptors: {
     interceptTextChunk: (chunk) => chunk.toUpperCase(),
   },
 })
+
+// Controllers: control execution flow
+.withHooks({
+  controllers: {
+    beforeLLMCall: async (ctx) => {
+      if (shouldCache(ctx)) {
+        return { action: 'skip', syntheticResponse: cachedResponse };
+      }
+      return { action: 'proceed' };
+    },
+  },
+})
 ```
 
 📖 **[Hooks Guide](./docs/HOOKS.md)** | **[Examples](./examples/03-hooks.ts)**

package/dist/cli.cjs

@@ -4253,7 +4253,7 @@ var import_commander3 = require("commander");
 // package.json
 var package_default = {
   name: "llmist",
-  version: "0.1.4",
+  version: "0.1.5",
   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",
@@ -4356,14 +4356,13 @@ var package_default = {
 
 // src/cli/agent-command.ts
 var import_promises = require("readline/promises");
-var import_chalk3 = __toESM(require("chalk"), 1);
+var import_chalk2 = __toESM(require("chalk"), 1);
 var import_commander2 = require("commander");
 init_builder();
 init_registry();
 init_constants2();
 
 // src/cli/builtin-gadgets.ts
-var import_chalk = __toESM(require("chalk"), 1);
 var import_zod = require("zod");
 
 // src/gadgets/gadget.ts
@@ -4539,17 +4538,17 @@ var tellUser = createGadget({
     type: import_zod.z.enum(["info", "success", "warning", "error"]).default("info").describe("Message type: info, success, warning, or error")
   }),
   execute: ({ message, done, type }) => {
-    const formatters = {
-      info: (msg) => import_chalk.default.blue(`\u2139\uFE0F  ${msg}`),
-      success: (msg) => import_chalk.default.green(`\u2705 ${msg}`),
-      warning: (msg) => import_chalk.default.yellow(`\u26A0\uFE0F  ${msg}`),
-      error: (msg) => import_chalk.default.red(`\u274C ${msg}`)
+    const prefixes = {
+      info: "\u2139\uFE0F  ",
+      success: "\u2705 ",
+      warning: "\u26A0\uFE0F  ",
+      error: "\u274C "
     };
-    const formatted = formatters[type](message);
+    const plainResult = prefixes[type] + message;
     if (done) {
-      throw new BreakLoopException(formatted);
+      throw new BreakLoopException(plainResult);
     }
-    return formatted;
+    return plainResult;
   }
 });
 var builtinGadgets = [askUser, tellUser];
@@ -4651,7 +4650,7 @@ async function loadGadgets(specifiers, cwd, importer = (specifier) => import(spe
 }
 
 // src/cli/utils.ts
-var import_chalk2 = __toESM(require("chalk"), 1);
+var import_chalk = __toESM(require("chalk"), 1);
 var import_commander = require("commander");
 init_constants2();
 function createNumericParser({
@@ -4710,9 +4709,10 @@ function isInteractive(stream2) {
 var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
 var SPINNER_DELAY_MS = 500;
 var StreamProgress = class {
-  constructor(target, isTTY) {
+  constructor(target, isTTY, modelRegistry) {
     this.target = target;
     this.isTTY = isTTY;
+    this.modelRegistry = modelRegistry;
   }
   // Animation state
   frameIndex = 0;
@@ -4733,6 +4733,7 @@ var StreamProgress = class {
   // Cumulative stats (cumulative mode)
   totalStartTime = Date.now();
   totalTokens = 0;
+  totalCost = 0;
   iterations = 0;
   /**
    * Starts a new LLM call. Switches to streaming mode.
@@ -4759,6 +4760,20 @@ var StreamProgress = class {
     this.iterations++;
     if (usage) {
       this.totalTokens += usage.totalTokens;
+      if (this.modelRegistry && this.model) {
+        try {
+          const modelName = this.model.includes(":") ? this.model.split(":")[1] : this.model;
+          const cost = this.modelRegistry.estimateCost(
+            modelName,
+            usage.inputTokens,
+            usage.outputTokens
+          );
+          if (cost) {
+            this.totalCost += cost.totalCost;
+          }
+        } catch {
+        }
+      }
     }
     this.pause();
     this.mode = "cumulative";
@@ -4822,33 +4837,39 @@ var StreamProgress = class {
     const outTokens = this.callOutputTokensEstimated ? Math.round(this.callOutputChars / FALLBACK_CHARS_PER_TOKEN) : this.callOutputTokens;
     const parts = [];
     if (this.model) {
-      parts.push(import_chalk2.default.cyan(this.model));
+      parts.push(import_chalk.default.cyan(this.model));
     }
     if (this.callInputTokens > 0) {
       const prefix = this.callInputTokensEstimated ? "~" : "";
-      parts.push(import_chalk2.default.dim("out:") + import_chalk2.default.yellow(` ${prefix}${this.callInputTokens}`));
+      parts.push(import_chalk.default.dim("out:") + import_chalk.default.yellow(` ${prefix}${this.callInputTokens}`));
     }
     if (this.isStreaming || outTokens > 0) {
       const prefix = this.callOutputTokensEstimated ? "~" : "";
-      parts.push(import_chalk2.default.dim("in:") + import_chalk2.default.green(` ${prefix}${outTokens}`));
+      parts.push(import_chalk.default.dim("in:") + import_chalk.default.green(` ${prefix}${outTokens}`));
+    }
+    if (this.totalCost > 0) {
+      parts.push(import_chalk.default.dim("cost:") + import_chalk.default.cyan(` $${this.formatCost(this.totalCost)}`));
     }
-    parts.push(import_chalk2.default.dim(`${elapsed}s`));
-    this.target.write(`\r${import_chalk2.default.cyan(spinner)} ${parts.join(import_chalk2.default.dim(" | "))}`);
+    parts.push(import_chalk.default.dim(`${elapsed}s`));
+    this.target.write(`\r${import_chalk.default.cyan(spinner)} ${parts.join(import_chalk.default.dim(" | "))}`);
   }
   renderCumulativeMode(spinner) {
     const elapsed = ((Date.now() - this.totalStartTime) / 1e3).toFixed(1);
     const parts = [];
     if (this.model) {
-      parts.push(import_chalk2.default.cyan(this.model));
+      parts.push(import_chalk.default.cyan(this.model));
     }
     if (this.totalTokens > 0) {
-      parts.push(import_chalk2.default.dim("total:") + import_chalk2.default.magenta(` ${this.totalTokens}`));
+      parts.push(import_chalk.default.dim("total:") + import_chalk.default.magenta(` ${this.totalTokens}`));
     }
     if (this.iterations > 0) {
-      parts.push(import_chalk2.default.dim("iter:") + import_chalk2.default.blue(` ${this.iterations}`));
+      parts.push(import_chalk.default.dim("iter:") + import_chalk.default.blue(` ${this.iterations}`));
     }
-    parts.push(import_chalk2.default.dim(`${elapsed}s`));
-    this.target.write(`\r${import_chalk2.default.cyan(spinner)} ${parts.join(import_chalk2.default.dim(" | "))}`);
+    if (this.totalCost > 0) {
+      parts.push(import_chalk.default.dim("cost:") + import_chalk.default.cyan(` $${this.formatCost(this.totalCost)}`));
+    }
+    parts.push(import_chalk.default.dim(`${elapsed}s`));
+    this.target.write(`\r${import_chalk.default.cyan(spinner)} ${parts.join(import_chalk.default.dim(" | "))}`);
   }
   /**
    * Pauses the progress indicator and clears the line.
@@ -4876,6 +4897,12 @@ var StreamProgress = class {
   complete() {
     this.pause();
   }
+  /**
+   * Returns the total accumulated cost across all calls.
+   */
+  getTotalCost() {
+    return this.totalCost;
+  }
   /**
    * Returns a formatted prompt string with stats (like bash PS1).
    * Shows current call stats during streaming, cumulative stats otherwise.
@@ -4890,25 +4917,28 @@ var StreamProgress = class {
       if (this.callInputTokens > 0) {
         const prefix = this.callInputTokensEstimated ? "~" : "";
         parts.push(
-          import_chalk2.default.dim("out:") + import_chalk2.default.yellow(` ${prefix}${this.formatTokens(this.callInputTokens)}`)
+          import_chalk.default.dim("out:") + import_chalk.default.yellow(` ${prefix}${this.formatTokens(this.callInputTokens)}`)
         );
       }
       if (outTokens > 0) {
         const prefix = outEstimated ? "~" : "";
-        parts.push(import_chalk2.default.dim("in:") + import_chalk2.default.green(` ${prefix}${this.formatTokens(outTokens)}`));
+        parts.push(import_chalk.default.dim("in:") + import_chalk.default.green(` ${prefix}${this.formatTokens(outTokens)}`));
       }
-      parts.push(import_chalk2.default.dim(`${elapsed}s`));
+      parts.push(import_chalk.default.dim(`${elapsed}s`));
     } else {
       const elapsed = Math.round((Date.now() - this.totalStartTime) / 1e3);
       if (this.totalTokens > 0) {
-        parts.push(import_chalk2.default.magenta(this.formatTokens(this.totalTokens)));
+        parts.push(import_chalk.default.magenta(this.formatTokens(this.totalTokens)));
       }
       if (this.iterations > 0) {
-        parts.push(import_chalk2.default.blue(`i${this.iterations}`));
+        parts.push(import_chalk.default.blue(`i${this.iterations}`));
       }
-      parts.push(import_chalk2.default.dim(`${elapsed}s`));
+      if (this.totalCost > 0) {
+        parts.push(import_chalk.default.cyan(`$${this.formatCost(this.totalCost)}`));
+      }
+      parts.push(import_chalk.default.dim(`${elapsed}s`));
     }
-    return `${parts.join(import_chalk2.default.dim(" \u2502 "))} ${import_chalk2.default.green(">")} `;
+    return `${parts.join(import_chalk.default.dim(" \u2502 "))} ${import_chalk.default.green(">")} `;
   }
   /**
    * Formats token count compactly (3625 -> "3.6k").
@@ -4916,6 +4946,21 @@ var StreamProgress = class {
   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);
+    }
+    return cost.toFixed(2);
+  }
 };
 async function readStream(stream2) {
   const chunks = [];
@@ -4947,29 +4992,42 @@ async function resolvePrompt(promptArg, env) {
 function renderSummary(metadata) {
   const parts = [];
   if (metadata.iterations !== void 0) {
-    parts.push(import_chalk2.default.dim(`iterations: ${metadata.iterations}`));
+    parts.push(import_chalk.default.dim(`iterations: ${metadata.iterations}`));
   }
   if (metadata.finishReason) {
-    parts.push(import_chalk2.default.dim(`finish: ${metadata.finishReason}`));
+    parts.push(import_chalk.default.dim(`finish: ${metadata.finishReason}`));
   }
   if (metadata.usage) {
     const { inputTokens, outputTokens, totalTokens } = metadata.usage;
     parts.push(
-      import_chalk2.default.dim(`tokens: `) + import_chalk2.default.cyan(`${totalTokens}`) + import_chalk2.default.dim(` (in: ${inputTokens}, out: ${outputTokens})`)
+      import_chalk.default.dim(`tokens: `) + import_chalk.default.cyan(`${totalTokens}`) + import_chalk.default.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(import_chalk.default.dim(`cost: `) + import_chalk.default.cyan(`$${formattedCost}`));
+  }
   if (parts.length === 0) {
     return null;
   }
-  return `${import_chalk2.default.dim("\u2500".repeat(40))}
-${parts.join(import_chalk2.default.dim(" \u2502 "))}`;
+  return `${import_chalk.default.dim("\u2500".repeat(40))}
+${parts.join(import_chalk.default.dim(" \u2502 "))}`;
 }
 async function executeAction(action, env) {
   try {
     await action();
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    env.stderr.write(`${import_chalk2.default.red.bold("Error:")} ${message}
+    env.stderr.write(`${import_chalk.default.red.bold("Error:")} ${message}
 `);
     env.setExitCode(1);
   }
@@ -5013,17 +5071,18 @@ ${statsPrompt}` : statsPrompt;
   };
 }
 function formatGadgetSummary(result) {
-  const gadgetLabel = import_chalk3.default.magenta.bold(result.gadgetName);
-  const timeLabel = import_chalk3.default.dim(`${Math.round(result.executionTimeMs)}ms`);
+  const gadgetLabel = import_chalk2.default.magenta.bold(result.gadgetName);
+  const timeLabel = import_chalk2.default.dim(`${Math.round(result.executionTimeMs)}ms`);
   if (result.error) {
-    return `${import_chalk3.default.red("\u2717")} ${gadgetLabel} ${import_chalk3.default.red("error:")} ${result.error} ${timeLabel}`;
+    return `${import_chalk2.default.red("\u2717")} ${gadgetLabel} ${import_chalk2.default.red("error:")} ${result.error} ${timeLabel}`;
   }
   if (result.breaksLoop) {
-    return `${import_chalk3.default.yellow("\u23F9")} ${gadgetLabel} ${import_chalk3.default.yellow("finished:")} ${result.result} ${timeLabel}`;
+    return `${import_chalk2.default.yellow("\u23F9")} ${gadgetLabel} ${import_chalk2.default.yellow("finished:")} ${result.result} ${timeLabel}`;
   }
   const maxLen = 80;
-  const resultText = result.result ? result.result.length > maxLen ? `${result.result.slice(0, maxLen)}...` : result.result : "";
-  return `${import_chalk3.default.green("\u2713")} ${gadgetLabel} ${import_chalk3.default.dim("\u2192")} ${resultText} ${timeLabel}`;
+  const shouldTruncate = result.gadgetName !== "TellUser";
+  const resultText = result.result ? shouldTruncate && result.result.length > maxLen ? `${result.result.slice(0, maxLen)}...` : result.result : "";
+  return `${import_chalk2.default.green("\u2713")} ${gadgetLabel} ${import_chalk2.default.dim("\u2192")} ${resultText} ${timeLabel}`;
 }
 async function handleAgentCommand(promptArg, options, env) {
   const prompt = await resolvePrompt(promptArg, env);
@@ -5043,7 +5102,7 @@ async function handleAgentCommand(promptArg, options, env) {
   }
   const printer = new StreamPrinter(env.stdout);
   const stderrTTY = env.stderr.isTTY === true;
-  const progress = new StreamProgress(env.stderr, stderrTTY);
+  const progress = new StreamProgress(env.stderr, stderrTTY, client.modelRegistry);
   let finishReason;
   let usage;
   let iterations = 0;
@@ -5100,16 +5159,25 @@ async function handleAgentCommand(promptArg, options, env) {
       printer.write(event.content);
     } else if (event.type === "gadget_result") {
       progress.pause();
-      env.stderr.write(`${formatGadgetSummary(event.result)}
+      if (stderrTTY) {
+        env.stderr.write(`${formatGadgetSummary(event.result)}
 `);
+      }
     }
   }
   progress.complete();
   printer.ensureNewline();
-  const summary = renderSummary({ finishReason, usage, iterations });
-  if (summary) {
-    env.stderr.write(`${summary}
+  if (stderrTTY) {
+    const summary = renderSummary({
+      finishReason,
+      usage,
+      iterations,
+      cost: progress.getTotalCost()
+    });
+    if (summary) {
+      env.stderr.write(`${summary}
 `);
+    }
   }
 }
 function registerAgentCommand(program, env) {
@@ -5155,7 +5223,7 @@ async function handleCompleteCommand(promptArg, options, env) {
   });
   const printer = new StreamPrinter(env.stdout);
   const stderrTTY = env.stderr.isTTY === true;
-  const progress = new StreamProgress(env.stderr, stderrTTY);
+  const progress = new StreamProgress(env.stderr, stderrTTY, client.modelRegistry);
   const estimatedInputTokens = Math.round(prompt.length / FALLBACK_CHARS_PER_TOKEN);
   progress.startCall(options.model, estimatedInputTokens);
   let finishReason;
@@ -5181,12 +5249,15 @@ async function handleCompleteCommand(promptArg, options, env) {
       finishReason = chunk.finishReason;
     }
   }
+  progress.endCall(usage);
   progress.complete();
   printer.ensureNewline();
-  const summary = renderSummary({ finishReason, usage });
-  if (summary) {
-    env.stderr.write(`${summary}
+  if (stderrTTY) {
+    const summary = renderSummary({ finishReason, usage, cost: progress.getTotalCost() });
+    if (summary) {
+      env.stderr.write(`${summary}
 `);
+    }
   }
 }
 function registerCompleteCommand(program, env) {
@@ -5208,7 +5279,7 @@ function registerCompleteCommand(program, env) {
 
 // src/cli/environment.ts
 var import_node_readline = __toESM(require("readline"), 1);
-var import_chalk4 = __toESM(require("chalk"), 1);
+var import_chalk3 = __toESM(require("chalk"), 1);
 init_client();
 init_logger();
 var LOG_LEVEL_MAP = {
@@ -5254,14 +5325,14 @@ function createPromptFunction(stdin, stdout) {
         output: stdout
       });
       stdout.write("\n");
-      stdout.write(`${import_chalk4.default.cyan("\u2500".repeat(60))}
+      stdout.write(`${import_chalk3.default.cyan("\u2500".repeat(60))}
 `);
-      stdout.write(import_chalk4.default.cyan.bold("\u{1F916} Agent asks:\n"));
+      stdout.write(import_chalk3.default.cyan.bold("\u{1F916} Agent asks:\n"));
       stdout.write(`${question}
 `);
-      stdout.write(`${import_chalk4.default.cyan("\u2500".repeat(60))}
+      stdout.write(`${import_chalk3.default.cyan("\u2500".repeat(60))}
 `);
-      rl.question(import_chalk4.default.green.bold("You: "), (answer) => {
+      rl.question(import_chalk3.default.green.bold("You: "), (answer) => {
         rl.close();
         resolve(answer);
       });