@agtlantis/core 0.4.1

package/dist/base-provider-C3mFLNiN.d.cts

@@ -0,0 +1,1236 @@
+import { LanguageModelUsage, ToolSet, generateText, streamText, generateObject, FilePart, ImagePart, LanguageModel } from 'ai';
+import * as zod from 'zod';
+
+/**
+ * Timing metrics attached to each streaming event.
+ * Enables performance monitoring and latency debugging.
+ *
+ * @example
+ * ```typescript
+ * const event = {
+ *   type: 'progress',
+ *   message: 'Processing...',
+ *   metrics: {
+ *     timestamp: Date.now(),
+ *     elapsedMs: 150,
+ *     deltaMs: 50,
+ *   },
+ * };
+ * ```
+ */
+interface EventMetrics {
+    timestamp: number;
+    elapsedMs: number;
+    deltaMs: number;
+}
+
+/**
+ * Metadata collected during agent execution.
+ * Available after execution completes via `getSummary()`.
+ *
+ * @example
+ * ```typescript
+ * const metadata: ExecutionMetadata = {
+ *   duration: 1250,
+ *   usage: {
+ *     inputTokens: 500,
+ *     outputTokens: 200,
+ *     totalTokens: 700,
+ *   },
+ * };
+ * ```
+ */
+interface ExecutionMetadata {
+    duration: number;
+    languageModelUsage?: LanguageModelUsage;
+    [key: string]: unknown;
+}
+
+/**
+ * Pricing types for cost calculation.
+ *
+ * @module pricing/types
+ */
+/**
+ * AI provider type identifier.
+ *
+ * Common values: 'google', 'openai', 'anthropic', 'mock'
+ * Extensible to support custom providers.
+ */
+type ProviderType = string;
+/**
+ * Pricing for a specific model in USD per million tokens.
+ *
+ * @example
+ * ```typescript
+ * const gpt4Pricing: ModelPricing = {
+ *   inputPricePerMillion: 2.5,
+ *   outputPricePerMillion: 10.0,
+ *   cachedInputPricePerMillion: 1.25, // 50% discount for cached tokens
+ * };
+ * ```
+ */
+interface ModelPricing {
+    inputPricePerMillion: number;
+    outputPricePerMillion: number;
+    /** Defaults to inputPricePerMillion if not set */
+    cachedInputPricePerMillion?: number;
+}
+/**
+ * Pricing map for a provider's models.
+ *
+ * @example
+ * ```typescript
+ * const googlePricing: ProviderPricing = {
+ *   'gemini-2.5-flash': { inputPricePerMillion: 0.3, outputPricePerMillion: 2.5 },
+ *   'gemini-2.5-pro': { inputPricePerMillion: 1.25, outputPricePerMillion: 10.0 },
+ * };
+ * ```
+ */
+type ProviderPricing = Record<string, ModelPricing>;
+/**
+ * Global pricing configuration.
+ *
+ * Allows overriding built-in pricing defaults for any provider/model.
+ * Used with `configurePricing()` for global overrides or
+ * `Provider.withPricing()` for provider-level overrides.
+ *
+ * @example
+ * ```typescript
+ * const config: PricingConfig = {
+ *   providers: {
+ *     google: {
+ *       'gemini-2.5-flash': { inputPricePerMillion: 0.5, outputPricePerMillion: 3.0 },
+ *     },
+ *   },
+ *   fallback: {
+ *     inputPricePerMillion: 1.0,
+ *     outputPricePerMillion: 5.0,
+ *   },
+ * };
+ * ```
+ */
+interface PricingConfig {
+    providers?: Partial<Record<ProviderType, ProviderPricing>>;
+    fallback?: ModelPricing;
+}
+/**
+ * Parameters for cost calculation.
+ */
+interface CalculateCostParams {
+    /**
+     * Total input tokens INCLUDING cached tokens.
+     * The cost calculator subtracts cachedInputTokens to get non-cached tokens.
+     */
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * Cached input tokens count (optional).
+     * Must be <= inputTokens. Cached tokens are billed at a lower rate.
+     */
+    cachedInputTokens?: number;
+    model: string;
+    provider: ProviderType;
+}
+/**
+ * Result of cost calculation.
+ */
+interface CostResult {
+    total: number;
+    inputCost: number;
+    outputCost: number;
+    cachedInputCost: number;
+}
+
+/**
+ * Structural interface matching AI SDK's internal Output<OUTPUT, PARTIAL>.
+ *
+ * AI SDK exports `output as Output` (runtime value), not the interface directly.
+ * We define this compatible interface to enable structural typing.
+ *
+ * CRITICAL: Method signatures MUST exactly match AI SDK's internal interface
+ * for generic type inference to work.
+ *
+ * @see AI SDK source: node_modules/ai/dist/index.d.ts lines 572-596
+ */
+interface OutputSpec<OUTPUT = unknown, PARTIAL = unknown> {
+    responseFormat: PromiseLike<unknown>;
+    parseCompleteOutput(options: {
+        text: string;
+    }, context: {
+        response: unknown;
+        usage: unknown;
+        finishReason: unknown;
+    }): Promise<OUTPUT>;
+    parsePartialOutput(options: {
+        text: string;
+    }): Promise<{
+        partial: PARTIAL;
+    } | undefined>;
+}
+type DefaultOutput = OutputSpec<string, string>;
+type InferOutputComplete<T> = T extends OutputSpec<infer O, unknown> ? O : string;
+type GenerateTextResultTyped<TOOLS extends ToolSet, OUTPUT extends OutputSpec> = Awaited<ReturnType<typeof generateText<TOOLS>>> & {
+    output: InferOutputComplete<OUTPUT> | undefined;
+};
+type StreamTextResultTyped<TOOLS extends ToolSet, OUTPUT extends OutputSpec> = ReturnType<typeof streamText<TOOLS>> & {
+    output: Promise<InferOutputComplete<OUTPUT> | undefined>;
+};
+/**
+ * Parameters for session.generateText().
+ * Mirrors AI SDK's generateText() with 'model' excluded (injected by session).
+ */
+type GenerateTextParams<TOOLS extends ToolSet = {}, OUTPUT extends OutputSpec = DefaultOutput> = Omit<Parameters<typeof generateText<TOOLS>>[0], 'model' | 'output'> & {
+    model?: string;
+    output?: OUTPUT;
+};
+
+/**
+ * Parameters for session.streamText().
+ * Mirrors AI SDK's streamText() with 'model' excluded (injected by session).
+ */
+type StreamTextParams<TOOLS extends ToolSet = {}, OUTPUT extends OutputSpec = DefaultOutput> = Omit<Parameters<typeof streamText<TOOLS>>[0], 'model' | 'output'> & {
+    model?: string;
+    output?: OUTPUT;
+};
+
+/**
+ * @deprecated Use generateText with Output.object instead
+ */
+type GenerateObjectParams = Omit<Parameters<typeof generateObject>[0], 'model'>;
+
+interface ToolCallSummary {
+    name: string;
+    duration?: number;
+    success: boolean;
+    error?: string;
+}
+type LLMCallType = 'generateText' | 'streamText' | 'generateObject' | 'manual';
+interface LLMCallRecord {
+    startTime: number;
+    endTime: number;
+    duration: number;
+    usage: LanguageModelUsage;
+    type: LLMCallType;
+    model: string;
+    provider: ProviderType;
+}
+/**
+ * Aggregated summary of all activity within an execution session.
+ * Used for cost tracking, performance analysis, and metadata reporting.
+ */
+interface AdditionalCost {
+    type: string;
+    cost: number;
+    label?: string;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Internal data structure for SessionSummary constructor.
+ */
+interface SessionSummaryData {
+    totalLLMUsage: LanguageModelUsage;
+    llmCalls: LLMCallRecord[];
+    toolCalls: ToolCallSummary[];
+    customRecords: Record<string, unknown>[];
+    llmCost: number;
+    additionalCosts: AdditionalCost[];
+    metadata: Record<string, unknown>;
+    costByModel: Record<string, number>;
+}
+/**
+ * Aggregated summary of all activity within an execution session.
+ * Used for cost tracking, performance analysis, and metadata reporting.
+ *
+ * This is an immutable Value Object. All mutation methods return new instances.
+ */
+declare class SessionSummary {
+    readonly totalLLMUsage: LanguageModelUsage;
+    readonly llmCallCount: number;
+    readonly llmCalls: readonly LLMCallRecord[];
+    readonly toolCalls: readonly ToolCallSummary[];
+    readonly customRecords: readonly Record<string, unknown>[];
+    readonly llmCost: number;
+    readonly additionalCosts: readonly AdditionalCost[];
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** Cost breakdown by model. Key format: `${provider}/${model}` */
+    readonly costByModel: Readonly<Record<string, number>>;
+    private readonly startTime;
+    private constructor();
+    /**
+     * Total duration from session start to now (computed dynamically).
+     */
+    get totalDuration(): number;
+    /**
+     * Creates an empty SessionSummary.
+     */
+    static empty(startTime: number): SessionSummary;
+    /**
+     * Creates a SessionSummary with custom data for testing purposes.
+     * @internal For testing only - do not use in production code.
+     */
+    static forTest(data: Partial<SessionSummaryData> & {
+        startTime?: number;
+    }): SessionSummary;
+    /**
+     * Total cost of all additional (non-LLM) operations.
+     */
+    get totalAdditionalCost(): number;
+    /**
+     * Total cost including LLM and additional costs.
+     */
+    get totalCost(): number;
+    /**
+     * Returns a new SessionSummary with an LLM call added.
+     */
+    withLLMCall(call: LLMCallRecord, newLlmCost: number, newCostByModel: Record<string, number>, newTotalUsage: LanguageModelUsage): SessionSummary;
+    /**
+     * Returns a new SessionSummary with an additional cost recorded.
+     */
+    withAdditionalCost(cost: AdditionalCost): SessionSummary;
+    /**
+     * Returns a new SessionSummary with metadata updated.
+     */
+    withMetadata(key: string, value: unknown): SessionSummary;
+    /**
+     * Returns a new SessionSummary with a tool call added.
+     */
+    withToolCall(call: ToolCallSummary): SessionSummary;
+    /**
+     * Returns a new SessionSummary with a custom record added.
+     */
+    withCustomRecord(record: Record<string, unknown>): SessionSummary;
+    /**
+     * Serializes to plain JSON object for database storage.
+     */
+    toJSON(): SessionSummaryJSON;
+}
+/**
+ * JSON representation of SessionSummary for database storage.
+ */
+interface SessionSummaryJSON {
+    totalDuration: number;
+    totalLLMUsage: LanguageModelUsage;
+    llmCallCount: number;
+    llmCalls: LLMCallRecord[];
+    toolCalls: ToolCallSummary[];
+    customRecords: Record<string, unknown>[];
+    llmCost: number;
+    additionalCosts: AdditionalCost[];
+    metadata: Record<string, unknown>;
+    costByModel: Record<string, number>;
+    totalCost: number;
+    totalAdditionalCost: number;
+}
+/**
+ * Session for tracking LLM calls, tool calls, and custom records.
+ * Provides AI SDK wrappers with auto-tracking and manual recording methods.
+ */
+interface ExecutionSession {
+    generateText(params: GenerateTextParams): Promise<Awaited<ReturnType<typeof generateText>>>;
+    streamText(params: StreamTextParams): ReturnType<typeof streamText>;
+    generateObject<T>(params: GenerateObjectParams & {
+        schema: zod.ZodType<T>;
+    }): Promise<Awaited<ReturnType<typeof generateObject>>>;
+    recordToolCall(summary: ToolCallSummary): void;
+    recordLLMCall(record: Omit<LLMCallRecord, 'type'> & {
+        type?: LLMCallType;
+    }): void;
+    record(data: Record<string, unknown>): void;
+    recordAdditionalCost(cost: Omit<AdditionalCost, 'timestamp'>): void;
+    setMetadata(key: string, value: unknown): void;
+    setMetadata(data: Record<string, unknown>): void;
+    summary(): Promise<SessionSummary>;
+}
+/**
+ * Metadata passed to done() and fail() in StreamGeneratorControl.
+ * Union of SessionSummary and ExecutionMetadata for flexible usage.
+ */
+type DoneMetadata = SessionSummary | ExecutionMetadata;
+
+/**
+ * Logger interface for observability.
+ * All methods are optional - implement only the events you care about.
+ *
+ * @example
+ * ```typescript
+ * const myLogger: Logger = {
+ *   onLLMCallEnd(event) {
+ *     console.log(`${event.modelId}: ${event.response.duration}ms`);
+ *   },
+ *   onExecutionDone(event) {
+ *     console.log('Total duration:', event.duration);
+ *   },
+ * };
+ * ```
+ */
+interface Logger {
+    onLLMCallStart?(event: LLMCallStartEvent): void;
+    onLLMCallEnd?(event: LLMCallEndEvent): void;
+    onExecutionStart?(event: ExecutionStartEvent): void;
+    onExecutionEmit?<TEvent>(event: ExecutionEmitEvent<TEvent>): void;
+    onExecutionDone?<TResult>(event: ExecutionDoneEvent<TResult>): void;
+    onExecutionError?<TResult>(event: ExecutionErrorEvent<TResult>): void;
+    log?(level: LogLevel, message: string, data?: Record<string, unknown>): void;
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+type LLMCallLogType = 'generateText' | 'streamText';
+/**
+ * Event emitted when an LLM call starts.
+ *
+ * @example
+ * ```typescript
+ * logger.onLLMCallStart?.({
+ *   type: 'llm_call_start',
+ *   callType: 'generateText',
+ *   modelId: 'gemini-2.5-flash',
+ *   timestamp: Date.now(),
+ *   request: { params: { prompt: 'Hello' } },
+ * });
+ * ```
+ */
+interface LLMCallStartEvent {
+    type: 'llm_call_start';
+    callType: LLMCallLogType;
+    modelId: string;
+    timestamp: number;
+    request: {
+        params: Record<string, unknown>;
+    };
+}
+/**
+ * Event emitted when an LLM call ends (success or error).
+ *
+ * @example Success case:
+ * ```typescript
+ * logger.onLLMCallEnd?.({
+ *   type: 'llm_call_end',
+ *   callType: 'generateText',
+ *   modelId: 'gemini-2.5-flash',
+ *   timestamp: Date.now(),
+ *   response: {
+ *     duration: 1500,
+ *     usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+ *     raw: result,
+ *   },
+ * });
+ * ```
+ *
+ * @example Error case:
+ * ```typescript
+ * logger.onLLMCallEnd?.({
+ *   type: 'llm_call_end',
+ *   callType: 'streamText',
+ *   modelId: 'gpt-4o',
+ *   timestamp: Date.now(),
+ *   response: {
+ *     duration: 500,
+ *     error: new Error('Rate limit exceeded'),
+ *     raw: null,
+ *   },
+ * });
+ * ```
+ */
+interface LLMCallEndEvent {
+    type: 'llm_call_end';
+    callType: LLMCallLogType;
+    modelId: string;
+    timestamp: number;
+    response: {
+        duration: number;
+        usage?: LanguageModelUsage;
+        raw: unknown;
+        error?: Error;
+    };
+}
+interface ExecutionStartEvent {
+    type: 'execution_start';
+    timestamp: number;
+}
+/**
+ * Event emitted for each intermediate event during execution.
+ * @typeParam TEvent - The type of the emitted event (includes metrics)
+ */
+interface ExecutionEmitEvent<TEvent = unknown> {
+    type: 'execution_emit';
+    event: TEvent;
+}
+/**
+ * Event emitted when execution completes successfully.
+ * @typeParam TResult - The type of the execution result
+ */
+interface ExecutionDoneEvent<TResult = unknown> {
+    type: 'execution_done';
+    timestamp: number;
+    duration: number;
+    data: TResult;
+    summary: SessionSummary;
+}
+/**
+ * Event emitted when execution fails with an error.
+ * @typeParam TResult - The type of partial result data (if available)
+ */
+interface ExecutionErrorEvent<TResult = unknown> {
+    type: 'execution_error';
+    timestamp: number;
+    duration: number;
+    error: Error;
+    data?: TResult;
+    summary?: SessionSummary;
+}
+/**
+ * No-op logger (default when no logger provided).
+ *
+ * @example
+ * ```typescript
+ * const provider = createGoogleProvider({
+ *   apiKey: 'xxx',
+ *   logger: noopLogger,
+ * });
+ * ```
+ */
+declare const noopLogger: Logger;
+/**
+ * Helper to create a logger with only the handlers you need.
+ *
+ * @example
+ * ```typescript
+ * const metricsLogger = createLogger({
+ *   onLLMCallEnd(event) {
+ *     metrics.recordLatency(event.response.duration);
+ *   },
+ *   onExecutionDone(event) {
+ *     metrics.recordTokens(event.summary.totalLLMUsage.totalTokens);
+ *   },
+ * });
+ * ```
+ */
+declare function createLogger(handlers: Partial<Logger>): Logger;
+
+/** Result of uploading a file to a provider's file storage */
+interface UploadedFile {
+    /** Unique identifier from the provider (used for deletion, null for external URLs) */
+    id: string | null;
+    /** AI SDK part ready for use in prompts */
+    part: FilePart | ImagePart;
+}
+/** Provider-agnostic file manager interface for upload/delete operations */
+interface FileManager {
+    upload(files: FileSource[]): Promise<UploadedFile[]>;
+    delete(fileId: string): Promise<void>;
+    clear(): Promise<void>;
+    getUploadedFiles(): UploadedFile[];
+}
+/** Cache for uploaded files to prevent duplicate uploads */
+interface FileCache {
+    get(hash: string): UploadedFile | null;
+    set(hash: string, file: UploadedFile, ttl?: number): void;
+    delete(hash: string): void;
+    clear(): void;
+}
+interface FileManagerOptions {
+    cache?: FileCache;
+}
+interface FileSourcePath {
+    source: 'path';
+    path: string;
+    mediaType?: string;
+    filename?: string;
+    hash?: string;
+}
+interface FileSourceData {
+    source: 'data';
+    data: Buffer | Uint8Array;
+    mediaType: string;
+    filename?: string;
+    hash?: string;
+}
+interface FileSourceBase64 {
+    source: 'base64';
+    data: string;
+    mediaType: string;
+    filename?: string;
+    hash?: string;
+}
+interface FileSourceUrl {
+    source: 'url';
+    url: string;
+    mediaType?: string;
+    filename?: string;
+    hash?: string;
+}
+/** Union of all file part types. Use `source` to discriminate. */
+type FileSource = FileSourcePath | FileSourceData | FileSourceBase64 | FileSourceUrl;
+declare function isFileSource(v: unknown): v is FileSource;
+declare function isFileSourcePath(v: FileSource): v is FileSourcePath;
+declare function isFileSourceData(v: FileSource): v is FileSourceData;
+declare function isFileSourceBase64(v: FileSource): v is FileSourceBase64;
+declare function isFileSourceUrl(v: FileSource): v is FileSourceUrl;
+/** Provider interface with fluent configuration for AI model operations */
+interface Provider {
+    withDefaultModel(modelId: string): Provider;
+    withLogger(logger: Logger): Provider;
+    withPricing(pricing: ProviderPricing): Provider;
+    /**
+     * Set default provider-specific options for all LLM calls.
+     * These options will be deep-merged with per-call providerOptions.
+     * The actual options type depends on the provider (Google, OpenAI, etc.).
+     */
+    withDefaultOptions(options: Record<string, unknown>): Provider;
+    streamingExecution<TEvent extends {
+        type: string;
+    }>(generator: (session: StreamingSession<TEvent>) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>>>, options?: ExecutionOptions): StreamingExecution<TEvent>;
+    /**
+     * Execute a non-streaming function with the provider.
+     * Returns immediately (sync) - execution starts in the background.
+     *
+     * Breaking change: Previously returned Promise<Execution<TResult>>.
+     * Now returns SimpleExecution<TResult> directly (no await needed).
+     *
+     * @example
+     * ```typescript
+     * // Before (v1.x):
+     * const execution = provider.simpleExecution(fn);
+     *
+     * // After (v2.x):
+     * const execution = provider.simpleExecution(fn);
+     * execution.cancel(); // Can cancel in-progress LLM calls
+     * const result = await execution.result();
+     * ```
+     */
+    simpleExecution<TResult>(fn: (session: SimpleSession) => Promise<TResult>, options?: ExecutionOptions): SimpleExecution<TResult>;
+}
+
+/**
+ * Provider-specific options type.
+ * Maps provider names (e.g., 'google', 'openai') to their option objects.
+ */
+type ProviderOptions$1 = Record<string, Record<string, unknown>>;
+interface SimpleSessionOptions {
+    defaultLanguageModel?: LanguageModel | null;
+    modelFactory?: (modelId: string) => LanguageModel;
+    providerType: ProviderType;
+    providerPricing?: ProviderPricing;
+    fileManager: FileManager;
+    logger?: Logger;
+    startTime?: number;
+    /**
+     * AbortSignal for cancelling AI SDK calls.
+     * When aborted, ongoing generateText/streamText calls will be cancelled.
+     */
+    signal?: AbortSignal;
+    /**
+     * Default provider-specific options to apply to all LLM calls.
+     * These will be deep-merged with per-call providerOptions (per-call takes precedence).
+     */
+    defaultProviderOptions?: ProviderOptions$1;
+    /**
+     * Default tools to apply to all LLM calls (e.g., google_search, url_context).
+     * These will be merged with per-call tools (per-call takes precedence).
+     */
+    defaultTools?: ToolSet;
+}
+declare class SimpleSession {
+    private readonly defaultLanguageModel;
+    private readonly modelFactory;
+    private readonly providerType;
+    private readonly providerPricing;
+    private readonly defaultProviderOptions;
+    private readonly defaultTools;
+    private readonly _fileManager;
+    private readonly logger;
+    private readonly sessionStartTime;
+    private readonly signal?;
+    private summary;
+    private readonly pendingUsagePromises;
+    private readonly onDoneFns;
+    constructor(options: SimpleSessionOptions);
+    private getModel;
+    private extractModelId;
+    generateText<TOOLS extends ToolSet = {}, OUTPUT extends OutputSpec = DefaultOutput>(params: GenerateTextParams<TOOLS, OUTPUT>): Promise<GenerateTextResultTyped<TOOLS, OUTPUT>>;
+    streamText<TOOLS extends ToolSet = {}, OUTPUT extends OutputSpec = DefaultOutput>(params: StreamTextParams<TOOLS, OUTPUT>): StreamTextResultTyped<TOOLS, OUTPUT>;
+    get fileManager(): FileManager;
+    record(data: Record<string, unknown>): void;
+    recordToolCall(toolCallSummary: ToolCallSummary): void;
+    recordLLMCall(record: Omit<LLMCallRecord, 'type'> & {
+        type?: LLMCallType;
+    }): void;
+    recordAdditionalCost(cost: Omit<AdditionalCost, 'timestamp'>): void;
+    setMetadata(key: string, value: unknown): void;
+    setMetadata(data: Record<string, unknown>): void;
+    private updateSummaryWithLLMCall;
+    onDone(fn: () => Promise<void> | void): void;
+    runOnDoneHooks(): Promise<void>;
+    getSummary(): Promise<SessionSummary>;
+    /**
+     * Notifies Logger of execution start.
+     * @internal Called by SimpleExecutionHost - not intended for direct use.
+     */
+    notifyExecutionStart(): void;
+    /**
+     * Notifies Logger of execution completion with result data and summary.
+     * @param data - The execution result data
+     * @param startTime - Execution start timestamp for duration calculation
+     * @internal Called by SimpleExecutionHost - not intended for direct use.
+     */
+    notifyExecutionDone<T>(data: T, startTime: number): Promise<void>;
+    /**
+     * Notifies Logger of execution error with error details and summary (if available).
+     * Gracefully handles getSummary() failures - summary will be undefined if it fails.
+     * @param error - The error that occurred
+     * @param startTime - Execution start timestamp for duration calculation
+     * @internal Called by SimpleExecutionHost - not intended for direct use.
+     */
+    notifyExecutionError(error: Error, startTime: number): Promise<void>;
+    protected get _logger(): Logger;
+    protected get _startTime(): number;
+    protected get _modelId(): string;
+}
+
+type ProviderOptions = Record<string, Record<string, unknown>>;
+interface StreamingSessionOptions {
+    defaultLanguageModel?: LanguageModel | null;
+    modelFactory?: (modelId: string) => LanguageModel;
+    providerType: ProviderType;
+    providerPricing?: ProviderPricing;
+    fileManager: FileManager;
+    logger?: Logger;
+    startTime?: number;
+    signal?: AbortSignal;
+    defaultProviderOptions?: ProviderOptions;
+    defaultTools?: ToolSet;
+}
+declare class StreamingSession<TEvent extends {
+    type: string;
+}> extends SimpleSession {
+    private lastEventTime;
+    private _terminated;
+    constructor(options: StreamingSessionOptions);
+    /**
+     * Emits a streaming event with automatically attached metrics.
+     *
+     * Reserved types ('complete', 'error') throw at runtime - use session.done()
+     * or session.fail() instead.
+     *
+     * @param event - The event to emit (metrics will be added automatically)
+     * @returns The complete event with metrics attached
+     * @throws Error when attempting to emit reserved types ('complete', 'error')
+     */
+    emit(event: EmittableEventInput<TEvent>): SessionEvent<TEvent>;
+    /**
+     * Internal emit method - bypasses reserved type check.
+     * Used by done() and fail() to emit terminal events.
+     */
+    private emitInternal;
+    /**
+     * Signals successful completion of the streaming execution.
+     * Emits a 'complete' event with the result data and session summary.
+     * Also triggers Logger.onExecutionDone for observability.
+     * @param data - The final result data
+     * @returns The complete event with data and summary
+     */
+    done(data: ExtractResult<TEvent>): Promise<SessionEvent<TEvent>>;
+    /**
+     * Signals that the streaming execution failed with an error.
+     * Emits an 'error' event and triggers Logger.onExecutionError for observability.
+     * Gracefully handles getSummary() failures - summary will be undefined if it fails.
+     * @param error - The error that caused the failure
+     * @param data - Optional partial result data (if any was produced before failure)
+     * @returns The error event
+     */
+    fail(error: Error, data?: ExtractResult<TEvent>): Promise<SessionEvent<TEvent>>;
+    private createMetrics;
+}
+interface StreamingSessionInternal<TEvent extends {
+    type: string;
+}> {
+    generateText: SimpleSession['generateText'];
+    streamText: SimpleSession['streamText'];
+    fileManager: FileManager;
+    onDone: SimpleSession['onDone'];
+    record: SimpleSession['record'];
+    recordToolCall: SimpleSession['recordToolCall'];
+    emit(event: EmittableEventInput<TEvent>): SessionEvent<TEvent>;
+    done(data: ExtractResult<TEvent>): Promise<SessionEvent<TEvent>>;
+    fail(error: Error, data?: ExtractResult<TEvent>): Promise<SessionEvent<TEvent>>;
+    runOnDoneHooks(): Promise<void>;
+    getSummary(): Promise<SessionSummary>;
+}
+interface CreateStreamingSessionOptions {
+    defaultLanguageModel: LanguageModel;
+    providerType: ProviderType;
+    fileManager: FileManager;
+    logger?: Logger;
+    startTime?: number;
+    signal?: AbortSignal;
+}
+declare function createStreamingSession<TEvent extends {
+    type: string;
+}>(options: CreateStreamingSessionOptions): StreamingSessionInternal<TEvent>;
+
+/**
+ * Agent execution types for @agtlantis/core.
+ * Provides abstractions for streaming and non-streaming agent execution.
+ */
+
+/**
+ * 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 }
+ * ```
+ */
+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 } },
+ * ];
+ * ```
+ */
+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
+ */
+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().
+ */
+type ReservedEventType = 'complete' | 'error';
+/**
+ * Input type for emit() - excludes reserved event types.
+ * Users define pure domain events; framework adds metrics wrapper.
+ */
+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 }
+ * ```
+ */
+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);
+ *   }
+ * }
+ * ```
+ */
+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 }
+ * ```
+ */
+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.
+ */
+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
+ */
+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}`);
+ * ```
+ */
+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.
+ */
+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);
+ * }
+ * ```
+ */
+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();
+ * }
+ * ```
+ */
+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}`);
+ * ```
+ */
+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.
+ */
+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.
+ */
+type SessionStreamGeneratorFn<TEvent extends {
+    type: string;
+}> = (session: StreamingSession<TEvent>) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>> | undefined, unknown>;
+
+/**
+ * Abstract base class for AI providers.
+ *
+ * Provides common streamingExecution and simpleExecution implementation.
+ * Subclasses implement session creation and fluent configuration methods.
+ */
+declare abstract class BaseProvider implements Provider {
+    /**
+     * Create a SimpleSession for non-streaming execution.
+     * @param signal - AbortSignal for cancellation support
+     */
+    protected abstract createSimpleSession(signal?: AbortSignal): SimpleSession;
+    /**
+     * Create a StreamingSession for streaming execution.
+     * @param signal - AbortSignal for cancellation support
+     */
+    protected abstract createStreamingSession<TEvent extends {
+        type: string;
+    }>(signal?: AbortSignal): StreamingSession<TEvent>;
+    abstract withDefaultModel(modelId: string): Provider;
+    abstract withLogger(logger: Logger): Provider;
+    abstract withPricing(pricing: ProviderPricing): Provider;
+    abstract withDefaultOptions(options: Record<string, unknown>): Provider;
+    streamingExecution<TEvent extends {
+        type: string;
+    }>(generator: (session: StreamingSession<TEvent>) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>>>, options?: ExecutionOptions): StreamingExecution<TEvent>;
+    /**
+     * Execute a non-streaming function with cancellation support.
+     * Returns immediately - execution starts in the background.
+     */
+    simpleExecution<TResult>(fn: (session: SimpleSession) => Promise<TResult>, options?: ExecutionOptions): SimpleExecution<TResult>;
+}
+
+export { isFileSourceBase64 as $, type LLMCallStartEvent as A, BaseProvider as B, type CalculateCostParams as C, type DistributiveOmit as D, type ErrorEvent as E, type FileSource as F, type LLMCallEndEvent as G, type ExecutionStartEvent as H, type ExecutionEmitEvent as I, type ExecutionDoneEvent as J, type ExecutionErrorEvent as K, type Logger as L, type ModelPricing as M, noopLogger as N, createLogger as O, type ProviderType as P, type Provider as Q, type ReservedEventType as R, type StreamingExecution as S, type FileSourcePath as T, type UploadedFile as U, type FileSourceData as V, type FileSourceBase64 as W, type FileSourceUrl as X, isFileSource as Y, isFileSourcePath as Z, isFileSourceData as _, type PricingConfig as a, isFileSourceUrl as a0, type SimpleSessionOptions as a1, createStreamingSession as a2, type StreamingSessionOptions as a3, type CreateStreamingSessionOptions as a4, type StreamingSessionInternal as a5, type OutputSpec as a6, type DefaultOutput as a7, type InferOutputComplete as a8, type GenerateTextResultTyped as a9, type StreamTextResultTyped as aa, type GenerateTextParams as ab, type GenerateObjectParams as ac, type ToolCallSummary as ad, type LLMCallType as ae, type LLMCallRecord as af, type AdditionalCost as ag, SessionSummary as ah, type SessionSummaryJSON as ai, type ExecutionSession as aj, type DoneMetadata as ak, type ProviderPricing as b, type CostResult as c, StreamingSession as d, type SessionStreamGeneratorFn as e, type SessionEvent as f, type StreamingResult as g, type ExtractResult as h, type SimpleExecution as i, SimpleSession as j, type SimpleResult as k, type ExecutionStatus as l, type CompletionEvent as m, type StreamTextParams as n, type FileCache as o, type FileManager as p, type FileManagerOptions as q, type Execution as r, type ExecutionOptions as s, type ExecutionResult as t, type SessionEventInput as u, type EmittableEventInput as v, type EventMetrics as w, type ExecutionMetadata as x, type LogLevel as y, type LLMCallLogType as z };