llmist 15.11.0 → 15.13.0

package/dist/index.cjs

@@ -229,7 +229,8 @@ var init_execution_tree = __esm({
           response: llmNode.response,
           usage: llmNode.usage,
           finishReason: llmNode.finishReason,
-          cost: llmNode.cost
+          cost: llmNode.cost,
+          thinkingContent: params.thinkingContent
         });
       }
       /**
@@ -4039,6 +4040,958 @@ var init_registry = __esm({
   }
 });
 
+// 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,
+                      ctx.usage.cachedInputTokens ?? 0,
+                      ctx.usage.cacheCreationInputTokens ?? 0,
+                      ctx.usage.reasoningTokens ?? 0
+                    );
+                    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;
+      }
+      /**
+       * 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()
+        );
+      }
+    };
+  }
+});
+
 // src/providers/anthropic-models.ts
 var ANTHROPIC_MODELS;
 var init_anthropic_models = __esm({
@@ -4077,10 +5030,10 @@ var init_anthropic_models = __esm({
         contextWindow: 2e5,
         maxOutputTokens: 64e3,
         pricing: {
-          input: 0.8,
-          output: 4,
-          cachedInput: 0.08,
-          cacheWriteInput: 1
+          input: 1,
+          output: 5,
+          cachedInput: 0.1,
+          cacheWriteInput: 1.25
         },
         knowledgeCutoff: "2025-02",
         features: {
@@ -4276,10 +5229,10 @@ var init_anthropic_models = __esm({
         contextWindow: 2e5,
         maxOutputTokens: 64e3,
         pricing: {
-          input: 0.8,
-          output: 4,
-          cachedInput: 0.08,
-          cacheWriteInput: 1
+          input: 1,
+          output: 5,
+          cachedInput: 0.1,
+          cacheWriteInput: 1.25
         },
         knowledgeCutoff: "2025-02",
         features: {
@@ -4422,10 +5375,15 @@ var init_utils = __esm({
 });
 
 // src/providers/anthropic.ts
+function resolveAnthropicThinking(reasoning) {
+  if (!reasoning?.enabled) return void 0;
+  const budget = reasoning.budgetTokens ? Math.max(1024, reasoning.budgetTokens) : ANTHROPIC_EFFORT_BUDGET[reasoning.effort ?? "medium"];
+  return { type: "enabled", budget_tokens: budget };
+}
 function createAnthropicProviderFromEnv() {
   return createProviderFromEnv("ANTHROPIC_API_KEY", import_sdk.default, AnthropicMessagesProvider);
 }
-var import_sdk, AnthropicMessagesProvider;
+var import_sdk, ANTHROPIC_EFFORT_BUDGET, AnthropicMessagesProvider;
 var init_anthropic = __esm({
   "src/providers/anthropic.ts"() {
     "use strict";
@@ -4435,6 +5393,14 @@ var init_anthropic = __esm({
     init_base_provider();
     init_constants2();
     init_utils();
+    ANTHROPIC_EFFORT_BUDGET = {
+      none: 1024,
+      // Minimum allowed by Anthropic
+      low: 2048,
+      medium: 8192,
+      high: 16384,
+      maximum: 32768
+    };
     AnthropicMessagesProvider = class extends BaseProviderAdapter {
       providerId = "anthropic";
       supports(descriptor) {
@@ -4488,15 +5454,18 @@ var init_anthropic = __esm({
           )
         }));
         const defaultMaxTokens = spec?.maxOutputTokens ?? ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS;
+        const thinking = resolveAnthropicThinking(options.reasoning);
+        const temperature = thinking ? void 0 : options.temperature;
         const payload = {
           model: descriptor.name,
           system,
           messages: conversation,
           max_tokens: options.maxTokens ?? defaultMaxTokens,
-          temperature: options.temperature,
+          temperature,
           top_p: options.topP,
           stop_sequences: options.stopSequences,
           stream: true,
+          ...thinking ? { thinking } : {},
           ...options.extra
         };
         return payload;
@@ -4576,8 +5545,39 @@ var init_anthropic = __esm({
             };
             continue;
           }
-          if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
-            yield { text: event.delta.text ?? "", rawEvent: event };
+          if (event.type === "content_block_start") {
+            const block = event.content_block;
+            if (block.type === "thinking") {
+              yield { text: "", thinking: { content: "", type: "thinking" }, rawEvent: event };
+              continue;
+            }
+            if (block.type === "redacted_thinking") {
+              yield { text: "", thinking: { content: "", type: "redacted" }, rawEvent: event };
+              continue;
+            }
+          }
+          if (event.type === "content_block_delta") {
+            const delta = event.delta;
+            if (delta.type === "thinking_delta" && delta.thinking) {
+              yield {
+                text: "",
+                thinking: { content: delta.thinking, type: "thinking" },
+                rawEvent: event
+              };
+              continue;
+            }
+            if (delta.type === "signature_delta" && delta.signature) {
+              yield {
+                text: "",
+                thinking: { content: "", type: "thinking", signature: delta.signature },
+                rawEvent: event
+              };
+              continue;
+            }
+            if (delta.type === "text_delta") {
+              yield { text: delta.text ?? "", rawEvent: event };
+              continue;
+            }
             continue;
           }
           if (event.type === "message_delta") {
@@ -4886,10 +5886,10 @@ var init_gemini_models = __esm({
         contextWindow: 1048576,
         maxOutputTokens: 65536,
         pricing: {
-          input: 0.4,
-          // $0.40 for text/image/video
+          input: 0.5,
+          // $0.50 for text/image/video
           output: 3,
-          cachedInput: 0.04
+          cachedInput: 0.05
         },
         knowledgeCutoff: "2025-01",
         features: {
@@ -5183,6 +6183,23 @@ var init_gemini_speech_models = __esm({
 });
 
 // src/providers/gemini.ts
+function resolveGeminiThinkingConfig(reasoning, modelName) {
+  if (!reasoning?.enabled) return void 0;
+  const isGemini3 = modelName.includes("gemini-3");
+  if (isGemini3) {
+    return {
+      thinkingConfig: {
+        thinkingLevel: GEMINI3_THINKING_LEVEL[reasoning.effort ?? "medium"]
+      }
+    };
+  }
+  const budget = reasoning.budgetTokens ?? GEMINI25_THINKING_BUDGET[reasoning.effort ?? "medium"];
+  return {
+    thinkingConfig: {
+      thinkingBudget: budget
+    }
+  };
+}
 function wrapPcmInWav(pcmData, sampleRate, bitsPerSample, numChannels) {
   const byteRate = sampleRate * numChannels * bitsPerSample / 8;
   const blockAlign = numChannels * bitsPerSample / 8;
@@ -5211,7 +6228,7 @@ function wrapPcmInWav(pcmData, sampleRate, bitsPerSample, numChannels) {
 function createGeminiProviderFromEnv() {
   return createProviderFromEnv("GEMINI_API_KEY", import_genai.GoogleGenAI, GeminiGenerativeProvider);
 }
-var import_genai, GEMINI_ROLE_MAP, GeminiGenerativeProvider;
+var import_genai, GEMINI3_THINKING_LEVEL, GEMINI25_THINKING_BUDGET, GEMINI_ROLE_MAP, GeminiGenerativeProvider;
 var init_gemini = __esm({
   "src/providers/gemini.ts"() {
     "use strict";
@@ -5223,6 +6240,20 @@ var init_gemini = __esm({
     init_gemini_models();
     init_gemini_speech_models();
     init_utils();
+    GEMINI3_THINKING_LEVEL = {
+      none: "minimal",
+      low: "low",
+      medium: "medium",
+      high: "high",
+      maximum: "high"
+    };
+    GEMINI25_THINKING_BUDGET = {
+      none: 0,
+      low: 2048,
+      medium: 8192,
+      high: 16384,
+      maximum: 24576
+    };
     GEMINI_ROLE_MAP = {
       system: "user",
       user: "user",
@@ -5372,6 +6403,7 @@ var init_gemini = __esm({
       buildApiRequest(options, descriptor, _spec, messages) {
         const contents = this.convertMessagesToContents(messages);
         const generationConfig = this.buildGenerationConfig(options);
+        const thinkingConfig = resolveGeminiThinkingConfig(options.reasoning, descriptor.name);
         const config = {
           // Note: systemInstruction removed - it doesn't work with countTokens()
           // System messages are now included in contents as user+model exchanges
@@ -5382,6 +6414,7 @@ var init_gemini = __esm({
               mode: import_genai.FunctionCallingConfigMode.NONE
             }
           },
+          ...thinkingConfig ?? {},
           ...options.extra
         };
         return {
@@ -5519,7 +6552,18 @@ var init_gemini = __esm({
       async *normalizeProviderStream(iterable) {
         const stream2 = iterable;
         for await (const chunk of stream2) {
-          const text3 = this.extractMessageText(chunk);
+          const { text: text3, thinkingText, thinkingSignature } = this.extractTextAndThinking(chunk);
+          if (thinkingText) {
+            yield {
+              text: "",
+              thinking: {
+                content: thinkingText,
+                type: "thinking",
+                signature: thinkingSignature
+              },
+              rawEvent: chunk
+            };
+          }
           if (text3) {
             yield { text: text3, rawEvent: chunk };
           }
@@ -5530,11 +6574,30 @@ var init_gemini = __esm({
           }
         }
       }
-      extractMessageText(chunk) {
+      /**
+       * Extract both regular text and thinking text from a chunk.
+       * Gemini marks thinking parts with `thought: true`.
+       */
+      extractTextAndThinking(chunk) {
         if (!chunk?.candidates) {
-          return "";
+          return { text: "", thinkingText: "" };
+        }
+        let text3 = "";
+        let thinkingText = "";
+        let thinkingSignature;
+        for (const candidate of chunk.candidates) {
+          for (const part of candidate.content?.parts ?? []) {
+            if (part.thought) {
+              thinkingText += part.text ?? "";
+              if (part.thoughtSignature) {
+                thinkingSignature = part.thoughtSignature;
+              }
+            } else {
+              text3 += part.text ?? "";
+            }
+          }
         }
-        return chunk.candidates.flatMap((candidate) => candidate.content?.parts ?? []).map((part) => part.text ?? "").join("");
+        return { text: text3, thinkingText, thinkingSignature };
       }
       extractFinishReason(chunk) {
         const candidate = chunk?.candidates?.find((item) => item.finishReason);
@@ -5550,7 +6613,9 @@ var init_gemini = __esm({
           outputTokens: usageMetadata.candidatesTokenCount ?? 0,
           totalTokens: usageMetadata.totalTokenCount ?? 0,
           // Gemini returns cached token count in cachedContentTokenCount
-          cachedInputTokens: usageMetadata.cachedContentTokenCount ?? 0
+          cachedInputTokens: usageMetadata.cachedContentTokenCount ?? 0,
+          // Gemini returns thinking tokens in thoughtsTokenCount
+          reasoningTokens: usageMetadata.thoughtsTokenCount
         };
       }
       /**
@@ -6571,11 +7636,13 @@ var init_openai_compatible_provider = __esm({
             yield { text: text3, rawEvent: chunk };
           }
           const finishReason = chunk.choices.find((choice) => choice.finish_reason)?.finish_reason;
+          const usageDetails = chunk.usage;
           const usage = chunk.usage ? {
             inputTokens: chunk.usage.prompt_tokens,
             outputTokens: chunk.usage.completion_tokens,
             totalTokens: chunk.usage.total_tokens,
-            cachedInputTokens: 0
+            cachedInputTokens: 0,
+            reasoningTokens: usageDetails?.completion_tokens_details?.reasoning_tokens
           } : void 0;
           if (finishReason || usage) {
             yield { text: "", finishReason, usage, rawEvent: chunk };
@@ -6651,6 +7718,21 @@ var init_huggingface = __esm({
       getModelSpecs() {
         return HUGGINGFACE_MODELS;
       }
+      /**
+       * Override buildApiRequest to inject DeepSeek-specific thinking parameters.
+       * DeepSeek models use `extra_body: { thinking: { type: "enabled" } }` for reasoning.
+       */
+      buildApiRequest(options, descriptor, spec, messages) {
+        const request = super.buildApiRequest(options, descriptor, spec, messages);
+        if (options.reasoning?.enabled && descriptor.name.toLowerCase().includes("deepseek")) {
+          const requestObj = request;
+          requestObj.extra_body = {
+            ...requestObj.extra_body,
+            thinking: { type: "enabled" }
+          };
+        }
+        return request;
+      }
       /**
        * Enhance error messages with HuggingFace-specific guidance.
        */
@@ -7536,7 +8618,7 @@ function sanitizeExtra(extra, allowTemperature) {
 function createOpenAIProviderFromEnv() {
   return createProviderFromEnv("OPENAI_API_KEY", import_openai3.default, OpenAIChatProvider);
 }
-var import_openai3, import_tiktoken, ROLE_MAP2, OpenAIChatProvider;
+var import_openai3, import_tiktoken, ROLE_MAP2, OPENAI_EFFORT_MAP, OpenAIChatProvider;
 var init_openai = __esm({
   "src/providers/openai.ts"() {
     "use strict";
@@ -7554,6 +8636,13 @@ var init_openai = __esm({
       user: "user",
       assistant: "assistant"
     };
+    OPENAI_EFFORT_MAP = {
+      none: "none",
+      low: "low",
+      medium: "medium",
+      high: "high",
+      maximum: "xhigh"
+    };
     OpenAIChatProvider = class extends BaseProviderAdapter {
       providerId = "openai";
       supports(descriptor) {
@@ -7644,10 +8733,15 @@ var init_openai = __esm({
         };
       }
       buildApiRequest(options, descriptor, spec, messages) {
-        const { maxTokens, temperature, topP, stopSequences, extra } = options;
+        const { maxTokens, temperature, topP, stopSequences, extra, reasoning } = options;
         const supportsTemperature = spec?.metadata?.supportsTemperature !== false;
         const shouldIncludeTemperature = typeof temperature === "number" && supportsTemperature;
         const sanitizedExtra = sanitizeExtra(extra, shouldIncludeTemperature);
+        const reasoningParam = reasoning?.enabled !== void 0 ? {
+          reasoning: {
+            effort: OPENAI_EFFORT_MAP[reasoning.effort ?? "medium"]
+          }
+        } : {};
         return {
           model: descriptor.name,
           messages: messages.map((message) => this.convertToOpenAIMessage(message)),
@@ -7658,6 +8752,7 @@ var init_openai = __esm({
           stop: stopSequences,
           stream: true,
           stream_options: { include_usage: true },
+          ...reasoningParam,
           ...sanitizedExtra ?? {},
           ...shouldIncludeTemperature ? { temperature } : {}
         };
@@ -7746,11 +8841,13 @@ var init_openai = __esm({
             yield { text: text3, rawEvent: chunk };
           }
           const finishReason = chunk.choices.find((choice) => choice.finish_reason)?.finish_reason;
+          const usageDetails = chunk.usage;
           const usage = chunk.usage ? {
             inputTokens: chunk.usage.prompt_tokens,
             outputTokens: chunk.usage.completion_tokens,
             totalTokens: chunk.usage.total_tokens,
-            cachedInputTokens: chunk.usage.prompt_tokens_details?.cached_tokens ?? 0
+            cachedInputTokens: usageDetails?.prompt_tokens_details?.cached_tokens ?? 0,
+            reasoningTokens: usageDetails?.completion_tokens_details?.reasoning_tokens
           } : void 0;
           if (finishReason || usage) {
             yield { text: "", finishReason, usage, rawEvent: chunk };
@@ -8285,7 +9382,7 @@ function createOpenRouterProviderFromEnv() {
   });
   return new OpenRouterProvider(client, config);
 }
-var import_openai4, OpenRouterProvider;
+var import_openai4, OPENROUTER_EFFORT_MAP, OpenRouterProvider;
 var init_openrouter = __esm({
   "src/providers/openrouter.ts"() {
     "use strict";
@@ -8293,6 +9390,13 @@ var init_openrouter = __esm({
     init_openai_compatible_provider();
     init_openrouter_models();
     init_utils();
+    OPENROUTER_EFFORT_MAP = {
+      none: "none",
+      low: "low",
+      medium: "medium",
+      high: "high",
+      maximum: "xhigh"
+    };
     OpenRouterProvider = class extends OpenAICompatibleProvider {
       providerId = "openrouter";
       providerAlias = "or";
@@ -8302,6 +9406,20 @@ var init_openrouter = __esm({
       getModelSpecs() {
         return OPENROUTER_MODELS;
       }
+      /**
+       * Override buildApiRequest to inject reasoning parameters.
+       * OpenRouter normalizes reasoning into the standard OpenAI format.
+       */
+      buildApiRequest(options, descriptor, spec, messages) {
+        const request = super.buildApiRequest(options, descriptor, spec, messages);
+        if (options.reasoning?.enabled !== void 0) {
+          const requestObj = request;
+          requestObj.reasoning = {
+            effort: OPENROUTER_EFFORT_MAP[options.reasoning.effort ?? "medium"]
+          };
+        }
+        return request;
+      }
       /**
        * Get custom headers for OpenRouter analytics.
        */
@@ -8539,9 +9657,10 @@ var init_model_registry = __esm({
        * @param outputTokens - Number of output tokens
        * @param cachedInputTokens - Number of cached input tokens (subset of inputTokens)
        * @param cacheCreationInputTokens - Number of cache creation tokens (subset of inputTokens, Anthropic only)
+       * @param reasoningTokens - Number of reasoning/thinking tokens (subset of outputTokens)
        * @returns CostEstimate if model found, undefined otherwise
        */
-      estimateCost(modelId, inputTokens, outputTokens, cachedInputTokens = 0, cacheCreationInputTokens = 0) {
+      estimateCost(modelId, inputTokens, outputTokens, cachedInputTokens = 0, cacheCreationInputTokens = 0, reasoningTokens = 0) {
         const spec = this.getModelSpec(modelId);
         if (!spec) return void 0;
         const cachedRate = spec.pricing.cachedInput ?? spec.pricing.input;
@@ -8551,13 +9670,18 @@ var init_model_registry = __esm({
         const cachedInputCost = cachedInputTokens / 1e6 * cachedRate;
         const cacheCreationCost = cacheCreationInputTokens / 1e6 * cacheWriteRate;
         const inputCost = uncachedInputCost + cachedInputCost + cacheCreationCost;
-        const outputCost = outputTokens / 1e6 * spec.pricing.output;
+        const reasoningRate = spec.pricing.reasoningOutput ?? spec.pricing.output;
+        const nonReasoningOutputTokens = outputTokens - reasoningTokens;
+        const reasoningCost = reasoningTokens / 1e6 * reasoningRate;
+        const nonReasoningOutputCost = nonReasoningOutputTokens / 1e6 * spec.pricing.output;
+        const outputCost = nonReasoningOutputCost + reasoningCost;
         const totalCost = inputCost + outputCost;
         return {
           inputCost,
           cachedInputCost,
           cacheCreationCost,
           outputCost,
+          reasoningCost,
           totalCost,
           currency: "USD"
         };
@@ -9229,6 +10353,8 @@ var init_builder = __esm({
     init_agent();
     init_agent_internal_key();
     init_event_handlers();
+    init_file_logging();
+    init_hook_presets();
     AgentBuilder = class {
       client;
       model;
@@ -9270,6 +10396,7 @@ var init_builder = __esm({
       // Shared retry config from parent for consistent backoff behavior
       // When a gadget calls withParentContext(ctx), this config is shared
       sharedRetryConfig;
+      reasoningConfig;
       constructor(client) {
         this.client = client;
       }
@@ -9855,6 +10982,60 @@ var init_builder = __esm({
         this.signal = signal;
         return this;
       }
+      /**
+       * Enable reasoning/thinking mode for reasoning-capable models.
+       *
+       * Can be called with:
+       * - No args: enables reasoning at "medium" effort
+       * - A string effort level: `withReasoning("high")`
+       * - A full config object: `withReasoning({ enabled: true, budgetTokens: 10000 })`
+       *
+       * @param config - Optional effort level or full reasoning config
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * // Simple — medium effort
+       * LLMist.createAgent()
+       *   .withModel("o3")
+       *   .withReasoning()
+       *   .ask("Solve this logic puzzle...");
+       *
+       * // Explicit effort level
+       * LLMist.createAgent()
+       *   .withModel("anthropic:claude-4-opus")
+       *   .withReasoning("high")
+       *   .ask("Analyze this complex problem");
+       *
+       * // Full config with explicit token budget
+       * LLMist.createAgent()
+       *   .withModel("anthropic:claude-4-opus")
+       *   .withReasoning({ enabled: true, budgetTokens: 16000 })
+       *   .ask("Step through this proof");
+       * ```
+       */
+      withReasoning(config) {
+        if (typeof config === "string") {
+          this.reasoningConfig = { enabled: true, effort: config };
+        } else if (config === void 0) {
+          this.reasoningConfig = { enabled: true, effort: "medium" };
+        } else {
+          this.reasoningConfig = config;
+        }
+        return this;
+      }
+      /**
+       * Explicitly disable reasoning for this agent, even if the model supports it.
+       *
+       * By default, reasoning is auto-enabled at "medium" effort for models with
+       * `features.reasoning: true`. Use this to opt out.
+       *
+       * @returns This builder for chaining
+       */
+      withoutReasoning() {
+        this.reasoningConfig = { enabled: false };
+        return this;
+      }
       /**
        * Set subagent configuration overrides.
        *
@@ -10022,9 +11203,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;
         }
@@ -10133,6 +11321,7 @@ ${endPrefix}`
           retryConfig: this.retryConfig,
           rateLimitConfig: this.rateLimitConfig,
           signal: this.signal,
+          reasoning: this.reasoningConfig,
           subagentConfig: this.subagentConfig,
           // Tree context for shared tree model (subagents share parent's tree)
           parentTree: this.parentContext?.tree,
@@ -10320,6 +11509,7 @@ ${endPrefix}`
           retryConfig: this.retryConfig,
           rateLimitConfig: this.rateLimitConfig,
           signal: this.signal,
+          reasoning: this.reasoningConfig,
           subagentConfig: this.subagentConfig,
           // Tree context for shared tree model (subagents share parent's tree)
           parentTree: this.parentContext?.tree,
@@ -10774,6 +11964,7 @@ var init_cost_reporting_client = __esm({
         let outputTokens = 0;
         let cachedInputTokens = 0;
         let cacheCreationInputTokens = 0;
+        let reasoningTokens = 0;
         const messages = [
           ...options?.systemPrompt ? [{ role: "system", content: options.systemPrompt }] : [],
           { role: "user", content: prompt }
@@ -10790,6 +11981,7 @@ var init_cost_reporting_client = __esm({
             outputTokens = chunk.usage.outputTokens;
             cachedInputTokens = chunk.usage.cachedInputTokens ?? 0;
             cacheCreationInputTokens = chunk.usage.cacheCreationInputTokens ?? 0;
+            reasoningTokens = chunk.usage.reasoningTokens ?? 0;
           }
         }
         this.reportCostFromUsage(
@@ -10797,7 +11989,8 @@ var init_cost_reporting_client = __esm({
           inputTokens,
           outputTokens,
           cachedInputTokens,
-          cacheCreationInputTokens
+          cacheCreationInputTokens,
+          reasoningTokens
         );
         return result;
       }
@@ -10816,6 +12009,7 @@ var init_cost_reporting_client = __esm({
         let outputTokens = 0;
         let cachedInputTokens = 0;
         let cacheCreationInputTokens = 0;
+        let reasoningTokens = 0;
         const messages = [
           ...options?.systemPrompt ? [{ role: "system", content: options.systemPrompt }] : [],
           { role: "user", content: prompt }
@@ -10835,6 +12029,7 @@ var init_cost_reporting_client = __esm({
               outputTokens = chunk.usage.outputTokens;
               cachedInputTokens = chunk.usage.cachedInputTokens ?? 0;
               cacheCreationInputTokens = chunk.usage.cacheCreationInputTokens ?? 0;
+              reasoningTokens = chunk.usage.reasoningTokens ?? 0;
             }
           }
         } finally {
@@ -10843,7 +12038,8 @@ var init_cost_reporting_client = __esm({
             inputTokens,
             outputTokens,
             cachedInputTokens,
-            cacheCreationInputTokens
+            cacheCreationInputTokens,
+            reasoningTokens
           );
         }
       }
@@ -10870,6 +12066,7 @@ var init_cost_reporting_client = __esm({
           let outputTokens = 0;
           let cachedInputTokens = 0;
           let cacheCreationInputTokens = 0;
+          let reasoningTokens = 0;
           try {
             for await (const chunk of innerStream) {
               if (chunk.usage) {
@@ -10877,6 +12074,7 @@ var init_cost_reporting_client = __esm({
                 outputTokens = chunk.usage.outputTokens;
                 cachedInputTokens = chunk.usage.cachedInputTokens ?? 0;
                 cacheCreationInputTokens = chunk.usage.cacheCreationInputTokens ?? 0;
+                reasoningTokens = chunk.usage.reasoningTokens ?? 0;
               }
               yield chunk;
             }
@@ -10887,7 +12085,8 @@ var init_cost_reporting_client = __esm({
                 inputTokens,
                 outputTokens,
                 cachedInputTokens,
-                cacheCreationInputTokens
+                cacheCreationInputTokens,
+                reasoningTokens
               );
             }
           }
@@ -10897,14 +12096,15 @@ var init_cost_reporting_client = __esm({
       /**
        * Calculates and reports cost from token usage.
        */
-      reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens = 0, cacheCreationInputTokens = 0) {
+      reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens = 0, cacheCreationInputTokens = 0, reasoningTokens = 0) {
         if (inputTokens === 0 && outputTokens === 0) return;
         const estimate = this.client.modelRegistry.estimateCost(
           model,
           inputTokens,
           outputTokens,
           cachedInputTokens,
-          cacheCreationInputTokens
+          cacheCreationInputTokens,
+          reasoningTokens
         );
         if (estimate && estimate.totalCost > 0) {
           this.reportCost(estimate.totalCost);
@@ -11996,9 +13196,18 @@ var init_stream_processor = __esm({
         let usage;
         let didExecuteGadgets = false;
         let shouldBreakLoop = false;
+        let thinkingContent = "";
         for await (const chunk of stream2) {
           if (chunk.finishReason) finishReason = chunk.finishReason;
           if (chunk.usage) usage = chunk.usage;
+          if (chunk.thinking?.content) {
+            thinkingContent += chunk.thinking.content;
+            yield {
+              type: "thinking",
+              content: chunk.thinking.content,
+              thinkingType: chunk.thinking.type
+            };
+          }
           let processedChunk = "";
           if (chunk.text) {
             processedChunk = chunk.text;
@@ -12112,7 +13321,8 @@ var init_stream_processor = __esm({
           finishReason,
           usage,
           rawResponse: this.responseText,
-          finalMessage
+          finalMessage,
+          thinkingContent: thinkingContent || void 0
         };
         yield completionEvent;
       }
@@ -12914,6 +14124,7 @@ var init_agent = __esm({
       mediaStore;
       // Cancellation
       signal;
+      reasoning;
       // Retry configuration
       retryConfig;
       // Rate limit tracker for proactive throttling
@@ -13005,6 +14216,7 @@ var init_agent = __esm({
           );
         }
         this.signal = options.signal;
+        this.reasoning = options.reasoning;
         this.retryConfig = options.sharedRetryConfig ?? resolveRetryConfig(options.retryConfig);
         if (options.sharedRateLimitTracker) {
           this.rateLimitTracker = options.sharedRateLimitTracker;
@@ -13407,6 +14619,7 @@ var init_agent = __esm({
                     usage: result.usage,
                     rawResponse: result.rawResponse,
                     finalMessage: result.finalMessage,
+                    thinkingContent: result.thinkingContent,
                     logger: this.logger,
                     subagentContext
                   };
@@ -13707,17 +14920,34 @@ var init_agent = __esm({
         });
         return { type: "compaction", event: compactionEvent };
       }
+      /**
+       * Resolve reasoning configuration with auto-enable logic.
+       *
+       * Priority: explicit config > auto-enable for reasoning models > undefined
+       * When a model has `features.reasoning: true` and no explicit config is set,
+       * reasoning is automatically enabled at "medium" effort.
+       */
+      resolveReasoningConfig(spec) {
+        if (this.reasoning !== void 0) return this.reasoning;
+        if (spec?.features?.reasoning) {
+          return { enabled: true, effort: "medium" };
+        }
+        return void 0;
+      }
       /**
        * Prepare LLM call options, create tree node, and process beforeLLMCall controller.
        * @returns options, node ID, and optional skipWithSynthetic response if controller wants to skip
        */
       async prepareLLMCall(iteration) {
+        const spec = this.client.modelRegistry?.getModelSpec?.(this.model);
+        const reasoning = this.resolveReasoningConfig(spec);
         let llmOptions = {
           model: this.model,
           messages: this.conversation.getMessages(),
           temperature: this.temperature,
           maxTokens: this.defaultMaxTokens,
-          signal: this.signal
+          signal: this.signal,
+          reasoning
         };
         const llmNode = this.tree.addLLMCall({
           iteration,
@@ -13787,13 +15017,15 @@ var init_agent = __esm({
           inputTokens,
           outputTokens,
           result.usage?.cachedInputTokens ?? 0,
-          result.usage?.cacheCreationInputTokens ?? 0
+          result.usage?.cacheCreationInputTokens ?? 0,
+          result.usage?.reasoningTokens ?? 0
         )?.totalCost;
         this.tree.completeLLMCall(nodeId, {
           response: result.rawResponse,
           usage: result.usage,
           finishReason: result.finishReason,
-          cost: llmCost
+          cost: llmCost,
+          thinkingContent: result.thinkingContent
         });
       }
       /**
@@ -13969,9 +15201,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,
@@ -14043,781 +15277,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();
@@ -14830,6 +15291,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 {
@@ -15619,9 +16081,11 @@ function getHostExports2(ctx) {
   filterRootEvents,
   format,
   formatBytes,
+  formatCallNumber,
   formatDate,
   formatDuration,
   formatLLMError,
+  formatLlmRequest,
   gadgetError,
   gadgetSuccess,
   getErrorMessage,