@nanobpm/workflow 0.9.0 → 0.10.0

package/README.md

@@ -53,6 +53,15 @@ human-in-the-loop path), composed with control-flow combinators:
   `itemVar`). `{ sequential }` runs children one at a time; `{ outputCollection,
   outputElement }` collects each child's result into a list; `{ completionCondition }`
   completes the body early.
+- `w.race({ armName: { signal | timer, do }, … })` — a first-of race over ≥2
+  named arms, each waiting on **exactly one** event: a `signal` (a correlated
+  message catch, `{ correlationKey }`) or a `timer` (`{ after }` for a duration or
+  `{ at }` for a date, ISO or a leading-`=` FEEL expression). Whichever arm's event
+  fires **first wins**: its `do` block runs and the losers are cancelled. Compiles
+  to an **event-based gateway** fanning out to one intermediate catch event per arm
+  (a message- or timer-event-definition), the arm bodies rejoining downstream by an
+  implicit XOR merge. This is the shape a convergence loop uses to bound a
+  human-in-the-loop wait with a timeout.
 
 ```ts
 import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";
@@ -94,13 +103,35 @@ const convergence = defineFlow("convergence-loop", (w) => {
 });
 ```
 
-Each combinator compiles to a BPMN primitive the engine already runs: `switch` /
+Bound a human-in-the-loop wait with a timeout — `w.race` resolves to whichever
+arm fires first, cancelling the loser:
+
+```ts
+const reviewWait = defineFlow("review-wait", (w) => {
+  w.run("request-review", async (job) => ({ prKey: job.variables.prKey }));
+  w.race({
+    "review-arrived": {
+      signal: { correlationKey: "prKey" },
+      do: (b) => b.run("apply-review", applyReview),
+    },
+    "review-timed-out": {
+      timer: { after: "=reviewWaitTimeout" }, // FEEL duration, e.g. "PT48H"
+      do: (b) => b.run("escalate", escalate),
+    },
+  });
+  w.run("finalize", finalize);
+});
+```
+
+`switch` /
 `branch` → an exclusive gateway (in-order conditions, first match wins, default =
 unconditional flow); `loop` → a convergent gateway whose body falls through back to
 the head; nodes with multiple incoming flows are an implicit XOR merge; `parallel`
 → a diverging/converging **parallel gateway** pair (AND fork/join); `forEach` → a
 **parallel multi-instance** activity (a single-step body) or an embedded
-multi-instance sub-process (a multi-step body). See **ADR 0047**.
+multi-instance sub-process (a multi-step body); `race` → an **event-based
+gateway** fanning out to one intermediate catch event per arm (message or timer),
+first event wins and cancels the losers. See **ADR 0047**.
 
 #### Typed data envelopes (eject to model-first with contracts intact)
 
@@ -128,6 +159,46 @@ const orders = defineFlow(
 );
 ```
 
+#### Agent tasks — bind an LLM prompt to a worker (`w.task(name, { prompt })`)
+
+An **agent service task** is a `w.task` that additionally binds an LLM **prompt
+resource** to the worker that services it. Pass a `prompt` alongside the
+`jobType` capability token and the emitter adds a
+`<zeebe:linkedResource … resourceType="GenericScript" linkName="prompt">` to the
+task's `zeebe:taskDefinition` — the shape the nano-workforce agent tasks use to
+attach a prompt script to the (e.g. `senior:retro`) agent pool that runs the job:
+
+```ts
+w.task("synthesize", {
+  jobType: "senior:retro",              // the agent capability token
+  prompt: {
+    resourceId: "retro.md",             // the GenericScript resource bound as the prompt
+    bindingType: "latest",              // optional — how the version resolves (default "latest")
+    append: "=retroDigest",             // optional — FEEL fed to a zeebe:ioMapping `appendPrompt` input
+  },
+});
+```
+
+derives:
+
+```xml
+<bpmn:serviceTask id="synthesize" name="synthesize">
+  <bpmn:extensionElements>
+    <zeebe:taskDefinition type="senior:retro" />
+    <zeebe:linkedResources>
+      <zeebe:linkedResource resourceId="retro.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+    </zeebe:linkedResources>
+    <zeebe:ioMapping>
+      <zeebe:input source="=retroDigest" target="appendPrompt" />
+    </zeebe:ioMapping>
+  </bpmn:extensionElements>
+</bpmn:serviceTask>
+```
+
+Only `resourceId` is required; omit `append` and no `ioMapping` is emitted. A
+`w.task` **without** a `prompt` is unchanged — it emits no `linkedResources`.
+Data envelopes (via contracts) still lift alongside the prompt binding.
+
 ### Imperative (Temporal-style, engine-replayed) — experimental/internal
 
 Write the orchestration as a function. `ctx.run(name, fn)` is a durable step: its

package/dist/declarative.d.ts

@@ -288,12 +288,18 @@ export interface EmitApi {
     /** Place a fully custom BPMN element (a slice's own render closure). */
     addNode(node: RenderNode): void;
     /** Place a `<bpmn:serviceTask>` with the standard taskDefinition/envelope
-     *  extension elements (optionally with multi-instance characteristics). */
+     *  extension elements. `opts.mi` adds multi-instance characteristics; `opts.extraExt`
+     *  injects additional `<bpmn:extensionElements>` content (e.g. a
+     *  `zeebe:linkedResources` prompt binding) after the taskDefinition/properties,
+     *  so a variant task only supplies its delta rather than re-rendering the shell. */
     addServiceTask(node: {
         name: string;
         envelopes?: NodeEnvelopes;
         jobType?: string;
-    }, mi?: string): void;
+    }, opts?: {
+        mi?: string;
+        extraExt?: string;
+    }): void;
     /** Place a `<bpmn:intermediateCatchEvent>` with a message event definition. */
     addCatchEvent(node: {
         name: string;

package/dist/declarative.js

@@ -356,7 +356,7 @@ class Compiler {
             addNode: (node) => {
                 this.nodes.push({ ...node, scope: node.scope ?? this.currentScope() });
             },
-            addServiceTask: (node, mi) => this.addServiceTask(node, mi),
+            addServiceTask: (node, opts) => this.addServiceTask(node, opts),
             addCatchEvent: (node) => this.addCatchEvent(node),
             addTimerCatchEvent: (node) => this.addTimerCatchEvent(node),
             addGateway: (id, name) => this.addGateway(id, name),
@@ -404,7 +404,8 @@ class Compiler {
         }
         this.envelopes.set(env.name, env.fields);
     }
-    addServiceTask(node, mi = "") {
+    addServiceTask(node, opts = {}) {
+        const { mi = "", extraExt = "" } = opts;
         const type = node.jobType ?? jobType(this.flow.id, node.name);
         this.recordEnvelope(node.envelopes?.in);
         this.recordEnvelope(node.envelopes?.out);
@@ -416,6 +417,7 @@ class Compiler {
         const ext = `      <bpmn:extensionElements>\n` +
             `        <zeebe:taskDefinition type="${escapeXml(type)}" />\n` +
             (props.length ? `        <zeebe:properties>\n${props.join("\n")}\n        </zeebe:properties>\n` : "") +
+            extraExt +
             `      </bpmn:extensionElements>`;
         const id = node.name;
         this.nodes.push({

package/dist/nodes/forEach.js

@@ -82,9 +82,14 @@ registerNodeKind("forEach", {
         const only = node.body.length === 1 ? node.body[0] : undefined;
         // A single service-task body carries the MI characteristics directly; a
         // multi-step body is wrapped in an embedded MI sub-process (its own token
-        // scope, with its own start/end).
-        if (only && (only.kind === "run" || only.kind === "task")) {
-            api.addServiceTask(only, mi);
+        // scope, with its own start/end). A prompt-carrying `task` is deliberately
+        // EXCLUDED from this fast path: computing its `zeebe:linkedResources`/
+        // `appendPrompt` delta lives in the `task` kind's own emitter, so lifting it
+        // here would silently drop that binding. It falls through to the sub-process
+        // path, where the `task` emitter renders the agent service task (prompt
+        // intact) inside the MI scope.
+        if (only && (only.kind === "run" || (only.kind === "task" && only.prompt === undefined))) {
+            api.addServiceTask(only, { mi });
             api.connect(incoming, only.name);
             return [api.newEdge(only.name)];
         }

package/dist/nodes/index.d.ts

@@ -4,6 +4,7 @@ import "./continue.js";
 import "./forEach.js";
 import "./loop.js";
 import "./parallel.js";
+import "./race.js";
 import "./run.js";
 import "./signal.js";
 import "./switch.js";

package/dist/nodes/index.js

@@ -11,6 +11,7 @@ import "./continue.js";
 import "./forEach.js";
 import "./loop.js";
 import "./parallel.js";
+import "./race.js";
 import "./run.js";
 import "./signal.js";
 import "./switch.js";

package/dist/nodes/race.d.ts

@@ -0,0 +1,54 @@
+import type { FlowNode } from "../types.js";
+import type { Block } from "../declarative.js";
+/** One arm of a {@link FlowBuilder.race}: exactly one waited-for event — a
+ *  `signal` (a message catch correlated on a process variable) OR a `timer` (a
+ *  delay `{ after }` or an instant `{ at }`) — plus the `do` body that runs when
+ *  that event wins the race. */
+export type RaceArm = ({
+    signal: {
+        correlationKey: string;
+    };
+} | {
+    timer: {
+        after: string;
+    } | {
+        at: string;
+    };
+}) & {
+    do: Block;
+};
+/** A compiled race arm: its catch event (a `signal` or `timer` `FlowNode`, reused
+ *  from the built-ins) and the body that runs when it wins. */
+interface CompiledArm {
+    event: FlowNode;
+    body: FlowNode[];
+}
+declare module "../types.js" {
+    interface FlowNodeRegistry {
+        race: {
+            kind: "race";
+            arms: CompiledArm[];
+        };
+    }
+}
+declare module "../declarative.js" {
+    interface FlowBuilder<C extends object> {
+        /**
+         * A first-of event race — a BPMN event-based gateway. Each named arm waits on
+         * exactly one event: a `signal` (a durable message catch correlated on a
+         * process variable) or a `timer` (`{ after }` a delay, or `{ at }` an
+         * instant). The engine arms every catch at once; the FIRST to fire wins, its
+         * arm's `do` body runs, and the losing catch events are cancelled. Every arm's
+         * body converges on whatever follows the race.
+         *
+         * ```ts
+         * w.race({
+         *   "review-ready":   { signal: { correlationKey: "prKey" }, do: (b) => b.run("re-review", reReview) },
+         *   "review-timeout": { timer:  { after: "=reviewWaitTimeout" }, do: (b) => b.run("escalate", escalate) },
+         * });
+         * ```
+         */
+        race(arms: Record<string, RaceArm>): FlowBuilder<C>;
+    }
+}
+export {};

package/dist/nodes/race.js

@@ -0,0 +1,134 @@
+// Flow-node kind: `race` — a first-of event race (a BPMN event-based gateway).
+// The gateway forks to one intermediate catch event per arm — a MESSAGE catch for
+// a `signal` arm (correlated on a process variable) or a TIMER catch for a `timer`
+// arm — and the engine arms them all at once. The FIRST event to fire wins: its
+// arm's `do` body runs and the losing catch events are cancelled; each arm's body
+// then converges on whatever follows the race.
+//
+// Contributed entirely from this module through the wave-0 extension seam (epic
+// #314, S1/#316): its `FlowNode` variant (declaration-merged into the augmentable
+// `FlowNodeRegistry`), its `w.race(...)` builder method (merged into
+// `FlowBuilder<C>`), and its `walk`/`emit` handlers — with NO edit to the shared
+// `FlowNode` union, the `walkNodes`/`emitNode` dispatch, or the generated barrel.
+//
+// The catch arms are modelled as nested `signal`/`timer` `FlowNode`s so the whole
+// machine reuses the built-ins: `walk` recurses into them (so the shared message
+// emitter lifts each `signal` arm's `<bpmn:message>` + correlation subscription
+// automatically, and `WorkflowClient.signal` can correlate to it), and `emit`
+// dispatches each arm's catch through its own registered handler (so a race's
+// catch is byte-identical to a standalone `w.signal`/`w.timer`). Only the
+// event-based gateway itself is placed here.
+import { incomingOutgoing } from "../declarative.js";
+import { assertIdent, assertTimerDate, assertTimerDuration, escapeXml } from "../xml.js";
+import { registerNodeKind, requireNodeKind } from "./registry.js";
+function hasSignal(spec) {
+    return "signal" in spec && spec.signal !== null && typeof spec.signal === "object";
+}
+function hasTimer(spec) {
+    return "timer" in spec && spec.timer !== null && typeof spec.timer === "object";
+}
+registerNodeKind("race", {
+    build: (api) => (arms) => {
+        if (arms === null || typeof arms !== "object") {
+            throw new Error(`race() needs an arms object { "<name>": { signal | timer, do } }`);
+        }
+        const entries = Object.entries(arms);
+        if (entries.length < 2) {
+            throw new Error(`race() needs at least two arms (an event-based gateway with fewer than two events is degenerate)`);
+        }
+        const compiled = [];
+        for (const [name, spec] of entries) {
+            if (spec === null || typeof spec !== "object") {
+                throw new Error(`race() arm "${name}" must be an object { signal | timer, do }`);
+            }
+            const isSignal = hasSignal(spec);
+            const isTimer = hasTimer(spec);
+            if (isSignal === isTimer) {
+                throw new Error(`race() arm "${name}" needs exactly one of { signal: { correlationKey } } or { timer: { after | at } }`);
+            }
+            if (typeof spec.do !== "function") {
+                throw new Error(`race() arm "${name}" needs a do block (b) => {…}`);
+            }
+            api.claim(name);
+            let event;
+            if (isSignal) {
+                const rawKey = spec.signal.correlationKey;
+                if (typeof rawKey !== "string" || rawKey.trim() === "") {
+                    throw new Error(`race() arm "${name}" signal needs a non-empty { correlationKey }`);
+                }
+                // Trim before validating/storing, in parity with the timer arm ({ after }/
+                // { at } are trimmed above): a value like " prKey " is usable after
+                // trimming, so it must not fail the NCName check on stray whitespace. The
+                // assertIdent context names the arm so a failure says WHICH arm is invalid.
+                const correlationKey = rawKey.trim();
+                assertIdent(`race() arm "${name}" signal correlationKey`, correlationKey);
+                event = { kind: "signal", name, correlationKey, payload: api.contracts[name]?.in };
+            }
+            else {
+                const timer = spec.timer;
+                // Enforce exactly-one on KEY PRESENCE, not string-ness: a runtime-invalid
+                // arm that supplies both keys where only one is a string (e.g.
+                // `{ after: 1, at: "…" }`) must be rejected here, not silently dispatched
+                // into `after.trim()` — which would throw an opaque TypeError. Once the
+                // branch is chosen, validate the value is a string before trimming.
+                const hasAfterKey = "after" in timer;
+                const hasAtKey = "at" in timer;
+                if (hasAfterKey === hasAtKey) {
+                    throw new Error(`race() arm "${name}" timer needs exactly one of { after } (a delay) or { at } (an instant)`);
+                }
+                if ("after" in timer) {
+                    if (typeof timer.after !== "string") {
+                        throw new Error(`race() arm "${name}" timer { after } must be a string duration`);
+                    }
+                    const after = timer.after.trim();
+                    assertTimerDuration(`race() arm "${name}" timer after`, after);
+                    event = { kind: "timer", name, after };
+                }
+                else {
+                    if (typeof timer.at !== "string") {
+                        throw new Error(`race() arm "${name}" timer { at } must be a string instant`);
+                    }
+                    const at = timer.at.trim();
+                    assertTimerDate(`race() arm "${name}" timer at`, at);
+                    event = { kind: "timer", name, at };
+                }
+            }
+            compiled.push({ event, body: api.child(spec.do, false) });
+        }
+        api.out.push({ kind: "race", arms: compiled });
+        return api.self();
+    },
+    walk: (node, recurse) => {
+        // Recurse into each arm's catch event AND its body: the catch `signal` nodes
+        // must be visited so the shared message emitter lifts their `<bpmn:message>`
+        // + correlation subscription, and body `task` nodes so their external job
+        // types are discovered — exactly as a standalone `signal`/`task` would be.
+        for (const arm of node.arms)
+            recurse([arm.event, ...arm.body]);
+    },
+    emit: (node, incoming, loop, api) => {
+        const gwId = `Gw_${api.nextGw()}`;
+        api.addNode(eventBasedGateway(gwId, api.currentScope()));
+        api.connect(incoming, gwId);
+        const out = [];
+        for (const arm of node.arms) {
+            // Fork the gateway straight to the arm's catch event (BPMN requires an
+            // event-based gateway's targets to be intermediate catch events), reusing
+            // the arm kind's own registered emit so the catch is identical to a
+            // standalone `w.signal`/`w.timer`; then wire its `do` body onward.
+            const fork = api.newEdge(gwId);
+            const afterCatch = requireNodeKind(arm.event.kind).emit(arm.event, [fork], loop, api);
+            out.push(...api.emitList(arm.body, afterCatch, loop));
+        }
+        return out;
+    },
+});
+/** A `<bpmn:eventBasedGateway>` render node (no typed `EmitApi` primitive exists —
+ *  built as a custom {@link RenderNode} from the exported string helpers). */
+function eventBasedGateway(id, scope) {
+    return {
+        id,
+        scope,
+        render: (inc, outg) => `    <bpmn:eventBasedGateway id="${escapeXml(id)}">\n` + incomingOutgoing(inc, outg) + `    </bpmn:eventBasedGateway>`,
+    };
+}

package/dist/nodes/signal.js

@@ -6,10 +6,15 @@ import { registerNodeKind } from "./registry.js";
 registerNodeKind("signal", {
     build: (api) => (name, opts) => {
         api.claim(name);
-        if (!opts || !opts.correlationKey)
+        if (!opts || typeof opts.correlationKey !== "string" || opts.correlationKey.trim() === "") {
             throw new Error(`signal("${name}") needs { correlationKey }`);
-        assertIdent("correlationKey", opts.correlationKey);
-        api.out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: api.contracts[name]?.in });
+        }
+        // Trim before validating/storing, in parity with the race() signal arm: a
+        // value like " prKey " is usable after trimming, so it must not fail the
+        // NCName check on stray whitespace. Name the node in the assertIdent context.
+        const correlationKey = opts.correlationKey.trim();
+        assertIdent(`signal("${name}") correlationKey`, correlationKey);
+        api.out.push({ kind: "signal", name, correlationKey, payload: api.contracts[name]?.in });
         return api.self();
     },
     emit: (node, incoming, _loop, api) => {

package/dist/nodes/task.d.ts

@@ -1,3 +1,22 @@
+/** Binds an LLM prompt resource to an agent service task. Emits, alongside the
+ *  task's `zeebe:taskDefinition` capability token, a
+ *  `<zeebe:linkedResources><zeebe:linkedResource resourceId=… bindingType=…
+ *  resourceType="GenericScript" linkName="prompt"/></zeebe:linkedResources>`
+ *  extension — the shape the nano-workforce agent tasks use to attach a prompt
+ *  script to the worker that services the job. */
+export interface PromptBinding {
+    /** The `GenericScript` resource id bound as the prompt (the linkedResource
+     *  `resourceId`, e.g. `"retro.md"`). Required and non-empty. */
+    resourceId: string;
+    /** The linkedResource `bindingType` — how the engine resolves the resource
+     *  version at deploy time. Defaults to `"latest"`. */
+    bindingType?: string;
+    /** Optional prompt addendum: a FEEL expression (or literal) fed to the worker
+     *  through a `<zeebe:ioMapping><zeebe:input source=… target="appendPrompt"/>`
+     *  input, the convention the agent tasks use to append runtime context to the
+     *  bound prompt. Omitted → no `ioMapping` is emitted. */
+    append?: string;
+}
 declare module "../types.js" {
     interface FlowNodeRegistry {
         task: {
@@ -5,7 +24,24 @@ declare module "../types.js" {
             name: string;
             envelopes?: NodeEnvelopes;
             jobType?: string;
+            /** The agent prompt binding, when the task is an LLM-agent service task. */
+            prompt?: PromptBinding;
         };
     }
 }
-export {};
+declare module "../declarative.js" {
+    interface FlowBuilder<C extends object> {
+        /**
+         * An AGENT external service task: as `task`, but additionally binds an LLM
+         * `prompt` resource to the worker via a `zeebe:linkedResource`
+         * (`resourceType="GenericScript" linkName="prompt"`). Pair it with a
+         * `{ jobType }` capability token (e.g. `senior:retro`) so an agent pool
+         * services it. `prompt.append` (optional) feeds a FEEL expression to the
+         * worker through a `zeebe:ioMapping` `appendPrompt` input.
+         */
+        task<K extends string>(name: K, opts: {
+            jobType?: string;
+            prompt: PromptBinding;
+        }): FlowBuilder<C>;
+    }
+}

package/dist/nodes/task.js

@@ -2,19 +2,95 @@
 // OUTSIDE this program (no locally-hosted handler). Its job type defaults to the
 // derived `${flowId}:${name}` unless overridden with `{ jobType }`. Contributed
 // from this module through the extension seam (epic #314, S0/#315).
-import { assertJobType } from "../xml.js";
+//
+// This module also owns the AGENT PROMPT BINDING (epic #314, S4/#319): an
+// optional `{ prompt }` option binds an LLM prompt resource to the worker via a
+// `<zeebe:linkedResource … resourceType="GenericScript" linkName="prompt">`,
+// mirroring the nano-workforce agent service tasks. The extension is contributed
+// entirely from this module — the `task` node's own registered emit handler and
+// its option type — WITHOUT re-opening the shared `FlowNode` union, the central
+// `walkNodes`/`emitNode` dispatch, or the generated barrel.
+import { assertJobType, escapeXml } from "../xml.js";
 import { registerNodeKind } from "./registry.js";
+/** Normalize + validate a prompt binding at authoring time, applying the
+ *  `bindingType` default. Emitted string fields are trimmed before storing (in
+ *  parity with how `timer` normalizes `{ after }`/`{ at }`), so a value like
+ *  `resourceId: " retro.md "` passes validation AND is emitted without stray
+ *  surrounding whitespace. Returns a fully-resolved binding stored on the node. */
+function resolvePrompt(name, prompt) {
+    if (typeof prompt !== "object" || prompt === null) {
+        throw new Error(`task("${name}") prompt must be an object with a non-empty resourceId`);
+    }
+    const resourceId = prompt.resourceId;
+    if (typeof resourceId !== "string" || resourceId.trim() === "") {
+        throw new Error(`task("${name}") prompt.resourceId must be a non-empty string`);
+    }
+    // Only an ABSENT bindingType defaults to "latest"; `??` would also swallow an
+    // explicit `null`, masking an authoring mistake. Distinguish `undefined` (use
+    // the default) from any other non-string (reject), in parity with how `append`
+    // below treats `!== undefined` as "provided, so validate strictly".
+    const bindingType = prompt.bindingType === undefined ? "latest" : prompt.bindingType;
+    if (typeof bindingType !== "string" || bindingType.trim() === "") {
+        throw new Error(`task("${name}") prompt.bindingType must be a non-empty string`);
+    }
+    const resolved = { resourceId: resourceId.trim(), bindingType: bindingType.trim() };
+    if (prompt.append !== undefined) {
+        if (typeof prompt.append !== "string" || prompt.append.trim() === "") {
+            throw new Error(`task("${name}") prompt.append must be a non-empty string when provided`);
+        }
+        resolved.append = prompt.append.trim();
+    }
+    return resolved;
+}
+/** Build the prompt-specific `<bpmn:extensionElements>` delta appended to the
+ *  shared service-task emission: the `zeebe:linkedResources` prompt binding and
+ *  (optionally) a `zeebe:ioMapping` `appendPrompt` input. The task shell
+ *  (taskDefinition + envelope properties) is rendered by the built-in
+ *  `EmitApi.addServiceTask`, so this variant only contributes its delta and the
+ *  envelope serialization can never drift from the plain service task. */
+function promptExtensions(prompt) {
+    const { resourceId, bindingType, append } = prompt;
+    const linked = `        <zeebe:linkedResources>\n` +
+        `          <zeebe:linkedResource resourceId="${escapeXml(resourceId)}" ` +
+        `bindingType="${escapeXml(bindingType ?? "latest")}" resourceType="GenericScript" linkName="prompt" />\n` +
+        `        </zeebe:linkedResources>\n`;
+    const io = append !== undefined
+        ? `        <zeebe:ioMapping>\n` +
+            `          <zeebe:input source="${escapeXml(append)}" target="appendPrompt" />\n` +
+            `        </zeebe:ioMapping>\n`
+        : "";
+    return linked + io;
+}
 registerNodeKind("task", {
     build: (api) => (name, opts) => {
         api.claim(name);
         const override = opts?.jobType;
         if (override !== undefined)
             assertJobType("task jobType", override);
-        api.out.push({ kind: "task", name, envelopes: api.contractEnvelopes(name), jobType: override });
+        const prompt = opts?.prompt !== undefined ? resolvePrompt(name, opts.prompt) : undefined;
+        api.out.push({
+            kind: "task",
+            name,
+            envelopes: api.contractEnvelopes(name),
+            jobType: override,
+            prompt,
+        });
         return api.self();
     },
     emit: (node, incoming, _loop, api) => {
-        api.addServiceTask(node);
+        // No prompt → the standard service-task emission is preserved unchanged (no
+        // `linkedResources` are emitted).
+        if (node.prompt === undefined) {
+            api.addServiceTask(node);
+            api.connect(incoming, node.name);
+            return [api.newEdge(node.name)];
+        }
+        // Prompt binding present → the shared `addServiceTask` renders the task
+        // shell (taskDefinition + envelope properties, recording envelopes); we only
+        // supply the `zeebe:linkedResource` (and optional `appendPrompt` ioMapping)
+        // delta, so the envelope/taskDefinition serialization has a single source.
+        const prompt = node.prompt;
+        api.addServiceTask(node, { extraExt: promptExtensions(prompt) });
         api.connect(incoming, node.name);
         return [api.newEdge(node.name)];
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway through @nanobpm/nano-sdk (the shared engine-transport spine — ADR 0055), which negotiates the Falcon protocol on a Nano server and REST elsewhere.",
   "type": "module",
   "license": "Apache-2.0",

package/src/declarative.ts

@@ -622,8 +622,14 @@ export interface EmitApi {
   /** Place a fully custom BPMN element (a slice's own render closure). */
   addNode(node: RenderNode): void;
   /** Place a `<bpmn:serviceTask>` with the standard taskDefinition/envelope
-   *  extension elements (optionally with multi-instance characteristics). */
-  addServiceTask(node: { name: string; envelopes?: NodeEnvelopes; jobType?: string }, mi?: string): void;
+   *  extension elements. `opts.mi` adds multi-instance characteristics; `opts.extraExt`
+   *  injects additional `<bpmn:extensionElements>` content (e.g. a
+   *  `zeebe:linkedResources` prompt binding) after the taskDefinition/properties,
+   *  so a variant task only supplies its delta rather than re-rendering the shell. */
+  addServiceTask(
+    node: { name: string; envelopes?: NodeEnvelopes; jobType?: string },
+    opts?: { mi?: string; extraExt?: string },
+  ): void;
   /** Place a `<bpmn:intermediateCatchEvent>` with a message event definition. */
   addCatchEvent(node: { name: string }): void;
   /** Place a `<bpmn:intermediateCatchEvent>` with a timer event definition. */
@@ -674,7 +680,7 @@ class Compiler {
       addNode: (node) => {
         this.nodes.push({ ...node, scope: node.scope ?? this.currentScope() });
       },
-      addServiceTask: (node, mi) => this.addServiceTask(node, mi),
+      addServiceTask: (node, opts) => this.addServiceTask(node, opts),
       addCatchEvent: (node) => this.addCatchEvent(node),
       addTimerCatchEvent: (node) => this.addTimerCatchEvent(node),
       addGateway: (id, name) => this.addGateway(id, name),
@@ -727,7 +733,11 @@ class Compiler {
     this.envelopes.set(env.name, env.fields);
   }
 
-  private addServiceTask(node: { name: string; envelopes?: NodeEnvelopes; jobType?: string }, mi = ""): void {
+  private addServiceTask(
+    node: { name: string; envelopes?: NodeEnvelopes; jobType?: string },
+    opts: { mi?: string; extraExt?: string } = {},
+  ): void {
+    const { mi = "", extraExt = "" } = opts;
     const type = node.jobType ?? jobType(this.flow.id, node.name);
     this.recordEnvelope(node.envelopes?.in);
     this.recordEnvelope(node.envelopes?.out);
@@ -738,6 +748,7 @@ class Compiler {
       `      <bpmn:extensionElements>\n` +
       `        <zeebe:taskDefinition type="${escapeXml(type)}" />\n` +
       (props.length ? `        <zeebe:properties>\n${props.join("\n")}\n        </zeebe:properties>\n` : "") +
+      extraExt +
       `      </bpmn:extensionElements>`;
     const id = node.name;
     this.nodes.push({

package/src/nodes/forEach.ts

@@ -115,9 +115,14 @@ registerNodeKind("forEach", {
     const only = node.body.length === 1 ? node.body[0] : undefined;
     // A single service-task body carries the MI characteristics directly; a
     // multi-step body is wrapped in an embedded MI sub-process (its own token
-    // scope, with its own start/end).
-    if (only && (only.kind === "run" || only.kind === "task")) {
-      api.addServiceTask(only, mi);
+    // scope, with its own start/end). A prompt-carrying `task` is deliberately
+    // EXCLUDED from this fast path: computing its `zeebe:linkedResources`/
+    // `appendPrompt` delta lives in the `task` kind's own emitter, so lifting it
+    // here would silently drop that binding. It falls through to the sub-process
+    // path, where the `task` emitter renders the agent service task (prompt
+    // intact) inside the MI scope.
+    if (only && (only.kind === "run" || (only.kind === "task" && only.prompt === undefined))) {
+      api.addServiceTask(only, { mi });
       api.connect(incoming, only.name);
       return [api.newEdge(only.name)];
     }

package/src/nodes/index.ts

@@ -12,6 +12,7 @@ import "./continue.js";
 import "./forEach.js";
 import "./loop.js";
 import "./parallel.js";
+import "./race.js";
 import "./run.js";
 import "./signal.js";
 import "./switch.js";

package/src/nodes/race.ts

@@ -0,0 +1,185 @@
+// Flow-node kind: `race` — a first-of event race (a BPMN event-based gateway).
+// The gateway forks to one intermediate catch event per arm — a MESSAGE catch for
+// a `signal` arm (correlated on a process variable) or a TIMER catch for a `timer`
+// arm — and the engine arms them all at once. The FIRST event to fire wins: its
+// arm's `do` body runs and the losing catch events are cancelled; each arm's body
+// then converges on whatever follows the race.
+//
+// Contributed entirely from this module through the wave-0 extension seam (epic
+// #314, S1/#316): its `FlowNode` variant (declaration-merged into the augmentable
+// `FlowNodeRegistry`), its `w.race(...)` builder method (merged into
+// `FlowBuilder<C>`), and its `walk`/`emit` handlers — with NO edit to the shared
+// `FlowNode` union, the `walkNodes`/`emitNode` dispatch, or the generated barrel.
+//
+// The catch arms are modelled as nested `signal`/`timer` `FlowNode`s so the whole
+// machine reuses the built-ins: `walk` recurses into them (so the shared message
+// emitter lifts each `signal` arm's `<bpmn:message>` + correlation subscription
+// automatically, and `WorkflowClient.signal` can correlate to it), and `emit`
+// dispatches each arm's catch through its own registered handler (so a race's
+// catch is byte-identical to a standalone `w.signal`/`w.timer`). Only the
+// event-based gateway itself is placed here.
+
+import type { FlowNode } from "../types.js";
+import type { Block, Edge, RenderNode } from "../declarative.js";
+import { incomingOutgoing } from "../declarative.js";
+import { assertIdent, assertTimerDate, assertTimerDuration, escapeXml } from "../xml.js";
+import { registerNodeKind, requireNodeKind } from "./registry.js";
+
+/** One arm of a {@link FlowBuilder.race}: exactly one waited-for event — a
+ *  `signal` (a message catch correlated on a process variable) OR a `timer` (a
+ *  delay `{ after }` or an instant `{ at }`) — plus the `do` body that runs when
+ *  that event wins the race. */
+export type RaceArm = ({ signal: { correlationKey: string } } | { timer: { after: string } | { at: string } }) & {
+  do: Block;
+};
+
+/** A compiled race arm: its catch event (a `signal` or `timer` `FlowNode`, reused
+ *  from the built-ins) and the body that runs when it wins. */
+interface CompiledArm {
+  event: FlowNode;
+  body: FlowNode[];
+}
+
+declare module "../types.js" {
+  interface FlowNodeRegistry {
+    race: { kind: "race"; arms: CompiledArm[] };
+  }
+}
+
+declare module "../declarative.js" {
+  interface FlowBuilder<C extends object> {
+    /**
+     * A first-of event race — a BPMN event-based gateway. Each named arm waits on
+     * exactly one event: a `signal` (a durable message catch correlated on a
+     * process variable) or a `timer` (`{ after }` a delay, or `{ at }` an
+     * instant). The engine arms every catch at once; the FIRST to fire wins, its
+     * arm's `do` body runs, and the losing catch events are cancelled. Every arm's
+     * body converges on whatever follows the race.
+     *
+     * ```ts
+     * w.race({
+     *   "review-ready":   { signal: { correlationKey: "prKey" }, do: (b) => b.run("re-review", reReview) },
+     *   "review-timeout": { timer:  { after: "=reviewWaitTimeout" }, do: (b) => b.run("escalate", escalate) },
+     * });
+     * ```
+     */
+    race(arms: Record<string, RaceArm>): FlowBuilder<C>;
+  }
+}
+
+function hasSignal(spec: RaceArm): spec is { signal: { correlationKey: string } } & { do: Block } {
+  return "signal" in spec && spec.signal !== null && typeof spec.signal === "object";
+}
+
+function hasTimer(spec: RaceArm): spec is { timer: { after: string } | { at: string } } & { do: Block } {
+  return "timer" in spec && spec.timer !== null && typeof spec.timer === "object";
+}
+
+registerNodeKind("race", {
+  build: (api) => (arms: Record<string, RaceArm>) => {
+    if (arms === null || typeof arms !== "object") {
+      throw new Error(`race() needs an arms object { "<name>": { signal | timer, do } }`);
+    }
+    const entries = Object.entries(arms);
+    if (entries.length < 2) {
+      throw new Error(
+        `race() needs at least two arms (an event-based gateway with fewer than two events is degenerate)`,
+      );
+    }
+    const compiled: CompiledArm[] = [];
+    for (const [name, spec] of entries) {
+      if (spec === null || typeof spec !== "object") {
+        throw new Error(`race() arm "${name}" must be an object { signal | timer, do }`);
+      }
+      const isSignal = hasSignal(spec);
+      const isTimer = hasTimer(spec);
+      if (isSignal === isTimer) {
+        throw new Error(
+          `race() arm "${name}" needs exactly one of { signal: { correlationKey } } or { timer: { after | at } }`,
+        );
+      }
+      if (typeof spec.do !== "function") {
+        throw new Error(`race() arm "${name}" needs a do block (b) => {…}`);
+      }
+      api.claim(name);
+      let event: FlowNode;
+      if (isSignal) {
+        const rawKey = spec.signal.correlationKey;
+        if (typeof rawKey !== "string" || rawKey.trim() === "") {
+          throw new Error(`race() arm "${name}" signal needs a non-empty { correlationKey }`);
+        }
+        // Trim before validating/storing, in parity with the timer arm ({ after }/
+        // { at } are trimmed above): a value like " prKey " is usable after
+        // trimming, so it must not fail the NCName check on stray whitespace. The
+        // assertIdent context names the arm so a failure says WHICH arm is invalid.
+        const correlationKey = rawKey.trim();
+        assertIdent(`race() arm "${name}" signal correlationKey`, correlationKey);
+        event = { kind: "signal", name, correlationKey, payload: api.contracts[name]?.in };
+      } else {
+        const timer = spec.timer;
+        // Enforce exactly-one on KEY PRESENCE, not string-ness: a runtime-invalid
+        // arm that supplies both keys where only one is a string (e.g.
+        // `{ after: 1, at: "…" }`) must be rejected here, not silently dispatched
+        // into `after.trim()` — which would throw an opaque TypeError. Once the
+        // branch is chosen, validate the value is a string before trimming.
+        const hasAfterKey = "after" in timer;
+        const hasAtKey = "at" in timer;
+        if (hasAfterKey === hasAtKey) {
+          throw new Error(`race() arm "${name}" timer needs exactly one of { after } (a delay) or { at } (an instant)`);
+        }
+        if ("after" in timer) {
+          if (typeof timer.after !== "string") {
+            throw new Error(`race() arm "${name}" timer { after } must be a string duration`);
+          }
+          const after = timer.after.trim();
+          assertTimerDuration(`race() arm "${name}" timer after`, after);
+          event = { kind: "timer", name, after };
+        } else {
+          if (typeof timer.at !== "string") {
+            throw new Error(`race() arm "${name}" timer { at } must be a string instant`);
+          }
+          const at = timer.at.trim();
+          assertTimerDate(`race() arm "${name}" timer at`, at);
+          event = { kind: "timer", name, at };
+        }
+      }
+      compiled.push({ event, body: api.child(spec.do, false) });
+    }
+    api.out.push({ kind: "race", arms: compiled });
+    return api.self();
+  },
+  walk: (node, recurse) => {
+    // Recurse into each arm's catch event AND its body: the catch `signal` nodes
+    // must be visited so the shared message emitter lifts their `<bpmn:message>`
+    // + correlation subscription, and body `task` nodes so their external job
+    // types are discovered — exactly as a standalone `signal`/`task` would be.
+    for (const arm of node.arms) recurse([arm.event, ...arm.body]);
+  },
+  emit: (node, incoming, loop, api) => {
+    const gwId = `Gw_${api.nextGw()}`;
+    api.addNode(eventBasedGateway(gwId, api.currentScope()));
+    api.connect(incoming, gwId);
+    const out: Edge[] = [];
+    for (const arm of node.arms) {
+      // Fork the gateway straight to the arm's catch event (BPMN requires an
+      // event-based gateway's targets to be intermediate catch events), reusing
+      // the arm kind's own registered emit so the catch is identical to a
+      // standalone `w.signal`/`w.timer`; then wire its `do` body onward.
+      const fork = api.newEdge(gwId);
+      const afterCatch = requireNodeKind(arm.event.kind).emit(arm.event, [fork], loop, api);
+      out.push(...api.emitList(arm.body, afterCatch, loop));
+    }
+    return out;
+  },
+});
+
+/** A `<bpmn:eventBasedGateway>` render node (no typed `EmitApi` primitive exists —
+ *  built as a custom {@link RenderNode} from the exported string helpers). */
+function eventBasedGateway(id: string, scope: string | undefined): RenderNode {
+  return {
+    id,
+    scope,
+    render: (inc: string[], outg: string[]) =>
+      `    <bpmn:eventBasedGateway id="${escapeXml(id)}">\n` + incomingOutgoing(inc, outg) + `    </bpmn:eventBasedGateway>`,
+  };
+}

package/src/nodes/signal.ts

@@ -15,9 +15,15 @@ declare module "../types.js" {
 registerNodeKind("signal", {
   build: (api) => (name: string, opts: { correlationKey: string }) => {
     api.claim(name);
-    if (!opts || !opts.correlationKey) throw new Error(`signal("${name}") needs { correlationKey }`);
-    assertIdent("correlationKey", opts.correlationKey);
-    api.out.push({ kind: "signal", name, correlationKey: opts.correlationKey, payload: api.contracts[name]?.in });
+    if (!opts || typeof opts.correlationKey !== "string" || opts.correlationKey.trim() === "") {
+      throw new Error(`signal("${name}") needs { correlationKey }`);
+    }
+    // Trim before validating/storing, in parity with the race() signal arm: a
+    // value like " prKey " is usable after trimming, so it must not fail the
+    // NCName check on stray whitespace. Name the node in the assertIdent context.
+    const correlationKey = opts.correlationKey.trim();
+    assertIdent(`signal("${name}") correlationKey`, correlationKey);
+    api.out.push({ kind: "signal", name, correlationKey, payload: api.contracts[name]?.in });
     return api.self();
   },
   emit: (node, incoming, _loop, api) => {

package/src/nodes/task.ts

@@ -2,27 +2,148 @@
 // OUTSIDE this program (no locally-hosted handler). Its job type defaults to the
 // derived `${flowId}:${name}` unless overridden with `{ jobType }`. Contributed
 // from this module through the extension seam (epic #314, S0/#315).
+//
+// This module also owns the AGENT PROMPT BINDING (epic #314, S4/#319): an
+// optional `{ prompt }` option binds an LLM prompt resource to the worker via a
+// `<zeebe:linkedResource … resourceType="GenericScript" linkName="prompt">`,
+// mirroring the nano-workforce agent service tasks. The extension is contributed
+// entirely from this module — the `task` node's own registered emit handler and
+// its option type — WITHOUT re-opening the shared `FlowNode` union, the central
+// `walkNodes`/`emitNode` dispatch, or the generated barrel.
 
 import type { NodeEnvelopes } from "../types.js";
-import { assertJobType } from "../xml.js";
+import { assertJobType, escapeXml } from "../xml.js";
 import { registerNodeKind } from "./registry.js";
 
+/** Binds an LLM prompt resource to an agent service task. Emits, alongside the
+ *  task's `zeebe:taskDefinition` capability token, a
+ *  `<zeebe:linkedResources><zeebe:linkedResource resourceId=… bindingType=…
+ *  resourceType="GenericScript" linkName="prompt"/></zeebe:linkedResources>`
+ *  extension — the shape the nano-workforce agent tasks use to attach a prompt
+ *  script to the worker that services the job. */
+export interface PromptBinding {
+  /** The `GenericScript` resource id bound as the prompt (the linkedResource
+   *  `resourceId`, e.g. `"retro.md"`). Required and non-empty. */
+  resourceId: string;
+  /** The linkedResource `bindingType` — how the engine resolves the resource
+   *  version at deploy time. Defaults to `"latest"`. */
+  bindingType?: string;
+  /** Optional prompt addendum: a FEEL expression (or literal) fed to the worker
+   *  through a `<zeebe:ioMapping><zeebe:input source=… target="appendPrompt"/>`
+   *  input, the convention the agent tasks use to append runtime context to the
+   *  bound prompt. Omitted → no `ioMapping` is emitted. */
+  append?: string;
+}
+
 declare module "../types.js" {
   interface FlowNodeRegistry {
-    task: { kind: "task"; name: string; envelopes?: NodeEnvelopes; jobType?: string };
+    task: {
+      kind: "task";
+      name: string;
+      envelopes?: NodeEnvelopes;
+      jobType?: string;
+      /** The agent prompt binding, when the task is an LLM-agent service task. */
+      prompt?: PromptBinding;
+    };
   }
 }
 
+declare module "../declarative.js" {
+  interface FlowBuilder<C extends object> {
+    /**
+     * An AGENT external service task: as `task`, but additionally binds an LLM
+     * `prompt` resource to the worker via a `zeebe:linkedResource`
+     * (`resourceType="GenericScript" linkName="prompt"`). Pair it with a
+     * `{ jobType }` capability token (e.g. `senior:retro`) so an agent pool
+     * services it. `prompt.append` (optional) feeds a FEEL expression to the
+     * worker through a `zeebe:ioMapping` `appendPrompt` input.
+     */
+    task<K extends string>(name: K, opts: { jobType?: string; prompt: PromptBinding }): FlowBuilder<C>;
+  }
+}
+
+/** Normalize + validate a prompt binding at authoring time, applying the
+ *  `bindingType` default. Emitted string fields are trimmed before storing (in
+ *  parity with how `timer` normalizes `{ after }`/`{ at }`), so a value like
+ *  `resourceId: " retro.md "` passes validation AND is emitted without stray
+ *  surrounding whitespace. Returns a fully-resolved binding stored on the node. */
+function resolvePrompt(name: string, prompt: PromptBinding): PromptBinding {
+  if (typeof prompt !== "object" || prompt === null) {
+    throw new Error(`task("${name}") prompt must be an object with a non-empty resourceId`);
+  }
+  const resourceId = prompt.resourceId;
+  if (typeof resourceId !== "string" || resourceId.trim() === "") {
+    throw new Error(`task("${name}") prompt.resourceId must be a non-empty string`);
+  }
+  // Only an ABSENT bindingType defaults to "latest"; `??` would also swallow an
+  // explicit `null`, masking an authoring mistake. Distinguish `undefined` (use
+  // the default) from any other non-string (reject), in parity with how `append`
+  // below treats `!== undefined` as "provided, so validate strictly".
+  const bindingType = prompt.bindingType === undefined ? "latest" : prompt.bindingType;
+  if (typeof bindingType !== "string" || bindingType.trim() === "") {
+    throw new Error(`task("${name}") prompt.bindingType must be a non-empty string`);
+  }
+  const resolved: PromptBinding = { resourceId: resourceId.trim(), bindingType: bindingType.trim() };
+  if (prompt.append !== undefined) {
+    if (typeof prompt.append !== "string" || prompt.append.trim() === "") {
+      throw new Error(`task("${name}") prompt.append must be a non-empty string when provided`);
+    }
+    resolved.append = prompt.append.trim();
+  }
+  return resolved;
+}
+
+/** Build the prompt-specific `<bpmn:extensionElements>` delta appended to the
+ *  shared service-task emission: the `zeebe:linkedResources` prompt binding and
+ *  (optionally) a `zeebe:ioMapping` `appendPrompt` input. The task shell
+ *  (taskDefinition + envelope properties) is rendered by the built-in
+ *  `EmitApi.addServiceTask`, so this variant only contributes its delta and the
+ *  envelope serialization can never drift from the plain service task. */
+function promptExtensions(prompt: PromptBinding): string {
+  const { resourceId, bindingType, append } = prompt;
+  const linked =
+    `        <zeebe:linkedResources>\n` +
+    `          <zeebe:linkedResource resourceId="${escapeXml(resourceId)}" ` +
+    `bindingType="${escapeXml(bindingType ?? "latest")}" resourceType="GenericScript" linkName="prompt" />\n` +
+    `        </zeebe:linkedResources>\n`;
+  const io =
+    append !== undefined
+      ? `        <zeebe:ioMapping>\n` +
+        `          <zeebe:input source="${escapeXml(append)}" target="appendPrompt" />\n` +
+        `        </zeebe:ioMapping>\n`
+      : "";
+  return linked + io;
+}
+
 registerNodeKind("task", {
-  build: (api) => (name: string, opts?: { jobType?: string }) => {
+  build: (api) => (name: string, opts?: { jobType?: string; prompt?: PromptBinding }) => {
     api.claim(name);
     const override = opts?.jobType;
     if (override !== undefined) assertJobType("task jobType", override);
-    api.out.push({ kind: "task", name, envelopes: api.contractEnvelopes(name), jobType: override });
+    const prompt = opts?.prompt !== undefined ? resolvePrompt(name, opts.prompt) : undefined;
+    api.out.push({
+      kind: "task",
+      name,
+      envelopes: api.contractEnvelopes(name),
+      jobType: override,
+      prompt,
+    });
     return api.self();
   },
   emit: (node, incoming, _loop, api) => {
-    api.addServiceTask(node);
+    // No prompt → the standard service-task emission is preserved unchanged (no
+    // `linkedResources` are emitted).
+    if (node.prompt === undefined) {
+      api.addServiceTask(node);
+      api.connect(incoming, node.name);
+      return [api.newEdge(node.name)];
+    }
+    // Prompt binding present → the shared `addServiceTask` renders the task
+    // shell (taskDefinition + envelope properties, recording envelopes); we only
+    // supply the `zeebe:linkedResource` (and optional `appendPrompt` ioMapping)
+    // delta, so the envelope/taskDefinition serialization has a single source.
+    const prompt = node.prompt;
+    api.addServiceTask(node, { extraExt: promptExtensions(prompt) });
     api.connect(incoming, node.name);
     return [api.newEdge(node.name)];
   },