@agtlantis/core 0.4.1 → 0.5.1

package/dist/execution/testing/vitest-assertions.js

@@ -0,0 +1,142 @@
+/**
+ * Vitest-specific assertion helpers for execution module tests.
+ * These helpers depend on vitest and should only be used in internal tests.
+ */
+import { vi, expect } from 'vitest';
+// ============================================================================
+// Result Assertion Helpers
+// ============================================================================
+/**
+ * Assert that an execution result is successful and optionally check the value.
+ *
+ * @example
+ * ```typescript
+ * const result = await execution.result();
+ * expectSuccessResult(result, 'expected-value');
+ * // result is now narrowed to succeeded type
+ * console.log(result.value);
+ * ```
+ */
+export function expectSuccessResult(result, expectedValue) {
+    expect(result.status).toBe('succeeded');
+    if (result.status !== 'succeeded') {
+        throw new Error('Result is not succeeded');
+    }
+    if (expectedValue !== undefined) {
+        expect(result.value).toBe(expectedValue);
+    }
+}
+/**
+ * Assert that an execution result is failed and optionally check the error.
+ *
+ * @example
+ * ```typescript
+ * const result = await execution.result();
+ * expectFailedResult(result, 'Expected error message');
+ * // or with regex
+ * expectFailedResult(result, /timeout/i);
+ * ```
+ */
+export function expectFailedResult(result, errorMatcher) {
+    expect(result.status).toBe('failed');
+    if (result.status !== 'failed') {
+        throw new Error('Result is not failed');
+    }
+    if (errorMatcher !== undefined) {
+        if (typeof errorMatcher === 'string') {
+            expect(result.error.message).toBe(errorMatcher);
+        }
+        else if (errorMatcher instanceof RegExp) {
+            expect(result.error.message).toMatch(errorMatcher);
+        }
+        else {
+            expect(result.error).toBe(errorMatcher);
+        }
+    }
+}
+/**
+ * Assert that an execution result is canceled.
+ *
+ * @example
+ * ```typescript
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * ```
+ */
+export function expectCanceledResult(result) {
+    expect(result.status).toBe('canceled');
+}
+/**
+ * Assert streaming result status and optionally check events count.
+ *
+ * @example
+ * ```typescript
+ * const result = await execution.result();
+ * expectStreamingSuccessResult(result, 'value', 3);
+ * ```
+ */
+export function expectStreamingSuccessResult(result, expectedValue, expectedEventCount) {
+    expectSuccessResult(result, expectedValue);
+    if (expectedEventCount !== undefined) {
+        expect(result.events).toHaveLength(expectedEventCount);
+    }
+}
+/**
+ * Verify that logger was called in the expected sequence.
+ *
+ * @example
+ * ```typescript
+ * const logger = createMockLogger();
+ * // ... run execution ...
+ *
+ * verifyLoggerSequence(logger, ['start', 'emit', 'emit', 'done']);
+ * ```
+ */
+export function verifyLoggerSequence(logger, expectedSequence) {
+    const eventMap = {
+        start: 'onExecutionStart',
+        emit: 'onExecutionEmit',
+        done: 'onExecutionDone',
+        error: 'onExecutionError',
+    };
+    // Count expected occurrences
+    const expectedCounts = expectedSequence.reduce((acc, event) => {
+        acc[event] = (acc[event] || 0) + 1;
+        return acc;
+    }, {});
+    // Verify each event type was called the expected number of times
+    for (const [event, count] of Object.entries(expectedCounts)) {
+        const methodName = eventMap[event];
+        expect(logger[methodName]).toHaveBeenCalledTimes(count);
+    }
+}
+/**
+ * Create a vitest mock logger.
+ */
+export function createVitestMockLogger() {
+    return {
+        onLLMCallStart: vi.fn(),
+        onLLMCallEnd: vi.fn(),
+        onExecutionStart: vi.fn(),
+        onExecutionEmit: vi.fn(),
+        onExecutionDone: vi.fn(),
+        onExecutionError: vi.fn(),
+    };
+}
+/**
+ * @deprecated Use createVitestMockLogger instead
+ */
+export const createMockLogger = createVitestMockLogger;
+/**
+ * Get vitest's vi.fn for use with framework-agnostic fixtures.
+ *
+ * @example
+ * ```typescript
+ * import { vitestMockFn } from './vitest-assertions';
+ * import { createStreamingSessionFactory } from './fixtures';
+ *
+ * const factory = createStreamingSessionFactory({ mockFn: vitestMockFn });
+ * ```
+ */
+export const vitestMockFn = () => vi.fn();
+//# sourceMappingURL=vitest-assertions.js.map

package/dist/execution/testing/vitest-assertions.js.map

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

package/dist/execution/types.d.ts

@@ -0,0 +1,432 @@
+/**
+ * Agent execution types for @agtlantis/core.
+ * Provides abstractions for streaming and non-streaming agent execution.
+ */
+import type { EventMetrics } from '../observability/index.js';
+import type { SessionSummary, StreamingSession } from '../session/index.js';
+/**
+ * Distributive version of Omit that properly handles union types.
+ *
+ * Standard `Omit<A | B, K>` loses unique properties from union members.
+ * `DistributiveOmit<A | B, K>` preserves them by distributing over the union.
+ *
+ * @example
+ * ```typescript
+ * type A = { type: 'a'; foo: string; metrics: EventMetrics };
+ * type B = { type: 'b'; bar: number; metrics: EventMetrics };
+ * type Union = A | B;
+ *
+ * // ❌ Standard Omit - loses foo and bar
+ * type Bad = Omit<Union, 'metrics'>;
+ * // Result: { type: 'a' | 'b' }
+ *
+ * // ✅ DistributiveOmit - preserves unique properties
+ * type Good = DistributiveOmit<Union, 'metrics'>;
+ * // Result: { type: 'a'; foo: string } | { type: 'b'; bar: number }
+ * ```
+ */
+export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
+/**
+ * Adds `metrics: EventMetrics` to event types.
+ * The framework uses this internally to wrap user-defined events with timing info.
+ *
+ * **For most use cases, you don't need this type.** Simply define your events
+ * without metrics, and the framework handles the wrapping automatically.
+ *
+ * **When you need SessionEvent:**
+ * - Creating mock/stub streaming executions for testing
+ * - Explicitly typing `StreamingResult.events` arrays
+ *
+ * @example
+ * ```typescript
+ * // User defines pure event types (recommended)
+ * type MyEvent =
+ *   | { type: 'progress'; step: string }
+ *   | { type: 'complete'; data: string };
+ *
+ * // Framework internally wraps as SessionEvent<MyEvent>
+ * // StreamingResult.events returns SessionEvent<MyEvent>[]
+ *
+ * // Testing: Create mock events with explicit metrics
+ * const mockEvents: SessionEvent<MyEvent>[] = [
+ *   { type: 'progress', step: 'loading', metrics: { timestamp: Date.now(), elapsedMs: 0, deltaMs: 0 } },
+ * ];
+ * ```
+ */
+export type SessionEvent<T extends {
+    type: string;
+}> = T & {
+    metrics: EventMetrics;
+};
+/**
+ * Input type for session.emit() - removes metrics from event types.
+ * Uses DistributiveOmit to properly handle union types.
+ *
+ * @example
+ * ```typescript
+ * type MyAgentEvent = SessionEvent<ProgressEvent | CompleteEvent | ErrorEvent>;
+ *
+ * // For emit input, metrics is not required
+ * type EmitInput = SessionEventInput<MyAgentEvent>;
+ *
+ * // Usage in session.emit()
+ * session.emit({ type: 'progress', step: 'reading', message: 'Loading...' });
+ * // No casting needed!
+ * ```
+ */
+/**
+ * @deprecated TEvent no longer requires metrics constraint - use TEvent directly
+ * This type is kept for backwards compatibility during migration
+ */
+export type SessionEventInput<T extends {
+    type: string;
+}> = T;
+/**
+ * Reserved event types that cannot be emitted directly via session.emit().
+ * These types are controlled internally by session.done() and session.fail().
+ */
+export type ReservedEventType = 'complete' | 'error';
+/**
+ * Input type for emit() - excludes reserved event types.
+ * Users define pure domain events; framework adds metrics wrapper.
+ */
+export type EmittableEventInput<T extends {
+    type: string;
+}> = T extends {
+    type: ReservedEventType;
+} ? never : T;
+/**
+ * Completion event emitted by session.done().
+ * Include this in your event union to define the result type.
+ *
+ * @example
+ * ```typescript
+ * type MyEvent =
+ *   | { type: 'progress'; step: string }
+ *   | CompletionEvent<MyResult>;
+ *
+ * // session.done(result) emits { type: 'complete', data: result, summary }
+ * ```
+ */
+export type CompletionEvent<TResult> = {
+    type: 'complete';
+    data: TResult;
+    summary: SessionSummary;
+};
+/**
+ * Error event emitted by session.fail().
+ * Auto-added to stream() return type — users don't need to include this in their event union.
+ *
+ * @example
+ * ```typescript
+ * for await (const event of execution.stream()) {
+ *   if (event.type === 'error') {
+ *     console.error(event.error.message);
+ *   }
+ * }
+ * ```
+ */
+export type ErrorEvent = {
+    type: 'error';
+    error: Error;
+    summary?: SessionSummary;
+    data?: unknown;
+};
+/**
+ * Extract the result type from an event union containing CompletionEvent<T>.
+ * Returns `never` if no CompletionEvent member exists (making session.done() uncallable).
+ *
+ * @example
+ * ```typescript
+ * type MyEvent =
+ *   | { type: 'progress'; step: string }
+ *   | CompletionEvent<{ answer: string }>;
+ *
+ * type Result = ExtractResult<MyEvent>;
+ * // Result = { answer: string }
+ * ```
+ */
+export type ExtractResult<TEvent extends {
+    type: string;
+}> = Extract<TEvent, {
+    type: 'complete';
+}> extends {
+    data: infer R;
+} ? R : never;
+/**
+ * Options for execution.
+ * Used by both simpleExecution and streamingExecution.
+ */
+export interface ExecutionOptions {
+    /**
+     * AbortSignal for cancellation.
+     * Combined with internal AbortController - both can trigger cancellation.
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     *
+     * // Pass signal to execution
+     * const execution = provider.simpleExecution(fn, { signal: controller.signal });
+     *
+     * // Cancel externally
+     * setTimeout(() => controller.abort(), 5000);
+     *
+     * // Or use execution.cancel() directly
+     * execution.cancel();
+     * ```
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Status of an execution after completion.
+ * - `succeeded`: Execution completed normally with a result
+ * - `failed`: Execution threw an error
+ * - `canceled`: Execution was canceled via cancel() or AbortSignal
+ */
+export type ExecutionStatus = 'succeeded' | 'failed' | 'canceled';
+/**
+ * Discriminated union representing the outcome of an execution.
+ * Summary is always available, regardless of execution status.
+ *
+ * @typeParam T - The result type on success
+ *
+ * @example
+ * ```typescript
+ * const result = await execution.result();
+ *
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value);
+ * } else if (result.status === 'failed') {
+ *   console.error(result.error);
+ * }
+ *
+ * // Summary always available
+ * console.log(`Cost: $${result.summary.totalCost}`);
+ * ```
+ */
+export type ExecutionResult<T> = {
+    status: 'succeeded';
+    value: T;
+    summary: SessionSummary;
+} | {
+    status: 'failed';
+    error: Error;
+    summary: SessionSummary;
+} | {
+    status: 'canceled';
+    summary: SessionSummary;
+};
+/**
+ * Result type for SimpleExecution.
+ * Alias for ExecutionResult for clarity in type annotations.
+ */
+export type SimpleResult<T> = ExecutionResult<T>;
+/**
+ * Result type for StreamingExecution.
+ * Extends ExecutionResult with readonly events array.
+ * Events are always available, even on failure or cancellation.
+ *
+ * @typeParam TEvent - Event type
+ * @typeParam T - Result type on success
+ *
+ * @example
+ * ```typescript
+ * const result = await execution.result();
+ *
+ * // Events always available, regardless of status
+ * console.log(`Received ${result.events.length} events`);
+ *
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value);
+ * }
+ * ```
+ */
+export type StreamingResult<TEvent, T> = ExecutionResult<T> & {
+    readonly events: readonly TEvent[];
+};
+/**
+ * Base interface for all execution types.
+ * Both streaming and non-streaming executions implement this interface,
+ * enabling unified handling at outer layers.
+ *
+ * @typeParam TResult - The final result type
+ *
+ * @example
+ * ```typescript
+ * // Option 1: Automatic cleanup with await using (recommended)
+ * await using execution = agent.execute(input);
+ * const result = await execution.result();
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value, result.summary.totalCost);
+ * }
+ * // cleanup() called automatically on scope exit
+ *
+ * // Option 2: Manual cleanup with try/finally
+ * const execution = agent.execute(input);
+ * try {
+ *   const result = await execution.result();
+ * } finally {
+ *   await execution.cleanup();
+ * }
+ * ```
+ */
+export interface Execution<TResult> extends AsyncDisposable {
+    /**
+     * Get the execution result with status and summary.
+     * Returns a discriminated union that always includes the summary,
+     * regardless of whether execution succeeded, failed, or was canceled.
+     *
+     * For streaming executions, this waits for all events to complete.
+     *
+     * @example
+     * ```typescript
+     * const result = await execution.result();
+     *
+     * if (result.status === 'succeeded') {
+     *   console.log(result.value);
+     * } else if (result.status === 'failed') {
+     *   console.error(result.error);
+     * }
+     *
+     * // Summary always available
+     * console.log(`Cost: $${result.summary.totalCost}`);
+     * ```
+     */
+    result(): Promise<ExecutionResult<TResult>>;
+    /**
+     * Request cancellation of the execution.
+     * Aborts the current operation if in progress.
+     * Works even if custom signal was provided (signals are combined).
+     *
+     * No-op if execution already completed.
+     */
+    cancel(): void;
+    /**
+     * Cleanup resources (uploaded files, connections, etc.).
+     * Should always be called after execution, even on error.
+     * Safe to call multiple times.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Async disposal for `await using` syntax (TS 5.2+).
+     * Delegates to cleanup().
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Simple (non-streaming) execution.
+ * Starts eagerly on construction - execution begins immediately.
+ *
+ * @typeParam TResult - The final result type
+ *
+ * @example
+ * ```typescript
+ * // Start execution (sync - no await, starts immediately)
+ * const execution = provider.simpleExecution(async (session) => {
+ *   const response = await session.generateText({ prompt: 'Hello' });
+ *   return response.text;
+ * });
+ *
+ * // Cancel if needed
+ * setTimeout(() => execution.cancel(), 5000);
+ *
+ * // Get result (status-based, never throws)
+ * const result = await execution.result();
+ *
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value);
+ * } else if (result.status === 'canceled') {
+ *   console.log('Execution was canceled');
+ * }
+ *
+ * // Summary always available
+ * console.log(`Cost: $${result.summary.totalCost}`);
+ * ```
+ */
+export interface SimpleExecution<TResult> extends Execution<TResult> {
+    /**
+     * Get the execution result with status and summary.
+     *
+     * @example
+     * ```typescript
+     * const execution = provider.simpleExecution(async (session) => {
+     *   const response = await session.generateText({ prompt: 'Hello' });
+     *   return response.text;
+     * });
+     *
+     * const result = await execution.result();
+     *
+     * if (result.status === 'succeeded') {
+     *   console.log(result.value);
+     * } else if (result.status === 'failed') {
+     *   console.error(result.error);
+     * }
+     *
+     * // Summary always available
+     * console.log(`Cost: $${result.summary.totalCost}`);
+     * ```
+     */
+    result(): Promise<SimpleResult<TResult>>;
+}
+/**
+ * Represents a streaming execution that emits events as they occur.
+ * TEvent is the user's pure domain event type (without metrics).
+ * stream() and result() return SessionEvent<TEvent> which includes metrics.
+ */
+export interface StreamingExecution<TEvent extends {
+    type: string;
+}> extends Execution<ExtractResult<TEvent>> {
+    /**
+     * Get the event stream.
+     * Returns an AsyncIterable that yields all events with metrics:
+     * - Events already in the buffer (from eager execution)
+     * - Real-time events as they occur
+     * - ErrorEvent is auto-included — no need to add it to your event union
+     *
+     * Can be called multiple times - each call replays buffered events.
+     * After execution completes, replays all events from buffer.
+     *
+     * @example
+     * ```typescript
+     * type MyEvent =
+     *   | { type: 'progress'; step: number }
+     *   | CompletionEvent<MyResult>;
+     *
+     * const execution = provider.streamingExecution<MyEvent>(...);
+     *
+     * for await (const event of execution.stream()) {
+     *   // event is SessionEvent<MyEvent | ErrorEvent>
+     *   console.log(`[${event.metrics.elapsedMs}ms] ${event.type}`);
+     * }
+     * ```
+     */
+    stream(): AsyncIterable<SessionEvent<TEvent | ErrorEvent>>;
+    /**
+     * Get the execution result with status, summary, and all events.
+     *
+     * @example
+     * ```typescript
+     * const result = await execution.result();
+     *
+     * // Events always available
+     * console.log(`Received ${result.events.length} events`);
+     *
+     * if (result.status === 'succeeded') {
+     *   console.log(result.value);
+     * }
+     *
+     * console.log(`Cost: $${result.summary.totalCost}`);
+     * ```
+     */
+    result(): Promise<StreamingResult<SessionEvent<TEvent | ErrorEvent>, ExtractResult<TEvent>>>;
+}
+/**
+ * Generator function type for streaming executions.
+ * TEvent is the user's pure domain event type (without metrics).
+ * The generator yields SessionEvent<TEvent> which includes metrics.
+ */
+export type SessionStreamGeneratorFn<TEvent extends {
+    type: string;
+}> = (session: StreamingSession<TEvent>) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>> | undefined, unknown>;
+//# sourceMappingURL=types.d.ts.map

package/dist/execution/types.d.ts.map

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

package/dist/execution/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/execution/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/execution/types.ts"],"names":[],"mappings":""}

package/dist/execution/utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Calculate duration from start time in milliseconds.
+ *
+ * @param startTime - The start timestamp from Date.now()
+ * @returns Duration in milliseconds
+ */
+export declare function getDuration(startTime: number): number;
+/**
+ * Combine multiple AbortSignals into a single signal.
+ * The combined signal aborts when ANY of the source signals abort.
+ *
+ * Node 18 compatible - doesn't use AbortSignal.any() which is Node 20+.
+ *
+ * @param signals - AbortSignals to combine
+ * @returns A new AbortSignal that aborts when any input signal aborts
+ *
+ * @example
+ * ```typescript
+ * const userController = new AbortController();
+ * const timeoutController = new AbortController();
+ *
+ * const combined = combineSignals(userController.signal, timeoutController.signal);
+ *
+ * // Either abort triggers the combined signal
+ * userController.abort(); // combined.aborted === true
+ * ```
+ */
+export declare function combineSignals(...signals: AbortSignal[]): AbortSignal;
+/**
+ * A Promise that can be resolved or rejected externally.
+ *
+ * Useful for bridging callback-based APIs to async/await patterns.
+ * The resolve/reject functions are exposed as instance properties,
+ * allowing external code to control when the promise settles.
+ *
+ * @typeParam T - The type of the resolved value (defaults to void)
+ *
+ * @example
+ * ```typescript
+ * const deferred = new Deferred<string>();
+ *
+ * // Later, in a callback:
+ * someApi.onData((data) => deferred.resolve(data));
+ * someApi.onError((err) => deferred.reject(err));
+ *
+ * // Await the result:
+ * const result = await deferred.promise;
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In async generator for event notification:
+ * let pending = new Deferred<void>();
+ * const subscriber = () => pending.resolve();
+ *
+ * while (!done) {
+ *   await pending.promise;
+ *   pending = new Deferred<void>(); // Reset for next wait
+ * }
+ * ```
+ */
+export declare class Deferred<T = void> {
+    readonly promise: Promise<T>;
+    readonly resolve: (value: T) => void;
+    readonly reject: (error: Error) => void;
+    constructor();
+}
+//# sourceMappingURL=utils.d.ts.map

package/dist/execution/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/execution/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,GAAG,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,CAiBrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,QAAQ,CAAC,CAAC,GAAG,IAAI;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAExC,cASC;CACF"}