@nanobpm/nano-workforce 0.135.0 → 0.136.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.136.0](https://github.com/nanobpm/nano-workforce/compare/v0.135.0...v0.136.0) (2026-08-24)
+
+### Features
+
+* **delivery:** agent-node classifier-emit contract so S7 guarded branches fire ([#506](https://github.com/nanobpm/nano-workforce/issues/506)) ([#509](https://github.com/nanobpm/nano-workforce/issues/509)) ([f3acd5b](https://github.com/nanobpm/nano-workforce/commit/f3acd5bd5977fe3b12797f7d1e3acb7d5e67eb8c))
+
+### Bug Fixes
+
+* **deps:** update dependency @nanobpm/urban to ^0.82.0 ([#482](https://github.com/nanobpm/nano-workforce/issues/482)) ([81decc1](https://github.com/nanobpm/nano-workforce/commit/81decc1b8ebd53b2835aaecbb369c5347371ceb3))
+
 ## [0.135.0](https://github.com/nanobpm/nano-workforce/compare/v0.134.0...v0.135.0) (2026-08-24)
 
 ### Features

package/app/deliveryGraphDeploy.test.ts

@@ -277,6 +277,110 @@ test("S7 deploy+route: the green default branch SKIPS `migrate` and rides the el
   assert(r.releaseRan, "the green outcome still reaches `release` via the else-flow (proof the exclusive merge fires on one token)");
 });
 
+// ── #506: the REAL agentic-worker classifier-emit contract drives a guarded split ──────────────────
+// The S7 stubs above (`() => ({ result: outcome })`) prove the ENGINE routes on a published fact, but a
+// bare `{ result }` is NOT what a real `senior:*` fleet agent returns — it completes with the whole
+// Output-contract envelope (`{ status, summary, pr, … }`) and never a bare fact. So the gap #506 closes
+// is: (a) the node's declared `emits` must be threaded into the agent's `appendPrompt` so a real agent
+// is TOLD to surface the fact, and (b) the fact rides that SAME envelope as an extra top-level field.
+// This graph proves both against the real engine: the `adopt` node declares `emits: [result]` and is
+// serviced by a worker that (1) ASSERTS the emit contract reached it via `appendPrompt` — proving the
+// runner actually delivers the instruction, not a test stub — and (2) returns the full envelope with the
+// fact folded in, exactly as a contract-following agent would. Both branches are driven end to end.
+const GUARDED_ADOPT_REAL: DeliveryGraph = {
+  name: "adopt runbook (real agent)",
+  nodes: [
+    {
+      id: "adopt",
+      kind: "agent",
+      agent: { jobType: "senior:feature", prompt: "Adopt the published package into this consumer and open a PR." },
+      emits: [{ name: "result", type: "string", description: "breaking | compatible" }],
+    },
+    { id: "migrate", kind: "agent", agent: { jobType: "senior:migrate" } },
+    { id: "release", kind: "connector", connector: { target: "npm:publish", dedupeKey: "rel-real-1" } },
+  ],
+  edges: [
+    { from: "adopt", to: "migrate", when: "adopt.result", equals: "breaking" },
+    { from: "adopt", to: "release", default: true },
+    { from: "migrate", to: "release" },
+  ],
+};
+
+/** Drive `GUARDED_ADOPT_REAL` with a worker that behaves like a REAL contract-following `senior:feature`
+ *  agent: it reads the emit contract the runner threaded into its `appendPrompt`, then completes with the
+ *  full Output-contract envelope carrying the classifier fact as a top-level field. Returns whether the
+ *  contract actually reached the agent, plus which branches ran. */
+async function driveGuardedRealAgent(outcome: "breaking" | "compatible"): Promise<{
+  state: string;
+  contractDelivered: boolean;
+  factSurfaced: boolean;
+  migrateRan: boolean;
+  releaseRan: boolean;
+}> {
+  const engine = await createWasmEngineClient();
+  try {
+    let contractDelivered = false;
+    let factSurfaced = false;
+    let migrateRan = false;
+    let releaseRan = false;
+
+    await engine.registerWorker("senior:feature", async (job) => {
+      const appendPrompt = String((job.variables as Record<string, unknown> | undefined)?.appendPrompt ?? "");
+      // (a) The classifier emit contract MUST have reached the agent via its steering channel — this is
+      //     the #506 fix (a plain `senior:feature` seed would carry no such instruction).
+      contractDelivered =
+        appendPrompt.includes("Classifier emit contract") &&
+        appendPrompt.includes("`result`") &&
+        appendPrompt.includes("AGENT_RESULT_FILE");
+      factSurfaced = appendPrompt.includes("`result`");
+      // (b) A real agent completes with the WHOLE Output-contract envelope, folding the declared fact in
+      //     as an extra top-level field — NOT a bare `{ result }` stub.
+      return { status: "opened", summary: `adopt done (${outcome})`, pr: "owner/repo#900", result: outcome };
+    });
+    await engine.registerWorker("senior:migrate", async () => {
+      migrateRan = true;
+      return { status: "opened", summary: "migrated", pr: "owner/repo#901" };
+    });
+    await engine.registerWorker(DELIVERY_CONNECTOR_TASK_TYPE, async () => {
+      releaseRan = true;
+      return {};
+    });
+
+    const run = await runDeliveryGraph(engine, GUARDED_ADOPT_REAL);
+    assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
+    const key = run.handle.processInstanceKey;
+
+    let state = "?";
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+      await engine.drain();
+      const [pi] = await engine.searchProcessInstances({ processInstanceKeys: [key] });
+      assert(pi, `no process instance snapshot for ${key}`);
+      state = pi.state ?? "?";
+      if (state === "COMPLETED" || state === "TERMINATED") break;
+    }
+    return { state, contractDelivered, factSurfaced, migrateRan, releaseRan };
+  } finally {
+    await engine.close();
+  }
+}
+
+test("#506 deploy+route: a REAL contract-following agent's envelope carries the classifier fact and routes the BREAKING branch through `migrate`", async () => {
+  const r = await driveGuardedRealAgent("breaking");
+  assert(r.contractDelivered, "the emit contract must reach the agent via its threaded appendPrompt (the #506 fix)");
+  assert(r.factSurfaced, "the declared fact must be named to the agent");
+  assertEquals(r.state, "COMPLETED", "the breaking branch must run to a COMPLETED instance");
+  assert(r.migrateRan, "the breaking outcome (returned inside the real Output-contract envelope) must route through `migrate`");
+  assert(r.releaseRan, "both branches must re-converge on `release`");
+});
+
+test("#506 deploy+route: the SAME real agent returning `compatible` in its envelope rides the default flow, SKIPPING `migrate`", async () => {
+  const r = await driveGuardedRealAgent("compatible");
+  assert(r.contractDelivered, "the emit contract must reach the agent via its threaded appendPrompt (the #506 fix)");
+  assertEquals(r.state, "COMPLETED", "the compatible branch must run to a COMPLETED instance");
+  assert(!r.migrateRan, "the compatible outcome must NOT route through `migrate` — the envelope's `result` rides the default flow");
+  assert(r.releaseRan, "the compatible outcome still reaches `release` via the else-flow");
+});
+
 test("S7 deploy+route: mutually-exclusive leaves join End on an exclusive merge — the untaken leaf never blocks completion", async () => {
   // Mode D: `adopt` routes a missing surface to an escalate (human) leaf, else to a `done` connector
   // leaf. On the default path the escalate leaf never fires; an exclusive End merge must still let the

package/app/deliveryRunner.test.ts

@@ -119,6 +119,39 @@ test("the human node seeds prompt/nodeId/emits; a click-done (no-emit, no-prompt
   assertEquals(ack?.nodeId, "ack");
 });
 
+test("agent node classifier-emit contract (#506): a declared `emits` threads the emit instruction into appendPrompt; a no-emit node leaves it untouched", async () => {
+  // #506: a guarded split (S7) routes on a producer's emitted scalar, published from the engine
+  // variable named exactly after the fact. A real `senior:*` agent completes with the Output-contract
+  // envelope and would never return that fact unless TOLD — so an agent node that declares `emits`
+  // must carry the emit contract in its `appendPrompt` (its only steering channel), while a plain
+  // implementation node (no emits) must be byte-for-byte unchanged.
+  const graph: DeliveryGraph = {
+    name: "classifier",
+    nodes: [
+      { id: "adopt", kind: "agent", agent: { jobType: "senior:feature", prompt: "adopt the package" }, emits: [{ name: "result", type: "string", description: "breaking | compatible" }] },
+      { id: "plain", kind: "agent", agent: { jobType: "senior:feature", prompt: "just implement it" } },
+    ],
+    edges: [{ from: "adopt.result", to: "plain", when: "adopt.result", equals: "breaking" }, { from: "adopt", to: "plain", default: true }],
+  };
+  const p = await prepareOk(graph);
+  const agents = Object.values(p.nodeInputs).filter((v) => "jobType" in v) as Array<Record<string, unknown>>;
+  const adopt = agents.find((v) => String(v.appendPrompt).startsWith("adopt the package"));
+  const plain = agents.find((v) => String(v.appendPrompt).startsWith("just implement it"));
+
+  // The emit-declaring node keeps its authored prompt AND gains the emit contract naming its fact.
+  assert(adopt, "the emit-declaring agent node must be seeded");
+  const adoptPrompt = String(adopt?.appendPrompt);
+  assert(adoptPrompt.startsWith("adopt the package"), "the authored prompt is preserved as the prefix");
+  assert(adoptPrompt.includes("Classifier emit contract"), `the emit contract must be threaded in, got: ${adoptPrompt}`);
+  assert(adoptPrompt.includes("`result`") && adoptPrompt.includes("(string)"), "the declared fact name + type must be surfaced to the agent");
+  assert(adoptPrompt.includes("breaking | compatible"), "the fact's optional description rides the contract");
+  assert(adoptPrompt.includes("AGENT_RESULT_FILE"), "the contract names the completion channel the fact rides");
+
+  // A node that declares NO facts is untouched — appendPrompt is exactly the authored prompt.
+  assertEquals(plain?.appendPrompt, "just implement it");
+});
+
+
 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

@@ -170,6 +170,39 @@ function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
     .replace(`bpmnElement="${DELIVERY_GRAPH_PROCESS_ID}"`, `bpmnElement="${processDefinitionId}"`);
 }
 
+/** Render the classifier-emit contract appended to an `agent` node's `appendPrompt` (issue #506) — the
+ * instruction that turns a declared `emits[]` into completion variables a downstream guarded split (S7)
+ * can route on. A `senior:*` fleet agent completes with the Output-contract envelope (`status`,
+ * `summary`, `pr`, …); the delivery output ioMapping instead publishes the engine variable named exactly
+ * after each fact (`factSourceVar` → `fact.name`), so the agent must ALSO return each declared fact as a
+ * TOP-LEVEL field of that same result JSON. This block tells it so, deriving entirely from the node's
+ * declared `emits` (no second source of truth). Empty for a no-emit node → the prompt is unchanged, so a
+ * plain implementation node behaves exactly as before. Deterministic: fixed wording, facts in declared
+ * order, so identical graphs still compile+seed byte-identically. */
+export function renderEmitContract(emits: readonly DeliveryFact[]): string {
+  if (emits.length === 0) return "";
+  const facts = emits.map((f) => `- \`${f.name}\` (${f.type})${f.description ? ` — ${f.description}` : ""}`);
+  return [
+    "",
+    "",
+    "---",
+    "",
+    "## Classifier emit contract (delivery graph)",
+    "",
+    "This node is a PRODUCER in a delivery graph: a downstream **guarded split** routes on the typed",
+    "fact(s) below. In ADDITION to your normal result fields (`status`, `summary`, `pr`, …), the",
+    "structured result you write to `AGENT_RESULT_FILE` MUST include these TOP-LEVEL fields, each a",
+    "bare scalar of the declared type:",
+    "",
+    ...facts,
+    "",
+    "The value you return for each fact IS the routing decision — a downstream edge fires only when the",
+    "fact equals a specific literal, otherwise the graph takes the `default` (else) branch. If you",
+    "genuinely cannot determine a fact, OMIT it (the default branch is taken) rather than guessing.",
+  ].join("\n");
+}
+
+
 /** Build the `nodeInputs.<element>` seed for one node, per its kind — the exact fields the compiled
  * subProcess ioMapping pulls. Total over the closed kind set. */
 function buildNodeInput(
@@ -177,8 +210,21 @@ function buildNodeInput(
   ctx: { runKey: string; element: string; nodeTimeout: string; probeTimeout: string; probePollEvery: string; escalationSlaTimeout: string; escalationAssignee: string | null },
 ): NodeInput {
   switch (node.kind) {
-    case "agent":
-      return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
+    case "agent": {
+      // Classifier-emit contract (issue #506). A `senior:*` fleet agent's real completion is the
+      // Output-contract envelope (`{ status, summary, pr, … }`) — it does NOT return a bare fact, so a
+      // node's declared `emits` would never appear and a downstream GUARDED split (S7) could only ever
+      // take its `default` branch. Close the gap the same way `factSourceVar` already reads it: the
+      // output ioMapping publishes the engine variable named exactly after each fact, so the agent must
+      // return `{ <fact>: <value> }` AS A TOP-LEVEL field of its result JSON (the same channel that
+      // carries `status`/`summary`/`pr`). The agent only knows to do this if it is TOLD — so the
+      // declared emits are rendered into the node's `appendPrompt` (its sole steering channel; the
+      // delivery agent node carries no base-prompt resource), keeping `emits` the single source of
+      // truth. A no-emit node appends nothing, so a plain implementation node is unchanged.
+      const basePrompt = node.agent.prompt ?? "";
+      const emits = Array.isArray(node.emits) ? node.emits.map((f) => ({ ...f })) : [];
+      return { jobType: node.agent.jobType, appendPrompt: basePrompt + renderEmitContract(emits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
+    }
     case "wait": {
       const probe = parseProbe(node.wait);
       return {

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -268,6 +268,32 @@ resume cannot double-fire.
 > Determinism is preserved: gateway ids are positional over id-sorted nodes, so a graph with no guards
 > compiles byte-for-byte as before.
 
+> **Amendment (issue #506): the agent-node classifier-emit contract.** S7 (above) routes a guarded
+> split on a producer's emitted scalar, published to `<producerElement>_<fact>` by the node's output
+> ioMapping — which, for an `agent`/`connector` node, reads the engine variable named exactly after the
+> fact (`factSourceVar` → `fact.name`). A REAL `senior:*` fleet agent, though, completes with its
+> **Output-contract envelope** (`{ status, summary, pr, question, delta }`) and never a bare
+> `{ <fact>: <value> }`, so a guarded split authored on a `senior:feature` node compiled + was
+> deadlock-safe (the `default` else-flow fires when the fact is unset) but its non-default branch was
+> **inert** — the migrate/escalate arm never fired. The contract that closes this:
+> - An `agent` node's declared `emits[]` is threaded into the node's `appendPrompt` (its sole steering
+>   channel — the delivery agent node carries no base-prompt resource) as a **classifier emit contract**
+>   block (`deliveryRunner.renderEmitContract`), instructing the servicing agent to ALSO return each
+>   declared fact as a **top-level field** of its result JSON — the very same `AGENT_RESULT_FILE`
+>   channel that already carries `status`/`summary`/`pr`. The fleet harness merges that JSON into the
+>   job completion variables, so `<fact.name>` lands in scope exactly where the output ioMapping reads
+>   it. `emits` stays the single source of truth: the contract text is derived from it, never a parallel
+>   declaration.
+> - The convention a graph author relies on: declare `emits: [{ name, type }]` on the agent node and
+>   guard the downstream edge with `when: "<node>.<name>"` + `equals: <literal>`; a contract-following
+>   agent returns `{ …, <name>: <value> }` and the split routes on it. Omitting the fact (the agent
+>   could not decide) takes the `default` branch — the deadlock-safe fallback S7 already guarantees.
+> - A no-emit agent node appends nothing, so a plain implementation node is byte-for-byte unchanged.
+>   The `deploy+route` coverage now drives BOTH branches with a **real contract-following worker** (it
+>   asserts the emit contract reached it via `appendPrompt`, then completes with the full envelope
+>   carrying the fact), not a bare-`{ result }` stub — proving the instruction is actually delivered and
+>   the real completion shape routes.
+
 ## Open questions
 
 - **Compiler target for the first cut** — confirm compile-to-native (diagram + native scheduling) vs a

package/docs/agent-guide.md

@@ -448,6 +448,23 @@ A **typed fact** (`emits[]` entry) is `{ name, type, description? }` where
 downstream as `<nodeId>.<name>`. A "click done" human node or a pass-through node declares
 no facts.
 
+**Guarded routing + the agent classifier-emit contract.** An edge may carry a **guard** —
+`when: "<nodeId>.<fact>"` + `equals: <scalar>` — or be the split's single `default: true`
+else-branch (S7). A node whose out-edges are guarded is a **data-based exclusive split**: at
+runtime exactly one branch fires, chosen by the producer's emitted fact. For an **`agent`**
+node the fact is late-bound from the servicing job's completion: the delivery output-mapping
+publishes the engine variable named **exactly after the fact** (e.g. a fact `result` reads the
+completion variable `result`). A real `senior:*` fleet agent completes with its **Output
+contract** envelope (`{ status, summary, pr, question, delta }`), so — to make a guarded split
+fire — an agent node that declares `emits` has a **classifier emit contract** automatically
+appended to its prompt at dispatch: the agent MUST return each declared fact as an **extra
+top-level field of the same result JSON** (the `AGENT_RESULT_FILE` it already writes
+`status`/`summary`/`pr` to). Author side, this means: declare `emits: [{ name, type }]` on the
+agent node and guard the downstream edge on `<node>.<name>`; a contract-following agent returns
+`{ …, <name>: <value> }` and the split routes on it. If the agent cannot decide the fact it
+**omits** it, and the split takes its `default` (else) branch — the deadlock-safe fallback. A
+node that declares no `emits` gets no contract text and behaves exactly as before.
+
 ### 9.2 The agent loop: draft → compile → stage → ask an operator to dispatch
 
 ```

package/openapi.yaml

@@ -1392,7 +1392,17 @@ components:
           properties:
             id: { type: string }
             kind: { type: string, enum: [agent] }
-            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            emits:
+              type: array
+              items: { $ref: "#/components/schemas/DeliveryFact" }
+              description: >-
+                The typed facts this agent node hands forward (issue #506 — the classifier-emit
+                contract). Each declared fact is appended to the node's dispatch prompt as an
+                instruction the servicing `senior:*` agent MUST honour: return the fact as an extra
+                TOP-LEVEL field of its result JSON (the same `AGENT_RESULT_FILE` envelope that carries
+                `status`/`summary`/`pr`). The delivery output-mapping publishes that completion variable
+                (named exactly after the fact) so a downstream guarded edge (`when: "<node>.<fact>"` +
+                `equals`) routes on it; an omitted fact takes the split's `default` branch.
             agent:
               type: object
               additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.135.0",
+  "version": "0.136.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.81.0",
+    "@nanobpm/urban": "^0.82.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {