@nanobpm/nano-workforce 0.185.1 → 0.186.1

package/app/pollUserTasks.test.ts

@@ -661,6 +661,62 @@ test("pollUserTasks (engine-first): surfaces an inlined delivery-graph human tas
   assertEquals(byKey["35002"].subject_title, "release runbook");
 });
 
+test("pollUserTasks: a parked delivery-human node carries its instruction as `question` (Decision context, issue #772)", async () => {
+  // The Tasks surface seeds no form variables, so a delivery-graph `human` node's instruction can only
+  // reach the operator through the read-model `question` (rendered as "Decision context"). Source it
+  // from the run's stamped `human_labels`, keyed by the parked user-task element id — else the panel is
+  // blank and the human has no idea what the run is waiting on.
+  const { data, stores } = memData({
+    delivery_graph_runs: [
+      {
+        run_key: "delivery-graph-403eb22e",
+        process_key: "dg-1",
+        status: "running",
+        title: "release runbook",
+        human_labels: JSON.stringify({
+          "delivery-human-task__n7": "Run the manual OTP publish for @nanobpm/urban",
+        }),
+      },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "20411", elementId: "delivery-human-task__n7", processInstanceKey: "dg-1", state: "CREATED" },
+    // the bounded-timeout escalation twin parks on the `…__esc` id but resolves the same base label
+    { userTaskKey: "20412", elementId: "delivery-human-task__n7__esc", processInstanceKey: "dg-1", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(byKey["20411"].question, "Run the manual OTP publish for @nanobpm/urban");
+  assertEquals(byKey["20412"].question, "Run the manual OTP publish for @nanobpm/urban");
+});
+
+test("pollUserTasks: a delivery-human node with no stored label still gets a non-blank Decision context (issue #772)", async () => {
+  // An untracked run (or a run whose label wasn't stamped) must not leave the panel blank — a static,
+  // node-NEUTRAL fallback still tells the operator a delivery-graph step is waiting. It must read true
+  // for a non-human escalation twin too, so it must not claim "human step".
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "20411", elementId: "delivery-human-task__n1", processInstanceKey: "dg-9", state: "CREATED" },
+    // a bounded `agent`/`wait`/`connector` node's escalation twin: `isDeliveryHumanElement` matches it,
+    // but it carries no stored human label, so it gets the neutral fallback, not a "human step" claim.
+    { userTaskKey: "20499", elementId: "delivery-human-task__agent5__esc", processInstanceKey: "dg-9", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(byKey["20411"].question, "A scheduled delivery-graph step is waiting to be completed.");
+  assertEquals(byKey["20499"].question, "A scheduled delivery-graph step is waiting to be completed.");
+});
+
 test("pollUserTasks (engine-first): a delivery-human task on an UNTRACKED run still surfaces (bucketed `delivery`, instance fallback) (issue #442)", async () => {
   // Even with no `delivery_graph_runs` row referencing the instance, the kind implies its aggregate, so
   // the row renders and stays answerable — mirroring the orphaned-escalation guarantee (#358).

package/app/service.ts

@@ -30,7 +30,7 @@ import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./delivery.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
-import { isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { deliveryHumanContextQuestion, isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
 import { deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
@@ -2613,6 +2613,10 @@ export async function pollUserTasks(
     url?: string | null;
     deliveryLabel?: string | null;
     conformanceSummary?: string | null;
+    /** The parked human-node instruction labels for a delivery run, keyed by user-task element id
+     *  (`delivery-human-task__<node>`) — the run row's stamped `human_labels`, denormalised so the
+     *  Tasks-inbox "Decision context" can explain a parked delivery-graph `human` node (issue #772). */
+    humanLabels?: Record<string, string>;
     /** The subject's at-a-glance "waiting on <capability> · …" rollup, denormalised for the readiness
      *  escalation question (issue #674): the wait-gate projection on `plans.wait_gate_label`, or the
      *  feature run's `delivery_label` for the inline preflight. */
@@ -2640,7 +2644,7 @@ export async function pollUserTasks(
   // feature/plan/pr enrichment. The row's inlined `delivery-human-task__<node>` id is recognised by
   // the shared `userTaskKindLabel` predicate, and buckets as `delivery` (below).
   for (const run of await deliveryGraphRuns(data).all()) {
-    if (run.process_key) subjectByInstance.set(run.process_key, { type: "delivery", key: run.run_key, title: run.title, url: null });
+    if (run.process_key) subjectByInstance.set(run.process_key, { type: "delivery", key: run.run_key, title: run.title, url: null, humanLabels: parseHumanLabels(run.human_labels) });
   }
 
   // Per-element subject type for an ORPHANED task (no subject row) — the kind implies its aggregate even
@@ -2719,6 +2723,13 @@ export async function pollUserTasks(
         question = readinessEscalationQuestion(subj?.waitGateLabel ?? null);
         break;
     }
+    // A delivery-graph `human` node's user-task id is inlined per node (`delivery-human-task__<node>`
+    // and its `…__esc` twin), so it can't be a static `case` above (issue #772). Fill its "Decision
+    // context" from the run's stamped `human_labels` — otherwise the panel is blank and, because this
+    // surface seeds no form variables, the operator has no idea what the run is waiting on.
+    if (question === null && isDeliveryHumanElement(elementId)) {
+      question = deliveryHumanContextQuestion(subj?.humanLabels, elementId);
+    }
     return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? null, question, processKey: processInstanceKey, formKey: resolvedFormKey };
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.185.1",
+  "version": "0.186.1",
   "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"
   },

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 };
 }