@ai-matrx/chat 0.7.3 → 0.7.5

package/dist/agents/redux/execution-system/utils/stream-block-accumulator.d.ts

@@ -1,87 +1,357 @@
 /**
- * StreamBlockAccumulator — the LIVE DRIVER over the one block splitter.
+ * StreamBlockAccumulator — Incremental block detection for streaming text.
  *
- * Sits inside the processStream() closure and ingests rAF-batched text deltas. It owns no
- * splitting rules of its own: every delta goes to rich-content's `BlockSplitter` — the same
- * reading a reload of the stored text draws — and the driver turns the blocks into
- * `upsertRenderBlock` dispatches (Audit B family 1, chair ruling 2026-10-08: live and reload
- * always draw the same blocks).
+ * Sits inside the processStream() closure and ingests rAF-batched text
+ * deltas. For each delta it runs the cheap content-prefilter (classifyLine)
+ * to detect block boundaries and emits upsertRenderBlock dispatches so
+ * Redux stores typed RenderBlockPayloads incrementally.
  *
- * What the driver adds is only what a STREAM has and a reload does not:
- *  - status: every block but the last is `complete`; the last is `streaming` until finalize;
- *  - stable ids (`client_block_<n>`) and retraction of a block a later reading no longer has;
- *  - a LIVE kind envelope for the open JSON region (a content-ir parse session), so a kind
- *    draws as its card while it arrives — a closed region carries the splitter's own envelope;
- *  - holds: a nascent JSON object (`{` with no key yet) and an open front matter are not drawn;
- *  - tool boundaries (`breakTextBlock`): each text run is split on its own, as reload splits
- *    each run's stored text;
- *  - provider-retry rewind and the reasoning-boundary diagnostics.
+ * 97% of lines are plain text — they append to the current text block
+ * with zero regex or parsing. The remaining 3% trigger boundary
+ * transitions (code fences, XML tags, tables, images, etc.).
+ *
+ * Key constraint: each character is processed exactly once. The
+ * accumulator never re-reads completed blocks.
  */
 import type { RenderBlockPayload } from "@ai-matrx/agents/generated/stream-events";
 type DispatchFn = (action: unknown) => unknown;
-type UpsertAction = (payload: {
-    requestId: string;
-    block: RenderBlockPayload;
-}) => unknown;
 export declare class StreamBlockAccumulator {
-    private readonly requestId;
-    private readonly upsertAction;
-    private splitter;
-    /** Absolute index of the current text run's first block (tool boundaries start a new run). */
-    private base;
-    /** How many blocks the current run has drawn (retraction bookkeeping). */
-    private drawn;
-    /** Last dispatched signature per absolute block index. */
-    private signatures;
-    private region;
-    /** Final envelope of a region closed at a run's end (stream death or tool boundary). */
-    private closedEnvelopes;
-    private identities;
-    private unclosedReasoningReported;
-    constructor(requestId: string, upsertAction: UpsertAction);
-    /** Ingest a text delta (the rAF-batched textBuffer content). */
+    private requestId;
+    private currentBlockIndex;
+    private currentBlockType;
+    private currentBlockContent;
+    /**
+     * Number of lines appended to the current block. Used to preserve LEADING
+     * blank lines: the first appended line is written verbatim (even if it's an
+     * empty string), and every subsequent line is joined with "\n". Without this
+     * counter, appending "" to an empty `currentBlockContent` was a no-op, which
+     * silently swallowed a block's first blank line and produced a 1-byte drift
+     * vs the V2 splitter / Python server (which keep that blank line).
+     */
+    private currentBlockLineCount;
+    private pendingLineFragment;
+    /**
+     * True once the block at the current index has been dispatched to Redux —
+     * including speculative streaming projections of `pendingLineFragment`
+     * (see `emitCurrentBlock`). Reset whenever a new block is opened. Used by
+     * `closeCurrentBlock` to retract a speculative block whose line turned out
+     * to be a different typed block (see the bare-JSON duplication note there).
+     */
+    private currentBlockEmitted;
+    /**
+     * THE DATA KEEPS ITS KINDS. A JSON wrapper that holds kinds is drawn as its
+     * kinds plus a residual (A7) — the residual is the wrapper's data WITH ITS
+     * KINDS REMOVED, so it is a display projection, never the answer. Every
+     * such split remembers the bytes it was cut from, keyed by its first block
+     * index, so data capture (`deriveAnswerDataText`) reads what the model wrote.
+     * Live only; a rewind forgets every split at or past its boundary.
+     */
+    private wrapperSplits;
+    private subState;
+    /**
+     * URL + label for the current `audio` block. The accumulator's single-line
+     * media blocks (image/video) leave `data` null, which is why the legacy
+     * client image/video markdown path never populated `src`. Audio MUST carry
+     * its URL on `data.src` or BlockRenderer's `audio` case renders nothing —
+     * so we stash the extracted link here and emit it via buildBlockData.
+     */
+    private pendingMediaData;
+    private ingestCount;
+    private emitCount;
+    /** Live kind-parser session for the OPEN JSON region (fence or bare). */
+    private irSession;
+    /** Lines fed to the session for this region (drives the "\n" separators). */
+    private irRegionLineCount;
+    /** How many chars of the current pendingLineFragment were already fed. */
+    private irFedFragmentLen;
+    /** Final envelope of the region being closed — consumed by the complete emit. */
+    private irEnvelope;
+    /**
+     * True only between seeing a LITERAL closing fence line and the block's
+     * emit (set in the code_fence close branch). Stream-death finalize never
+     * sets it, so the fence-surface convergence hook fires exclusively on
+     * genuinely completed fence regions.
+     */
+    private fenceClosedCleanly;
+    /**
+     * True once a simple-XML region's LITERAL closing tag has been seen — the twin
+     * of `fenceClosedCleanly`. Never set by stream-death `finalize()`, so a
+     * truncated region keeps today's legacy rendering (no envelope).
+     *
+     * MUST NOT be re-derived by scanning `currentBlockContent` for the closing
+     * tag: the accumulator STRIPS the literal tag text out of a simple-XML
+     * block's content (so `</reasoning>` can't leak into visible chat), which
+     * silently killed the XML keystone once already. The state machine already
+     * knows when the region closed; ask it, don't re-parse its output.
+     */
+    private xmlClosedCleanly;
+    /**
+     * True while the OPEN ir region is the JSON BODY of an attribute-XML block
+     * (`<artifact …>{"__kind":…}</artifact>`) rather than a block that IS the
+     * JSON region. Two consequences, both required:
+     *
+     *  - the parity check is skipped — it compares the envelope against
+     *    `JSON.parse(currentBlockContent)`, and an attr-XML block's content is
+     *    the tag chrome PLUS the body, which never parses as JSON. Without this
+     *    every wrapped payload would fire a false "stream parity" alarm.
+     *  - the fragment feed stays off the closing-tag line (see `ingest`).
+     */
+    private irRegionIsXmlBody;
+    /** Every session identity opened during this stream (disposed at finalize). */
+    private irIdentities;
+    /**
+     * True only for the closeCurrentBlock call that closes the FIRST HALF of a
+     * region split by a tool boundary (breakTextBlock keeps the region open in
+     * a fresh block). Metadata built during that close must not report
+     * `isComplete: true` — the region genuinely continues.
+     */
+    private regionContinuesAfterClose;
+    private upsertAction;
+    /** Same-line remainders are queued, never recursively reclassified. */
+    private lineQueue;
+    /**
+     * The current line held a kind object that broke into prose
+     * (`{"__kind":"note","title":"Hi" and then…`, L-4 round 9): it is prose to
+     * its end — no opener re-reads it as JSON — and the prose leaf reads the
+     * broken object as its one-line label, exactly as a reload does.
+     */
+    private kindLineIsProse;
+    private isProcessingLineQueue;
+    /** Incomplete generic XML must never promote embedded JSON on finalize. */
+    private genericXmlRecoverySuppressed;
+    /**
+     * The unused text slot opened after a clean container close is omitted.
+     *
+     * A completed bare JSON root opens a fresh text slot so subsequent source
+     * can continue in document order. If the stream ends there, emitting that
+     * slot creates a second, empty terminal block after the actual answer.
+     */
+    private suppressEmptyTrailingSlot;
+    /** Lifts JSON regions out of blockquotes before the line machine (V1). */
+    private quoteLift;
+    /** Un-escapes a markdown-escaped kind (`"\_\_kind"`) before the quote lift (P8). */
+    private kindUnescape;
+    /** Drops the `![`…`](url)` wrapper of a kind written as image alt text (P9). */
+    private imageAlt;
+    constructor(requestId: string, upsertAction: (payload: {
+        requestId: string;
+        block: RenderBlockPayload;
+    }) => unknown);
+    /**
+     * Ingest a text delta (the rAF-batched textBuffer content).
+     * Processes only complete lines; the trailing fragment is held until the
+     * next call or finalize().
+     */
     ingest(delta: string, dispatch: DispatchFn): void;
-    /** The stream ended: every block becomes complete. Called once after the stream loop. */
+    /** Release what the quote lift still holds (stream end or a hard boundary). */
+    private flushQuoteLift;
+    private ingestText;
+    /**
+     * Flush remaining content and mark the final block as complete.
+     * Called once after the stream loop ends.
+     */
     finalize(dispatch: DispatchFn): void;
     /**
-     * The source bytes behind every live A7 wrapper split. The splitter's reading of the stored
-     * text is the reading every surface draws, so no live block stands for bytes it does not hold.
+     * Forget every in-flight parser/block byte at and after a durable content
+     * boundary. Redux owns removal of the already-dispatched suffix; this resets
+     * the local streaming state so the replacement provider attempt cannot
+     * concatenate onto or resurrect the failed attempt.
      */
+    /** The source bytes behind every live A7 wrapper split (see `wrapperSplits`). */
     getWrapperSplitSources(): Array<{
         blockIds: string[];
         source: string;
     }>;
-    /**
-     * Forget every in-flight byte at and after a durable content boundary (a provider retry).
-     * Redux owns removal of the already-dispatched suffix; the replacement attempt starts a fresh
-     * run at `blockCount`.
-     */
     rewindToBlockCount(blockCount: number): void;
     /**
-     * Close the current text run at an interleaved-content boundary (a tool call between two text
-     * runs): the next text opens fresh blocks after this run's, so "text → tool → text" keeps its
-     * chronological order. Reload splits each run's stored text on its own, and so does this.
-     * A no-op when nothing is open.
+     * Close the current text block at an interleaved-content boundary — a tool
+     * call that lands BETWEEN two text runs. The NEXT text run then opens a
+     * FRESH render block instead of appending onto the block that held the text
+     * BEFORE the tool.
+     *
+     * Why this exists: the accumulator lives for the whole stream and is never
+     * otherwise told about tool calls. Without this break, "text → tool → text"
+     * collapses both runs into a single `client_block_N`. The timeline still
+     * records a `text_end` for the second run, but its
+     * `[blockStartIndex, blockEndIndex)` range comes out EMPTY (no new blockId
+     * was pushed), so `selectUnifiedSlots` emits `[merged_text, tool]` — the
+     * tool card renders AFTER all the text, destroying chronological order.
+     * (The persisted/DB path is unaffected because it rebuilds each run's text
+     * from `text_end.rawText`, which is why a reload renders correctly.)
+     *
+     * Call this once per tool event, BEFORE the tool's `appendTimeline` dispatch
+     * and AFTER the pre-tool text has been flushed into the accumulator
+     * (process-stream's `dispatchBatch()` does that flush). It is a no-op when
+     * there is nothing open to break (back-to-back tool events, a tool with no
+     * preceding text, a tool right after a media block), so it is always safe.
      */
     breakTextBlock(dispatch: DispatchFn): void;
-    private endRun;
-    private sync;
-    private metadataFor;
-    /** Feed the open region's new bytes; reopen when the block is a different region. */
-    private feedRegion;
-    private openRegion;
-    /** End the open region; its final envelope is kept for the block it belongs to. */
-    private closeRegion;
-    private dropRegion;
-    private disposeAll;
-    /** `{` (or `[{`) with no key yet may become a JSON region next frame: draw nothing yet. */
-    private holdsNascentJson;
-    private frontMatterStillOpen;
-    private emit;
-    /** `data` as the renderer has always read it: a code block's language, a media block's link. */
-    private dataFor;
-    private signatureOf;
-    private retract;
+    private orphanReasoningCloseReported;
+    private unclosedReasoningReported;
+    private reportOrphanReasoningClose;
     private reportUnclosedReasoningRegion;
+    private get currentBlockId();
+    private processLine;
+    /** The open bare-JSON region on this line is prose after all: drop its parse, keep its block as text. */
+    private demoteKindLineToProse;
+    /** Process queued lines in order (re-entrant calls return; the outer loop drains). */
+    private drainLineQueue;
+    /** Lines this accumulator has read (the first may open front matter). */
+    private linesRead;
+    private processLineNow;
+    /** Set while the next bare-JSON region opens as an array element (A6). */
+    private nextBareJsonInArray;
+    /** Set while the next bare-JSON region is a kind split out of a section (A8). */
+    private nextBareJsonResumeXml;
+    /** True while a split kind's earlier lines replay into its region (the XML tracker already saw them). */
+    private replayingSplitKind;
+    /**
+     * Track a JSON object inside a simple XML section; split it out the moment
+     * it carries a `__kind` key (A8). `line` is the section body part of a
+     * line. Returns true when the line was consumed by the split.
+     */
+    private trackXmlKindCandidate;
+    /**
+     * Close the section's part before the kind (trimmed, like the reload's
+     * piece), then replay the kind's lines so far as a bare-JSON region that
+     * resumes the section when it balances (A8).
+     */
+    private splitKindOutOfXmlSection;
+    /** The section a kind was split out of continues in a fresh block (A8). */
+    private resumeXmlSection;
+    /**
+     * Track a JSON object or JSON-family fence inside a generic XML container
+     * (an XML TAG — structure, ruling (b), round 3); split it out the moment its
+     * text carries a `__kind` key (X1). Returns true when the line was consumed.
+     */
+    private trackGenericXmlKindCandidate;
+    /**
+     * Close the XML card's part before the kind, then replay the kind's lines
+     * so far as its own region (bare JSON or the JSON fence) that resumes the
+     * container when it closes (X1). The reload's recovery splits the same bytes.
+     */
+    private splitKindOutOfGenericXml;
+    /** The fragment twin of the generic-XML split (X1): `<output>\n{"__kind":…` with no newline yet. */
+    private maybeSplitKindFromGenericXmlFragment;
+    /**
+     * The fragment twin of the section split: a newline-less kind object inside
+     * a simple section (`<info>{"__kind":…`) leaves it as soon as `__kind` is
+     * visible, and the fragment opens the region below (A8).
+     */
+    private maybeSplitKindFromXmlFragment;
+    /**
+     * The held array start is a kind array: close the prose before it, drop the
+     * `[`, and replay the held lines as array content (A6).
+     */
+    private commitKindArray;
+    /** Not a kind array after all: the held lines are ordinary lines, in order. */
+    private releaseHeldArray;
+    /**
+     * Array content between (or opening) elements: `,` and whitespace are
+     * chrome, `]` ends the array, `{` opens the next element as its own
+     * bare-JSON region. Anything else ends the array as ordinary source.
+     */
+    private continueKindArray;
+    /**
+     * The fragment twin of the array entry in processLineNow: a newline-less
+     * `[{"__kind":…` decides on its first key while it streams (A6).
+     */
+    private maybeEnterKindArrayFromFragment;
+    /** The fragment twin of the complete-line split in processLineNow (A5). */
+    private maybeSplitProseBeforeKindFragment;
+    /**
+     * Open a bare_json region directly from the trailing line fragment — the
+     * newline-less minified JSON case (`{"__kind":…}` streamed as one line with
+     * no `\n` until the end). Without this, processLine (which only sees COMPLETE
+     * lines) never opens the region and the raw JSON projects as a text block
+     * until finalize — the "shows the whole JSON, converts only when done" bug.
+     *
+     * Mirrors processLine's bare-JSON branch but fragment-driven: it commits the
+     * moment the fragment reveals `{ "key":` (unambiguous JSON), retracting the
+     * speculative text projection of those same chars, and lets the existing
+     * fragment-feed path (in ingest) and finalize/newline completion carry the
+     * region the rest of the way. openBraces/closeBraces start at 0 — the
+     * completing line counts them exactly once (see the bare_json substate case).
+     */
+    private maybeOpenBareJsonFromFragment;
+    private processSubStateLine;
+    private openXmlTagBlock;
+    private irOpenRegion;
+    /**
+     * Feed region text. `part` is either the unfed remainder of a completing
+     * line (isLineComplete) or a pendingLineFragment delta (streaming chars of
+     * a line that hasn't finished — how minified single-line JSON gets live
+     * parsing instead of waiting for a newline).
+     */
+    private irWriteLinePart;
+    /** Complete a region line, accounting for any fragment chars already fed. */
+    private irFeedLine;
+    /** End the open region: final envelope + shadow parity telemetry. */
+    private irCloseRegion;
+    /**
+     * Open an ir region for the JSON BODY of an attribute-XML block.
+     *
+     * THE WRAPPED-PAYLOAD CLASS. A structured-output agent whose answer is
+     * wrapped by the artifact system arrives as
+     *
+     *     <artifact type="flashcards" id="…" title="…">
+     *     {"__kind":"flashcard_set","cards":[…]}
+     *     </artifact>
+     *
+     * The accumulator opens ir regions for fences and for bare JSON, but an
+     * attr-XML region swallowed every body line whole — no region, no
+     * `metadata.__ir`, so `selectKindEnvelope` answered null for the entire run
+     * AND after it. Every surface reading the envelope (the flashcard
+     * card-by-card preview, D170's `<image_prompt>` step) therefore showed a
+     * spinner over a stream that was arriving perfectly. The wrapper is not the
+     * payload: parse the body exactly as a bare JSON region.
+     *
+     * Rendering is deliberately UNCHANGED — the artifact block keeps the
+     * artifact renderer (kind-route.ts refuses to re-type an artifact); the
+     * envelope is attached for selectors, which is what was missing.
+     *
+     * `part` is a whole body line (isLineComplete) or the streaming fragment of
+     * one, so a minified single-line body parses live instead of at the close.
+     */
+    private maybeOpenXmlBodyIrRegion;
+    private irParityCheck;
+    /** Dispose all sessions this stream opened (finalize-time cleanup). */
+    private irDisposeAll;
+    private appendToCurrentBlock;
+    private closeCurrentBlock;
+    /**
+     * A surrounding Markdown/code/XML classification never outranks an inner
+     * complete object carrying `__kind`. Replace the formerly monolithic Redux
+     * block with lossless container fragments plus independently routable JSON
+     * blocks. The first fragment reuses the already-streamed block id; later
+     * fragments take consecutive ids, so the next ordinary openBlock continues
+     * at the correct document position.
+     */
+    private emitRecoveredEmbeddedKindBlocks;
+    /**
+     * Overwrites the block at the current index with an empty, completed payload
+     * so a previously-projected speculative streaming block is removed from the
+     * rendered output. Keyed by `currentBlockId`, so it replaces the exact
+     * Redux entry the speculative projection created.
+     */
+    private retractCurrentBlock;
+    private openBlock;
+    private emitCurrentBlock;
+    /**
+     * Builds metadata for the block currently being emitted.
+     *
+     * Critical for attribute-XML tags (`<decision>`, `<artifact>`, `<editor_*>`):
+     * BlockRenderer reads `metadata.decision` / `metadata.artifactId` /
+     * `metadata.rawXml` etc. and falls back to raw-markdown rendering when those
+     * are missing — which is exactly the bug we're fixing (decision tags
+     * appearing as plain text mid-stream because metadata was hard-coded to
+     * `undefined` here previously).
+     *
+     * For simple XML tags we emit `{ isComplete, rawXml }` so consumers (loaders,
+     * inline-edit flows) can both gate on completion and round-trip the source.
+     */
+    private buildBlockMetadata;
+    private buildXmlBlockMetadata;
+    private buildBlockData;
 }
 export {};