@agtlantis/core 0.5.0 → 0.6.0

package/dist/execution/streaming-host.js

@@ -0,0 +1,276 @@
+import { ERRORS } from './constants.js';
+import { combineSignals, Deferred } from './utils.js';
+import { isAbortError, normalizeError, createHookRunner } from './shared.js';
+/**
+ * Streaming execution host that uses StreamingSession.
+ * Starts execution eagerly on construction - events are buffered automatically.
+ *
+ * @typeParam TEvent - User's pure domain event type with required `type` field (metrics added automatically)
+ *
+ * @example
+ * ```typescript
+ * const execution = new StreamingExecutionHost(
+ *   () => new StreamingSession({
+ *     defaultLanguageModel: provider.model,
+ *     fileManager: new GoogleFileManager(apiKey),
+ *   }),
+ *   async function* (session) {
+ *     session.onDone(() => session.fileManager.clear());
+ *     const result = await session.generateText({ prompt: 'Hello' });
+ *     yield session.emit({ type: 'progress', message: 'Working...' });
+ *     return session.done(result.text);
+ *   }
+ * );
+ * // ↑ Execution already started, events being buffered
+ *
+ * // Option 1: Stream events (buffered + real-time)
+ * for await (const event of execution.stream()) {
+ *   console.log(event.type, event.metrics.elapsedMs);
+ * }
+ * const result = await execution.result();
+ *
+ * // Option 2: Skip streaming, events available in result
+ * const result = await execution.result();
+ * console.log(`Received ${result.events.length} events`);
+ *
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value);
+ * }
+ * ```
+ */
+export class StreamingExecutionHost {
+    createSession;
+    generator;
+    abortController = new AbortController();
+    effectiveSignal;
+    consumerPromise;
+    eventBuffer = [];
+    subscribers = new Set();
+    completed = false;
+    cleaned = false;
+    hookRunner = null;
+    cancelRequested = false;
+    extractedOutcome = null;
+    extractedSummary = null;
+    constructor(createSession, generator, userSignal) {
+        this.createSession = createSession;
+        this.generator = generator;
+        // Combine user signal with internal controller for dual cancellation support
+        this.effectiveSignal = userSignal
+            ? combineSignals(userSignal, this.abortController.signal)
+            : this.abortController.signal;
+        // Eager start! Begin consuming immediately
+        this.consumerPromise = this.startConsuming();
+    }
+    hasDataField(event) {
+        return 'data' in event && event.data !== undefined;
+    }
+    hasSummaryField(event) {
+        return 'summary' in event && event.summary !== undefined;
+    }
+    hasErrorField(event) {
+        return 'error' in event && event.error instanceof Error;
+    }
+    extractResultAndMetadata(event) {
+        const isCompleteOrError = event.type === 'complete' || event.type === 'error';
+        if (!isCompleteOrError) {
+            return;
+        }
+        // Extract outcome (error takes precedence if both present)
+        if (this.hasErrorField(event)) {
+            this.extractedOutcome = { type: 'error', error: event.error };
+        }
+        else if (this.hasDataField(event)) {
+            this.extractedOutcome = { type: 'result', value: event.data };
+        }
+        if (this.hasSummaryField(event)) {
+            this.extractedSummary = event.summary;
+        }
+    }
+    notifySubscribers(event) {
+        this.subscribers.forEach(fn => fn(event));
+    }
+    async startConsuming() {
+        // Pass the effective signal to session for AI SDK cancellation
+        const session = this.createSession(this.effectiveSignal);
+        this.hookRunner = createHookRunner(() => session.runOnDoneHooks());
+        const gen = this.generator(session);
+        try {
+            let next = await gen.next();
+            while (!next.done) {
+                // Buffer and notify
+                this.eventBuffer.push(next.value);
+                this.notifySubscribers(next.value);
+                // Auto-abort after terminal events to prevent further AI calls
+                const isTerminal = next.value.type === 'complete' || next.value.type === 'error';
+                if (isTerminal) {
+                    this.extractResultAndMetadata(next.value);
+                    this.abortController.abort();
+                    break;
+                }
+                if (this.abortController.signal.aborted) {
+                    break;
+                }
+                next = await gen.next();
+            }
+            // Handle return value from generator
+            if (next.done && next.value !== undefined) {
+                const finalEvent = await Promise.resolve(next.value);
+                this.eventBuffer.push(finalEvent);
+                this.notifySubscribers(finalEvent);
+                this.extractResultAndMetadata(finalEvent);
+                // Auto-abort after terminal event from return statement
+                const isTerminal = finalEvent.type === 'complete' || finalEvent.type === 'error';
+                if (isTerminal) {
+                    this.abortController.abort();
+                }
+            }
+            return this.buildResult(session);
+        }
+        catch (error) {
+            const errorObj = normalizeError(error);
+            // AbortError is treated as normal cancellation
+            if (isAbortError(error, this.abortController.signal)) {
+                return {
+                    success: false,
+                    aborted: true,
+                    error: errorObj,
+                    summary: await session.getSummary(),
+                };
+            }
+            // Generate error event via session.fail()
+            const errorEvent = await session.fail(errorObj);
+            this.eventBuffer.push(errorEvent);
+            this.notifySubscribers(errorEvent);
+            this.extractResultAndMetadata(errorEvent);
+            // Auto-abort after error event
+            this.abortController.abort();
+            return this.buildResult(session);
+        }
+        finally {
+            this.completed = true;
+            // Note: Don't clear subscribers here - each stream() consumer
+            // cleans up its own subscriber in its finally block to avoid orphaning
+            await this.hookRunner?.ensureRun();
+            await gen.return(undefined);
+        }
+    }
+    async buildResult(session) {
+        const summary = this.extractedSummary ?? await session.getSummary();
+        // Use discriminated union for clean pattern matching
+        if (this.extractedOutcome?.type === 'error') {
+            return {
+                success: false,
+                aborted: false,
+                error: this.extractedOutcome.error,
+                summary,
+            };
+        }
+        if (this.extractedOutcome?.type === 'result') {
+            return {
+                success: true,
+                result: this.extractedOutcome.value,
+                summary,
+            };
+        }
+        // No result extracted - likely canceled or abnormal termination
+        return {
+            success: false,
+            aborted: true,
+            error: new Error(ERRORS.NO_RESULT),
+            summary,
+        };
+    }
+    /**
+     * Get the event stream.
+     * Returns buffered events first, then real-time events.
+     * Can be called multiple times - replays buffer each time.
+     */
+    async *stream() {
+        // 1. Yield buffered events first
+        let index = 0;
+        while (index < this.eventBuffer.length) {
+            yield this.eventBuffer[index++];
+        }
+        // 2. If completed, we're done
+        if (this.completed) {
+            return;
+        }
+        // 3. Subscribe for real-time events using Deferred for clean async coordination
+        const queue = [];
+        let pending = new Deferred();
+        const subscriber = (event) => {
+            queue.push(event);
+            pending.resolve();
+        };
+        this.subscribers.add(subscriber);
+        try {
+            while (!this.completed || queue.length > 0) {
+                if (queue.length > 0) {
+                    yield queue.shift();
+                }
+                else if (!this.completed) {
+                    await pending.promise;
+                    pending = new Deferred(); // Reset for next wait
+                }
+            }
+        }
+        finally {
+            this.subscribers.delete(subscriber);
+        }
+    }
+    cancel() {
+        this.cancelRequested = true;
+        this.abortController.abort();
+    }
+    async cleanup() {
+        if (this.cleaned) {
+            return;
+        }
+        this.cleaned = true;
+        // Cancel if still running
+        if (!this.completed) {
+            this.cancel();
+            await this.consumerPromise.catch(() => { });
+        }
+        // Clean up resources
+        this.subscribers.clear();
+        await this.hookRunner?.ensureRun();
+    }
+    async [Symbol.asyncDispose]() {
+        await this.cleanup();
+    }
+    /**
+     * Get the execution result with status, summary, and all events.
+     * Never throws - returns a discriminated union with status.
+     */
+    async result() {
+        const internal = await this.consumerPromise;
+        const events = Object.freeze([...this.eventBuffer]);
+        // Success state
+        if (internal.success) {
+            return {
+                status: 'succeeded',
+                value: internal.result,
+                summary: internal.summary,
+                events,
+            };
+        }
+        // Canceled state
+        if (this.cancelRequested || internal.aborted) {
+            return {
+                status: 'canceled',
+                summary: internal.summary,
+                events,
+            };
+        }
+        // Failed state
+        return {
+            status: 'failed',
+            error: internal.error,
+            summary: internal.summary,
+            events,
+        };
+    }
+}
+//# sourceMappingURL=streaming-host.js.map

package/dist/execution/streaming-host.js.map

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

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":"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"}