@nanobpm/nano-workforce 0.201.0 → 0.201.1

package/app/deliveryHuman.ts

@@ -32,6 +32,7 @@
 //      binds and pins exactly the value the human handed forward.
 import type { DeliveryFact, DeliveryNodeHuman } from "../nano-generated/api-io.d.ts";
 import { DELIVERY_FACT_TYPES, type DeliveryFactType, FACT_NAME_MAX_LENGTH, FACT_NAME_PATTERN } from "./deliveryGraph.ts";
+import { redactFreeText } from "./redactText.ts";
 
 /** The single BPMN `bpmn:userTask` element id every `human` delivery-graph node schedules its work
  *  as (`resources/processes/delivery-human.bpmn`). One reusable engine-native body, instantiated once
@@ -54,6 +55,77 @@ export function isDeliveryHumanElement(elementId: string): boolean {
   return elementId === DELIVERY_HUMAN_ELEMENT || elementId.startsWith(`${DELIVERY_HUMAN_ELEMENT}__`);
 }
 
+/** The id suffix the S4 compiler appends for a service node's bounded-timeout escalation TWIN user task
+ *  (`delivery-human-task__<el>__esc`). */
+export const DELIVERY_ESCALATION_TWIN_SUFFIX = "__esc";
+
+/** The id suffix for an `agent` node's producer-contract escalation TWIN (`…__contract`). */
+export const DELIVERY_CONTRACT_TWIN_SUFFIX = "__contract";
+
+/** The KIND marker the S4 compiler appends to a `wait` gate's bounded-timeout escalation twin
+ *  (`delivery-human-task__<el>__esc__wait`). A wait-gate escalation has NO retry semantics — its
+ *  resolution is "supply the awaited value and continue", never "re-run the probe loop" — so the
+ *  compiler renders the select-less {@link GENERIC_HUMAN_FORM} for it, NOT the retry-capable
+ *  {@link ESCALATION_FORM} a service-node `__esc`/`__contract` twin renders. The bare `__esc` suffix is
+ *  shared by both kinds, so a form inferred from the suffix ALONE misclassifies the wait gate as
+ *  retryable (the #461 Tasks-inbox `form_key` fallback then renders a bogus "Retry this step" that the
+ *  wait process silently ignores). Stamping the kind into the id lets {@link escalationFormId} DERIVE
+ *  the compiled form from the id — no separate node-kind registry to drift (PR #863 review,
+ *  app/agentCompletion.ts:186). */
+export const DELIVERY_WAIT_ESCALATION_KIND_MARKER = "__wait";
+
+/** The full id suffix of a `wait` gate's bounded-timeout escalation twin (`__esc` + the `__wait` kind
+ *  marker). */
+export const DELIVERY_WAIT_ESCALATION_TWIN_SUFFIX = `${DELIVERY_ESCALATION_TWIN_SUFFIX}${DELIVERY_WAIT_ESCALATION_KIND_MARKER}`;
+
+/** True for a delivery-graph SERVICE-node escalation TWIN user task — the bounded-timeout `__esc` twin
+ *  or an agent's producer-contract `__contract` twin — as opposed to a plain per-node human task
+ *  (`delivery-human-task__<el>`). Unlike that per-node human task, which renders a DIFFERENT form per
+ *  node (and so has no single static completion contract — left unvalidated, `ESCALATION_FORM_BY_ELEMENT`
+ *  deliberately omits it), a twin ALWAYS renders a FIXED escalation form — the retry-capable
+ *  {@link ESCALATION_FORM} (a strict superset of {@link GENERIC_HUMAN_FORM}: same `value`, an optional
+ *  note field (`escalationNote` on the escalation form, `note` on the generic human form), PLUS
+ *  the `decision` select) or the select-less generic form — so its completion variables CAN be validated
+ *  against `ESCALATION_FORM`'s contract (no required fields, so the generic-form twins never false-reject;
+ *  only a present-but-invalid `decision` is rejected). Matched on the convention suffix — single source of
+ *  truth with the compiler's `escalationTaskElement`/`contractEscalationTaskElement` builders — requiring
+ *  a NON-EMPTY `<el>` between prefix and suffix so the bare per-node base of a node literally named
+ *  `esc`/`contract` (`delivery-human-task__esc`) is not misread as a twin. (A node id MAY itself end in
+ *  `__esc` — `NODE_ID_PATTERN` allows it — so the twin of node `foo` and the base of a node named
+ *  `foo__esc` collide on one id; validating that rare base against the superset escalation form is
+ *  harmless, since the form has no required fields and only constrains a `decision` such a base never
+ *  sets to an out-of-range value through its own select-less form.) */
+export function isDeliveryEscalationTwin(elementId: string): boolean {
+  const prefix = `${DELIVERY_HUMAN_ELEMENT}__`;
+  if (!elementId.startsWith(prefix)) return false;
+  for (const suffix of [DELIVERY_WAIT_ESCALATION_TWIN_SUFFIX, DELIVERY_ESCALATION_TWIN_SUFFIX, DELIVERY_CONTRACT_TWIN_SUFFIX]) {
+    if (elementId.endsWith(suffix) && elementId.length > prefix.length + suffix.length) return true;
+  }
+  return false;
+}
+
+/** True for a `wait` gate's bounded-timeout escalation twin specifically (`…__esc__wait`) — the twin
+ *  kind that renders the select-less {@link GENERIC_HUMAN_FORM} (no retry path), as opposed to a
+ *  service-node `__esc`/`__contract` twin, which renders the retry-capable {@link ESCALATION_FORM}.
+ *  This is the discriminator {@link escalationFormId} uses to DERIVE the compiled form from the id. */
+export function isDeliveryWaitEscalationTwin(elementId: string): boolean {
+  const prefix = `${DELIVERY_HUMAN_ELEMENT}__`;
+  return (
+    elementId.startsWith(prefix) &&
+    elementId.endsWith(DELIVERY_WAIT_ESCALATION_TWIN_SUFFIX) &&
+    elementId.length > prefix.length + DELIVERY_WAIT_ESCALATION_TWIN_SUFFIX.length
+  );
+}
+
+/** Strip the trailing escalation-twin suffix (`__esc`, the wait-gate `__esc__wait`, or `__contract`)
+ *  to recover the base per-node element id (`delivery-human-task__<el>`). The `__esc__wait` kind marker
+ *  MUST be stripped before the bare `__esc` (it ends in `__esc`, so stripping `__esc` first would leave
+ *  a dangling `__wait`). A non-twin id is returned unchanged. Single source of truth for the strip so
+ *  every "resolve the twin to its base node" lookup agrees on the suffix set. */
+export function stripDeliveryEscalationTwinSuffix(elementId: string): string {
+  return elementId.replace(/__(esc__wait|esc|contract)$/, "");
+}
+
 /** The read-model "Decision context" for a parked delivery-graph `human` node (issue #772). The Tasks
  *  surface renders the deployed `.form` against EMPTY data (it seeds no task-local variables), so the
  *  node's instruction cannot reach the operator through the form's readonly `prompt` field — it must
@@ -76,11 +148,45 @@ export function isDeliveryHumanElement(elementId: string): boolean {
 export function deliveryHumanContextQuestion(
   humanLabels: Record<string, string> | undefined,
   elementId: string,
+  livePrompt?: string | null,
 ): string {
   const labels = humanLabels ?? {};
-  const base = elementId.replace(/__esc$/, "");
+  const base = stripDeliveryEscalationTwinSuffix(elementId);
   const label = (labels[elementId] ?? labels[base] ?? "").trim();
-  return label || "A scheduled delivery-graph step is waiting to be completed.";
+  return label || (livePrompt ?? "").trim() || "A scheduled delivery-graph step is waiting to be completed.";
+}
+
+/** Whether a parked delivery task needs its LIVE engine prompt for the "Decision context": an
+ *  `__esc`/`__contract` escalation twin of a bounded agent/wait/connector node has no stamped
+ *  `human_labels` entry, so without the compiler's per-task `prompt` (node, reported status, missing
+ *  emits, the agent's own report/question/transcript, and how to resolve) the operator saw only the
+ *  static fallback — the "no actionable information" escalations of instance 171774. A real human
+ *  node (or its `__esc` twin) keeps its authored instruction label. */
+export function needsLiveDeliveryPrompt(humanLabels: Record<string, string> | undefined, elementId: string): boolean {
+  if (!/__(esc__wait|esc|contract)$/.test(elementId)) return false;
+  const labels = humanLabels ?? {};
+  const base = stripDeliveryEscalationTwinSuffix(elementId);
+  return !(labels[elementId] ?? labels[base] ?? "").trim();
+}
+
+/** Decode a `prompt` variable as the engine's variable search reports it (a JSON-encoded value) into
+ *  plain text; `null` for an absent, non-string, or truncated preview (never show a clipped prompt as
+ *  if it were whole — the caller falls back).
+ *
+ *  The decoded text is REDACTED ({@link redactFreeText}) before it is returned: the escalation prompt
+ *  embeds agent-controlled `summary`/`question`/`error`/`transcriptUrl` (the compiler's report
+ *  sentence), and the caller persists the result as the operator-facing `user_tasks.question`. An
+ *  agent report can carry a token-bearing URL or a credential copied into its report, so this path
+ *  redacts exactly like the static `human_labels` instruction (which `buildHumanLabels` runs through
+ *  `redactFreeText`, issue #778) — never store a live prompt raw (issue #863 review). */
+export function decodeLivePrompt(row: { value: string; isTruncated?: boolean } | undefined): string | null {
+  if (!row || row.isTruncated) return null;
+  try {
+    const v: unknown = JSON.parse(row.value);
+    return typeof v === "string" && v.trim() ? redactFreeText(v.trim()) : null;
+  } catch {
+    return null;
+  }
 }
 
 /** The clickable link for a parked delivery-graph `human` node's Tasks-inbox row (issue #813): the
@@ -96,7 +202,7 @@ export function deliveryHumanContextUrl(
   elementId: string,
 ): string | null {
   const labels = humanLabels ?? {};
-  const base = elementId.replace(/__esc$/, "");
+  const base = stripDeliveryEscalationTwinSuffix(elementId);
   const instruction = labels[elementId] ?? labels[base] ?? "";
   const url = firstHttpUrl(instruction);
   // The stored `human_labels` are display-REDACTED (`redactFreeText` in `buildHumanLabels`): a URL that
@@ -179,6 +285,12 @@ export function firstHttpUrl(text: string | undefined | null): string | null {
  *  declared emitted fact, so a human node with no explicit/category form can STILL emit downstream. */
 export const GENERIC_HUMAN_FORM = "delivery-human-generic";
 
+/** The bounded service-node ESCALATION form (retry-node resolution): like the generic form plus the
+ *  `decision` Resolution select (Continue / Retry this step). Kept SEPARATE from {@link GENERIC_HUMAN_FORM}
+ *  — that form is shared with plain scheduled human steps and wait-gate escalations, which have no
+ *  retry semantics and never read `decision`, so the select must not render there. */
+export const ESCALATION_FORM = "delivery-escalation";
+
 /** The "click done" category form: a degenerate no-emit acknowledgement ("now do X" → done). */
 export const HUMAN_ACK_FORM = "delivery-human-ack";
 

package/app/deliveryRunner.test.ts

@@ -238,12 +238,12 @@ test("producer contract required-emit subset (#761): a routing-only emit is NOT
   const graph: DeliveryGraph = {
     name: "routing-only producer",
     nodes: [
-      { id: "classify", kind: "agent", agent: { jobType: "senior:feature", prompt: "classify it" }, emits: [{ name: "decision", type: "string" }] },
+      { id: "classify", kind: "agent", agent: { jobType: "senior:feature", prompt: "classify it" }, emits: [{ name: "verdict", type: "string" }] },
       { id: "migrate", kind: "connector", connector: { target: "npm:install", dedupeKey: "m-1" } },
       { id: "release", kind: "connector", connector: { target: "npm:publish", dedupeKey: "r-1" } },
     ],
     edges: [
-      { from: "classify", to: "migrate", when: "classify.decision", equals: "breaking" },
+      { from: "classify", to: "migrate", when: "classify.verdict", equals: "breaking" },
       { from: "classify", to: "release", default: true },
     ],
   };
@@ -257,7 +257,7 @@ test("producer contract required-emit subset (#761): a routing-only emit is NOT
   assert(!prompt.includes("populate each of these top-level fields"), "no required-emit sentence is rendered when every emit is routing-only");
   // The classifier-emit contract STILL tells the agent to return the routing fact (and omit if undecidable).
   assert(prompt.includes("Classifier emit contract"), "the classifier-emit contract is present");
-  assert(prompt.includes("`decision`"), "the routing fact is still named by the classifier-emit contract");
+  assert(prompt.includes("`verdict`"), "the routing fact is still named by the classifier-emit contract");
 });
 
 

package/app/redactText.ts

@@ -0,0 +1,88 @@
+// Free-form-prose URL-credential redaction (`redactFreeText`) lives in this LOW-LEVEL helper module so
+// both the delivery-graph compiler (`deliveryGraphCompiler.ts`, which embeds redacted prompts into the
+// generated BPMN display name/documentation) AND `deliveryHuman.ts` (which redacts a decoded live
+// prompt / human labels) can import it WITHOUT a cycle. Previously `redactFreeText` was defined in the
+// compiler and `deliveryHuman.ts` imported the compiler solely for it — a direct `compiler ⇄ human`
+// import cycle that reversed `deliveryHuman.ts`'s documented pure-helper layering and made module init
+// depend on ESM cycle ordering (PR #863 review — thread deliveryGraphCompiler.ts / deliveryHuman.ts).
+// This module depends only on the character-class strip (`deliveryGraph.ts`) and the canonical URL
+// redactors (`readiness.ts`), both strictly lower layers, so nothing here can import back.
+
+import { stripXmlInvalidChars } from "./deliveryGraph.ts";
+import { redactEmbeddedCredential, redactString } from "./readiness.ts";
+
+/** Redact credential-bearing pieces of any URL embedded in FREE-FORM prose (a node's authored
+ * `prompt`), IN PLACE. Unlike {@link redactString} — tuned for a single opaque target string, where it
+ * truncates from the first `?`/`#` to end-of-string — this finds each URL-shaped token *within*
+ * surrounding prose (`scheme://…` or a scheme-relative `//…`) and strips only that token's
+ * `user:pass@` userinfo and `?query`/`#fragment` via `redactString`, leaving the prose (and ordinary
+ * punctuation such as a `?` ending a sentence) intact. Applied to the DISPLAY name/documentation only —
+ * a prompt is up to 20 000 chars of arbitrary text that can embed a bearer token or private URL, and
+ * the deployed `<bpmn:documentation>`/name is visible to modeler/explorer readers; the RAW prompt still
+ * reaches the runtime job input (`appendPrompt`/`prompt`) unmodified (issue #778 review). Deterministic
+ * and total. */
+export function redactFreeText(value: string): string {
+  // Strip XML-invalid display characters BEFORE tokenizing/redacting so every scan runs on the exact
+  // string the renderer emits. Otherwise a control char embedded in a URL (`//us\x0Ber:pass@…`) breaks
+  // the `//[^\s]+` token match, escapes redaction, then reconstructs the credential once `escapeXml`/
+  // `stripXmlInvalidChars` drops the control at render time (issue #778 review — same class as the
+  // connector/probe strip-before-classify fix).
+  const cleaned = stripXmlInvalidChars(value);
+  // Embedded credential userinfo: DERIVE from the ONE canonical redactor {@link redactEmbeddedCredential}
+  // (`EMBEDDED_CREDENTIAL_SRC` = `//[^/?#]*@`) rather than a bespoke belt heuristic. Its `[^/?#]` class
+  // spans spaces/TABs/newlines up to the LAST `@` before a `/`/`?`/`#`, so EVERY `//<userinfo>@` shape
+  // collapses uniformly to `//***@` — a colon-prefix `//user:pass@`, a colon-LESS bearer separated from
+  // its `@host` by a word or space (`//token part@host`, `//token @host`), a userinfo split by a raw
+  // CR/LF/TAB, and a malformed multi-`@` authority (`//user:pass@ss@host`) — with NO second "what is a
+  // credential" implementation that can drift from the canonical redactor/validator (`hasEmbeddedCredential`)
+  // (issue #783 review — thread deliveryGraphCompiler.ts:1140; the earlier bespoke colon-less bridge
+  // stopped on the first non-whitespace char after the space and leaked `//token part@host`). A `//…@`
+  // span is UNAMBIGUOUSLY a credential wherever it sits, so redacting a prose `//word …@host` too is the
+  // SAFE direction: the RAW prompt still reaches the runtime job input unmodified — only the operator-
+  // visible display doc loses the span. The `[^/?#]` bound also keeps the userinfo from swallowing a `?`
+  // marker (`//host?token=secret@tail` has no userinfo — its `@` rides the query), leaving that tail to
+  // the query/fragment belt below.
+  const credStripped = redactEmbeddedCredential(cleaned);
+  // Query/fragment across a whitespace BREAK: the primary `//[^\s]+` token below stops at the break, so a
+  // `//host/?\nTOKEN=secret` would leave the value visible in the XML-preserved doc. The linear belt walks
+  // each SPACE-bounded `//`-run (crossing an embedded CR/LF/TAB the primary token stopped at) and
+  // CONSERVATIVELY redacts its `?query`/`#fragment` tail through the span's space boundary — a continuation
+  // past the break is indistinguishable from a split value, so we never keep the far side (issue #778
+  // review — thread deliveryGraphCompiler.ts:1115).
+  const belted = redactQueryFragmentSpans(credStripped);
+  return belted.replace(/(?:[a-z][a-z0-9+.-]*:)?\/\/[^\s]+/gi, (m) => redactString(m));
+}
+
+/** Linear (backtracking-free) newline-aware belt companion to {@link redactFreeText}'s primary
+ * whitespace-bounded pass. Each `//`-run is bounded by a literal SPACE (0x20) — so a single span may
+ * cross a CR/LF/TAB *inside* the URL that the primary `//[^\s]+` token stopped at. Credential userinfo is
+ * already collapsed to `//***@` by the canonical {@link redactEmbeddedCredential} before this runs, so the
+ * belt's SOLE remaining job is a `?query`/`#fragment` tail: it redacts CONSERVATIVELY from the first
+ * `?`/`#` marker through the span's space boundary — a continuation past an embedded break is
+ * indistinguishable from a split value, so the far side is never kept. A span with no `?`/`#` (ordinary
+ * prose — a `//comment` reference, an already-collapsed `//***@host`) is returned untouched. The scan is a
+ * single left-to-right walk using `indexOf`/`charCodeAt` over spans bounded by the next SPACE, with no
+ * regex backtracking, so a 20 000-char adversarial prompt cannot trigger catastrophic backtracking (issue
+ * #778 review). Deterministic and total. */
+function redactQueryFragmentSpans(text: string): string {
+  let out = "";
+  let i = 0;
+  for (;;) {
+    const start = text.indexOf("//", i);
+    if (start < 0) return out + text.slice(i);
+    out += text.slice(i, start);
+    let end = start;
+    while (end < text.length && text.charCodeAt(end) !== 0x20 /* SPACE */) end++;
+    const span = text.slice(start, end);
+    const qMark = span.indexOf("?");
+    const hMark = span.indexOf("#");
+    const qi = qMark < 0 ? hMark : hMark < 0 ? qMark : Math.min(qMark, hMark);
+    // CONSERVATIVE: keep everything up to and including the `?`/`#` marker, then collapse the whole tail
+    // (any continuation past an embedded CR/LF/TAB) to `***`. A value/prose resuming after the break is
+    // INDISTINGUISHABLE from a split-credential continuation, so we never keep the post-break side; the RAW
+    // prompt still reaches the runtime job input unmodified (issue #778 review — thread
+    // deliveryGraphCompiler.ts:1115).
+    out += qi < 0 ? span : `${span.slice(0, qi + 1)}***`;
+    i = end;
+  }
+}

package/app/service.ts

@@ -34,7 +34,7 @@ import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./deliver
 import { DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels, reconcileOriginalInstanceBeforeRelaunch, reconcileStaleLaunchClaim } from "./deliveryGraphRun.ts";
-import { deliveryHumanContextQuestion, deliveryHumanContextUrl, isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { decodeLivePrompt, deliveryHumanContextQuestion, deliveryHumanContextUrl, isDeliveryHumanElement, needsLiveDeliveryPrompt } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
 import { deriveFeatureCompletion, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns, featureRunsTracking, foldCompletedFeatureRun } from "./feature.ts";
@@ -3316,7 +3316,21 @@ export async function pollUserTasks(
     // null), so this is the only link a delivery human task can offer.
     let deliverySubjectUrl: string | null = null;
     if (question === null && isDeliveryHumanElement(elementId)) {
-      question = deliveryHumanContextQuestion(subj?.humanLabels, elementId);
+      let livePrompt: string | null = null;
+      if (needsLiveDeliveryPrompt(subj?.humanLabels, elementId)) {
+        // An agent/wait/connector escalation twin: read the task's OWN compiler-rendered `prompt`, local
+        // to the user task's element instance (fail-open to the static fallback on any read error).
+        try {
+          const [ei] = await engine.searchElementInstances({ processInstanceKey, elementId, state: "ACTIVE" });
+          if (ei) {
+            const [row] = await engine.searchVariables({ scopeKey: String(ei.elementInstanceKey), name: "prompt" });
+            livePrompt = decodeLivePrompt(row);
+          }
+        } catch (err) {
+          console.error(`[poller] delivery escalation prompt (${processInstanceKey}/${elementId}): ${err}`);
+        }
+      }
+      question = deliveryHumanContextQuestion(subj?.humanLabels, elementId, livePrompt);
       deliverySubjectUrl = deliveryHumanContextUrl(subj?.humanLabels, elementId);
     }
     return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? deliverySubjectUrl, question, processKey: processInstanceKey, formKey: resolvedFormKey };

package/e2e/delivery-graph-dispatch.e2e.ts

@@ -21,6 +21,7 @@ import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { deliveryGraphProposals } from "../app/deliveryGraphProposals.ts";
 import { deliveryGraphRuns } from "../app/deliveryGraphRun.ts";
 import { pollDeliveryGraphPhase } from "../app/service.ts";
+import { isDeliveryEscalationTwin } from "../app/deliveryHuman.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 
 const APP_ROOT = resolve(import.meta.dirname, "..");
@@ -129,7 +130,7 @@ describe("delivery-graph dispatch — agent compiles→stages, operator dispatch
 
     // ── Completion: complete the human stop → the instance ends → the poller reconciles to done ───
     const open = await app.engine.searchUserTasks({ state: "CREATED" });
-    const human = open.find((t) => t.elementId?.startsWith("delivery-human-task__") && !t.elementId?.endsWith("__esc"));
+    const human = open.find((t) => t.elementId?.startsWith("delivery-human-task__") && !isDeliveryEscalationTwin(t.elementId));
     assert.ok(human, `a human user task is open, got ${JSON.stringify(open.map((t) => t.elementId))}`);
     await app.engine.completeUserTask(human.userTaskKey, { humanOutcome: "completed" });
     await app.settle();