@llmist/testing 9.0.0

package/dist/index.d.ts

@@ -0,0 +1,1422 @@
+import { PassThrough, Readable, Writable } from 'node:stream';
+import { LLMMessage, AbstractGadget, LLMGenerationOptions, ImageMimeType, AudioMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, LLMStreamChunk } from 'llmist';
+import { ZodType } from 'zod';
+
+/**
+ * CLI testing utilities for llmist.
+ * Provides helpers for testing CLI commands without real I/O.
+ */
+
+/**
+ * Options for creating a test environment.
+ */
+interface TestEnvironmentOptions {
+    /** Input to provide via stdin (string or line array) */
+    stdin?: string | string[];
+    /** Whether stdin is a TTY (default: false) */
+    isTTY?: boolean;
+    /** Environment variables to set */
+    env?: Record<string, string>;
+    /** Command line arguments (default: ["node", "llmist"]) */
+    argv?: string[];
+}
+/**
+ * A test environment with captured I/O streams.
+ */
+interface TestEnvironment {
+    /** Stdin readable stream */
+    stdin: Readable;
+    /** Stdout writable stream (PassThrough for capturing) */
+    stdout: PassThrough;
+    /** Stderr writable stream (PassThrough for capturing) */
+    stderr: PassThrough;
+    /** Whether stdin is TTY */
+    isTTY: boolean;
+    /** Command line arguments */
+    argv: string[];
+    /** Environment variables */
+    env: Record<string, string>;
+    /** Exit code if set */
+    exitCode?: number;
+    /** Function to set exit code */
+    setExitCode: (code: number) => void;
+}
+/**
+ * Create a test environment with mocked I/O streams.
+ *
+ * @param options - Configuration options
+ * @returns A test environment with captured streams
+ *
+ * @example
+ * ```typescript
+ * const env = createTestEnvironment({
+ *   stdin: '{"param": "value"}',
+ *   isTTY: false
+ * });
+ *
+ * // Pass to CLI command
+ * await executeCommand(env);
+ *
+ * // Check output
+ * const output = await collectOutput(env.stdout);
+ * expect(output).toContain("Success");
+ * ```
+ */
+declare function createTestEnvironment(options?: TestEnvironmentOptions): TestEnvironment;
+/**
+ * Create a readable stream from a string or array of lines.
+ *
+ * @param input - String content or array of lines
+ * @returns A Readable stream
+ *
+ * @example
+ * ```typescript
+ * const stream = createMockReadable("line1\nline2\n");
+ * // or
+ * const stream = createMockReadable(["line1", "line2"]);
+ * ```
+ */
+declare function createMockReadable(input?: string | string[]): Readable;
+/**
+ * Create a writable stream that collects all written data.
+ *
+ * @returns A writable stream with getData() method
+ */
+declare function createMockWritable(): Writable & {
+    getData(): string;
+};
+/**
+ * Collect all output from a PassThrough stream.
+ * Waits for the stream to end before returning.
+ *
+ * @param stream - The stream to collect from
+ * @param timeout - Maximum time to wait in ms (default: 5000)
+ * @returns All data written to the stream
+ *
+ * @example
+ * ```typescript
+ * const output = await collectOutput(env.stdout);
+ * expect(output).toContain("Expected text");
+ * ```
+ */
+declare function collectOutput(stream: PassThrough, timeout?: number): Promise<string>;
+/**
+ * Collect output without waiting for stream end.
+ * Returns immediately with whatever has been written.
+ *
+ * @param stream - The stream to read from
+ * @returns Currently buffered data
+ */
+declare function getBufferedOutput(stream: PassThrough): string;
+/**
+ * Create a mock prompt function for testing interactive input.
+ *
+ * @param responses - Array of responses to return in order
+ * @returns A prompt function that returns the next response
+ *
+ * @example
+ * ```typescript
+ * const prompt = createMockPrompt(["yes", "no", "maybe"]);
+ * expect(await prompt("Question 1?")).toBe("yes");
+ * expect(await prompt("Question 2?")).toBe("no");
+ * ```
+ */
+declare function createMockPrompt(responses: string[]): (question: string) => Promise<string>;
+/**
+ * Mock prompt that records questions and returns configured responses.
+ */
+declare class MockPromptRecorder {
+    private responses;
+    private index;
+    private questions;
+    constructor(responses: string[]);
+    /**
+     * The prompt function to use in tests.
+     */
+    prompt: (question: string) => Promise<string>;
+    /**
+     * Get all questions that were asked.
+     */
+    getQuestions(): string[];
+    /**
+     * Get the number of questions asked.
+     */
+    getQuestionCount(): number;
+    /**
+     * Reset the recorder state.
+     */
+    reset(newResponses?: string[]): void;
+}
+/**
+ * Wait for a condition to be true, with timeout.
+ * Useful for async testing scenarios.
+ *
+ * @param condition - Function that returns true when condition is met
+ * @param timeout - Maximum time to wait in ms (default: 5000)
+ * @param interval - Check interval in ms (default: 50)
+ */
+declare function waitFor(condition: () => boolean, timeout?: number, interval?: number): Promise<void>;
+
+/**
+ * Conversation fixture generators for testing.
+ * Provides utilities for creating test conversation data.
+ */
+
+/**
+ * Create a conversation with a specified number of turns.
+ * Each turn consists of a user message and an assistant response.
+ *
+ * @param turnCount - Number of conversation turns to generate
+ * @param options - Configuration options
+ * @returns Array of LLMMessages representing the conversation
+ *
+ * @example
+ * ```typescript
+ * const messages = createConversation(5);
+ * // Creates 10 messages: 5 user + 5 assistant
+ * ```
+ */
+declare function createConversation(turnCount: number, options?: {
+    /** Prefix for user messages (default: "User message") */
+    userPrefix?: string;
+    /** Prefix for assistant messages (default: "Assistant response") */
+    assistantPrefix?: string;
+    /** Base content length per message (default: 100 chars) */
+    contentLength?: number;
+}): LLMMessage[];
+/**
+ * Create a conversation with gadget calls interspersed.
+ * Simulates an agent conversation with tool usage.
+ *
+ * @param turnCount - Number of conversation turns
+ * @param gadgetCallsPerTurn - Number of gadget calls per assistant turn
+ * @returns Array of LLMMessages including gadget call/result pairs
+ *
+ * @example
+ * ```typescript
+ * const messages = createConversationWithGadgets(3, 2);
+ * // Creates: user, assistant+gadget, gadget-result, assistant+gadget, gadget-result, assistant (per turn)
+ * ```
+ */
+declare function createConversationWithGadgets(turnCount: number, gadgetCallsPerTurn?: number, options?: {
+    /** Gadget names to cycle through (default: ["search", "calculate", "read"]) */
+    gadgetNames?: string[];
+    /** Content length for messages */
+    contentLength?: number;
+}): LLMMessage[];
+/**
+ * Estimate token count for a message array.
+ * Uses a simple 4-characters-per-token heuristic.
+ *
+ * @param messages - Messages to estimate tokens for
+ * @returns Estimated token count
+ *
+ * @example
+ * ```typescript
+ * const messages = createConversation(10);
+ * const tokens = estimateTokens(messages);
+ * // Returns approximate token count
+ * ```
+ */
+declare function estimateTokens(messages: LLMMessage[]): number;
+/**
+ * Create a single user message.
+ */
+declare function createUserMessage(content: string): LLMMessage;
+/**
+ * Create a single assistant message.
+ */
+declare function createAssistantMessage(content: string): LLMMessage;
+/**
+ * Create a system message.
+ */
+declare function createSystemMessage(content: string): LLMMessage;
+/**
+ * Create a minimal conversation for quick tests.
+ * Returns a single turn: one user message and one assistant response.
+ */
+declare function createMinimalConversation(): LLMMessage[];
+/**
+ * Create a conversation that exceeds a target token count.
+ * Useful for testing compaction triggers.
+ *
+ * @param targetTokens - Minimum token count to exceed
+ * @param options - Configuration options
+ * @returns Conversation with at least targetTokens tokens
+ */
+declare function createLargeConversation(targetTokens: number, options?: {
+    /** Average tokens per turn (default: 200) */
+    tokensPerTurn?: number;
+}): LLMMessage[];
+
+/**
+ * Testing utilities for gadgets.
+ *
+ * Provides helpers for testing gadgets with schema validation without
+ * requiring full executor setup.
+ *
+ * @module testing/gadget-testing
+ */
+
+/**
+ * Result of testing a gadget.
+ */
+interface TestGadgetResult {
+    /** Result string if execution succeeded */
+    result?: string;
+    /** Error message if validation or execution failed */
+    error?: string;
+    /** Parameters after validation and default application */
+    validatedParams?: Record<string, unknown>;
+    /** Cost reported by the gadget in USD (e.g., 0.001 for $0.001) */
+    cost?: number;
+}
+/**
+ * Options for testGadget.
+ */
+interface TestGadgetOptions {
+    /**
+     * If true, skip schema validation.
+     * Useful for testing gadget behavior with invalid parameters.
+     */
+    skipValidation?: boolean;
+}
+/**
+ * Test a gadget with schema validation and default application.
+ *
+ * This helper replicates the validation behavior from GadgetExecutor.execute(),
+ * making it easy to test gadgets in isolation without setting up a full
+ * registry and executor.
+ *
+ * @param gadget - Gadget instance to test
+ * @param params - Raw parameters (before validation)
+ * @param options - Test options
+ * @returns Promise resolving to test result
+ *
+ * @example
+ * ```typescript
+ * import { testGadget } from 'llmist/testing';
+ * import { createGadget } from 'llmist';
+ * import { z } from 'zod';
+ *
+ * const calculator = createGadget({
+ *   description: 'Add numbers',
+ *   schema: z.object({
+ *     a: z.number(),
+ *     b: z.number().default(0),
+ *   }),
+ *   execute: ({ a, b }) => String(a + b),
+ * });
+ *
+ * // Test with defaults applied
+ * const result = await testGadget(calculator, { a: 5 });
+ * expect(result.result).toBe('5');
+ * expect(result.validatedParams).toEqual({ a: 5, b: 0 });
+ *
+ * // Test validation errors
+ * const invalid = await testGadget(calculator, { a: 'not a number' });
+ * expect(invalid.error).toContain('Invalid parameters');
+ *
+ * // Test with validation skipped
+ * const skipped = await testGadget(calculator, { a: 5 }, { skipValidation: true });
+ * expect(skipped.validatedParams).toEqual({ a: 5 }); // No defaults applied
+ * ```
+ */
+declare function testGadget(gadget: AbstractGadget, params: Record<string, unknown>, options?: TestGadgetOptions): Promise<TestGadgetResult>;
+/**
+ * Test multiple parameter sets against a gadget.
+ *
+ * Convenience helper for running the same gadget with different inputs.
+ *
+ * @param gadget - Gadget instance to test
+ * @param paramSets - Array of parameter sets to test
+ * @param options - Test options applied to all tests
+ * @returns Promise resolving to array of test results
+ *
+ * @example
+ * ```typescript
+ * const results = await testGadgetBatch(calculator, [
+ *   { a: 1, b: 2 },
+ *   { a: 5 },
+ *   { a: 'invalid' },
+ * ]);
+ *
+ * expect(results[0].result).toBe('3');
+ * expect(results[1].result).toBe('5');
+ * expect(results[2].error).toBeDefined();
+ * ```
+ */
+declare function testGadgetBatch(gadget: AbstractGadget, paramSets: Record<string, unknown>[], options?: TestGadgetOptions): Promise<TestGadgetResult[]>;
+
+/**
+ * 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>;
+/**
+ * Image data in a mock response.
+ */
+interface MockImageData {
+    /** Base64-encoded image data */
+    data: string;
+    /** MIME type of the image */
+    mimeType: ImageMimeType;
+    /** Revised prompt (for image generation responses) */
+    revisedPrompt?: string;
+}
+/**
+ * Audio data in a mock response.
+ */
+interface MockAudioData {
+    /** Base64-encoded audio data */
+    data: string;
+    /** MIME type of the audio */
+    mimeType: AudioMimeType;
+}
+/**
+ * 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;
+    }>;
+    /**
+     * Image data to return in the response (e.g., for image generation mocks).
+     * Each image will be yielded as a separate chunk in the stream.
+     */
+    images?: MockImageData[];
+    /**
+     * Audio data to return in the response (e.g., for speech synthesis mocks).
+     * Will be yielded as a chunk in the stream.
+     */
+    audio?: MockAudioData;
+    /**
+     * 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;
+    /**
+     * Check if this adapter supports image generation for a given model.
+     * Returns true if there's a registered mock with images for this model.
+     */
+    supportsImageGeneration(_modelId: string): boolean;
+    /**
+     * Generate mock images based on registered mocks.
+     *
+     * @param options - Image generation options
+     * @returns Mock image generation result
+     */
+    generateImage(options: ImageGenerationOptions): Promise<ImageGenerationResult>;
+    /**
+     * Transform mock response into ImageGenerationResult format.
+     *
+     * @param options - Original image generation options
+     * @param mockResponse - Mock response containing image data
+     * @returns ImageGenerationResult with mock data and zero cost
+     */
+    private createImageResult;
+    /**
+     * Check if this adapter supports speech generation for a given model.
+     * Returns true if there's a registered mock with audio for this model.
+     */
+    supportsSpeechGeneration(_modelId: string): boolean;
+    /**
+     * Generate mock speech based on registered mocks.
+     *
+     * @param options - Speech generation options
+     * @returns Mock speech generation result
+     */
+    generateSpeech(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
+    /**
+     * Transform mock response into SpeechGenerationResult format.
+     * Converts base64 audio data to ArrayBuffer.
+     *
+     * @param options - Original speech generation options
+     * @param mockResponse - Mock response containing audio data
+     * @returns SpeechGenerationResult with mock data and zero cost
+     */
+    private createSpeechResult;
+    /**
+     * Map MIME type to audio format for SpeechGenerationResult.
+     * Defaults to "mp3" for unknown MIME types.
+     *
+     * @param mimeType - Audio MIME type string
+     * @returns Audio format identifier
+     */
+    private mimeTypeToAudioFormat;
+}
+/**
+ * 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;
+    /**
+     * Match when any message contains an image.
+     *
+     * @example
+     * mockLLM().whenMessageHasImage().returns("I see an image of a sunset.")
+     */
+    whenMessageHasImage(): this;
+    /**
+     * Match when any message contains audio.
+     *
+     * @example
+     * mockLLM().whenMessageHasAudio().returns("I hear music playing.")
+     */
+    whenMessageHasAudio(): this;
+    /**
+     * Match based on the number of images in the last message.
+     *
+     * @example
+     * mockLLM().whenImageCount((n) => n >= 2).returns("Comparing multiple images...")
+     */
+    whenImageCount(predicate: (count: number) => boolean): 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;
+    /**
+     * Return a single image in the response.
+     * Useful for mocking image generation endpoints.
+     *
+     * @param data - Image data (base64 string or Buffer)
+     * @param mimeType - MIME type (auto-detected if Buffer provided without type)
+     *
+     * @example
+     * mockLLM()
+     *   .forModel('dall-e-3')
+     *   .returnsImage(pngBuffer)
+     *   .register();
+     */
+    returnsImage(data: string | Buffer | Uint8Array, mimeType?: ImageMimeType): this;
+    /**
+     * Return multiple images in the response.
+     *
+     * @example
+     * mockLLM()
+     *   .forModel('dall-e-3')
+     *   .returnsImages([
+     *     { data: pngBuffer1 },
+     *     { data: pngBuffer2 },
+     *   ])
+     *   .register();
+     */
+    returnsImages(images: Array<{
+        data: string | Buffer | Uint8Array;
+        mimeType?: ImageMimeType;
+        revisedPrompt?: string;
+    }>): this;
+    /**
+     * Return audio data in the response.
+     * Useful for mocking speech synthesis endpoints.
+     *
+     * @param data - Audio data (base64 string or Buffer)
+     * @param mimeType - MIME type (auto-detected if Buffer provided without type)
+     *
+     * @example
+     * mockLLM()
+     *   .forModel('tts-1')
+     *   .returnsAudio(mp3Buffer)
+     *   .register();
+     */
+    returnsAudio(data: string | Buffer | Uint8Array, mimeType?: AudioMimeType): 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;
+
+/**
+ * Mock ConversationManager for testing compaction and agent components.
+ * Implements IConversationManager interface with test-friendly features.
+ */
+
+/**
+ * A mock implementation of IConversationManager for testing.
+ * Tracks all operations and allows inspection of state changes.
+ *
+ * @example
+ * ```typescript
+ * const mockConvo = new MockConversationManager([
+ *   { role: "user", content: "Hello" },
+ *   { role: "assistant", content: "Hi!" }
+ * ]);
+ *
+ * // Use in compaction tests
+ * compactionManager.checkAndCompact(mockConvo, 1);
+ *
+ * // Assert on state changes
+ * expect(mockConvo.wasReplaceHistoryCalled()).toBe(true);
+ * expect(mockConvo.getReplacementHistory()).toHaveLength(2);
+ * ```
+ */
+declare class MockConversationManager implements IConversationManager {
+    private history;
+    private readonly baseMessages;
+    private replacementHistory;
+    private replaceHistoryCallCount;
+    private addedMessages;
+    constructor(history?: LLMMessage[], baseMessages?: LLMMessage[]);
+    addUserMessage(content: string): void;
+    addAssistantMessage(content: string): void;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string): void;
+    getMessages(): LLMMessage[];
+    getHistoryMessages(): LLMMessage[];
+    getBaseMessages(): LLMMessage[];
+    getConversationHistory(): LLMMessage[];
+    replaceHistory(newHistory: LLMMessage[]): void;
+    /**
+     * Check if replaceHistory was called.
+     */
+    wasReplaceHistoryCalled(): boolean;
+    /**
+     * Get the number of times replaceHistory was called.
+     */
+    getReplaceHistoryCallCount(): number;
+    /**
+     * Get the most recent history passed to replaceHistory.
+     * Returns undefined if replaceHistory was never called.
+     */
+    getReplacementHistory(): LLMMessage[] | undefined;
+    /**
+     * Get all messages that were added via add* methods.
+     */
+    getAddedMessages(): LLMMessage[];
+    /**
+     * Reset all tracking state while preserving the conversation.
+     */
+    resetTracking(): void;
+    /**
+     * Completely reset the mock to initial state.
+     * Note: baseMessages cannot be changed after construction.
+     */
+    reset(history?: LLMMessage[]): void;
+    /**
+     * Set the history directly (for test setup).
+     */
+    setHistory(messages: LLMMessage[]): void;
+    /**
+     * Get the current history length.
+     */
+    getHistoryLength(): number;
+    /**
+     * Get total message count (base + history).
+     */
+    getTotalMessageCount(): number;
+}
+/**
+ * Create a mock conversation manager with a pre-populated conversation.
+ *
+ * @param turnCount - Number of conversation turns
+ * @param baseMessages - Optional base messages (system prompts)
+ * @returns Configured MockConversationManager
+ */
+declare function createMockConversationManager(turnCount: number, baseMessages?: LLMMessage[]): MockConversationManager;
+
+/**
+ * Mock gadget utilities for testing.
+ *
+ * Provides helpers for creating mock gadgets with configurable behavior
+ * and call tracking.
+ *
+ * @module testing/mock-gadget
+ */
+
+/**
+ * Recorded gadget call for tracking.
+ */
+interface RecordedCall {
+    /** Parameters passed to execute() */
+    params: Record<string, unknown>;
+    /** When the call was made */
+    timestamp: number;
+}
+/**
+ * Mock gadget with call tracking capabilities.
+ */
+interface MockGadget extends AbstractGadget {
+    /** Get all recorded calls */
+    getCalls(): RecordedCall[];
+    /** Get number of times the gadget was executed */
+    getCallCount(): number;
+    /** Reset call history */
+    resetCalls(): void;
+    /** Check if gadget was called with specific params (partial match) */
+    wasCalledWith(params: Partial<Record<string, unknown>>): boolean;
+    /** Get the last call's parameters */
+    getLastCall(): RecordedCall | undefined;
+}
+/**
+ * Configuration for creating a mock gadget.
+ */
+interface MockGadgetConfig<TSchema extends ZodType = ZodType> {
+    /** Gadget name (required) */
+    name: string;
+    /** Gadget description */
+    description?: string;
+    /** Parameter schema */
+    schema?: TSchema;
+    /** Static result to return */
+    result?: string;
+    /** Dynamic result based on parameters */
+    resultFn?: (params: Record<string, unknown>) => string | Promise<string>;
+    /** Error to throw on execution */
+    error?: Error | string;
+    /** Enable call tracking (default: true) */
+    trackCalls?: boolean;
+    /** Execution delay in ms */
+    delayMs?: number;
+    /** Gadget timeout setting */
+    timeoutMs?: number;
+}
+/**
+ * Create a mock gadget for testing.
+ *
+ * @param config - Mock gadget configuration
+ * @returns MockGadget instance with call tracking
+ *
+ * @example
+ * ```typescript
+ * import { createMockGadget } from 'llmist/testing';
+ * import { z } from 'zod';
+ *
+ * const calculator = createMockGadget({
+ *   name: 'Calculator',
+ *   schema: z.object({ a: z.number(), b: z.number() }),
+ *   resultFn: ({ a, b }) => String(Number(a) + Number(b)),
+ * });
+ *
+ * // Use in tests
+ * const registry = new GadgetRegistry();
+ * registry.registerByClass(calculator);
+ *
+ * // After running agent...
+ * expect(calculator.getCallCount()).toBe(1);
+ * expect(calculator.wasCalledWith({ a: 5 })).toBe(true);
+ * ```
+ */
+declare function createMockGadget<TSchema extends ZodType>(config: MockGadgetConfig<TSchema>): MockGadget;
+/**
+ * Fluent builder for creating mock gadgets.
+ *
+ * @example
+ * ```typescript
+ * import { mockGadget } from 'llmist/testing';
+ * import { z } from 'zod';
+ *
+ * const mock = mockGadget()
+ *   .withName('Weather')
+ *   .withDescription('Get weather for a city')
+ *   .withSchema(z.object({ city: z.string() }))
+ *   .returns('Sunny, 72F')
+ *   .trackCalls()
+ *   .build();
+ *
+ * // Or for error testing
+ * const errorMock = mockGadget()
+ *   .withName('Unstable')
+ *   .throws('Service unavailable')
+ *   .build();
+ * ```
+ */
+declare class MockGadgetBuilder {
+    private config;
+    /**
+     * Set the gadget name.
+     */
+    withName(name: string): this;
+    /**
+     * Set the gadget description.
+     */
+    withDescription(description: string): this;
+    /**
+     * Set the parameter schema.
+     */
+    withSchema<T extends ZodType>(schema: T): MockGadgetBuilder;
+    /**
+     * Set a static result to return.
+     */
+    returns(result: string): this;
+    /**
+     * Set a dynamic result function.
+     */
+    returnsAsync(resultFn: (params: Record<string, unknown>) => string | Promise<string>): this;
+    /**
+     * Make the gadget throw an error on execution.
+     */
+    throws(error: Error | string): this;
+    /**
+     * Add execution delay.
+     */
+    withDelay(ms: number): this;
+    /**
+     * Set timeout for the gadget.
+     */
+    withTimeout(ms: number): this;
+    /**
+     * Enable call tracking (enabled by default).
+     */
+    trackCalls(): this;
+    /**
+     * Disable call tracking.
+     */
+    noTracking(): this;
+    /**
+     * Build the mock gadget.
+     */
+    build(): MockGadget;
+}
+/**
+ * Create a fluent builder for mock gadgets.
+ *
+ * @returns New MockGadgetBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const mock = mockGadget()
+ *   .withName('Search')
+ *   .withSchema(z.object({ query: z.string() }))
+ *   .returnsAsync(async ({ query }) => {
+ *     return `Results for: ${query}`;
+ *   })
+ *   .build();
+ * ```
+ */
+declare function mockGadget(): MockGadgetBuilder;
+
+/**
+ * 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;
+
+/**
+ * Stream testing utilities for llmist.
+ * Provides helpers for creating and consuming test streams.
+ */
+
+/**
+ * Create an async iterable stream from an array of chunks.
+ * Useful for creating deterministic test streams.
+ *
+ * @param chunks - Array of chunks to yield
+ * @returns An async iterable that yields the chunks in order
+ *
+ * @example
+ * ```typescript
+ * const stream = createTestStream([
+ *   { text: "Hello " },
+ *   { text: "world", finishReason: "stop", usage: { inputTokens: 10, outputTokens: 5 } }
+ * ]);
+ * ```
+ */
+declare function createTestStream(chunks: LLMStreamChunk[]): LLMStream;
+/**
+ * Create a stream that yields text in specified chunks.
+ * Automatically adds finishReason and usage to the final chunk.
+ *
+ * @param text - The full text to stream
+ * @param options - Configuration options
+ * @returns An async iterable stream
+ *
+ * @example
+ * ```typescript
+ * const stream = createTextStream("Hello, world!", { chunkSize: 5 });
+ * // Yields: "Hello", ", wor", "ld!"
+ * ```
+ */
+declare function createTextStream(text: string, options?: {
+    /** Size of each chunk (default: entire text as one chunk) */
+    chunkSize?: number;
+    /** Delay before starting the stream in ms */
+    delayMs?: number;
+    /** Delay between chunks in ms */
+    chunkDelayMs?: number;
+    /** Custom usage stats */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    /** Custom finish reason (default: "stop") */
+    finishReason?: string;
+}): LLMStream;
+/**
+ * Collect all chunks from a stream into an array.
+ * Useful for asserting on stream output in tests.
+ *
+ * @param stream - The stream to collect from
+ * @returns Array of all chunks from the stream
+ *
+ * @example
+ * ```typescript
+ * const chunks = await collectStream(myStream);
+ * expect(chunks).toHaveLength(3);
+ * expect(chunks[2].finishReason).toBe("stop");
+ * ```
+ */
+declare function collectStream(stream: LLMStream): Promise<LLMStreamChunk[]>;
+/**
+ * Collect all text from a stream into a single string.
+ *
+ * @param stream - The stream to collect from
+ * @returns Concatenated text from all chunks
+ *
+ * @example
+ * ```typescript
+ * const text = await collectStreamText(myStream);
+ * expect(text).toBe("Hello, world!");
+ * ```
+ */
+declare function collectStreamText(stream: LLMStream): Promise<string>;
+/**
+ * Get the final chunk from a stream (containing finishReason and usage).
+ *
+ * @param stream - The stream to consume
+ * @returns The final chunk from the stream
+ */
+declare function getStreamFinalChunk(stream: LLMStream): Promise<LLMStreamChunk | undefined>;
+/**
+ * Create an empty stream that yields nothing.
+ * Useful for testing edge cases.
+ */
+declare function createEmptyStream(): LLMStream;
+/**
+ * Create a stream that throws an error after yielding some chunks.
+ * Useful for testing error handling.
+ *
+ * @param chunksBeforeError - Chunks to yield before throwing
+ * @param error - The error to throw
+ */
+declare function createErrorStream(chunksBeforeError: LLMStreamChunk[], error: Error): LLMStream;
+
+export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, type MockStats, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, testGadget, testGadgetBatch, waitFor };