@nanobpm/workflow 0.15.0 → 0.16.0

package/README.md

@@ -105,6 +105,19 @@ const { processInstanceKey } = await client.start(onboarding, {});
 await client.signal(onboarding, "approved", userId, { by: "alice" });
 ```
 
+A long-running step (transcription, an agent call, a multi-GB upload) can
+outlive the engine's default job lock: the lease expires mid-handler, the
+engine re-activates the job, and a second worker runs it again. Declare the
+lock timeout per step with `w.run(name, handler, { timeoutMs })` (overrides the
+`Worker`'s worker-wide `jobTimeoutMs`, default 30s, for that step's job type):
+
+```ts
+const flow = defineFlow("uploads", (w) => {
+  w.run("transcode", transcode, { timeoutMs: 3_600_000 }); // 1h lock for this step
+  w.run("notify", notify);
+});
+```
+
 A human-in-the-loop **approval gate** with a form, an assignment, and an output
 mapping that stamps the decision back onto a process variable:
 

package/dist/declarative.d.ts

@@ -45,6 +45,12 @@ export interface FlowBuilder<C extends object = object> {
      */
     run<K extends string>(name: K, handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>, opts?: {
         io?: HumanIoMapping;
+        /** Job lock timeout, ms, for this step's derived worker (issue #596): how long the
+         *  engine leases an activated job before re-activating it elsewhere. Set it above the
+         *  handler's worst-case runtime for long steps (transcription, an agent call, a
+         *  multi-GB upload) so the lock cannot expire mid-handler and the job run twice.
+         *  Overrides the `Worker`'s worker-wide `jobTimeoutMs` for this step's job type. */
+        timeoutMs?: number;
     }): FlowBuilder<C>;
     /**
      * A durable activity served by a worker OUTSIDE this program (a BPMN service
@@ -239,6 +245,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/run.d.ts

@@ -6,6 +6,7 @@ declare module "../types.js" {
             name: string;
             envelopes?: NodeEnvelopes;
             io?: HumanIoMapping;
+            timeoutMs?: number;
         };
     }
 }

package/dist/nodes/run.js

@@ -11,8 +11,18 @@ registerNodeKind("run", {
         if (typeof handler !== "function")
             throw new Error(`run("${name}") needs a handler function`);
         assertIoMapping(`run("${name}")`, opts?.io);
+        const timeoutMs = opts?.timeoutMs;
+        if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs <= 0)) {
+            throw new Error(`run("${name}"): timeoutMs must be a positive integer (ms)`);
+        }
         api.handlers[name] = handler;
-        api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name), io: opts?.io });
+        api.out.push({
+            kind: "run",
+            name,
+            envelopes: api.contractEnvelopes(name),
+            io: opts?.io,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
         return api.self();
     },
     emit: (node, incoming, _loop, api) => {

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/dist/worker.d.ts

@@ -54,6 +54,9 @@ export declare class Worker {
     private readonly onError?;
     /** job type → { workflowId, handle } */
     private readonly routes;
+    /** Job lock timeout (ms) per derived job type, from a `run` step's `{ timeoutMs }`
+     *  (issue #596). Overrides the worker-wide `jobTimeoutMs` for that type. */
+    private readonly typeTimeoutMs;
     private running;
     private workers;
     constructor(opts: WorkerOptions);

package/dist/worker.js

@@ -30,6 +30,9 @@ export class Worker {
     onError;
     /** job type → { workflowId, handle } */
     routes = new Map();
+    /** Job lock timeout (ms) per derived job type, from a `run` step's `{ timeoutMs }`
+     *  (issue #596). Overrides the worker-wide `jobTimeoutMs` for that type. */
+    typeTimeoutMs = new Map();
     running = false;
     workers = [];
     constructor(opts) {
@@ -87,6 +90,10 @@ export class Worker {
                         return { variables };
                     },
                 });
+                // A step-declared job lock timeout (issue #596) applies to this step's derived
+                // job type, overriding the worker-wide `jobTimeoutMs` at `start()`.
+                if (s.timeoutMs !== undefined)
+                    this.typeTimeoutMs.set(jobType(wf.id, s.name), s.timeoutMs);
             });
         }
     }
@@ -141,7 +148,8 @@ export class Worker {
                 jobType: type,
                 workerName: this.name,
                 maxParallelJobs: this.maxParallelJobs,
-                jobTimeoutMs: this.jobTimeoutMs,
+                // A step-declared `{ timeoutMs }` (issue #596) wins over the worker-wide default.
+                jobTimeoutMs: this.typeTimeoutMs.get(type) ?? this.jobTimeoutMs,
                 pollTimeoutMs: this.pollTimeoutMs,
                 autoStart: false,
                 jobHandler: (job) => this.handleJob(type, route, job),

package/package.json

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

@@ -102,7 +102,15 @@ export interface FlowBuilder<C extends object = object> {
   run<K extends string>(
     name: K,
     handler: TypedHandler<VarsOf<C, K>, ResultOf<C, K>>,
-    opts?: { io?: HumanIoMapping },
+    opts?: {
+      io?: HumanIoMapping;
+      /** Job lock timeout, ms, for this step's derived worker (issue #596): how long the
+       *  engine leases an activated job before re-activating it elsewhere. Set it above the
+       *  handler's worst-case runtime for long steps (transcription, an agent call, a
+       *  multi-GB upload) so the lock cannot expire mid-handler and the job run twice.
+       *  Overrides the `Worker`'s worker-wide `jobTimeoutMs` for this step's job type. */
+      timeoutMs?: number;
+    },
   ): FlowBuilder<C>;
   /**
    * A durable activity served by a worker OUTSIDE this program (a BPMN service
@@ -562,6 +570,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/run.ts

@@ -11,17 +11,27 @@ import { registerNodeKind } from "./registry.js";
 
 declare module "../types.js" {
   interface FlowNodeRegistry {
-    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes; io?: HumanIoMapping };
+    run: { kind: "run"; name: string; envelopes?: NodeEnvelopes; io?: HumanIoMapping; timeoutMs?: number };
   }
 }
 
 registerNodeKind("run", {
-  build: (api) => (name: string, handler: StepHandler, opts?: { io?: HumanIoMapping }) => {
+  build: (api) => (name: string, handler: StepHandler, opts?: { io?: HumanIoMapping; timeoutMs?: number }) => {
     api.claim(name);
     if (typeof handler !== "function") throw new Error(`run("${name}") needs a handler function`);
     assertIoMapping(`run("${name}")`, opts?.io);
+    const timeoutMs = opts?.timeoutMs;
+    if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs <= 0)) {
+      throw new Error(`run("${name}"): timeoutMs must be a positive integer (ms)`);
+    }
     api.handlers[name] = handler;
-    api.out.push({ kind: "run", name, envelopes: api.contractEnvelopes(name), io: opts?.io });
+    api.out.push({
+      kind: "run",
+      name,
+      envelopes: api.contractEnvelopes(name),
+      io: opts?.io,
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
     return api.self();
   },
   emit: (node, incoming, _loop, api) => {

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)];
   },

package/src/worker.ts

@@ -84,6 +84,9 @@ export class Worker {
   private readonly onError?: WorkerOptions["onError"];
   /** job type → { workflowId, handle } */
   private readonly routes = new Map<string, { workflowId: string; handle: Handler }>();
+  /** Job lock timeout (ms) per derived job type, from a `run` step's `{ timeoutMs }`
+   *  (issue #596). Overrides the worker-wide `jobTimeoutMs` for that type. */
+  private readonly typeTimeoutMs = new Map<string, number>();
   private running = false;
   private workers: NanoJobWorker[] = [];
 
@@ -142,6 +145,9 @@ export class Worker {
             return { variables };
           },
         });
+        // A step-declared job lock timeout (issue #596) applies to this step's derived
+        // job type, overriding the worker-wide `jobTimeoutMs` at `start()`.
+        if (s.timeoutMs !== undefined) this.typeTimeoutMs.set(jobType(wf.id, s.name), s.timeoutMs);
       });
     }
   }
@@ -200,7 +206,8 @@ export class Worker {
         jobType: type,
         workerName: this.name,
         maxParallelJobs: this.maxParallelJobs,
-        jobTimeoutMs: this.jobTimeoutMs,
+        // A step-declared `{ timeoutMs }` (issue #596) wins over the worker-wide default.
+        jobTimeoutMs: this.typeTimeoutMs.get(type) ?? this.jobTimeoutMs,
         pollTimeoutMs: this.pollTimeoutMs,
         autoStart: false,
         jobHandler: (job) => this.handleJob(type, route, job),