@agtlantis/core 0.5.0 → 0.6.0

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

package/dist/execution/utils.js

@@ -0,0 +1,93 @@
+/**
+ * Calculate duration from start time in milliseconds.
+ *
+ * @param startTime - The start timestamp from Date.now()
+ * @returns Duration in milliseconds
+ */
+export function getDuration(startTime) {
+    return Date.now() - startTime;
+}
+/**
+ * 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 function combineSignals(...signals) {
+    const controller = new AbortController();
+    for (const signal of signals) {
+        // If any signal is already aborted, immediately abort and return
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            return controller.signal;
+        }
+        // Listen for future aborts
+        signal.addEventListener('abort', () => controller.abort(signal.reason), {
+            once: true,
+        });
+    }
+    return controller.signal;
+}
+/**
+ * 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 class Deferred {
+    promise;
+    resolve;
+    reject;
+    constructor() {
+        let res;
+        let rej;
+        this.promise = new Promise((resolve, reject) => {
+            res = resolve;
+            rej = reject;
+        });
+        this.resolve = res;
+        this.reject = rej;
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/execution/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/execution/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAAC,GAAG,OAAsB;IACtD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IAEzC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,iEAAiE;QACjE,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAChC,OAAO,UAAU,CAAC,MAAM,CAAC;QAC3B,CAAC;QAED,2BAA2B;QAC3B,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE;YACtE,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,QAAQ;IACV,OAAO,CAAa;IACpB,OAAO,CAAqB;IAC5B,MAAM,CAAyB;IAExC;QACE,IAAI,GAAwB,CAAC;QAC7B,IAAI,GAA4B,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAChD,GAAG,GAAG,OAAO,CAAC;YACd,GAAG,GAAG,MAAM,CAAC;QACf,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;IACpB,CAAC;CACF"}