@agtlantis/core 0.4.1

package/dist/index.d.cts

@@ -0,0 +1,1502 @@
+import { P as ProviderType, a as PricingConfig, M as ModelPricing, b as ProviderPricing, C as CalculateCostParams, c as CostResult, S as StreamingExecution, d as StreamingSession, e as SessionStreamGeneratorFn, f as SessionEvent, E as ErrorEvent, g as StreamingResult, h as ExtractResult, i as SimpleExecution, j as SimpleSession, k as SimpleResult, l as ExecutionStatus, m as CompletionEvent, n as StreamTextParams, B as BaseProvider, F as FileSource, o as FileCache, U as UploadedFile, p as FileManager, L as Logger, q as FileManagerOptions } from './base-provider-C3mFLNiN.cjs';
+export { ag as AdditionalCost, a4 as CreateStreamingSessionOptions, a7 as DefaultOutput, D as DistributiveOmit, ak as DoneMetadata, v as EmittableEventInput, w as EventMetrics, r as Execution, J as ExecutionDoneEvent, I as ExecutionEmitEvent, K as ExecutionErrorEvent, x as ExecutionMetadata, s as ExecutionOptions, t as ExecutionResult, aj as ExecutionSession, H as ExecutionStartEvent, W as FileSourceBase64, V as FileSourceData, T as FileSourcePath, X as FileSourceUrl, ac as GenerateObjectParams, ab as GenerateTextParams, a9 as GenerateTextResultTyped, a8 as InferOutputComplete, G as LLMCallEndEvent, z as LLMCallLogType, af as LLMCallRecord, A as LLMCallStartEvent, ae as LLMCallType, y as LogLevel, a6 as OutputSpec, Q as Provider, R as ReservedEventType, u as SessionEventInput, ah as SessionSummary, ai as SessionSummaryJSON, a1 as SimpleSessionOptions, aa as StreamTextResultTyped, a5 as StreamingSessionInternal, a3 as StreamingSessionOptions, ad as ToolCallSummary, O as createLogger, a2 as createStreamingSession, Y as isFileSource, $ as isFileSourceBase64, _ as isFileSourceData, Z as isFileSourcePath, a0 as isFileSourceUrl, N as noopLogger } from './base-provider-C3mFLNiN.cjs';
+import { LanguageModelUsage, ToolSet, StopCondition } from 'ai';
+export { GenerateTextResult, LanguageModelUsage, StreamTextResult, ToolSet } from 'ai';
+import { z } from 'zod';
+import { GoogleGenerativeAIProviderOptions } from '@ai-sdk/google';
+export { GoogleGenerativeAIProviderOptions } from '@ai-sdk/google';
+import { OpenAIChatLanguageModelOptions } from '@ai-sdk/openai';
+export { OpenAIChatLanguageModelOptions } from '@ai-sdk/openai';
+
+declare enum ExecutionErrorCode {
+    EXECUTION_ERROR = "EXECUTION_ERROR",
+    STREAM_ERROR = "STREAM_ERROR",
+    RESULT_EXTRACTION_ERROR = "RESULT_EXTRACTION_ERROR",
+    CANCELLED = "CANCELLED",
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+}
+declare enum ConfigurationErrorCode {
+    CONFIG_ERROR = "CONFIG_ERROR",
+    MISSING_API_KEY = "MISSING_API_KEY",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    MISSING_REQUIRED = "MISSING_REQUIRED"
+}
+declare enum FileErrorCode {
+    FILE_ERROR = "FILE_ERROR",
+    UPLOAD_ERROR = "UPLOAD_ERROR",
+    DELETE_ERROR = "DELETE_ERROR",
+    NOT_FOUND = "NOT_FOUND",
+    TOO_LARGE = "TOO_LARGE",
+    UNSUPPORTED_TYPE = "UNSUPPORTED_TYPE"
+}
+type AgtlantisErrorCode = ExecutionErrorCode | ConfigurationErrorCode | FileErrorCode;
+interface AgtlantisErrorOptions<TCode extends AgtlantisErrorCode = AgtlantisErrorCode> {
+    code: TCode;
+    cause?: Error;
+    context?: Record<string, unknown>;
+}
+interface ErrorOptions<TCode extends AgtlantisErrorCode> {
+    code?: TCode;
+    cause?: Error;
+    context?: Record<string, unknown>;
+}
+type ExecutionErrorOptions = ErrorOptions<ExecutionErrorCode>;
+type ConfigurationErrorOptions = ErrorOptions<ConfigurationErrorCode>;
+type FileErrorOptions = ErrorOptions<FileErrorCode>;
+/**
+ * Base error class for all Agtlantis errors.
+ * Provides structured error information including error code and optional context.
+ */
+declare class AgtlantisError<TCode extends AgtlantisErrorCode = AgtlantisErrorCode> extends Error {
+    readonly code: TCode;
+    readonly cause?: Error;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options: AgtlantisErrorOptions<TCode>);
+    get isRetryable(): boolean;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown during agent execution (streaming failures, result extraction, cancellation).
+ */
+declare class ExecutionError extends AgtlantisError<ExecutionErrorCode> {
+    constructor(message: string, options?: ExecutionErrorOptions);
+    static from(error: unknown, code?: ExecutionErrorCode, context?: Record<string, unknown>): ExecutionError;
+}
+/**
+ * Error thrown when configuration is invalid or missing (API keys, model names).
+ */
+declare class ConfigurationError extends AgtlantisError<ConfigurationErrorCode> {
+    constructor(message: string, options?: ConfigurationErrorOptions);
+    static from(error: unknown, code?: ConfigurationErrorCode, context?: Record<string, unknown>): ConfigurationError;
+}
+/**
+ * Error thrown during file operations (upload, delete, not found, size limits).
+ */
+declare class FileError extends AgtlantisError<FileErrorCode> {
+    constructor(message: string, options?: FileErrorOptions);
+    static from(error: unknown, code?: FileErrorCode, context?: Record<string, unknown>): FileError;
+}
+
+declare function mergeUsages(usages: LanguageModelUsage[]): LanguageModelUsage;
+declare function createZeroUsage(): LanguageModelUsage;
+declare function detectProviderType(modelId: string): ProviderType | undefined;
+
+/**
+ * Global pricing configuration.
+ *
+ * Priority order (highest to lowest):
+ * 1. Provider.withPricing() - per-provider override
+ * 2. configurePricing() - global override
+ * 3. Built-in defaults (defaults.ts)
+ * 4. Fallback pricing
+ *
+ * @module pricing/config
+ */
+
+/**
+ * Configure global pricing overrides.
+ *
+ * WARNING: This uses global mutable state and is not thread-safe.
+ * For multi-tenant scenarios or concurrent requests with different pricing,
+ * use `Provider.withPricing()` instead for proper isolation.
+ *
+ * @example
+ * ```typescript
+ * configurePricing({
+ *   providers: {
+ *     google: {
+ *       'gemini-2.5-flash': { inputPricePerMillion: 0.5, outputPricePerMillion: 3.0 },
+ *     },
+ *   },
+ * });
+ *
+ * // Reset to built-in defaults
+ * configurePricing(undefined);
+ * ```
+ */
+declare function configurePricing(config: PricingConfig | undefined): void;
+declare function getPricingConfig(): PricingConfig | undefined;
+/**
+ * Reset global pricing configuration.
+ * Useful for testing to ensure clean state between tests.
+ */
+declare function resetPricingConfig(): void;
+type PricingSource = 'global' | 'default' | 'fallback';
+interface EffectivePricingResult {
+    pricing: ModelPricing;
+    source: PricingSource;
+}
+/**
+ * Get effective pricing for a model with source information.
+ * Useful for debugging to understand which pricing layer is applied.
+ *
+ * @example
+ * ```typescript
+ * const result = getEffectivePricing('gemini-2.5-flash', 'google');
+ * console.log(result.source); // 'default' (using built-in pricing)
+ *
+ * configurePricing({ providers: { google: { 'gemini-2.5-flash': {...} } } });
+ * const result2 = getEffectivePricing('gemini-2.5-flash', 'google');
+ * console.log(result2.source); // 'global' (using configured override)
+ * ```
+ */
+declare function getEffectivePricing(model: string, provider: ProviderType): EffectivePricingResult;
+
+/**
+ * Pricing validation utilities.
+ *
+ * Provides fail-fast validation for pricing configuration to catch
+ * invalid values (negative, NaN, Infinity) at configuration time.
+ *
+ * @module pricing/validator
+ */
+
+/**
+ * Validates a ModelPricing object.
+ * Ensures all price values are non-negative and finite.
+ *
+ * @throws {Error} If any price value is invalid
+ *
+ * @example
+ * ```typescript
+ * validateModelPricing(
+ *   { inputPricePerMillion: 2.5, outputPricePerMillion: 10.0 },
+ *   'openai/gpt-4o'
+ * );
+ * ```
+ */
+declare function validateModelPricing(pricing: ModelPricing, context: string): void;
+/**
+ * Validates a ProviderPricing object.
+ *
+ * @throws {Error} If any model pricing is invalid
+ *
+ * @example
+ * ```typescript
+ * validateProviderPricing({
+ *   'gemini-2.5-flash': { inputPricePerMillion: 0.3, outputPricePerMillion: 2.5 },
+ *   'gemini-2.5-pro': { inputPricePerMillion: 1.25, outputPricePerMillion: 10.0 },
+ * }, 'google');
+ * ```
+ */
+declare function validateProviderPricing(pricing: ProviderPricing, providerContext?: string): void;
+/**
+ * Validates a PricingConfig object.
+ *
+ * @throws {Error} If any pricing configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * validatePricingConfig({
+ *   providers: {
+ *     google: { 'gemini-2.5-flash': { inputPricePerMillion: 0.3, outputPricePerMillion: 2.5 } },
+ *   },
+ *   fallback: { inputPricePerMillion: 1.0, outputPricePerMillion: 5.0 },
+ * });
+ * ```
+ */
+declare function validatePricingConfig(config: PricingConfig): void;
+
+/**
+ * Cost calculation functions.
+ *
+ * @module pricing/calculator
+ *
+ * NOTE: Cost calculations use standard JavaScript floating-point arithmetic.
+ * For high-volume usage tracking, accumulated totals may have minor precision drift.
+ * For financial reporting, consider rounding results to appropriate decimal places
+ * (e.g., `Math.round(cost * 100) / 100` for cents).
+ */
+
+/**
+ * Get pricing for a specific model.
+ *
+ * Resolution order:
+ * 1. Provider-level config (providerPricing param)
+ * 2. Global config (configurePricing)
+ * 3. Built-in defaults
+ * 4. Fallback pricing
+ */
+declare function getModelPricing(model: string, provider: ProviderType, providerPricing?: ProviderPricing): ModelPricing;
+/**
+ * Calculate cost from token counts.
+ *
+ * @throws Error if token counts are negative, non-finite, or if cachedInputTokens > inputTokens
+ *
+ * @example
+ * ```typescript
+ * const cost = calculateCost({
+ *   inputTokens: 1000,
+ *   outputTokens: 500,
+ *   cachedInputTokens: 200,
+ *   model: 'gemini-2.5-flash',
+ *   provider: 'google',
+ * });
+ * console.log(cost.total); // 0.000315
+ * ```
+ */
+declare function calculateCost(params: CalculateCostParams, providerPricing?: ProviderPricing): CostResult;
+/**
+ * Calculate cost from AI SDK LanguageModelUsage.
+ *
+ * Convenience function that extracts token counts from the
+ * AI SDK's LanguageModelUsage type and calculates the cost.
+ *
+ * @example
+ * ```typescript
+ * const usage = await result.usage;
+ * const cost = calculateCostFromUsage(usage, 'gemini-2.5-flash', 'google');
+ * ```
+ */
+declare function calculateCostFromUsage(usage: LanguageModelUsage, model: string, provider: ProviderType, providerPricing?: ProviderPricing): CostResult;
+/**
+ * Calculate total cost for multiple LLM calls.
+ *
+ * Aggregates costs from multiple calls, grouping by model.
+ *
+ * @returns Object with:
+ *   - `totalCost`: Sum of all call costs in USD
+ *   - `costByModel`: Map where key format is `${provider}/${model}`
+ */
+declare function calculateTotalCost(calls: Array<{
+    usage: LanguageModelUsage;
+    model: string;
+    provider: ProviderType;
+}>, providerPricing?: ProviderPricing): {
+    totalCost: number;
+    costByModel: Record<string, number>;
+};
+
+/**
+ * Built-in pricing tables (USD per million tokens).
+ *
+ * These are the default prices for common models. They can be overridden
+ * using `configurePricing()` (global) or `Provider.withPricing()` (per-provider).
+ *
+ * Last updated: January 2025
+ *
+ * @module pricing/defaults
+ */
+
+/**
+ * OpenAI model pricing.
+ * @see https://openai.com/pricing
+ */
+declare const OPENAI_PRICING: ProviderPricing;
+/**
+ * Google Gemini model pricing.
+ * @see https://ai.google.dev/gemini-api/docs/pricing
+ */
+declare const GOOGLE_PRICING: ProviderPricing;
+/**
+ * Anthropic Claude model pricing.
+ * @see https://www.anthropic.com/pricing
+ */
+declare const ANTHROPIC_PRICING: ProviderPricing;
+declare const DEFAULT_PRICING_CONFIG: Required<PricingConfig>;
+declare const DEFAULT_FALLBACK_PRICING: ModelPricing;
+
+/**
+ * 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);
+ * }
+ * ```
+ */
+declare class StreamingExecutionHost<TEvent extends {
+    type: string;
+}> implements StreamingExecution<TEvent> {
+    private readonly createSession;
+    private readonly generator;
+    private readonly abortController;
+    private readonly effectiveSignal;
+    private readonly consumerPromise;
+    private readonly eventBuffer;
+    private readonly subscribers;
+    private completed;
+    private cleaned;
+    private hookRunner;
+    private cancelRequested;
+    private extractedOutcome;
+    private extractedSummary;
+    constructor(createSession: (signal?: AbortSignal) => StreamingSession<TEvent>, generator: SessionStreamGeneratorFn<TEvent>, userSignal?: AbortSignal);
+    private hasDataField;
+    private hasSummaryField;
+    private hasErrorField;
+    private extractResultAndMetadata;
+    private notifySubscribers;
+    private startConsuming;
+    private buildResult;
+    /**
+     * Get the event stream.
+     * Returns buffered events first, then real-time events.
+     * Can be called multiple times - replays buffer each time.
+     */
+    stream(): AsyncIterable<SessionEvent<TEvent | ErrorEvent>>;
+    cancel(): void;
+    cleanup(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Get the execution result with status, summary, and all events.
+     * Never throws - returns a discriminated union with status.
+     */
+    result(): Promise<StreamingResult<SessionEvent<TEvent | ErrorEvent>, ExtractResult<TEvent>>>;
+}
+
+/**
+ * SimpleExecutionHost implements the SimpleExecution interface for eager execution.
+ *
+ * Execution starts immediately on construction (eager evaluation).
+ * Use result() to get the execution outcome with status and summary.
+ *
+ * Signal combination:
+ * - If userSignal is provided, it's combined with internal AbortController
+ * - Both cancel() and userSignal abort will trigger cancellation
+ * - The combined signal is passed to SimpleSession for AI SDK calls
+ *
+ * @example
+ * ```typescript
+ * const execution = new SimpleExecutionHost(createSession, async (session) => {
+ *   return await session.generateText({ prompt: 'Hello' });
+ * });
+ *
+ * const result = await execution.result();
+ *
+ * if (result.status === 'succeeded') {
+ *   console.log(result.value);
+ * }
+ * console.log(`Cost: $${result.summary.totalCost}`);
+ * ```
+ */
+declare class SimpleExecutionHost<TResult> implements SimpleExecution<TResult> {
+    private readonly abortController;
+    private readonly effectiveSignal;
+    private readonly consumerPromise;
+    private cachedSession?;
+    private readonly startTime;
+    private cancelRequested;
+    constructor(createSession: (signal?: AbortSignal) => SimpleSession, fn: (session: SimpleSession) => Promise<TResult>, userSignal?: AbortSignal);
+    private execute;
+    /**
+     * Request cancellation of the execution.
+     * Aborts the current LLM call if in progress.
+     * No-op if execution already completed.
+     */
+    cancel(): void;
+    /**
+     * Get the execution result with status and summary.
+     * Never throws - returns a discriminated union with status.
+     */
+    result(): Promise<SimpleResult<TResult>>;
+    /**
+     * Cleanup resources.
+     * For SimpleExecution, hooks are already run during execution,
+     * so this is intentionally a no-op.
+     */
+    cleanup(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+declare const ERRORS: {
+    readonly ALREADY_CONSUMED: "Execution already consumed";
+    readonly METADATA_NOT_AVAILABLE: "Metadata not available yet. Consume the execution first.";
+    readonly NO_RESULT: "No result available";
+    readonly UNKNOWN_ERROR: "Execution failed with unknown error";
+};
+
+/**
+ * Calculate duration from start time in milliseconds.
+ *
+ * @param startTime - The start timestamp from Date.now()
+ * @returns Duration in milliseconds
+ */
+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
+ * ```
+ */
+declare function combineSignals(...signals: AbortSignal[]): AbortSignal;
+
+/**
+ * Shared utilities for execution hosts.
+ *
+ * These functions extract common patterns from SimpleExecutionHost and
+ * StreamingExecutionHost to reduce code duplication and ensure consistent
+ * behavior across both implementations.
+ */
+/**
+ * Checks if an error is an abort-related error.
+ *
+ * An error is considered abort-related if either:
+ * - The error has the name 'AbortError' (standard for AbortController)
+ * - The signal has been aborted (covers edge cases where error name differs)
+ *
+ * @param error - The error to check
+ * @param signal - The AbortSignal associated with the execution
+ * @returns true if this is an abort-related error
+ */
+declare function isAbortError(error: unknown, signal: AbortSignal): boolean;
+/**
+ * Normalizes an unknown error to an Error instance.
+ *
+ * If the error is already an Error instance, it's returned as-is.
+ * Otherwise, it's converted to a string and wrapped in a new Error.
+ *
+ * @param error - The unknown error to normalize
+ * @returns A proper Error instance
+ */
+declare function normalizeError(error: unknown): Error;
+/**
+ * Determines the execution status based on the execution state.
+ *
+ * Status determination priority:
+ * 1. If user called cancel() OR the operation was aborted → 'canceled'
+ * 2. If there's an error → 'failed'
+ * 3. Otherwise → 'succeeded'
+ *
+ * Note: The 'aborted' flag takes precedence over 'hasError' because
+ * AbortError is treated as a normal cancellation, not a failure.
+ *
+ * @param cancelRequested - Whether cancel() was explicitly called
+ * @param aborted - Whether the signal was aborted (includes external abort)
+ * @param hasError - Whether the execution ended with an error
+ * @returns The appropriate execution status
+ */
+declare function determineResultStatus(cancelRequested: boolean, aborted: boolean, hasError: boolean): ExecutionStatus;
+/**
+ * Return type for createHookRunner utility.
+ */
+type HookRunner = {
+    /**
+     * Ensures hooks run exactly once.
+     * Safe to call multiple times - only executes on first call.
+     */
+    ensureRun: () => Promise<void>;
+    /**
+     * Check if hooks have already been run.
+     */
+    hasRun: () => boolean;
+};
+/**
+ * Creates a hook runner that ensures hooks run exactly once.
+ *
+ * This utility encapsulates the common pattern of running cleanup hooks
+ * with a guard flag to prevent double execution. Both SimpleExecutionHost
+ * and StreamingExecutionHost use this pattern for onDone hooks.
+ *
+ * @param runHooks - The async function to run hooks
+ * @returns Object with ensureRun() and hasRun() methods
+ *
+ * @example
+ * ```typescript
+ * const hookRunner = createHookRunner(async () => {
+ *   await session.runOnDoneHooks();
+ * });
+ *
+ * // In finally block or cleanup:
+ * await hookRunner.ensureRun();
+ *
+ * // Safe to call multiple times - only executes once
+ * await hookRunner.ensureRun(); // no-op
+ * ```
+ */
+declare function createHookRunner(runHooks: () => Promise<void>): HookRunner;
+
+type ReplaceResult<TEvent extends {
+    type: string;
+}, U> = Exclude<TEvent, {
+    type: 'complete';
+}> | CompletionEvent<U>;
+declare function mapExecution<TEvent extends {
+    type: string;
+}, UEvent extends {
+    type: string;
+}>(execution: StreamingExecution<TEvent>, fn: (event: TEvent) => UEvent | Promise<UEvent>): StreamingExecution<UEvent>;
+declare function mapExecution<A, B>(execution: SimpleExecution<A>, fn: (result: A) => B | Promise<B>): SimpleExecution<B>;
+declare function mapExecutionResult<TEvent extends {
+    type: string;
+}, U>(execution: StreamingExecution<TEvent>, fn: (result: ExtractResult<TEvent>) => U | Promise<U>): StreamingExecution<ReplaceResult<TEvent, U>>;
+declare function mapExecutionResult<A, B>(execution: SimpleExecution<A>, fn: (result: A) => B | Promise<B>): SimpleExecution<B>;
+
+type ProgressiveStreamOptions<TUserTools extends ToolSet = {}> = Omit<StreamTextParams<TUserTools>, 'tools' | 'toolChoice' | 'stopWhen'> & {
+    tools?: TUserTools;
+    /**
+     * Additional stop conditions. Will be combined with the default
+     * `hasToolCall('submitResult')`.
+     */
+    stopWhen?: StopCondition<ToolSet> | StopCondition<ToolSet>[];
+    /**
+     * Custom protocol instructions appended to the system prompt.
+     * If not provided, uses the default TOOL_CALLING_PROTOCOL.
+     */
+    protocol?: string;
+};
+/**
+ * Progress event - pure domain event without metrics.
+ * Framework automatically wraps with SessionEvent at runtime.
+ */
+interface ProgressEvent<TProgress> {
+    type: 'progress';
+    data: TProgress;
+}
+/**
+ * Complete event - pure domain event without metrics.
+ * Framework automatically wraps with SessionEvent at runtime.
+ */
+interface CompleteEvent<TResult> {
+    type: 'complete';
+    data: TResult;
+    summary: unknown;
+}
+declare const TOOL_CALLING_PROTOCOL = "## CRITICAL INSTRUCTION - READ CAREFULLY\n\nYou have 2 tools available:\n1. reportProgress - [OPTIONAL] Show intermediate work (multiple times)\n2. submitResult - [REQUIRED] Submit your final answer\n\n\u26A0\uFE0F IMPORTANT RULES:\n- You may call reportProgress 0-3 times to show progress\n- You MUST call submitResult exactly once to complete the task\n- After calling reportProgress, you MUST call submitResult in your NEXT response\n- If you call reportProgress more than 3 times without submitResult, the task FAILS\n- The task is NOT complete until submitResult is called\n\nCORRECT SEQUENCE:\n1. [Optional] reportProgress\n2. [Required] submitResult (exactly once)\n\n\u274C WRONG: reportProgress \u2192 reportProgress \u2192 reportProgress \u2192 reportProgress (no submitResult = FAIL)\n\u2705 CORRECT: reportProgress \u2192 submitResult (SUCCESS)";
+/**
+ * Creates a progressive pattern for streaming LLM responses with intermediate progress updates.
+ *
+ * The pattern automatically:
+ * - Injects `reportProgress` and `submitResult` tools
+ * - Stops when `submitResult` is called (via `hasToolCall('submitResult')`)
+ * - Appends protocol instructions to the system prompt
+ *
+ * @example Basic usage
+ * ```typescript
+ * const pattern = defineProgressivePattern({
+ *   progressSchema: z.object({ stage: z.string(), message: z.string() }),
+ *   resultSchema: z.object({ summary: z.string(), score: z.number() }),
+ * });
+ *
+ * for await (const event of pattern.run(provider, {
+ *   system: 'You are an analyzer.',
+ *   prompt: 'Analyze this...',
+ * })) {
+ *   console.log(event.type, event.data);
+ * }
+ * ```
+ *
+ * @example With custom stopWhen (add step limit)
+ * ```typescript
+ * import { stepCountIs } from 'ai';
+ *
+ * for await (const event of pattern.run(provider, {
+ *   prompt: 'Analyze...',
+ *   stopWhen: stepCountIs(10), // Stop at submitResult OR after 10 steps
+ * })) { ... }
+ * ```
+ *
+ * @example With custom protocol
+ * ```typescript
+ * for await (const event of pattern.run(provider, {
+ *   prompt: 'Analyze...',
+ *   protocol: 'Call reportProgress for each step, then submitResult.',
+ * })) { ... }
+ * ```
+ *
+ * @example Composable (within a session)
+ * ```typescript
+ * provider.streamingExecution(async function*(session) {
+ *   yield* pattern.runInSession(session, {
+ *     system: 'You are an analyzer.',
+ *     messages: [...],
+ *   });
+ * });
+ * ```
+ */
+declare function defineProgressivePattern<TProgressSchema extends z.ZodType, TResultSchema extends z.ZodType>(config: {
+    progressSchema: TProgressSchema;
+    resultSchema: TResultSchema;
+}): ProgressivePattern<TProgressSchema, TResultSchema, z.core.output<TProgressSchema>, z.core.output<TResultSchema>, {
+    type: string;
+}>;
+declare class ProgressivePattern<TProgressSchema extends z.ZodType, TResultSchema extends z.ZodType, TProgress = z.infer<TProgressSchema>, TResult = z.infer<TResultSchema>, TEvent extends {
+    type: string;
+} = {
+    type: string;
+}> {
+    readonly progressSchema: TProgressSchema;
+    readonly resultSchema: TResultSchema;
+    constructor(progressSchema: TProgressSchema, resultSchema: TResultSchema);
+    private lastParseError;
+    /**
+     * Runs the pattern within an existing session. Use this for composing
+     * multiple patterns or when you need fine-grained control over the session.
+     *
+     * @param session - The streaming session to run within
+     * @param options - Stream options including:
+     *   - `stopWhen` - Additional stop conditions (combined with default `hasToolCall('submitResult')`)
+     *   - `protocol` - Custom protocol instructions (replaces default `TOOL_CALLING_PROTOCOL`)
+     *   - All other `streamText` options except `tools`, `toolChoice`, `stopWhen`
+     *
+     * @example Basic usage
+     * ```typescript
+     * provider.streamingExecution(async function*(session) {
+     *   yield* pattern.runInSession(session, {
+     *     system: 'You are an analyzer.',
+     *     messages: [{ role: 'user', content: 'Analyze...' }],
+     *   });
+     * });
+     * ```
+     *
+     * @example With custom stopWhen
+     * ```typescript
+     * yield* pattern.runInSession(session, {
+     *   prompt: 'Analyze...',
+     *   stopWhen: stepCountIs(5), // Combined: submitResult OR 5 steps
+     * });
+     * ```
+     */
+    runInSession<TUserTools extends ToolSet = {}>(session: StreamingSession<TEvent>, options: ProgressiveStreamOptions<TUserTools>): AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent>, undefined>;
+    /**
+     * Standalone execution that creates a new session internally.
+     * Use this for simple, single-pattern executions.
+     *
+     * @param provider - The AI provider to use
+     * @param options - Stream options including:
+     *   - `stopWhen` - Additional stop conditions (combined with default `hasToolCall('submitResult')`)
+     *   - `protocol` - Custom protocol instructions (replaces default `TOOL_CALLING_PROTOCOL`)
+     *
+     * @example Basic usage
+     * ```typescript
+     * for await (const event of pattern.run(provider, {
+     *   system: 'You are an analyzer.',
+     *   prompt: 'Analyze this document...',
+     * })) {
+     *   if (event.type === 'progress') {
+     *     console.log('Progress:', event.data);
+     *   } else if (event.type === 'complete') {
+     *     console.log('Result:', event.data);
+     *   }
+     * }
+     * ```
+     *
+     * @example With step limit
+     * ```typescript
+     * import { stepCountIs } from 'ai';
+     *
+     * for await (const event of pattern.run(provider, {
+     *   prompt: 'Analyze...',
+     *   stopWhen: stepCountIs(10),
+     * })) { ... }
+     * ```
+     */
+    run<TUserTools extends ToolSet = {}>(provider: BaseProvider, options: ProgressiveStreamOptions<TUserTools>): AsyncIterable<SessionEvent<TEvent | ErrorEvent>>;
+    private createTools;
+    private parseJsonWrapper;
+    private parseProgressInput;
+    private parseResultInput;
+    private combineStopConditions;
+    private renderSystemPrompt;
+}
+
+/**
+ * Prompt module types for @agtlantis/core.
+ *
+ * Provides structured prompt management with versioning, templating, and repository abstraction.
+ */
+/**
+ * Raw prompt template data as stored in the repository.
+ * This is the serialized form before template compilation.
+ *
+ * @example
+ * ```typescript
+ * const data: PromptTemplateData = {
+ *   id: 'greeting',
+ *   version: '1.0.0',
+ *   system: 'You are a helpful assistant.',
+ *   userTemplate: 'Hello, {{name}}!',
+ * };
+ * ```
+ */
+interface PromptTemplateData {
+    /** Unique identifier for the prompt */
+    id: string;
+    /** Semantic version string (e.g., '1.0.0') */
+    version: string;
+    /** System prompt template (Handlebars syntax) */
+    system: string;
+    /** User prompt template (Handlebars syntax) */
+    userTemplate: string;
+}
+/**
+ * Compiled prompt renderer with template functions.
+ * Created from PromptTemplate.compile() after Handlebars compilation.
+ *
+ * @typeParam TSystemInput - Type of the input object for system prompt rendering
+ * @typeParam TUserInput - Type of the input object for user prompt rendering
+ *
+ * @example
+ * ```typescript
+ * interface SessionContext {
+ *   studentName: string;
+ * }
+ * interface TurnContext {
+ *   previousAnswers: string[];
+ * }
+ *
+ * const renderer: PromptRenderer<SessionContext, TurnContext> = template.compile();
+ *
+ * const systemPrompt = renderer.renderSystemPrompt({ studentName: 'Kim' });
+ * const userPrompt = renderer.renderUserPrompt({ previousAnswers: ['A', 'B'] });
+ * ```
+ */
+interface PromptRenderer<TSystemInput = unknown, TUserInput = unknown> {
+    /** Unique identifier for the prompt */
+    id: string;
+    /** Semantic version string (e.g., '1.0.0') */
+    version: string;
+    /** Compiled template function that renders the system prompt */
+    renderSystemPrompt: (input: TSystemInput) => string;
+    /** Compiled template function that renders the user prompt */
+    renderUserPrompt: (input: TUserInput) => string;
+}
+/**
+ * Repository interface for prompt storage operations.
+ * Implementations can use file system, database, or other storage backends.
+ *
+ * @example
+ * ```typescript
+ * import { createFilePromptRepository, PromptTemplate } from '@agtlantis/core';
+ *
+ * const repo = createFilePromptRepository({ directory: './prompts' });
+ *
+ * // Read latest version
+ * const data = await repo.read('greeting');
+ * const renderer = PromptTemplate.from(data).compile<SessionCtx, TurnCtx>();
+ *
+ * // Read specific version
+ * const v1Data = await repo.read('greeting', '1.0.0');
+ *
+ * // Write new prompt
+ * await repo.write({
+ *   id: 'greeting',
+ *   version: '2.0.0',
+ *   system: 'You are a friendly assistant.',
+ *   userTemplate: 'Hi {{name}}! How are you?',
+ * });
+ * ```
+ */
+interface PromptRepository {
+    /**
+     * Reads raw prompt template data from the repository.
+     *
+     * @param id - Prompt identifier
+     * @param version - Optional specific version. If omitted, returns the latest version.
+     * @returns Raw prompt template data
+     * @throws {PromptNotFoundError} If prompt with given id (and version) doesn't exist
+     * @throws {PromptInvalidFormatError} If prompt file has invalid format
+     */
+    read(id: string, version?: string): Promise<PromptTemplateData>;
+    /**
+     * Writes a prompt to the repository.
+     *
+     * @param content - Raw prompt template data to store
+     * @throws {PromptIOError} If write operation fails
+     */
+    write(content: PromptTemplateData): Promise<void>;
+}
+/**
+ * Minimal file system interface for repository operations.
+ * Abstracts Node.js fs/promises for easier testing and potential browser compatibility.
+ *
+ * @example
+ * ```typescript
+ * // Use default Node.js implementation
+ * const repo = createFilePromptRepository({ directory: './prompts' });
+ *
+ * // Use custom implementation for testing
+ * const mockFs: FileSystem = {
+ *   readFile: async (path) => mockFiles[path],
+ *   writeFile: async (path, content) => { mockFiles[path] = content; },
+ *   readdir: async (path) => Object.keys(mockFiles),
+ * };
+ * const repo = createFilePromptRepository({ directory: './prompts', fs: mockFs });
+ * ```
+ */
+interface FileSystem {
+    /**
+     * Reads file content as UTF-8 string.
+     * @param path - Absolute or relative file path
+     * @returns File content as string
+     * @throws If file doesn't exist or read fails
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Writes content to a file (creates or overwrites).
+     * @param path - Absolute or relative file path
+     * @param content - Content to write
+     * @throws If write operation fails
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Lists files in a directory.
+     * @param path - Directory path
+     * @returns Array of file/directory names (not full paths)
+     * @throws If directory doesn't exist or read fails
+     */
+    readdir(path: string): Promise<string[]>;
+}
+
+/**
+ * Prompt template with compilation capabilities.
+ *
+ * Use `PromptTemplate.from()` to create from raw data, then call `compile()`
+ * to get compiled template functions.
+ *
+ * @example
+ * ```typescript
+ * // From raw data
+ * const template = PromptTemplate.from({
+ *   id: 'greeting',
+ *   version: '1.0.0',
+ *   system: 'You are helping {{studentName}}.',
+ *   userTemplate: 'Previous answers: {{answers}}',
+ * });
+ *
+ * // Compile to renderer
+ * interface SessionCtx { studentName: string }
+ * interface TurnCtx { answers: string[] }
+ *
+ * const renderer = template.compile<SessionCtx, TurnCtx>();
+ * const systemPrompt = renderer.renderSystemPrompt({ studentName: 'Kim' });
+ * const userPrompt = renderer.renderUserPrompt({ answers: ['A', 'B'] });
+ * ```
+ */
+declare class PromptTemplate implements PromptTemplateData {
+    readonly id: string;
+    readonly version: string;
+    readonly system: string;
+    readonly userTemplate: string;
+    private constructor();
+    /**
+     * Creates a PromptTemplate instance from raw data.
+     *
+     * @param data - Raw prompt template data
+     * @returns PromptTemplate instance
+     */
+    static from(data: PromptTemplateData): PromptTemplate;
+    /**
+     * Compiles templates and returns a PromptRenderer.
+     *
+     * @typeParam TSystemInput - Type of input for system prompt template
+     * @typeParam TUserInput - Type of input for user prompt template (defaults to TSystemInput)
+     * @returns Compiled prompt renderer with renderSystemPrompt and renderUserPrompt functions
+     * @throws {PromptTemplateError} If template compilation fails
+     *
+     * @example
+     * ```typescript
+     * // Different input types for system and user prompts
+     * const renderer = template.compile<SessionCtx, TurnCtx>();
+     *
+     * // Same input type for both
+     * const simpleRenderer = template.compile<CommonCtx>();
+     * ```
+     */
+    compile<TSystemInput = unknown, TUserInput = TSystemInput>(): PromptRenderer<TSystemInput, TUserInput>;
+    /**
+     * Returns raw data representation.
+     * Useful for serialization or passing to repository.write().
+     */
+    toData(): PromptTemplateData;
+}
+
+/**
+ * Prompt module error classes for @agtlantis/core.
+ *
+ * Each error type has a specific code and context for precise error handling.
+ */
+
+declare enum PromptErrorCode {
+    /** Generic prompt error */
+    PROMPT_ERROR = "PROMPT_ERROR",
+    /** Prompt not found in repository */
+    NOT_FOUND = "PROMPT_NOT_FOUND",
+    /** Invalid prompt file format (e.g., malformed YAML) */
+    INVALID_FORMAT = "PROMPT_INVALID_FORMAT",
+    /** Template compilation failed */
+    TEMPLATE_ERROR = "PROMPT_TEMPLATE_ERROR",
+    /** File I/O operation failed */
+    IO_ERROR = "PROMPT_IO_ERROR"
+}
+declare module '../errors' {
+    interface AgtlantisErrorCodeMap {
+        prompt: PromptErrorCode;
+    }
+}
+interface PromptErrorOptions {
+    code?: PromptErrorCode;
+    cause?: Error;
+    context?: Record<string, unknown>;
+}
+/**
+ * Base error class for prompt operations.
+ * Use specific error subclasses for more precise error handling.
+ *
+ * @example
+ * ```typescript
+ * throw new PromptError('Something went wrong', {
+ *   code: PromptErrorCode.PROMPT_ERROR,
+ *   context: { promptId: 'greeting' }
+ * });
+ * ```
+ */
+declare class PromptError extends AgtlantisError<PromptErrorCode & AgtlantisErrorCode> {
+    constructor(message: string, options?: PromptErrorOptions);
+    /**
+     * Creates a PromptError from an unknown error.
+     */
+    static from(error: unknown, code?: PromptErrorCode, context?: Record<string, unknown>): PromptError;
+}
+/**
+ * Error thrown when a prompt is not found in the repository.
+ *
+ * @example
+ * ```typescript
+ * throw new PromptNotFoundError('greeting', '1.0.0');
+ * // Error: Prompt 'greeting' version '1.0.0' not found
+ *
+ * throw new PromptNotFoundError('greeting');
+ * // Error: Prompt 'greeting' not found
+ * ```
+ */
+declare class PromptNotFoundError extends PromptError {
+    readonly promptId: string;
+    readonly version?: string;
+    constructor(promptId: string, version?: string, options?: Omit<PromptErrorOptions, 'code'>);
+}
+/**
+ * Error thrown when a prompt file has invalid format.
+ * Examples: malformed YAML, missing required fields, invalid schema.
+ *
+ * @example
+ * ```typescript
+ * throw new PromptInvalidFormatError('greeting', 'Missing required field: system');
+ * // Error: Invalid format for prompt 'greeting': Missing required field: system
+ * ```
+ */
+declare class PromptInvalidFormatError extends PromptError {
+    readonly promptId: string;
+    readonly details: string;
+    constructor(promptId: string, details: string, options?: Omit<PromptErrorOptions, 'code'>);
+}
+/**
+ * Error thrown when template compilation fails.
+ * Examples: invalid Handlebars syntax, missing helper.
+ *
+ * @example
+ * ```typescript
+ * throw new PromptTemplateError('greeting', 'Unexpected token {{/if}}');
+ * // Error: Template compilation failed for prompt 'greeting': Unexpected token {{/if}}
+ * ```
+ */
+declare class PromptTemplateError extends PromptError {
+    readonly promptId: string;
+    readonly details: string;
+    constructor(promptId: string, details: string, options?: Omit<PromptErrorOptions, 'code'>);
+}
+/**
+ * Error thrown when file I/O operations fail.
+ * Examples: read failure, write failure, directory access denied.
+ *
+ * @example
+ * ```typescript
+ * throw new PromptIOError('read', '/path/to/prompt.yaml', {
+ *   cause: originalError
+ * });
+ * // Error: Failed to read prompt file: /path/to/prompt.yaml
+ * ```
+ */
+declare class PromptIOError extends PromptError {
+    readonly operation: 'read' | 'write' | 'list';
+    readonly path: string;
+    constructor(operation: 'read' | 'write' | 'list', path: string, options?: Omit<PromptErrorOptions, 'code'>);
+}
+
+/**
+ * Template engine for prompt compilation.
+ *
+ * Uses Handlebars for template rendering with custom helpers.
+ */
+/**
+ * Compiles a Handlebars template string into a render function.
+ *
+ * @typeParam TInput - Type of the input object for template rendering
+ * @param template - Handlebars template string
+ * @param promptId - Prompt ID for error context
+ * @returns Compiled template function
+ * @throws {PromptTemplateError} If template compilation fails
+ *
+ * @example
+ * ```typescript
+ * const render = compileTemplate<{ name: string }>('Hello, {{name}}!', 'greeting');
+ * const result = render({ name: 'World' });
+ * // => 'Hello, World!'
+ * ```
+ */
+declare function compileTemplate<TInput>(template: string, promptId: string): (input: TInput) => string;
+
+/**
+ * File-based prompt repository implementation.
+ *
+ * Stores prompts as YAML files with naming convention: {id}-{version}.yaml
+ */
+
+interface FilePromptRepositoryOptions {
+    /** Directory path where prompt files are stored */
+    directory: string;
+    /** Optional custom file system implementation (defaults to Node.js fs) */
+    fs?: FileSystem;
+    /** Enable in-memory caching for read operations (defaults to true) */
+    cache?: boolean;
+}
+/**
+ * File-based prompt repository.
+ *
+ * Prompts are stored as YAML files with naming convention: {id}-{version}.yaml
+ *
+ * Can be subclassed to customize parsing/serialization (e.g., JSON instead of YAML).
+ *
+ * @example
+ * ```typescript
+ * const repo = new FilePromptRepository({ directory: './prompts' });
+ *
+ * // Read latest version
+ * const prompt = await repo.read<GreetingInput>('greeting');
+ *
+ * // Subclass to use JSON format
+ * class JsonPromptRepository extends FilePromptRepository {
+ *   protected parseContent(content: string, promptId: string): PromptTemplateData {
+ *     return JSON.parse(content);
+ *   }
+ *   protected serializeContent(content: PromptTemplateData): string {
+ *     return JSON.stringify(content, null, 2);
+ *   }
+ * }
+ * ```
+ */
+declare class FilePromptRepository implements PromptRepository {
+    protected readonly directory: string;
+    protected readonly fileSystem: FileSystem;
+    protected readonly cacheEnabled: boolean;
+    private readonly contentCache;
+    constructor(options: FilePromptRepositoryOptions);
+    /**
+     * Generates file name from prompt id and version.
+     * Override this along with `parseFileName` to change file naming convention.
+     */
+    protected getFileName(id: string, version: string): string;
+    /**
+     * Parses file name into id and version.
+     * Override this along with `getFileName` to change file naming convention.
+     */
+    protected parseFileName(fileName: string): {
+        id: string;
+        version: string;
+    } | null;
+    /**
+     * Parses raw file content into PromptTemplateData.
+     * Override this to support different file formats (e.g., JSON, TOML).
+     */
+    protected parseContent(content: string, promptId: string): PromptTemplateData;
+    /**
+     * Serializes PromptTemplateData to file content string.
+     * Override this to support different file formats (e.g., JSON, TOML).
+     */
+    protected serializeContent(content: PromptTemplateData): string;
+    private getCacheKey;
+    read(id: string, version?: string): Promise<PromptTemplateData>;
+    write(content: PromptTemplateData): Promise<void>;
+}
+/**
+ * Creates a file-based prompt repository.
+ *
+ * This is a convenience factory function. For subclassing, use `FilePromptRepository` class directly.
+ *
+ * @example
+ * ```typescript
+ * const repo = createFilePromptRepository({ directory: './prompts' });
+ * const prompt = await repo.read<GreetingInput>('greeting');
+ * ```
+ */
+declare function createFilePromptRepository(options: FilePromptRepositoryOptions): PromptRepository;
+
+declare function computeFileSourceHash(source: FileSource): Promise<string>;
+
+interface InMemoryFileCacheOptions {
+    defaultTTL?: number;
+}
+declare class InMemoryFileCache implements FileCache {
+    private readonly cache;
+    private readonly defaultTTL;
+    constructor(options?: InMemoryFileCacheOptions);
+    get(hash: string): UploadedFile | null;
+    set(hash: string, file: UploadedFile, ttl?: number): void;
+    delete(hash: string): void;
+    clear(): void;
+}
+
+/** FileManager for providers without file upload support (throws on upload/delete) */
+declare class NoOpFileManager implements FileManager {
+    upload(_files: FileSource[]): Promise<UploadedFile[]>;
+    delete(_fileId: string): Promise<void>;
+    clear(): Promise<void>;
+    getUploadedFiles(): UploadedFile[];
+}
+
+declare const EXTENSION_TO_MIME: Record<string, string>;
+/** Infers MIME type from file extension (case-insensitive) */
+declare function inferMediaType(filePath: string): string | undefined;
+interface FoundFileSource {
+    part: FileSource;
+    path: (string | number)[];
+}
+/** Recursively scans an input for FileSources and returns them with their JSON paths */
+declare function scanForFileSources(input: unknown, currentPath?: (string | number)[]): FoundFileSource[];
+interface ResolveOptions {
+    basePath?: string;
+    maxSize?: number;
+}
+declare const DEFAULT_MAX_SIZE: number;
+/**
+ * Resolves a FileSource to AI SDK compatible format.
+ * Path-based parts are read into Buffer; others returned unchanged.
+ */
+declare function resolveFileSource(part: FileSource, options?: ResolveOptions): Promise<FileSource>;
+/** Resolves all FileSources in an input (returns new object, original unchanged) */
+declare function resolveFileSourcesInInput<T>(input: T, options?: ResolveOptions): Promise<T>;
+interface FileSourceDisplayInfo {
+    source: FileSource['source'];
+    description: string;
+    mediaType: string;
+    filename?: string;
+}
+/** Extracts display info from a FileSource for reporting (excludes raw data) */
+declare function getFileSourceDisplayInfo(part: FileSource): FileSourceDisplayInfo;
+declare function getFileSourcesDisplayInfo(input: unknown): FileSourceDisplayInfo[];
+
+type HarmCategory = 'HARM_CATEGORY_HATE_SPEECH' | 'HARM_CATEGORY_SEXUALLY_EXPLICIT' | 'HARM_CATEGORY_DANGEROUS_CONTENT' | 'HARM_CATEGORY_HARASSMENT' | 'HARM_CATEGORY_CIVIC_INTEGRITY';
+type HarmBlockThreshold = 'BLOCK_NONE' | 'BLOCK_ONLY_HIGH' | 'BLOCK_MEDIUM_AND_ABOVE' | 'BLOCK_LOW_AND_ABOVE' | 'OFF';
+interface SafetySetting {
+    category: HarmCategory;
+    threshold: HarmBlockThreshold;
+}
+interface GoogleProviderConfig {
+    apiKey: string;
+    safetySettings?: SafetySetting[];
+}
+declare class GoogleProvider extends BaseProvider {
+    private readonly apiKey;
+    private readonly defaultModelId;
+    private readonly logger;
+    private readonly safetySettings?;
+    private readonly pricingConfig?;
+    private readonly defaultOptions?;
+    private readonly searchEnabled;
+    private readonly urlContextEnabled;
+    private readonly fileCache?;
+    private readonly google;
+    constructor(apiKey: string, defaultModelId: string | null, logger: Logger, safetySettings?: SafetySetting[] | undefined, pricingConfig?: ProviderPricing | undefined, defaultOptions?: GoogleGenerativeAIProviderOptions | undefined, searchEnabled?: boolean, urlContextEnabled?: boolean, fileCache?: FileCache | undefined);
+    withDefaultModel(modelId: string): GoogleProvider;
+    withLogger(newLogger: Logger): GoogleProvider;
+    withPricing(pricing: ProviderPricing): GoogleProvider;
+    /**
+     * Set default provider-specific options for all LLM calls.
+     * These options will be deep-merged with per-call providerOptions.
+     *
+     * @example
+     * ```typescript
+     * createGoogleProvider({ apiKey: 'xxx' })
+     *   .withDefaultModel('gemini-2.0-flash-thinking-exp')
+     *   .withDefaultOptions({
+     *     thinkingConfig: { includeThoughts: true, thinkingLevel: 'low' }
+     *   })
+     * ```
+     */
+    withDefaultOptions(options: GoogleGenerativeAIProviderOptions): GoogleProvider;
+    /**
+     * Enable Google Search grounding for all LLM calls.
+     * Allows the model to access real-time web information.
+     *
+     * @example
+     * ```typescript
+     * createGoogleProvider({ apiKey: 'xxx' })
+     *   .withDefaultModel('gemini-2.5-flash')
+     *   .withSearchEnabled()
+     * ```
+     */
+    withSearchEnabled(): GoogleProvider;
+    /**
+     * Enable URL Context grounding for all LLM calls.
+     * Allows the model to retrieve and use content from URLs in the prompt.
+     *
+     * @example
+     * ```typescript
+     * createGoogleProvider({ apiKey: 'xxx' })
+     *   .withDefaultModel('gemini-2.5-flash')
+     *   .withUrlContextEnabled()
+     * ```
+     */
+    withUrlContextEnabled(): GoogleProvider;
+    /**
+     * Set a file cache for reusing uploaded files across sessions.
+     * If no cache is provided, creates a new InMemoryFileCache.
+     *
+     * @example
+     * ```typescript
+     * // Use default InMemoryFileCache
+     * createGoogleProvider({ apiKey: 'xxx' })
+     *   .withFileCache()
+     *
+     * // Use custom cache with TTL
+     * const cache = new InMemoryFileCache({ defaultTTL: 3600000 });
+     * createGoogleProvider({ apiKey: 'xxx' })
+     *   .withFileCache(cache)
+     * ```
+     */
+    withFileCache(cache?: FileCache): GoogleProvider;
+    private getSessionConfig;
+    protected createStreamingSession<TEvent extends {
+        type: string;
+    }>(signal?: AbortSignal): StreamingSession<TEvent>;
+    protected createSimpleSession(signal?: AbortSignal): SimpleSession;
+    /**
+     * Type assertion needed because @ai-sdk/google's type signature doesn't
+     * include the second parameter, but it's supported at runtime.
+     */
+    private createModel;
+}
+declare function createGoogleProvider(config: GoogleProviderConfig): GoogleProvider;
+
+/** Google GenAI File API implementation with automatic session cleanup */
+declare class GoogleFileManager implements FileManager {
+    private uploadedFiles;
+    private client;
+    private cache;
+    constructor(apiKey: string, options?: FileManagerOptions);
+    private uploadOne;
+    upload(files: FileSource[]): Promise<UploadedFile[]>;
+    delete(fileId: string): Promise<void>;
+    clear(): Promise<void>;
+    getUploadedFiles(): UploadedFile[];
+}
+
+interface OpenAIProviderConfig {
+    apiKey: string;
+    baseURL?: string;
+    organization?: string;
+}
+declare class OpenAIProvider extends BaseProvider {
+    private readonly apiKey;
+    private readonly defaultModelId;
+    private readonly logger;
+    private readonly baseURL?;
+    private readonly organization?;
+    private readonly pricingConfig?;
+    private readonly defaultOptions?;
+    private readonly fileCache?;
+    private readonly openai;
+    constructor(apiKey: string, defaultModelId: string | null, logger: Logger, baseURL?: string | undefined, organization?: string | undefined, pricingConfig?: ProviderPricing | undefined, defaultOptions?: OpenAIChatLanguageModelOptions | undefined, fileCache?: FileCache | undefined);
+    withDefaultModel(modelId: string): OpenAIProvider;
+    withLogger(newLogger: Logger): OpenAIProvider;
+    withPricing(pricing: ProviderPricing): OpenAIProvider;
+    /**
+     * Set default provider-specific options for all LLM calls.
+     * These options will be deep-merged with per-call providerOptions.
+     *
+     * @example
+     * ```typescript
+     * createOpenAIProvider({ apiKey: 'xxx' })
+     *   .withDefaultModel('gpt-4o')
+     *   .withDefaultOptions({
+     *     reasoningEffort: 'high',
+     *     parallelToolCalls: true,
+     *   })
+     * ```
+     */
+    withDefaultOptions(options: OpenAIChatLanguageModelOptions): OpenAIProvider;
+    /**
+     * Set a file cache for API consistency with GoogleProvider.
+     * Note: OpenAI does not support file caching, so this is a no-op.
+     *
+     * @example
+     * ```typescript
+     * createOpenAIProvider({ apiKey: 'xxx' })
+     *   .withFileCache()
+     * ```
+     */
+    withFileCache(cache?: FileCache): OpenAIProvider;
+    private getSessionConfig;
+    protected createStreamingSession<TEvent extends {
+        type: string;
+    }>(signal?: AbortSignal): StreamingSession<TEvent>;
+    protected createSimpleSession(signal?: AbortSignal): SimpleSession;
+}
+declare function createOpenAIProvider(config: OpenAIProviderConfig): OpenAIProvider;
+
+interface ValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+interface ValidationAttempt<TResult> extends ValidationResult {
+    result: TResult;
+    attempt: number;
+}
+interface ReadonlyValidationHistory<TResult> {
+    /** 1-based attempt number for the next attempt. */
+    readonly nextAttempt: number;
+    /** Last validation attempt, or undefined if no attempts yet. */
+    readonly last: ValidationAttempt<TResult> | undefined;
+    /** All validation attempts as a readonly array. */
+    readonly all: readonly ValidationAttempt<TResult>[];
+    /** Reasons from all failed attempts. */
+    readonly failureReasons: string[];
+    /** True if at least one previous attempt exists. */
+    readonly isRetry: boolean;
+}
+interface ValidationOptions<TResult> {
+    /**
+     * Validation function that checks the result.
+     * Can access history to compare with previous attempts.
+     */
+    validate: (result: TResult, history: ReadonlyValidationHistory<TResult>) => ValidationResult | Promise<ValidationResult>;
+    /**
+     * Maximum number of attempts before throwing ValidationExhaustedError.
+     * @default 3
+     * @minimum 1
+     */
+    maxAttempts?: number;
+    /**
+     * AbortSignal for cancellation support.
+     * When aborted, throws the abort reason before the next attempt.
+     */
+    signal?: AbortSignal;
+    /**
+     * Delay between retry attempts in milliseconds.
+     * Only applied when there will be another attempt after a failure.
+     */
+    retryDelay?: number;
+    /**
+     * Callback invoked after each attempt (success or failure).
+     * Useful for logging or progress tracking.
+     */
+    onAttempt?: (attempt: ValidationAttempt<TResult>) => void;
+}
+
+declare class ValidationHistory<TResult> implements ReadonlyValidationHistory<TResult> {
+    private attempts;
+    get nextAttempt(): number;
+    get last(): ValidationAttempt<TResult> | undefined;
+    get all(): readonly ValidationAttempt<TResult>[];
+    get failureReasons(): string[];
+    get isRetry(): boolean;
+    /** Internal use only - not exposed via ReadonlyValidationHistory. */
+    add(result: TResult, validation: ValidationResult): void;
+}
+
+declare enum ValidationErrorCode {
+    VALIDATION_EXHAUSTED = "VALIDATION_EXHAUSTED"
+}
+/**
+ * Error thrown when validation fails after all attempts are exhausted.
+ * Contains the full validation history for debugging and partial result recovery.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await withValidation(execute, options);
+ * } catch (e) {
+ *   if (e instanceof ValidationExhaustedError) {
+ *     console.log(`Failed after ${e.history.all.length} attempts`);
+ *     console.log('Last result:', e.history.last?.result);
+ *     console.log('All failures:', e.history.failureReasons);
+ *     console.log('Error code:', e.code); // 'VALIDATION_EXHAUSTED'
+ *   }
+ * }
+ * ```
+ */
+declare class ValidationExhaustedError<TResult> extends AgtlantisError<ValidationErrorCode & AgtlantisErrorCode> {
+    readonly history: ReadonlyValidationHistory<TResult>;
+    constructor(message: string, history: ReadonlyValidationHistory<TResult>);
+}
+
+/**
+ * Wraps an async operation with validation and retry logic.
+ *
+ * Executes the function and validates the result. If validation fails,
+ * retries up to maxAttempts times, passing the history to the execute
+ * function so it can adjust its approach based on previous failures.
+ *
+ * @param execute - Function to execute. Receives history for retry context.
+ * @param options - Validation options including the validate function.
+ * @returns The first result that passes validation.
+ * @throws {ValidationExhaustedError} If all attempts fail validation.
+ *
+ * @example
+ * ```typescript
+ * const result = await withValidation(
+ *   (history) => session.generateText({
+ *     messages: [
+ *       { role: 'user', content: prompt },
+ *       ...(history.isRetry ? [{
+ *         role: 'user' as const,
+ *         content: `Fix: ${history.last!.reason}`,
+ *       }] : []),
+ *     ],
+ *     schema,
+ *   }),
+ *   {
+ *     validate: (result) => ({
+ *       valid: result.confidence > 0.8,
+ *       reason: `Confidence ${result.confidence} below 0.8`,
+ *     }),
+ *     maxAttempts: 3,
+ *   }
+ * );
+ * ```
+ */
+declare function withValidation<TResult>(execute: (history: ReadonlyValidationHistory<NoInfer<TResult>>) => Promise<TResult>, options: ValidationOptions<NoInfer<TResult>>): Promise<TResult>;
+
+export { ANTHROPIC_PRICING, AgtlantisError, type AgtlantisErrorCode, type AgtlantisErrorOptions, BaseProvider, CalculateCostParams, type CompleteEvent, CompletionEvent, ConfigurationError, ConfigurationErrorCode, type ConfigurationErrorOptions, CostResult, DEFAULT_FALLBACK_PRICING, DEFAULT_MAX_SIZE, DEFAULT_PRICING_CONFIG, ERRORS, EXTENSION_TO_MIME, type EffectivePricingResult, ErrorEvent, ExecutionError, ExecutionErrorCode, type ExecutionErrorOptions, ExecutionStatus, ExtractResult, FileCache, FileError, FileErrorCode, type FileErrorOptions, FileManager, FileManagerOptions, FilePromptRepository, type FilePromptRepositoryOptions, FileSource, type FileSourceDisplayInfo, type FileSystem, type FoundFileSource, GOOGLE_PRICING, GoogleFileManager, GoogleProvider, type GoogleProviderConfig, type HarmBlockThreshold, type HarmCategory, type HookRunner, InMemoryFileCache, type InMemoryFileCacheOptions, Logger, ModelPricing, NoOpFileManager, OPENAI_PRICING, type OpenAIProviderConfig, PricingConfig, type PricingSource, type ProgressEvent, ProgressivePattern, type ProgressiveStreamOptions, PromptError, PromptErrorCode, type PromptErrorOptions, PromptIOError, PromptInvalidFormatError, PromptNotFoundError, type PromptRenderer, type PromptRepository, PromptTemplate, type PromptTemplateData, PromptTemplateError, ProviderPricing, ProviderType, type ReadonlyValidationHistory, type ReplaceResult, type ResolveOptions, type SafetySetting, SessionEvent, SessionStreamGeneratorFn, SimpleExecution, SimpleExecutionHost, SimpleResult, SimpleSession, StreamTextParams, StreamingExecution, StreamingExecutionHost, StreamingResult, StreamingSession, TOOL_CALLING_PROTOCOL, UploadedFile, type ValidationAttempt, ValidationErrorCode, ValidationExhaustedError, ValidationHistory, type ValidationOptions, type ValidationResult, calculateCost, calculateCostFromUsage, calculateTotalCost, combineSignals, compileTemplate, computeFileSourceHash, configurePricing, createFilePromptRepository, createGoogleProvider, createHookRunner, createOpenAIProvider, createZeroUsage, defineProgressivePattern, detectProviderType, determineResultStatus, getDuration, getEffectivePricing, getFileSourceDisplayInfo, getFileSourcesDisplayInfo, getModelPricing, getPricingConfig, inferMediaType, isAbortError, mapExecution, mapExecutionResult, mergeUsages, normalizeError, resetPricingConfig, resolveFileSource, resolveFileSourcesInInput, scanForFileSources, validateModelPricing, validatePricingConfig, validateProviderPricing, withValidation };