@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.334

package/packages/typescript/src/utils/retry.js

@@ -0,0 +1,190 @@
+/**
+ * Retry and backoff utilities for robust async operations.
+ *
+ * Provides:
+ * - Exponential backoff with jitter
+ * - Configurable retry logic
+ * - Abort signal support
+ *
+ * @module utils/retry
+ */
+// ============================================================================
+// Sleep Utilities
+// ============================================================================
+/**
+ * Sleep for a specified duration.
+ *
+ * @param ms - Milliseconds to sleep
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Sleep with abort signal support.
+ *
+ * @param ms - Milliseconds to sleep
+ * @param abortSignal - Optional signal to abort sleep
+ * @throws If aborted
+ */
+export async function sleepWithAbort(ms, abortSignal) {
+    if (ms <= 0) {
+        return;
+    }
+    return new Promise((resolve, reject) => {
+        if (abortSignal?.aborted) {
+            return reject(new Error("aborted"));
+        }
+        const timeoutId = setTimeout(() => {
+            if (abortSignal) {
+                abortSignal.removeEventListener("abort", onAbort);
+            }
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timeoutId);
+            reject(new Error("aborted"));
+        }
+        if (abortSignal) {
+            abortSignal.addEventListener("abort", onAbort);
+        }
+    });
+}
+/**
+ * Compute the backoff delay for a given attempt.
+ *
+ * @param policy - Backoff policy configuration
+ * @param attempt - Attempt number (1-based)
+ * @returns Delay in milliseconds
+ */
+export function computeBackoff(policy, attempt) {
+    const base = policy.initialMs * policy.factor ** Math.max(attempt - 1, 0);
+    const jitter = base * policy.jitter * Math.random();
+    return Math.min(policy.maxMs, Math.round(base + jitter));
+}
+const DEFAULT_RETRY_CONFIG = {
+    attempts: 3,
+    minDelayMs: 300,
+    maxDelayMs: 30_000,
+    jitter: 0,
+};
+const asFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+const clampNumber = (value, fallback, min, max) => {
+    const next = asFiniteNumber(value);
+    if (next === undefined) {
+        return fallback;
+    }
+    const floor = typeof min === "number" ? min : Number.NEGATIVE_INFINITY;
+    const ceiling = typeof max === "number" ? max : Number.POSITIVE_INFINITY;
+    return Math.min(Math.max(next, floor), ceiling);
+};
+/**
+ * Resolve retry configuration with defaults.
+ *
+ * @param defaults - Default configuration
+ * @param overrides - Override values
+ * @returns Fully resolved configuration
+ */
+export function resolveRetryConfig(defaults = DEFAULT_RETRY_CONFIG, overrides) {
+    const attempts = Math.max(1, Math.round(clampNumber(overrides?.attempts, defaults.attempts, 1)));
+    const minDelayMs = Math.max(0, Math.round(clampNumber(overrides?.minDelayMs, defaults.minDelayMs, 0)));
+    const maxDelayMs = Math.max(minDelayMs, Math.round(clampNumber(overrides?.maxDelayMs, defaults.maxDelayMs, 0)));
+    const jitter = clampNumber(overrides?.jitter, defaults.jitter, 0, 1);
+    return { attempts, minDelayMs, maxDelayMs, jitter };
+}
+function applyJitter(delayMs, jitter) {
+    if (jitter <= 0) {
+        return delayMs;
+    }
+    const offset = (Math.random() * 2 - 1) * jitter;
+    return Math.max(0, Math.round(delayMs * (1 + offset)));
+}
+/**
+ * Execute an async function with automatic retries.
+ *
+ * Supports two calling styles:
+ * 1. Simple: `retryAsync(fn, attempts, initialDelayMs)`
+ * 2. Full options: `retryAsync(fn, { attempts, minDelayMs, ... })`
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const result = await retryAsync(() => fetch(url), 3, 1000);
+ *
+ * // Full options
+ * const result = await retryAsync(
+ *   () => fetch(url),
+ *   {
+ *     attempts: 5,
+ *     minDelayMs: 500,
+ *     maxDelayMs: 30000,
+ *     jitter: 0.2,
+ *     shouldRetry: (err) => isRetryable(err),
+ *     onRetry: ({ attempt, delayMs }) => log(`Retry ${attempt} in ${delayMs}ms`)
+ *   }
+ * );
+ * ```
+ *
+ * @param fn - Async function to execute
+ * @param attemptsOrOptions - Number of attempts or full options
+ * @param initialDelayMs - Initial delay (only used with simple calling style)
+ * @returns Promise resolving to function result
+ * @throws Last error after all retries exhausted
+ */
+export async function retryAsync(fn, attemptsOrOptions = 3, initialDelayMs = 300) {
+    if (typeof attemptsOrOptions === "number") {
+        const attempts = Math.max(1, Math.round(attemptsOrOptions));
+        let lastErr;
+        for (let i = 0; i < attempts; i += 1) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastErr = err;
+                if (i === attempts - 1) {
+                    break;
+                }
+                const delay = initialDelayMs * 2 ** i;
+                await sleep(delay);
+            }
+        }
+        throw lastErr ?? new Error("Retry failed");
+    }
+    const options = attemptsOrOptions;
+    const resolved = resolveRetryConfig(DEFAULT_RETRY_CONFIG, options);
+    const maxAttempts = resolved.attempts;
+    const minDelayMs = resolved.minDelayMs;
+    const maxDelayMs = Number.isFinite(resolved.maxDelayMs) && resolved.maxDelayMs > 0
+        ? resolved.maxDelayMs
+        : Number.POSITIVE_INFINITY;
+    const jitter = resolved.jitter;
+    const shouldRetry = options.shouldRetry ?? (() => true);
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= maxAttempts || !shouldRetry(err, attempt)) {
+                break;
+            }
+            const retryAfterMs = options.retryAfterMs?.(err);
+            const hasRetryAfter = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs);
+            const baseDelay = hasRetryAfter
+                ? Math.max(retryAfterMs, minDelayMs)
+                : minDelayMs * 2 ** (attempt - 1);
+            let delay = Math.min(baseDelay, maxDelayMs);
+            delay = applyJitter(delay, jitter);
+            delay = Math.min(Math.max(delay, minDelayMs), maxDelayMs);
+            options.onRetry?.({
+                attempt,
+                maxAttempts,
+                delayMs: delay,
+                err,
+                label: options.label,
+            });
+            await sleep(delay);
+        }
+    }
+    throw lastErr ?? new Error("Retry failed");
+}

package/packages/typescript/src/utils/server-health.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Server health check utilities for waiting for servers to be ready
+ */
+export interface ServerHealthOptions {
+    port: number;
+    endpoint?: string;
+    maxWaitTime?: number;
+    pollInterval?: number;
+    requestTimeout?: number;
+    host?: string;
+    protocol?: "http" | "https";
+}
+/**
+ * Error thrown when server fails to become ready within the timeout
+ */
+export declare class ServerHealthError extends Error {
+    readonly url: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, url: string, cause?: Error | undefined);
+}
+/**
+ * Wait for server to be ready by polling health endpoint
+ *
+ * @param options - Configuration options for server health check
+ * @throws ServerHealthError if server doesn't become ready within maxWaitTime
+ */
+export declare function waitForServerReady(options: ServerHealthOptions): Promise<void>;
+/**
+ * Simple ping check for server availability (no stabilization wait)
+ *
+ * @param options - Configuration options for server ping
+ * @returns true if server responds with 2xx, false otherwise
+ */
+export declare function pingServer(options: ServerHealthOptions): Promise<boolean>;
+//# sourceMappingURL=server-health.d.ts.map

package/packages/typescript/src/utils/server-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-health.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/server-health.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAG1B,GAAG,EAAE,MAAM;aACX,KAAK,CAAC,EAAE,KAAK;gBAF7B,OAAO,EAAE,MAAM,EACC,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,KAAK,YAAA;CAK9B;AAoCD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,mBAAmB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC/B,OAAO,EAAE,mBAAmB,GAC1B,OAAO,CAAC,OAAO,CAAC,CAKlB"}

package/packages/typescript/src/utils/server-health.js

@@ -0,0 +1,76 @@
+/**
+ * Server health check utilities for waiting for servers to be ready
+ */
+/**
+ * Error thrown when server fails to become ready within the timeout
+ */
+export class ServerHealthError extends Error {
+    url;
+    cause;
+    constructor(message, url, cause) {
+        super(message);
+        this.url = url;
+        this.cause = cause;
+        this.name = "ServerHealthError";
+    }
+}
+/**
+ * Build URL from options
+ */
+function buildUrl(options) {
+    const { port, endpoint = "/api/agents", host = "localhost", protocol = "http", } = options;
+    return `${protocol}://${host}:${port}${endpoint}`;
+}
+/**
+ * Perform a single health check request with timeout
+ */
+async function checkHealth(url, timeout) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        return { ok: response.ok };
+    }
+    catch (error) {
+        // Network errors, timeouts, aborts are expected during startup
+        return { ok: false, error: error };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Wait for server to be ready by polling health endpoint
+ *
+ * @param options - Configuration options for server health check
+ * @throws ServerHealthError if server doesn't become ready within maxWaitTime
+ */
+export async function waitForServerReady(options) {
+    const { maxWaitTime = 30000, pollInterval = 1000, requestTimeout = 2000, } = options;
+    const url = buildUrl(options);
+    const startTime = Date.now();
+    let lastError;
+    while (Date.now() - startTime < maxWaitTime) {
+        const result = await checkHealth(url, requestTimeout);
+        if (result.ok) {
+            // Server is ready, give it one more second to stabilize
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+            return;
+        }
+        lastError = result.error;
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    throw new ServerHealthError(`Server failed to become ready at ${url} within ${maxWaitTime}ms`, url, lastError);
+}
+/**
+ * Simple ping check for server availability (no stabilization wait)
+ *
+ * @param options - Configuration options for server ping
+ * @returns true if server responds with 2xx, false otherwise
+ */
+export async function pingServer(options) {
+    const { requestTimeout = 2000 } = options;
+    const url = buildUrl(options);
+    const result = await checkHealth(url, requestTimeout);
+    return result.ok;
+}

package/packages/typescript/src/utils/slice-to-fit-budget.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Choose how many items to include so estimated character total stays within a
+ * target budget.
+ *
+ * WHY: Providers often fetch a superset of data, then need to keep prompt size
+ * bounded. One fetch + in-memory selection avoids extra DB round trips while
+ * still adapting to item size (short items -> more fit, long items -> fewer).
+ */
+export declare function sliceToFitBudget<T>(items: T[], estimateChars: (item: T) => number, targetChars: number, options?: {
+    fromEnd?: boolean;
+}): T[];
+//# sourceMappingURL=slice-to-fit-budget.d.ts.map

package/packages/typescript/src/utils/slice-to-fit-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slice-to-fit-budget.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/slice-to-fit-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wBAAgB,gBAAgB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EAAE,EACV,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAClC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,CAAC,EAAE,CA4BL"}

package/packages/typescript/src/utils/slice-to-fit-budget.js

@@ -0,0 +1,36 @@
+/**
+ * Choose how many items to include so estimated character total stays within a
+ * target budget.
+ *
+ * WHY: Providers often fetch a superset of data, then need to keep prompt size
+ * bounded. One fetch + in-memory selection avoids extra DB round trips while
+ * still adapting to item size (short items -> more fit, long items -> fewer).
+ */
+export function sliceToFitBudget(items, estimateChars, targetChars, options) {
+    if (items.length === 0)
+        return [];
+    // Zero or negative budget means no room - return empty array
+    if (targetChars <= 0)
+        return [];
+    const fromEnd = options?.fromEnd ?? false;
+    let total = 0;
+    let count = 0;
+    // Calculate all sizes upfront to avoid double estimation
+    const sizes = items.map(estimateChars);
+    if (fromEnd) {
+        for (let index = items.length - 1; index >= 0; index--) {
+            if (total + sizes[index] > targetChars)
+                break;
+            total += sizes[index];
+            count++;
+        }
+        const take = count > 0 ? count : 0;
+        return items.slice(items.length - take);
+    }
+    for (; count < items.length; count++) {
+        if (total + sizes[count] > targetChars)
+            break;
+        total += sizes[count];
+    }
+    return items.slice(0, count);
+}

package/packages/typescript/src/utils/state-dir.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Milady state-dir resolution.
+ *
+ * Canonical rule: `MILADY_STATE_DIR` wins, then `ELIZA_STATE_DIR` (historical
+ * alias), then `<homedir>/.milady`. Every caller that wants to touch the
+ * persisted user state (skills, training, optimized prompts, counters) must
+ * go through `resolveStateDir()` so we have one place that enforces this
+ * precedence.
+ *
+ * Uses `os.homedir()` instead of `process.env.HOME` so the resolution works
+ * on Windows where `HOME` is not normally set; `homedir()` returns a string
+ * or throws.
+ */
+/**
+ * Resolve the Milady per-user state directory, honoring the documented
+ * `MILADY_STATE_DIR` → `ELIZA_STATE_DIR` → `~/.milady` precedence.
+ */
+export declare function resolveStateDir(): string;
+//# sourceMappingURL=state-dir.d.ts.map

package/packages/typescript/src/utils/state-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-dir.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/utils/state-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAMxC"}

package/packages/typescript/src/utils/state-dir.js

@@ -0,0 +1,24 @@
+/**
+ * Milady state-dir resolution.
+ *
+ * Canonical rule: `MILADY_STATE_DIR` wins, then `ELIZA_STATE_DIR` (historical
+ * alias), then `<homedir>/.milady`. Every caller that wants to touch the
+ * persisted user state (skills, training, optimized prompts, counters) must
+ * go through `resolveStateDir()` so we have one place that enforces this
+ * precedence.
+ *
+ * Uses `os.homedir()` instead of `process.env.HOME` so the resolution works
+ * on Windows where `HOME` is not normally set; `homedir()` returns a string
+ * or throws.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Resolve the Milady per-user state directory, honoring the documented
+ * `MILADY_STATE_DIR` → `ELIZA_STATE_DIR` → `~/.milady` precedence.
+ */
+export function resolveStateDir() {
+    return (process.env.MILADY_STATE_DIR?.trim() ||
+        process.env.ELIZA_STATE_DIR?.trim() ||
+        join(homedir(), ".milady"));
+}

package/packages/typescript/src/utils/streaming.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Streaming utilities for filtering and extracting streamable content.
+ *
+ * This module provides implementations of {@link IStreamExtractor}:
+ * - PassthroughExtractor - Simple passthrough (no filtering)
+ * - XmlTagExtractor - Extract content from a specific XML tag
+ * - ResponseStreamExtractor - Action-aware XML (for DefaultMessageService)
+ * - ActionStreamFilter - Content-type aware filter (for action handlers)
+ *
+ * For the interface definition, see types/streaming.ts.
+ * Implementations can use these or create their own extractors.
+ */
+import type { StreamChunkCallback } from "../types/components";
+import type { IStreamExtractor } from "../types/streaming";
+/** Error codes for streaming operations */
+export type StreamErrorCode = "CHUNK_TOO_LARGE" | "BUFFER_OVERFLOW" | "PARSE_ERROR" | "TIMEOUT" | "ABORTED";
+/**
+ * Standardized error class for streaming operations.
+ * Provides structured error codes for easier handling.
+ */
+export declare class StreamError extends Error {
+    readonly code: StreamErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(code: StreamErrorCode, message: string, details?: Record<string, unknown>);
+    /** Check if an error is a StreamError */
+    static isStreamError(error: unknown): error is StreamError;
+}
+/**
+ * Streams all content as-is without any filtering.
+ * Use when LLM output is already in the desired format (e.g., plain text responses).
+ */
+export declare class PassthroughExtractor implements IStreamExtractor {
+    get done(): boolean;
+    push(chunk: string): string;
+    reset(): void;
+}
+/**
+ * Extracts content from a specific XML tag, streaming it progressively.
+ * Use when you have a simple XML format like `<response><text>content</text></response>`.
+ *
+ * @example
+ * ```ts
+ * const extractor = new XmlTagExtractor('text');
+ * extractor.push('<response><text>Hello'); // Returns 'Hel' (keeps margin for split tags)
+ * extractor.push(' world!</text></response>'); // Returns 'lo world!'
+ * ```
+ */
+export declare class XmlTagExtractor implements IStreamExtractor {
+    private readonly openTag;
+    private readonly closeTag;
+    private buffer;
+    private insideTag;
+    private finished;
+    constructor(tagName: string);
+    get done(): boolean;
+    push(chunk: string): string;
+    reset(): void;
+}
+/**
+ * Extracts streamable text from XML-structured LLM responses with action-based routing.
+ *
+ * This is the default implementation used by DefaultMessageService.
+ * It understands the `<actions>` tag to determine whether to stream `<text>` content.
+ *
+ * Strategy:
+ * - Parse <actions> to determine if response is direct (REPLY) or delegated (other actions)
+ * - If direct: stream <text> content immediately
+ * - If delegated: skip <text> (action handler will generate its own response via ActionStreamFilter)
+ *
+ * For simpler use cases without action routing, use {@link XmlTagExtractor} instead.
+ */
+export declare class ResponseStreamExtractor implements IStreamExtractor {
+    private static readonly STREAM_TAGS;
+    private static readonly OPEN_TEXT_TAG;
+    private static readonly CLOSE_TEXT_TAG;
+    private buffer;
+    private insideTag;
+    private currentTag;
+    private finished;
+    private responseStrategy;
+    get done(): boolean;
+    reset(): void;
+    push(chunk: string): string;
+    /** Detect response strategy from <actions> tag using pre-compiled regex */
+    private detectResponseStrategy;
+    /** Parse comma-separated actions */
+    private parseActions;
+    /** Check if actions represent a direct reply */
+    private isDirectReply;
+    /** Determine if a tag should be streamed based on strategy */
+    private shouldStreamTag;
+}
+/**
+ * Filters action handler output for streaming.
+ * Used by runtime.ts processActions() for each action's useModel calls.
+ *
+ * Auto-detects content type from first non-whitespace character:
+ * - JSON (starts with { or [) → Don't stream (structured data for parsing)
+ * - XML (starts with <) → Look for <text> tag and stream its content
+ * - Plain text → Stream immediately
+ */
+export declare class ActionStreamFilter implements IStreamExtractor {
+    private buffer;
+    private decided;
+    private contentType;
+    private insideTextTag;
+    private finished;
+    get done(): boolean;
+    reset(): void;
+    push(chunk: string): string;
+    /** Detect content type from first non-whitespace character */
+    private detectContentType;
+    /** Handle plain text - stream everything */
+    private handlePlainText;
+    /** Handle XML content - extract and stream <text> tag content */
+    private handleXml;
+}
+/**
+ * Passthrough extractor that can be marked complete externally.
+ *
+ * WHY: When using ValidationStreamExtractor inside dynamicPromptExecFromState,
+ * extraction/completion is handled internally. But the outer streaming context
+ * still needs to know when streaming is complete for retry/fallback logic.
+ *
+ * This extractor passes through all content and provides a markComplete() method
+ * that the caller can invoke when the underlying operation completes successfully.
+ *
+ * @example
+ * ```ts
+ * const extractor = new MarkableExtractor();
+ * const ctx = createStreamingContext(extractor, callback);
+ *
+ * const result = await dynamicPromptExecFromState({ ... });
+ * if (result) {
+ *   extractor.markComplete(); // Signal success
+ * }
+ *
+ * if (ctx.isComplete()) {
+ *   // Now returns true after markComplete()
+ * }
+ * ```
+ */
+export declare class MarkableExtractor implements IStreamExtractor {
+    private _done;
+    get done(): boolean;
+    push(chunk: string): string;
+    flush(): string;
+    reset(): void;
+    /**
+     * Mark the extractor as complete.
+     * WHY: Called by the outer code when the underlying operation completes
+     * successfully. This allows isComplete() to return true for retry/fallback logic.
+     */
+    markComplete(): void;
+}
+import type { SchemaRow, StreamEvent } from "../types/state";
+import type { IStreamingRetryState } from "../types/streaming";
+/**
+ * Extractor state machine for validation-aware streaming.
+ */
+export type ExtractorState = "streaming" | "validating" | "retrying" | "complete" | "failed";
+/**
+ * Per-field state tracking for progressive validation.
+ */
+export type FieldState = "pending" | "partial" | "complete" | "invalid";
+/**
+ * Configuration for ValidationStreamExtractor.
+ */
+export interface ValidationStreamExtractorConfig {
+    /** Validation level (0-3) */
+    level: 0 | 1 | 2 | 3;
+    /** Schema rows with field definitions */
+    schema: SchemaRow[];
+    /** Which fields to stream to the consumer */
+    streamFields: string[];
+    /** Expected validation codes per field */
+    expectedCodes: Map<string, string>;
+    /**
+     * Callback for streaming chunks.
+     * WHY accumulated: consumers (voice detection, client-side merge) need the
+     * full field text to avoid re-deriving it from deltas — which caused the
+     * dual-extractor garbling bug when two pipelines accumulated differently.
+     * The extractor already tracks this as `content` in emitFieldContent, so
+     * surfacing it is zero-cost.
+     */
+    onChunk: (chunk: string, field?: string, accumulated?: string) => void;
+    /** Rich event callback for sophisticated consumers */
+    onEvent?: (event: StreamEvent) => void;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Whether the consumer has an onEvent handler */
+    hasRichConsumer?: boolean;
+}
+/**
+ * Diagnosis result for error analysis.
+ */
+export interface ValidationDiagnosis {
+    /** Fields that were never started */
+    missingFields: string[];
+    /** Fields with wrong validation codes */
+    invalidFields: string[];
+    /** Fields that started but didn't complete */
+    incompleteFields: string[];
+}
+/**
+ * Validation-aware stream extractor for dynamicPromptExecFromState.
+ *
+ * WHY THIS EXISTS:
+ * LLMs can silently truncate output when they hit token limits. This is catastrophic
+ * for structured outputs - you might get half a JSON object. Traditional streaming
+ * has no validation - you might stream half a broken response.
+ *
+ * This extractor bridges the gap: it enables streaming while detecting truncation.
+ * It uses "validation codes" - random UUIDs that the LLM must echo. If the echoed
+ * code matches, we know that part wasn't truncated.
+ *
+ * VALIDATION LEVELS:
+ * - Level 0 (Trusted): No codes, stream immediately. Fast but no safety.
+ * - Level 1 (Progressive): Per-field codes, emit as each field validates.
+ * - Level 2 (First Checkpoint): Code at start only, buffer until validated.
+ * - Level 3 (Full): Codes at start AND end, maximum safety.
+ */
+export declare class ValidationStreamExtractor implements IStreamExtractor {
+    private readonly config;
+    private buffer;
+    private fieldContents;
+    private validatedFields;
+    private emittedContent;
+    private fieldStates;
+    private state;
+    constructor(config: ValidationStreamExtractorConfig);
+    get done(): boolean;
+    push(chunk: string): string;
+    flush(): string;
+    reset(): void;
+    /**
+     * Signal a retry attempt. Returns info about validated fields for smart retry prompts.
+     */
+    signalRetry(retryCount: number): {
+        validatedFields: string[];
+    };
+    /**
+     * Signal an unrecoverable error.
+     */
+    signalError(message: string): void;
+    /**
+     * Get fields that passed validation (for smart retry context).
+     */
+    getValidatedFields(): Map<string, string>;
+    /**
+     * Diagnose what went wrong for error reporting.
+     */
+    diagnose(): ValidationDiagnosis;
+    /**
+     * Get current extractor state.
+     */
+    getState(): ExtractorState;
+    private extractFieldContents;
+    private checkPerFieldEmission;
+    private checkValidationCode;
+    private emitFieldContent;
+    private emitEvent;
+}
+import type { StreamingContext } from "../streaming-context";
+/**
+ * Creates a streaming retry state from an extractor.
+ */
+export declare function createStreamingRetryState(extractor: IStreamExtractor): IStreamingRetryState & {
+    appendText: (text: string) => void;
+};
+/**
+ * Creates a complete streaming context with retry state management.
+ */
+export declare function createStreamingContext(extractor: IStreamExtractor, onStreamChunk: StreamChunkCallback, messageId?: string): StreamingContext & IStreamingRetryState;
+//# sourceMappingURL=streaming.d.ts.map