llmist 0.1.3 → 0.1.5

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createGadget
-} from "./chunk-JEBGLCDW.js";
+} from "./chunk-MO5ONHPZ.js";
 import {
   MockBuilder,
   MockManager,
@@ -13,7 +13,7 @@ import {
   mockLLM,
   validateAndApplyDefaults,
   validateGadgetParams
-} from "./chunk-DCW33WV7.js";
+} from "./chunk-PVHHXDCV.js";
 import {
   AgentBuilder,
   AnthropicMessagesProvider,
@@ -70,7 +70,7 @@ import {
   resolveRulesTemplate,
   runWithHandlers,
   stream
-} from "./chunk-TP7HE3MN.js";
+} from "./chunk-J3NCIWMY.js";
 
 // src/index.ts
 init_builder();
@@ -80,18 +80,59 @@ import { z } from "zod";
 // src/agent/hook-presets.ts
 var HookPresets = class _HookPresets {
   /**
-   * Preset: Basic logging of all events.
+   * Logs LLM calls and gadget execution to console with optional verbosity.
    *
-   * Logs LLM calls and gadget executions to console.
+   * **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
-   * @returns Hook configuration
+   * @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
-   * .withHooks(HookPresets.logging())
-   * .withHooks(HookPresets.logging({ verbose: true }))
+   * // 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 {
@@ -123,16 +164,54 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Performance timing for all operations.
-   *
    * Measures and logs execution time for LLM calls and gadgets.
    *
-   * @returns Hook configuration
+   * **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
-   * .withHooks(HookPresets.timing())
+   * // 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();
@@ -169,16 +248,57 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Token usage tracking.
+   * 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
    *
-   * Tracks and logs cumulative token usage across all LLM calls.
+   * **Performance:** Minimal overhead. Simple counter increments.
    *
-   * @returns Hook configuration
+   * **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
-   * .withHooks(HookPresets.tokenTracking())
+   * // 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;
@@ -197,16 +317,64 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Error logging.
+   * 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
    *
-   * Logs detailed error information for debugging.
+   * **Use cases:**
+   * - Troubleshooting production issues
+   * - Understanding error patterns and frequency
+   * - Debugging error recovery behavior
+   * - Collecting error metrics for monitoring
    *
-   * @returns Hook configuration
+   * **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
-   * .withHooks(HookPresets.errorLogging())
+   * // 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 {
@@ -227,48 +395,131 @@ var HookPresets = class _HookPresets {
     };
   }
   /**
-   * Preset: Silent (no output).
+   * Returns empty hook configuration for clean output without any logging.
    *
-   * Useful for testing or when you want complete control.
+   * **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
-   * .withHooks(HookPresets.silent())
+   * // 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 {};
   }
   /**
-   * Merge multiple hook configurations.
+   * 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
    *
-   * Combines hook presets or custom configurations into a single object.
-   * When multiple hooks target the same lifecycle event, they are composed
-   * to run sequentially (all handlers will execute).
+   * **Use cases:**
+   * - Combining multiple presets (logging + timing + tokens)
+   * - Adding custom hooks to presets
+   * - Building modular, reusable monitoring configurations
+   * - Environment-specific hook composition
    *
-   * @param hookSets - Array of hook configurations to merge
-   * @returns Merged hook configuration with composed handlers
+   * **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.logging({ verbose: true }),
    *   HookPresets.timing(),
-   *   HookPresets.tokenTracking(),
    *   {
-   *     // Custom hook
    *     observers: {
    *       onLLMCallComplete: async (ctx) => {
-   *         saveToDatabase(ctx);
-   *       }
-   *     }
+   *         await saveMetrics({ tokens: ctx.usage?.totalTokens });
+   *       },
+   *     },
    *   }
    * ))
-   * // All onLLMCallComplete handlers from logging, timing, tokenTracking,
-   * // and the custom hook will execute in order
    * ```
+   *
+   * @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 = {
@@ -301,18 +552,62 @@ var HookPresets = class _HookPresets {
     return merged;
   }
   /**
-   * Preset: Complete monitoring suite.
+   * Composite preset combining logging, timing, tokenTracking, and errorLogging.
    *
-   * Combines logging, timing, and token tracking.
+   * This is the recommended preset for development and initial production deployments,
+   * providing comprehensive observability with a single method call.
    *
-   * @param options - Options for monitoring
-   * @returns Merged hook configuration
+   * **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
-   * .withHooks(HookPresets.monitoring())
-   * .withHooks(HookPresets.monitoring({ verbose: true }))
+   * // 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(

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/agent/hook-presets.ts","../src/agent/index.ts","../src/gadgets/typed-gadget.ts"],"sourcesContent":["// Re-export Zod's z for schema definitions\n// Using llmist's z ensures .describe() metadata is preserved in JSON schemas\nexport { z } from \"zod\";\n// Syntactic sugar: Agent builder and event handlers\nexport type { HistoryMessage } from \"./agent/builder.js\";\nexport { AgentBuilder } from \"./agent/builder.js\";\nexport type { EventHandlers } from \"./agent/event-handlers.js\";\nexport { collectEvents, collectText, runWithHandlers } from \"./agent/event-handlers.js\";\n// Syntactic sugar: Hook presets\nexport type { LoggingOptions } from \"./agent/hook-presets.js\";\nexport { HookPresets } from \"./agent/hook-presets.js\";\n// Agent infrastructure\n// New clean hooks system\nexport type {\n  AfterGadgetExecutionAction,\n  AfterGadgetExecutionControllerContext,\n  AfterLLMCallAction,\n  AfterLLMCallControllerContext,\n  AfterLLMErrorAction,\n  AgentHooks,\n  AgentOptions,\n  BeforeGadgetExecutionAction,\n  BeforeLLMCallAction,\n  // Interceptor contexts\n  ChunkInterceptorContext,\n  Controllers,\n  GadgetExecutionControllerContext,\n  GadgetParameterInterceptorContext,\n  GadgetResultInterceptorContext,\n  IConversationManager,\n  Interceptors,\n  // Controller contexts and actions\n  LLMCallControllerContext,\n  LLMErrorControllerContext,\n  MessageInterceptorContext,\n  ObserveChunkContext,\n  ObserveGadgetCompleteContext,\n  ObserveGadgetStartContext,\n  // Observer contexts\n  ObserveLLMCallContext,\n  ObserveLLMCompleteContext,\n  ObserveLLMErrorContext,\n  Observers,\n  StreamProcessingResult,\n  StreamProcessorOptions,\n} from \"./agent/index.js\";\nexport { ConversationManager, StreamProcessor } from \"./agent/index.js\";\nexport type { LLMistOptions } from \"./core/client.js\";\nexport { LLMist } from \"./core/client.js\";\nexport type { LLMMessage, LLMRole } from \"./core/messages.js\";\nexport { LLMMessageBuilder } from \"./core/messages.js\";\n// Model catalog\nexport type {\n  CostEstimate,\n  ModelFeatures,\n  ModelLimits,\n  ModelPricing,\n  ModelSpec,\n} from \"./core/model-catalog.js\";\nexport { ModelRegistry } from \"./core/model-registry.js\";\n\n// Syntactic sugar: Model shortcuts and quick methods\nexport {\n  getModelId,\n  getProvider,\n  hasProviderPrefix,\n  MODEL_ALIASES,\n  resolveModel,\n} from \"./core/model-shortcuts.js\";\nexport type {\n  LLMGenerationOptions,\n  LLMStream,\n  LLMStreamChunk,\n  ModelDescriptor,\n  ProviderIdentifier,\n  TokenUsage,\n} from \"./core/options.js\";\nexport { ModelIdentifierParser } from \"./core/options.js\";\nexport type { PromptConfig, PromptContext, PromptTemplate } from \"./core/prompt-config.js\";\nexport {\n  DEFAULT_PROMPTS,\n  resolvePromptTemplate,\n  resolveRulesTemplate,\n} from \"./core/prompt-config.js\";\nexport type { QuickOptions } from \"./core/quick-methods.js\";\nexport { complete, stream } from \"./core/quick-methods.js\";\nexport type { CreateGadgetConfig } from \"./gadgets/create-gadget.js\";\nexport { createGadget } from \"./gadgets/create-gadget.js\";\n// Gadget infrastructure\nexport { BreakLoopException, HumanInputException } from \"./gadgets/exceptions.js\";\nexport { GadgetExecutor } from \"./gadgets/executor.js\";\nexport { BaseGadget } from \"./gadgets/gadget.js\";\nexport { StreamParser } from \"./gadgets/parser.js\";\nexport type { GadgetClass, GadgetOrClass } from \"./gadgets/registry.js\";\nexport { GadgetRegistry } from \"./gadgets/registry.js\";\n\n// Syntactic sugar: Typed gadgets and helpers\nexport type { GadgetConfig } from \"./gadgets/typed-gadget.js\";\nexport { Gadget } from \"./gadgets/typed-gadget.js\";\nexport type {\n  GadgetExecutionResult,\n  ParsedGadgetCall,\n  StreamEvent,\n  TextOnlyAction,\n  TextOnlyContext,\n  TextOnlyCustomHandler,\n  TextOnlyGadgetConfig,\n  TextOnlyHandler,\n  TextOnlyStrategy,\n} from \"./gadgets/types.js\";\nexport type { ValidationIssue, ValidationResult } from \"./gadgets/validation.js\";\nexport { validateAndApplyDefaults, validateGadgetParams } from \"./gadgets/validation.js\";\nexport type { LoggerOptions } from \"./logging/logger.js\";\nexport { createLogger, defaultLogger } from \"./logging/logger.js\";\nexport {\n  AnthropicMessagesProvider,\n  createAnthropicProviderFromEnv,\n} from \"./providers/anthropic.js\";\nexport { discoverProviderAdapters } from \"./providers/discovery.js\";\nexport { createGeminiProviderFromEnv, GeminiGenerativeProvider } from \"./providers/gemini.js\";\nexport { createOpenAIProviderFromEnv, OpenAIChatProvider } from \"./providers/openai.js\";\nexport type { ProviderAdapter } from \"./providers/provider.js\";\n\n// Testing/Mock infrastructure\nexport type {\n  MockMatcher,\n  MockMatcherContext,\n  MockOptions,\n  MockRegistration,\n  MockResponse,\n  MockStats,\n} from \"./testing/index.js\";\nexport {\n  createMockAdapter,\n  createMockClient,\n  createMockStream,\n  createTextMockStream,\n  getMockManager,\n  MockBuilder,\n  MockManager,\n  MockProviderAdapter,\n  mockLLM,\n} from \"./testing/index.js\";\n","/**\n * Common hook presets for logging, timing, and monitoring.\n *\n * @example\n * ```typescript\n * import { HookPresets } from 'llmist/hooks';\n *\n * const agent = LLMist.createAgent()\n *   .withHooks(HookPresets.logging())\n *   .ask(\"...\");\n *\n * // Or combine multiple presets\n * const agent = LLMist.createAgent()\n *   .withHooks(HookPresets.merge(\n *     HookPresets.logging({ verbose: true }),\n *     HookPresets.timing(),\n *     HookPresets.tokenTracking()\n *   ))\n *   .ask(\"...\");\n * ```\n */\n\nimport type { AgentHooks } from \"./hooks.js\";\n\n/**\n * Options for logging preset.\n */\nexport interface LoggingOptions {\n  /** Include verbose details like parameters and results */\n  verbose?: boolean;\n}\n\n/**\n * Common hook presets.\n */\nexport class HookPresets {\n  /**\n   * Preset: Basic logging of all events.\n   *\n   * Logs LLM calls and gadget executions to console.\n   *\n   * @param options - Logging options\n   * @returns Hook configuration\n   *\n   * @example\n   * ```typescript\n   * .withHooks(HookPresets.logging())\n   * .withHooks(HookPresets.logging({ verbose: true }))\n   * ```\n   */\n  static logging(options: LoggingOptions = {}): AgentHooks {\n    return {\n      observers: {\n        onLLMCallStart: async (ctx) => {\n          console.log(`[LLM] Starting call (iteration ${ctx.iteration})`);\n        },\n        onLLMCallComplete: async (ctx) => {\n          const tokens = ctx.usage?.totalTokens ?? \"unknown\";\n          console.log(`[LLM] Completed (tokens: ${tokens})`);\n          if (options.verbose && ctx.finalMessage) {\n            console.log(`[LLM] Response: ${ctx.finalMessage}`);\n          }\n        },\n        onGadgetExecutionStart: async (ctx) => {\n          console.log(`[GADGET] Executing ${ctx.gadgetName}`);\n          if (options.verbose) {\n            console.log(`[GADGET] Parameters:`, JSON.stringify(ctx.parameters, null, 2));\n          }\n        },\n        onGadgetExecutionComplete: async (ctx) => {\n          console.log(`[GADGET] Completed ${ctx.gadgetName}`);\n          if (options.verbose) {\n            const display = ctx.error ?? ctx.finalResult ?? \"(no result)\";\n            console.log(`[GADGET] Result: ${display}`);\n          }\n        },\n      },\n    };\n  }\n\n  /**\n   * Preset: Performance timing for all operations.\n   *\n   * Measures and logs execution time for LLM calls and gadgets.\n   *\n   * @returns Hook configuration\n   *\n   * @example\n   * ```typescript\n   * .withHooks(HookPresets.timing())\n   * ```\n   */\n  static timing(): AgentHooks {\n    const timings = new Map<string, number>();\n\n    return {\n      observers: {\n        onLLMCallStart: async (ctx) => {\n          timings.set(`llm-${ctx.iteration}`, Date.now());\n        },\n        onLLMCallComplete: async (ctx) => {\n          const start = timings.get(`llm-${ctx.iteration}`);\n          if (start) {\n            const duration = Date.now() - start;\n            console.log(`⏱️  LLM call took ${duration}ms`);\n            timings.delete(`llm-${ctx.iteration}`);\n          }\n        },\n        onGadgetExecutionStart: async (ctx) => {\n          const key = `gadget-${ctx.gadgetName}-${Date.now()}`;\n          timings.set(key, Date.now());\n          // Store key for lookup in complete handler\n          (ctx as any)._timingKey = key;\n        },\n        onGadgetExecutionComplete: async (ctx) => {\n          const key = (ctx as any)._timingKey;\n          if (key) {\n            const start = timings.get(key);\n            if (start) {\n              const duration = Date.now() - start;\n              console.log(`⏱️  Gadget ${ctx.gadgetName} took ${duration}ms`);\n              timings.delete(key);\n            }\n          }\n        },\n      },\n    };\n  }\n\n  /**\n   * Preset: Token usage tracking.\n   *\n   * Tracks and logs cumulative token usage across all LLM calls.\n   *\n   * @returns Hook configuration\n   *\n   * @example\n   * ```typescript\n   * .withHooks(HookPresets.tokenTracking())\n   * ```\n   */\n  static tokenTracking(): AgentHooks {\n    let totalTokens = 0;\n    let totalCalls = 0;\n\n    return {\n      observers: {\n        onLLMCallComplete: async (ctx) => {\n          totalCalls++;\n          if (ctx.usage?.totalTokens) {\n            totalTokens += ctx.usage.totalTokens;\n            console.log(`📊 Tokens this call: ${ctx.usage.totalTokens}`);\n            console.log(`📊 Total tokens: ${totalTokens} (across ${totalCalls} calls)`);\n          }\n        },\n      },\n    };\n  }\n\n  /**\n   * Preset: Error logging.\n   *\n   * Logs detailed error information for debugging.\n   *\n   * @returns Hook configuration\n   *\n   * @example\n   * ```typescript\n   * .withHooks(HookPresets.errorLogging())\n   * ```\n   */\n  static errorLogging(): AgentHooks {\n    return {\n      observers: {\n        onLLMCallError: async (ctx) => {\n          console.error(`❌ LLM Error (iteration ${ctx.iteration}):`, ctx.error.message);\n          console.error(`   Model: ${ctx.options.model}`);\n          console.error(`   Recovered: ${ctx.recovered}`);\n        },\n        onGadgetExecutionComplete: async (ctx) => {\n          if (ctx.error) {\n            console.error(`❌ Gadget Error: ${ctx.gadgetName}`);\n            console.error(`   Error: ${ctx.error}`);\n            console.error(`   Parameters:`, JSON.stringify(ctx.parameters, null, 2));\n          }\n        },\n      },\n    };\n  }\n\n  /**\n   * Preset: Silent (no output).\n   *\n   * Useful for testing or when you want complete control.\n   *\n   * @returns Empty hook configuration\n   *\n   * @example\n   * ```typescript\n   * .withHooks(HookPresets.silent())\n   * ```\n   */\n  static silent(): AgentHooks {\n    return {};\n  }\n\n  /**\n   * Merge multiple hook configurations.\n   *\n   * Combines hook presets or custom configurations into a single object.\n   * When multiple hooks target the same lifecycle event, they are composed\n   * to run sequentially (all handlers will execute).\n   *\n   * @param hookSets - Array of hook configurations to merge\n   * @returns Merged hook configuration with composed handlers\n   *\n   * @example\n   * ```typescript\n   * .withHooks(HookPresets.merge(\n   *   HookPresets.logging({ verbose: true }),\n   *   HookPresets.timing(),\n   *   HookPresets.tokenTracking(),\n   *   {\n   *     // Custom hook\n   *     observers: {\n   *       onLLMCallComplete: async (ctx) => {\n   *         saveToDatabase(ctx);\n   *       }\n   *     }\n   *   }\n   * ))\n   * // All onLLMCallComplete handlers from logging, timing, tokenTracking,\n   * // and the custom hook will execute in order\n   * ```\n   */\n  static merge(...hookSets: AgentHooks[]): AgentHooks {\n    const merged: AgentHooks = {\n      observers: {},\n      interceptors: {},\n      controllers: {},\n    };\n\n    // Compose observers: run all handlers for the same event\n    for (const hooks of hookSets) {\n      if (hooks.observers) {\n        for (const [key, handler] of Object.entries(hooks.observers)) {\n          const typedKey = key as keyof typeof hooks.observers;\n          if (merged.observers![typedKey]) {\n            // Compose: run both existing and new handler\n            const existing = merged.observers![typedKey];\n            merged.observers![typedKey] = async (ctx: any) => {\n              await existing(ctx);\n              await handler(ctx);\n            };\n          } else {\n            merged.observers![typedKey] = handler as any;\n          }\n        }\n      }\n\n      // Interceptors: last one wins (complex signatures make composition impractical)\n      // Each interceptor has different parameters (chunk, message, parameters, etc.)\n      // so we can't meaningfully compose them like we do with observers\n      if (hooks.interceptors) {\n        Object.assign(merged.interceptors!, hooks.interceptors);\n      }\n\n      // Controllers: last one wins (can't meaningfully compose boolean returns)\n      if (hooks.controllers) {\n        Object.assign(merged.controllers!, hooks.controllers);\n      }\n    }\n\n    return merged;\n  }\n\n  /**\n   * Preset: Complete monitoring suite.\n   *\n   * Combines logging, timing, and token tracking.\n   *\n   * @param options - Options for monitoring\n   * @returns Merged hook configuration\n   *\n   * @example\n   * ```typescript\n   * .withHooks(HookPresets.monitoring())\n   * .withHooks(HookPresets.monitoring({ verbose: true }))\n   * ```\n   */\n  static monitoring(options: LoggingOptions = {}): AgentHooks {\n    return HookPresets.merge(\n      HookPresets.logging(options),\n      HookPresets.timing(),\n      HookPresets.tokenTracking(),\n      HookPresets.errorLogging(),\n    );\n  }\n}\n","/**\n * Agent module - Composable, single-responsibility architecture for LLM agents.\n * This module provides a cleaner alternative to the monolithic AgentLoop.\n */\n\nexport type { AgentOptions } from \"./agent.js\";\nexport { ConversationManager } from \"./conversation-manager.js\";\n// New clean hooks system\nexport type {\n  AfterGadgetExecutionAction,\n  AfterGadgetExecutionControllerContext,\n  AfterLLMCallAction,\n  AfterLLMCallControllerContext,\n  AfterLLMErrorAction,\n  AgentHooks,\n  BeforeGadgetExecutionAction,\n  BeforeLLMCallAction,\n  // Interceptor contexts\n  ChunkInterceptorContext,\n  Controllers,\n  GadgetExecutionControllerContext,\n  GadgetParameterInterceptorContext,\n  GadgetResultInterceptorContext,\n  Interceptors,\n  // Controller contexts and actions\n  LLMCallControllerContext,\n  LLMErrorControllerContext,\n  MessageInterceptorContext,\n  ObserveChunkContext,\n  ObserveGadgetCompleteContext,\n  ObserveGadgetStartContext,\n  // Observer contexts\n  ObserveLLMCallContext,\n  ObserveLLMCompleteContext,\n  ObserveLLMErrorContext,\n  Observers,\n} from \"./hooks.js\";\nexport type { IConversationManager } from \"./interfaces.js\";\n\n// StreamProcessor for advanced use cases\nexport {\n  type StreamProcessingResult,\n  StreamProcessor,\n  type StreamProcessorOptions,\n} from \"./stream-processor.js\";\n","/**\n * Type-safe gadget factory with automatic parameter inference.\n *\n * Gadget eliminates the need for manual type assertions\n * by automatically inferring parameter types from the Zod schema.\n *\n * @example\n * ```typescript\n * class Calculator extends Gadget({\n *   description: \"Performs arithmetic operations\",\n *   schema: z.object({\n *     operation: z.enum([\"add\", \"subtract\"]),\n *     a: z.number(),\n *     b: z.number(),\n *   }),\n * }) {\n *   // ✨ params is automatically typed!\n *   execute(params: this['params']): string {\n *     const { operation, a, b } = params; // All typed!\n *     return operation === \"add\" ? String(a + b) : String(a - b);\n *   }\n * }\n * ```\n */\n\nimport type { ZodType } from \"zod\";\nimport { BaseGadget } from \"./gadget.js\";\n\n/**\n * Infer the TypeScript type from a Zod schema.\n */\ntype InferSchema<T> = T extends ZodType<infer U> ? U : never;\n\n/**\n * Configuration for creating a typed gadget.\n */\nexport interface GadgetConfig<TSchema extends ZodType> {\n  /** Human-readable description of what the gadget does */\n  description: string;\n\n  /** Zod schema for parameter validation */\n  schema: TSchema;\n\n  /** Optional custom name (defaults to class name) */\n  name?: string;\n\n  /** Optional timeout in milliseconds */\n  timeoutMs?: number;\n}\n\n/**\n * Factory function to create a typed gadget base class.\n *\n * The returned class automatically infers parameter types from the Zod schema,\n * eliminating the need for manual type assertions in the execute method.\n *\n * @param config - Configuration with description and schema\n * @returns Base class to extend with typed execute method\n *\n * @example\n * ```typescript\n * import { z } from 'zod';\n * import { Gadget } from 'llmist';\n *\n * class Calculator extends Gadget({\n *   description: \"Performs arithmetic operations\",\n *   schema: z.object({\n *     operation: z.enum([\"add\", \"subtract\", \"multiply\", \"divide\"]),\n *     a: z.number().describe(\"First number\"),\n *     b: z.number().describe(\"Second number\"),\n *   }),\n * }) {\n *   execute(params: this['params']): string {\n *     // params is automatically typed as:\n *     // { operation: \"add\" | \"subtract\" | \"multiply\" | \"divide\"; a: number; b: number }\n *     const { operation, a, b } = params;\n *\n *     switch (operation) {\n *       case \"add\": return String(a + b);\n *       case \"subtract\": return String(a - b);\n *       case \"multiply\": return String(a * b);\n *       case \"divide\": return String(a / b);\n *     }\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * // With async execution\n * class WeatherGadget extends Gadget({\n *   description: \"Fetches weather for a city\",\n *   schema: z.object({\n *     city: z.string().min(1).describe(\"City name\"),\n *   }),\n *   timeoutMs: 10000,\n * }) {\n *   async execute(params: this['params']): Promise<string> {\n *     const { city } = params; // Automatically typed as { city: string }\n *     const weather = await fetchWeather(city);\n *     return `Weather in ${city}: ${weather}`;\n *   }\n * }\n * ```\n */\nexport function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>) {\n  abstract class GadgetBase extends BaseGadget {\n    description = config.description;\n    parameterSchema = config.schema;\n    name = config.name;\n    timeoutMs = config.timeoutMs;\n\n    /**\n     * Type helper property for accessing inferred parameter type.\n     * This is used in the execute method signature: `execute(params: this['params'])`\n     *\n     * Note: This is just for type inference - the actual params in execute()\n     * will be Record<string, unknown> which you can safely cast to this['params']\n     */\n    readonly params!: InferSchema<TSchema>;\n\n    /**\n     * Execute the gadget. Subclasses should cast params to this['params'].\n     *\n     * @param params - Validated parameters from the LLM\n     * @returns Result as a string (or Promise<string> for async gadgets)\n     *\n     * @example\n     * ```typescript\n     * execute(params: Record<string, unknown>): string {\n     *   const typed = params as this['params'];\n     *   // Now 'typed' is fully typed!\n     *   return String(typed.a + typed.b);\n     * }\n     * ```\n     */\n    abstract execute(params: Record<string, unknown>): string | Promise<string>;\n  }\n\n  return GadgetBase as {\n    new (): GadgetBase & { params: InferSchema<TSchema> };\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/agent/hook-presets.ts","../src/agent/index.ts","../src/gadgets/typed-gadget.ts"],"sourcesContent":["// Re-export Zod's z for schema definitions\n// Using llmist's z ensures .describe() metadata is preserved in JSON schemas\nexport { z } from \"zod\";\n// Syntactic sugar: Agent builder and event handlers\nexport type { HistoryMessage } from \"./agent/builder.js\";\nexport { AgentBuilder } from \"./agent/builder.js\";\nexport type { EventHandlers } from \"./agent/event-handlers.js\";\nexport { collectEvents, collectText, runWithHandlers } from \"./agent/event-handlers.js\";\n// Syntactic sugar: Hook presets\nexport type { LoggingOptions } from \"./agent/hook-presets.js\";\nexport { HookPresets } from \"./agent/hook-presets.js\";\n// Agent infrastructure\n// New clean hooks system\nexport type {\n  AfterGadgetExecutionAction,\n  AfterGadgetExecutionControllerContext,\n  AfterLLMCallAction,\n  AfterLLMCallControllerContext,\n  AfterLLMErrorAction,\n  AgentHooks,\n  AgentOptions,\n  BeforeGadgetExecutionAction,\n  BeforeLLMCallAction,\n  // Interceptor contexts\n  ChunkInterceptorContext,\n  Controllers,\n  GadgetExecutionControllerContext,\n  GadgetParameterInterceptorContext,\n  GadgetResultInterceptorContext,\n  IConversationManager,\n  Interceptors,\n  // Controller contexts and actions\n  LLMCallControllerContext,\n  LLMErrorControllerContext,\n  MessageInterceptorContext,\n  ObserveChunkContext,\n  ObserveGadgetCompleteContext,\n  ObserveGadgetStartContext,\n  // Observer contexts\n  ObserveLLMCallContext,\n  ObserveLLMCompleteContext,\n  ObserveLLMErrorContext,\n  Observers,\n  StreamProcessingResult,\n  StreamProcessorOptions,\n} from \"./agent/index.js\";\nexport { ConversationManager, StreamProcessor } from \"./agent/index.js\";\nexport type { LLMistOptions } from \"./core/client.js\";\nexport { LLMist } from \"./core/client.js\";\nexport type { LLMMessage, LLMRole } from \"./core/messages.js\";\nexport { LLMMessageBuilder } from \"./core/messages.js\";\n// Model catalog\nexport type {\n  CostEstimate,\n  ModelFeatures,\n  ModelLimits,\n  ModelPricing,\n  ModelSpec,\n} from \"./core/model-catalog.js\";\nexport { ModelRegistry } from \"./core/model-registry.js\";\n\n// Syntactic sugar: Model shortcuts and quick methods\nexport {\n  getModelId,\n  getProvider,\n  hasProviderPrefix,\n  MODEL_ALIASES,\n  resolveModel,\n} from \"./core/model-shortcuts.js\";\nexport type {\n  LLMGenerationOptions,\n  LLMStream,\n  LLMStreamChunk,\n  ModelDescriptor,\n  ProviderIdentifier,\n  TokenUsage,\n} from \"./core/options.js\";\nexport { ModelIdentifierParser } from \"./core/options.js\";\nexport type { PromptConfig, PromptContext, PromptTemplate } from \"./core/prompt-config.js\";\nexport {\n  DEFAULT_PROMPTS,\n  resolvePromptTemplate,\n  resolveRulesTemplate,\n} from \"./core/prompt-config.js\";\nexport type { QuickOptions } from \"./core/quick-methods.js\";\nexport { complete, stream } from \"./core/quick-methods.js\";\nexport type { CreateGadgetConfig } from \"./gadgets/create-gadget.js\";\nexport { createGadget } from \"./gadgets/create-gadget.js\";\n// Gadget infrastructure\nexport { BreakLoopException, HumanInputException } from \"./gadgets/exceptions.js\";\nexport { GadgetExecutor } from \"./gadgets/executor.js\";\nexport { BaseGadget } from \"./gadgets/gadget.js\";\nexport { StreamParser } from \"./gadgets/parser.js\";\nexport type { GadgetClass, GadgetOrClass } from \"./gadgets/registry.js\";\nexport { GadgetRegistry } from \"./gadgets/registry.js\";\n\n// Syntactic sugar: Typed gadgets and helpers\nexport type { GadgetConfig } from \"./gadgets/typed-gadget.js\";\nexport { Gadget } from \"./gadgets/typed-gadget.js\";\nexport type {\n  GadgetExecutionResult,\n  ParsedGadgetCall,\n  StreamEvent,\n  TextOnlyAction,\n  TextOnlyContext,\n  TextOnlyCustomHandler,\n  TextOnlyGadgetConfig,\n  TextOnlyHandler,\n  TextOnlyStrategy,\n} from \"./gadgets/types.js\";\nexport type { ValidationIssue, ValidationResult } from \"./gadgets/validation.js\";\nexport { validateAndApplyDefaults, validateGadgetParams } from \"./gadgets/validation.js\";\nexport type { LoggerOptions } from \"./logging/logger.js\";\nexport { createLogger, defaultLogger } from \"./logging/logger.js\";\nexport {\n  AnthropicMessagesProvider,\n  createAnthropicProviderFromEnv,\n} from \"./providers/anthropic.js\";\nexport { discoverProviderAdapters } from \"./providers/discovery.js\";\nexport { createGeminiProviderFromEnv, GeminiGenerativeProvider } from \"./providers/gemini.js\";\nexport { createOpenAIProviderFromEnv, OpenAIChatProvider } from \"./providers/openai.js\";\nexport type { ProviderAdapter } from \"./providers/provider.js\";\n\n// Testing/Mock infrastructure\nexport type {\n  MockMatcher,\n  MockMatcherContext,\n  MockOptions,\n  MockRegistration,\n  MockResponse,\n  MockStats,\n} from \"./testing/index.js\";\nexport {\n  createMockAdapter,\n  createMockClient,\n  createMockStream,\n  createTextMockStream,\n  getMockManager,\n  MockBuilder,\n  MockManager,\n  MockProviderAdapter,\n  mockLLM,\n} from \"./testing/index.js\";\n","/**\n * Ready-to-use hook configurations for common monitoring, logging, and debugging tasks.\n *\n * HookPresets provide instant observability without writing custom hooks. They're the\n * fastest way to add monitoring to your agents during development and production.\n *\n * ## Available Presets\n *\n * - **logging(options?)** - Log LLM calls and gadget execution\n * - **timing()** - Measure execution time for operations\n * - **tokenTracking()** - Track cumulative token usage and costs\n * - **errorLogging()** - Log detailed error information\n * - **silent()** - No output (useful for testing)\n * - **monitoring(options?)** - All-in-one preset combining logging, timing, tokens, and errors\n * - **merge(...hookSets)** - Combine multiple hook configurations\n *\n * ## Quick Start\n *\n * @example\n * ```typescript\n * import { LLMist, HookPresets } from 'llmist';\n *\n * // Basic logging\n * await LLMist.createAgent()\n *   .withHooks(HookPresets.logging())\n *   .ask(\"Your prompt\");\n *\n * // Full monitoring suite (recommended for development)\n * await LLMist.createAgent()\n *   .withHooks(HookPresets.monitoring({ verbose: true }))\n *   .ask(\"Your prompt\");\n *\n * // Combine multiple presets\n * await LLMist.createAgent()\n *   .withHooks(HookPresets.merge(\n *     HookPresets.timing(),\n *     HookPresets.tokenTracking()\n *   ))\n *   .ask(\"Your prompt\");\n *\n * // Environment-based configuration\n * const hooks = process.env.NODE_ENV === 'production'\n *   ? HookPresets.merge(HookPresets.errorLogging(), HookPresets.tokenTracking())\n *   : HookPresets.monitoring({ verbose: true });\n *\n * await LLMist.createAgent()\n *   .withHooks(hooks)\n *   .ask(\"Your prompt\");\n * ```\n *\n * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md | Full documentation}\n */\n\nimport type { AgentHooks } from \"./hooks.js\";\n\n/**\n * Options for logging preset.\n */\nexport interface LoggingOptions {\n  /** Include verbose details like parameters and results */\n  verbose?: boolean;\n}\n\n/**\n * Common hook presets.\n */\nexport class HookPresets {\n  /**\n   * Logs LLM calls and gadget execution to console with optional verbosity.\n   *\n   * **Output (basic mode):**\n   * - LLM call start/complete events with iteration numbers\n   * - Gadget execution start/complete with gadget names\n   * - Token counts when available\n   *\n   * **Output (verbose mode):**\n   * - All basic mode output\n   * - Full gadget parameters (formatted JSON)\n   * - Full gadget results\n   * - Complete LLM response text\n   *\n   * **Use cases:**\n   * - Basic development debugging and execution flow visibility\n   * - Understanding agent decision-making and tool usage\n   * - Troubleshooting gadget invocations\n   *\n   * **Performance:** Minimal overhead. Console writes are synchronous but fast.\n   *\n   * @param options - Logging options\n   * @param options.verbose - Include full parameters and results. Default: false\n   * @returns Hook configuration that can be passed to .withHooks()\n   *\n   * @example\n   * ```typescript\n   * // Basic logging\n   * await LLMist.createAgent()\n   *   .withHooks(HookPresets.logging())\n   *   .ask(\"Calculate 15 * 23\");\n   * // Output: [LLM] Starting call (iteration 0)\n   * //         [GADGET] Executing Calculator\n   * //         [GADGET] Completed Calculator\n   * //         [LLM] Completed (tokens: 245)\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Verbose logging with full details\n   * await LLMist.createAgent()\n   *   .withHooks(HookPresets.logging({ verbose: true }))\n   *   .ask(\"Calculate 15 * 23\");\n   * // Output includes: parameters, results, and full responses\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Environment-based verbosity\n   * const isDev = process.env.NODE_ENV === 'development';\n   * .withHooks(HookPresets.logging({ verbose: isDev }))\n   * ```\n   *\n   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsloggingoptions | Full documentation}\n   */\n  static logging(options: LoggingOptions = {}): AgentHooks {\n    return {\n      observers: {\n        onLLMCallStart: async (ctx) => {\n          console.log(`[LLM] Starting call (iteration ${ctx.iteration})`);\n        },\n        onLLMCallComplete: async (ctx) => {\n          const tokens = ctx.usage?.totalTokens ?? \"unknown\";\n          console.log(`[LLM] Completed (tokens: ${tokens})`);\n          if (options.verbose && ctx.finalMessage) {\n            console.log(`[LLM] Response: ${ctx.finalMessage}`);\n          }\n        },\n        onGadgetExecutionStart: async (ctx) => {\n          console.log(`[GADGET] Executing ${ctx.gadgetName}`);\n          if (options.verbose) {\n            console.log(`[GADGET] Parameters:`, JSON.stringify(ctx.parameters, null, 2));\n          }\n        },\n        onGadgetExecutionComplete: async (ctx) => {\n          console.log(`[GADGET] Completed ${ctx.gadgetName}`);\n          if (options.verbose) {\n            const display = ctx.error ?? ctx.finalResult ?? \"(no result)\";\n            console.log(`[GADGET] Result: ${display}`);\n          }\n        },\n      },\n    };\n  }\n\n  /**\n   * Measures and logs execution time for LLM calls and gadgets.\n   *\n   * **Output:**\n   * - Duration in milliseconds with ⏱️ emoji for each operation\n   * - Separate timing for each LLM iteration\n   * - Separate timing for each gadget execution\n   *\n   * **Use cases:**\n   * - Performance profiling and optimization\n   * - Identifying slow operations (LLM calls vs gadget execution)\n   * - Monitoring response times in production\n   * - Capacity planning and SLA tracking\n   *\n   * **Performance:** Negligible overhead. Uses Date.now() for timing measurements.\n   *\n   * @returns Hook configuration that can be passed to .withHooks()\n   *\n   * @example\n   * ```typescript\n   * // Basic timing\n   * await LLMist.createAgent()\n   *   .withHooks(HookPresets.timing())\n   *   .withGadgets(Weather, Database)\n   *   .ask(\"What's the weather in NYC?\");\n   * // Output: ⏱️ LLM call took 1234ms\n   * //         ⏱️ Gadget Weather took 567ms\n   * //         ⏱️ LLM call took 890ms\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Combined with logging for full context\n   * .withHooks(HookPresets.merge(\n   *   HookPresets.logging(),\n   *   HookPresets.timing()\n   * ))\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Correlate performance with cost\n   * .withHooks(HookPresets.merge(\n   *   HookPresets.timing(),\n   *   HookPresets.tokenTracking()\n   * ))\n   * ```\n   *\n   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstiming | Full documentation}\n   */\n  static timing(): AgentHooks {\n    const timings = new Map<string, number>();\n\n    return {\n      observers: {\n        onLLMCallStart: async (ctx) => {\n          timings.set(`llm-${ctx.iteration}`, Date.now());\n        },\n        onLLMCallComplete: async (ctx) => {\n          const start = timings.get(`llm-${ctx.iteration}`);\n          if (start) {\n            const duration = Date.now() - start;\n            console.log(`⏱️  LLM call took ${duration}ms`);\n            timings.delete(`llm-${ctx.iteration}`);\n          }\n        },\n        onGadgetExecutionStart: async (ctx) => {\n          const key = `gadget-${ctx.gadgetName}-${Date.now()}`;\n          timings.set(key, Date.now());\n          // Store key for lookup in complete handler\n          (ctx as any)._timingKey = key;\n        },\n        onGadgetExecutionComplete: async (ctx) => {\n          const key = (ctx as any)._timingKey;\n          if (key) {\n            const start = timings.get(key);\n            if (start) {\n              const duration = Date.now() - start;\n              console.log(`⏱️  Gadget ${ctx.gadgetName} took ${duration}ms`);\n              timings.delete(key);\n            }\n          }\n        },\n      },\n    };\n  }\n\n  /**\n   * Tracks cumulative token usage across all LLM calls.\n   *\n   * **Output:**\n   * - Per-call token count with 📊 emoji\n   * - Cumulative total across all calls\n   * - Call count for average calculations\n   *\n   * **Use cases:**\n   * - Cost monitoring and budget tracking\n   * - Optimizing prompts to reduce token usage\n   * - Comparing token efficiency across different approaches\n   * - Real-time cost estimation\n   *\n   * **Performance:** Minimal overhead. Simple counter increments.\n   *\n   * **Note:** Token counts depend on the provider's response. Some providers\n   * may not include usage data, in which case counts won't be logged.\n   *\n   * @returns Hook configuration that can be passed to .withHooks()\n   *\n   * @example\n   * ```typescript\n   * // Basic token tracking\n   * await LLMist.createAgent()\n   *   .withHooks(HookPresets.tokenTracking())\n   *   .ask(\"Summarize this document...\");\n   * // Output: 📊 Tokens this call: 1,234\n   * //         📊 Total tokens: 1,234 (across 1 calls)\n   * //         📊 Tokens this call: 567\n   * //         📊 Total tokens: 1,801 (across 2 calls)\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Cost calculation with custom hook\n   * let totalTokens = 0;\n   * .withHooks(HookPresets.merge(\n   *   HookPresets.tokenTracking(),\n   *   {\n   *     observers: {\n   *       onLLMCallComplete: async (ctx) => {\n   *         totalTokens += ctx.usage?.totalTokens ?? 0;\n   *         const cost = (totalTokens / 1_000_000) * 3.0; // $3 per 1M tokens\n   *         console.log(`💰 Estimated cost: $${cost.toFixed(4)}`);\n   *       },\n   *     },\n   *   }\n   * ))\n   * ```\n   *\n   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetstokentracking | Full documentation}\n   */\n  static tokenTracking(): AgentHooks {\n    let totalTokens = 0;\n    let totalCalls = 0;\n\n    return {\n      observers: {\n        onLLMCallComplete: async (ctx) => {\n          totalCalls++;\n          if (ctx.usage?.totalTokens) {\n            totalTokens += ctx.usage.totalTokens;\n            console.log(`📊 Tokens this call: ${ctx.usage.totalTokens}`);\n            console.log(`📊 Total tokens: ${totalTokens} (across ${totalCalls} calls)`);\n          }\n        },\n      },\n    };\n  }\n\n  /**\n   * Logs detailed error information for debugging and troubleshooting.\n   *\n   * **Output:**\n   * - LLM errors with ❌ emoji, including model and recovery status\n   * - Gadget errors with full context (parameters, error message)\n   * - Separate logging for LLM and gadget failures\n   *\n   * **Use cases:**\n   * - Troubleshooting production issues\n   * - Understanding error patterns and frequency\n   * - Debugging error recovery behavior\n   * - Collecting error metrics for monitoring\n   *\n   * **Performance:** Minimal overhead. Only logs when errors occur.\n   *\n   * @returns Hook configuration that can be passed to .withHooks()\n   *\n   * @example\n   * ```typescript\n   * // Basic error logging\n   * await LLMist.createAgent()\n   *   .withHooks(HookPresets.errorLogging())\n   *   .withGadgets(Database)\n   *   .ask(\"Fetch user data\");\n   * // Output (on LLM error): ❌ LLM Error (iteration 1): Rate limit exceeded\n   * //                        Model: gpt-5-nano\n   * //                        Recovered: true\n   * // Output (on gadget error): ❌ Gadget Error: Database\n   * //                            Error: Connection timeout\n   * //                            Parameters: {...}\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Combine with monitoring for full context\n   * .withHooks(HookPresets.merge(\n   *   HookPresets.monitoring(),  // Includes errorLogging\n   *   customErrorAnalytics\n   * ))\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Error analytics collection\n   * const errors: any[] = [];\n   * .withHooks(HookPresets.merge(\n   *   HookPresets.errorLogging(),\n   *   {\n   *     observers: {\n   *       onLLMCallError: async (ctx) => {\n   *         errors.push({ type: 'llm', error: ctx.error, recovered: ctx.recovered });\n   *       },\n   *     },\n   *   }\n   * ))\n   * ```\n   *\n   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetserrorlogging | Full documentation}\n   */\n  static errorLogging(): AgentHooks {\n    return {\n      observers: {\n        onLLMCallError: async (ctx) => {\n          console.error(`❌ LLM Error (iteration ${ctx.iteration}):`, ctx.error.message);\n          console.error(`   Model: ${ctx.options.model}`);\n          console.error(`   Recovered: ${ctx.recovered}`);\n        },\n        onGadgetExecutionComplete: async (ctx) => {\n          if (ctx.error) {\n            console.error(`❌ Gadget Error: ${ctx.gadgetName}`);\n            console.error(`   Error: ${ctx.error}`);\n            console.error(`   Parameters:`, JSON.stringify(ctx.parameters, null, 2));\n          }\n        },\n      },\n    };\n  }\n\n  /**\n   * Returns empty hook configuration for clean output without any logging.\n   *\n   * **Output:**\n   * - None. Returns {} (empty object).\n   *\n   * **Use cases:**\n   * - Clean test output without console noise\n   * - Production environments where logging is handled externally\n   * - Baseline for custom hook development\n   * - Temporary disable of all hook output\n   *\n   * **Performance:** Zero overhead. No-op hook configuration.\n   *\n   * @returns Empty hook configuration\n   *\n   * @example\n   * ```typescript\n   * // Clean test output\n   * describe('Agent tests', () => {\n   *   it('should calculate correctly', async () => {\n   *     const result = await LLMist.createAgent()\n   *       .withHooks(HookPresets.silent()) // No console output\n   *       .withGadgets(Calculator)\n   *       .askAndCollect(\"What is 15 times 23?\");\n   *\n   *     expect(result).toContain(\"345\");\n   *   });\n   * });\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Conditional silence based on environment\n   * const isTesting = process.env.NODE_ENV === 'test';\n   * .withHooks(isTesting ? HookPresets.silent() : HookPresets.monitoring())\n   * ```\n   *\n   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetssilent | Full documentation}\n   */\n  static silent(): AgentHooks {\n    return {};\n  }\n\n  /**\n   * Combines multiple hook configurations into one.\n   *\n   * Merge allows you to compose preset and custom hooks for modular monitoring\n   * configurations. Understanding merge behavior is crucial for proper composition.\n   *\n   * **Merge behavior:**\n   * - **Observers:** Composed - all handlers run sequentially in order\n   * - **Interceptors:** Last one wins - only the last interceptor applies\n   * - **Controllers:** Last one wins - only the last controller applies\n   *\n   * **Why interceptors/controllers don't compose:**\n   * - Interceptors have different signatures per method, making composition impractical\n   * - Controllers return specific actions that can't be meaningfully combined\n   * - Only observers support composition because they're read-only and independent\n   *\n   * **Use cases:**\n   * - Combining multiple presets (logging + timing + tokens)\n   * - Adding custom hooks to presets\n   * - Building modular, reusable monitoring configurations\n   * - Environment-specific hook composition\n   *\n   * **Performance:** Minimal overhead for merging. Runtime performance depends on merged hooks.\n   *\n   * @param hookSets - Variable number of hook configurations to merge\n   * @returns Single merged hook configuration with composed/overridden handlers\n   *\n   * @example\n   * ```typescript\n   * // Combine multiple presets\n   * .withHooks(HookPresets.merge(\n   *   HookPresets.logging(),\n   *   HookPresets.timing(),\n   *   HookPresets.tokenTracking()\n   * ))\n   * // All observers from all three presets will run\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Add custom observer to preset (both run)\n   * .withHooks(HookPresets.merge(\n   *   HookPresets.timing(),\n   *   {\n   *     observers: {\n   *       onLLMCallComplete: async (ctx) => {\n   *         await saveMetrics({ tokens: ctx.usage?.totalTokens });\n   *       },\n   *     },\n   *   }\n   * ))\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Multiple interceptors (last wins!)\n   * .withHooks(HookPresets.merge(\n   *   {\n   *     interceptors: {\n   *       interceptTextChunk: (chunk) => chunk.toUpperCase(), // Ignored\n   *     },\n   *   },\n   *   {\n   *     interceptors: {\n   *       interceptTextChunk: (chunk) => chunk.toLowerCase(), // This wins\n   *     },\n   *   }\n   * ))\n   * // Result: text will be lowercase\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Modular environment-based configuration\n   * const baseHooks = HookPresets.errorLogging();\n   * const devHooks = HookPresets.merge(baseHooks, HookPresets.monitoring({ verbose: true }));\n   * const prodHooks = HookPresets.merge(baseHooks, HookPresets.tokenTracking());\n   *\n   * const hooks = process.env.NODE_ENV === 'production' ? prodHooks : devHooks;\n   * .withHooks(hooks)\n   * ```\n   *\n   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsmergehooksets | Full documentation}\n   */\n  static merge(...hookSets: AgentHooks[]): AgentHooks {\n    const merged: AgentHooks = {\n      observers: {},\n      interceptors: {},\n      controllers: {},\n    };\n\n    // Compose observers: run all handlers for the same event\n    for (const hooks of hookSets) {\n      if (hooks.observers) {\n        for (const [key, handler] of Object.entries(hooks.observers)) {\n          const typedKey = key as keyof typeof hooks.observers;\n          if (merged.observers![typedKey]) {\n            // Compose: run both existing and new handler\n            const existing = merged.observers![typedKey];\n            merged.observers![typedKey] = async (ctx: any) => {\n              await existing(ctx);\n              await handler(ctx);\n            };\n          } else {\n            merged.observers![typedKey] = handler as any;\n          }\n        }\n      }\n\n      // Interceptors: last one wins (complex signatures make composition impractical)\n      // Each interceptor has different parameters (chunk, message, parameters, etc.)\n      // so we can't meaningfully compose them like we do with observers\n      if (hooks.interceptors) {\n        Object.assign(merged.interceptors!, hooks.interceptors);\n      }\n\n      // Controllers: last one wins (can't meaningfully compose boolean returns)\n      if (hooks.controllers) {\n        Object.assign(merged.controllers!, hooks.controllers);\n      }\n    }\n\n    return merged;\n  }\n\n  /**\n   * Composite preset combining logging, timing, tokenTracking, and errorLogging.\n   *\n   * This is the recommended preset for development and initial production deployments,\n   * providing comprehensive observability with a single method call.\n   *\n   * **Includes:**\n   * - All output from `logging()` preset (with optional verbosity)\n   * - All output from `timing()` preset (execution times)\n   * - All output from `tokenTracking()` preset (token usage)\n   * - All output from `errorLogging()` preset (error details)\n   *\n   * **Output format:**\n   * - Event logging: [LLM]/[GADGET] messages\n   * - Timing: ⏱️ emoji with milliseconds\n   * - Tokens: 📊 emoji with per-call and cumulative counts\n   * - Errors: ❌ emoji with full error details\n   *\n   * **Use cases:**\n   * - Full observability during development\n   * - Comprehensive monitoring in production\n   * - One-liner for complete agent visibility\n   * - Troubleshooting and debugging with full context\n   *\n   * **Performance:** Combined overhead of all four presets, but still minimal in practice.\n   *\n   * @param options - Monitoring options\n   * @param options.verbose - Passed to logging() preset for detailed output. Default: false\n   * @returns Merged hook configuration combining all monitoring presets\n   *\n   * @example\n   * ```typescript\n   * // Basic monitoring (recommended for development)\n   * await LLMist.createAgent()\n   *   .withHooks(HookPresets.monitoring())\n   *   .withGadgets(Calculator, Weather)\n   *   .ask(\"What is 15 times 23, and what's the weather in NYC?\");\n   * // Output: All events, timing, tokens, and errors in one place\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Verbose monitoring with full details\n   * await LLMist.createAgent()\n   *   .withHooks(HookPresets.monitoring({ verbose: true }))\n   *   .ask(\"Your prompt\");\n   * // Output includes: parameters, results, and complete responses\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Environment-based monitoring\n   * const isDev = process.env.NODE_ENV === 'development';\n   * .withHooks(HookPresets.monitoring({ verbose: isDev }))\n   * ```\n   *\n   * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetsmonitoringoptions | Full documentation}\n   */\n  static monitoring(options: LoggingOptions = {}): AgentHooks {\n    return HookPresets.merge(\n      HookPresets.logging(options),\n      HookPresets.timing(),\n      HookPresets.tokenTracking(),\n      HookPresets.errorLogging(),\n    );\n  }\n}\n","/**\n * Agent module - Composable, single-responsibility architecture for LLM agents.\n * This module provides a cleaner alternative to the monolithic AgentLoop.\n */\n\nexport type { AgentOptions } from \"./agent.js\";\nexport { ConversationManager } from \"./conversation-manager.js\";\n// New clean hooks system\nexport type {\n  AfterGadgetExecutionAction,\n  AfterGadgetExecutionControllerContext,\n  AfterLLMCallAction,\n  AfterLLMCallControllerContext,\n  AfterLLMErrorAction,\n  AgentHooks,\n  BeforeGadgetExecutionAction,\n  BeforeLLMCallAction,\n  // Interceptor contexts\n  ChunkInterceptorContext,\n  Controllers,\n  GadgetExecutionControllerContext,\n  GadgetParameterInterceptorContext,\n  GadgetResultInterceptorContext,\n  Interceptors,\n  // Controller contexts and actions\n  LLMCallControllerContext,\n  LLMErrorControllerContext,\n  MessageInterceptorContext,\n  ObserveChunkContext,\n  ObserveGadgetCompleteContext,\n  ObserveGadgetStartContext,\n  // Observer contexts\n  ObserveLLMCallContext,\n  ObserveLLMCompleteContext,\n  ObserveLLMErrorContext,\n  Observers,\n} from \"./hooks.js\";\nexport type { IConversationManager } from \"./interfaces.js\";\n\n// StreamProcessor for advanced use cases\nexport {\n  type StreamProcessingResult,\n  StreamProcessor,\n  type StreamProcessorOptions,\n} from \"./stream-processor.js\";\n","/**\n * Type-safe gadget factory with automatic parameter inference.\n *\n * Gadget eliminates the need for manual type assertions\n * by automatically inferring parameter types from the Zod schema.\n *\n * @example\n * ```typescript\n * class Calculator extends Gadget({\n *   description: \"Performs arithmetic operations\",\n *   schema: z.object({\n *     operation: z.enum([\"add\", \"subtract\"]),\n *     a: z.number(),\n *     b: z.number(),\n *   }),\n * }) {\n *   // ✨ params is automatically typed!\n *   execute(params: this['params']): string {\n *     const { operation, a, b } = params; // All typed!\n *     return operation === \"add\" ? String(a + b) : String(a - b);\n *   }\n * }\n * ```\n */\n\nimport type { ZodType } from \"zod\";\nimport { BaseGadget } from \"./gadget.js\";\n\n/**\n * Infer the TypeScript type from a Zod schema.\n */\ntype InferSchema<T> = T extends ZodType<infer U> ? U : never;\n\n/**\n * Configuration for creating a typed gadget.\n */\nexport interface GadgetConfig<TSchema extends ZodType> {\n  /** Human-readable description of what the gadget does */\n  description: string;\n\n  /** Zod schema for parameter validation */\n  schema: TSchema;\n\n  /** Optional custom name (defaults to class name) */\n  name?: string;\n\n  /** Optional timeout in milliseconds */\n  timeoutMs?: number;\n}\n\n/**\n * Factory function to create a typed gadget base class.\n *\n * The returned class automatically infers parameter types from the Zod schema,\n * eliminating the need for manual type assertions in the execute method.\n *\n * @param config - Configuration with description and schema\n * @returns Base class to extend with typed execute method\n *\n * @example\n * ```typescript\n * import { z } from 'zod';\n * import { Gadget } from 'llmist';\n *\n * class Calculator extends Gadget({\n *   description: \"Performs arithmetic operations\",\n *   schema: z.object({\n *     operation: z.enum([\"add\", \"subtract\", \"multiply\", \"divide\"]),\n *     a: z.number().describe(\"First number\"),\n *     b: z.number().describe(\"Second number\"),\n *   }),\n * }) {\n *   execute(params: this['params']): string {\n *     // params is automatically typed as:\n *     // { operation: \"add\" | \"subtract\" | \"multiply\" | \"divide\"; a: number; b: number }\n *     const { operation, a, b } = params;\n *\n *     switch (operation) {\n *       case \"add\": return String(a + b);\n *       case \"subtract\": return String(a - b);\n *       case \"multiply\": return String(a * b);\n *       case \"divide\": return String(a / b);\n *     }\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * // With async execution\n * class WeatherGadget extends Gadget({\n *   description: \"Fetches weather for a city\",\n *   schema: z.object({\n *     city: z.string().min(1).describe(\"City name\"),\n *   }),\n *   timeoutMs: 10000,\n * }) {\n *   async execute(params: this['params']): Promise<string> {\n *     const { city } = params; // Automatically typed as { city: string }\n *     const weather = await fetchWeather(city);\n *     return `Weather in ${city}: ${weather}`;\n *   }\n * }\n * ```\n */\nexport function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>) {\n  abstract class GadgetBase extends BaseGadget {\n    description = config.description;\n    parameterSchema = config.schema;\n    name = config.name;\n    timeoutMs = config.timeoutMs;\n\n    /**\n     * Type helper property for accessing inferred parameter type.\n     * This is used in the execute method signature: `execute(params: this['params'])`\n     *\n     * Note: This is just for type inference - the actual params in execute()\n     * will be Record<string, unknown> which you can safely cast to this['params']\n     */\n    readonly params!: InferSchema<TSchema>;\n\n    /**\n     * Execute the gadget. Subclasses should cast params to this['params'].\n     *\n     * @param params - Validated parameters from the LLM\n     * @returns Result as a string (or Promise<string> for async gadgets)\n     *\n     * @example\n     * ```typescript\n     * execute(params: Record<string, unknown>): string {\n     *   const typed = params as this['params'];\n     *   // Now 'typed' is fully typed!\n     *   return String(typed.a + typed.b);\n     * }\n     * ```\n     */\n    abstract execute(params: Record<string, unknown>): string | Promise<string>;\n  }\n\n  return GadgetBase as {\n    new (): GadgetBase & { params: InferSchema<TSchema> };\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/{mock-stream-D4erlo7B.d.cts → mock-stream-C2sBQlvc.d.cts}

@@ -108,7 +108,6 @@ declare class StreamParser {
     private readonly startPrefix;
     private readonly endPrefix;
     private readonly parameterFormat;
-    private invocationCounter;
     constructor(options?: StreamParserOptions);
     private takeTextUntil;
     /**
@@ -291,7 +290,7 @@ declare class LLMMessageBuilder {
         startPrefix?: string;
         endPrefix?: string;
     }): this;
-    private buildGadgetsXmlSection;
+    private buildGadgetsSection;
     private buildUsageSection;
     private buildExamplesSection;
     private buildRulesSection;