@nanobpm/nano-workforce 0.140.0 → 0.142.0

package/openapi.yaml

@@ -643,6 +643,11 @@ components:
         elementId:
           type: string
           description: The BPMN element id (activity/task) the job was for, when still known (advisory).
+        elementInstanceKey:
+          type: string
+          description: The engine element-instance key the job's token occupied (#544) — the per-occupancy
+            handle, unambiguous across a looping / retried activity where many instances share one elementId.
+            Resolved from the job's element-instance wait-state; advisory, present when resolution landed.
         planKey:
           type: string
           description: The plan / epic key this job was part of (e.g. owner/repo#142), when still known (advisory).
@@ -749,6 +754,10 @@ components:
         elementId:
           type: string
           description: The BPMN element id, when still known (advisory).
+        elementInstanceKey:
+          type: string
+          description: The engine element-instance key the job's token occupied (#544) — per-occupancy,
+            unambiguous across a looping / retried activity; advisory, present when resolution landed.
         planKey:
           type: string
           description: The plan / epic key, when still known (advisory).
@@ -1352,10 +1361,13 @@ components:
           description: The fact's identifier, referenced downstream as `<nodeId>.<name>`. Must be unique within the node.
         type:
           type: string
-          enum: [string, number, boolean, artifact, version, url]
+          enum: [string, number, boolean, artifact, version, url, pr]
           description: >-
             The fact's declared type. `artifact` is a `pkg@version` handle, `version` a bare version
-            string, `url` a location — mirrors the values `capability`/`pr` probes late-bind.
+            string, `url` a location — mirrors the values `capability`/`pr` probes late-bind. `pr`
+            (issue #548) is a PR reference (`owner/repo#N`) an `agent` node emits for the PR it opened,
+            so a downstream `connector[converge*]`/`wait[pr]` node LATE-BINDS its target PR from the
+            fact instead of a hardcoded literal.
         description:
           type: string
           maxLength: 512
@@ -2802,6 +2814,13 @@ paths:
           schema:
             type: string
           description: Return only transcripts whose (still-known) correlation names this process instance.
+        - name: elementInstanceKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Return only transcripts whose correlation names this engine element-instance key (#544) —
+            resolves a session to one occupancy of a looping / retried activity, unlike the static elementId.
         - name: planKey
           in: query
           required: false

package/operations/listAgenticTranscripts.ts

@@ -46,6 +46,7 @@ export default defineOperation("listAgenticTranscripts", async ({ query, req },
   const filter: TranscriptFilter = {
     ...(query.jobKey !== undefined ? { jobKey: query.jobKey } : {}),
     ...(query.processInstanceKey !== undefined ? { processInstanceKey: query.processInstanceKey } : {}),
+    ...(query.elementInstanceKey !== undefined ? { elementInstanceKey: query.elementInstanceKey } : {}),
     ...(query.planKey !== undefined ? { planKey: query.planKey } : {}),
     ...(query.instance !== undefined ? { instance: query.instance } : {}),
     ...(query.since !== undefined ? { since: query.since } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.140.0",
+  "version": "0.142.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",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.4.0",
-    "@nanobpm/urban": "^0.82.0",
+    "@nanobpm/urban": "^0.83.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {

package/workers/delivery-connector/worker.test.ts

@@ -123,34 +123,52 @@ test("readConnectorInput: an array payload is rejected (arrays are not plain obj
 
 test("readConvergeInput: parses pr; convergeOnly defaults from the target; dependsOn is optional", () => {
   // `converge-merge` drives the merge loop → convergeOnly defaults false.
-  const merge = readConvergeInput("converge-merge", { pr: "owner/repo#7" });
+  const merge = readConvergeInput("converge-merge", { pr: "owner/repo#7" }, null);
   assertEquals(merge.parsed.prKey, "owner/repo#7");
   assertEquals(merge.convergeOnly, false);
   assertEquals(merge.dependsOn, []);
   // `converge` is review-only → convergeOnly defaults true.
-  const conv = readConvergeInput("converge", { pr: "owner/repo#7" });
+  const conv = readConvergeInput("converge", { pr: "owner/repo#7" }, null);
   assertEquals(conv.convergeOnly, true);
 });
 
 test("readConvergeInput: an explicit payload.convergeOnly overrides the target default; dependsOn threads through", () => {
-  const r = readConvergeInput("converge-merge", { pr: "owner/repo#7", convergeOnly: true, dependsOn: ["owner/repo#5", 42] as unknown as string[] });
+  const r = readConvergeInput("converge-merge", { pr: "owner/repo#7", convergeOnly: true, dependsOn: ["owner/repo#5", 42] as unknown as string[] }, null);
   assertEquals(r.convergeOnly, true, "the explicit boolean wins over the target default");
   assertEquals(r.dependsOn, ["owner/repo#5"], "non-string dependsOn entries are dropped");
 });
 
 test("readConvergeInput: a missing / unparseable pr fails CLOSED (a converge connector with no target PR is meaningless)", () => {
-  assertThrows(() => readConvergeInput("converge-merge", null), Error, "payload.pr");
-  assertThrows(() => readConvergeInput("converge-merge", {}), Error, "payload.pr");
-  assertThrows(() => readConvergeInput("converge", { pr: "not-a-pr" }), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge-merge", null, null), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge-merge", {}, null), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge", { pr: "not-a-pr" }, null), Error, "payload.pr");
 });
 
 test("readConvergeInput: an unparseable pr whose value is not JSON-serializable still fails CLOSED with the intended error (not a serializer TypeError)", () => {
   // `p.pr` is user-controlled payload data; a BigInt (or a circular object) makes JSON.stringify
   // throw, which must NOT mask the intended "requires payload.pr" error.
-  assertThrows(() => readConvergeInput("converge", { pr: 10n as unknown as string }), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge", { pr: 10n as unknown as string }, null), Error, "payload.pr");
   const circular: Record<string, unknown> = {};
   circular.self = circular;
-  assertThrows(() => readConvergeInput("converge", { pr: circular as unknown as string }), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge", { pr: circular as unknown as string }, null), Error, "payload.pr");
+});
+
+test("readConvergeInput: #548 late-binds the PR from an upstream agent's emitted `pr` fact (no literal needed)", () => {
+  const bound = [{ from: "open", name: "pr", value: "owner/repo#42" }];
+  // OMITTED payload.pr → binds the single incoming `pr` fact.
+  assertEquals(readConvergeInput("converge-merge", null, bound).parsed.prKey, "owner/repo#42");
+  assertEquals(readConvergeInput("converge-merge", {}, bound).parsed.prKey, "owner/repo#42");
+  // EXPLICIT reference form → resolves that specific threaded fact.
+  assertEquals(readConvergeInput("converge", { pr: "open.pr" }, bound).parsed.prKey, "owner/repo#42");
+  // A LITERAL still wins as-is even when a bound fact is present (never `<node>.<fact>`-shaped).
+  assertEquals(readConvergeInput("converge", { pr: "owner/repo#9" }, bound).parsed.prKey, "owner/repo#9");
+});
+
+test("readConvergeInput: #548 a dangling reference (no matching bound fact) fails CLOSED", () => {
+  // "open.pr" is reference-shaped but nothing threaded it → falls through to a literal parse, which
+  // rejects (it is not an `owner/repo#N`), so a mis-wired graph never silently enrolls a junk PR.
+  assertThrows(() => readConvergeInput("converge-merge", { pr: "open.pr" }, []), Error, "payload.pr");
+  assertThrows(() => readConvergeInput("converge-merge", { pr: "open.pr" }, [{ from: "other", name: "pr", value: "o/r#1" }]), Error, "payload.pr");
 });
 
 test("safeStringify: always returns a string, even for values JSON.stringify serializes to undefined (Symbol/undefined/function)", () => {

package/workers/delivery-connector/worker.ts

@@ -15,6 +15,7 @@ import {
   convergeOnlyForTarget,
   dispatchConnector,
   isConvergeTarget,
+  resolveConvergePr,
 } from "../../app/deliveryConnector.ts";
 import { isPrSettled, MAX_ROUNDS, type ParsedPr, parsePr, submitPr } from "../../app/service.ts";
 
@@ -81,19 +82,26 @@ export function safeStringify(value: unknown): string {
  * `convergeOnly` DEFAULTS from the target (`converge` → review-only `true`; `converge-merge` → drive
  * the merge loop `false`) and may be overridden per-dispatch by an explicit boolean. `dependsOn` is an
  * optional list of PR refs unioned into the enrolled PR's merge-stage dependency set (only non-string
- * entries are dropped; `submitPr` itself ignores unparseable refs). Exported for unit coverage — the
- * MVP sources `pr` as a literal (identical to how the `wait: pr` node targets a known PR), so no new
- * fact plumbing is needed to ship. */
+ * entries are dropped; `submitPr` itself ignores unparseable refs). Exported for unit coverage.
+ *
+ * `pr` may be sourced three ways (issue #548), resolved by {@link resolveConvergePr} against the
+ * threaded `boundFacts` BEFORE parsing: a LITERAL `owner/repo#N`, an explicit fact REFERENCE
+ * (`payload.pr: "<upstreamNode>.pr"`), or OMITTED — late-bound from the single incoming `pr` fact an
+ * upstream `agent` node emitted for the PR it opened. This is what lets the canonical
+ * `agent → connector[converge-merge] → wait` shape carry no hardcoded PR number. */
 export function readConvergeInput(
   target: string,
   payload: Record<string, unknown> | null,
+  boundFacts: readonly BoundFact[] | null,
 ): { parsed: ParsedPr; convergeOnly: boolean; dependsOn: string[] } {
   const p = payload ?? {};
-  const parsed = parsePr(p.pr);
+  const prValue = resolveConvergePr(p.pr, boundFacts ?? []);
+  const parsed = parsePr(prValue);
   if (!parsed) {
     throw new Error(
-      `delivery-connector: '${target}' target requires payload.pr as a parseable "owner/repo#N" ` +
-        `(got ${safeStringify(p.pr ?? null)})`,
+      `delivery-connector: '${target}' target requires a target PR — a literal "owner/repo#N" in ` +
+        `payload.pr, an upstream-fact reference (payload.pr: "<node>.pr"), or a threaded \`pr\` fact ` +
+        `bound from an upstream \`agent\` node (got ${safeStringify(prValue ?? null)})`,
     );
   }
   const convergeOnly = typeof p.convergeOnly === "boolean" ? p.convergeOnly : convergeOnlyForTarget(target);
@@ -106,7 +114,7 @@ const handler: AppJobHandler<In, ConnectorDispatchResult> = async (job, app) =>
   // A `converge`/`converge-merge` target enrolls a PR into the shared convergence (+ merge) loop.
   // Parse + validate its payload BEFORE claiming a ledger row, so a misconfigured converge node (no
   // parseable `pr`) fails CLOSED without writing a junk dispatch row it could never act on.
-  const converge = isConvergeTarget(target) ? readConvergeInput(target, payload) : null;
+  const converge = isConvergeTarget(target) ? readConvergeInput(target, payload, boundFacts) : null;
   const dedupeKey = connectorDedupeKey({
     dedupeKey: job.variables.dedupeKey ?? null,
     processInstanceKey: job.processInstanceKey ?? null,