@nanobpm/workflow 0.14.0 → 0.15.1

package/dist/declarative.d.ts

@@ -239,6 +239,13 @@ export declare function walkNodes(nodes: FlowNode[], visit: (n: FlowNode) => voi
  *  { jobType })`. Deduplicated (preserving first-seen order) since several steps
  *  may intentionally share one override token. */
 export declare function externalJobTypes(flow: DeclarativeFlow): string[];
+/** The job types of a flow's inline-handled `run` steps (anywhere in the tree) —
+ *  exactly the set the in-process `Worker` hosts (same walk, same derived
+ *  `<flowId>:<stepName>`; a `run` step has no `jobType` override). Codegen
+ *  consumes this to treat those steps as already-served: a worker-stub
+ *  scaffolder must never plan a stub for them (nano-ide#595). Deduplicated,
+ *  preserving first-seen order. */
+export declare function inlineJobTypes(flow: DeclarativeFlow): string[];
 /** A renderable BPMN element the emitter has placed. A kind's `emit` handler
  *  adds one (or more) via `api.addNode(...)` (or a typed helper like
  *  `api.addServiceTask`). */

package/dist/declarative.js

@@ -319,6 +319,26 @@ export function externalJobTypes(flow) {
     });
     return types;
 }
+/** The job types of a flow's inline-handled `run` steps (anywhere in the tree) —
+ *  exactly the set the in-process `Worker` hosts (same walk, same derived
+ *  `<flowId>:<stepName>`; a `run` step has no `jobType` override). Codegen
+ *  consumes this to treat those steps as already-served: a worker-stub
+ *  scaffolder must never plan a stub for them (nano-ide#595). Deduplicated,
+ *  preserving first-seen order. */
+export function inlineJobTypes(flow) {
+    const seen = new Set();
+    const types = [];
+    walkNodes(flow.steps, (n) => {
+        if (n.kind !== "run")
+            return;
+        const type = jobType(flow.id, n.name);
+        if (seen.has(type))
+            return;
+        seen.add(type);
+        types.push(type);
+    });
+    return types;
+}
 function requireTimerAt(node) {
     if (node.at === undefined)
         throw new Error(`timer event is missing its { at } value`);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export type { Journal, ReplayStep } from "./imperative.js";
-export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
+export { defineFlow, declarativeToBpmn, externalJobTypes, inlineJobTypes, walkNodes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
 export type { BoundaryOptions } from "./nodes/boundary.js";
 export type { HumanOptions, HumanIoMapping, HumanIoEntry } from "./nodes/human.js";

package/dist/index.js

@@ -39,7 +39,7 @@
 // code-first surface (steps are not engine-visible; requires determinism
 // discipline). Retained for advanced durable-orchestration use only.
 export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
-export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
+export { defineFlow, declarativeToBpmn, externalJobTypes, inlineJobTypes, walkNodes } from "./declarative.js";
 export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
 export { envelope } from "./envelope.js";
 export { WorkflowClient, WorkflowError, toBpmn, toDeployableBpmn } from "./client.js";

package/dist/nodes/forEach.js

@@ -4,6 +4,7 @@
 // wrapped in an embedded MI sub-process. Contributed through the extension seam.
 import { assertIdent, escapeXml } from "../xml.js";
 import { registerNodeKind } from "./registry.js";
+import { hasTaskExtensions } from "./task.js";
 /** The `<bpmn:multiInstanceLoopCharacteristics>` block for a `forEach` node — the
  *  same shape whether lifted onto a leaf service task or a sub-process. */
 function miCharacteristics(node) {
@@ -82,13 +83,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). A prompt-carrying `task` is deliberately
+        // scope, with its own start/end). A `task` with an extension delta (agent
+        // marker, prompt binding or io mapping — see `hasTaskExtensions`) 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))) {
+        if (only && (only.kind === "run" || (only.kind === "task" && !hasTaskExtensions(only)))) {
             api.addServiceTask(only, { mi });
             api.connect(incoming, only.name);
             return [api.newEdge(only.name)];

package/dist/nodes/task.d.ts

@@ -27,6 +27,11 @@ declare module "../types.js" {
             jobType?: string;
             /** The agent prompt binding, when the task is an LLM-agent service task. */
             prompt?: PromptBinding;
+            /** Whether the task is an AGENT service task, emitting the engine-native
+             *  AgentTask marker `<zeebe:agentDefinition agentType="external" />`
+             *  (issue #597). Resolved at authoring time: an explicit `agent` option
+             *  wins, otherwise it is `true` exactly when a `prompt` is bound. */
+            agent?: boolean;
             /** An explicit `<zeebe:ioMapping>` on the service task — arbitrary input
              *  (and output) variable mappings, using the shared ioMapping shape. When a
              *  `prompt.append` is ALSO present it is folded into this single mapping as
@@ -49,7 +54,29 @@ declare module "../declarative.js" {
         task<K extends string>(name: K, opts: {
             jobType?: string;
             prompt: PromptBinding;
+            agent?: boolean;
+            io?: HumanIoMapping;
+        }): FlowBuilder<C>;
+        /**
+         * A PROMPT-LESS agent external service task: as `task`, but `agent: true`
+         * emits the AgentTask marker `<zeebe:agentDefinition agentType="external" />`
+         * (the nano-workforce agent-task signal, issue #597) without binding a
+         * prompt resource — the worker is steered by its inputs alone.
+         */
+        task<K extends string>(name: K, opts: {
+            jobType?: string;
+            agent: boolean;
             io?: HumanIoMapping;
         }): FlowBuilder<C>;
     }
 }
+/** Whether a `task` node carries an extension delta (agent marker, prompt
+ *  binding, or io mapping) that only this module's emitter renders. The SINGLE
+ *  predicate any other emitter (e.g. `forEach`'s single-task fast path) must
+ *  consult before rendering the task shell itself, so a new delta can never be
+ *  silently dropped by a bypass. */
+export declare function hasTaskExtensions(node: {
+    agent?: boolean;
+    prompt?: PromptBinding;
+    io?: HumanIoMapping;
+}): boolean;

package/dist/nodes/task.js

@@ -57,7 +57,10 @@ function resolvePrompt(name, prompt) {
  *  `<zeebe:ioMapping>` (never two). Element order matches the golden:
  *  `linkedResources` (when any) then `ioMapping` (when any), the latter after
  *  `taskDefinition`/`properties`. */
-function taskExtensions(prompt, io) {
+function taskExtensions(agent, prompt, io) {
+    // The AgentTask marker leads the delta so it sits directly after the
+    // taskDefinition, matching the nano-workforce reference shape.
+    const marker = agent === true ? `        <zeebe:agentDefinition agentType="external" />\n` : "";
     const linked = prompt !== undefined
         ? `        <zeebe:linkedResources>\n` +
             `          <zeebe:linkedResource resourceId="${escapeXml(prompt.resourceId)}" ` +
@@ -73,7 +76,15 @@ function taskExtensions(prompt, io) {
     if (prompt?.append !== undefined)
         inputs.push({ source: prompt.append, target: "appendPrompt" });
     const merged = { input: inputs, output: io?.output ?? [] };
-    return linked + renderIoMapping(merged);
+    return marker + linked + renderIoMapping(merged);
+}
+/** Whether a `task` node carries an extension delta (agent marker, prompt
+ *  binding, or io mapping) that only this module's emitter renders. The SINGLE
+ *  predicate any other emitter (e.g. `forEach`'s single-task fast path) must
+ *  consult before rendering the task shell itself, so a new delta can never be
+ *  silently dropped by a bypass. */
+export function hasTaskExtensions(node) {
+    return node.agent === true || node.prompt !== undefined || node.io !== undefined;
 }
 registerNodeKind("task", {
     build: (api) => (name, opts) => {
@@ -83,12 +94,17 @@ registerNodeKind("task", {
             assertJobType("task jobType", override);
         const prompt = opts?.prompt !== undefined ? resolvePrompt(name, opts.prompt) : undefined;
         assertIoMapping(`task("${name}")`, opts?.io);
+        if (opts?.agent !== undefined && typeof opts.agent !== "boolean") {
+            throw new Error(`task("${name}") agent must be a boolean when provided`);
+        }
+        const agent = opts?.agent ?? prompt !== undefined;
         api.out.push({
             kind: "task",
             name,
             envelopes: api.contractEnvelopes(name),
             jobType: override,
             prompt,
+            agent,
             io: opts?.io,
         });
         return api.self();
@@ -97,7 +113,7 @@ registerNodeKind("task", {
         // Neither a prompt binding nor an explicit io mapping → the standard
         // service-task emission is preserved unchanged (no `linkedResources`, no
         // `ioMapping`).
-        if (node.prompt === undefined && node.io === undefined) {
+        if (!hasTaskExtensions(node)) {
             api.addServiceTask(node);
             api.connect(incoming, node.name);
             return [api.newEdge(node.name)];
@@ -107,7 +123,7 @@ registerNodeKind("task", {
         // properties, recording envelopes); we only supply the `linkedResource`
         // and/or `ioMapping` delta, so the envelope/taskDefinition serialization has
         // a single source.
-        api.addServiceTask(node, { extraExt: taskExtensions(node.prompt, node.io) });
+        api.addServiceTask(node, { extraExt: taskExtensions(node.agent, node.prompt, node.io) });
         api.connect(incoming, node.name);
         return [api.newEdge(node.name)];
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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

@@ -562,6 +562,25 @@ export function externalJobTypes(flow: DeclarativeFlow): string[] {
   return types;
 }
 
+/** The job types of a flow's inline-handled `run` steps (anywhere in the tree) —
+ *  exactly the set the in-process `Worker` hosts (same walk, same derived
+ *  `<flowId>:<stepName>`; a `run` step has no `jobType` override). Codegen
+ *  consumes this to treat those steps as already-served: a worker-stub
+ *  scaffolder must never plan a stub for them (nano-ide#595). Deduplicated,
+ *  preserving first-seen order. */
+export function inlineJobTypes(flow: DeclarativeFlow): string[] {
+  const seen = new Set<string>();
+  const types: string[] = [];
+  walkNodes(flow.steps, (n) => {
+    if (n.kind !== "run") return;
+    const type = jobType(flow.id, n.name);
+    if (seen.has(type)) return;
+    seen.add(type);
+    types.push(type);
+  });
+  return types;
+}
+
 function requireTimerAt(node: { at?: string }): string {
   if (node.at === undefined) throw new Error(`timer event is missing its { at } value`);
   return node.at;

package/src/index.ts

@@ -41,7 +41,7 @@
 // discipline). Retained for advanced durable-orchestration use only.
 export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export type { Journal, ReplayStep } from "./imperative.js";
-export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
+export { defineFlow, declarativeToBpmn, externalJobTypes, inlineJobTypes, walkNodes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
 // The `.boundary(...)` option type (its builder method augments FlowBuilder from
 // the boundary kind module — S2/#317).

package/src/nodes/forEach.ts

@@ -7,6 +7,7 @@ import type { FlowNode } from "../types.js";
 import type { Block } from "../declarative.js";
 import { assertIdent, escapeXml } from "../xml.js";
 import { registerNodeKind } from "./registry.js";
+import { hasTaskExtensions } from "./task.js";
 
 /** The `forEach` node shape (its `FlowNode` variant). */
 interface ForEachNode {
@@ -115,13 +116,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). A prompt-carrying `task` is deliberately
+    // scope, with its own start/end). A `task` with an extension delta (agent
+    // marker, prompt binding or io mapping — see `hasTaskExtensions`) 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))) {
+    if (only && (only.kind === "run" || (only.kind === "task" && !hasTaskExtensions(only)))) {
       api.addServiceTask(only, { mi });
       api.connect(incoming, only.name);
       return [api.newEdge(only.name)];

package/src/nodes/task.ts

@@ -46,6 +46,11 @@ declare module "../types.js" {
       jobType?: string;
       /** The agent prompt binding, when the task is an LLM-agent service task. */
       prompt?: PromptBinding;
+      /** Whether the task is an AGENT service task, emitting the engine-native
+       *  AgentTask marker `<zeebe:agentDefinition agentType="external" />`
+       *  (issue #597). Resolved at authoring time: an explicit `agent` option
+       *  wins, otherwise it is `true` exactly when a `prompt` is bound. */
+      agent?: boolean;
       /** An explicit `<zeebe:ioMapping>` on the service task — arbitrary input
        *  (and output) variable mappings, using the shared ioMapping shape. When a
        *  `prompt.append` is ALSO present it is folded into this single mapping as
@@ -68,7 +73,17 @@ declare module "../declarative.js" {
      */
     task<K extends string>(
       name: K,
-      opts: { jobType?: string; prompt: PromptBinding; io?: HumanIoMapping },
+      opts: { jobType?: string; prompt: PromptBinding; agent?: boolean; io?: HumanIoMapping },
+    ): FlowBuilder<C>;
+    /**
+     * A PROMPT-LESS agent external service task: as `task`, but `agent: true`
+     * emits the AgentTask marker `<zeebe:agentDefinition agentType="external" />`
+     * (the nano-workforce agent-task signal, issue #597) without binding a
+     * prompt resource — the worker is steered by its inputs alone.
+     */
+    task<K extends string>(
+      name: K,
+      opts: { jobType?: string; agent: boolean; io?: HumanIoMapping },
     ): FlowBuilder<C>;
   }
 }
@@ -118,7 +133,14 @@ function resolvePrompt(name: string, prompt: PromptBinding): PromptBinding {
  *  `<zeebe:ioMapping>` (never two). Element order matches the golden:
  *  `linkedResources` (when any) then `ioMapping` (when any), the latter after
  *  `taskDefinition`/`properties`. */
-function taskExtensions(prompt: PromptBinding | undefined, io: HumanIoMapping | undefined): string {
+function taskExtensions(
+  agent: boolean | undefined,
+  prompt: PromptBinding | undefined,
+  io: HumanIoMapping | undefined,
+): string {
+  // The AgentTask marker leads the delta so it sits directly after the
+  // taskDefinition, matching the nano-workforce reference shape.
+  const marker = agent === true ? `        <zeebe:agentDefinition agentType="external" />\n` : "";
   const linked =
     prompt !== undefined
       ? `        <zeebe:linkedResources>\n` +
@@ -134,22 +156,36 @@ function taskExtensions(prompt: PromptBinding | undefined, io: HumanIoMapping |
   const inputs: HumanIoEntry[] = [...(io?.input ?? [])];
   if (prompt?.append !== undefined) inputs.push({ source: prompt.append, target: "appendPrompt" });
   const merged: HumanIoMapping = { input: inputs, output: io?.output ?? [] };
-  return linked + renderIoMapping(merged);
+  return marker + linked + renderIoMapping(merged);
+}
+
+/** Whether a `task` node carries an extension delta (agent marker, prompt
+ *  binding, or io mapping) that only this module's emitter renders. The SINGLE
+ *  predicate any other emitter (e.g. `forEach`'s single-task fast path) must
+ *  consult before rendering the task shell itself, so a new delta can never be
+ *  silently dropped by a bypass. */
+export function hasTaskExtensions(node: { agent?: boolean; prompt?: PromptBinding; io?: HumanIoMapping }): boolean {
+  return node.agent === true || node.prompt !== undefined || node.io !== undefined;
 }
 
 registerNodeKind("task", {
-  build: (api) => (name: string, opts?: { jobType?: string; prompt?: PromptBinding; io?: HumanIoMapping }) => {
+  build: (api) => (name: string, opts?: { jobType?: string; prompt?: PromptBinding; agent?: boolean; io?: HumanIoMapping }) => {
     api.claim(name);
     const override = opts?.jobType;
     if (override !== undefined) assertJobType("task jobType", override);
     const prompt = opts?.prompt !== undefined ? resolvePrompt(name, opts.prompt) : undefined;
     assertIoMapping(`task("${name}")`, opts?.io);
+    if (opts?.agent !== undefined && typeof opts.agent !== "boolean") {
+      throw new Error(`task("${name}") agent must be a boolean when provided`);
+    }
+    const agent = opts?.agent ?? prompt !== undefined;
     api.out.push({
       kind: "task",
       name,
       envelopes: api.contractEnvelopes(name),
       jobType: override,
       prompt,
+      agent,
       io: opts?.io,
     });
     return api.self();
@@ -158,7 +194,7 @@ registerNodeKind("task", {
     // Neither a prompt binding nor an explicit io mapping → the standard
     // service-task emission is preserved unchanged (no `linkedResources`, no
     // `ioMapping`).
-    if (node.prompt === undefined && node.io === undefined) {
+    if (!hasTaskExtensions(node)) {
       api.addServiceTask(node);
       api.connect(incoming, node.name);
       return [api.newEdge(node.name)];
@@ -168,7 +204,7 @@ registerNodeKind("task", {
     // properties, recording envelopes); we only supply the `linkedResource`
     // and/or `ioMapping` delta, so the envelope/taskDefinition serialization has
     // a single source.
-    api.addServiceTask(node, { extraExt: taskExtensions(node.prompt, node.io) });
+    api.addServiceTask(node, { extraExt: taskExtensions(node.agent, node.prompt, node.io) });
     api.connect(incoming, node.name);
     return [api.newEdge(node.name)];
   },