llmist 15.10.0 → 15.12.0

package/dist/index.cjs

@@ -1785,9 +1785,25 @@ function resolveRetryConfig(config) {
     maxRetryAfterMs: config.maxRetryAfterMs ?? DEFAULT_RETRY_CONFIG.maxRetryAfterMs
   };
 }
+function getErrorStatusCode(error) {
+  const errAny = error;
+  if (typeof errAny.status === "number") return errAny.status;
+  if (typeof errAny.code === "number") return errAny.code;
+  if (typeof errAny.statusCode === "number") return errAny.statusCode;
+  if (typeof errAny.code === "string" && /^\d{3}$/.test(errAny.code)) {
+    return parseInt(errAny.code, 10);
+  }
+  return void 0;
+}
 function isRetryableError(error) {
   const message = error.message.toLowerCase();
   const name = error.name;
+  const statusCode = getErrorStatusCode(error);
+  if (statusCode !== void 0) {
+    if (statusCode === 429) return true;
+    if (statusCode >= 500 && statusCode < 600) return true;
+    if (statusCode >= 400 && statusCode < 500) return false;
+  }
   if (message.includes("429") || message.includes("rate limit") || message.includes("rate_limit")) {
     return true;
   }
@@ -3958,66 +3974,1015 @@ var init_registry = __esm({
             registry.register(name, instance);
           }
         }
-        return registry;
+        return registry;
+      }
+      /**
+       * Registers multiple gadgets at once from an array.
+       *
+       * @param gadgets - Array of gadget instances or classes
+       * @returns This registry for chaining
+       *
+       * @example
+       * ```typescript
+       * registry.registerMany([Calculator, Weather, Email]);
+       * registry.registerMany([new Calculator(), new Weather()]);
+       * ```
+       */
+      registerMany(gadgets) {
+        for (const gadget of gadgets) {
+          const instance = typeof gadget === "function" ? new gadget() : gadget;
+          this.registerByClass(instance);
+        }
+        return this;
+      }
+      // Register a gadget by name
+      register(name, gadget) {
+        const normalizedName = name.toLowerCase();
+        if (this.gadgets.has(normalizedName)) {
+          throw new Error(`Gadget '${name}' is already registered`);
+        }
+        if (gadget.parameterSchema) {
+          validateGadgetSchema(gadget.parameterSchema, name);
+        }
+        this.gadgets.set(normalizedName, gadget);
+      }
+      // Register a gadget using its name property or class name
+      registerByClass(gadget) {
+        const name = gadget.name ?? gadget.constructor.name;
+        this.register(name, gadget);
+      }
+      // Get gadget by name (case-insensitive)
+      get(name) {
+        return this.gadgets.get(name.toLowerCase());
+      }
+      // Check if gadget exists (case-insensitive)
+      has(name) {
+        return this.gadgets.has(name.toLowerCase());
+      }
+      // Get all registered gadget names
+      getNames() {
+        return Array.from(this.gadgets.keys());
+      }
+      // Get all gadgets for instruction generation
+      getAll() {
+        return Array.from(this.gadgets.values());
+      }
+      // Unregister gadget (useful for testing, case-insensitive)
+      unregister(name) {
+        return this.gadgets.delete(name.toLowerCase());
+      }
+      // Clear all gadgets (useful for testing)
+      clear() {
+        this.gadgets.clear();
+      }
+    };
+  }
+});
+
+// src/agent/file-logging.ts
+function formatLlmRequest(messages) {
+  const lines = [];
+  for (const msg of messages) {
+    lines.push(`=== ${msg.role.toUpperCase()} ===`);
+    lines.push(msg.content ? extractMessageText(msg.content) : "");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function formatCallNumber(n, padding = 4) {
+  return n.toString().padStart(padding, "0");
+}
+async function writeLogFile(dir, filename, content) {
+  await (0, import_promises2.mkdir)(dir, { recursive: true });
+  await (0, import_promises2.writeFile)((0, import_node_path3.join)(dir, filename), content, "utf-8");
+}
+function createFileLoggingHooks(options) {
+  const {
+    directory,
+    startingCounter = 1,
+    counterPadding = 4,
+    skipSubagents = true,
+    formatRequest = formatLlmRequest,
+    onFileWritten
+  } = options;
+  let callCounter = startingCounter - 1;
+  return {
+    observers: {
+      /**
+       * Write request file when LLM call is ready (messages are finalized).
+       */
+      onLLMCallReady: async (context) => {
+        if (skipSubagents && context.subagentContext) {
+          return;
+        }
+        callCounter++;
+        const filename = `${formatCallNumber(callCounter, counterPadding)}.request`;
+        const content = formatRequest(context.options.messages);
+        try {
+          await writeLogFile(directory, filename, content);
+          if (onFileWritten) {
+            onFileWritten({
+              filePath: (0, import_node_path3.join)(directory, filename),
+              type: "request",
+              callNumber: callCounter,
+              contentLength: content.length
+            });
+          }
+        } catch (error) {
+          console.warn(`[file-logging] Failed to write ${filename}:`, error);
+        }
+      },
+      /**
+       * Write response file when LLM call completes.
+       */
+      onLLMCallComplete: async (context) => {
+        if (skipSubagents && context.subagentContext) {
+          return;
+        }
+        const filename = `${formatCallNumber(callCounter, counterPadding)}.response`;
+        const content = context.rawResponse;
+        try {
+          await writeLogFile(directory, filename, content);
+          if (onFileWritten) {
+            onFileWritten({
+              filePath: (0, import_node_path3.join)(directory, filename),
+              type: "response",
+              callNumber: callCounter,
+              contentLength: content.length
+            });
+          }
+        } catch (error) {
+          console.warn(`[file-logging] Failed to write ${filename}:`, error);
+        }
+      }
+    }
+  };
+}
+function getEnvFileLoggingHooks() {
+  const directory = process.env[ENV_LOG_RAW_DIRECTORY]?.trim();
+  if (!directory) {
+    return void 0;
+  }
+  return createFileLoggingHooks({ directory });
+}
+var import_promises2, import_node_path3, ENV_LOG_RAW_DIRECTORY;
+var init_file_logging = __esm({
+  "src/agent/file-logging.ts"() {
+    "use strict";
+    import_promises2 = require("fs/promises");
+    import_node_path3 = require("path");
+    init_messages();
+    ENV_LOG_RAW_DIRECTORY = "LLMIST_LOG_RAW_DIRECTORY";
+  }
+});
+
+// src/agent/hook-presets.ts
+var HookPresets;
+var init_hook_presets = __esm({
+  "src/agent/hook-presets.ts"() {
+    "use strict";
+    init_file_logging();
+    HookPresets = class _HookPresets {
+      /**
+       * Logs LLM calls and gadget execution to console with optional verbosity.
+       *
+       * **Output (basic mode):**
+       * - LLM call start/complete events with iteration numbers
+       * - Gadget execution start/complete with gadget names
+       * - Token counts when available
+       *
+       * **Output (verbose mode):**
+       * - All basic mode output
+       * - Full gadget parameters (formatted JSON)
+       * - Full gadget results
+       * - Complete LLM response text
+       *
+       * **Use cases:**
+       * - Basic development debugging and execution flow visibility
+       * - Understanding agent decision-making and tool usage
+       * - Troubleshooting gadget invocations
+       *
+       * **Performance:** Minimal overhead. Console writes are synchronous but fast.
+       *
+       * @param options - Logging options
+       * @param options.verbose - Include full parameters and results. Default: false
+       * @returns Hook configuration that can be passed to .withHooks()
+       *
+       * @example
+       * ```typescript
+       * // Basic logging
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.logging())
+       *   .ask("Calculate 15 * 23");
+       * // Output: [LLM] Starting call (iteration 0)
+       * //         [GADGET] Executing Calculator
+       * //         [GADGET] Completed Calculator
+       * //         [LLM] Completed (tokens: 245)
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Verbose logging with full details
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.logging({ verbose: true }))
+       *   .ask("Calculate 15 * 23");
+       * // Output includes: parameters, results, and full responses
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Environment-based verbosity
+       * const isDev = process.env.NODE_ENV === 'development';
+       * .withHooks(HookPresets.logging({ verbose: isDev }))
+       * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsloggingoptions | Full documentation}
+       */
+      static logging(options = {}) {
+        return {
+          observers: {
+            onLLMCallStart: async (ctx) => {
+              console.log(`[LLM] Starting call (iteration ${ctx.iteration})`);
+            },
+            onLLMCallComplete: async (ctx) => {
+              const tokens = ctx.usage?.totalTokens ?? "unknown";
+              console.log(`[LLM] Completed (tokens: ${tokens})`);
+              if (options.verbose && ctx.finalMessage) {
+                console.log(`[LLM] Response: ${ctx.finalMessage}`);
+              }
+            },
+            onGadgetExecutionStart: async (ctx) => {
+              console.log(`[GADGET] Executing ${ctx.gadgetName}`);
+              if (options.verbose) {
+                console.log(`[GADGET] Parameters:`, JSON.stringify(ctx.parameters, null, 2));
+              }
+            },
+            onGadgetExecutionComplete: async (ctx) => {
+              console.log(`[GADGET] Completed ${ctx.gadgetName}`);
+              if (options.verbose) {
+                const display = ctx.error ?? ctx.finalResult ?? "(no result)";
+                console.log(`[GADGET] Result: ${display}`);
+              }
+            }
+          }
+        };
+      }
+      /**
+       * Measures and logs execution time for LLM calls and gadgets.
+       *
+       * **Output:**
+       * - Duration in milliseconds with ⏱️ emoji for each operation
+       * - Separate timing for each LLM iteration
+       * - Separate timing for each gadget execution
+       *
+       * **Use cases:**
+       * - Performance profiling and optimization
+       * - Identifying slow operations (LLM calls vs gadget execution)
+       * - Monitoring response times in production
+       * - Capacity planning and SLA tracking
+       *
+       * **Performance:** Negligible overhead. Uses Date.now() for timing measurements.
+       *
+       * @returns Hook configuration that can be passed to .withHooks()
+       *
+       * @example
+       * ```typescript
+       * // Basic timing
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.timing())
+       *   .withGadgets(Weather, Database)
+       *   .ask("What's the weather in NYC?");
+       * // Output: ⏱️ LLM call took 1234ms
+       * //         ⏱️ Gadget Weather took 567ms
+       * //         ⏱️ LLM call took 890ms
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Combined with logging for full context
+       * .withHooks(HookPresets.merge(
+       *   HookPresets.logging(),
+       *   HookPresets.timing()
+       * ))
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Correlate performance with cost
+       * .withHooks(HookPresets.merge(
+       *   HookPresets.timing(),
+       *   HookPresets.tokenTracking()
+       * ))
+       * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstiming | Full documentation}
+       */
+      static timing() {
+        const timings = /* @__PURE__ */ new Map();
+        return {
+          observers: {
+            onLLMCallStart: async (ctx) => {
+              timings.set(`llm-${ctx.iteration}`, Date.now());
+            },
+            onLLMCallComplete: async (ctx) => {
+              const start = timings.get(`llm-${ctx.iteration}`);
+              if (start) {
+                const duration = Date.now() - start;
+                console.log(`\u23F1\uFE0F  LLM call took ${duration}ms`);
+                timings.delete(`llm-${ctx.iteration}`);
+              }
+            },
+            onGadgetExecutionStart: async (ctx) => {
+              const key = `gadget-${ctx.gadgetName}-${Date.now()}`;
+              timings.set(key, Date.now());
+              ctx._timingKey = key;
+            },
+            onGadgetExecutionComplete: async (ctx) => {
+              const key = ctx._timingKey;
+              if (key) {
+                const start = timings.get(key);
+                if (start) {
+                  const duration = Date.now() - start;
+                  console.log(`\u23F1\uFE0F  Gadget ${ctx.gadgetName} took ${duration}ms`);
+                  timings.delete(key);
+                }
+              }
+            }
+          }
+        };
+      }
+      /**
+       * Tracks cumulative token usage across all LLM calls.
+       *
+       * **Output:**
+       * - Per-call token count with 📊 emoji
+       * - Cumulative total across all calls
+       * - Call count for average calculations
+       *
+       * **Use cases:**
+       * - Cost monitoring and budget tracking
+       * - Optimizing prompts to reduce token usage
+       * - Comparing token efficiency across different approaches
+       * - Real-time cost estimation
+       *
+       * **Performance:** Minimal overhead. Simple counter increments.
+       *
+       * **Note:** Token counts depend on the provider's response. Some providers
+       * may not include usage data, in which case counts won't be logged.
+       *
+       * @returns Hook configuration that can be passed to .withHooks()
+       *
+       * @example
+       * ```typescript
+       * // Basic token tracking
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.tokenTracking())
+       *   .ask("Summarize this document...");
+       * // Output: 📊 Tokens this call: 1,234
+       * //         📊 Total tokens: 1,234 (across 1 calls)
+       * //         📊 Tokens this call: 567
+       * //         📊 Total tokens: 1,801 (across 2 calls)
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Cost calculation with custom hook
+       * let totalTokens = 0;
+       * .withHooks(HookPresets.merge(
+       *   HookPresets.tokenTracking(),
+       *   {
+       *     observers: {
+       *       onLLMCallComplete: async (ctx) => {
+       *         totalTokens += ctx.usage?.totalTokens ?? 0;
+       *         const cost = (totalTokens / 1_000_000) * 3.0; // $3 per 1M tokens
+       *         console.log(`💰 Estimated cost: $${cost.toFixed(4)}`);
+       *       },
+       *     },
+       *   }
+       * ))
+       * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstokentracking | Full documentation}
+       */
+      static tokenTracking() {
+        let totalTokens = 0;
+        let totalCalls = 0;
+        return {
+          observers: {
+            onLLMCallComplete: async (ctx) => {
+              totalCalls++;
+              if (ctx.usage?.totalTokens) {
+                totalTokens += ctx.usage.totalTokens;
+                console.log(`\u{1F4CA} Tokens this call: ${ctx.usage.totalTokens}`);
+                console.log(`\u{1F4CA} Total tokens: ${totalTokens} (across ${totalCalls} calls)`);
+              }
+            }
+          }
+        };
+      }
+      /**
+       * Tracks comprehensive progress metrics including iterations, tokens, cost, and timing.
+       *
+       * **This preset showcases llmist's core capabilities by demonstrating:**
+       * - Observer pattern for non-intrusive monitoring
+       * - Integration with ModelRegistry for cost estimation
+       * - Callback-based architecture for flexible UI updates
+       * - Provider-agnostic token and cost tracking
+       *
+       * Unlike `tokenTracking()` which only logs to console, this preset provides
+       * structured data through callbacks, making it perfect for building custom UIs,
+       * dashboards, or progress indicators (like the llmist CLI).
+       *
+       * **Output (when logProgress: true):**
+       * - Iteration number and call count
+       * - Cumulative token usage (input + output)
+       * - Cumulative cost in USD (requires modelRegistry)
+       * - Elapsed time in seconds
+       *
+       * **Use cases:**
+       * - Building CLI progress indicators with live updates
+       * - Creating web dashboards with real-time metrics
+       * - Budget monitoring and cost alerts
+       * - Performance tracking and optimization
+       * - Custom logging to external systems (Datadog, CloudWatch, etc.)
+       *
+       * **Performance:** Minimal overhead. Uses Date.now() for timing and optional
+       * ModelRegistry.estimateCost() which is O(1) lookup. Callback invocation is
+       * synchronous and fast.
+       *
+       * @param options - Progress tracking options
+       * @param options.modelRegistry - ModelRegistry for cost estimation (optional)
+       * @param options.onProgress - Callback invoked after each LLM call (optional)
+       * @param options.logProgress - Log progress to console (default: false)
+       * @returns Hook configuration with progress tracking observers
+       *
+       * @example
+       * ```typescript
+       * // Basic usage with callback (RECOMMENDED - used by llmist CLI)
+       * import { LLMist, HookPresets } from 'llmist';
+       *
+       * const client = LLMist.create();
+       *
+       * await client.agent()
+       *   .withHooks(HookPresets.progressTracking({
+       *     modelRegistry: client.modelRegistry,
+       *     onProgress: (stats) => {
+       *       // Update your UI with stats
+       *       console.log(`#${stats.currentIteration} | ${stats.totalTokens} tokens | $${stats.totalCost.toFixed(4)}`);
+       *     }
+       *   }))
+       *   .withGadgets(Calculator)
+       *   .ask("Calculate 15 * 23");
+       * // Output: #1 | 245 tokens | $0.0012
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Console logging mode (quick debugging)
+       * await client.agent()
+       *   .withHooks(HookPresets.progressTracking({
+       *     modelRegistry: client.modelRegistry,
+       *     logProgress: true  // Simple console output
+       *   }))
+       *   .ask("Your prompt");
+       * // Output: 📊 Progress: Iteration #1 | 245 tokens | $0.0012 | 1.2s
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Budget monitoring with alerts
+       * const BUDGET_USD = 0.10;
+       *
+       * await client.agent()
+       *   .withHooks(HookPresets.progressTracking({
+       *     modelRegistry: client.modelRegistry,
+       *     onProgress: (stats) => {
+       *       if (stats.totalCost > BUDGET_USD) {
+       *         throw new Error(`Budget exceeded: $${stats.totalCost.toFixed(4)}`);
+       *       }
+       *     }
+       *   }))
+       *   .ask("Long running task...");
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Web dashboard integration
+       * let progressBar: HTMLElement;
+       *
+       * await client.agent()
+       *   .withHooks(HookPresets.progressTracking({
+       *     modelRegistry: client.modelRegistry,
+       *     onProgress: (stats) => {
+       *       // Update web UI in real-time
+       *       progressBar.textContent = `Iteration ${stats.currentIteration}`;
+       *       progressBar.dataset.cost = stats.totalCost.toFixed(4);
+       *       progressBar.dataset.tokens = stats.totalTokens.toString();
+       *     }
+       *   }))
+       *   .ask("Your prompt");
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // External logging (Datadog, CloudWatch, etc.)
+       * await client.agent()
+       *   .withHooks(HookPresets.progressTracking({
+       *     modelRegistry: client.modelRegistry,
+       *     onProgress: async (stats) => {
+       *       await metrics.gauge('llm.iteration', stats.currentIteration);
+       *       await metrics.gauge('llm.cost', stats.totalCost);
+       *       await metrics.gauge('llm.tokens', stats.totalTokens);
+       *     }
+       *   }))
+       *   .ask("Your prompt");
+       * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsprogresstrackingoptions | Full documentation}
+       * @see {@link ProgressTrackingOptions} for detailed options
+       * @see {@link ProgressStats} for the callback data structure
+       */
+      static progressTracking(options) {
+        const { modelRegistry, onProgress, logProgress = false } = options ?? {};
+        let totalCalls = 0;
+        let currentIteration = 0;
+        let totalInputTokens = 0;
+        let totalOutputTokens = 0;
+        let totalCost = 0;
+        let totalGadgetCost = 0;
+        const startTime = Date.now();
+        return {
+          observers: {
+            // Track iteration on each LLM call start
+            onLLMCallStart: async (ctx) => {
+              currentIteration++;
+            },
+            // Accumulate metrics and report progress on each LLM call completion
+            onLLMCallComplete: async (ctx) => {
+              totalCalls++;
+              if (ctx.usage) {
+                totalInputTokens += ctx.usage.inputTokens;
+                totalOutputTokens += ctx.usage.outputTokens;
+                if (modelRegistry) {
+                  try {
+                    const modelName = ctx.options.model.includes(":") ? ctx.options.model.split(":")[1] : ctx.options.model;
+                    const costEstimate = modelRegistry.estimateCost(
+                      modelName,
+                      ctx.usage.inputTokens,
+                      ctx.usage.outputTokens
+                    );
+                    if (costEstimate) {
+                      totalCost += costEstimate.totalCost;
+                    }
+                  } catch (error) {
+                    if (logProgress) {
+                      console.warn(`\u26A0\uFE0F  Cost estimation failed:`, error);
+                    }
+                  }
+                }
+              }
+              const stats = {
+                currentIteration,
+                totalCalls,
+                totalInputTokens,
+                totalOutputTokens,
+                totalTokens: totalInputTokens + totalOutputTokens,
+                totalCost: totalCost + totalGadgetCost,
+                elapsedSeconds: Number(((Date.now() - startTime) / 1e3).toFixed(1))
+              };
+              if (onProgress) {
+                onProgress(stats);
+              }
+              if (logProgress) {
+                const formattedTokens = stats.totalTokens >= 1e3 ? `${(stats.totalTokens / 1e3).toFixed(1)}k` : `${stats.totalTokens}`;
+                const formattedCost = stats.totalCost > 0 ? `$${stats.totalCost.toFixed(4)}` : "$0";
+                console.log(
+                  `\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;
+              }
+            }
+          }
+        };
+      }
+      /**
+       * Logs detailed error information for debugging and troubleshooting.
+       *
+       * **Output:**
+       * - LLM errors with ❌ emoji, including model and recovery status
+       * - Gadget errors with full context (parameters, error message)
+       * - Separate logging for LLM and gadget failures
+       *
+       * **Use cases:**
+       * - Troubleshooting production issues
+       * - Understanding error patterns and frequency
+       * - Debugging error recovery behavior
+       * - Collecting error metrics for monitoring
+       *
+       * **Performance:** Minimal overhead. Only logs when errors occur.
+       *
+       * @returns Hook configuration that can be passed to .withHooks()
+       *
+       * @example
+       * ```typescript
+       * // Basic error logging
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.errorLogging())
+       *   .withGadgets(Database)
+       *   .ask("Fetch user data");
+       * // Output (on LLM error): ❌ LLM Error (iteration 1): Rate limit exceeded
+       * //                        Model: gpt-5-nano
+       * //                        Recovered: true
+       * // Output (on gadget error): ❌ Gadget Error: Database
+       * //                            Error: Connection timeout
+       * //                            Parameters: {...}
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Combine with monitoring for full context
+       * .withHooks(HookPresets.merge(
+       *   HookPresets.monitoring(),  // Includes errorLogging
+       *   customErrorAnalytics
+       * ))
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Error analytics collection
+       * const errors: any[] = [];
+       * .withHooks(HookPresets.merge(
+       *   HookPresets.errorLogging(),
+       *   {
+       *     observers: {
+       *       onLLMCallError: async (ctx) => {
+       *         errors.push({ type: 'llm', error: ctx.error, recovered: ctx.recovered });
+       *       },
+       *     },
+       *   }
+       * ))
+       * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetserrorlogging | Full documentation}
+       */
+      static errorLogging() {
+        return {
+          observers: {
+            onLLMCallError: async (ctx) => {
+              console.error(`\u274C LLM Error (iteration ${ctx.iteration}):`, ctx.error.message);
+              console.error(`   Model: ${ctx.options.model}`);
+              console.error(`   Recovered: ${ctx.recovered}`);
+            },
+            onGadgetExecutionComplete: async (ctx) => {
+              if (ctx.error) {
+                console.error(`\u274C Gadget Error: ${ctx.gadgetName}`);
+                console.error(`   Error: ${ctx.error}`);
+                console.error(`   Parameters:`, JSON.stringify(ctx.parameters, null, 2));
+              }
+            }
+          }
+        };
+      }
+      /**
+       * Tracks context compaction events.
+       *
+       * **Output:**
+       * - Compaction events with 🗜️ emoji
+       * - Strategy name, tokens before/after, and savings
+       * - Cumulative statistics
+       *
+       * **Use cases:**
+       * - Monitoring long-running conversations
+       * - Understanding when and how compaction occurs
+       * - Debugging context management issues
+       *
+       * **Performance:** Minimal overhead. Simple console output.
+       *
+       * @returns Hook configuration that can be passed to .withHooks()
+       *
+       * @example
+       * ```typescript
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.compactionTracking())
+       *   .ask("Your prompt");
+       * ```
+       */
+      static compactionTracking() {
+        return {
+          observers: {
+            onCompaction: async (ctx) => {
+              const saved = ctx.event.tokensBefore - ctx.event.tokensAfter;
+              const percent = (saved / ctx.event.tokensBefore * 100).toFixed(1);
+              console.log(
+                `\u{1F5DC}\uFE0F  Compaction (${ctx.event.strategy}): ${ctx.event.tokensBefore} \u2192 ${ctx.event.tokensAfter} tokens (saved ${saved}, ${percent}%)`
+              );
+              console.log(`   Messages: ${ctx.event.messagesBefore} \u2192 ${ctx.event.messagesAfter}`);
+              if (ctx.stats.totalCompactions > 1) {
+                console.log(
+                  `   Cumulative: ${ctx.stats.totalCompactions} compactions, ${ctx.stats.totalTokensSaved} tokens saved`
+                );
+              }
+            }
+          }
+        };
+      }
+      /**
+       * Logs LLM requests and responses to files for debugging and audit trails.
+       *
+       * Files are named `{counter}.request` and `{counter}.response` where counter
+       * is a zero-padded number that increments with each LLM call.
+       *
+       * **Output:**
+       * - Request files containing formatted LLM message history
+       * - Response files containing raw LLM output
+       *
+       * **Use cases:**
+       * - Debugging complex agent interactions
+       * - Creating audit trails for compliance
+       * - Analyzing LLM behavior patterns
+       * - Replaying conversations for testing
+       *
+       * **Performance:** Minimal overhead - only file I/O, no synchronous blocking.
+       *
+       * **Note:** Can also be enabled via `LLMIST_LOG_RAW_DIRECTORY` environment
+       * variable for zero-code activation.
+       *
+       * @param options - File logging options
+       * @param options.directory - Directory where log files will be written
+       * @param options.startingCounter - Starting counter (default: 1)
+       * @param options.counterPadding - Number of digits for padding (default: 4)
+       * @param options.skipSubagents - Skip subagent calls (default: true)
+       * @param options.formatRequest - Custom request formatter
+       * @param options.onFileWritten - Callback after each file is written
+       * @returns Hook configuration that can be passed to .withHooks()
+       *
+       * @example
+       * ```typescript
+       * // Basic file logging
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.fileLogging({
+       *     directory: './debug-logs'
+       *   }))
+       *   .ask("Hello");
+       * // Creates: ./debug-logs/0001.request
+       * //          ./debug-logs/0001.response
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // With callback for tracking
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.fileLogging({
+       *     directory: './logs',
+       *     onFileWritten: (info) => {
+       *       console.log(`Wrote ${info.type}: ${info.filePath}`);
+       *     }
+       *   }))
+       *   .ask("Hello");
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Combined with other presets
+       * .withHooks(HookPresets.merge(
+       *   HookPresets.fileLogging({ directory: logDir }),
+       *   HookPresets.progressTracking({ onProgress: updateUI }),
+       *   HookPresets.errorLogging()
+       * ))
+       * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsfileloggingoptions | Full documentation}
+       */
+      static fileLogging(options) {
+        return createFileLoggingHooks(options);
+      }
+      /**
+       * Returns empty hook configuration for clean output without any logging.
+       *
+       * **Output:**
+       * - None. Returns {} (empty object).
+       *
+       * **Use cases:**
+       * - Clean test output without console noise
+       * - Production environments where logging is handled externally
+       * - Baseline for custom hook development
+       * - Temporary disable of all hook output
+       *
+       * **Performance:** Zero overhead. No-op hook configuration.
+       *
+       * @returns Empty hook configuration
+       *
+       * @example
+       * ```typescript
+       * // Clean test output
+       * describe('Agent tests', () => {
+       *   it('should calculate correctly', async () => {
+       *     const result = await LLMist.createAgent()
+       *       .withHooks(HookPresets.silent()) // No console output
+       *       .withGadgets(Calculator)
+       *       .askAndCollect("What is 15 times 23?");
+       *
+       *     expect(result).toContain("345");
+       *   });
+       * });
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Conditional silence based on environment
+       * const isTesting = process.env.NODE_ENV === 'test';
+       * .withHooks(isTesting ? HookPresets.silent() : HookPresets.monitoring())
+       * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetssilent | Full documentation}
+       */
+      static silent() {
+        return {};
+      }
+      /**
+       * Combines multiple hook configurations into one.
+       *
+       * Merge allows you to compose preset and custom hooks for modular monitoring
+       * configurations. Understanding merge behavior is crucial for proper composition.
+       *
+       * **Merge behavior:**
+       * - **Observers:** Composed - all handlers run sequentially in order
+       * - **Interceptors:** Last one wins - only the last interceptor applies
+       * - **Controllers:** Last one wins - only the last controller applies
+       *
+       * **Why interceptors/controllers don't compose:**
+       * - Interceptors have different signatures per method, making composition impractical
+       * - Controllers return specific actions that can't be meaningfully combined
+       * - Only observers support composition because they're read-only and independent
+       *
+       * **Use cases:**
+       * - Combining multiple presets (logging + timing + tokens)
+       * - Adding custom hooks to presets
+       * - Building modular, reusable monitoring configurations
+       * - Environment-specific hook composition
+       *
+       * **Performance:** Minimal overhead for merging. Runtime performance depends on merged hooks.
+       *
+       * @param hookSets - Variable number of hook configurations to merge
+       * @returns Single merged hook configuration with composed/overridden handlers
+       *
+       * @example
+       * ```typescript
+       * // Combine multiple presets
+       * .withHooks(HookPresets.merge(
+       *   HookPresets.logging(),
+       *   HookPresets.timing(),
+       *   HookPresets.tokenTracking()
+       * ))
+       * // All observers from all three presets will run
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Add custom observer to preset (both run)
+       * .withHooks(HookPresets.merge(
+       *   HookPresets.timing(),
+       *   {
+       *     observers: {
+       *       onLLMCallComplete: async (ctx) => {
+       *         await saveMetrics({ tokens: ctx.usage?.totalTokens });
+       *       },
+       *     },
+       *   }
+       * ))
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Multiple interceptors (last wins!)
+       * .withHooks(HookPresets.merge(
+       *   {
+       *     interceptors: {
+       *       interceptTextChunk: (chunk) => chunk.toUpperCase(), // Ignored
+       *     },
+       *   },
+       *   {
+       *     interceptors: {
+       *       interceptTextChunk: (chunk) => chunk.toLowerCase(), // This wins
+       *     },
+       *   }
+       * ))
+       * // Result: text will be lowercase
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Modular environment-based configuration
+       * const baseHooks = HookPresets.errorLogging();
+       * const devHooks = HookPresets.merge(baseHooks, HookPresets.monitoring({ verbose: true }));
+       * const prodHooks = HookPresets.merge(baseHooks, HookPresets.tokenTracking());
+       *
+       * const hooks = process.env.NODE_ENV === 'production' ? prodHooks : devHooks;
+       * .withHooks(hooks)
+       * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsmergehooksets | Full documentation}
+       */
+      static merge(...hookSets) {
+        const merged = {
+          observers: {},
+          interceptors: {},
+          controllers: {}
+        };
+        for (const hooks of hookSets) {
+          if (hooks.observers) {
+            for (const [key, handler] of Object.entries(hooks.observers)) {
+              const typedKey = key;
+              if (merged.observers[typedKey]) {
+                const existing = merged.observers[typedKey];
+                merged.observers[typedKey] = async (ctx) => {
+                  await existing(ctx);
+                  await handler(ctx);
+                };
+              } else {
+                merged.observers[typedKey] = handler;
+              }
+            }
+          }
+          if (hooks.interceptors) {
+            Object.assign(merged.interceptors, hooks.interceptors);
+          }
+          if (hooks.controllers) {
+            Object.assign(merged.controllers, hooks.controllers);
+          }
+        }
+        return merged;
       }
       /**
-       * Registers multiple gadgets at once from an array.
+       * Composite preset combining logging, timing, tokenTracking, and errorLogging.
        *
-       * @param gadgets - Array of gadget instances or classes
-       * @returns This registry for chaining
+       * This is the recommended preset for development and initial production deployments,
+       * providing comprehensive observability with a single method call.
+       *
+       * **Includes:**
+       * - All output from `logging()` preset (with optional verbosity)
+       * - All output from `timing()` preset (execution times)
+       * - All output from `tokenTracking()` preset (token usage)
+       * - All output from `errorLogging()` preset (error details)
+       *
+       * **Output format:**
+       * - Event logging: [LLM]/[GADGET] messages
+       * - Timing: ⏱️ emoji with milliseconds
+       * - Tokens: 📊 emoji with per-call and cumulative counts
+       * - Errors: ❌ emoji with full error details
+       *
+       * **Use cases:**
+       * - Full observability during development
+       * - Comprehensive monitoring in production
+       * - One-liner for complete agent visibility
+       * - Troubleshooting and debugging with full context
+       *
+       * **Performance:** Combined overhead of all four presets, but still minimal in practice.
+       *
+       * @param options - Monitoring options
+       * @param options.verbose - Passed to logging() preset for detailed output. Default: false
+       * @returns Merged hook configuration combining all monitoring presets
        *
        * @example
        * ```typescript
-       * registry.registerMany([Calculator, Weather, Email]);
-       * registry.registerMany([new Calculator(), new Weather()]);
+       * // Basic monitoring (recommended for development)
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.monitoring())
+       *   .withGadgets(Calculator, Weather)
+       *   .ask("What is 15 times 23, and what's the weather in NYC?");
+       * // Output: All events, timing, tokens, and errors in one place
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Verbose monitoring with full details
+       * await LLMist.createAgent()
+       *   .withHooks(HookPresets.monitoring({ verbose: true }))
+       *   .ask("Your prompt");
+       * // Output includes: parameters, results, and complete responses
+       * ```
+       *
+       * @example
+       * ```typescript
+       * // Environment-based monitoring
+       * const isDev = process.env.NODE_ENV === 'development';
+       * .withHooks(HookPresets.monitoring({ verbose: isDev }))
        * ```
+       *
+       * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsmonitoringoptions | Full documentation}
        */
-      registerMany(gadgets) {
-        for (const gadget of gadgets) {
-          const instance = typeof gadget === "function" ? new gadget() : gadget;
-          this.registerByClass(instance);
-        }
-        return this;
-      }
-      // Register a gadget by name
-      register(name, gadget) {
-        const normalizedName = name.toLowerCase();
-        if (this.gadgets.has(normalizedName)) {
-          throw new Error(`Gadget '${name}' is already registered`);
-        }
-        if (gadget.parameterSchema) {
-          validateGadgetSchema(gadget.parameterSchema, name);
-        }
-        this.gadgets.set(normalizedName, gadget);
-      }
-      // Register a gadget using its name property or class name
-      registerByClass(gadget) {
-        const name = gadget.name ?? gadget.constructor.name;
-        this.register(name, gadget);
-      }
-      // Get gadget by name (case-insensitive)
-      get(name) {
-        return this.gadgets.get(name.toLowerCase());
-      }
-      // Check if gadget exists (case-insensitive)
-      has(name) {
-        return this.gadgets.has(name.toLowerCase());
-      }
-      // Get all registered gadget names
-      getNames() {
-        return Array.from(this.gadgets.keys());
-      }
-      // Get all gadgets for instruction generation
-      getAll() {
-        return Array.from(this.gadgets.values());
-      }
-      // Unregister gadget (useful for testing, case-insensitive)
-      unregister(name) {
-        return this.gadgets.delete(name.toLowerCase());
-      }
-      // Clear all gadgets (useful for testing)
-      clear() {
-        this.gadgets.clear();
+      static monitoring(options = {}) {
+        return _HookPresets.merge(
+          _HookPresets.logging(options),
+          _HookPresets.timing(),
+          _HookPresets.tokenTracking(),
+          _HookPresets.errorLogging()
+        );
       }
     };
   }
@@ -9213,6 +10178,8 @@ var init_builder = __esm({
     init_agent();
     init_agent_internal_key();
     init_event_handlers();
+    init_file_logging();
+    init_hook_presets();
     AgentBuilder = class {
       client;
       model;
@@ -10006,9 +10973,16 @@ ${endPrefix}`
        * Note: Subagent event visibility is now handled entirely by the ExecutionTree.
        * When a subagent uses withParentContext(ctx), it shares the parent's tree,
        * and all events are automatically visible to tree subscribers (like the TUI).
+       *
+       * Environment-based file logging (via LLMIST_LOG_RAW_DIRECTORY) is automatically
+       * injected if the env var is set. User-provided hooks take precedence.
        */
       composeHooks() {
-        const hooks = this.hooks;
+        let hooks = this.hooks;
+        const envFileLogging = getEnvFileLoggingHooks();
+        if (envFileLogging) {
+          hooks = hooks ? HookPresets.merge(envFileLogging, hooks) : envFileLogging;
+        }
         if (!this.trailingMessage) {
           return hooks;
         }
@@ -13953,9 +14927,11 @@ __export(index_exports, {
   filterRootEvents: () => filterRootEvents,
   format: () => format,
   formatBytes: () => formatBytes,
+  formatCallNumber: () => formatCallNumber,
   formatDate: () => formatDate,
   formatDuration: () => formatDuration,
   formatLLMError: () => formatLLMError,
+  formatLlmRequest: () => formatLlmRequest,
   gadgetError: () => gadgetError,
   gadgetSuccess: () => gadgetSuccess,
   getErrorMessage: () => getErrorMessage,
@@ -14027,781 +15003,8 @@ var import_zod3 = require("zod");
 init_agent();
 init_builder();
 init_event_handlers();
-
-// src/agent/hook-presets.ts
-var HookPresets = class _HookPresets {
-  /**
-   * Logs LLM calls and gadget execution to console with optional verbosity.
-   *
-   * **Output (basic mode):**
-   * - LLM call start/complete events with iteration numbers
-   * - Gadget execution start/complete with gadget names
-   * - Token counts when available
-   *
-   * **Output (verbose mode):**
-   * - All basic mode output
-   * - Full gadget parameters (formatted JSON)
-   * - Full gadget results
-   * - Complete LLM response text
-   *
-   * **Use cases:**
-   * - Basic development debugging and execution flow visibility
-   * - Understanding agent decision-making and tool usage
-   * - Troubleshooting gadget invocations
-   *
-   * **Performance:** Minimal overhead. Console writes are synchronous but fast.
-   *
-   * @param options - Logging options
-   * @param options.verbose - Include full parameters and results. Default: false
-   * @returns Hook configuration that can be passed to .withHooks()
-   *
-   * @example
-   * ```typescript
-   * // Basic logging
-   * await LLMist.createAgent()
-   *   .withHooks(HookPresets.logging())
-   *   .ask("Calculate 15 * 23");
-   * // Output: [LLM] Starting call (iteration 0)
-   * //         [GADGET] Executing Calculator
-   * //         [GADGET] Completed Calculator
-   * //         [LLM] Completed (tokens: 245)
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Verbose logging with full details
-   * await LLMist.createAgent()
-   *   .withHooks(HookPresets.logging({ verbose: true }))
-   *   .ask("Calculate 15 * 23");
-   * // Output includes: parameters, results, and full responses
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Environment-based verbosity
-   * const isDev = process.env.NODE_ENV === 'development';
-   * .withHooks(HookPresets.logging({ verbose: isDev }))
-   * ```
-   *
-   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsloggingoptions | Full documentation}
-   */
-  static logging(options = {}) {
-    return {
-      observers: {
-        onLLMCallStart: async (ctx) => {
-          console.log(`[LLM] Starting call (iteration ${ctx.iteration})`);
-        },
-        onLLMCallComplete: async (ctx) => {
-          const tokens = ctx.usage?.totalTokens ?? "unknown";
-          console.log(`[LLM] Completed (tokens: ${tokens})`);
-          if (options.verbose && ctx.finalMessage) {
-            console.log(`[LLM] Response: ${ctx.finalMessage}`);
-          }
-        },
-        onGadgetExecutionStart: async (ctx) => {
-          console.log(`[GADGET] Executing ${ctx.gadgetName}`);
-          if (options.verbose) {
-            console.log(`[GADGET] Parameters:`, JSON.stringify(ctx.parameters, null, 2));
-          }
-        },
-        onGadgetExecutionComplete: async (ctx) => {
-          console.log(`[GADGET] Completed ${ctx.gadgetName}`);
-          if (options.verbose) {
-            const display = ctx.error ?? ctx.finalResult ?? "(no result)";
-            console.log(`[GADGET] Result: ${display}`);
-          }
-        }
-      }
-    };
-  }
-  /**
-   * Measures and logs execution time for LLM calls and gadgets.
-   *
-   * **Output:**
-   * - Duration in milliseconds with ⏱️ emoji for each operation
-   * - Separate timing for each LLM iteration
-   * - Separate timing for each gadget execution
-   *
-   * **Use cases:**
-   * - Performance profiling and optimization
-   * - Identifying slow operations (LLM calls vs gadget execution)
-   * - Monitoring response times in production
-   * - Capacity planning and SLA tracking
-   *
-   * **Performance:** Negligible overhead. Uses Date.now() for timing measurements.
-   *
-   * @returns Hook configuration that can be passed to .withHooks()
-   *
-   * @example
-   * ```typescript
-   * // Basic timing
-   * await LLMist.createAgent()
-   *   .withHooks(HookPresets.timing())
-   *   .withGadgets(Weather, Database)
-   *   .ask("What's the weather in NYC?");
-   * // Output: ⏱️ LLM call took 1234ms
-   * //         ⏱️ Gadget Weather took 567ms
-   * //         ⏱️ LLM call took 890ms
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Combined with logging for full context
-   * .withHooks(HookPresets.merge(
-   *   HookPresets.logging(),
-   *   HookPresets.timing()
-   * ))
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Correlate performance with cost
-   * .withHooks(HookPresets.merge(
-   *   HookPresets.timing(),
-   *   HookPresets.tokenTracking()
-   * ))
-   * ```
-   *
-   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstiming | Full documentation}
-   */
-  static timing() {
-    const timings = /* @__PURE__ */ new Map();
-    return {
-      observers: {
-        onLLMCallStart: async (ctx) => {
-          timings.set(`llm-${ctx.iteration}`, Date.now());
-        },
-        onLLMCallComplete: async (ctx) => {
-          const start = timings.get(`llm-${ctx.iteration}`);
-          if (start) {
-            const duration = Date.now() - start;
-            console.log(`\u23F1\uFE0F  LLM call took ${duration}ms`);
-            timings.delete(`llm-${ctx.iteration}`);
-          }
-        },
-        onGadgetExecutionStart: async (ctx) => {
-          const key = `gadget-${ctx.gadgetName}-${Date.now()}`;
-          timings.set(key, Date.now());
-          ctx._timingKey = key;
-        },
-        onGadgetExecutionComplete: async (ctx) => {
-          const key = ctx._timingKey;
-          if (key) {
-            const start = timings.get(key);
-            if (start) {
-              const duration = Date.now() - start;
-              console.log(`\u23F1\uFE0F  Gadget ${ctx.gadgetName} took ${duration}ms`);
-              timings.delete(key);
-            }
-          }
-        }
-      }
-    };
-  }
-  /**
-   * Tracks cumulative token usage across all LLM calls.
-   *
-   * **Output:**
-   * - Per-call token count with 📊 emoji
-   * - Cumulative total across all calls
-   * - Call count for average calculations
-   *
-   * **Use cases:**
-   * - Cost monitoring and budget tracking
-   * - Optimizing prompts to reduce token usage
-   * - Comparing token efficiency across different approaches
-   * - Real-time cost estimation
-   *
-   * **Performance:** Minimal overhead. Simple counter increments.
-   *
-   * **Note:** Token counts depend on the provider's response. Some providers
-   * may not include usage data, in which case counts won't be logged.
-   *
-   * @returns Hook configuration that can be passed to .withHooks()
-   *
-   * @example
-   * ```typescript
-   * // Basic token tracking
-   * await LLMist.createAgent()
-   *   .withHooks(HookPresets.tokenTracking())
-   *   .ask("Summarize this document...");
-   * // Output: 📊 Tokens this call: 1,234
-   * //         📊 Total tokens: 1,234 (across 1 calls)
-   * //         📊 Tokens this call: 567
-   * //         📊 Total tokens: 1,801 (across 2 calls)
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Cost calculation with custom hook
-   * let totalTokens = 0;
-   * .withHooks(HookPresets.merge(
-   *   HookPresets.tokenTracking(),
-   *   {
-   *     observers: {
-   *       onLLMCallComplete: async (ctx) => {
-   *         totalTokens += ctx.usage?.totalTokens ?? 0;
-   *         const cost = (totalTokens / 1_000_000) * 3.0; // $3 per 1M tokens
-   *         console.log(`💰 Estimated cost: $${cost.toFixed(4)}`);
-   *       },
-   *     },
-   *   }
-   * ))
-   * ```
-   *
-   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstokentracking | Full documentation}
-   */
-  static tokenTracking() {
-    let totalTokens = 0;
-    let totalCalls = 0;
-    return {
-      observers: {
-        onLLMCallComplete: async (ctx) => {
-          totalCalls++;
-          if (ctx.usage?.totalTokens) {
-            totalTokens += ctx.usage.totalTokens;
-            console.log(`\u{1F4CA} Tokens this call: ${ctx.usage.totalTokens}`);
-            console.log(`\u{1F4CA} Total tokens: ${totalTokens} (across ${totalCalls} calls)`);
-          }
-        }
-      }
-    };
-  }
-  /**
-   * Tracks comprehensive progress metrics including iterations, tokens, cost, and timing.
-   *
-   * **This preset showcases llmist's core capabilities by demonstrating:**
-   * - Observer pattern for non-intrusive monitoring
-   * - Integration with ModelRegistry for cost estimation
-   * - Callback-based architecture for flexible UI updates
-   * - Provider-agnostic token and cost tracking
-   *
-   * Unlike `tokenTracking()` which only logs to console, this preset provides
-   * structured data through callbacks, making it perfect for building custom UIs,
-   * dashboards, or progress indicators (like the llmist CLI).
-   *
-   * **Output (when logProgress: true):**
-   * - Iteration number and call count
-   * - Cumulative token usage (input + output)
-   * - Cumulative cost in USD (requires modelRegistry)
-   * - Elapsed time in seconds
-   *
-   * **Use cases:**
-   * - Building CLI progress indicators with live updates
-   * - Creating web dashboards with real-time metrics
-   * - Budget monitoring and cost alerts
-   * - Performance tracking and optimization
-   * - Custom logging to external systems (Datadog, CloudWatch, etc.)
-   *
-   * **Performance:** Minimal overhead. Uses Date.now() for timing and optional
-   * ModelRegistry.estimateCost() which is O(1) lookup. Callback invocation is
-   * synchronous and fast.
-   *
-   * @param options - Progress tracking options
-   * @param options.modelRegistry - ModelRegistry for cost estimation (optional)
-   * @param options.onProgress - Callback invoked after each LLM call (optional)
-   * @param options.logProgress - Log progress to console (default: false)
-   * @returns Hook configuration with progress tracking observers
-   *
-   * @example
-   * ```typescript
-   * // Basic usage with callback (RECOMMENDED - used by llmist CLI)
-   * import { LLMist, HookPresets } from 'llmist';
-   *
-   * const client = LLMist.create();
-   *
-   * await client.agent()
-   *   .withHooks(HookPresets.progressTracking({
-   *     modelRegistry: client.modelRegistry,
-   *     onProgress: (stats) => {
-   *       // Update your UI with stats
-   *       console.log(`#${stats.currentIteration} | ${stats.totalTokens} tokens | $${stats.totalCost.toFixed(4)}`);
-   *     }
-   *   }))
-   *   .withGadgets(Calculator)
-   *   .ask("Calculate 15 * 23");
-   * // Output: #1 | 245 tokens | $0.0012
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Console logging mode (quick debugging)
-   * await client.agent()
-   *   .withHooks(HookPresets.progressTracking({
-   *     modelRegistry: client.modelRegistry,
-   *     logProgress: true  // Simple console output
-   *   }))
-   *   .ask("Your prompt");
-   * // Output: 📊 Progress: Iteration #1 | 245 tokens | $0.0012 | 1.2s
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Budget monitoring with alerts
-   * const BUDGET_USD = 0.10;
-   *
-   * await client.agent()
-   *   .withHooks(HookPresets.progressTracking({
-   *     modelRegistry: client.modelRegistry,
-   *     onProgress: (stats) => {
-   *       if (stats.totalCost > BUDGET_USD) {
-   *         throw new Error(`Budget exceeded: $${stats.totalCost.toFixed(4)}`);
-   *       }
-   *     }
-   *   }))
-   *   .ask("Long running task...");
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Web dashboard integration
-   * let progressBar: HTMLElement;
-   *
-   * await client.agent()
-   *   .withHooks(HookPresets.progressTracking({
-   *     modelRegistry: client.modelRegistry,
-   *     onProgress: (stats) => {
-   *       // Update web UI in real-time
-   *       progressBar.textContent = `Iteration ${stats.currentIteration}`;
-   *       progressBar.dataset.cost = stats.totalCost.toFixed(4);
-   *       progressBar.dataset.tokens = stats.totalTokens.toString();
-   *     }
-   *   }))
-   *   .ask("Your prompt");
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // External logging (Datadog, CloudWatch, etc.)
-   * await client.agent()
-   *   .withHooks(HookPresets.progressTracking({
-   *     modelRegistry: client.modelRegistry,
-   *     onProgress: async (stats) => {
-   *       await metrics.gauge('llm.iteration', stats.currentIteration);
-   *       await metrics.gauge('llm.cost', stats.totalCost);
-   *       await metrics.gauge('llm.tokens', stats.totalTokens);
-   *     }
-   *   }))
-   *   .ask("Your prompt");
-   * ```
-   *
-   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsprogresstrackingoptions | Full documentation}
-   * @see {@link ProgressTrackingOptions} for detailed options
-   * @see {@link ProgressStats} for the callback data structure
-   */
-  static progressTracking(options) {
-    const { modelRegistry, onProgress, logProgress = false } = options ?? {};
-    let totalCalls = 0;
-    let currentIteration = 0;
-    let totalInputTokens = 0;
-    let totalOutputTokens = 0;
-    let totalCost = 0;
-    let totalGadgetCost = 0;
-    const startTime = Date.now();
-    return {
-      observers: {
-        // Track iteration on each LLM call start
-        onLLMCallStart: async (ctx) => {
-          currentIteration++;
-        },
-        // Accumulate metrics and report progress on each LLM call completion
-        onLLMCallComplete: async (ctx) => {
-          totalCalls++;
-          if (ctx.usage) {
-            totalInputTokens += ctx.usage.inputTokens;
-            totalOutputTokens += ctx.usage.outputTokens;
-            if (modelRegistry) {
-              try {
-                const modelName = ctx.options.model.includes(":") ? ctx.options.model.split(":")[1] : ctx.options.model;
-                const costEstimate = modelRegistry.estimateCost(
-                  modelName,
-                  ctx.usage.inputTokens,
-                  ctx.usage.outputTokens
-                );
-                if (costEstimate) {
-                  totalCost += costEstimate.totalCost;
-                }
-              } catch (error) {
-                if (logProgress) {
-                  console.warn(`\u26A0\uFE0F  Cost estimation failed:`, error);
-                }
-              }
-            }
-          }
-          const stats = {
-            currentIteration,
-            totalCalls,
-            totalInputTokens,
-            totalOutputTokens,
-            totalTokens: totalInputTokens + totalOutputTokens,
-            totalCost: totalCost + totalGadgetCost,
-            elapsedSeconds: Number(((Date.now() - startTime) / 1e3).toFixed(1))
-          };
-          if (onProgress) {
-            onProgress(stats);
-          }
-          if (logProgress) {
-            const formattedTokens = stats.totalTokens >= 1e3 ? `${(stats.totalTokens / 1e3).toFixed(1)}k` : `${stats.totalTokens}`;
-            const formattedCost = stats.totalCost > 0 ? `$${stats.totalCost.toFixed(4)}` : "$0";
-            console.log(
-              `\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;
-          }
-        }
-      }
-    };
-  }
-  /**
-   * Logs detailed error information for debugging and troubleshooting.
-   *
-   * **Output:**
-   * - LLM errors with ❌ emoji, including model and recovery status
-   * - Gadget errors with full context (parameters, error message)
-   * - Separate logging for LLM and gadget failures
-   *
-   * **Use cases:**
-   * - Troubleshooting production issues
-   * - Understanding error patterns and frequency
-   * - Debugging error recovery behavior
-   * - Collecting error metrics for monitoring
-   *
-   * **Performance:** Minimal overhead. Only logs when errors occur.
-   *
-   * @returns Hook configuration that can be passed to .withHooks()
-   *
-   * @example
-   * ```typescript
-   * // Basic error logging
-   * await LLMist.createAgent()
-   *   .withHooks(HookPresets.errorLogging())
-   *   .withGadgets(Database)
-   *   .ask("Fetch user data");
-   * // Output (on LLM error): ❌ LLM Error (iteration 1): Rate limit exceeded
-   * //                        Model: gpt-5-nano
-   * //                        Recovered: true
-   * // Output (on gadget error): ❌ Gadget Error: Database
-   * //                            Error: Connection timeout
-   * //                            Parameters: {...}
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Combine with monitoring for full context
-   * .withHooks(HookPresets.merge(
-   *   HookPresets.monitoring(),  // Includes errorLogging
-   *   customErrorAnalytics
-   * ))
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Error analytics collection
-   * const errors: any[] = [];
-   * .withHooks(HookPresets.merge(
-   *   HookPresets.errorLogging(),
-   *   {
-   *     observers: {
-   *       onLLMCallError: async (ctx) => {
-   *         errors.push({ type: 'llm', error: ctx.error, recovered: ctx.recovered });
-   *       },
-   *     },
-   *   }
-   * ))
-   * ```
-   *
-   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetserrorlogging | Full documentation}
-   */
-  static errorLogging() {
-    return {
-      observers: {
-        onLLMCallError: async (ctx) => {
-          console.error(`\u274C LLM Error (iteration ${ctx.iteration}):`, ctx.error.message);
-          console.error(`   Model: ${ctx.options.model}`);
-          console.error(`   Recovered: ${ctx.recovered}`);
-        },
-        onGadgetExecutionComplete: async (ctx) => {
-          if (ctx.error) {
-            console.error(`\u274C Gadget Error: ${ctx.gadgetName}`);
-            console.error(`   Error: ${ctx.error}`);
-            console.error(`   Parameters:`, JSON.stringify(ctx.parameters, null, 2));
-          }
-        }
-      }
-    };
-  }
-  /**
-   * Tracks context compaction events.
-   *
-   * **Output:**
-   * - Compaction events with 🗜️ emoji
-   * - Strategy name, tokens before/after, and savings
-   * - Cumulative statistics
-   *
-   * **Use cases:**
-   * - Monitoring long-running conversations
-   * - Understanding when and how compaction occurs
-   * - Debugging context management issues
-   *
-   * **Performance:** Minimal overhead. Simple console output.
-   *
-   * @returns Hook configuration that can be passed to .withHooks()
-   *
-   * @example
-   * ```typescript
-   * await LLMist.createAgent()
-   *   .withHooks(HookPresets.compactionTracking())
-   *   .ask("Your prompt");
-   * ```
-   */
-  static compactionTracking() {
-    return {
-      observers: {
-        onCompaction: async (ctx) => {
-          const saved = ctx.event.tokensBefore - ctx.event.tokensAfter;
-          const percent = (saved / ctx.event.tokensBefore * 100).toFixed(1);
-          console.log(
-            `\u{1F5DC}\uFE0F  Compaction (${ctx.event.strategy}): ${ctx.event.tokensBefore} \u2192 ${ctx.event.tokensAfter} tokens (saved ${saved}, ${percent}%)`
-          );
-          console.log(`   Messages: ${ctx.event.messagesBefore} \u2192 ${ctx.event.messagesAfter}`);
-          if (ctx.stats.totalCompactions > 1) {
-            console.log(
-              `   Cumulative: ${ctx.stats.totalCompactions} compactions, ${ctx.stats.totalTokensSaved} tokens saved`
-            );
-          }
-        }
-      }
-    };
-  }
-  /**
-   * Returns empty hook configuration for clean output without any logging.
-   *
-   * **Output:**
-   * - None. Returns {} (empty object).
-   *
-   * **Use cases:**
-   * - Clean test output without console noise
-   * - Production environments where logging is handled externally
-   * - Baseline for custom hook development
-   * - Temporary disable of all hook output
-   *
-   * **Performance:** Zero overhead. No-op hook configuration.
-   *
-   * @returns Empty hook configuration
-   *
-   * @example
-   * ```typescript
-   * // Clean test output
-   * describe('Agent tests', () => {
-   *   it('should calculate correctly', async () => {
-   *     const result = await LLMist.createAgent()
-   *       .withHooks(HookPresets.silent()) // No console output
-   *       .withGadgets(Calculator)
-   *       .askAndCollect("What is 15 times 23?");
-   *
-   *     expect(result).toContain("345");
-   *   });
-   * });
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Conditional silence based on environment
-   * const isTesting = process.env.NODE_ENV === 'test';
-   * .withHooks(isTesting ? HookPresets.silent() : HookPresets.monitoring())
-   * ```
-   *
-   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetssilent | Full documentation}
-   */
-  static silent() {
-    return {};
-  }
-  /**
-   * Combines multiple hook configurations into one.
-   *
-   * Merge allows you to compose preset and custom hooks for modular monitoring
-   * configurations. Understanding merge behavior is crucial for proper composition.
-   *
-   * **Merge behavior:**
-   * - **Observers:** Composed - all handlers run sequentially in order
-   * - **Interceptors:** Last one wins - only the last interceptor applies
-   * - **Controllers:** Last one wins - only the last controller applies
-   *
-   * **Why interceptors/controllers don't compose:**
-   * - Interceptors have different signatures per method, making composition impractical
-   * - Controllers return specific actions that can't be meaningfully combined
-   * - Only observers support composition because they're read-only and independent
-   *
-   * **Use cases:**
-   * - Combining multiple presets (logging + timing + tokens)
-   * - Adding custom hooks to presets
-   * - Building modular, reusable monitoring configurations
-   * - Environment-specific hook composition
-   *
-   * **Performance:** Minimal overhead for merging. Runtime performance depends on merged hooks.
-   *
-   * @param hookSets - Variable number of hook configurations to merge
-   * @returns Single merged hook configuration with composed/overridden handlers
-   *
-   * @example
-   * ```typescript
-   * // Combine multiple presets
-   * .withHooks(HookPresets.merge(
-   *   HookPresets.logging(),
-   *   HookPresets.timing(),
-   *   HookPresets.tokenTracking()
-   * ))
-   * // All observers from all three presets will run
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Add custom observer to preset (both run)
-   * .withHooks(HookPresets.merge(
-   *   HookPresets.timing(),
-   *   {
-   *     observers: {
-   *       onLLMCallComplete: async (ctx) => {
-   *         await saveMetrics({ tokens: ctx.usage?.totalTokens });
-   *       },
-   *     },
-   *   }
-   * ))
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Multiple interceptors (last wins!)
-   * .withHooks(HookPresets.merge(
-   *   {
-   *     interceptors: {
-   *       interceptTextChunk: (chunk) => chunk.toUpperCase(), // Ignored
-   *     },
-   *   },
-   *   {
-   *     interceptors: {
-   *       interceptTextChunk: (chunk) => chunk.toLowerCase(), // This wins
-   *     },
-   *   }
-   * ))
-   * // Result: text will be lowercase
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Modular environment-based configuration
-   * const baseHooks = HookPresets.errorLogging();
-   * const devHooks = HookPresets.merge(baseHooks, HookPresets.monitoring({ verbose: true }));
-   * const prodHooks = HookPresets.merge(baseHooks, HookPresets.tokenTracking());
-   *
-   * const hooks = process.env.NODE_ENV === 'production' ? prodHooks : devHooks;
-   * .withHooks(hooks)
-   * ```
-   *
-   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsmergehooksets | Full documentation}
-   */
-  static merge(...hookSets) {
-    const merged = {
-      observers: {},
-      interceptors: {},
-      controllers: {}
-    };
-    for (const hooks of hookSets) {
-      if (hooks.observers) {
-        for (const [key, handler] of Object.entries(hooks.observers)) {
-          const typedKey = key;
-          if (merged.observers[typedKey]) {
-            const existing = merged.observers[typedKey];
-            merged.observers[typedKey] = async (ctx) => {
-              await existing(ctx);
-              await handler(ctx);
-            };
-          } else {
-            merged.observers[typedKey] = handler;
-          }
-        }
-      }
-      if (hooks.interceptors) {
-        Object.assign(merged.interceptors, hooks.interceptors);
-      }
-      if (hooks.controllers) {
-        Object.assign(merged.controllers, hooks.controllers);
-      }
-    }
-    return merged;
-  }
-  /**
-   * Composite preset combining logging, timing, tokenTracking, and errorLogging.
-   *
-   * This is the recommended preset for development and initial production deployments,
-   * providing comprehensive observability with a single method call.
-   *
-   * **Includes:**
-   * - All output from `logging()` preset (with optional verbosity)
-   * - All output from `timing()` preset (execution times)
-   * - All output from `tokenTracking()` preset (token usage)
-   * - All output from `errorLogging()` preset (error details)
-   *
-   * **Output format:**
-   * - Event logging: [LLM]/[GADGET] messages
-   * - Timing: ⏱️ emoji with milliseconds
-   * - Tokens: 📊 emoji with per-call and cumulative counts
-   * - Errors: ❌ emoji with full error details
-   *
-   * **Use cases:**
-   * - Full observability during development
-   * - Comprehensive monitoring in production
-   * - One-liner for complete agent visibility
-   * - Troubleshooting and debugging with full context
-   *
-   * **Performance:** Combined overhead of all four presets, but still minimal in practice.
-   *
-   * @param options - Monitoring options
-   * @param options.verbose - Passed to logging() preset for detailed output. Default: false
-   * @returns Merged hook configuration combining all monitoring presets
-   *
-   * @example
-   * ```typescript
-   * // Basic monitoring (recommended for development)
-   * await LLMist.createAgent()
-   *   .withHooks(HookPresets.monitoring())
-   *   .withGadgets(Calculator, Weather)
-   *   .ask("What is 15 times 23, and what's the weather in NYC?");
-   * // Output: All events, timing, tokens, and errors in one place
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Verbose monitoring with full details
-   * await LLMist.createAgent()
-   *   .withHooks(HookPresets.monitoring({ verbose: true }))
-   *   .ask("Your prompt");
-   * // Output includes: parameters, results, and complete responses
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Environment-based monitoring
-   * const isDev = process.env.NODE_ENV === 'development';
-   * .withHooks(HookPresets.monitoring({ verbose: isDev }))
-   * ```
-   *
-   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsmonitoringoptions | Full documentation}
-   */
-  static monitoring(options = {}) {
-    return _HookPresets.merge(
-      _HookPresets.logging(options),
-      _HookPresets.timing(),
-      _HookPresets.tokenTracking(),
-      _HookPresets.errorLogging()
-    );
-  }
-};
+init_file_logging();
+init_hook_presets();
 
 // src/agent/compaction/index.ts
 init_config();
@@ -14814,6 +15017,7 @@ init_gadget_output_store();
 
 // src/agent/hints.ts
 init_prompt_config();
+init_hook_presets();
 function iterationProgressHint(options) {
   const { timing: timing2 = "always", showUrgency = true, template } = options ?? {};
   return {
@@ -15603,9 +15807,11 @@ function getHostExports2(ctx) {
   filterRootEvents,
   format,
   formatBytes,
+  formatCallNumber,
   formatDate,
   formatDuration,
   formatLLMError,
+  formatLlmRequest,
   gadgetError,
   gadgetSuccess,
   getErrorMessage,