llmist 1.3.0 → 1.4.0

package/dist/chunk-UEEESLOA.js

@@ -0,0 +1,974 @@
+import {
+  BaseGadget,
+  DEFAULT_HINTS,
+  init_anthropic,
+  init_builder,
+  init_client,
+  init_config,
+  init_conversation_manager,
+  init_create_gadget,
+  init_discovery,
+  init_event_handlers,
+  init_exceptions,
+  init_executor,
+  init_gadget,
+  init_gadget_output_store,
+  init_gemini,
+  init_logger,
+  init_manager,
+  init_messages,
+  init_model_registry,
+  init_model_shortcuts,
+  init_openai,
+  init_options,
+  init_output_viewer,
+  init_parser,
+  init_prompt_config,
+  init_quick_methods,
+  init_registry,
+  init_strategies,
+  init_strategy,
+  init_stream_processor,
+  resolveHintTemplate
+} from "./chunk-VGZCFUPX.js";
+
+// src/index.ts
+init_builder();
+init_event_handlers();
+import { z } from "zod";
+
+// 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;
+    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,
+            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`
+            );
+          }
+        }
+      }
+    };
+  }
+  /**
+   * 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()
+    );
+  }
+};
+
+// src/agent/index.ts
+init_conversation_manager();
+init_stream_processor();
+init_gadget_output_store();
+
+// src/agent/compaction/index.ts
+init_config();
+init_strategy();
+init_strategies();
+init_manager();
+
+// src/agent/hints.ts
+init_prompt_config();
+function iterationProgressHint(options) {
+  const { timing = "always", showUrgency = true, template } = options ?? {};
+  return {
+    controllers: {
+      beforeLLMCall: async (ctx) => {
+        const iteration = ctx.iteration + 1;
+        const maxIterations = ctx.maxIterations;
+        const progress = iteration / maxIterations;
+        if (timing === "late" && progress < 0.5) {
+          return { action: "proceed" };
+        }
+        if (timing === "urgent" && progress < 0.8) {
+          return { action: "proceed" };
+        }
+        const remaining = maxIterations - iteration;
+        const hintContext = {
+          iteration,
+          maxIterations,
+          remaining
+        };
+        let hint = resolveHintTemplate(
+          template,
+          DEFAULT_HINTS.iterationProgressHint,
+          hintContext
+        );
+        if (showUrgency && progress >= 0.8) {
+          hint += " \u26A0\uFE0F Running low on iterations - focus on completing the task.";
+        }
+        const messages = [...ctx.options.messages];
+        let lastUserIndex = -1;
+        for (let i = messages.length - 1; i >= 0; i--) {
+          if (messages[i].role === "user") {
+            lastUserIndex = i;
+            break;
+          }
+        }
+        if (lastUserIndex >= 0) {
+          messages.splice(lastUserIndex + 1, 0, {
+            role: "user",
+            content: `[System Hint] ${hint}`
+          });
+        } else {
+          messages.push({
+            role: "user",
+            content: `[System Hint] ${hint}`
+          });
+        }
+        return {
+          action: "proceed",
+          modifiedOptions: { messages }
+        };
+      }
+    }
+  };
+}
+function parallelGadgetHint(options) {
+  const {
+    minGadgetsForEfficiency = 2,
+    message = DEFAULT_HINTS.parallelGadgetsHint,
+    enabled = true
+  } = options ?? {};
+  return {
+    controllers: {
+      afterLLMCall: async (ctx) => {
+        if (!enabled) {
+          return { action: "continue" };
+        }
+        if (ctx.gadgetCallCount > 0 && ctx.gadgetCallCount < minGadgetsForEfficiency) {
+          return {
+            action: "append_messages",
+            messages: [
+              {
+                role: "user",
+                content: `[System Hint] ${message}`
+              }
+            ]
+          };
+        }
+        return { action: "continue" };
+      }
+    }
+  };
+}
+function createHints(config) {
+  const hooksToMerge = [];
+  if (config.iterationProgress) {
+    const options = typeof config.iterationProgress === "boolean" ? {} : config.iterationProgress;
+    hooksToMerge.push(iterationProgressHint(options));
+  }
+  if (config.parallelGadgets) {
+    const options = typeof config.parallelGadgets === "boolean" ? {} : config.parallelGadgets;
+    hooksToMerge.push(parallelGadgetHint(options));
+  }
+  if (config.custom) {
+    hooksToMerge.push(...config.custom);
+  }
+  return HookPresets.merge(...hooksToMerge);
+}
+
+// src/index.ts
+init_client();
+init_messages();
+init_model_registry();
+init_model_shortcuts();
+init_options();
+init_prompt_config();
+init_quick_methods();
+init_create_gadget();
+init_output_viewer();
+init_exceptions();
+init_executor();
+init_gadget();
+init_parser();
+init_registry();
+
+// src/gadgets/typed-gadget.ts
+init_gadget();
+function Gadget(config) {
+  class GadgetBase extends BaseGadget {
+    description = config.description;
+    parameterSchema = config.schema;
+    name = config.name;
+    timeoutMs = config.timeoutMs;
+    examples = config.examples;
+    /**
+     * Type helper property for accessing inferred parameter type.
+     * This is used in the execute method signature: `execute(params: this['params'])`
+     *
+     * Note: This is just for type inference - the actual params in execute()
+     * will be Record<string, unknown> which you can safely cast to this['params']
+     */
+    params;
+  }
+  return GadgetBase;
+}
+
+// src/index.ts
+init_logger();
+init_anthropic();
+init_discovery();
+init_gemini();
+init_openai();
+
+export {
+  HookPresets,
+  iterationProgressHint,
+  parallelGadgetHint,
+  createHints,
+  Gadget,
+  z
+};
+//# sourceMappingURL=chunk-UEEESLOA.js.map