@agtlantis/core 0.4.1

package/dist/testing/index.d.ts

@@ -0,0 +1,516 @@
+import { af as LLMCallRecord, ad as ToolCallSummary, ag as AdditionalCost, ah as SessionSummary, m as CompletionEvent, S as StreamingExecution, f as SessionEvent, E as ErrorEvent, p as FileManager, L as Logger, B as BaseProvider, b as ProviderPricing, j as SimpleSession, d as StreamingSession, h as ExtractResult, v as EmittableEventInput } from '../base-provider-C3mFLNiN.js';
+import { LanguageModelUsage, LanguageModel } from 'ai';
+import { MockLanguageModelV3 } from 'ai/test';
+export { MockLanguageModelV3, simulateReadableStream } from 'ai/test';
+import 'zod';
+
+declare const TEST_API_KEY = "test-api-key";
+declare function createMockUsage$1(overrides?: Partial<LanguageModelUsage>): LanguageModelUsage;
+interface TestBaseEvent$1 {
+    type: string;
+    message?: string;
+    data?: string;
+}
+type TestEvent$1 = TestBaseEvent$1 | CompletionEvent<string>;
+interface TestResult {
+    value: string;
+}
+declare function createTestEvent(type: string, overrides?: Partial<Omit<TestBaseEvent$1, 'type'>>): TestBaseEvent$1;
+interface MockSessionSummaryOptions {
+    /** @deprecated Use startTime instead. totalDuration is computed from startTime. */
+    totalDuration?: number;
+    startTime?: number;
+    totalLLMUsage?: LanguageModelUsage;
+    /** @deprecated Provide llmCalls array instead. llmCallCount creates dummy records. */
+    llmCallCount?: number;
+    llmCalls?: LLMCallRecord[];
+    toolCalls?: ToolCallSummary[];
+    customRecords?: Record<string, unknown>[];
+    /** @deprecated Use llmCost instead */
+    totalCost?: number;
+    llmCost?: number;
+    additionalCosts?: AdditionalCost[];
+    metadata?: Record<string, unknown>;
+    costByModel?: Record<string, number>;
+}
+declare function createMockSessionSummary(overrides?: MockSessionSummaryOptions): SessionSummary;
+
+/**
+ * Collects all events from a StreamingExecution into an array.
+ * Works with both StreamingExecution (via .stream()) and raw AsyncIterable.
+ */
+declare function collectEvents$1<T extends {
+    type: string;
+}>(execution: StreamingExecution<T>): Promise<SessionEvent<T | ErrorEvent>[]>;
+declare function collectEvents$1<T extends {
+    type: string;
+}>(execution: AsyncIterable<SessionEvent<T>>): Promise<SessionEvent<T>[]>;
+/**
+ * Drains a StreamingExecution or AsyncIterable without storing events.
+ */
+declare function consumeExecution<T extends {
+    type: string;
+}>(execution: StreamingExecution<T> | AsyncIterable<SessionEvent<T>>): Promise<void>;
+declare function expectFileManagerInterface(obj: unknown): asserts obj is FileManager;
+
+/**
+ * MockProvider - Test provider for @agtlantis/core.
+ *
+ * Extends BaseProvider to provide mock LLM responses with call tracking.
+ * Use `mock.provider()` factory for convenient creation.
+ *
+ * @example
+ * ```typescript
+ * import { mock } from '@agtlantis/core/testing';
+ *
+ * const provider = mock.provider(mock.text('Hello!'));
+ * const execution = provider.simpleExecution(async (session) => {
+ *   const { text } = await session.generateText({ prompt: 'Say hi' });
+ *   return text;
+ * });
+ *
+ * expect(await execution.toResult()).toBe('Hello!');
+ * expect(provider.getCalls()).toHaveLength(1);
+ * ```
+ */
+
+type ModelFactory = (modelId: string) => MockLanguageModelV3;
+interface MockProviderConfig {
+    model?: MockLanguageModelV3;
+    modelFactory?: ModelFactory;
+    fileManager?: FileManager;
+    logger?: Logger;
+    providerType?: string;
+}
+interface MockCall {
+    modelId: string;
+    type: 'generate' | 'stream';
+    timestamp: number;
+    params: unknown;
+}
+declare class MockProvider extends BaseProvider {
+    private readonly calls;
+    private readonly modelSource;
+    private readonly fileManagerInstance;
+    private readonly loggerInstance;
+    private readonly defaultModelId;
+    private readonly pricingConfig?;
+    private readonly providerTypeId;
+    constructor(config: MockProviderConfig);
+    /**
+     * Creates instance for fluent API without calling constructor.
+     * Shares calls array between fluent instances for tracking.
+     */
+    private static createWithConfig;
+    getCalls(): MockCall[];
+    clearCalls(): void;
+    withDefaultModel(modelId: string): MockProvider;
+    withLogger(logger: Logger): MockProvider;
+    withPricing(pricing: ProviderPricing): MockProvider;
+    /**
+     * Mock implementation - returns same provider since mocks don't use provider options.
+     */
+    withDefaultOptions(_options: Record<string, unknown>): MockProvider;
+    protected createSimpleSession(signal?: AbortSignal): SimpleSession;
+    protected createStreamingSession<TEvent extends {
+        type: string;
+    }>(signal?: AbortSignal): StreamingSession<TEvent>;
+    private buildSessionConfig;
+    private getBaseModel;
+    private createTrackingModel;
+}
+declare function createMockProvider(configOrModel: MockProviderConfig | MockLanguageModelV3 | ModelFactory): MockProvider;
+
+/**
+ * Mock factory functions for AI SDK testing.
+ *
+ * Provides convenient helpers to create MockLanguageModelV3 instances
+ * with predefined responses for unit testing.
+ *
+ * @example
+ * import { generateText } from 'ai';
+ * import { mock } from '@agtlantis/core/testing';
+ *
+ * const result = await generateText({
+ *   model: mock.text('Hello, world!'),
+ *   prompt: 'Say hello',
+ * });
+ */
+
+type DoGenerateResult = Awaited<ReturnType<MockLanguageModelV3['doGenerate']>>;
+type ResponseOptions = Partial<Omit<DoGenerateResult, 'content'>>;
+declare const mock: {
+    /**
+     * Creates a MockLanguageModelV3 that returns text content.
+     *
+     * @param text - The text to return from generateText
+     * @param options - Optional overrides for usage, finishReason, etc.
+     *
+     * @example
+     * const model = mock.text('Hello, world!');
+     *
+     * @example
+     * // With custom usage for cost calculation tests
+     * const model = mock.text('Hello', {
+     *   usage: {
+     *     inputTokens: { total: 100 },
+     *     outputTokens: { total: 50 },
+     *   },
+     * });
+     */
+    text(text: string, options?: ResponseOptions): MockLanguageModelV3;
+    /**
+     * Creates a MockLanguageModelV3 that returns JSON content.
+     *
+     * Automatically stringifies the data. Use with generateObject or
+     * generateText + Output.object.
+     *
+     * @param data - The object to return as JSON
+     * @param options - Optional overrides for usage, finishReason, etc.
+     *
+     * @example
+     * const model = mock.json({ name: 'Alice', age: 30 });
+     */
+    json<T>(data: T, options?: ResponseOptions): MockLanguageModelV3;
+    /**
+     * Creates a MockLanguageModelV3 that streams text chunks.
+     *
+     * @param chunks - Array of text strings to stream
+     * @param options - Optional overrides for finishReason, usage, etc.
+     *
+     * @example
+     * const model = mock.stream(['Hello', ', ', 'world!']);
+     */
+    stream(chunks: string[], options?: ResponseOptions): MockLanguageModelV3;
+    /**
+     * Creates a MockLanguageModelV3 that throws an error.
+     *
+     * @param error - The error to throw
+     *
+     * @example
+     * const model = mock.error(new Error('Rate limit exceeded'));
+     *
+     * await expect(generateText({ model, prompt: 'Hi' }))
+     *   .rejects.toThrow('Rate limit exceeded');
+     */
+    error(error: Error): MockLanguageModelV3;
+    /**
+     * Creates a MockProvider with call tracking.
+     *
+     * Supports three input styles:
+     * - Single model: `mock.provider(mock.text('Hello'))`
+     * - Model factory: `mock.provider((modelId) => mock.text(modelId))`
+     * - Full config: `mock.provider({ model, fileManager, logger })`
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const provider = mock.provider(mock.text('Hello!'));
+     * const execution = provider.simpleExecution(async (session) => {
+     *   const { text } = await session.generateText({ prompt: 'Say hi' });
+     *   return text;
+     * });
+     * expect(await execution.toResult()).toBe('Hello!');
+     * expect(provider.getCalls()).toHaveLength(1);
+     *
+     * // With model factory for different responses per model
+     * const provider = mock.provider((modelId) => {
+     *   if (modelId === 'gpt-4') return mock.text('GPT-4 response');
+     *   return mock.text('Default response');
+     * });
+     * ```
+     */
+    provider(configOrModel: MockProviderConfig | MockLanguageModelV3 | ModelFactory): MockProvider;
+};
+
+/**
+ * Test helpers for execution module tests.
+ * Provides reusable utilities for abort scenarios, generator creation,
+ * and logger tracking.
+ *
+ * These helpers are framework-agnostic (no vitest/jest dependency).
+ */
+
+type LoggerEventType = 'start' | 'emit' | 'done' | 'error';
+/**
+ * Abort scenario helper for testing cancellation flows.
+ */
+interface AbortScenario {
+    /** The AbortController instance */
+    controller: AbortController;
+    /** The AbortSignal to pass to execution */
+    signal: AbortSignal;
+    /** Call to abort with optional reason */
+    abort: (reason?: string) => void;
+    /** Check if signal is aborted */
+    isAborted: () => boolean;
+}
+/**
+ * Create an abort scenario for testing cancellation.
+ *
+ * @example
+ * ```typescript
+ * const { signal, abort, isAborted } = createAbortScenario();
+ * const execution = new SimpleExecutionHost(factory, fn, signal);
+ *
+ * abort('User canceled');
+ * expect(isAborted()).toBe(true);
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * ```
+ */
+declare function createAbortScenario(): AbortScenario;
+/**
+ * Create an already-aborted signal for testing pre-aborted scenarios.
+ *
+ * @example
+ * ```typescript
+ * const signal = createAlreadyAbortedSignal('Pre-aborted');
+ * const execution = new SimpleExecutionHost(factory, fn, signal);
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * ```
+ */
+declare function createAlreadyAbortedSignal(reason?: string): AbortSignal;
+/**
+ * Create a simple generator that emits specified events and returns the result.
+ *
+ * @example
+ * ```typescript
+ * const generator = createSimpleGenerator('result-value', [
+ *   { type: 'progress', message: 'step 1' },
+ *   { type: 'progress', message: 'step 2' },
+ * ]);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ * ```
+ */
+declare function createSimpleGenerator<TEvent extends {
+    type: string;
+}>(result: ExtractResult<TEvent>, events?: EmittableEventInput<TEvent>[]): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+    done: (value: ExtractResult<TEvent>) => Promise<SessionEvent<TEvent>>;
+}) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>>, unknown>;
+/**
+ * Create a generator that throws an error.
+ *
+ * @example
+ * ```typescript
+ * const generator = createErrorGenerator(new Error('Test error'));
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * const result = await execution.result();
+ * expectFailedResult(result, 'Test error');
+ * ```
+ */
+declare function createErrorGenerator<TEvent extends {
+    type: string;
+}>(error: Error, eventsBeforeError?: EmittableEventInput<TEvent>[]): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+}) => AsyncGenerator<SessionEvent<TEvent>, never, unknown>;
+/**
+ * Create a generator that waits for cancellation using closure pattern.
+ * Uses the provided AbortScenario to detect when to abort.
+ *
+ * @example
+ * ```typescript
+ * const abortScenario = createAbortScenario();
+ * const onCancelCalled = vi.fn();
+ * const generator = createCancelableGenerator(abortScenario, onCancelCalled);
+ *
+ * const execution = new StreamingExecutionHost(factory, generator, abortScenario.signal);
+ * abortScenario.abort();
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * expect(onCancelCalled).toHaveBeenCalled();
+ * ```
+ */
+declare function createCancelableGenerator<TEvent extends {
+    type: string;
+}>(abortScenario: AbortScenario, onCancel?: () => void, eventsBeforeWait?: EmittableEventInput<TEvent>[]): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+}) => AsyncGenerator<SessionEvent<TEvent>, void, unknown>;
+/**
+ * Create a function that waits for cancellation using closure pattern.
+ * Uses the provided AbortScenario to detect when to abort.
+ * Equivalent of createCancelableGenerator for SimpleExecutionHost.
+ *
+ * @example
+ * ```typescript
+ * const abortScenario = createAbortScenario();
+ * const onCancelCalled = vi.fn();
+ * const fn = createCancelableFunction(abortScenario, onCancelCalled);
+ *
+ * const execution = new SimpleExecutionHost(factory, fn, abortScenario.signal);
+ * abortScenario.abort();
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * expect(onCancelCalled).toHaveBeenCalled();
+ * ```
+ */
+declare function createCancelableFunction(abortScenario: AbortScenario, onCancel?: () => void): (session: SimpleSession) => Promise<unknown>;
+/**
+ * Create a generator with delay, useful for timing-related tests.
+ *
+ * @example
+ * ```typescript
+ * const generator = createDelayedGenerator(100, 'result');
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Cancel before delay completes
+ * setTimeout(() => execution.cancel(), 50);
+ * ```
+ */
+declare function createDelayedGenerator<TEvent extends {
+    type: string;
+}>(delayMs: number, result: ExtractResult<TEvent>, abortScenario?: AbortScenario): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+    done: (value: ExtractResult<TEvent>) => Promise<SessionEvent<TEvent>>;
+}) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>>, unknown>;
+/**
+ * Create a generator that yields events with a configurable delay between each.
+ * Useful for race condition testing where timing control is needed.
+ *
+ * @example
+ * ```typescript
+ * const generator = createSlowGenerator([
+ *   { type: 'chunk', content: 'A' },
+ *   { type: 'chunk', content: 'B' },
+ * ], 10);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Cancel mid-stream
+ * setTimeout(() => execution.cancel(), 15);
+ * ```
+ */
+declare function createSlowGenerator<TEvent extends {
+    type: string;
+}>(events: EmittableEventInput<TEvent>[], delayBetweenEventsMs: number, abortScenario?: AbortScenario): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+}) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | undefined, unknown>;
+/**
+ * Collect all events from an async iterable stream.
+ * Useful for testing stream() output in race condition scenarios.
+ *
+ * @example
+ * ```typescript
+ * const events = await collectStreamAsync(execution.stream());
+ * expect(events).toHaveLength(3);
+ * ```
+ */
+declare function collectStreamAsync<T>(stream: AsyncIterable<T>): Promise<T[]>;
+/**
+ * Create a generator that never completes (infinite wait).
+ * Useful for testing cleanup and cancellation behavior.
+ *
+ * @example
+ * ```typescript
+ * const generator = createNeverEndingGenerator([
+ *   { type: 'chunk', content: 'A' },
+ * ]);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Must cancel to complete
+ * execution.cancel();
+ * ```
+ */
+declare function createNeverEndingGenerator<TEvent extends {
+    type: string;
+}>(eventsBeforeWait?: EmittableEventInput<TEvent>[], abortScenario?: AbortScenario): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+}) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | undefined, unknown>;
+/**
+ * Create a logger that tracks call order for sequence verification.
+ * This version is framework-agnostic (no vitest/jest dependency).
+ *
+ * @example
+ * ```typescript
+ * const { logger, getCallOrder } = createOrderTrackingLogger();
+ * // ... run execution with logger ...
+ *
+ * expect(getCallOrder()).toEqual(['start', 'emit', 'done']);
+ * ```
+ */
+declare function createOrderTrackingLogger(): {
+    logger: Logger;
+    getCallOrder: () => LoggerEventType[];
+};
+
+/**
+ * Test fixtures for execution module tests.
+ * Provides mock factories and session factories for testing.
+ *
+ * These fixtures are framework-agnostic (no vitest/jest dependency).
+ * Pass your own mock function (vi.fn, jest.fn, etc.) or use the noop default.
+ */
+
+type MockFn = (...args: unknown[]) => unknown;
+type MockFnFactory = () => MockFn;
+declare const TEST_PROVIDER_TYPE: "google";
+/**
+ * Base test event — the domain event users emit via session.emit().
+ */
+interface TestBaseEvent {
+    type: string;
+    message?: string;
+    data?: string;
+}
+/**
+ * Full test event union including CompletionEvent.
+ * ExtractResult<TestEvent> = string, EmittableEventInput<TestEvent> = TestBaseEvent.
+ */
+type TestEvent = TestBaseEvent | CompletionEvent<string>;
+interface CreateMockModelOptions {
+    mockFn?: MockFnFactory;
+}
+declare function createMockModel(options?: CreateMockModelOptions): LanguageModel;
+interface CreateMockFileManagerOptions {
+    mockFn?: MockFnFactory;
+}
+declare function createMockFileManager(options?: CreateMockFileManagerOptions): FileManager;
+interface CreateMockLoggerOptions {
+    mockFn?: MockFnFactory;
+}
+declare function createMockLogger(options?: CreateMockLoggerOptions): Logger;
+declare function createMockUsage(overrides?: Partial<LanguageModelUsage>): LanguageModelUsage;
+interface CreateSessionFactoryOptions {
+    mockFn?: MockFnFactory;
+    logger?: Logger;
+}
+declare function createSimpleSessionFactory(options?: CreateSessionFactoryOptions): (signal?: AbortSignal) => SimpleSession;
+declare function createStreamingSessionFactory<TEvent extends {
+    type: string;
+} = TestEvent>(options?: CreateSessionFactoryOptions): () => StreamingSession<TEvent>;
+interface CreateStreamingSessionFactoryWithSignalOptions extends CreateSessionFactoryOptions {
+    onSignalCapture?: (signal: AbortSignal | undefined) => void;
+}
+declare function createStreamingSessionFactoryWithSignal<TEvent extends {
+    type: string;
+} = TestEvent>(options?: CreateStreamingSessionFactoryWithSignalOptions): (signal?: AbortSignal) => StreamingSession<TEvent>;
+declare function collectEvents<T>(stream: AsyncIterable<T>): Promise<T[]>;
+/**
+ * Creates a controllable promise for testing async flows
+ */
+declare function createControllablePromise<T = void>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: Error) => void;
+};
+
+declare function createTestExecution<TEvent extends {
+    type: string;
+}>(result: ExtractResult<TEvent>, events?: EmittableEventInput<TEvent>[]): StreamingExecution<TEvent>;
+declare function createTestErrorExecution<TEvent extends {
+    type: string;
+}>(error: Error, options?: {
+    events?: EmittableEventInput<TEvent>[];
+    data?: ExtractResult<TEvent>;
+}): StreamingExecution<TEvent>;
+declare function createTestCanceledExecution<TEvent extends {
+    type: string;
+}>(events?: EmittableEventInput<TEvent>[]): StreamingExecution<TEvent>;
+
+export { type AbortScenario, type CreateMockFileManagerOptions, type CreateMockLoggerOptions, type CreateMockModelOptions, type CreateSessionFactoryOptions, type CreateStreamingSessionFactoryWithSignalOptions, type TestBaseEvent as ExecutionTestBaseEvent, type TestEvent as ExecutionTestEvent, type LoggerEventType, type MockCall, type MockFn, type MockFnFactory, MockProvider, type MockProviderConfig, type ModelFactory, type ResponseOptions, TEST_API_KEY, TEST_PROVIDER_TYPE, type TestBaseEvent$1 as TestBaseEvent, type TestEvent$1 as TestEvent, type TestResult, collectEvents$1 as collectEvents, collectEvents as collectExecutionEvents, collectStreamAsync, consumeExecution, createAbortScenario, createAlreadyAbortedSignal, createCancelableFunction, createCancelableGenerator, createControllablePromise, createDelayedGenerator, createErrorGenerator, createMockFileManager, createMockUsage as createMockLanguageModelUsage, createMockLogger, createMockModel, createMockProvider, createMockSessionSummary, createMockUsage$1 as createMockUsage, createNeverEndingGenerator, createOrderTrackingLogger, createSimpleGenerator, createSimpleSessionFactory, createSlowGenerator, createStreamingSessionFactory, createStreamingSessionFactoryWithSignal, createTestCanceledExecution, createTestErrorExecution, createTestEvent, createTestExecution, expectFileManagerInterface, mock };