@elizaos/agent 0.25.9 → 2.0.0-alpha.151

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

@@ -0,0 +1,774 @@
+/**
+ * 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.
+ */
+/**
+ * Standardized error class for streaming operations.
+ * Provides structured error codes for easier handling.
+ */
+export class StreamError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "StreamError";
+        this.code = code;
+        this.details = details;
+    }
+    /** Check if an error is a StreamError */
+    static isStreamError(error) {
+        return error instanceof StreamError;
+    }
+}
+// ============================================================================
+// Shared constants and utilities
+// ============================================================================
+/** Safe margin to keep when streaming to avoid splitting closing tags */
+const SAFE_MARGIN = 10;
+/** Maximum buffer size to prevent memory exhaustion (100KB) */
+const MAX_BUFFER = 100 * 1024;
+/** Maximum chunk size to prevent DoS (1MB) */
+const MAX_CHUNK_SIZE = 1024 * 1024;
+/** Pre-compiled regex for actions tag extraction */
+const ACTIONS_REGEX = /<actions>([\s\S]*?)<\/actions>/;
+/**
+ * Extracts content from an XML tag in a streaming-friendly way.
+ * Shared utility used by multiple extractors.
+ *
+ * @param buffer - Current accumulated buffer
+ * @param openTag - Opening tag (e.g., "<text>")
+ * @param closeTag - Closing tag (e.g., "</text>")
+ * @param insideTag - Whether we're currently inside the tag
+ * @param safeMargin - Margin to keep for potential split tags
+ * @returns Extraction result with content and updated state
+ */
+function extractTagContent(buffer, openTag, closeTag, insideTag, safeMargin = SAFE_MARGIN) {
+    let currentBuffer = buffer;
+    let currentInsideTag = insideTag;
+    // Look for opening tag if not inside
+    if (!currentInsideTag) {
+        const idx = currentBuffer.indexOf(openTag);
+        if (idx !== -1) {
+            currentInsideTag = true;
+            currentBuffer = currentBuffer.slice(idx + openTag.length);
+        }
+        else {
+            return {
+                content: "",
+                closed: false,
+                buffer: currentBuffer,
+                insideTag: false,
+            };
+        }
+    }
+    // Check for closing tag
+    const closeIdx = currentBuffer.indexOf(closeTag);
+    if (closeIdx !== -1) {
+        const content = currentBuffer.slice(0, closeIdx);
+        const newBuffer = currentBuffer.slice(closeIdx + closeTag.length);
+        return { content, closed: true, buffer: newBuffer, insideTag: false };
+    }
+    // Stream safe content (keep margin for potential closing tag split)
+    if (currentBuffer.length > safeMargin) {
+        const content = currentBuffer.slice(0, -safeMargin);
+        const newBuffer = currentBuffer.slice(-safeMargin);
+        return { content, closed: false, buffer: newBuffer, insideTag: true };
+    }
+    return { content: "", closed: false, buffer: currentBuffer, insideTag: true };
+}
+/**
+ * Validates and limits chunk size to prevent DoS attacks.
+ * @throws StreamError if chunk exceeds maximum size
+ */
+function validateChunkSize(chunk) {
+    if (chunk.length > MAX_CHUNK_SIZE) {
+        throw new StreamError("CHUNK_TOO_LARGE", `Chunk size ${chunk.length} exceeds maximum allowed ${MAX_CHUNK_SIZE}`, {
+            chunkSize: chunk.length,
+            maxAllowed: MAX_CHUNK_SIZE,
+        });
+    }
+}
+/**
+ * Trims buffer to prevent unbounded growth.
+ */
+function trimBuffer(buffer, maxSize = MAX_BUFFER, keepSize = 1024) {
+    if (buffer.length > maxSize) {
+        return buffer.slice(-keepSize);
+    }
+    return buffer;
+}
+// ============================================================================
+// PassthroughExtractor - Simplest implementation
+// ============================================================================
+/**
+ * Streams all content as-is without any filtering.
+ * Use when LLM output is already in the desired format (e.g., plain text responses).
+ */
+export class PassthroughExtractor {
+    get done() {
+        return false; // Never "done" - always accepts more
+    }
+    push(chunk) {
+        validateChunkSize(chunk);
+        return chunk; // Pass through everything
+    }
+    reset() {
+        // Nothing to reset
+    }
+}
+// ============================================================================
+// XmlTagExtractor - Simple XML tag content extraction
+// ============================================================================
+/**
+ * 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 class XmlTagExtractor {
+    openTag;
+    closeTag;
+    buffer = "";
+    insideTag = false;
+    finished = false;
+    constructor(tagName) {
+        this.openTag = `<${tagName}>`;
+        this.closeTag = `</${tagName}>`;
+    }
+    get done() {
+        return this.finished;
+    }
+    push(chunk) {
+        if (this.finished)
+            return "";
+        validateChunkSize(chunk);
+        this.buffer += chunk;
+        // Trim buffer if too large and not inside tag
+        if (!this.insideTag) {
+            this.buffer = trimBuffer(this.buffer);
+        }
+        const result = extractTagContent(this.buffer, this.openTag, this.closeTag, this.insideTag, SAFE_MARGIN);
+        this.buffer = result.buffer;
+        this.insideTag = result.insideTag;
+        if (result.closed) {
+            this.finished = true;
+        }
+        return result.content;
+    }
+    reset() {
+        this.buffer = "";
+        this.insideTag = false;
+        this.finished = false;
+    }
+}
+/**
+ * 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 class ResponseStreamExtractor {
+    static STREAM_TAGS = ["text"];
+    static OPEN_TEXT_TAG = "<text>";
+    static CLOSE_TEXT_TAG = "</text>";
+    buffer = "";
+    insideTag = false;
+    currentTag = null;
+    finished = false;
+    responseStrategy = "pending";
+    get done() {
+        return this.finished;
+    }
+    reset() {
+        this.buffer = "";
+        this.insideTag = false;
+        this.currentTag = null;
+        this.finished = false;
+        this.responseStrategy = "pending";
+    }
+    push(chunk) {
+        validateChunkSize(chunk);
+        this.buffer += chunk;
+        // Detect strategy from <actions> tag (comes before <text>)
+        if (this.responseStrategy === "pending") {
+            this.detectResponseStrategy();
+        }
+        // Look for streamable tags
+        if (!this.insideTag) {
+            const tag = ResponseStreamExtractor.STREAM_TAGS[0];
+            const openTag = ResponseStreamExtractor.OPEN_TEXT_TAG;
+            const closeTag = ResponseStreamExtractor.CLOSE_TEXT_TAG;
+            const idx = this.buffer.indexOf(openTag);
+            if (idx !== -1) {
+                // Check if we should stream this tag
+                if (!this.shouldStreamTag(tag)) {
+                    // Skip tag entirely - wait for closing tag and remove
+                    const closeIdx = this.buffer.indexOf(closeTag);
+                    if (closeIdx !== -1) {
+                        this.buffer = this.buffer.slice(closeIdx + closeTag.length);
+                    }
+                }
+                else {
+                    this.insideTag = true;
+                    this.currentTag = tag;
+                    this.buffer = this.buffer.slice(idx + openTag.length);
+                }
+            }
+        }
+        // Trim buffer if too large and not inside tag
+        if (!this.insideTag) {
+            this.buffer = trimBuffer(this.buffer);
+            return "";
+        }
+        // Extract content from current tag using shared helper
+        const closeTag = `</${this.currentTag}>`;
+        const closeIdx = this.buffer.indexOf(closeTag);
+        if (closeIdx !== -1) {
+            const content = this.buffer.slice(0, closeIdx);
+            this.buffer = this.buffer.slice(closeIdx + closeTag.length);
+            this.insideTag = false;
+            this.currentTag = null;
+            this.finished = true;
+            return content;
+        }
+        // Stream safe content (keep margin for potential closing tag split)
+        if (this.buffer.length > SAFE_MARGIN) {
+            const toStream = this.buffer.slice(0, -SAFE_MARGIN);
+            this.buffer = this.buffer.slice(-SAFE_MARGIN);
+            return toStream;
+        }
+        return "";
+    }
+    /** Detect response strategy from <actions> tag using pre-compiled regex */
+    detectResponseStrategy() {
+        const match = this.buffer.match(ACTIONS_REGEX);
+        if (match) {
+            const actions = this.parseActions(match[1]);
+            this.responseStrategy = this.isDirectReply(actions)
+                ? "direct"
+                : "delegated";
+        }
+    }
+    /** Parse comma-separated actions */
+    parseActions(raw) {
+        return raw
+            .split(",")
+            .map((a) => a.trim().toUpperCase())
+            .filter(Boolean);
+    }
+    /** Check if actions represent a direct reply */
+    isDirectReply(actions) {
+        return actions.length === 1 && actions[0] === "REPLY";
+    }
+    /** Determine if a tag should be streamed based on strategy */
+    shouldStreamTag(tag) {
+        return tag === "text" && this.responseStrategy === "direct";
+    }
+}
+/**
+ * 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 class ActionStreamFilter {
+    buffer = "";
+    decided = false;
+    contentType = null;
+    insideTextTag = false;
+    finished = false;
+    get done() {
+        return this.finished;
+    }
+    reset() {
+        this.buffer = "";
+        this.decided = false;
+        this.contentType = null;
+        this.insideTextTag = false;
+        this.finished = false;
+    }
+    push(chunk) {
+        validateChunkSize(chunk);
+        this.buffer += chunk;
+        // Decide content type on first non-whitespace character
+        if (!this.decided) {
+            const contentType = this.detectContentType();
+            if (contentType) {
+                this.contentType = contentType;
+                this.decided = true;
+            }
+            else {
+                return "";
+            }
+        }
+        // Route based on content type
+        switch (this.contentType) {
+            case "json":
+                return ""; // Never stream JSON
+            case "text":
+                return this.handlePlainText();
+            case "xml":
+                return this.handleXml();
+            default:
+                return "";
+        }
+    }
+    /** Detect content type from first non-whitespace character */
+    detectContentType() {
+        const trimmed = this.buffer.trimStart();
+        if (trimmed.length === 0)
+            return null;
+        const firstChar = trimmed[0];
+        if (firstChar === "{" || firstChar === "[")
+            return "json";
+        if (firstChar === "<")
+            return "xml";
+        return "text";
+    }
+    /** Handle plain text - stream everything */
+    handlePlainText() {
+        const toStream = this.buffer;
+        this.buffer = "";
+        return toStream;
+    }
+    /** Handle XML content - extract and stream <text> tag content */
+    handleXml() {
+        const result = extractTagContent(this.buffer, "<text>", "</text>", this.insideTextTag, SAFE_MARGIN);
+        this.buffer = result.buffer;
+        this.insideTextTag = result.insideTag;
+        if (result.closed) {
+            this.finished = true;
+        }
+        // Trim buffer if not inside tag and not found yet
+        if (!this.insideTextTag && !result.closed) {
+            this.buffer = trimBuffer(this.buffer, 1024, 1024);
+        }
+        return result.content;
+    }
+}
+// ============================================================================
+// MarkableExtractor - Passthrough with external completion control
+// ============================================================================
+/**
+ * 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 class MarkableExtractor {
+    _done = false;
+    get done() {
+        return this._done;
+    }
+    push(chunk) {
+        validateChunkSize(chunk);
+        return chunk; // Pass through everything
+    }
+    flush() {
+        return "";
+    }
+    reset() {
+        this._done = false;
+    }
+    /**
+     * 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() {
+        this._done = true;
+    }
+}
+/**
+ * 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 class ValidationStreamExtractor {
+    config;
+    buffer = "";
+    fieldContents = new Map();
+    validatedFields = new Set();
+    emittedContent = new Map();
+    fieldStates = new Map();
+    state = "streaming";
+    constructor(config) {
+        this.config = config;
+        for (const field of config.streamFields) {
+            this.fieldStates.set(field, "pending");
+        }
+    }
+    get done() {
+        return this.state === "complete" || this.state === "failed";
+    }
+    push(chunk) {
+        // Check for cancellation - transition to failed for any non-terminal state
+        if (this.config.abortSignal?.aborted) {
+            if (this.state !== "complete" && this.state !== "failed") {
+                this.state = "failed";
+                this.emitEvent({
+                    eventType: "error",
+                    error: "Cancelled by user",
+                    timestamp: Date.now(),
+                });
+            }
+            return "";
+        }
+        if (this.state !== "streaming")
+            return "";
+        validateChunkSize(chunk);
+        this.buffer += chunk;
+        // Extract field contents from buffer
+        this.extractFieldContents();
+        // For levels 0-1, check if we can emit validated content
+        if (this.config.level <= 1) {
+            this.checkPerFieldEmission();
+        }
+        return ""; // We emit via callbacks, not return value
+    }
+    flush() {
+        // Don't overwrite failed state (e.g., from abort)
+        if (this.state === "failed") {
+            return "";
+        }
+        // For levels 2-3, emit all buffered content when validation passes
+        if (this.config.level >= 2) {
+            for (const field of this.config.streamFields) {
+                const content = this.fieldContents.get(field) || "";
+                if (content) {
+                    this.emitFieldContent(field, content);
+                }
+            }
+        }
+        this.state = "complete";
+        this.emitEvent({ eventType: "complete", timestamp: Date.now() });
+        return "";
+    }
+    reset() {
+        this.buffer = "";
+        this.fieldContents.clear();
+        this.validatedFields.clear();
+        this.emittedContent.clear();
+        for (const field of this.config.streamFields) {
+            this.fieldStates.set(field, "pending");
+        }
+        this.state = "streaming";
+    }
+    /**
+     * Signal a retry attempt. Returns info about validated fields for smart retry prompts.
+     */
+    signalRetry(retryCount) {
+        this.state = "retrying";
+        this.emitEvent({
+            eventType: "retry_start",
+            retryCount,
+            timestamp: Date.now(),
+        });
+        return { validatedFields: Array.from(this.validatedFields) };
+    }
+    /**
+     * Signal an unrecoverable error.
+     */
+    signalError(message) {
+        this.state = "failed";
+        this.emitEvent({
+            eventType: "error",
+            error: message,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Get fields that passed validation (for smart retry context).
+     */
+    getValidatedFields() {
+        const result = new Map();
+        for (const field of this.validatedFields) {
+            const content = this.fieldContents.get(field);
+            if (content) {
+                result.set(field, content);
+            }
+        }
+        return result;
+    }
+    /**
+     * Diagnose what went wrong for error reporting.
+     */
+    diagnose() {
+        const missingFields = [];
+        const invalidFields = [];
+        const incompleteFields = [];
+        for (const row of this.config.schema) {
+            const state = this.fieldStates.get(row.field);
+            switch (state) {
+                case "pending":
+                    missingFields.push(row.field);
+                    break;
+                case "invalid":
+                    invalidFields.push(row.field);
+                    break;
+                case "partial":
+                    incompleteFields.push(row.field);
+                    break;
+            }
+        }
+        return { missingFields, invalidFields, incompleteFields };
+    }
+    /**
+     * Get current extractor state.
+     */
+    getState() {
+        return this.state;
+    }
+    // Private helpers
+    extractFieldContents() {
+        // Pre-compute all field tags for boundary detection
+        const allOpenTags = this.config.schema.map((row) => `<${row.field}>`);
+        for (const row of this.config.schema) {
+            const field = row.field;
+            const openTag = `<${field}>`;
+            const closeTag = `</${field}>`;
+            const openIdx = this.buffer.indexOf(openTag);
+            if (openIdx === -1)
+                continue;
+            const contentStart = openIdx + openTag.length;
+            const closeIdx = this.buffer.indexOf(closeTag, contentStart);
+            if (closeIdx !== -1) {
+                // Complete field found
+                const content = this.buffer.substring(contentStart, closeIdx);
+                this.fieldContents.set(field, content);
+                this.fieldStates.set(field, "complete");
+            }
+            else if (this.fieldStates.get(field) !== "complete") {
+                // Partial field - still streaming
+                this.fieldStates.set(field, "partial");
+                // Find the end boundary for partial content:
+                // Either the next field's opening tag or end of buffer
+                let partialEnd = this.buffer.length;
+                for (const otherTag of allOpenTags) {
+                    if (otherTag === openTag)
+                        continue; // Skip self
+                    const otherIdx = this.buffer.indexOf(otherTag, contentStart);
+                    if (otherIdx !== -1 && otherIdx < partialEnd) {
+                        partialEnd = otherIdx;
+                    }
+                }
+                const partialContent = this.buffer.substring(contentStart, partialEnd);
+                this.fieldContents.set(field, partialContent);
+            }
+        }
+    }
+    checkPerFieldEmission() {
+        for (const field of this.config.streamFields) {
+            const state = this.fieldStates.get(field);
+            if (state === "invalid")
+                continue; // Skip already invalid fields
+            const content = this.fieldContents.get(field);
+            if (!content)
+                continue;
+            // Check validation codes if required
+            const expectedCode = this.config.expectedCodes.get(field);
+            if (expectedCode) {
+                const startCodeValid = this.checkValidationCode(field, "start", expectedCode);
+                const endCodeValid = this.checkValidationCode(field, "end", expectedCode);
+                if (state === "complete") {
+                    if (startCodeValid && endCodeValid) {
+                        this.validatedFields.add(field);
+                        this.emitFieldContent(field, content);
+                        this.emitEvent({
+                            eventType: "field_validated",
+                            field,
+                            timestamp: Date.now(),
+                        });
+                    }
+                    else if (startCodeValid && !endCodeValid) {
+                        // Start valid but end invalid
+                        this.fieldStates.set(field, "invalid");
+                        this.emitEvent({
+                            eventType: "error",
+                            field,
+                            error: `End validation code mismatch for ${field}`,
+                            timestamp: Date.now(),
+                        });
+                    }
+                    else {
+                        this.fieldStates.set(field, "invalid");
+                        this.emitEvent({
+                            eventType: "error",
+                            field,
+                            error: `Validation codes mismatch for ${field}`,
+                            timestamp: Date.now(),
+                        });
+                    }
+                }
+            }
+            else {
+                // No validation codes for this field
+                if (this.config.level === 0) {
+                    // Level 0: Stream immediately as content arrives (no validation)
+                    this.emitFieldContent(field, content);
+                }
+                else if (state === "complete") {
+                    // Levels 1-3: Stream when field is complete (even without per-field validation)
+                    // Per-field validation is optional; fields without codes stream on completion
+                    this.emitFieldContent(field, content);
+                }
+                // For partial state at levels 1-3: wait until complete before streaming
+            }
+        }
+    }
+    checkValidationCode(field, position, expectedCode) {
+        const codeField = `code_${field}_${position}`;
+        const openTag = `<${codeField}>`;
+        const closeTag = `</${codeField}>`;
+        const openIdx = this.buffer.indexOf(openTag);
+        if (openIdx === -1)
+            return false;
+        const contentStart = openIdx + openTag.length;
+        const closeIdx = this.buffer.indexOf(closeTag, contentStart);
+        if (closeIdx === -1)
+            return false;
+        const actualCode = this.buffer.substring(contentStart, closeIdx).trim();
+        return actualCode === expectedCode;
+    }
+    emitFieldContent(field, content) {
+        const previouslyEmitted = this.emittedContent.get(field) || "";
+        // Defensive check: if content shrinks (shouldn't happen, indicates extraction bug),
+        // reset and emit the full new content rather than producing invalid substring
+        if (content.length < previouslyEmitted.length) {
+            // Content shrunk unexpectedly - reset tracking and emit full content
+            this.emittedContent.set(field, content);
+            if (content) {
+                this.config.onChunk(content, field, content);
+                this.emitEvent({
+                    eventType: "chunk",
+                    field,
+                    chunk: content,
+                    timestamp: Date.now(),
+                });
+            }
+            return;
+        }
+        const newContent = content.substring(previouslyEmitted.length);
+        if (newContent) {
+            this.config.onChunk(newContent, field, content);
+            this.emitEvent({
+                eventType: "chunk",
+                field,
+                chunk: newContent,
+                timestamp: Date.now(),
+            });
+            this.emittedContent.set(field, content);
+        }
+    }
+    emitEvent(event) {
+        if (this.config.onEvent) {
+            this.config.onEvent(event);
+        }
+    }
+}
+/**
+ * Creates a streaming retry state from an extractor.
+ */
+export function createStreamingRetryState(extractor) {
+    let streamedText = "";
+    return {
+        getStreamedText: () => {
+            const buffered = extractor.flush?.() ?? "";
+            if (buffered) {
+                streamedText += buffered;
+            }
+            return streamedText;
+        },
+        isComplete: () => extractor.done,
+        reset: () => {
+            extractor.reset?.();
+            streamedText = "";
+        },
+        /** Append text to the streamed content buffer */
+        appendText: (text) => {
+            streamedText += text;
+        },
+    };
+}
+/**
+ * Creates a complete streaming context with retry state management.
+ */
+export function createStreamingContext(extractor, onStreamChunk, messageId) {
+    const retryState = createStreamingRetryState(extractor);
+    return {
+        /**
+         * NOTE: `accumulated` from the upstream source is forwarded unchanged.
+         * This is only semantically correct when `extractor` is a passthrough
+         * (i.e., extractor.push(chunk) === chunk). MarkableExtractor satisfies
+         * this invariant; other extractors may not.
+         */
+        onStreamChunk: async (chunk, msgId, accumulated) => {
+            if (extractor.done)
+                return;
+            const textToStream = extractor.push(chunk);
+            if (textToStream) {
+                retryState.appendText(textToStream);
+                await onStreamChunk(textToStream, msgId, accumulated);
+            }
+        },
+        messageId,
+        reset: retryState.reset,
+        getStreamedText: retryState.getStreamedText,
+        isComplete: retryState.isComplete,
+    };
+}