@agtlantis/core 0.5.0 → 0.5.1

package/dist/execution/testing/fixtures.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+import type { LanguageModel, LanguageModelUsage } from 'ai';
+import type { CompletionEvent } from '../types.js';
+import type { FileManager } from '../../provider/types.js';
+import type { Logger } from '../../observability/logger.js';
+import { SimpleSession } from '../../session/simple-session.js';
+import { StreamingSession } from '../../session/streaming-session.js';
+export type MockFn = (...args: unknown[]) => unknown;
+export type MockFnFactory = () => MockFn;
+export declare const TEST_PROVIDER_TYPE: "google";
+/**
+ * Base test event — the domain event users emit via session.emit().
+ */
+export interface TestBaseEvent {
+    type: string;
+    message?: string;
+    data?: string;
+}
+/**
+ * Full test event union including CompletionEvent.
+ * ExtractResult<TestEvent> = string, EmittableEventInput<TestEvent> = TestBaseEvent.
+ */
+export type TestEvent = TestBaseEvent | CompletionEvent<string>;
+export interface CreateMockModelOptions {
+    mockFn?: MockFnFactory;
+}
+export declare function createMockModel(options?: CreateMockModelOptions): LanguageModel;
+export interface CreateMockFileManagerOptions {
+    mockFn?: MockFnFactory;
+}
+export declare function createMockFileManager(options?: CreateMockFileManagerOptions): FileManager;
+export interface CreateMockLoggerOptions {
+    mockFn?: MockFnFactory;
+}
+export declare function createMockLogger(options?: CreateMockLoggerOptions): Logger;
+export declare function createMockUsage(overrides?: Partial<LanguageModelUsage>): LanguageModelUsage;
+export interface CreateSessionFactoryOptions {
+    mockFn?: MockFnFactory;
+    logger?: Logger;
+}
+export declare function createSimpleSessionFactory(options?: CreateSessionFactoryOptions): (signal?: AbortSignal) => SimpleSession;
+export declare function createStreamingSessionFactory<TEvent extends {
+    type: string;
+} = TestEvent>(options?: CreateSessionFactoryOptions): () => StreamingSession<TEvent>;
+export interface CreateStreamingSessionFactoryWithSignalOptions extends CreateSessionFactoryOptions {
+    onSignalCapture?: (signal: AbortSignal | undefined) => void;
+}
+export declare function createStreamingSessionFactoryWithSignal<TEvent extends {
+    type: string;
+} = TestEvent>(options?: CreateStreamingSessionFactoryWithSignalOptions): (signal?: AbortSignal) => StreamingSession<TEvent>;
+export declare function collectEvents<T>(stream: AsyncIterable<T>): Promise<T[]>;
+/**
+ * Creates a controllable promise for testing async flows
+ */
+export declare function createControllablePromise<T = void>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: Error) => void;
+};
+export { createAbortScenario, createAlreadyAbortedSignal, type AbortScenario, createSimpleGenerator, createErrorGenerator, createCancelableGenerator, createCancelableFunction, createDelayedGenerator, createSlowGenerator, collectStreamAsync, createNeverEndingGenerator, createOrderTrackingLogger, type LoggerEventType, } from './helpers.js';
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/execution/testing/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../../src/execution/testing/fixtures.ts"],"names":[],"mappings":"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"}

package/dist/execution/testing/fixtures.js

@@ -0,0 +1,145 @@
+/**
+ * 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.
+ */
+import { SimpleSession } from '../../session/simple-session.js';
+import { StreamingSession } from '../../session/streaming-session.js';
+export const TEST_PROVIDER_TYPE = 'google';
+// ============================================================================
+// Default noop mock factory
+// ============================================================================
+const noop = () => { };
+const noopFactory = () => noop;
+function createNoopWithReturn(value) {
+    return () => value;
+}
+function createNoopAsync(value) {
+    return () => Promise.resolve(value);
+}
+export function createMockModel(options = {}) {
+    const { mockFn = noopFactory } = options;
+    return {
+        specificationVersion: 'v1',
+        provider: 'test-provider',
+        modelId: 'test-model',
+        defaultObjectGenerationMode: 'json',
+        doGenerate: mockFn(),
+        doStream: mockFn(),
+    };
+}
+export function createMockFileManager(options = {}) {
+    const { mockFn } = options;
+    if (mockFn) {
+        return {
+            upload: mockFn(),
+            delete: mockFn(),
+            clear: mockFn(),
+            getUploadedFiles: mockFn(),
+        };
+    }
+    // Default noop implementation with proper return values
+    return {
+        upload: createNoopAsync([]),
+        delete: createNoopAsync(undefined),
+        clear: createNoopAsync(undefined),
+        getUploadedFiles: createNoopWithReturn([]),
+    };
+}
+export function createMockLogger(options = {}) {
+    const { mockFn = noopFactory } = options;
+    return {
+        onLLMCallStart: mockFn(),
+        onLLMCallEnd: mockFn(),
+        onExecutionStart: mockFn(),
+        onExecutionEmit: mockFn(),
+        onExecutionDone: mockFn(),
+        onExecutionError: mockFn(),
+    };
+}
+export function createMockUsage(overrides = {}) {
+    return {
+        inputTokens: 100,
+        outputTokens: 50,
+        totalTokens: 150,
+        inputTokenDetails: {
+            noCacheTokens: 100,
+            cacheReadTokens: 0,
+            cacheWriteTokens: 0,
+        },
+        outputTokenDetails: {
+            textTokens: 50,
+            reasoningTokens: 0,
+        },
+        ...overrides,
+    };
+}
+export function createSimpleSessionFactory(options = {}) {
+    const { mockFn, logger } = options;
+    return (signal) => new SimpleSession({
+        defaultLanguageModel: createMockModel({ mockFn }),
+        providerType: TEST_PROVIDER_TYPE,
+        fileManager: createMockFileManager({ mockFn }),
+        signal,
+        logger,
+    });
+}
+export function createStreamingSessionFactory(options = {}) {
+    const { mockFn, logger } = options;
+    return () => new StreamingSession({
+        defaultLanguageModel: createMockModel({ mockFn }),
+        providerType: TEST_PROVIDER_TYPE,
+        fileManager: createMockFileManager({ mockFn }),
+        logger,
+    });
+}
+export function createStreamingSessionFactoryWithSignal(options = {}) {
+    const { mockFn, logger, onSignalCapture } = options;
+    return (signal) => {
+        onSignalCapture?.(signal);
+        return new StreamingSession({
+            defaultLanguageModel: createMockModel({ mockFn }),
+            providerType: TEST_PROVIDER_TYPE,
+            fileManager: createMockFileManager({ mockFn }),
+            signal,
+            logger,
+        });
+    };
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+export async function collectEvents(stream) {
+    const events = [];
+    for await (const event of stream) {
+        events.push(event);
+    }
+    return events;
+}
+/**
+ * Creates a controllable promise for testing async flows
+ */
+export function createControllablePromise() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+// ============================================================================
+// Re-export Test Helpers
+// ============================================================================
+export { 
+// Abort/Signal helpers
+createAbortScenario, createAlreadyAbortedSignal, 
+// Generator helpers
+createSimpleGenerator, createErrorGenerator, createCancelableGenerator, createCancelableFunction, createDelayedGenerator, 
+// Race condition & concurrency helpers
+createSlowGenerator, collectStreamAsync, createNeverEndingGenerator, 
+// Logger helpers
+createOrderTrackingLogger, } from './helpers.js';
+//# sourceMappingURL=fixtures.js.map

package/dist/execution/testing/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../../src/execution/testing/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAStE,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAiB,CAAC;AAiBpD,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAE/E,MAAM,IAAI,GAAW,GAAG,EAAE,CAAC,EAAC,CAAC,CAAC;AAC9B,MAAM,WAAW,GAAkB,GAAG,EAAE,CAAC,IAAI,CAAC;AAE9C,SAAS,oBAAoB,CAAI,KAAQ,EAAU;IACjD,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC;AAAA,CACpB;AAED,SAAS,eAAe,CAAI,KAAQ,EAAU;IAC5C,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAAA,CACrC;AAUD,MAAM,UAAU,eAAe,CAAC,OAAO,GAA2B,EAAE,EAAiB;IACnF,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,OAAO,CAAC;IACzC,OAAO;QACL,oBAAoB,EAAE,IAAI;QAC1B,QAAQ,EAAE,eAAe;QACzB,OAAO,EAAE,YAAY;QACrB,2BAA2B,EAAE,MAAM;QACnC,UAAU,EAAE,MAAM,EAAE;QACpB,QAAQ,EAAE,MAAM,EAAE;KACS,CAAC;AAAA,CAC/B;AAMD,MAAM,UAAU,qBAAqB,CACnC,OAAO,GAAiC,EAAE,EAC7B;IACb,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAE3B,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;YACL,MAAM,EAAE,MAAM,EAAE;YAChB,MAAM,EAAE,MAAM,EAAE;YAChB,KAAK,EAAE,MAAM,EAAE;YACf,gBAAgB,EAAE,MAAM,EAAE;SACZ,CAAC;IACnB,CAAC;IAED,wDAAwD;IACxD,OAAO;QACL,MAAM,EAAE,eAAe,CAAC,EAAE,CAAC;QAC3B,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC;QAClC,KAAK,EAAE,eAAe,CAAC,SAAS,CAAC;QACjC,gBAAgB,EAAE,oBAAoB,CAAC,EAAE,CAAC;KAC5B,CAAC;AAAA,CAClB;AAMD,MAAM,UAAU,gBAAgB,CAAC,OAAO,GAA4B,EAAE,EAAU;IAC9E,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,OAAO,CAAC;IACzC,OAAO;QACL,cAAc,EAAE,MAAM,EAAE;QACxB,YAAY,EAAE,MAAM,EAAE;QACtB,gBAAgB,EAAE,MAAM,EAAE;QAC1B,eAAe,EAAE,MAAM,EAAE;QACzB,eAAe,EAAE,MAAM,EAAE;QACzB,gBAAgB,EAAE,MAAM,EAAE;KAC3B,CAAC;AAAA,CACH;AAED,MAAM,UAAU,eAAe,CAC7B,SAAS,GAAgC,EAAE,EACvB;IACpB,OAAO;QACL,WAAW,EAAE,GAAG;QAChB,YAAY,EAAE,EAAE;QAChB,WAAW,EAAE,GAAG;QAChB,iBAAiB,EAAE;YACjB,aAAa,EAAE,GAAG;YAClB,eAAe,EAAE,CAAC;YAClB,gBAAgB,EAAE,CAAC;SACpB;QACD,kBAAkB,EAAE;YAClB,UAAU,EAAE,EAAE;YACd,eAAe,EAAE,CAAC;SACnB;QACD,GAAG,SAAS;KACb,CAAC;AAAA,CACH;AAWD,MAAM,UAAU,0BAA0B,CACxC,OAAO,GAAgC,EAAE,EACA;IACzC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEnC,OAAO,CAAC,MAAoB,EAAE,EAAE,CAC9B,IAAI,aAAa,CAAC;QAChB,oBAAoB,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QACjD,YAAY,EAAE,kBAAkB;QAChC,WAAW,EAAE,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC9C,MAAM;QACN,MAAM;KACP,CAAC,CAAC;AAAA,CACN;AAED,MAAM,UAAU,6BAA6B,CAE3C,OAAO,GAAgC,EAAE,EAAkC;IAC3E,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEnC,OAAO,GAAG,EAAE,CACV,IAAI,gBAAgB,CAAS;QAC3B,oBAAoB,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QACjD,YAAY,EAAE,kBAAkB;QAChC,WAAW,EAAE,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC9C,MAAM;KACP,CAAC,CAAC;AAAA,CACN;AAOD,MAAM,UAAU,uCAAuC,CAGrD,OAAO,GAAmD,EAAE,EACR;IACpD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IAEpD,OAAO,CAAC,MAAoB,EAAE,EAAE,CAAC;QAC/B,eAAe,EAAE,CAAC,MAAM,CAAC,CAAC;QAC1B,OAAO,IAAI,gBAAgB,CAAS;YAClC,oBAAoB,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;YACjD,YAAY,EAAE,kBAAkB;YAChC,WAAW,EAAE,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;YAC9C,MAAM;YACN,MAAM;SACP,CAAC,CAAC;IAAA,CACJ,CAAC;AAAA,CACH;AAED,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,MAAM,CAAC,KAAK,UAAU,aAAa,CAAI,MAAwB,EAAgB;IAC7E,MAAM,MAAM,GAAQ,EAAE,CAAC;IACvB,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACf;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,GAIvC;IACA,IAAI,OAA4B,CAAC;IACjC,IAAI,MAA+B,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC;QAC3C,OAAO,GAAG,GAAG,CAAC;QACd,MAAM,GAAG,GAAG,CAAC;IAAA,CACd,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAAA,CACrC;AAED,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E,OAAO;AACL,uBAAuB;AACvB,mBAAmB,EACnB,0BAA0B;AAE1B,oBAAoB;AACpB,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB;AACtB,uCAAuC;AACvC,mBAAmB,EACnB,kBAAkB,EAClB,0BAA0B;AAC1B,iBAAiB;AACjB,yBAAyB,GAE1B,MAAM,cAAc,CAAC"}

package/dist/execution/testing/helpers.d.ts

@@ -0,0 +1,218 @@
+/**
+ * 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).
+ */
+import type { SessionEvent, ExtractResult, EmittableEventInput } from '../types.js';
+import type { Logger } from '../../observability/logger.js';
+import type { SimpleSession } from '../../session/simple-session.js';
+export type LoggerEventType = 'start' | 'emit' | 'done' | 'error';
+/**
+ * Abort scenario helper for testing cancellation flows.
+ */
+export 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);
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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');
+ * ```
+ */
+export 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();
+ * ```
+ */
+export 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();
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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();
+ * ```
+ */
+export 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']);
+ * ```
+ */
+export declare function createOrderTrackingLogger(): {
+    logger: Logger;
+    getCallOrder: () => LoggerEventType[];
+};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/execution/testing/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/execution/testing/helpers.ts"],"names":[],"mappings":"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"}