llmist 0.1.1

package/dist/mock-stream-D4erlo7B.d.ts

@@ -0,0 +1,2602 @@
+import { Logger, ILogObj } from 'tslog';
+import { ZodTypeAny } from 'zod';
+
+interface GadgetExecutionResult {
+    gadgetName: string;
+    invocationId: string;
+    parameters: Record<string, unknown>;
+    result?: string;
+    error?: string;
+    executionTimeMs: number;
+    breaksLoop?: boolean;
+}
+interface ParsedGadgetCall {
+    gadgetName: string;
+    invocationId: string;
+    parametersYaml: string;
+    parameters?: Record<string, unknown>;
+    parseError?: string;
+}
+type StreamEvent = {
+    type: "text";
+    content: string;
+} | {
+    type: "gadget_call";
+    call: ParsedGadgetCall;
+} | {
+    type: "gadget_result";
+    result: GadgetExecutionResult;
+} | {
+    type: "human_input_required";
+    question: string;
+    gadgetName: string;
+    invocationId: string;
+};
+
+type TextOnlyHandler = TextOnlyStrategy | TextOnlyGadgetConfig | TextOnlyCustomHandler;
+/**
+ * Simple strategies for common cases
+ * - 'terminate': End the loop (default behavior)
+ * - 'acknowledge': Continue to next iteration
+ * - 'wait_for_input': Request human input
+ */
+type TextOnlyStrategy = "terminate" | "acknowledge" | "wait_for_input";
+/**
+ * Configuration for triggering a gadget when receiving text-only response
+ */
+interface TextOnlyGadgetConfig {
+    type: "gadget";
+    name: string;
+    /**
+     * Optional function to map text to gadget parameters.
+     * If not provided, text will be passed as { text: string }
+     */
+    parameterMapping?: (text: string) => Record<string, unknown>;
+}
+/**
+ * Custom handler for complex text-only response scenarios
+ */
+interface TextOnlyCustomHandler {
+    type: "custom";
+    handler: (context: TextOnlyContext) => Promise<TextOnlyAction> | TextOnlyAction;
+}
+/**
+ * Context provided to custom text-only handlers
+ */
+interface TextOnlyContext {
+    /** The complete text response from the LLM */
+    text: string;
+    /** Current iteration number */
+    iteration: number;
+    /** Full conversation history */
+    conversation: LLMMessage[];
+    /** Logger instance */
+    logger: Logger<ILogObj>;
+}
+/**
+ * Actions that can be returned by text-only handlers
+ */
+type TextOnlyAction = {
+    action: "continue";
+} | {
+    action: "terminate";
+} | {
+    action: "wait_for_input";
+    question?: string;
+} | {
+    action: "trigger_gadget";
+    name: string;
+    parameters: Record<string, unknown>;
+};
+
+type ParameterFormat = "json" | "yaml" | "auto";
+interface StreamParserOptions {
+    startPrefix?: string;
+    endPrefix?: string;
+    /**
+     * Format for parsing gadget parameters.
+     * - 'json': Parse as JSON (more robust, recommended for complex nested data)
+     * - 'yaml': Parse as YAML (backward compatible)
+     * - 'auto': Try JSON first, fall back to YAML
+     * @default 'json'
+     */
+    parameterFormat?: ParameterFormat;
+}
+declare class StreamParser {
+    private buffer;
+    private lastReportedTextLength;
+    private readonly startPrefix;
+    private readonly endPrefix;
+    private readonly parameterFormat;
+    private invocationCounter;
+    constructor(options?: StreamParserOptions);
+    private takeTextUntil;
+    /**
+     * Parse parameter string according to configured format
+     */
+    private parseParameters;
+    feed(chunk: string): Generator<StreamEvent>;
+    finalize(): Generator<StreamEvent>;
+    reset(): void;
+}
+
+/**
+ * Internal base class for gadgets. Most users should use the `Gadget` class
+ * (formerly TypedGadget) or `createGadget()` function instead, as they provide
+ * better type safety and simpler APIs.
+ *
+ * @internal
+ */
+declare abstract class BaseGadget {
+    /**
+     * The name of the gadget. Used for identification when LLM calls it.
+     * If not provided, defaults to the class name.
+     */
+    name?: string;
+    /**
+     * Human-readable description of what the gadget does.
+     */
+    abstract description: string;
+    /**
+     * Optional Zod schema describing the expected input payload. When provided,
+     * it will be validated before execution and transformed into a JSON Schema
+     * representation that is surfaced to the LLM as part of the instructions.
+     */
+    parameterSchema?: ZodTypeAny;
+    /**
+     * Optional timeout in milliseconds for gadget execution.
+     * If execution exceeds this timeout, a TimeoutException will be thrown.
+     * If not set, the global defaultGadgetTimeoutMs from runtime options will be used.
+     * Set to 0 or undefined to disable timeout for this gadget.
+     */
+    timeoutMs?: number;
+    /**
+     * Execute the gadget with the given parameters.
+     * Can be synchronous or asynchronous.
+     *
+     * @param params - Parameters passed from the LLM
+     * @returns Result as a string
+     */
+    abstract execute(params: Record<string, unknown>): string | Promise<string>;
+    /**
+     * Auto-generated instruction text for the LLM.
+     * Combines name, description, and parameter schema into a formatted instruction.
+     * @deprecated Use getInstruction(format) instead for format-specific schemas
+     */
+    get instruction(): string;
+    /**
+     * Generate instruction text for the LLM with format-specific schema.
+     * Combines name, description, and parameter schema into a formatted instruction.
+     *
+     * @param format - Format for the schema representation ('json' | 'yaml' | 'auto')
+     * @returns Formatted instruction string
+     */
+    getInstruction(format?: ParameterFormat): string;
+}
+
+/**
+ * Context provided to prompt template functions for rendering dynamic content.
+ */
+interface PromptContext {
+    /** The parameter format being used (json or yaml) */
+    parameterFormat: ParameterFormat;
+    /** Custom gadget start prefix */
+    startPrefix: string;
+    /** Custom gadget end prefix */
+    endPrefix: string;
+    /** Number of gadgets being registered */
+    gadgetCount: number;
+    /** Names of all gadgets */
+    gadgetNames: string[];
+}
+/**
+ * Template that can be either a static string or a function that renders based on context.
+ */
+type PromptTemplate = string | ((context: PromptContext) => string);
+/**
+ * Configuration for customizing all prompts used internally by llmist.
+ *
+ * Each field can be either a string (static text) or a function that receives
+ * context and returns a string (for dynamic content).
+ *
+ * @example
+ * ```typescript
+ * const customConfig: PromptConfig = {
+ *   mainInstruction: "USE ONLY THE GADGET MARKERS BELOW:",
+ *   criticalUsage: "Important: Follow the exact format shown.",
+ *   rules: (ctx) => [
+ *     "Always use the markers to invoke gadgets",
+ *     "Never use function calling",
+ *     `You have ${ctx.gadgetCount} gadgets available`
+ *   ]
+ * };
+ * ```
+ */
+interface PromptConfig {
+    /**
+     * Main instruction block that appears at the start of the gadget system prompt.
+     * Default emphasizes using text markers instead of function calling.
+     */
+    mainInstruction?: PromptTemplate;
+    /**
+     * Critical usage instruction that appears in the usage section.
+     * Default emphasizes the exact format requirement.
+     */
+    criticalUsage?: PromptTemplate;
+    /**
+     * Format description for YAML parameter format.
+     * Default: "Parameters in YAML format (one per line)"
+     */
+    formatDescriptionYaml?: PromptTemplate;
+    /**
+     * Format description for JSON parameter format.
+     * Default: "Parameters in JSON format (valid JSON object)"
+     */
+    formatDescriptionJson?: PromptTemplate;
+    /**
+     * Rules that appear in the rules section.
+     * Can be an array of strings or a function that returns an array.
+     * Default includes 6 rules about not using function calling.
+     */
+    rules?: PromptTemplate | string[] | ((context: PromptContext) => string[]);
+    /**
+     * Schema label for JSON format.
+     * Default: "\n\nInput Schema (JSON):"
+     */
+    schemaLabelJson?: PromptTemplate;
+    /**
+     * Schema label for YAML format.
+     * Default: "\n\nInput Schema (YAML):"
+     */
+    schemaLabelYaml?: PromptTemplate;
+    /**
+     * Custom examples to show in the examples section.
+     * If provided, replaces the default examples entirely.
+     * Should be a function that returns formatted example strings.
+     */
+    customExamples?: (context: PromptContext) => string;
+}
+/**
+ * Default prompt templates used by llmist.
+ * These match the original hardcoded strings.
+ */
+declare const DEFAULT_PROMPTS: Required<Omit<PromptConfig, "rules" | "customExamples"> & {
+    rules: (context: PromptContext) => string[];
+    customExamples: null;
+}>;
+/**
+ * Resolve a prompt template to a string using the given context.
+ */
+declare function resolvePromptTemplate(template: PromptTemplate | undefined, defaultValue: PromptTemplate, context: PromptContext): string;
+/**
+ * Resolve rules template to an array of strings.
+ */
+declare function resolveRulesTemplate(rules: PromptConfig["rules"] | undefined, context: PromptContext): string[];
+
+type LLMRole = "system" | "user" | "assistant";
+interface LLMMessage {
+    role: LLMRole;
+    content: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class LLMMessageBuilder {
+    private readonly messages;
+    private startPrefix;
+    private endPrefix;
+    private promptConfig;
+    constructor(promptConfig?: PromptConfig);
+    addSystem(content: string, metadata?: Record<string, unknown>): this;
+    addGadgets(gadgets: BaseGadget[], parameterFormat?: ParameterFormat, options?: {
+        startPrefix?: string;
+        endPrefix?: string;
+    }): this;
+    private buildGadgetsXmlSection;
+    private buildUsageSection;
+    private buildExamplesSection;
+    private buildRulesSection;
+    addUser(content: string, metadata?: Record<string, unknown>): this;
+    addAssistant(content: string, metadata?: Record<string, unknown>): this;
+    addGadgetCall(gadget: string, parameters: Record<string, unknown>, result: string, parameterFormat?: ParameterFormat): this;
+    private formatParameters;
+    build(): LLMMessage[];
+}
+
+/**
+ * Model Catalog Types
+ *
+ * Type definitions for LLM model specifications including
+ * context windows, pricing, features, and capabilities.
+ */
+interface ModelPricing {
+    /** Price per 1 million input tokens in USD */
+    input: number;
+    /** Price per 1 million output tokens in USD */
+    output: number;
+    /** Price per 1 million cached input tokens in USD (if supported) */
+    cachedInput?: number;
+}
+interface ModelFeatures {
+    /** Supports streaming responses */
+    streaming: boolean;
+    /** Supports function/tool calling */
+    functionCalling: boolean;
+    /** Supports vision/image input */
+    vision: boolean;
+    /** Supports extended thinking/reasoning */
+    reasoning?: boolean;
+    /** Supports structured outputs */
+    structuredOutputs?: boolean;
+    /** Supports fine-tuning */
+    fineTuning?: boolean;
+}
+interface ModelSpec {
+    /** Provider identifier (e.g., 'openai', 'anthropic', 'gemini') */
+    provider: string;
+    /** Full model identifier used in API calls */
+    modelId: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Maximum context window size in tokens */
+    contextWindow: number;
+    /** Maximum output tokens per request */
+    maxOutputTokens: number;
+    /** Pricing per 1M tokens */
+    pricing: ModelPricing;
+    /** Training data knowledge cutoff date (YYYY-MM-DD or description) */
+    knowledgeCutoff: string;
+    /** Supported features and capabilities */
+    features: ModelFeatures;
+    /** Additional metadata */
+    metadata?: {
+        /** Model family/series */
+        family?: string;
+        /** Release date */
+        releaseDate?: string;
+        /** Deprecation date if applicable */
+        deprecationDate?: string;
+        /** Notes or special information */
+        notes?: string;
+        /** Whether manual temperature configuration is supported (defaults to true) */
+        supportsTemperature?: boolean;
+    };
+}
+interface ModelLimits {
+    contextWindow: number;
+    maxOutputTokens: number;
+}
+interface CostEstimate {
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+    currency: "USD";
+}
+
+interface LLMGenerationOptions {
+    model: string;
+    messages: LLMMessage[];
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stopSequences?: string[];
+    responseFormat?: "text";
+    metadata?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+interface LLMStreamChunk {
+    text: string;
+    /**
+     * Indicates that the provider has finished producing output and includes the reason if available.
+     */
+    finishReason?: string | null;
+    /**
+     * Token usage information, typically available in the final chunk when the stream completes.
+     */
+    usage?: TokenUsage;
+    /**
+     * Provider specific payload emitted at the same time as the text chunk. This is useful for debugging and tests.
+     */
+    rawEvent?: unknown;
+}
+interface LLMStream extends AsyncIterable<LLMStreamChunk> {
+}
+type ProviderIdentifier = string;
+interface ModelDescriptor {
+    provider: string;
+    name: string;
+}
+declare class ModelIdentifierParser {
+    private readonly defaultProvider;
+    constructor(defaultProvider?: string);
+    parse(identifier: string): ModelDescriptor;
+}
+
+interface ProviderAdapter {
+    readonly providerId: string;
+    /**
+     * Optional priority for adapter resolution.
+     * Higher numbers = higher priority (checked first).
+     *
+     * When multiple adapters support the same model descriptor, the adapter
+     * with the highest priority is selected. Adapters with equal priority
+     * maintain their registration order (stable sort).
+     *
+     * Default: 0 (normal priority)
+     * Mock adapters use: 100 (high priority)
+     *
+     * @default 0
+     */
+    readonly priority?: number;
+    supports(model: ModelDescriptor): boolean;
+    stream(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec?: ModelSpec): LLMStream;
+    /**
+     * Optionally provide model specifications for this provider.
+     * This allows the model registry to discover available models and their capabilities.
+     */
+    getModelSpecs?(): ModelSpec[];
+    /**
+     * Count tokens in messages before making an API call.
+     * Uses provider-specific native token counting methods.
+     * @param messages - Array of messages to count tokens for
+     * @param descriptor - Model descriptor
+     * @param spec - Optional model specification
+     * @returns Promise resolving to the number of input tokens
+     */
+    countTokens?(messages: LLMMessage[], descriptor: ModelDescriptor, spec?: ModelSpec): Promise<number>;
+}
+
+/**
+ * Model Registry
+ *
+ * Centralized registry for querying LLM model specifications,
+ * validating configurations, and estimating costs.
+ *
+ * Model data is provided by ProviderAdapter implementations and
+ * automatically populated when providers are registered.
+ */
+
+declare class ModelRegistry {
+    private modelSpecs;
+    private providerMap;
+    /**
+     * Register a provider and collect its model specifications
+     */
+    registerProvider(provider: ProviderAdapter): void;
+    /**
+     * Register a custom model specification at runtime
+     *
+     * Use this to add models that aren't in the built-in catalog, such as:
+     * - Fine-tuned models with custom pricing
+     * - New models not yet supported by llmist
+     * - Custom deployments with different configurations
+     *
+     * @param spec - Complete model specification
+     * @throws {Error} If spec is missing required fields
+     *
+     * @example
+     * ```ts
+     * client.modelRegistry.registerModel({
+     *   provider: "openai",
+     *   modelId: "ft:gpt-4o-2024-08-06:my-org:custom:abc123",
+     *   displayName: "My Fine-tuned GPT-4o",
+     *   contextWindow: 128_000,
+     *   maxOutputTokens: 16_384,
+     *   pricing: { input: 7.5, output: 30.0 },
+     *   knowledgeCutoff: "2024-08",
+     *   features: { streaming: true, functionCalling: true, vision: true }
+     * });
+     * ```
+     */
+    registerModel(spec: ModelSpec): void;
+    /**
+     * Register multiple custom model specifications at once
+     *
+     * @param specs - Array of complete model specifications
+     *
+     * @example
+     * ```ts
+     * client.modelRegistry.registerModels([
+     *   { provider: "openai", modelId: "gpt-5", ... },
+     *   { provider: "openai", modelId: "gpt-5-mini", ... }
+     * ]);
+     * ```
+     */
+    registerModels(specs: ModelSpec[]): void;
+    /**
+     * Get model specification by model ID
+     * @param modelId - Full model identifier (e.g., 'gpt-5', 'claude-sonnet-4-5-20250929')
+     * @returns ModelSpec if found, undefined otherwise
+     */
+    getModelSpec(modelId: string): ModelSpec | undefined;
+    /**
+     * List all models, optionally filtered by provider
+     * @param providerId - Optional provider ID to filter by (e.g., 'openai', 'anthropic')
+     * @returns Array of ModelSpec objects
+     */
+    listModels(providerId?: string): ModelSpec[];
+    /**
+     * Get context window and output limits for a model
+     * @param modelId - Full model identifier
+     * @returns ModelLimits if model found, undefined otherwise
+     */
+    getModelLimits(modelId: string): ModelLimits | undefined;
+    /**
+     * Estimate API cost for a given model and token usage
+     * @param modelId - Full model identifier
+     * @param inputTokens - Number of input tokens
+     * @param outputTokens - Number of output tokens
+     * @param useCachedInput - Whether to use cached input pricing (if supported by provider)
+     * @returns CostEstimate if model found, undefined otherwise
+     */
+    estimateCost(modelId: string, inputTokens: number, outputTokens: number, useCachedInput?: boolean): CostEstimate | undefined;
+    /**
+     * Validate that requested token count fits within model limits
+     * @param modelId - Full model identifier
+     * @param requestedTokens - Total tokens requested (input + output)
+     * @returns true if valid, false if model not found or exceeds limits
+     */
+    validateModelConfig(modelId: string, requestedTokens: number): boolean;
+    /**
+     * Check if a model supports a specific feature
+     * @param modelId - Full model identifier
+     * @param feature - Feature to check ('streaming', 'functionCalling', 'vision', etc.)
+     * @returns true if model supports feature, false otherwise
+     */
+    supportsFeature(modelId: string, feature: keyof ModelSpec["features"]): boolean;
+    /**
+     * Get all models that support a specific feature
+     * @param feature - Feature to filter by
+     * @param providerId - Optional provider ID to filter by
+     * @returns Array of ModelSpec objects that support the feature
+     */
+    getModelsByFeature(feature: keyof ModelSpec["features"], providerId?: string): ModelSpec[];
+    /**
+     * Get the most cost-effective model for a given provider and token budget
+     * @param inputTokens - Expected input tokens
+     * @param outputTokens - Expected output tokens
+     * @param providerId - Optional provider ID to filter by
+     * @returns ModelSpec with lowest total cost, or undefined if no models found
+     */
+    getCheapestModel(inputTokens: number, outputTokens: number, providerId?: string): ModelSpec | undefined;
+}
+
+/**
+ * Quick execution methods for simple use cases.
+ *
+ * These methods provide convenient shortcuts for common operations
+ * without requiring full agent setup.
+ *
+ * @example
+ * ```typescript
+ * // Quick completion
+ * const answer = await llmist.complete("What is 2+2?");
+ *
+ * // Quick streaming
+ * for await (const chunk of llmist.stream("Tell me a story")) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+
+/**
+ * Options for quick execution methods.
+ */
+interface QuickOptions {
+    /** Model to use (supports aliases like "gpt4", "sonnet", "flash") */
+    model?: string;
+    /** Temperature (0-1) */
+    temperature?: number;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Max tokens to generate */
+    maxTokens?: number;
+}
+/**
+ * Quick completion - returns final text response.
+ *
+ * @param client - LLMist client instance
+ * @param prompt - User prompt
+ * @param options - Optional configuration
+ * @returns Complete text response
+ *
+ * @example
+ * ```typescript
+ * const client = new LLMist();
+ * const answer = await complete(client, "What is 2+2?");
+ * console.log(answer); // "4" or "2+2 equals 4"
+ * ```
+ */
+declare function complete(client: LLMist, prompt: string, options?: QuickOptions): Promise<string>;
+/**
+ * Quick streaming - returns async generator of text chunks.
+ *
+ * @param client - LLMist client instance
+ * @param prompt - User prompt
+ * @param options - Optional configuration
+ * @returns Async generator yielding text chunks
+ *
+ * @example
+ * ```typescript
+ * const client = new LLMist();
+ *
+ * for await (const chunk of stream(client, "Tell me a story")) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+declare function stream(client: LLMist, prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+
+interface LLMistOptions {
+    /**
+     * Provider adapters to register manually.
+     */
+    adapters?: ProviderAdapter[];
+    /**
+     * Default provider prefix applied when a model identifier omits it.
+     */
+    defaultProvider?: string;
+    /**
+     * Automatically discover built-in providers based on environment configuration.
+     * Enabled by default.
+     */
+    autoDiscoverProviders?: boolean;
+    /**
+     * Custom model specifications to register at initialization.
+     * Use this to define models not in the built-in catalog, such as:
+     * - Fine-tuned models with custom pricing
+     * - New models not yet supported by llmist
+     * - Custom deployments with different configurations
+     *
+     * @example
+     * ```ts
+     * new LLMist({
+     *   customModels: [{
+     *     provider: "openai",
+     *     modelId: "ft:gpt-4o-2024-08-06:my-org:custom:abc123",
+     *     displayName: "My Fine-tuned GPT-4o",
+     *     contextWindow: 128_000,
+     *     maxOutputTokens: 16_384,
+     *     pricing: { input: 7.5, output: 30.0 },
+     *     knowledgeCutoff: "2024-08",
+     *     features: { streaming: true, functionCalling: true, vision: true }
+     *   }]
+     * });
+     * ```
+     */
+    customModels?: ModelSpec[];
+}
+declare class LLMist {
+    private readonly parser;
+    readonly modelRegistry: ModelRegistry;
+    private readonly adapters;
+    constructor();
+    constructor(adapters: ProviderAdapter[]);
+    constructor(adapters: ProviderAdapter[], defaultProvider: string);
+    constructor(options: LLMistOptions);
+    stream(options: LLMGenerationOptions): LLMStream;
+    /**
+     * Count tokens in messages for a given model.
+     *
+     * Uses provider-specific token counting methods for accurate estimation:
+     * - OpenAI: tiktoken library with model-specific encodings
+     * - Anthropic: Native messages.countTokens() API
+     * - Gemini: SDK's countTokens() method
+     *
+     * Falls back to character-based estimation (4 chars/token) if the provider
+     * doesn't support native token counting or if counting fails.
+     *
+     * This is useful for:
+     * - Pre-request cost estimation
+     * - Context window management
+     * - Request batching optimization
+     *
+     * @param model - Model identifier (e.g., "openai:gpt-4", "anthropic:claude-3-5-sonnet-20241022")
+     * @param messages - Array of messages to count tokens for
+     * @returns Promise resolving to the estimated input token count
+     *
+     * @example
+     * ```typescript
+     * const client = new LLMist();
+     * const messages = [
+     *   { role: 'system', content: 'You are a helpful assistant.' },
+     *   { role: 'user', content: 'Hello!' }
+     * ];
+     *
+     * const tokenCount = await client.countTokens('openai:gpt-4', messages);
+     * console.log(`Estimated tokens: ${tokenCount}`);
+     * ```
+     */
+    countTokens(model: string, messages: LLMMessage[]): Promise<number>;
+    private resolveAdapter;
+    /**
+     * Quick completion - returns final text response.
+     * Convenient for simple queries without needing agent setup.
+     *
+     * @param prompt - User prompt
+     * @param options - Optional configuration
+     * @returns Complete text response
+     *
+     * @example
+     * ```typescript
+     * const answer = await LLMist.complete("What is 2+2?");
+     * console.log(answer); // "4" or "2+2 equals 4"
+     *
+     * const answer = await LLMist.complete("Tell me a joke", {
+     *   model: "sonnet",
+     *   temperature: 0.9
+     * });
+     * ```
+     */
+    static complete(prompt: string, options?: QuickOptions): Promise<string>;
+    /**
+     * Quick streaming - returns async generator of text chunks.
+     * Convenient for streaming responses without needing agent setup.
+     *
+     * @param prompt - User prompt
+     * @param options - Optional configuration
+     * @returns Async generator yielding text chunks
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of LLMist.stream("Tell me a story")) {
+     *   process.stdout.write(chunk);
+     * }
+     *
+     * // With options
+     * for await (const chunk of LLMist.stream("Generate code", {
+     *   model: "gpt4",
+     *   systemPrompt: "You are a coding assistant"
+     * })) {
+     *   process.stdout.write(chunk);
+     * }
+     * ```
+     */
+    static stream(prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+    /**
+     * Instance method: Quick completion using this client instance.
+     *
+     * @param prompt - User prompt
+     * @param options - Optional configuration
+     * @returns Complete text response
+     */
+    complete(prompt: string, options?: QuickOptions): Promise<string>;
+    /**
+     * Instance method: Quick streaming using this client instance.
+     *
+     * @param prompt - User prompt
+     * @param options - Optional configuration
+     * @returns Async generator yielding text chunks
+     */
+    streamText(prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+    /**
+     * Create a fluent agent builder.
+     * Provides a chainable API for configuring and creating agents.
+     *
+     * @returns AgentBuilder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const agent = LLMist.createAgent()
+     *   .withModel("sonnet")
+     *   .withSystem("You are a helpful assistant")
+     *   .withGadgets(Calculator, Weather)
+     *   .ask("What's the weather in Paris?");
+     *
+     * for await (const event of agent.run()) {
+     *   // handle events
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Quick one-liner for simple queries
+     * const answer = await LLMist.createAgent()
+     *   .withModel("gpt4-mini")
+     *   .askAndCollect("What is 2+2?");
+     * ```
+     */
+    static createAgent(): AgentBuilder;
+    /**
+     * Create agent builder with this client instance.
+     * Useful when you want to reuse a configured client.
+     *
+     * @returns AgentBuilder instance using this client
+     *
+     * @example
+     * ```typescript
+     * const client = new LLMist({ ... });
+     *
+     * const agent = client.createAgent()
+     *   .withModel("sonnet")
+     *   .ask("Hello");
+     * ```
+     */
+    createAgent(): AgentBuilder;
+}
+
+type GadgetClass = new (...args: unknown[]) => BaseGadget;
+type GadgetOrClass = BaseGadget | GadgetClass;
+declare class GadgetRegistry {
+    private readonly gadgets;
+    /**
+     * Creates a registry from an array of gadget classes or instances,
+     * or an object mapping names to gadgets.
+     *
+     * @param gadgets - Array of gadgets/classes or object with custom names
+     * @returns New GadgetRegistry with all gadgets registered
+     *
+     * @example
+     * ```typescript
+     * // From array of classes
+     * const registry = GadgetRegistry.from([Calculator, Weather]);
+     *
+     * // From array of instances
+     * const registry = GadgetRegistry.from([new Calculator(), new Weather()]);
+     *
+     * // From object with custom names
+     * const registry = GadgetRegistry.from({
+     *   calc: Calculator,
+     *   weather: new Weather({ apiKey: "..." })
+     * });
+     * ```
+     */
+    static from(gadgets: GadgetOrClass[] | Record<string, GadgetOrClass>): GadgetRegistry;
+    /**
+     * Registers multiple gadgets at once from an array.
+     *
+     * @param gadgets - Array of gadget instances or classes
+     * @returns This registry for chaining
+     *
+     * @example
+     * ```typescript
+     * registry.registerMany([Calculator, Weather, Email]);
+     * registry.registerMany([new Calculator(), new Weather()]);
+     * ```
+     */
+    registerMany(gadgets: GadgetOrClass[]): this;
+    register(name: string, gadget: BaseGadget): void;
+    registerByClass(gadget: BaseGadget): void;
+    get(name: string): BaseGadget | undefined;
+    has(name: string): boolean;
+    getNames(): string[];
+    getAll(): BaseGadget[];
+    unregister(name: string): boolean;
+    clear(): void;
+}
+
+/**
+ * Internal key for Agent instantiation.
+ * This Symbol is used to ensure only AgentBuilder can create Agent instances.
+ *
+ * @internal
+ */
+declare const AGENT_INTERNAL_KEY: unique symbol;
+
+/**
+ * Event handler sugar for cleaner event processing.
+ *
+ * Instead of verbose if/else chains, use named handlers
+ * for each event type.
+ *
+ * @example
+ * ```typescript
+ * await agent.runWith({
+ *   onText: (content) => console.log("LLM:", content),
+ *   onGadgetResult: (result) => console.log("Result:", result.result),
+ * });
+ * ```
+ */
+
+/**
+ * Named event handlers for different event types.
+ */
+interface EventHandlers {
+    /** Called when text is generated by the LLM */
+    onText?: (content: string) => void | Promise<void>;
+    /** Called when a gadget is about to be executed */
+    onGadgetCall?: (call: {
+        gadgetName: string;
+        parameters?: Record<string, unknown>;
+        parametersYaml: string;
+    }) => void | Promise<void>;
+    /** Called when a gadget execution completes */
+    onGadgetResult?: (result: {
+        gadgetName: string;
+        result?: string;
+        error?: string;
+        parameters: Record<string, unknown>;
+    }) => void | Promise<void>;
+    /** Called when human input is required */
+    onHumanInputRequired?: (data: {
+        question: string;
+        gadgetName: string;
+    }) => void | Promise<void>;
+    /** Called for any other event type */
+    onOther?: (event: StreamEvent) => void | Promise<void>;
+}
+/**
+ * Helper to run an agent with named event handlers.
+ *
+ * @param agentGenerator - Agent's run() async generator
+ * @param handlers - Named event handlers
+ *
+ * @example
+ * ```typescript
+ * await runWithHandlers(agent.run(), {
+ *   onText: (text) => console.log("LLM:", text),
+ *   onGadgetResult: (result) => console.log("Result:", result.result),
+ * });
+ * ```
+ */
+declare function runWithHandlers(agentGenerator: AsyncGenerator<StreamEvent>, handlers: EventHandlers): Promise<void>;
+/**
+ * Helper to collect events by type.
+ *
+ * @param agentGenerator - Agent's run() async generator
+ * @param collect - Object specifying which event types to collect
+ * @returns Object with collected events
+ *
+ * @example
+ * ```typescript
+ * const { text, gadgetResults } = await collectEvents(agent.run(), {
+ *   text: true,
+ *   gadgetResults: true,
+ * });
+ *
+ * console.log("Full response:", text.join(""));
+ * console.log("Gadget calls:", gadgetResults.length);
+ * ```
+ */
+declare function collectEvents(agentGenerator: AsyncGenerator<StreamEvent>, collect: {
+    text?: boolean;
+    gadgetCalls?: boolean;
+    gadgetResults?: boolean;
+}): Promise<{
+    text: string[];
+    gadgetCalls: Array<{
+        gadgetName: string;
+        parameters: Record<string, unknown>;
+    }>;
+    gadgetResults: Array<{
+        gadgetName: string;
+        result?: string;
+        error?: string;
+        parameters: Record<string, unknown>;
+    }>;
+}>;
+/**
+ * Helper to collect only text from an agent run.
+ *
+ * @param agentGenerator - Agent's run() async generator
+ * @returns Combined text response
+ *
+ * @example
+ * ```typescript
+ * const response = await collectText(agent.run());
+ * console.log(response);
+ * ```
+ */
+declare function collectText(agentGenerator: AsyncGenerator<StreamEvent>): Promise<string>;
+
+/**
+ * Clean, world-class hooks system with clear separation of concerns.
+ *
+ * ## Three Distinct Categories
+ *
+ * ### 1. OBSERVERS (Read-Only)
+ * **Purpose:** Logging, metrics, monitoring, analytics
+ * **Characteristics:**
+ * - Cannot modify data, only observe
+ * - Run in parallel (no ordering guarantees)
+ * - Errors are logged but don't crash the system
+ * - Both sync and async supported
+ *
+ * **When to use:** When you need to track what's happening without affecting execution.
+ *
+ * @example
+ * ```typescript
+ * observers: {
+ *   onLLMCallComplete: async (ctx) => {
+ *     metrics.track('llm_call', { tokens: ctx.usage?.totalTokens });
+ *   },
+ *   onGadgetExecutionComplete: async (ctx) => {
+ *     console.log(`${ctx.gadgetName} took ${ctx.executionTimeMs}ms`);
+ *   }
+ * }
+ * ```
+ *
+ * ### 2. INTERCEPTORS (Synchronous Transformations)
+ * **Purpose:** Transform, filter, redact, format data in-flight
+ * **Characteristics:**
+ * - Pure functions: input -> output (or null to suppress)
+ * - Run in sequence (order matters)
+ * - Effect is immediate and visible to subsequent hooks
+ * - Sync only (no async)
+ *
+ * **When to use:** When you need to modify data as it flows through the system.
+ *
+ * @example
+ * ```typescript
+ * interceptors: {
+ *   // Redact sensitive data
+ *   interceptRawChunk: (chunk) =>
+ *     chunk.replace(/api_key=\w+/g, 'api_key=[REDACTED]'),
+ *
+ *   // Suppress certain outputs
+ *   interceptTextChunk: (chunk, ctx) =>
+ *     chunk.includes('[INTERNAL]') ? null : chunk,
+ *
+ *   // Add metadata to results
+ *   interceptGadgetResult: (result, ctx) =>
+ *     `[${ctx.gadgetName}] ${result}`
+ * }
+ * ```
+ *
+ * ### 3. CONTROLLERS (Async Lifecycle Control)
+ * **Purpose:** Control execution flow, skip operations, provide fallbacks
+ * **Characteristics:**
+ * - Async functions returning action objects
+ * - Can skip operations or provide synthetic/fallback responses
+ * - Run at specific decision points in the lifecycle
+ * - Actions are validated at runtime
+ *
+ * **When to use:** When you need to conditionally modify behavior or recover from errors.
+ *
+ * @example
+ * ```typescript
+ * controllers: {
+ *   // Skip LLM call and return cached response
+ *   beforeLLMCall: async (ctx) => {
+ *     const cached = cache.get(ctx.options.messages);
+ *     if (cached) return { action: 'skip', syntheticResponse: cached };
+ *     return { action: 'proceed' };
+ *   },
+ *
+ *   // Recover from LLM errors
+ *   afterLLMError: async (ctx) => ({
+ *     action: 'recover',
+ *     fallbackResponse: 'Sorry, I encountered an error. Please try again.'
+ *   }),
+ *
+ *   // Skip expensive gadgets in certain conditions
+ *   beforeGadgetExecution: async (ctx) => {
+ *     if (ctx.gadgetName === 'SlowSearch' && ctx.iteration > 2) {
+ *       return { action: 'skip', syntheticResult: 'Search skipped to save time' };
+ *     }
+ *     return { action: 'proceed' };
+ *   }
+ * }
+ * ```
+ *
+ * ## Hook Execution Order
+ *
+ * ```
+ * LLM CALL LIFECYCLE:
+ * 1. onLLMCallStart (observer)
+ * 2. beforeLLMCall (controller) - can skip/modify
+ * 3. [LLM API Call]
+ * 4. For each stream chunk:
+ *    a. interceptRawChunk (interceptor)
+ *    b. onStreamChunk (observer)
+ *    c. Parse for gadgets
+ *    d. If gadget found -> GADGET LIFECYCLE
+ *    e. If text -> interceptTextChunk -> emit
+ * 5. afterLLMCall (controller) - can append/modify
+ * 6. interceptAssistantMessage (interceptor)
+ * 7. onLLMCallComplete (observer)
+ *
+ * GADGET LIFECYCLE:
+ * 1. interceptGadgetParameters (interceptor)
+ * 2. beforeGadgetExecution (controller) - can skip
+ * 3. onGadgetExecutionStart (observer)
+ * 4. [Execute gadget]
+ * 5. interceptGadgetResult (interceptor)
+ * 6. afterGadgetExecution (controller) - can recover
+ * 7. onGadgetExecutionComplete (observer)
+ * ```
+ *
+ * @module agent/hooks
+ */
+
+/**
+ * Context provided when an LLM call starts.
+ * Read-only observation point.
+ */
+interface ObserveLLMCallContext {
+    iteration: number;
+    options: Readonly<LLMGenerationOptions>;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context provided when an LLM call completes successfully.
+ * Read-only observation point.
+ */
+interface ObserveLLMCompleteContext {
+    iteration: number;
+    options: Readonly<LLMGenerationOptions>;
+    finishReason: string | null;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    /** The complete raw response text */
+    rawResponse: string;
+    /** The final message that will be added to history (after interceptors) */
+    finalMessage: string;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context provided when an LLM call fails.
+ * Read-only observation point.
+ */
+interface ObserveLLMErrorContext {
+    iteration: number;
+    options: Readonly<LLMGenerationOptions>;
+    error: Error;
+    /** Whether the error was recovered by a controller */
+    recovered: boolean;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context provided when a gadget execution starts.
+ * Read-only observation point.
+ */
+interface ObserveGadgetStartContext {
+    iteration: number;
+    gadgetName: string;
+    invocationId: string;
+    /** Parameters after controller modifications */
+    parameters: Readonly<Record<string, unknown>>;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context provided when a gadget execution completes.
+ * Read-only observation point.
+ */
+interface ObserveGadgetCompleteContext {
+    iteration: number;
+    gadgetName: string;
+    invocationId: string;
+    parameters: Readonly<Record<string, unknown>>;
+    /** Original result before interceptors */
+    originalResult?: string;
+    /** Final result after interceptors */
+    finalResult?: string;
+    error?: string;
+    executionTimeMs: number;
+    breaksLoop?: boolean;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context provided for each stream chunk.
+ * Read-only observation point.
+ */
+interface ObserveChunkContext {
+    iteration: number;
+    /** The raw chunk from the LLM */
+    rawChunk: string;
+    /** Accumulated text so far */
+    accumulatedText: string;
+    /** Token usage if available (Anthropic sends input tokens at stream start) */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    logger: Logger<ILogObj>;
+}
+/**
+ * Observers: Read-only hooks for side effects.
+ * - Cannot modify data
+ * - Errors are logged but don't crash the system
+ * - Run in parallel (no ordering guarantees)
+ */
+interface Observers {
+    /** Called when an LLM call starts */
+    onLLMCallStart?: (context: ObserveLLMCallContext) => void | Promise<void>;
+    /** Called when an LLM call completes successfully */
+    onLLMCallComplete?: (context: ObserveLLMCompleteContext) => void | Promise<void>;
+    /** Called when an LLM call fails */
+    onLLMCallError?: (context: ObserveLLMErrorContext) => void | Promise<void>;
+    /** Called when a gadget execution starts */
+    onGadgetExecutionStart?: (context: ObserveGadgetStartContext) => void | Promise<void>;
+    /** Called when a gadget execution completes (success or error) */
+    onGadgetExecutionComplete?: (context: ObserveGadgetCompleteContext) => void | Promise<void>;
+    /** Called for each stream chunk */
+    onStreamChunk?: (context: ObserveChunkContext) => void | Promise<void>;
+}
+/**
+ * Context for chunk interception.
+ */
+interface ChunkInterceptorContext {
+    iteration: number;
+    accumulatedText: string;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context for message interception.
+ */
+interface MessageInterceptorContext {
+    iteration: number;
+    /** The raw LLM response */
+    rawResponse: string;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context for gadget parameter interception.
+ */
+interface GadgetParameterInterceptorContext {
+    iteration: number;
+    gadgetName: string;
+    invocationId: string;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context for gadget result interception.
+ */
+interface GadgetResultInterceptorContext {
+    iteration: number;
+    gadgetName: string;
+    invocationId: string;
+    parameters: Readonly<Record<string, unknown>>;
+    executionTimeMs: number;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Interceptors: Synchronous transformations with predictable timing.
+ * - Pure functions with clear input -> output
+ * - Run in sequence (order matters)
+ * - Effect is immediate (no confusion about timing)
+ */
+interface Interceptors {
+    /**
+     * Intercept and transform raw chunks from the LLM stream.
+     * Affects current stream immediately.
+     *
+     * @param chunk - The raw chunk text from the LLM
+     * @param context - Context information including iteration and accumulated text
+     * @returns Transformed chunk text, or null to suppress the chunk entirely
+     */
+    interceptRawChunk?: (chunk: string, context: ChunkInterceptorContext) => string | null;
+    /**
+     * Intercept and transform text chunks before they're displayed.
+     * Affects current output immediately.
+     *
+     * @param chunk - The text chunk to be displayed
+     * @param context - Context information including iteration and accumulated text
+     * @returns Transformed chunk text, or null to suppress the chunk entirely
+     */
+    interceptTextChunk?: (chunk: string, context: ChunkInterceptorContext) => string | null;
+    /**
+     * Intercept and transform the final assistant message before it's added to conversation history.
+     * This is the last chance to modify what gets stored.
+     *
+     * @param message - The final message text
+     * @param context - Context information including raw response
+     * @returns Transformed message text (cannot be suppressed)
+     */
+    interceptAssistantMessage?: (message: string, context: MessageInterceptorContext) => string;
+    /**
+     * Intercept and transform gadget parameters before execution.
+     *
+     * IMPORTANT: The intercepted parameters are used to update the original call object.
+     * This means the modified parameters will be visible in subsequent hooks.
+     *
+     * @param parameters - The original parameters (readonly - create new object if modifying)
+     * @param context - Context information including gadget name and invocation ID
+     * @returns Modified parameters object
+     */
+    interceptGadgetParameters?: (parameters: Readonly<Record<string, unknown>>, context: GadgetParameterInterceptorContext) => Record<string, unknown>;
+    /**
+     * Intercept and transform gadget results after execution.
+     * This affects what gets sent back to the LLM and stored in history.
+     *
+     * @param result - The gadget result text
+     * @param context - Context information including parameters and execution time
+     * @returns Transformed result text (cannot be suppressed)
+     */
+    interceptGadgetResult?: (result: string, context: GadgetResultInterceptorContext) => string;
+}
+/**
+ * Context for LLM call controller.
+ */
+interface LLMCallControllerContext {
+    iteration: number;
+    options: LLMGenerationOptions;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Action returned by beforeLLMCall controller.
+ */
+type BeforeLLMCallAction = {
+    action: "proceed";
+    modifiedOptions?: Partial<LLMGenerationOptions>;
+} | {
+    action: "skip";
+    syntheticResponse: string;
+};
+/**
+ * Context for after LLM call controller.
+ */
+interface AfterLLMCallControllerContext {
+    iteration: number;
+    options: Readonly<LLMGenerationOptions>;
+    finishReason: string | null;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    /** The final message (after interceptors) that will be added to history */
+    finalMessage: string;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Action returned by afterLLMCall controller.
+ */
+type AfterLLMCallAction = {
+    action: "continue";
+} | {
+    action: "append_messages";
+    messages: LLMMessage[];
+} | {
+    action: "modify_and_continue";
+    modifiedMessage: string;
+} | {
+    action: "append_and_modify";
+    modifiedMessage: string;
+    messages: LLMMessage[];
+};
+/**
+ * Context for LLM error controller.
+ */
+interface LLMErrorControllerContext {
+    iteration: number;
+    options: Readonly<LLMGenerationOptions>;
+    error: Error;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Action returned by LLM error controller.
+ */
+type AfterLLMErrorAction = {
+    action: "rethrow";
+} | {
+    action: "recover";
+    fallbackResponse: string;
+};
+/**
+ * Context for gadget execution controller.
+ */
+interface GadgetExecutionControllerContext {
+    iteration: number;
+    gadgetName: string;
+    invocationId: string;
+    /** Parameters after interceptors have run */
+    parameters: Record<string, unknown>;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Action returned by beforeGadgetExecution controller.
+ */
+type BeforeGadgetExecutionAction = {
+    action: "proceed";
+} | {
+    action: "skip";
+    syntheticResult: string;
+};
+/**
+ * Context for after gadget execution controller.
+ */
+interface AfterGadgetExecutionControllerContext {
+    iteration: number;
+    gadgetName: string;
+    invocationId: string;
+    parameters: Readonly<Record<string, unknown>>;
+    /** Result after interceptors (if successful) */
+    result?: string;
+    error?: string;
+    executionTimeMs: number;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Action returned by afterGadgetExecution controller.
+ */
+type AfterGadgetExecutionAction = {
+    action: "continue";
+} | {
+    action: "recover";
+    fallbackResult: string;
+};
+/**
+ * Controllers: Async lifecycle hooks that control execution flow.
+ * - Can short-circuit execution
+ * - Can modify options and provide fallbacks
+ * - Run at specific lifecycle points
+ */
+interface Controllers {
+    /**
+     * Called before making an LLM API call.
+     * Can modify options or skip the call entirely.
+     */
+    beforeLLMCall?: (context: LLMCallControllerContext) => Promise<BeforeLLMCallAction>;
+    /**
+     * Called after a successful LLM call (after interceptors have run).
+     * Can append messages to conversation or modify the final message.
+     */
+    afterLLMCall?: (context: AfterLLMCallControllerContext) => Promise<AfterLLMCallAction>;
+    /**
+     * Called after an LLM call fails.
+     * Can provide a fallback response to recover from the error.
+     */
+    afterLLMError?: (context: LLMErrorControllerContext) => Promise<AfterLLMErrorAction>;
+    /**
+     * Called before executing a gadget (after interceptors have run).
+     * Can skip execution and provide a synthetic result.
+     */
+    beforeGadgetExecution?: (context: GadgetExecutionControllerContext) => Promise<BeforeGadgetExecutionAction>;
+    /**
+     * Called after a gadget execution (success or error).
+     * Can provide a fallback result to recover from errors.
+     */
+    afterGadgetExecution?: (context: AfterGadgetExecutionControllerContext) => Promise<AfterGadgetExecutionAction>;
+}
+/**
+ * Clean hooks system with three distinct categories:
+ * - Observers: Read-only, for logging and metrics
+ * - Interceptors: Synchronous transformations with immediate effect
+ * - Controllers: Async lifecycle control with short-circuit capability
+ */
+interface AgentHooks {
+    /** Read-only observation hooks for logging, metrics, etc. */
+    observers?: Observers;
+    /** Synchronous transformation hooks that affect current execution */
+    interceptors?: Interceptors;
+    /** Async lifecycle control hooks */
+    controllers?: Controllers;
+}
+
+/**
+ * Agent: Lean orchestrator using the clean hooks architecture.
+ *
+ * The Agent delegates ALL stream processing and hook coordination to StreamProcessor,
+ * making it a simple loop orchestrator with clear responsibilities.
+ */
+
+/**
+ * Configuration options for the Agent.
+ */
+interface AgentOptions {
+    /** The LLM client */
+    client: LLMist;
+    /** The model ID */
+    model: string;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Initial user prompt (optional if using build()) */
+    userPrompt?: string;
+    /** Maximum iterations */
+    maxIterations?: number;
+    /** Temperature */
+    temperature?: number;
+    /** Gadget registry */
+    registry: GadgetRegistry;
+    /** Logger */
+    logger?: Logger<ILogObj>;
+    /** Clean hooks system */
+    hooks?: AgentHooks;
+    /** Callback for human input */
+    onHumanInputRequired?: (question: string) => Promise<string>;
+    /** Parameter format */
+    parameterFormat?: ParameterFormat;
+    /** Custom gadget start prefix */
+    gadgetStartPrefix?: string;
+    /** Custom gadget end prefix */
+    gadgetEndPrefix?: string;
+    /** Initial messages */
+    initialMessages?: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    /** Text-only handler */
+    textOnlyHandler?: TextOnlyHandler;
+    /** Stop on gadget error */
+    stopOnGadgetError?: boolean;
+    /** Custom error continuation logic */
+    shouldContinueAfterError?: (context: {
+        error: string;
+        gadgetName: string;
+        errorType: "parse" | "validation" | "execution";
+        parameters?: Record<string, unknown>;
+    }) => boolean | Promise<boolean>;
+    /** Default gadget timeout */
+    defaultGadgetTimeoutMs?: number;
+    /** Custom prompt configuration for gadget system prompts */
+    promptConfig?: PromptConfig;
+}
+/**
+ * Agent: Lean orchestrator that delegates to StreamProcessor.
+ *
+ * Responsibilities:
+ * - Run the main agent loop
+ * - Call LLM API
+ * - Delegate stream processing to StreamProcessor
+ * - Coordinate conversation management
+ * - Execute top-level lifecycle controllers
+ *
+ * NOT responsible for:
+ * - Stream parsing (StreamProcessor)
+ * - Hook coordination (StreamProcessor)
+ * - Gadget execution (StreamProcessor -> GadgetExecutor)
+ */
+declare class Agent {
+    private readonly client;
+    private readonly model;
+    private readonly maxIterations;
+    private readonly temperature?;
+    private readonly logger;
+    private readonly hooks;
+    private readonly conversation;
+    private readonly registry;
+    private readonly parameterFormat;
+    private readonly gadgetStartPrefix?;
+    private readonly gadgetEndPrefix?;
+    private readonly onHumanInputRequired?;
+    private readonly textOnlyHandler;
+    private readonly stopOnGadgetError;
+    private readonly shouldContinueAfterError?;
+    private readonly defaultGadgetTimeoutMs?;
+    private readonly defaultMaxTokens?;
+    private userPromptProvided;
+    /**
+     * Creates a new Agent instance.
+     * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
+     */
+    constructor(key: typeof AGENT_INTERNAL_KEY, options: AgentOptions);
+    /**
+     * Get the gadget registry for this agent.
+     *
+     * Useful for inspecting registered gadgets in tests or advanced use cases.
+     *
+     * @returns The GadgetRegistry instance
+     *
+     * @example
+     * ```typescript
+     * const agent = new AgentBuilder()
+     *   .withModel("sonnet")
+     *   .withGadgets(Calculator, Weather)
+     *   .build();
+     *
+     * // Inspect registered gadgets
+     * console.log(agent.getRegistry().getNames()); // ['Calculator', 'Weather']
+     * ```
+     */
+    getRegistry(): GadgetRegistry;
+    /**
+     * Run the agent loop.
+     * Clean, simple orchestration - all complexity is in StreamProcessor.
+     *
+     * @throws {Error} If no user prompt was provided (when using build() without ask())
+     */
+    run(): AsyncGenerator<StreamEvent>;
+    /**
+     * Handle LLM error through controller.
+     */
+    private handleLLMError;
+    /**
+     * Handle text-only response (no gadgets called).
+     */
+    private handleTextOnlyResponse;
+    /**
+     * Safely execute an observer, catching and logging any errors.
+     */
+    private safeObserve;
+    /**
+     * Resolve max tokens from model catalog.
+     */
+    private resolveMaxTokensFromCatalog;
+    /**
+     * Run agent with named event handlers (syntactic sugar).
+     *
+     * Instead of verbose if/else chains, use named handlers for cleaner code.
+     *
+     * @param handlers - Named event handlers
+     *
+     * @example
+     * ```typescript
+     * await agent.runWith({
+     *   onText: (text) => console.log("LLM:", text),
+     *   onGadgetResult: (result) => console.log("Result:", result.result),
+     *   onGadgetCall: (call) => console.log("Calling:", call.gadgetName),
+     * });
+     * ```
+     */
+    runWith(handlers: EventHandlers): Promise<void>;
+}
+
+/**
+ * Fluent builder for creating agents with delightful DX.
+ *
+ * @example
+ * ```typescript
+ * const agent = await LLMist.createAgent()
+ *   .withModel("sonnet")
+ *   .withSystem("You are a helpful assistant")
+ *   .withGadgets(Calculator, Weather)
+ *   .withMaxIterations(10)
+ *   .ask("What's the weather in Paris?");
+ *
+ * for await (const event of agent.run()) {
+ *   // process events
+ * }
+ * ```
+ */
+
+/**
+ * Message for conversation history.
+ */
+type HistoryMessage = {
+    user: string;
+} | {
+    assistant: string;
+} | {
+    system: string;
+};
+/**
+ * Fluent builder for creating agents.
+ *
+ * Provides a chainable API for configuring and creating agents,
+ * making the code more expressive and easier to read.
+ */
+declare class AgentBuilder {
+    private client?;
+    private model?;
+    private systemPrompt?;
+    private temperature?;
+    private maxIterations?;
+    private logger?;
+    private hooks?;
+    private promptConfig?;
+    private gadgets;
+    private initialMessages;
+    private onHumanInputRequired?;
+    private parameterFormat?;
+    private gadgetStartPrefix?;
+    private gadgetEndPrefix?;
+    private textOnlyHandler?;
+    private stopOnGadgetError?;
+    private shouldContinueAfterError?;
+    private defaultGadgetTimeoutMs?;
+    constructor(client?: LLMist);
+    /**
+     * Set the model to use.
+     * Supports aliases like "gpt4", "sonnet", "flash".
+     *
+     * @param model - Model name or alias
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withModel("sonnet")           // Alias
+     * .withModel("gpt-5-nano")       // Auto-detects provider
+     * .withModel("openai:gpt-5")     // Explicit provider
+     * ```
+     */
+    withModel(model: string): this;
+    /**
+     * Set the system prompt.
+     *
+     * @param prompt - System prompt
+     * @returns This builder for chaining
+     */
+    withSystem(prompt: string): this;
+    /**
+     * Set the temperature (0-1).
+     *
+     * @param temperature - Temperature value
+     * @returns This builder for chaining
+     */
+    withTemperature(temperature: number): this;
+    /**
+     * Set maximum iterations.
+     *
+     * @param max - Maximum number of iterations
+     * @returns This builder for chaining
+     */
+    withMaxIterations(max: number): this;
+    /**
+     * Set logger instance.
+     *
+     * @param logger - Logger instance
+     * @returns This builder for chaining
+     */
+    withLogger(logger: Logger<ILogObj>): this;
+    /**
+     * Add hooks for agent lifecycle events.
+     *
+     * @param hooks - Agent hooks configuration
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * import { HookPresets } from 'llmist/hooks';
+     *
+     * .withHooks(HookPresets.logging())
+     * .withHooks(HookPresets.merge(
+     *   HookPresets.logging(),
+     *   HookPresets.timing()
+     * ))
+     * ```
+     */
+    withHooks(hooks: AgentHooks): this;
+    /**
+     * Configure custom prompts for gadget system messages.
+     *
+     * @param config - Prompt configuration object
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withPromptConfig({
+     *   mainInstruction: "Use the gadget markers below:",
+     *   rules: ["Always use markers", "Never use function calling"]
+     * })
+     * ```
+     */
+    withPromptConfig(config: PromptConfig): this;
+    /**
+     * Add gadgets (classes or instances).
+     * Can be called multiple times to add more gadgets.
+     *
+     * @param gadgets - Gadget classes or instances
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withGadgets(Calculator, Weather, Email)
+     * .withGadgets(new Calculator(), new Weather())
+     * .withGadgets(createGadget({ ... }))
+     * ```
+     */
+    withGadgets(...gadgets: GadgetOrClass[]): this;
+    /**
+     * Add conversation history messages.
+     * Useful for continuing previous conversations.
+     *
+     * @param messages - Array of history messages
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withHistory([
+     *   { user: "Hello" },
+     *   { assistant: "Hi there!" },
+     *   { user: "How are you?" },
+     *   { assistant: "I'm doing well, thanks!" }
+     * ])
+     * ```
+     */
+    withHistory(messages: HistoryMessage[]): this;
+    /**
+     * Add a single message to the conversation history.
+     *
+     * @param message - Single history message
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .addMessage({ user: "Hello" })
+     * .addMessage({ assistant: "Hi there!" })
+     * ```
+     */
+    addMessage(message: HistoryMessage): this;
+    /**
+     * Set the human input handler for interactive conversations.
+     *
+     * @param handler - Function to handle human input requests
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .onHumanInput(async (question) => {
+     *   return await promptUser(question);
+     * })
+     * ```
+     */
+    onHumanInput(handler: (question: string) => Promise<string>): this;
+    /**
+     * Set the parameter format for gadget calls.
+     *
+     * @param format - Parameter format ("json" or "xml")
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withParameterFormat("xml")
+     * ```
+     */
+    withParameterFormat(format: ParameterFormat): this;
+    /**
+     * Set custom gadget marker prefix.
+     *
+     * @param prefix - Custom start prefix for gadget markers
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withGadgetStartPrefix("<<GADGET_START>>")
+     * ```
+     */
+    withGadgetStartPrefix(prefix: string): this;
+    /**
+     * Set custom gadget marker suffix.
+     *
+     * @param suffix - Custom end suffix for gadget markers
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withGadgetEndPrefix("<<GADGET_END>>")
+     * ```
+     */
+    withGadgetEndPrefix(suffix: string): this;
+    /**
+     * Set the text-only handler strategy.
+     *
+     * Controls what happens when the LLM returns text without calling any gadgets:
+     * - "terminate": End the agent loop (default)
+     * - "acknowledge": Continue the loop for another iteration
+     * - "wait_for_input": Wait for human input
+     * - Custom handler: Provide a function for dynamic behavior
+     *
+     * @param handler - Text-only handler strategy or custom handler
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple strategy
+     * .withTextOnlyHandler("acknowledge")
+     *
+     * // Custom handler
+     * .withTextOnlyHandler({
+     *   type: "custom",
+     *   handler: async (context) => {
+     *     if (context.text.includes("?")) {
+     *       return { action: "wait_for_input", question: context.text };
+     *     }
+     *     return { action: "continue" };
+     *   }
+     * })
+     * ```
+     */
+    withTextOnlyHandler(handler: TextOnlyHandler): this;
+    /**
+     * Set whether to stop gadget execution on first error.
+     *
+     * When true (default), if a gadget fails:
+     * - Subsequent gadgets in the same response are skipped
+     * - LLM stream is cancelled to save costs
+     * - Agent loop continues with error in context
+     *
+     * When false:
+     * - All gadgets in the response still execute
+     * - LLM stream continues to completion
+     *
+     * @param stop - Whether to stop on gadget error
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withStopOnGadgetError(false)
+     * ```
+     */
+    withStopOnGadgetError(stop: boolean): this;
+    /**
+     * Set custom error handling logic.
+     *
+     * Provides fine-grained control over whether to continue after different types of errors.
+     * Overrides `stopOnGadgetError` when provided.
+     *
+     * **Note:** This builder method configures the underlying `shouldContinueAfterError` option
+     * in `AgentOptions`. The method is named `withErrorHandler` for better developer experience,
+     * but maps to the `shouldContinueAfterError` property internally.
+     *
+     * @param handler - Function that decides whether to continue after an error.
+     *                  Return `true` to continue execution, `false` to stop.
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withErrorHandler((context) => {
+     *   // Stop on parse errors, continue on validation/execution errors
+     *   if (context.errorType === "parse") {
+     *     return false;
+     *   }
+     *   if (context.error.includes("CRITICAL")) {
+     *     return false;
+     *   }
+     *   return true;
+     * })
+     * ```
+     */
+    withErrorHandler(handler: (context: {
+        error: string;
+        gadgetName: string;
+        errorType: "parse" | "validation" | "execution";
+        parameters?: Record<string, unknown>;
+    }) => boolean | Promise<boolean>): this;
+    /**
+     * Set default timeout for gadget execution.
+     *
+     * @param timeoutMs - Timeout in milliseconds (must be non-negative)
+     * @returns This builder for chaining
+     * @throws {Error} If timeout is negative
+     *
+     * @example
+     * ```typescript
+     * .withDefaultGadgetTimeout(5000) // 5 second timeout
+     * ```
+     */
+    withDefaultGadgetTimeout(timeoutMs: number): this;
+    /**
+     * Build and create the agent with the given user prompt.
+     * Returns the Agent instance ready to run.
+     *
+     * @param userPrompt - User's question or request
+     * @returns Configured Agent instance
+     *
+     * @example
+     * ```typescript
+     * const agent = await LLMist.createAgent()
+     *   .withModel("sonnet")
+     *   .withGadgets(Calculator)
+     *   .ask("What is 2+2?");
+     *
+     * for await (const event of agent.run()) {
+     *   // handle events
+     * }
+     * ```
+     */
+    ask(userPrompt: string): Agent;
+    /**
+     * Build, run, and collect only the text response.
+     * Convenient for simple queries where you just want the final answer.
+     *
+     * @param userPrompt - User's question or request
+     * @returns Promise resolving to the complete text response
+     *
+     * @example
+     * ```typescript
+     * const answer = await LLMist.createAgent()
+     *   .withModel("gpt4-mini")
+     *   .withGadgets(Calculator)
+     *   .askAndCollect("What is 42 * 7?");
+     *
+     * console.log(answer); // "294"
+     * ```
+     */
+    askAndCollect(userPrompt: string): Promise<string>;
+    /**
+     * Build and run with event handlers.
+     * Combines agent creation and event handling in one call.
+     *
+     * @param userPrompt - User's question or request
+     * @param handlers - Event handlers
+     *
+     * @example
+     * ```typescript
+     * await LLMist.createAgent()
+     *   .withModel("sonnet")
+     *   .withGadgets(Calculator)
+     *   .askWith("What is 2+2?", {
+     *     onText: (text) => console.log("LLM:", text),
+     *     onGadgetResult: (result) => console.log("Result:", result.result),
+     *   });
+     * ```
+     */
+    askWith(userPrompt: string, handlers: EventHandlers): Promise<void>;
+    /**
+     * Build the agent without a user prompt.
+     *
+     * Returns an Agent instance that can be inspected (e.g., check registered gadgets)
+     * but cannot be run without first calling .ask(prompt).
+     *
+     * This is useful for:
+     * - Testing: Inspect the registry, configuration, etc.
+     * - Advanced use cases: Build agent configuration separately from execution
+     *
+     * @returns Configured Agent instance (without user prompt)
+     *
+     * @example
+     * ```typescript
+     * // Build agent for inspection
+     * const agent = new AgentBuilder()
+     *   .withModel("sonnet")
+     *   .withGadgets(Calculator, Weather)
+     *   .build();
+     *
+     * // Inspect registered gadgets
+     * console.log(agent.getRegistry().getNames()); // ['Calculator', 'Weather']
+     *
+     * // Note: Calling agent.run() will throw an error
+     * // Use .ask(prompt) instead if you want to run the agent
+     * ```
+     */
+    build(): Agent;
+}
+
+/**
+ * Context provided to matcher functions to determine if a mock should be used.
+ */
+interface MockMatcherContext {
+    /** The model descriptor (e.g., "openai:gpt-5") */
+    model: string;
+    /** The provider ID extracted from the model */
+    provider: string;
+    /** The model name without provider prefix */
+    modelName: string;
+    /** The complete LLM generation options */
+    options: LLMGenerationOptions;
+    /** The messages being sent to the LLM */
+    messages: LLMMessage[];
+}
+/**
+ * Matcher function that determines if a mock should be used for an LLM call.
+ *
+ * @param context - The context of the LLM call
+ * @returns true if this mock should be used, false otherwise
+ *
+ * @example
+ * // Match any call to GPT-5
+ * const matcher: MockMatcher = (ctx) => ctx.modelName.includes('gpt-5');
+ *
+ * @example
+ * // Match calls with specific message content
+ * const matcher: MockMatcher = (ctx) => {
+ *   const lastMessage = ctx.messages[ctx.messages.length - 1];
+ *   return lastMessage?.content?.includes('calculate');
+ * };
+ *
+ * @example
+ * // Match by provider
+ * const matcher: MockMatcher = (ctx) => ctx.provider === 'anthropic';
+ */
+type MockMatcher = (context: MockMatcherContext) => boolean | Promise<boolean>;
+/**
+ * A mock response that will be returned when a matcher succeeds.
+ */
+interface MockResponse {
+    /**
+     * Plain text content to return (will be streamed as text chunks)
+     * Can include gadget markers like \n<GADGET_name>...</GADGET_END>
+     */
+    text?: string;
+    /**
+     * Pre-parsed gadget calls to inject into the response stream
+     * These will be emitted as gadget_call events
+     */
+    gadgetCalls?: Array<{
+        gadgetName: string;
+        parameters: Record<string, unknown>;
+        /** Optional invocationId, will be auto-generated if not provided */
+        invocationId?: string;
+    }>;
+    /**
+     * Simulated token usage statistics
+     */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    /**
+     * Simulated finish reason
+     */
+    finishReason?: string;
+    /**
+     * Delay in milliseconds before starting to stream the response
+     * Useful for simulating network latency
+     */
+    delayMs?: number;
+    /**
+     * Delay in milliseconds between each chunk when streaming
+     * Useful for simulating realistic streaming behavior
+     */
+    streamDelayMs?: number;
+}
+/**
+ * A registered mock configuration combining a matcher with a response.
+ */
+interface MockRegistration {
+    /** Unique identifier for this mock (auto-generated if not provided) */
+    id: string;
+    /** The matcher function to determine if this mock applies */
+    matcher: MockMatcher;
+    /** The response to return when matched */
+    response: MockResponse | ((context: MockMatcherContext) => MockResponse | Promise<MockResponse>);
+    /** Optional label for debugging */
+    label?: string;
+    /** If true, this mock will only be used once then automatically removed */
+    once?: boolean;
+}
+/**
+ * Statistics about mock usage.
+ */
+interface MockStats {
+    /** Number of times this mock was matched and used */
+    matchCount: number;
+    /** Last time this mock was used */
+    lastUsed?: Date;
+}
+/**
+ * Options for configuring the mock system.
+ */
+interface MockOptions {
+    /**
+     * If true, throws an error when no mock matches an LLM call.
+     * If false, logs a warning and returns an empty response.
+     * Default: false
+     */
+    strictMode?: boolean;
+    /**
+     * If true, logs detailed information about mock matching and execution.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * If true, records statistics about mock usage.
+     * Default: true
+     */
+    recordStats?: boolean;
+}
+
+/**
+ * Provider adapter that serves mock responses instead of making real LLM API calls.
+ * This is useful for testing applications that use llmist without incurring API costs.
+ *
+ * The MockProviderAdapter has high priority (100) and is always checked before
+ * real providers when both are registered. This enables selective mocking where
+ * some models use mocks while others use real providers. If no matching mock is
+ * found and strictMode is disabled, requests return an empty response.
+ *
+ * @example
+ * ```typescript
+ * import { LLMist, createMockAdapter, mockLLM } from 'llmist/testing';
+ *
+ * // Use with real providers for selective mocking
+ * const client = new LLMist({
+ *   adapters: [createMockAdapter()],
+ *   autoDiscoverProviders: true // Also loads real OpenAI, Anthropic, etc.
+ * });
+ *
+ * // Register mocks for specific models
+ * mockLLM()
+ *   .forModel('gpt-5-nano')
+ *   .returns('Test response')
+ *   .register();
+ *
+ * // gpt-5-nano uses mock, other models use real providers
+ * const stream = client.stream({
+ *   model: 'openai:gpt-5-nano',
+ *   messages: [{ role: 'user', content: 'test' }]
+ * });
+ * ```
+ */
+declare class MockProviderAdapter implements ProviderAdapter {
+    readonly providerId = "mock";
+    readonly priority = 100;
+    private readonly mockManager;
+    constructor(options?: MockOptions);
+    supports(descriptor: ModelDescriptor): boolean;
+    stream(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec?: unknown): LLMStream;
+    private createMockStreamFromContext;
+}
+/**
+ * Create a mock provider adapter instance.
+ * This is a convenience factory function.
+ *
+ * @param options - Optional configuration for the mock system
+ * @returns A configured MockProviderAdapter
+ *
+ * @example
+ * ```typescript
+ * const adapter = createMockAdapter({ strictMode: true, debug: true });
+ * const client = new LLMist([adapter]);
+ * ```
+ */
+declare function createMockAdapter(options?: MockOptions): MockProviderAdapter;
+
+/**
+ * Fluent builder for creating mock responses and registrations.
+ * Provides a convenient API for common mocking scenarios.
+ *
+ * @example
+ * ```typescript
+ * import { mockLLM } from 'llmist';
+ *
+ * // Simple text mock
+ * mockLLM()
+ *   .forModel('gpt-5')
+ *   .returns('Hello, world!')
+ *   .register();
+ *
+ * // Mock with gadget calls
+ * mockLLM()
+ *   .forProvider('anthropic')
+ *   .whenMessageContains('calculate')
+ *   .returnsGadgetCalls([
+ *     { gadgetName: 'calculator', parameters: { operation: 'add', a: 1, b: 2 } }
+ *   ])
+ *   .register();
+ *
+ * // Complex conditional mock
+ * mockLLM()
+ *   .when((ctx) => ctx.messages.length > 5)
+ *   .returns('This conversation is getting long!')
+ *   .once()
+ *   .register();
+ * ```
+ */
+declare class MockBuilder {
+    private matchers;
+    private response;
+    private label?;
+    private isOnce;
+    private id?;
+    /**
+     * Match calls to a specific model (by name, supports partial matching).
+     *
+     * @example
+     * mockLLM().forModel('gpt-5')
+     * mockLLM().forModel('claude') // matches any Claude model
+     */
+    forModel(modelName: string): this;
+    /**
+     * Match calls to any model.
+     * Useful when you want to mock responses regardless of the model used.
+     *
+     * @example
+     * mockLLM().forAnyModel()
+     */
+    forAnyModel(): this;
+    /**
+     * Match calls to a specific provider.
+     *
+     * @example
+     * mockLLM().forProvider('openai')
+     * mockLLM().forProvider('anthropic')
+     */
+    forProvider(provider: string): this;
+    /**
+     * Match calls to any provider.
+     * Useful when you want to mock responses regardless of the provider used.
+     *
+     * @example
+     * mockLLM().forAnyProvider()
+     */
+    forAnyProvider(): this;
+    /**
+     * Match when any message contains the given text (case-insensitive).
+     *
+     * @example
+     * mockLLM().whenMessageContains('hello')
+     */
+    whenMessageContains(text: string): this;
+    /**
+     * Match when the last message contains the given text (case-insensitive).
+     *
+     * @example
+     * mockLLM().whenLastMessageContains('goodbye')
+     */
+    whenLastMessageContains(text: string): this;
+    /**
+     * Match when any message matches the given regex.
+     *
+     * @example
+     * mockLLM().whenMessageMatches(/calculate \d+/)
+     */
+    whenMessageMatches(regex: RegExp): this;
+    /**
+     * Match when a message with a specific role contains text.
+     *
+     * @example
+     * mockLLM().whenRoleContains('system', 'You are a helpful assistant')
+     */
+    whenRoleContains(role: LLMMessage["role"], text: string): this;
+    /**
+     * Match based on the number of messages in the conversation.
+     *
+     * @example
+     * mockLLM().whenMessageCount((count) => count > 10)
+     */
+    whenMessageCount(predicate: (count: number) => boolean): this;
+    /**
+     * Add a custom matcher function.
+     * This provides full control over matching logic.
+     *
+     * @example
+     * mockLLM().when((ctx) => {
+     *   return ctx.options.temperature > 0.8;
+     * })
+     */
+    when(matcher: MockMatcher): this;
+    /**
+     * Set the text response to return.
+     * Can be a static string or a function that returns a string dynamically.
+     *
+     * @example
+     * mockLLM().returns('Hello, world!')
+     * mockLLM().returns(() => `Response at ${Date.now()}`)
+     * mockLLM().returns((ctx) => `You said: ${ctx.messages[0]?.content}`)
+     */
+    returns(text: string | ((context: MockMatcherContext) => string | Promise<string>)): this;
+    /**
+     * Set gadget calls to include in the response.
+     *
+     * @example
+     * mockLLM().returnsGadgetCalls([
+     *   { gadgetName: 'calculator', parameters: { op: 'add', a: 1, b: 2 } }
+     * ])
+     */
+    returnsGadgetCalls(calls: Array<{
+        gadgetName: string;
+        parameters: Record<string, unknown>;
+        invocationId?: string;
+    }>): this;
+    /**
+     * Add a single gadget call to the response.
+     *
+     * @example
+     * mockLLM()
+     *   .returnsGadgetCall('calculator', { op: 'add', a: 1, b: 2 })
+     *   .returnsGadgetCall('logger', { message: 'Done!' })
+     */
+    returnsGadgetCall(gadgetName: string, parameters: Record<string, unknown>): this;
+    /**
+     * Set the complete mock response object.
+     * This allows full control over all response properties.
+     * Can also be a function that generates the response dynamically based on context.
+     *
+     * @example
+     * // Static response
+     * mockLLM().withResponse({
+     *   text: 'Hello',
+     *   usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+     *   finishReason: 'stop'
+     * })
+     *
+     * @example
+     * // Dynamic response
+     * mockLLM().withResponse((ctx) => ({
+     *   text: `You said: ${ctx.messages[ctx.messages.length - 1]?.content}`,
+     *   usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
+     * }))
+     */
+    withResponse(response: MockResponse | ((context: MockMatcherContext) => MockResponse | Promise<MockResponse>)): this;
+    /**
+     * Set simulated token usage.
+     *
+     * @example
+     * mockLLM().withUsage({ inputTokens: 100, outputTokens: 50, totalTokens: 150 })
+     */
+    withUsage(usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    }): this;
+    /**
+     * Set the finish reason.
+     *
+     * @example
+     * mockLLM().withFinishReason('stop')
+     * mockLLM().withFinishReason('length')
+     */
+    withFinishReason(reason: string): this;
+    /**
+     * Set initial delay before streaming starts (simulates network latency).
+     *
+     * @example
+     * mockLLM().withDelay(100) // 100ms delay
+     */
+    withDelay(ms: number): this;
+    /**
+     * Set delay between stream chunks (simulates realistic streaming).
+     *
+     * @example
+     * mockLLM().withStreamDelay(10) // 10ms between chunks
+     */
+    withStreamDelay(ms: number): this;
+    /**
+     * Set a label for this mock (useful for debugging).
+     *
+     * @example
+     * mockLLM().withLabel('greeting mock')
+     */
+    withLabel(label: string): this;
+    /**
+     * Set a specific ID for this mock.
+     *
+     * @example
+     * mockLLM().withId('my-custom-mock-id')
+     */
+    withId(id: string): this;
+    /**
+     * Mark this mock as one-time use (will be removed after first match).
+     *
+     * @example
+     * mockLLM().once()
+     */
+    once(): this;
+    /**
+     * Build the mock registration without registering it.
+     * Useful if you want to register it manually later.
+     *
+     * @returns The built MockRegistration object (without id if not specified)
+     */
+    build(): Omit<MockRegistration, "id"> & {
+        id?: string;
+    };
+    /**
+     * Register this mock with the global MockManager.
+     * Returns the ID of the registered mock.
+     *
+     * @example
+     * const mockId = mockLLM().forModel('gpt-5').returns('Hello!').register();
+     * // Later: getMockManager().unregister(mockId);
+     */
+    register(): string;
+}
+/**
+ * Create a new MockBuilder instance.
+ * This is the main entry point for the fluent mock API.
+ *
+ * @example
+ * ```typescript
+ * import { mockLLM } from 'llmist';
+ *
+ * mockLLM()
+ *   .forModel('gpt-5')
+ *   .whenMessageContains('hello')
+ *   .returns('Hello there!')
+ *   .register();
+ * ```
+ */
+declare function mockLLM(): MockBuilder;
+
+/**
+ * Create a preconfigured LLMist client with mock adapter.
+ * This is a convenience function for testing scenarios.
+ *
+ * @param options - Optional configuration for the mock system
+ * @returns A LLMist instance configured to use mocks
+ *
+ * @example
+ * ```typescript
+ * import { createMockClient, getMockManager } from 'llmist';
+ *
+ * // Setup
+ * const client = createMockClient({ strictMode: true });
+ * const mockManager = getMockManager();
+ *
+ * // Register mocks
+ * mockManager.register({
+ *   matcher: (ctx) => ctx.modelName === 'gpt-4',
+ *   response: { text: 'Mocked response' }
+ * });
+ *
+ * // Use in tests
+ * const stream = client.stream({
+ *   model: 'mock:gpt-4',
+ *   messages: [{ role: 'user', content: 'test' }]
+ * });
+ * ```
+ */
+declare function createMockClient(options?: MockOptions): LLMist;
+
+/**
+ * Global singleton instance for managing LLM mocks.
+ * This allows mocks to be registered once and used across the application.
+ */
+declare class MockManager {
+    private static instance;
+    private mocks;
+    private stats;
+    private options;
+    private logger;
+    private nextId;
+    private constructor();
+    /**
+     * Get the global MockManager instance.
+     * Creates one if it doesn't exist.
+     */
+    static getInstance(options?: MockOptions): MockManager;
+    /**
+     * Reset the global instance (useful for testing).
+     */
+    static reset(): void;
+    /**
+     * Register a new mock.
+     *
+     * @param registration - The mock registration configuration
+     * @returns The ID of the registered mock
+     *
+     * @example
+     * const manager = MockManager.getInstance();
+     * const mockId = manager.register({
+     *   label: 'GPT-4 mock',
+     *   matcher: (ctx) => ctx.modelName.includes('gpt-4'),
+     *   response: { text: 'Mocked response' }
+     * });
+     */
+    register(registration: Omit<MockRegistration, "id"> & {
+        id?: string;
+    }): string;
+    /**
+     * Unregister a mock by ID.
+     */
+    unregister(id: string): boolean;
+    /**
+     * Clear all registered mocks.
+     */
+    clear(): void;
+    /**
+     * Find and return a matching mock for the given context.
+     * Returns the mock response if found, null otherwise.
+     */
+    findMatch(context: MockMatcherContext): Promise<MockResponse | null>;
+    /**
+     * Get statistics for a specific mock.
+     */
+    getStats(id: string): MockStats | undefined;
+    /**
+     * Get all registered mock IDs.
+     */
+    getMockIds(): string[];
+    /**
+     * Get the number of registered mocks.
+     */
+    getCount(): number;
+    /**
+     * Update the mock manager options.
+     */
+    setOptions(options: Partial<MockOptions>): void;
+}
+/**
+ * Helper function to get the global mock manager instance.
+ */
+declare function getMockManager(options?: MockOptions): MockManager;
+
+/**
+ * Create a mock LLM stream from a mock response.
+ * This simulates the streaming behavior of real LLM providers.
+ *
+ * @param response - The mock response configuration
+ * @returns An async iterable that yields LLMStreamChunks
+ */
+declare function createMockStream(response: MockResponse): LLMStream;
+/**
+ * Create a simple text-only mock stream.
+ * Convenience helper for quickly creating mock responses.
+ *
+ * @param text - The text to stream
+ * @param options - Optional streaming configuration
+ *
+ * @example
+ * const stream = createTextMockStream('Hello, world!');
+ * for await (const chunk of stream) {
+ *   console.log(chunk.text);
+ * }
+ */
+declare function createTextMockStream(text: string, options?: {
+    delayMs?: number;
+    streamDelayMs?: number;
+    usage?: MockResponse["usage"];
+}): LLMStream;
+
+export { type ObserveGadgetCompleteContext as $, type AgentHooks as A, BaseGadget as B, type AfterGadgetExecutionAction as C, type AfterGadgetExecutionControllerContext as D, type EventHandlers as E, type AfterLLMCallAction as F, GadgetRegistry as G, type HistoryMessage as H, type AfterLLMCallControllerContext as I, type AfterLLMErrorAction as J, type AgentOptions as K, type LLMMessage as L, MockProviderAdapter as M, type BeforeGadgetExecutionAction as N, type BeforeLLMCallAction as O, type ParameterFormat as P, type ChunkInterceptorContext as Q, type Controllers as R, type StreamEvent as S, type GadgetExecutionControllerContext as T, type GadgetParameterInterceptorContext as U, type GadgetResultInterceptorContext as V, type Interceptors as W, type LLMCallControllerContext as X, type LLMErrorControllerContext as Y, type MessageInterceptorContext as Z, type ObserveChunkContext as _, MockBuilder as a, type ObserveGadgetStartContext as a0, type ObserveLLMCallContext as a1, type ObserveLLMCompleteContext as a2, type ObserveLLMErrorContext as a3, type Observers as a4, type LLMistOptions as a5, LLMist as a6, type LLMRole as a7, LLMMessageBuilder as a8, type CostEstimate as a9, type ModelFeatures as aa, type ModelLimits as ab, type ModelPricing as ac, ModelRegistry as ad, type ProviderIdentifier as ae, type TokenUsage as af, ModelIdentifierParser as ag, type PromptConfig as ah, type PromptContext as ai, type PromptTemplate as aj, DEFAULT_PROMPTS as ak, resolvePromptTemplate as al, resolveRulesTemplate as am, type QuickOptions as an, complete as ao, stream as ap, StreamParser as aq, type GadgetClass as ar, type GadgetOrClass as as, type TextOnlyAction as at, type TextOnlyContext as au, type TextOnlyCustomHandler as av, type TextOnlyGadgetConfig as aw, type TextOnlyHandler as ax, type TextOnlyStrategy as ay, createMockClient as b, createMockAdapter as c, MockManager as d, createMockStream as e, createTextMockStream as f, getMockManager as g, type MockMatcher as h, type MockMatcherContext as i, type MockOptions as j, type MockRegistration as k, type MockResponse as l, mockLLM as m, type MockStats as n, type LLMStreamChunk as o, type ParsedGadgetCall as p, type GadgetExecutionResult as q, type ProviderAdapter as r, type ModelDescriptor as s, type ModelSpec as t, type LLMGenerationOptions as u, type LLMStream as v, AgentBuilder as w, collectEvents as x, collectText as y, runWithHandlers as z };