@nanobpm/nano-workforce 0.131.0 → 0.131.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.131.1](https://github.com/nanobpm/nano-workforce/compare/v0.131.0...v0.131.1) (2026-08-24)
+
+### Bug Fixes
+
+* **delivery-graph:** seed human-task prompt/context so its form is not contextless ([#502](https://github.com/nanobpm/nano-workforce/issues/502)) ([d2991ea](https://github.com/nanobpm/nano-workforce/commit/d2991ea0ec54e36711c27f58b8901ca85b7179e6)), closes [#499](https://github.com/nanobpm/nano-workforce/issues/499) [#499](https://github.com/nanobpm/nano-workforce/issues/499)
+
 ## [0.131.0](https://github.com/nanobpm/nano-workforce/compare/v0.130.0...v0.131.0) (2026-08-23)
 
 ### Features

package/app/deliveryGraphCompiler.test.ts

@@ -29,6 +29,17 @@ async function compileFail(graph: unknown) {
   return r.errors;
 }
 
+/** The sub-process element id of the PLANNED human user task in a compiled graph — i.e. the
+ * delivery-human-task element that is NOT a bounded node's __esc timeout twin. Returns "" if none. */
+function humanTaskSubEl(bpmn: string): string {
+  const parts = bpmn.split('<bpmn:userTask id="delivery-human-task__');
+  for (let k = 1; k < parts.length; k++) {
+    const id = parts[k].slice(0, parts[k].indexOf('"'));
+    if (!id.endsWith("__esc")) return id;
+  }
+  return "";
+}
+
 // The ADR's motivating case: an agent merges PR #B, a `pr` wait node watches it merge and emits
 // `mergedSha`, a human does the manual OTP publish emitting `resolvedArtifact`, and a connector
 // consumes the published artifact.
@@ -114,6 +125,42 @@ test("late-binding: a fact-qualified edge threads a boundFacts input into the co
   assert(boundInput, `boundFacts is a single-quoted FEEL list literal, got: ${r.bpmn.match(/source='[^']*' target="boundFacts"/)?.[0] ?? r.bpmn.match(/source="[^"]*" target="boundFacts"/)?.[0]}`);
 });
 
+test("#499 human context: the human user-task seeds prompt/nodeId/emit context so its generic form is not contextless", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
+  // The human node's subProcess ioMapping must thread the authored prompt + node identity + emit
+  // context from `nodeInputs.<el>` onto the user task (the form reads them). A dropped prompt input is
+  // exactly the contextless-form bug (#499). Locate the PLANNED human task (not an `__esc` twin).
+  const subEl = humanTaskSubEl(r.bpmn);
+  assert(subEl !== "", "the graph inlines a planned human user task");
+  assert(r.bpmn.includes(`source="=nodeInputs.${subEl}.prompt" target="prompt"`), "the human task seeds its authored prompt");
+  assert(r.bpmn.includes(`source="=nodeInputs.${subEl}.nodeId" target="nodeId"`), "the human task seeds its node identity");
+  // The emit label/mode are DERIVED in FEEL from the seeded emits list (single source of truth) — a
+  // single-quoted attribute so the literal quotes survive the engine deploy path.
+  assert(
+    r.bpmn.includes(`source='=if count(nodeInputs.${subEl}.emits) = 0 then "none" else "typed"' target="emitMode"`),
+    "emitMode is derived from the emits count",
+  );
+  assert(
+    r.bpmn.includes(`for _e in nodeInputs.${subEl}.emits return _e.name`) && r.bpmn.includes('target="emitLabel"'),
+    "emitLabel is derived from the emits list",
+  );
+});
+
+test("#499 escalation context: an agent-node timeout escalation seeds a context line naming the node, its job type, and the elapsed SLA", async () => {
+  const r = await compileOk(RELEASE_RUNBOOK);
+  // The `__esc` timeout-escalation user task previously carried NO ioMapping — a blank form that never
+  // said a timeout occurred, on which node. It must now seed a `prompt` context line from a compile-time
+  // literal (node id + job type) concatenated with the runtime elapsed SLA (`nodeTimeout`).
+  const start = r.bpmn.indexOf('<bpmn:userTask id="delivery-human-task__n1__esc"');
+  assert(start !== -1, "a bounded node inlines an escalation user task");
+  const escBlock = r.bpmn.slice(start, r.bpmn.indexOf("</bpmn:userTask>", start));
+  assert(escBlock.includes('target="prompt"'), "the escalation task seeds a prompt context line");
+  assert(escBlock.includes("Node open-b (senior:feature) exceeded its SLA ("), "the context names the node and its job type");
+  assert(escBlock.includes("string(nodeTimeout)"), "the context reports the elapsed SLA at runtime");
+  assert(escBlock.includes('="none"') && escBlock.includes('target="emitMode"'), "the escalation labels its emit field N/A so the generic form hides the inert value input");
+});
+
+
 test("rejects unknown kind (by construction) with a path-qualified error, nothing compiled", async () => {
   const errors = await compileFail({
     nodes: [{ id: "x", kind: "deploy", deploy: { target: "prod" } }],

package/app/deliveryGraphCompiler.ts

@@ -823,6 +823,16 @@ function ioMappingLines(w: NodeWiring, boundInputs: readonly BoundInput[]): stri
     case "human":
       inputs.push({ source: cfg("escalationSlaTimeout"), target: "escalationSlaTimeout" });
       inputs.push({ source: cfg("escalationAssignee"), target: "escalationAssignee" });
+      // Seed the authored instruction + node identity + emit context so the generic human form renders
+      // "now do X", names the parked node, and labels/hides its emit field (issue #499). `emits` is the
+      // single source of truth; the emit label/mode are derived from it in FEEL here (no duplicate seed).
+      inputs.push({ source: cfg("prompt"), target: "prompt" });
+      inputs.push({ source: cfg("nodeId"), target: "nodeId" });
+      inputs.push({ source: `=if count(${cfg("emits").slice(1)}) = 0 then "none" else "typed"`, target: "emitMode" });
+      inputs.push({
+        source: `=string join(for _e in ${cfg("emits").slice(1)} return _e.name + " (" + _e.type + ")", ", ")`,
+        target: "emitLabel",
+      });
       break;
     case "connector":
       inputs.push({ source: cfg("target"), target: "target" });
@@ -868,9 +878,9 @@ function innerBodyLines(w: NodeWiring): string[] {
   const node = w.node;
   switch (node.kind) {
     case "agent":
-      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), []);
+      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], node.agent.jobType);
     case "connector":
-      return serviceBodyLines(el, node.id, `type="${DELEGATE_TASK_TYPE.connector}"`, []);
+      return serviceBodyLines(el, node.id, `type="${DELEGATE_TASK_TYPE.connector}"`, [], `connector → ${node.connector.target}`);
     case "wait":
       return waitBodyLines(el, node.id);
     case "human":
@@ -882,8 +892,15 @@ function innerBodyLines(w: NodeWiring): string[] {
 
 /** `agent`/`connector` body: `start → serviceTask → end`, with a bounded `=nodeTimeout` boundary that
  * escalates the stalled node onto a human-completable user task. `taskDefAttr` is the pre-rendered
- * `type="…"` attribute; `taskProps` are optional `<zeebe:property>` envelope lines. */
-function serviceBodyLines(el: string, nodeId: string, taskDefAttr: string, taskProps: readonly string[]): string[] {
+ * `type="…"` attribute; `taskProps` are optional `<zeebe:property>` envelope lines; `descriptor`
+ * names the stalled work (job type / connector target) for the escalation task's context line (#499). */
+function serviceBodyLines(
+  el: string,
+  nodeId: string,
+  taskDefAttr: string,
+  taskProps: readonly string[],
+  descriptor: string,
+): string[] {
   const esc = escalationTaskElement(el);
   const taskExt =
     taskProps.length > 0
@@ -911,7 +928,18 @@ function serviceBodyLines(el: string, nodeId: string, taskDefAttr: string, taskP
     `        <bpmn:outgoing>${el}_i2</bpmn:outgoing>`,
     `        <bpmn:timerEventDefinition id="${el}_ted"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=nodeTimeout</bpmn:timeDuration></bpmn:timerEventDefinition>`,
     "      </bpmn:boundaryEvent>",
-    ...escalationTaskLines(esc, nodeId, [`${el}_i2`], `${el}_i3`),
+    ...escalationTaskLines(
+      esc,
+      nodeId,
+      [`${el}_i2`],
+      `${el}_i3`,
+      escalationContextFeel(
+        nodeId,
+        descriptor,
+        "nodeTimeout",
+        "; in-flight work may already exist — check for a draft PR or partial state before retrying or reassigning.",
+      ),
+    ),
     `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i3</bpmn:incoming></bpmn:endEvent>`,
     flow(`${el}_i0`, `${el}_start`, `${el}_task`),
     flow(`${el}_i1`, `${el}_task`, `${el}_end`),
@@ -991,7 +1019,13 @@ function waitBodyLines(el: string, nodeId: string): string[] {
     `        <bpmn:outgoing>${el}_i7</bpmn:outgoing>`,
     `        <bpmn:outgoing>${el}_i4</bpmn:outgoing>`,
     "      </bpmn:exclusiveGateway>",
-    ...escalationTaskLines(esc, nodeId, [`${el}_i4`], `${el}_i5`),
+    ...escalationTaskLines(
+      esc,
+      nodeId,
+      [`${el}_i4`],
+      `${el}_i5`,
+      escalationContextFeel(nodeId, "readiness gate", "probeTimeout", " before its ReadinessProbe went green — decide how to proceed."),
+    ),
     `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i5</bpmn:incoming><bpmn:incoming>${el}_i7</bpmn:incoming></bpmn:endEvent>`,
     flow(`${el}_i0`, `${el}_start`, `${el}_probeLoop`),
     flow(`${el}_i1`, `${el}_probeLoop`, `${el}_end`),
@@ -1047,14 +1081,29 @@ function humanBodyLines(el: string, nodeId: string): string[] {
 }
 
 /** A bounded node's escalation user task — a human-completable stop (`isDeliveryHumanElement`
- * convention) that a human OR an agent (ADR 0046) answers to unstick a stalled node. */
-function escalationTaskLines(esc: string, nodeId: string, incoming: readonly string[], outgoing: string): string[] {
+ * convention) that a human OR an agent (ADR 0046) answers to unstick a stalled node. `contextFeel` is
+ * a FEEL expression yielding the context line seeded onto the generic form's read-only prompt field
+ * (issue #499) — e.g. "Node n1 (senior:feature) exceeded its SLA (PT30M); …" — so the operator can see
+ * WHICH node timed out and that in-flight work may already exist, instead of a blank form. The emit
+ * field is labelled "none" so the generic form hides its (inert on an escalation) typed-value input. */
+function escalationTaskLines(
+  esc: string,
+  nodeId: string,
+  incoming: readonly string[],
+  outgoing: string,
+  contextFeel: string,
+): string[] {
   return [
     `      <bpmn:userTask id="${esc}" name="Escalate: ${escapeXml(nodeId)}">`,
     "        <bpmn:extensionElements>",
     `          <zeebe:formDefinition formId="${GENERIC_HUMAN_FORM}" />`,
     "          <zeebe:userTask />",
     '          <zeebe:assignmentDefinition candidateGroups="operators" />',
+    "          <zeebe:ioMapping>",
+    `            <zeebe:input ${attr("source", contextFeel)} target="prompt" />`,
+    `            <zeebe:input ${attr("source", `=${feelStr(nodeId)}`)} target="nodeId" />`,
+    `            <zeebe:input ${attr("source", '="none"')} target="emitMode" />`,
+    "          </zeebe:ioMapping>",
     "        </bpmn:extensionElements>",
     ...incoming.map((id) => `        <bpmn:incoming>${id}</bpmn:incoming>`),
     `        <bpmn:outgoing>${outgoing}</bpmn:outgoing>`,
@@ -1062,6 +1111,15 @@ function escalationTaskLines(esc: string, nodeId: string, incoming: readonly str
   ];
 }
 
+/** Build the FEEL context line seeded onto an escalation task's read-only prompt field (issue #499).
+ * The node id + descriptor (job type / connector target / "readiness gate") are baked as compile-time
+ * literals; the elapsed SLA is read from the node body's runtime `timeoutVar` (`nodeTimeout` for a
+ * bounded service node, `probeTimeout` for a `wait` gate). `tail` closes the sentence per kind. */
+function escalationContextFeel(nodeId: string, descriptor: string, timeoutVar: string, tail: string): string {
+  const head = feelStr(`Node ${nodeId} (${descriptor}) exceeded its SLA (`);
+  return `=${head} + string(${timeoutVar}) + ${feelStr(`)${tail}`)}`;
+}
+
 /** A plain `<bpmn:sequenceFlow>` (6-space indented). */
 function flow(id: string, source: string, target: string): string {
   return `      <bpmn:sequenceFlow id="${id}" sourceRef="${source}" targetRef="${target}" />`;

package/app/deliveryRunner.test.ts

@@ -79,12 +79,46 @@ test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMappin
   assert(wait?.probe && typeof wait.probe === "object", "the wait node carries its ReadinessProbe descriptor");
 
   const human = byField((v) => "escalationSlaTimeout" in v);
-  assertEquals(human, { escalationSlaTimeout: "PT2H", escalationAssignee: "alice" });
+  assertEquals(human, {
+    escalationSlaTimeout: "PT2H",
+    escalationAssignee: "alice",
+    // #499: the human node seeds its authored prompt, node identity, and declared emits so the
+    // generic user-task form renders "now do X", names the parked node, and labels its emit field.
+    prompt: "run the manual OTP publish",
+    nodeId: "publish",
+    emits: [{ name: "resolvedArtifact", type: "artifact" }],
+  });
 
   const connector = byField((v) => v.target === "npm:install");
   assertEquals(connector, { target: "npm:install", dedupeKey: "consume-1", payload: null, timeout: "PT10M" });
 });
 
+test("the human node seeds prompt/nodeId/emits; a click-done (no-emit, no-prompt) node seeds empty defaults", async () => {
+  // #499: the compiled human user-task's form reads `prompt`/`nodeId`/`emits` from `nodeInputs.<el>`;
+  // a discarded prompt is the contextless-form bug. Pin both an emit-declaring node and the degenerate
+  // click-done node (no `human` config, no `emits`) so the seed never regresses to null/undefined.
+  const graph: DeliveryGraph = {
+    nodes: [
+      { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" }, emits: [{ name: "resolvedArtifact", type: "artifact" }] },
+      { id: "ack", kind: "human" },
+    ],
+    edges: [{ from: "publish.resolvedArtifact", to: "ack" }],
+  };
+  const p = await prepareOk(graph);
+  const humans = Object.values(p.nodeInputs).filter((v) => "escalationSlaTimeout" in v) as Array<Record<string, unknown>>;
+  const publish = humans.find((v) => v.nodeId === "publish");
+  const ack = humans.find((v) => v.nodeId === "ack");
+
+  assertEquals(publish?.prompt, "run the manual OTP publish");
+  assertEquals(publish?.emits, [{ name: "resolvedArtifact", type: "artifact" }]);
+
+  // The click-done node carries a defined-but-empty prompt and an empty emits list (never undefined),
+  // so the form seeds a blank instruction and hides its emit field rather than seeding null.
+  assertEquals(ack?.prompt, "");
+  assertEquals(ack?.emits, []);
+  assertEquals(ack?.nodeId, "ack");
+});
+
 test("wait gateKeys default to a fresh per-run token so concurrent runs of one graph never cross-correlate", async () => {
   const gateKeyOf = (p: Awaited<ReturnType<typeof prepareOk>>) =>
     (Object.values(p.nodeInputs).find((v) => "gateKey" in v) as { gateKey?: string } | undefined)?.gateKey;

package/app/deliveryRunner.ts

@@ -15,7 +15,7 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
-import type { DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
+import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery } from "./readiness.ts";
 
@@ -65,7 +65,7 @@ const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
 type NodeInput =
   | { jobType: string; appendPrompt: string; timeout: string }
   | { gateKey: string; probe: unknown; probeTimeout: string; probePollEvery: string }
-  | { escalationSlaTimeout: string; escalationAssignee: string | null }
+  | { escalationSlaTimeout: string; escalationAssignee: string | null; prompt: string; nodeId: string; emits: DeliveryFact[] }
   | { target: string; dedupeKey: string | null; payload: Record<string, unknown> | null; timeout: string };
 
 /** The result of compiling + preparing a graph for deployment: the content-addressed process id, the
@@ -185,7 +185,17 @@ function buildNodeInput(
       };
     }
     case "human":
-      return { escalationSlaTimeout: ctx.escalationSlaTimeout, escalationAssignee: ctx.escalationAssignee };
+      return {
+        escalationSlaTimeout: ctx.escalationSlaTimeout,
+        escalationAssignee: ctx.escalationAssignee,
+        // Seed the authored instruction, node identity, and declared emits so the human user-task's
+        // form can render its "now do X" prompt, name the parked node, and label/hide its emit field
+        // (issue #499 — the generic form otherwise renders contextless). `emits` stays the single
+        // source of truth: the compiled ioMapping derives the emit label/mode from it in FEEL.
+        prompt: node.human?.prompt ?? "",
+        nodeId: node.id ?? ctx.element,
+        emits: Array.isArray(node.emits) ? node.emits.map((f) => ({ ...f })) : [],
+      };
     case "connector":
       return {
         target: node.connector.target,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.131.0",
+  "version": "0.131.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",

package/resources/forms/delivery-human-generic.form

@@ -3,6 +3,13 @@
   "schemaVersion": 18,
   "type": "default",
   "components": [
+    {
+      "type": "text",
+      "text": "### Delivery graph — node `{{nodeId}}`",
+      "conditional": {
+        "hide": "=(nodeId = null) or (nodeId = \"\")"
+      }
+    },
     {
       "type": "textarea",
       "key": "prompt",
@@ -10,15 +17,32 @@
       "description": "The scheduled human step this delivery graph is waiting on.",
       "readonly": true
     },
+    {
+      "type": "text",
+      "text": "**Emits:** {{emitLabel}} — enter its typed value below (validated against the node's declared fact).",
+      "conditional": {
+        "hide": "=emitMode != \"typed\""
+      }
+    },
     {
       "type": "textfield",
       "key": "value",
       "label": "Emitted value",
       "description": "The typed value this step hands forward to its downstream dependents. Validated against the node's declared emitted fact.",
+      "conditional": {
+        "hide": "=emitMode != \"typed\""
+      },
       "validate": {
         "required": true
       }
     },
+    {
+      "type": "text",
+      "text": "_This step emits no typed fact (N/A) — just complete it to unblock its dependents._",
+      "conditional": {
+        "hide": "=emitMode = \"typed\""
+      }
+    },
     {
       "type": "textarea",
       "key": "note",

package/resources/processes/delivery-human.bpmn

@@ -10,6 +10,10 @@
         <zeebe:userTask />
         <zeebe:assignmentDefinition candidateGroups="operators" assignee="=if (is defined(escalationAssignee) and escalationAssignee != null and trim(string(escalationAssignee)) != &#34;&#34;) then escalationAssignee else null" />
         <zeebe:ioMapping>
+          <zeebe:input source="=if (is defined(prompt)) then prompt else null" target="prompt" />
+          <zeebe:input source="=if (is defined(nodeId)) then nodeId else null" target="nodeId" />
+          <zeebe:input source="=if (is defined(emits) and count(emits) != 0) then &#34;typed&#34; else &#34;none&#34;" target="emitMode" />
+          <zeebe:input source="=if (is defined(emits)) then string join(for _e in emits return _e.name + &#34; (&#34; + _e.type + &#34;)&#34;, &#34;, &#34;) else &#34;&#34;" target="emitLabel" />
           <zeebe:output source="=&#34;completed&#34;" target="humanOutcome" />
           <zeebe:output source="=if (is defined(value)) then value else null" target="humanEmitValue" />
           <zeebe:output source="=if (is defined(resolvedArtifact)) then resolvedArtifact else null" target="humanEmitArtifact" />