@nanobpm/nano-workforce 0.185.1 → 0.186.0

package/pages/cockpit/generated/transcript-derive.js

@@ -4,10 +4,14 @@
 // renders the agentic transcript from ONE source of truth (#660). Regenerate with:
 //   node --experimental-strip-types scripts/build-cockpit-browser.ts
 
-import { deriveViewFromChunks, optionKindAllows, } from "./transcript-events.js";
+import { createDisplayProjection } from "./transcript-display.js";
+import { deriveViewFromChunks, optionKindAllows, parseTranscriptEvent, utf8ByteLength, } from "./transcript-events.js";
 /**
- * Derive the structured view of a fetched transcript page by folding its stored chunks through the ONE
- * event parser + fold. Pure: the cockpit reads THIS instead of re-parsing raw frame bytes.
+ * Derive the structured (event-fold) view of a fetched transcript page — the flat message/tool/permission
+ * history, per-turn structure and raw-byte accounting. This is the {@link DerivedView} fold, kept for the
+ * raw-fidelity footer and summary counts; the ordered, human-facing block SEQUENCE is the separate
+ * display projection {@link renderDerivedTranscript} draws. Pure: the cockpit reads THESE instead of
+ * re-parsing raw frame bytes.
  */
 export function deriveTranscript(data) {
     return deriveViewFromChunks(data.entries);
@@ -116,9 +120,11 @@ function detectDiff(tool) {
         return { lines: structured, source: "args" };
     return undefined;
 }
-/** Render one tool card: name, status, args + result content, and a distinguishable diff block. */
-function renderTool(doc, tool) {
-    const card = el(doc, "div", "cockpit-transcript-tool");
+/** Fill an EXISTING tool card node with one tool's content (name, status, args/result, diff block). Clears
+ *  the node first so it is safe to re-invoke in place when the tool's result later arrives (bounded to
+ *  this one card — no sibling block is touched). */
+function applyTool(card, doc, tool) {
+    card.replaceChildren();
     card.setAttribute("data-tool", tool.name);
     card.setAttribute("data-offset", String(tool.offset));
     card.setAttribute("data-status", tool.result === undefined ? "pending" : tool.result.ok ? "ok" : "error");
@@ -152,6 +158,11 @@ function renderTool(doc, tool) {
         resEl.setAttribute("data-tool-result", "true");
         card.appendChild(resEl);
     }
+}
+/** Render one tool card: name, status, args + result content, and a distinguishable diff block. */
+function renderTool(doc, tool) {
+    const card = el(doc, "div", "cockpit-transcript-tool");
+    applyTool(card, doc, tool);
     return card;
 }
 /**
@@ -160,8 +171,8 @@ function renderTool(doc, tool) {
  * - a `yolo` request → informational only (yolo auto-allows, it never prompts a human);
  * - a resolved permission → settled (`allowed`/`denied`), showing the chosen option, no live buttons.
  */
-function renderPermission(doc, perm, options) {
-    const card = el(doc, "div", "cockpit-transcript-permission");
+function applyPermission(card, doc, perm, options) {
+    card.replaceChildren();
     card.setAttribute("data-permission", "request");
     card.setAttribute("data-policy", perm.policy);
     card.setAttribute("data-call-id", perm.callId);
@@ -181,13 +192,13 @@ function renderPermission(doc, perm, options) {
         if (perm.resolved.by !== undefined)
             settled.setAttribute("data-by", perm.resolved.by);
         card.appendChild(settled);
-        return card;
+        return;
     }
     if (perm.policy === "yolo") {
         // Informational: yolo auto-allows and never prompts a human, so no Allow/Deny buttons.
         card.setAttribute("data-status", "auto");
         card.appendChild(el(doc, "div", "cockpit-transcript-permission-note", "Auto-allowed (yolo) — no operator prompt."));
-        return card;
+        return;
     }
     // Pending escalate: one interactive button per offered option, wired to the resolve seam.
     card.setAttribute("data-status", "pending");
@@ -206,55 +217,207 @@ function renderPermission(doc, perm, options) {
         actions.appendChild(button);
     }
     card.appendChild(actions);
+}
+/**
+ * Render one permission prompt card from a {@link DerivedPermission}:
+ * - a pending `escalate` request → interactive Allow/Deny buttons wired to `onPermissionResolve`;
+ * - a `yolo` request → informational only (yolo auto-allows, it never prompts a human);
+ * - a resolved permission → settled (`allowed`/`denied`), showing the chosen option, no live buttons.
+ */
+function renderPermission(doc, perm, options) {
+    const card = el(doc, "div", "cockpit-transcript-permission");
+    applyPermission(card, doc, perm, options);
     return card;
 }
+/** Fill an EXISTING text-block node with a coalesced message's text + offsets. The block is ONE growing
+ *  node per logical message — a delta patches this node's `textContent` in place (never a new card per
+ *  fragment), so a split word reconstructs into exactly that word. */
+function applyText(node, block) {
+    node.setAttribute("data-role", block.role);
+    node.setAttribute("data-offset", String(block.startOffset));
+    node.setAttribute("data-end-offset", String(block.endOffset));
+    node.setAttribute("data-block-id", block.id);
+    if (block.messageId !== undefined)
+        node.setAttribute("data-message-id", block.messageId);
+    node.setAttribute("data-complete", String(block.complete));
+    node.textContent = block.text;
+}
+/** Render one coalesced-message text block (a single growing node). */
+function renderText(doc, block) {
+    const node = el(doc, "div", "cockpit-transcript-message");
+    applyText(node, block);
+    return node;
+}
+/** Fill an EXISTING retention-gap node. A gap is a first-class visible break so a reattach that dropped
+ *  chunks never implies the surrounding text is continuous; its `beforeOffset` is anchored once the first
+ *  post-gap block opens. */
+function applyGap(node, block) {
+    node.setAttribute("data-gap", "true");
+    node.setAttribute("data-block-id", block.id);
+    if (block.beforeOffset !== undefined)
+        node.setAttribute("data-before-offset", String(block.beforeOffset));
+    node.textContent = "⋯ retained-data gap — earlier output was evicted ⋯";
+}
+/** Render one retention-gap block. */
+function renderGap(doc, block) {
+    const node = el(doc, "div", "cockpit-transcript-gap");
+    applyGap(node, block);
+    return node;
+}
+/** Build a fresh DOM node for any display block kind. */
+function renderBlock(doc, block, options) {
+    switch (block.kind) {
+        case "text":
+            return renderText(doc, block);
+        case "tool":
+            return renderTool(doc, block.tool);
+        case "permission":
+            return renderPermission(doc, block.permission, options);
+        case "gap":
+            return renderGap(doc, block);
+    }
+}
+/** Patch an EXISTING block node in place (bounded to that one block — no sibling node is touched). */
+function patchBlock(node, doc, block, options) {
+    switch (block.kind) {
+        case "text":
+            applyText(node, block);
+            return;
+        case "tool":
+            applyTool(node, doc, block.tool);
+            return;
+        case "permission":
+            applyPermission(node, doc, block.permission, options);
+            return;
+        case "gap":
+            applyGap(node, block);
+            return;
+    }
+}
 /**
- * Render the DERIVED structured view of a fetched transcript into `host`, replacing whatever was there.
- * Draws per-turn sections with their derived messages, rich tool/diff cards and permission prompts, plus
- * a raw-fidelity footer (retained bytes/chunks) so the operator sees the byte-replay is preserved
- * alongside the structure. Idempotent — call again on each refresh. Everything it shows is a derivation
- * of the one event log. `options.onPermissionResolve`, when provided, is invoked by a pending
- * escalate-permission prompt's Allow/Deny buttons.
+ * Build the incremental renderer's stable DOM scaffold under `host` and return the mutable render state.
+ * Shared by {@link createIncrementalTranscript} (live) and {@link renderDerivedTranscript} (batch) so
+ * historical replay renders IDENTICALLY to the final live rendering.
  */
-export function renderDerivedTranscript(host, doc, data, options = {}) {
-    const view = deriveTranscript(data);
+export function createIncrementalTranscript(host, doc, stream, options = {}) {
     host.replaceChildren();
+    const projection = createDisplayProjection();
+    const nodes = new Map();
+    const tallies = { text: 0, tool: 0, permission: 0, gap: 0, turns: 0, rawBytes: 0, rawChunks: 0, lifecycle: "open" };
+    // A turn opens implicitly before the first structured block even without an explicit `turn` event
+    // (mirrors deriveView's implicit turn 0), so any structured content means at least one turn.
+    let structured = false;
     const root = el(doc, "div", "cockpit-transcript-derived");
-    root.setAttribute("data-stream", data.stream);
-    root.setAttribute("data-lifecycle", view.lifecycle);
-    root.setAttribute("data-turn-count", String(view.turns.length));
-    root.setAttribute("data-message-count", String(view.messages.length));
-    root.setAttribute("data-tool-count", String(view.tools.length));
-    root.setAttribute("data-permission-count", String(view.permissions.length));
-    if (view.turns.length === 0) {
-        const empty = el(doc, "div", "cockpit-transcript-empty", "No structured events derived — raw replay only.");
-        empty.setAttribute("data-empty", "true");
-        root.appendChild(empty);
+    root.setAttribute("data-stream", stream);
+    const blocksHost = el(doc, "div", "cockpit-transcript-blocks");
+    const empty = el(doc, "div", "cockpit-transcript-empty");
+    const footer = el(doc, "footer", "cockpit-transcript-raw");
+    root.appendChild(blocksHost);
+    root.appendChild(empty);
+    root.appendChild(footer);
+    host.appendChild(root);
+    function refreshSummary() {
+        const turnCount = tallies.turns > 0 ? tallies.turns : structured ? 1 : 0;
+        root.setAttribute("data-lifecycle", tallies.lifecycle);
+        root.setAttribute("data-turn-count", String(turnCount));
+        root.setAttribute("data-message-count", String(tallies.text));
+        root.setAttribute("data-tool-count", String(tallies.tool));
+        root.setAttribute("data-permission-count", String(tallies.permission));
+        root.setAttribute("data-gap-count", String(tallies.gap));
+        root.setAttribute("data-block-count", String(nodes.size));
+        const hasBlocks = tallies.text + tallies.tool + tallies.permission > 0;
+        // Toggle (never remove — ElementLike has no removeChild) so a live first block clears the empty note
+        // without rebuilding, and an all-raw page still shows exactly one data-empty="true" element.
+        empty.setAttribute("data-empty", String(!hasBlocks));
+        empty.textContent = hasBlocks ? "" : "No structured events derived — raw replay only.";
+        footer.setAttribute("data-raw-bytes", String(tallies.rawBytes));
+        footer.setAttribute("data-raw-chunks", String(tallies.rawChunks));
+        footer.textContent = `${tallies.rawChunks} raw chunk(s) · ${tallies.rawBytes} B retained for replay`;
+    }
+    function countAppended(block) {
+        structured = structured || block.kind !== "gap";
+        if (block.kind === "text")
+            tallies.text++;
+        else if (block.kind === "tool")
+            tallies.tool++;
+        else if (block.kind === "permission")
+            tallies.permission++;
+        else
+            tallies.gap++;
     }
-    for (const turn of view.turns) {
-        const section = el(doc, "section", "cockpit-transcript-turn");
-        section.setAttribute("data-turn", String(turn.index));
-        section.setAttribute("data-steps", String(turn.steps));
-        section.appendChild(el(doc, "h3", "cockpit-transcript-turn-title", `Turn ${turn.index}`));
-        for (const msg of turn.messages) {
-            const row = el(doc, "div", "cockpit-transcript-message", msg.text);
-            row.setAttribute("data-role", msg.role);
-            row.setAttribute("data-offset", String(msg.offset));
-            section.appendChild(row);
+    /** Reconcile ONE projection apply-result into the DOM: append a new node, patch an existing one, and/or
+     *  patch a secondary now-anchored gap. Bounded to the touched block(s) — no unaffected node is replaced. */
+    function reconcile(changed, appended, anchored) {
+        if (changed !== undefined) {
+            if (appended) {
+                const node = renderBlock(doc, changed, options);
+                nodes.set(changed.id, node);
+                blocksHost.appendChild(node);
+                countAppended(changed);
+            }
+            else {
+                const node = nodes.get(changed.id);
+                if (node !== undefined)
+                    patchBlock(node, doc, changed, options);
+            }
         }
-        for (const tool of turn.tools) {
-            section.appendChild(renderTool(doc, tool));
+        if (anchored !== undefined) {
+            const node = nodes.get(anchored.id);
+            if (node !== undefined)
+                patchBlock(node, doc, anchored, options);
         }
-        for (const perm of turn.permissions) {
-            section.appendChild(renderPermission(doc, perm, options));
+    }
+    function applyEvent(event) {
+        // Raw bytes feed the byte-replay footer but produce no display block (the projection ignores them).
+        if (event.kind === "stream-chunk") {
+            tallies.rawChunks++;
+            tallies.rawBytes += utf8ByteLength(event.chunk);
+        }
+        else if (event.kind === "turn") {
+            tallies.turns++;
+        }
+        else if (event.kind === "lifecycle") {
+            tallies.lifecycle = event.phase;
         }
-        root.appendChild(section);
+        const result = projection.apply(event);
+        reconcile(result.changed, result.appended, result.anchored);
     }
-    const footer = el(doc, "footer", "cockpit-transcript-raw");
-    footer.setAttribute("data-raw-bytes", String(view.rawByteLength));
-    footer.setAttribute("data-raw-chunks", String(view.rawChunkCount));
-    footer.textContent = `${view.rawChunkCount} raw chunk(s) · ${view.rawByteLength} B retained for replay`;
-    root.appendChild(footer);
-    host.appendChild(root);
-    return { root };
+    refreshSummary();
+    return {
+        root,
+        applyChunk(chunk) {
+            applyEvent(parseTranscriptEvent(chunk));
+            refreshSummary();
+        },
+        noteGap() {
+            const result = projection.noteGap();
+            reconcile(result.changed, result.appended, result.anchored);
+            refreshSummary();
+        },
+        blocks() {
+            return projection.blocks();
+        },
+    };
+}
+/**
+ * Render the DERIVED, ORDERED display of a fetched transcript page into `host`, replacing whatever was
+ * there — the pure BATCH convenience over {@link createIncrementalTranscript}. Draws one growing text
+ * block per logical message, with tool/diff cards and permission prompts interleaved in chronological
+ * (offset) order, plus a raw-fidelity footer (retained bytes/chunks) so the byte-replay stays visibly
+ * preserved. A retention `gap` on the page (`data.gap`) renders a leading visible break. Idempotent —
+ * call again on each refresh. Everything it shows is a derivation of the one event log, and it renders
+ * IDENTICALLY to the final live rendering (same incremental fold). `options.onPermissionResolve`, when
+ * provided, is invoked by a pending escalate-permission prompt's Allow/Deny buttons.
+ */
+export function renderDerivedTranscript(host, doc, data, options = {}) {
+    const incremental = createIncrementalTranscript(host, doc, data.stream, options);
+    // A page-level retention gap precedes the page's first chunk: note it before folding so a leading
+    // visible break renders (a reattach that dropped chunks never implies false continuity).
+    if (data.gap)
+        incremental.noteGap();
+    // The batch path folds the SAME chunks the live path does, in offset order, through the ONE projection,
+    // so historical and live rendering are byte-for-byte the same tree.
+    for (const chunk of [...data.entries].sort((a, b) => a.offset - b.offset))
+        incremental.applyChunk(chunk);
+    return { root: incremental.root };
 }

package/pages/cockpit/generated/transcript-display.js

@@ -0,0 +1,316 @@
+// @generated from node_modules/@nanobpm/agentic/dist/transcript/display.js by scripts/build-cockpit-browser.ts — DO NOT EDIT.
+//
+// Browser ESM derived (type-strip only) from the typed transcript core so pages/cockpit/mount.js
+// renders the agentic transcript from ONE source of truth (#660). Regenerate with:
+//   node --experimental-strip-types scripts/build-cockpit-browser.ts
+
+const NOOP = Object.freeze({ appended: false });
+/** Recursively freeze a value already owned exclusively by the caller (a fresh clone), so no consumer
+ *  can mutate it at any depth. Idempotent, and a no-op for primitives and already-frozen objects. A
+ *  `seen` set guards against cyclic references so an arbitrarily-shaped `args` payload with a cycle
+ *  freezes without recursing forever. */
+function deepFreeze(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value) || seen.has(value))
+        return;
+    seen.add(value);
+    Object.freeze(value);
+    for (const nested of Object.values(value))
+        deepFreeze(nested, seen);
+}
+/** Decouple a producer-owned, arbitrarily-shaped `args` value from projection state: deep clone it (so
+ *  the returned snapshot shares no mutable reference) then deep-freeze the clone. When `structuredClone`
+ *  is unavailable or `args` is non-cloneable (e.g. it contains functions), fall back to deep-freezing
+ *  `args` *in place* rather than returning it unfrozen: a shared-by-reference fallback would let a
+ *  consumer mutate `tool.args` back into the projection's internals, so freezing the shared object is
+ *  what preserves the "cannot reach back" guarantee even when cloning fails. */
+function freezeArgs(args) {
+    if (args === null || typeof args !== "object")
+        return args;
+    let cloned;
+    try {
+        cloned = structuredClone(args);
+    }
+    catch {
+        deepFreeze(args);
+        return args;
+    }
+    deepFreeze(cloned);
+    return cloned;
+}
+/** Deep-freeze a {@link DerivedTool} into a snapshot decoupled from the projection's mutable internals:
+ *  a shallow clone whose nested `result` is itself cloned + frozen and whose producer-owned `args` is
+ *  deep cloned + frozen ({@link freezeArgs}), so a consumer that mutates the returned `tool` (or
+ *  `tool.result` / `tool.args`) cannot reach back into projection state. */
+function freezeTool(tool) {
+    return Object.freeze({
+        ...tool,
+        ...(tool.args !== undefined ? { args: freezeArgs(tool.args) } : {}),
+        ...(tool.result !== undefined ? { result: Object.freeze({ ...tool.result }) } : {}),
+    });
+}
+/** Deep-freeze a {@link DerivedPermission} into a snapshot decoupled from the projection's mutable
+ *  internals: a shallow clone whose nested `options` (and each option) and `resolved` are cloned +
+ *  frozen, so a consumer cannot mutate projection state through the returned `permission`. */
+function freezePermission(permission) {
+    return Object.freeze({
+        ...permission,
+        options: Object.freeze(permission.options.map((option) => Object.freeze({ ...option }))),
+        ...(permission.resolved !== undefined ? { resolved: Object.freeze({ ...permission.resolved }) } : {}),
+    });
+}
+function freezeBlock(block) {
+    switch (block.kind) {
+        case "text":
+            return Object.freeze({
+                kind: "text",
+                id: `text:${block.startOffset}`,
+                role: block.role,
+                ...(block.messageId !== undefined ? { messageId: block.messageId } : {}),
+                text: block.text,
+                startOffset: block.startOffset,
+                endOffset: block.endOffset,
+                complete: block.complete,
+            });
+        case "tool":
+            return Object.freeze({
+                kind: "tool",
+                id: `tool:${block.startOffset}`,
+                tool: freezeTool(block.tool),
+                startOffset: block.startOffset,
+                endOffset: block.endOffset,
+            });
+        case "permission":
+            return Object.freeze({
+                kind: "permission",
+                id: `permission:${block.startOffset}`,
+                permission: freezePermission(block.permission),
+                startOffset: block.startOffset,
+                endOffset: block.endOffset,
+            });
+        case "gap":
+            return Object.freeze({
+                kind: "gap",
+                id: `gap:${block.ordinal}`,
+                ...(block.beforeOffset !== undefined ? { beforeOffset: block.beforeOffset } : {}),
+            });
+    }
+}
+function toolFromCall(event) {
+    return {
+        name: event.name,
+        offset: event.offset,
+        ...(event.callId !== undefined ? { callId: event.callId } : {}),
+        ...(event.args !== undefined ? { args: event.args } : {}),
+    };
+}
+function toolWithResult(tool, result) {
+    return {
+        ...tool,
+        result: {
+            ok: result.ok,
+            offset: result.offset,
+            ...(result.content !== undefined ? { content: result.content } : {}),
+        },
+    };
+}
+function permissionFromRequest(event) {
+    return {
+        callId: event.callId,
+        policy: event.policy,
+        options: event.options,
+        offset: event.offset,
+        ...(event.toolName !== undefined ? { toolName: event.toolName } : {}),
+        ...(event.title !== undefined ? { title: event.title } : {}),
+        ...(event.reason !== undefined ? { reason: event.reason } : {}),
+    };
+}
+function permissionWithResolution(permission, resolution) {
+    return {
+        ...permission,
+        resolved: {
+            allowed: resolution.allowed,
+            optionId: resolution.optionId,
+            offset: resolution.offset,
+            ...(resolution.by !== undefined ? { by: resolution.by } : {}),
+        },
+    };
+}
+export function createDisplayProjection() {
+    const blocks = [];
+    const openTools = new Map();
+    let anonymousTool;
+    const openPermissions = new Map();
+    // The append-order idempotency key: the highest offset ever folded. Any event at or below it was
+    // already applied (a replayed/duplicated chunk), so it is a no-op — this is what keeps replay,
+    // reconnect and pagination overlap from doubling text. Starts at -1 so offset 0 applies.
+    let lastOffset = -1;
+    // A pending gap awaiting the offset of the next block, so a consumer can anchor the break.
+    let pendingGapBlock;
+    let gapOrdinal = 0;
+    /** The active text block a delta may extend: the LAST block, iff it is an open text block. Any other
+     *  trailing block (a tool card, a permission, a gap) means there is no open text run to coalesce into. */
+    const activeText = () => {
+        const tail = blocks[blocks.length - 1];
+        return tail !== undefined && tail.kind === "text" && !tail.complete ? tail : undefined;
+    };
+    const closeActiveText = () => {
+        const active = activeText();
+        if (active !== undefined)
+            active.complete = true;
+    };
+    /** Anchor a not-yet-anchored gap to the first block that opens after it, returning the now-anchored gap
+     *  (frozen) so the triggering {@link apply} can surface it as {@link DisplayApplyResult.anchored} — else
+     *  `undefined` when there is no pending gap. */
+    const anchorGap = (offset) => {
+        if (pendingGapBlock === undefined)
+            return undefined;
+        pendingGapBlock.beforeOffset = offset;
+        const anchored = freezeBlock(pendingGapBlock);
+        pendingGapBlock = undefined;
+        return anchored;
+    };
+    const applyMessage = (event) => {
+        const active = activeText();
+        // A delta may extend the active block only when it is the SAME speaker AND the SAME logical message
+        // AND the producer did not force a new block with `start`. Message identity: if both sides carry a
+        // `messageId` they must match; a changed id (or one side having an id the other lacks) is a distinct
+        // message. With no ids on either side, the fallback is purely structural — adjacent + same speaker.
+        const idsMatch = event.messageId !== undefined || active?.messageId !== undefined
+            ? event.messageId === active?.messageId
+            : true;
+        const canExtend = active !== undefined && event.start !== true && active.role === event.role && idsMatch;
+        if (canExtend && active !== undefined) {
+            // Snapshot REPLACES the accumulated text; a delta APPENDS exactly (no separator).
+            active.text = event.mode === "snapshot" ? event.text : active.text + event.text;
+            active.endOffset = event.offset;
+            if (event.final === true)
+                active.complete = true;
+            return { changed: freezeBlock(active), appended: false };
+        }
+        // Open a fresh block. (A `start`/id-change/role-change also closes any still-open predecessor so the
+        // next unrelated delta cannot re-open it.)
+        closeActiveText();
+        const anchored = anchorGap(event.offset);
+        const block = {
+            kind: "text",
+            role: event.role,
+            text: event.text,
+            startOffset: event.offset,
+            endOffset: event.offset,
+            complete: event.final === true,
+            ...(event.messageId !== undefined ? { messageId: event.messageId } : {}),
+        };
+        blocks.push(block);
+        return { changed: freezeBlock(block), appended: true, ...(anchored !== undefined ? { anchored } : {}) };
+    };
+    const applyToolCall = (event) => {
+        // A tool call interrupts any running text: it becomes the trailing block, so a later delta opens a
+        // new text block rather than coalescing across the tool.
+        closeActiveText();
+        const anchored = anchorGap(event.offset);
+        const block = {
+            kind: "tool",
+            tool: toolFromCall(event),
+            startOffset: event.offset,
+            endOffset: event.offset,
+        };
+        blocks.push(block);
+        const pending = { block };
+        if (event.callId !== undefined)
+            openTools.set(event.callId, pending);
+        else
+            anonymousTool = pending;
+        return { changed: freezeBlock(block), appended: true, ...(anchored !== undefined ? { anchored } : {}) };
+    };
+    const applyToolResult = (event) => {
+        const pending = event.callId !== undefined ? openTools.get(event.callId) : anonymousTool;
+        if (pending === undefined)
+            return NOOP; // A result with no open call — nothing to pair (never invents a card).
+        pending.block.tool = toolWithResult(pending.block.tool, event);
+        pending.block.endOffset = event.offset;
+        if (event.callId !== undefined)
+            openTools.delete(event.callId);
+        else
+            anonymousTool = undefined;
+        return { changed: freezeBlock(pending.block), appended: false };
+    };
+    const applyPermissionRequest = (event) => {
+        closeActiveText();
+        const anchored = anchorGap(event.offset);
+        const block = {
+            kind: "permission",
+            permission: permissionFromRequest(event),
+            startOffset: event.offset,
+            endOffset: event.offset,
+        };
+        blocks.push(block);
+        openPermissions.set(event.callId, { block });
+        return { changed: freezeBlock(block), appended: true, ...(anchored !== undefined ? { anchored } : {}) };
+    };
+    const applyPermissionResolution = (event) => {
+        const pending = openPermissions.get(event.callId);
+        if (pending === undefined)
+            return NOOP;
+        pending.block.permission = permissionWithResolution(pending.block.permission, event);
+        pending.block.endOffset = event.offset;
+        openPermissions.delete(event.callId);
+        return { changed: freezeBlock(pending.block), appended: false };
+    };
+    const apply = (event) => {
+        // Idempotency gate: this projection requires events in strictly increasing `offset` order, so any
+        // offset at or below the high-water mark is treated as already folded (replay / reconnect /
+        // pagination overlap / a duplicated chunk) and re-applying it must not change anything. A genuinely
+        // out-of-order event (offset <= lastOffset arriving late) is likewise dropped here, not merged — a
+        // caller seeing a "missing" block must re-feed the stream in order rather than read it as deduped.
+        if (event.offset <= lastOffset)
+            return NOOP;
+        lastOffset = event.offset;
+        switch (event.kind) {
+            case "message":
+                return applyMessage(event);
+            case "tool-call":
+                return applyToolCall(event);
+            case "tool-result":
+                return applyToolResult(event);
+            case "permission":
+                return event.phase === "request" ? applyPermissionRequest(event) : applyPermissionResolution(event);
+            case "turn":
+                // An explicit turn boundary closes the running message so the next turn's text starts fresh.
+                closeActiveText();
+                return NOOP;
+            // A `step`, a `lifecycle` transition, and a raw `stream-chunk` do not themselves produce a display
+            // block and do not break text coalescing (raw bytes render on the separate byte-terminal plane).
+            case "step":
+            case "lifecycle":
+            case "stream-chunk":
+                return NOOP;
+        }
+    };
+    return {
+        apply,
+        applyAll(events) {
+            for (const event of events)
+                apply(event);
+        },
+        noteGap() {
+            closeActiveText();
+            const block = { kind: "gap", ordinal: gapOrdinal++ };
+            blocks.push(block);
+            pendingGapBlock = block;
+            return { changed: freezeBlock(block), appended: true };
+        },
+        blocks() {
+            return blocks.map(freezeBlock);
+        },
+    };
+}
+/**
+ * The pure batch convenience: fold a whole run of offset-ordered events into the ordered display blocks
+ * in one call, over a fresh {@link createDisplayProjection}. Duplicate offsets in the input are deduped
+ * by the same idempotency gate, so a replayed slice folds to the same result as a gap-free one.
+ */
+export function deriveDisplay(events) {
+    const projection = createDisplayProjection();
+    projection.applyAll(events);
+    return projection.blocks();
+}