llmist 7.0.0 → 8.0.0

package/dist/testing/index.d.cts

@@ -1,710 +0,0 @@
-import { PassThrough, Readable, Writable } from 'node:stream';
-import { L as LLMMessage, A as AbstractGadget, I as IConversationManager, a as LLMStream, b as LLMStreamChunk } from '../mock-stream-r5vjy2Iq.cjs';
-export { j as MockAudioData, d as MockBuilder, k as MockImageData, f as MockManager, l as MockMatcher, n as MockMatcherContext, o as MockOptions, M as MockProviderAdapter, p as MockRegistration, q as MockResponse, r as MockStats, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM } from '../mock-stream-r5vjy2Iq.cjs';
-import { ZodType } from 'zod';
-import 'tslog';
-
-/**
- * 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[]>;
-
-/**
- * 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[];
-    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;
-
-/**
- * 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 { MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, MockPromptRecorder, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getStreamFinalChunk, mockGadget, testGadget, testGadgetBatch, waitFor };