@superblocksteam/vite-plugin-file-sync 2.0.59-next.2 → 2.0.59-next.3

package/dist/ai-service/llm/interaction/middlewares/stream-retry.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Retry middleware for StreamText operations.
+ *
+ * This middleware wraps entire streamText() calls to handle failures during
+ * stream consumption. When a stream fails mid-consumption (e.g., network timeout),
+ * this middleware retries the entire streamText call with accumulated messages
+ * from successful steps preserved via Context.
+ *
+ * **Two-phase retry architecture:**
+ * 1. **Initial call retry**: Retries errors when calling streamText() to get metadata
+ * 2. **Stream consumption retry**: Retries mid-stream errors during stream consumption
+ *
+ * **Separate retry budgets:**
+ * Each phase has its own independent retry budget. For example, with maxRetries: 3:
+ * - Phase 1 can retry up to 3 times (4 total attempts to get initial metadata)
+ * - Phase 2 can retry up to 3 times (4 total attempts to consume stream)
+ * - Maximum total attempts: 4 (phase 1) + 4 (phase 2) = 8
+ *
+ * This design ensures that failures in one phase don't prevent retries in the other phase.
+ *
+ * ## Why at StreamText Level?
+ *
+ * Retrying at the streamText level (vs model.doStream level) ensures:
+ * 1. **Fresh Vercel SDK state**: Each retry gets a new eventProcessor with no
+ *    partial chunk pollution from failed attempts
+ * 2. **Correct message sequences**: No orphaned content IDs or invalid message structures
+ * 3. **Natural continuation**: Vercel SDK's built-in logic handles multi-step resumption
+ *
+ * ## How It Works with Context
+ *
+ * The Context system provides the accumulated messages for retry:
+ * - Step 1 succeeds → Context.endStep() records messages
+ * - Step 2 fails → No endStep() call, empty step array remains
+ * - Retry → Context.getMessages() provides Step 1's messages
+ * - Fresh streamText() call receives those messages and continues from Step 2 Context.startStep() is idempotent → reuses empty step array
+ *
+ * ## Multi-Step Scenarios
+ *
+ * For multi-step flows (e.g., tool calling):
+ * - Step 1 (tool call) succeeds
+ * - Step 2 (continuation) fails
+ * - Retry receives Step 1's messages (including tool-results)
+ * - Vercel SDK sees tool-results and continues to Step 2
+ * - Does NOT re-execute Step 1's tools (already have results)
+ *
+ * @example
+ * ```typescript
+ * const middleware = createStreamRetryMiddleware({
+ *   maxRetries: 3,
+ *   maxTotalRetryTimeMs: 120000,
+ *   isRetryable: (error) => isNetworkError(error)
+ * });
+ *
+ * const provider = applyMiddleware(baseProvider, middleware);
+ * const result = await provider.streamText({ model, messages, tools });
+ * // Automatically retries on stream consumption failures
+ * ```
+ */
+import { type Logger } from "../../../../util/logger.js";
+import { type BackoffStrategy } from "../../../util/backoff-strategy.js";
+import type { StreamTextMiddleware } from "../middleware.js";
+export interface StreamRetryOptions {
+    /**
+     * Maximum number of retry attempts per phase (not including the initial attempt).
+     * Each phase (initial call, stream consumption) gets its own retry budget.
+     * Default: Infinity (unlimited)
+     */
+    maxRetries?: number;
+    /**
+     * Custom backoff strategy for calculating retry delays.
+     * If not provided, uses ExponentialBackoff.
+     */
+    backoffStrategy?: BackoffStrategy;
+    /**
+     * Initial delay in milliseconds before the first retry.
+     * Default: 500 (0.5 seconds)
+     */
+    initialDelayMs?: number;
+    /**
+     * Maximum delay in milliseconds for exponential backoff.
+     * Default: 5000 (5 seconds)
+     */
+    maxDelayMs?: number;
+    /**
+     * Backoff multiplier for exponential backoff.
+     * Default: 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Maximum total time in milliseconds for all retry attempts.
+     * Default: undefined (no time limit)
+     */
+    maxTotalRetryTimeMs?: number;
+    /**
+     * Function to determine if an error is retryable.
+     * Default: checks for timeout and connection errors
+     */
+    isRetryable?: (error: unknown) => boolean;
+    /**
+     * Callback invoked before each retry attempt.
+     */
+    onRetry?: (error: unknown, attempt: number, delayMs: number, totalRetryTimeMs: number) => void | Promise<void>;
+    /**
+     * Optional abort signal to cancel retry attempts.
+     * When the signal is aborted, no further retries will be attempted.
+     */
+    abortSignal?: AbortSignal;
+    /** Logger instance for retry operations */
+    logger?: Logger;
+}
+/**
+ * Creates a middleware that retries streamText calls on failure.
+ *
+ * This middleware wraps the entire streamText operation, catching errors during
+ * both the initial call and stream consumption. Retries with accumulated messages from Context.
+ *
+ * @param options - Configuration for retry behavior
+ * @returns A StreamTextMiddleware
+ */
+export declare function createStreamRetryMiddleware(options?: StreamRetryOptions): StreamTextMiddleware;
+//# sourceMappingURL=stream-retry.d.ts.map

package/dist/ai-service/llm/interaction/middlewares/stream-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-retry.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/llm/interaction/middlewares/stream-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EACL,KAAK,MAAM,EAGZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,mCAAmC,CAAC;AAI3C,OAAO,KAAK,EACV,oBAAoB,EAIrB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;OAEG;IACH,OAAO,CAAC,EAAE,CACR,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,kBAAuB,GAC/B,oBAAoB,CAgHtB"}

package/dist/ai-service/llm/interaction/middlewares/stream-retry.js

@@ -0,0 +1,291 @@
+/**
+ * Retry middleware for StreamText operations.
+ *
+ * This middleware wraps entire streamText() calls to handle failures during
+ * stream consumption. When a stream fails mid-consumption (e.g., network timeout),
+ * this middleware retries the entire streamText call with accumulated messages
+ * from successful steps preserved via Context.
+ *
+ * **Two-phase retry architecture:**
+ * 1. **Initial call retry**: Retries errors when calling streamText() to get metadata
+ * 2. **Stream consumption retry**: Retries mid-stream errors during stream consumption
+ *
+ * **Separate retry budgets:**
+ * Each phase has its own independent retry budget. For example, with maxRetries: 3:
+ * - Phase 1 can retry up to 3 times (4 total attempts to get initial metadata)
+ * - Phase 2 can retry up to 3 times (4 total attempts to consume stream)
+ * - Maximum total attempts: 4 (phase 1) + 4 (phase 2) = 8
+ *
+ * This design ensures that failures in one phase don't prevent retries in the other phase.
+ *
+ * ## Why at StreamText Level?
+ *
+ * Retrying at the streamText level (vs model.doStream level) ensures:
+ * 1. **Fresh Vercel SDK state**: Each retry gets a new eventProcessor with no
+ *    partial chunk pollution from failed attempts
+ * 2. **Correct message sequences**: No orphaned content IDs or invalid message structures
+ * 3. **Natural continuation**: Vercel SDK's built-in logic handles multi-step resumption
+ *
+ * ## How It Works with Context
+ *
+ * The Context system provides the accumulated messages for retry:
+ * - Step 1 succeeds → Context.endStep() records messages
+ * - Step 2 fails → No endStep() call, empty step array remains
+ * - Retry → Context.getMessages() provides Step 1's messages
+ * - Fresh streamText() call receives those messages and continues from Step 2 Context.startStep() is idempotent → reuses empty step array
+ *
+ * ## Multi-Step Scenarios
+ *
+ * For multi-step flows (e.g., tool calling):
+ * - Step 1 (tool call) succeeds
+ * - Step 2 (continuation) fails
+ * - Retry receives Step 1's messages (including tool-results)
+ * - Vercel SDK sees tool-results and continues to Step 2
+ * - Does NOT re-execute Step 1's tools (already have results)
+ *
+ * @example
+ * ```typescript
+ * const middleware = createStreamRetryMiddleware({
+ *   maxRetries: 3,
+ *   maxTotalRetryTimeMs: 120000,
+ *   isRetryable: (error) => isNetworkError(error)
+ * });
+ *
+ * const provider = applyMiddleware(baseProvider, middleware);
+ * const result = await provider.streamText({ model, messages, tools });
+ * // Automatically retries on stream consumption failures
+ * ```
+ */
+import { getErrorMeta, getPrefixedLogger, } from "../../../../util/logger.js";
+import { ExponentialBackoff, } from "../../../util/backoff-strategy.js";
+import { LLMProviderError } from "../../error.js";
+import { isProviderErrorRetryable } from "../../util/provider-errors.js";
+/**
+ * Creates a middleware that retries streamText calls on failure.
+ *
+ * This middleware wraps the entire streamText operation, catching errors during
+ * both the initial call and stream consumption. Retries with accumulated messages from Context.
+ *
+ * @param options - Configuration for retry behavior
+ * @returns A StreamTextMiddleware
+ */
+export function createStreamRetryMiddleware(options = {}) {
+    const { maxRetries = Infinity, initialDelayMs = 500, maxDelayMs = 5000, backoffMultiplier = 2, maxTotalRetryTimeMs, isRetryable = isProviderErrorRetryable, onRetry, abortSignal, logger = getPrefixedLogger("[StreamRetry]"), } = options;
+    const backoffStrategy = options.backoffStrategy ??
+        new ExponentialBackoff({
+            initialDelayMs,
+            maxDelayMs,
+            backoffMultiplier,
+        });
+    const maxRetriesDisplay = maxRetries === Infinity ? "unlimited" : String(maxRetries);
+    return {
+        wrap(provider) {
+            return {
+                async streamText(streamOptions) {
+                    // Phase 1: Retry initial streamText call
+                    let httpAttempt = 0;
+                    let totalRetryTime = 0;
+                    const overallStartTime = Date.now();
+                    let initialResult;
+                    while (true) {
+                        try {
+                            initialResult = await provider.streamText(streamOptions);
+                            break; // Success!
+                        }
+                        catch (err) {
+                            httpAttempt++;
+                            const error = wrapError(err);
+                            const delay = await handleRetryAttempt(error, httpAttempt, totalRetryTime, {
+                                maxRetries,
+                                maxRetriesDisplay,
+                                maxTotalRetryTimeMs,
+                                overallStartTime,
+                                backoffStrategy,
+                                isRetryable,
+                                onRetry,
+                                abortSignal,
+                                logger,
+                                errorContext: "HTTP error",
+                            });
+                            totalRetryTime += delay;
+                        }
+                    }
+                    // Phase 2: Wrap streams to handle consumption errors
+                    const retryingFullStream = createRetryingAsyncIterable(provider, streamOptions, () => initialResult.fullStream, {
+                        maxRetries,
+                        maxRetriesDisplay,
+                        maxTotalRetryTimeMs,
+                        overallStartTime,
+                        backoffStrategy,
+                        isRetryable,
+                        onRetry,
+                        abortSignal,
+                        logger,
+                    });
+                    const retryingTextStream = createRetryingAsyncIterable(provider, streamOptions, () => initialResult.textStream, {
+                        maxRetries,
+                        maxRetriesDisplay,
+                        maxTotalRetryTimeMs,
+                        overallStartTime,
+                        backoffStrategy,
+                        isRetryable,
+                        onRetry,
+                        abortSignal,
+                        logger,
+                    });
+                    // Return result with retrying streams
+                    return {
+                        ...initialResult,
+                        fullStream: retryingFullStream,
+                        textStream: retryingTextStream,
+                    };
+                },
+            };
+        },
+    };
+}
+/**
+ * Creates an AsyncIterableStream that retries on consumption errors.
+ */
+function createRetryingAsyncIterable(provider, streamOptions, getInitialStream, config) {
+    // Create an AsyncIterable that implements the retry logic
+    const retryingIterable = {
+        async *[Symbol.asyncIterator]() {
+            let consumptionAttempt = 0;
+            let isFirstAttempt = true;
+            while (true) {
+                try {
+                    // Get stream for current attempt
+                    const iterator = isFirstAttempt
+                        ? getInitialStream()[Symbol.asyncIterator]()
+                        : await (async () => {
+                            const streamResult = await provider.streamText(streamOptions);
+                            // Use fullStream for retries (contains all chunk types)
+                            return streamResult.fullStream[Symbol.asyncIterator]();
+                        })();
+                    isFirstAttempt = false;
+                    // Iterate through chunks
+                    while (true) {
+                        const { value: chunk, done } = await iterator.next();
+                        if (done) {
+                            return; // Success!
+                        }
+                        // Check for error chunks
+                        if (typeof chunk === "object" &&
+                            chunk !== null &&
+                            "type" in chunk &&
+                            chunk.type === "error") {
+                            throw wrapError(chunk.error);
+                        }
+                        // Normal chunk - yield it
+                        yield chunk;
+                        // Reset consumption attempt on successful chunk
+                        consumptionAttempt = 0;
+                    }
+                }
+                catch (err) {
+                    const error = wrapError(err);
+                    // Handle error - check if we should retry
+                    consumptionAttempt++;
+                    const totalElapsed = Date.now() - config.overallStartTime;
+                    try {
+                        await handleRetryAttempt(error, consumptionAttempt, totalElapsed, {
+                            ...config,
+                            errorContext: "Stream error",
+                        });
+                        // Loop continues - will try again with fresh stream
+                    }
+                    catch (finalError) {
+                        // Exhausted or non-retryable - yield error and exit
+                        yield {
+                            type: "error",
+                            error: finalError,
+                        };
+                        return;
+                    }
+                }
+            }
+        },
+    };
+    // Convert AsyncIterable to ReadableStream
+    const readableStream = new ReadableStream({
+        async start(controller) {
+            try {
+                for await (const chunk of retryingIterable) {
+                    controller.enqueue(chunk);
+                }
+                controller.close();
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+    });
+    // Return as AsyncIterableStream (ReadableStream with async iteration support)
+    return readableStream;
+}
+/**
+ * Wraps an error in LLMProviderError if it isn't already.
+ */
+function wrapError(err, provider) {
+    if (err instanceof LLMProviderError) {
+        return err;
+    }
+    // Provider is optional here since we may not know it at this level
+    return new LLMProviderError({
+        provider: provider,
+        cause: err,
+    });
+}
+/**
+ * Checks if retry is allowed and executes retry logic.
+ * Returns the delay in milliseconds if a retry should be attempted.
+ * Throws if no retry is possible.
+ */
+async function handleRetryAttempt(error, attempt, totalRetryTime, config) {
+    // Check abort signal
+    if (config.abortSignal?.aborted) {
+        const abortError = new LLMProviderError({
+            provider: error.provider,
+            message: "Request aborted",
+            type: "aborted",
+            isRetryable: false,
+        });
+        config.logger.info("Request aborted, stopping retry attempts");
+        throw abortError;
+    }
+    // Check retry conditions
+    const withinMaxRetries = attempt <= config.maxRetries;
+    const withinTimeLimit = !config.maxTotalRetryTimeMs ||
+        Date.now() - config.overallStartTime < config.maxTotalRetryTimeMs;
+    const errorIsRetryable = config.isRetryable(error);
+    const canRetry = errorIsRetryable && withinMaxRetries && withinTimeLimit;
+    if (!canRetry) {
+        if (errorIsRetryable) {
+            const reason = !withinMaxRetries
+                ? `after ${config.maxRetriesDisplay} retries`
+                : `total retry time exceeded ${config.maxTotalRetryTimeMs}ms`;
+            config.logger.error(`Exceeded retry limits: ${reason}`, getErrorMeta(error.cause));
+            throw new LLMProviderError({
+                provider: error.provider,
+                message: `${config.errorContext} ${reason}`,
+                type: "retries_exhausted",
+                isRetryable: false,
+                cause: error,
+            });
+        }
+        config.logger.error("Non-retryable error encountered", getErrorMeta(error.cause));
+        throw error;
+    }
+    // Calculate backoff delay
+    const delay = config.backoffStrategy.getNextDelay(attempt);
+    config.logger.warn(`${config.errorContext} (type: ${error.type}). Attempt ${attempt}/${config.maxRetriesDisplay}. Retrying in ${delay}ms...`);
+    // Call onRetry callback
+    if (config.onRetry) {
+        await config.onRetry(error, attempt, delay, totalRetryTime);
+    }
+    // Wait before retry
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    return delay;
+}
+//# sourceMappingURL=stream-retry.js.map

package/dist/ai-service/llm/interaction/middlewares/stream-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-retry.js","sourceRoot":"","sources":["../../../../../src/ai-service/llm/interaction/middlewares/stream-retry.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/llm/interaction/provider.d.ts

@@ -0,0 +1,158 @@
+/**
+ * High-level provider interface for LLM streaming interactions.
+ *
+ * This interface defines a complete, SDK-agnostic contract for multi-step
+ * LLM streaming, including all lifecycle hooks. Concrete implementations
+ * (adapters) bridge this interface to specific SDKs (Vercel AI, Anthropic, etc.).
+ *
+ * Key features:
+ * - Complete lifecycle: prepareStep → onChunk → onStepFinish → onFinish → onFinally
+ * - onFinally: Guaranteed to run after stream consumption (our addition!)
+ * - SDK-agnostic: Could be implemented with any LLM SDK
+ * - Testable: Easy to mock for testing
+ */
+import type { Tool } from "../../agent/tools2/types.js";
+import type { StopCondition } from "../../util/stop-condition.js";
+import type { ProviderOptions } from "@ai-sdk/provider-utils";
+import type { LanguageModel, TextStreamPart, LanguageModelUsage, ModelMessage, UserModelMessage } from "ai";
+/**
+ * Provider interface for LLM streaming interactions.
+ *
+ * Implementations of this interface wrap specific SDKs and provide
+ * a consistent, high-level API with complete lifecycle management.
+ */
+export interface StreamTextProvider {
+    /**
+     * Streams text from an LLM with multi-step tool calling support.
+     *
+     * @param options - Configuration and lifecycle hooks
+     * @returns Promise resolving to stream result with text/full streams
+     */
+    streamText<TOOLS extends Record<string, Tool> = Record<string, Tool>>(options: StreamTextOptions<TOOLS>): Promise<StreamTextResult<TOOLS>>;
+}
+/**
+ * Options for a streamText call.
+ *
+ * Includes model configuration, messages, tools, and comprehensive
+ * lifecycle hooks including onFinally (runs after stream consumption).
+ */
+export interface StreamTextOptions<TOOLS extends Record<string, Tool>> {
+    /** The language model to use */
+    model: LanguageModel;
+    /**
+     * Conversation messages.
+     * Note: When using context middleware, this will be populated automatically
+     * from context history. You typically provide user instead.
+     */
+    messages?: ModelMessage[];
+    /**
+     * User message for this interaction.
+     * When using context middleware, this is added to the conversation history
+     * and messages are populated automatically from context.
+     */
+    user?: UserModelMessage;
+    /** Available tools the model can call */
+    tools?: TOOLS;
+    /**
+     * System prompt.
+     * When using context middleware, this is set on the context.
+     */
+    system?: string;
+    /** Maximum number of automatic tool call steps */
+    maxSteps?: number;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Custom headers for the request */
+    headers?: Record<string, string | undefined>;
+    /** Provider-specific options */
+    providerOptions?: ProviderOptions;
+    /**
+     * Vercel AI SDK specific: Condition to stop generation early.
+     * Pass through to the underlying SDK.
+     */
+    stopWhen?: StopCondition<any> | StopCondition<any>[];
+    /**
+     * Vercel AI SDK specific: Transformation stream for the output.
+     * Pass through to the underlying SDK.
+     */
+    experimental_transform?: any;
+    /**
+     * Called before each LLM step.
+     * Can transform the step parameters before execution.
+     */
+    prepareStep?: (step: StepParameters) => Promise<StepParameters> | StepParameters;
+    /**
+     * Called for each chunk in the stream during generation.
+     */
+    onChunk?: (event: {
+        chunk: StreamChunk;
+    }) => Promise<void> | void;
+    /**
+     * Called after each step completes (after tool execution).
+     */
+    onStepFinish?: (step: StepResult) => Promise<void> | void;
+    /**
+     * Called when the entire multi-step interaction finishes.
+     * This fires after generation completes, before stream consumption.
+     */
+    onFinish?: (result: FinalResult) => Promise<void> | void;
+    /**
+     * Called after stream consumption completes.
+     *
+     * This is the key lifecycle hook for cleanup operations:
+     * - Releasing locks (context handles)
+     * - Finishing tracing spans
+     * - Closing database connections
+     * - Saving final artifacts
+     *
+     * Guarantees:
+     * - Runs exactly once, even if multiple stream accessors are used
+     * - Runs after the stream is fully consumed OR abandoned
+     * - Runs in error cases as well (usage may be partial)
+     * - Idempotent and safe to call multiple times
+     *
+     */
+    onFinally?: () => Promise<void> | void;
+    /**
+     * Called if an error occurs during generation or consumption.
+     */
+    onError?: (error: Error) => Promise<void> | void;
+    /**
+     * Called if the operation is aborted via the abortSignal.
+     */
+    onAbort?: () => Promise<void> | void;
+}
+/**
+ * Parameters for a single LLM step.
+ */
+export interface StepParameters {
+    messages: ModelMessage[];
+    stepNumber: number;
+}
+/**
+ * A chunk from the streaming response.
+ * This is a direct re-export of Vercel AI SDK's TextStreamPart.
+ */
+export type StreamChunk = TextStreamPart<Record<string, Tool>>;
+import type { StepResult as VercelStepResult } from "ai";
+/**
+ * Result of a single LLM step.
+ * Re-exported from Vercel AI SDK to avoid type incompatibilities.
+ */
+export type StepResult = VercelStepResult<any>;
+/**
+ * Final result of the entire multi-step interaction.
+ * This is the result passed to onFinish callback.
+ * Re-exported from Vercel AI SDK's internal type.
+ */
+export type FinalResult = StepResult & {
+    readonly steps: StepResult[];
+    readonly totalUsage: LanguageModelUsage;
+};
+import type { StreamTextResult as VercelStreamTextResult } from "ai";
+/**
+ * Result of a streamText call.
+ * Re-exported from Vercel AI SDK with default for PARTIAL_OUTPUT.
+ */
+export type StreamTextResult<TOOLS extends Record<string, Tool> = Record<string, Tool>> = VercelStreamTextResult<TOOLS, any>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/ai-service/llm/interaction/provider.d.ts.map

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

package/dist/ai-service/llm/interaction/provider.js

@@ -0,0 +1,15 @@
+/**
+ * High-level provider interface for LLM streaming interactions.
+ *
+ * This interface defines a complete, SDK-agnostic contract for multi-step
+ * LLM streaming, including all lifecycle hooks. Concrete implementations
+ * (adapters) bridge this interface to specific SDKs (Vercel AI, Anthropic, etc.).
+ *
+ * Key features:
+ * - Complete lifecycle: prepareStep → onChunk → onStepFinish → onFinish → onFinally
+ * - onFinally: Guaranteed to run after stream consumption (our addition!)
+ * - SDK-agnostic: Could be implemented with any LLM SDK
+ * - Testable: Easy to mock for testing
+ */
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/ai-service/llm/interaction/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../../src/ai-service/llm/interaction/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/ai-service/llm/interaction/stream-lifecycle.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Stream lifecycle management utilities.
+ *
+ * Provides utilities for wrapping streams with lifecycle hooks, particularly
+ * `onFinally` which runs after stream consumption completes.
+ *
+ * Key challenge: The `streamText()` function returns immediately, but the
+ * streams are consumed asynchronously later. We need to track when consumption
+ * actually completes to run cleanup logic.
+ *
+ * Solution: Wrap streams with `TransformStream` that tracks consumption via
+ * the `flush()` method, which runs when the input stream closes.
+ */
+import type { StreamTextResult } from "./provider.js";
+import type { Tool } from "../../agent/tools2/types.js";
+/**
+ * Wraps a StreamTextResult to add onFinally lifecycle hook.
+ *
+ * The onFinally callback runs after stream consumption completes, handling:
+ * - Normal completion (stream exhausted)
+ * - Errors during consumption
+ * - Stream cancellation/abandonment
+ *
+ * Guarantees:
+ * - Runs exactly once, even if multiple stream accessors are used
+ * - Idempotent (safe to call multiple times)
+ * - Works with all consumption patterns (iteration, promises, piping)
+ *
+ * @param result - The stream result to wrap
+ * @param onFinally - Callback to run after consumption
+ * @returns Wrapped result with lifecycle tracking
+ *
+ * @example
+ * ```typescript
+ * const result = await streamText({ model, messages });
+ * const wrapped = withStreamLifecycle(result, async () => {
+ *   console.log('Stream consumed!');
+ *   await cleanup();
+ * });
+ *
+ * for await (const text of wrapped.textStream) {
+ *   console.log(text);
+ * }
+ * // onFinally runs here ^
+ * ```
+ */
+export declare function withStreamLifecycle<TOOLS extends Record<string, Tool> = Record<string, Tool>>(result: StreamTextResult<TOOLS>, onFinally: () => Promise<void> | void): StreamTextResult<TOOLS>;
+//# sourceMappingURL=stream-lifecycle.d.ts.map

package/dist/ai-service/llm/interaction/stream-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/ai-service/llm/interaction/stream-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAEzD,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACpC,gBAAgB,CAAC,KAAK,CAAC,CAmCzB"}