@nanobpm/nano-workforce 0.185.1 → 0.186.0

package/app/agentic/cockpit/transcript-derive.ts

@@ -1,30 +1,53 @@
-// The cockpit STRUCTURED transcript view — derived from the one event fold (ADR 0056, #251).
+// The cockpit STRUCTURED transcript view — derived from the one ORDERED DISPLAY projection (#566, #757).
 //
 // Beside the byte-level replay (`transcript-render.ts` feeds stored chunks through the live terminal
-// renderer for pixel-faithful playback), the cockpit can also show a STRUCTURED view of a captured
-// session: its derived message history, tool cards and per-turn boundaries. Per the issue's acceptance
-// criterion, that structured view is a DERIVATION of the one typed event log — it re-parses nothing.
-// It reads a fetched transcript page and folds it through the single {@link deriveViewFromChunks} entry
-// point (which routes every chunk through the ONE parser, `parseTranscriptEvent`), so there is no
-// second parser of the raw bytes. The drift-guard test enforces that this module never parses chunks
-// itself.
+// renderer for pixel-faithful playback), the cockpit shows a STRUCTURED view of a captured session. That
+// view is a DERIVATION of the one typed event log — it re-parses nothing. It folds the stored chunks
+// through the single {@link parseTranscriptEvent} parser and the canonical ORDERED DISPLAY projection
+// ({@link createDisplayProjection}, agentic #566): the projection coalesces transport-fragmented message
+// deltas ("I", "not", "ice I am act", …) back into ONE growing block per logical message, and interleaves
+// text blocks, tool cards and permission prompts in strict chronological (offset) order. So a split word
+// reconstructs into exactly that word in one coherent block — never one bordered card per delta — and a
+// tool call issued mid-message renders between the text before and after it (issue #757). The raw log,
+// its offsets and byte-faithful replay are untouched; the drift-guard test enforces this module never
+// parses chunks itself.
 //
-// Framework-free and side-effect-free, like the sibling cockpit views: the same report always yields
-// the same {@link DerivedView}, and the renderer draws into the injected {@link DocumentLike} subset so
-// a real DOM satisfies it at runtime and an in-memory fake satisfies it for DOM-free Node tests.
+// INCREMENTAL, not rebuild-on-every-chunk. {@link createIncrementalTranscript} keeps the display
+// projection and a `blockId → DOM node` map as mutable state, so a live delta updates the ONE active
+// block's node in place (append a new node, or patch an existing one) instead of rebuilding the whole
+// transcript tree. That is what lets the browser adapter (`pages/cockpit/mount.js`) preserve the
+// operator's selection, expansion and scroll position and auto-follow only at the tail. {@link
+// renderDerivedTranscript} is the pure batch convenience over the same fold — historical replay renders
+// IDENTICALLY to the final live rendering because both drive the one incremental renderer.
+//
+// Framework-free and DOM-agnostic, like the sibling cockpit views: it draws into the injected {@link
+// DocumentLike} subset so a real DOM satisfies it at runtime and an in-memory fake satisfies it for
+// DOM-free Node tests.
 import type { DocumentLike, ElementLike } from "@nanobpm/agentic/cockpit";
+import { createDisplayProjection } from "../transcript-display.ts";
 import {
   type DerivedPermission,
   type DerivedTool,
   type DerivedView,
+  type DisplayBlock,
+  type DisplayGapBlock,
+  type DisplayProjection,
+  type DisplayTextBlock,
   deriveViewFromChunks,
   optionKindAllows,
+  parseTranscriptEvent,
+  type StoredChunk,
+  type TranscriptEvent,
+  utf8ByteLength,
 } from "../transcript-events.ts";
 import type { TranscriptDataReport } from "./transcript-render.ts";
 
 /**
- * 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: TranscriptDataReport): DerivedView {
   return deriveViewFromChunks(data.entries);
@@ -156,9 +179,11 @@ function detectDiff(tool: DerivedTool): DetectedDiff | undefined {
   return undefined;
 }
 
-/** Render one tool card: name, status, args + result content, and a distinguishable diff block. */
-function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
-  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: ElementLike, doc: DocumentLike, tool: DerivedTool): void {
+  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");
@@ -195,6 +220,12 @@ function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
     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: DocumentLike, tool: DerivedTool): ElementLike {
+  const card = el(doc, "div", "cockpit-transcript-tool");
+  applyTool(card, doc, tool);
   return card;
 }
 
@@ -204,8 +235,8 @@ function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
  * - 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: DocumentLike, perm: DerivedPermission, options: RenderDerivedTranscriptOptions): ElementLike {
-  const card = el(doc, "div", "cockpit-transcript-permission");
+function applyPermission(card: ElementLike, doc: DocumentLike, perm: DerivedPermission, options: RenderDerivedTranscriptOptions): void {
+  card.replaceChildren();
   card.setAttribute("data-permission", "request");
   card.setAttribute("data-policy", perm.policy);
   card.setAttribute("data-call-id", perm.callId);
@@ -222,14 +253,14 @@ function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: R
     settled.setAttribute("data-chosen-option", perm.resolved.optionId);
     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.
@@ -249,65 +280,268 @@ function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: R
     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: DocumentLike, perm: DerivedPermission, options: RenderDerivedTranscriptOptions): ElementLike {
+  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: ElementLike, block: DisplayTextBlock): void {
+  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: DocumentLike, block: DisplayTextBlock): ElementLike {
+  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: ElementLike, block: DisplayGapBlock): void {
+  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: DocumentLike, block: DisplayGapBlock): ElementLike {
+  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: DocumentLike, block: DisplayBlock, options: RenderDerivedTranscriptOptions): ElementLike {
+  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: ElementLike, doc: DocumentLike, block: DisplayBlock, options: RenderDerivedTranscriptOptions): void {
+  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.
+ * A STATEFUL, incremental transcript renderer over a `host` element. It maintains the ordered
+ * {@link DisplayBlock} sequence (via the canonical {@link createDisplayProjection}) and a `blockId → DOM
+ * node` map, so feeding it one live chunk at a time updates just the ONE touched block's node in place —
+ * append a brand-new block node, or patch an existing block's node (a growing text delta, a tool result
+ * pairing, a permission resolution, or a now-anchored gap) — instead of rebuilding the whole transcript
+ * tree. That bounded update is what lets the browser adapter preserve selection, expansion and scroll.
+ *
+ * DOM shape (stable across live growth so unaffected nodes are never replaced):
+ *   div.cockpit-transcript-derived[data-*]
+ *     div.cockpit-transcript-blocks   ← ordered block nodes are appended here / patched in place
+ *     div.cockpit-transcript-empty    ← shown (data-empty="true") only while there are zero blocks
+ *     footer.cockpit-transcript-raw   ← retained raw bytes/chunks (byte-replay is preserved alongside)
  */
-export function renderDerivedTranscript(
+export interface IncrementalTranscript {
+  /** The rendered root (a `cockpit-transcript-derived` element) appended under the host. */
+  readonly root: ElementLike;
+  /**
+   * Fold ONE stored chunk (by offset) into the display and update the DOM minimally. Idempotent on
+   * offset — re-feeding an already-applied offset (reconnect, pagination overlap, a duplicated chunk) is
+   * a no-op, so replayed text never doubles. Feed chunks in offset order (the projection drops a late
+   * lower offset rather than merging it out of place).
+   */
+  applyChunk(chunk: StoredChunk): void;
+  /**
+   * Record a retention gap at the current tail BEFORE feeding the post-gap chunks: the consumer resumed
+   * from an offset older than the oldest retained chunk, so what follows is NOT continuous with what
+   * precedes. Renders a visible break; its `beforeOffset` is anchored when the next block opens.
+   */
+  noteGap(): void;
+  /** A snapshot of the ordered display blocks as they stand now (for tests/inspection). */
+  blocks(): readonly DisplayBlock[];
+}
+
+/** Running summary tallies for the root attributes + raw footer, maintained WITHOUT re-folding. */
+interface Tallies {
+  text: number;
+  tool: number;
+  permission: number;
+  gap: number;
+  turns: number;
+  rawBytes: number;
+  rawChunks: number;
+  lifecycle: "open" | "completed" | "exited";
+}
+
+/**
+ * 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 createIncrementalTranscript(
   host: ElementLike,
   doc: DocumentLike,
-  data: TranscriptDataReport,
+  stream: string,
   options: RenderDerivedTranscriptOptions = {},
-): DerivedTranscriptDom {
-  const view = deriveTranscript(data);
+): IncrementalTranscript {
   host.replaceChildren();
+  const projection: DisplayProjection = createDisplayProjection();
+  const nodes = new Map<string, ElementLike>();
+  const tallies: 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(): void {
+    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: DisplayBlock): void {
+    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: DisplayBlock | undefined, appended: boolean, anchored: DisplayBlock | undefined): void {
+    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: TranscriptEvent): void {
+    // 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);
+  refreshSummary();
 
-  host.appendChild(root);
-  return { root };
+  return {
+    root,
+    applyChunk(chunk: StoredChunk): void {
+      applyEvent(parseTranscriptEvent(chunk));
+      refreshSummary();
+    },
+    noteGap(): void {
+      const result = projection.noteGap();
+      reconcile(result.changed, result.appended, result.anchored);
+      refreshSummary();
+    },
+    blocks(): readonly DisplayBlock[] {
+      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: ElementLike,
+  doc: DocumentLike,
+  data: TranscriptDataReport,
+  options: RenderDerivedTranscriptOptions = {},
+): DerivedTranscriptDom {
+  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/app/agentic/transcript-display.ts

@@ -0,0 +1,17 @@
+// nano-workforce — the ordered DISPLAY projection, DERIVED from its one owner (agentic #566).
+//
+// Sibling of `transcript-events.ts`: where that barrel re-exports the transcript EVENT grammar (the one
+// parser + fold), THIS barrel re-exports the canonical ordered DISPLAY derivation — the projection that
+// coalesces transport-fragmented message deltas back into logical blocks and interleaves them
+// chronologically with tool cards and permission prompts (`createDisplayProjection` / `deriveDisplay`).
+// The cockpit renders THIS instead of the raw per-event groups, so a split word reconstructs into one
+// block and text/tool/permission order never scrambles.
+//
+// Why a SEPARATE barrel rather than folding these into `transcript-events.ts`: the browser bundle
+// (`scripts/build-cockpit-browser.ts`) emits one generated ESM sibling per agentic source module, and
+// the display projection lives in agentic's own `dist/transcript/display.js` — a self-contained,
+// browser-safe module distinct from `events.js`. Keeping the display import on its own specifier lets
+// the bundle rewrite it to `./transcript-display.js` (agentic's display module) while the event import
+// still rewrites to `./transcript-events.js`. Both remain thin re-exports of the ONE agentic source of
+// truth — there is no local display algorithm here (Derivation Over Duplication).
+export { createDisplayProjection, deriveDisplay } from "@nanobpm/agentic/transcript";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.185.1",
+  "version": "0.186.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -64,7 +64,7 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/agentic": "^0.13.0",
+    "@nanobpm/agentic": "^0.14.0",
     "@nanobpm/urban": "^0.93.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },