@bpmnkit/core 0.1.1 → 0.1.2

package/dist/bpmn/bpmn-builder.d.ts

@@ -4,11 +4,15 @@ import type { RestConnectorConfig } from "./rest-connector.js";
 export interface ElementOptions {
     name?: string;
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). Used by the AI Agent connector as a tool description. */
+    documentation?: string;
 }
 /** Options for send/receive task elements. */
 export interface MessageTaskOptions extends ElementOptions {
     /** Message name — generates or reuses a root <bpmn:message> and sets messageRef. */
     messageName?: string;
+    /** FEEL expression correlating this message to a specific process instance (`zeebe:subscription`). */
+    correlationKey?: string;
 }
 /** Options for creating a start event. */
 export interface StartEventOptions extends ElementOptions {
@@ -58,6 +62,11 @@ export interface ServiceTaskOptions {
     };
     /** Task header key-value pairs. */
     taskHeaders?: Record<string, string>;
+    /** Zeebe property key-value pairs (`zeebe:properties`/`zeebe:property`). */
+    zeebeProperties?: Array<{
+        name: string;
+        value: string;
+    }>;
     /** Zeebe modeler template ID. */
     modelerTemplate?: string;
     /** Zeebe modeler template version. */
@@ -66,6 +75,8 @@ export interface ServiceTaskOptions {
     modelerTemplateIcon?: string;
     /** Mark this task as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). Used by the AI Agent connector as a tool description. */
+    documentation?: string;
 }
 /** Options for creating a script task. */
 export interface ScriptTaskOptions {
@@ -77,6 +88,8 @@ export interface ScriptTaskOptions {
     resultVariable: string;
     /** Mark this task as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). */
+    documentation?: string;
 }
 /** Options for creating a user task. */
 export interface UserTaskOptions {
@@ -88,6 +101,20 @@ export interface UserTaskOptions {
     zeebeUserTask?: boolean;
     /** Mark this task as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). */
+    documentation?: string;
+    /** Static assignee (`zeebe:assignmentDefinition assignee`). FEEL expressions must start with "=". */
+    assignee?: string;
+    /** Candidate groups, comma-separated or a FEEL expression (`zeebe:assignmentDefinition candidateGroups`). */
+    candidateGroups?: string;
+    /** Candidate users, comma-separated or a FEEL expression (`zeebe:assignmentDefinition candidateUsers`). */
+    candidateUsers?: string;
+    /** Due date — ISO 8601 or FEEL expression (`zeebe:taskSchedule dueDate`). */
+    dueDate?: string;
+    /** Follow-up date — ISO 8601 or FEEL expression (`zeebe:taskSchedule followUpDate`). */
+    followUpDate?: string;
+    /** Task priority 0-100, default 50 (`zeebe:priorityDefinition`). */
+    priority?: number;
 }
 /** Options for creating a call activity. */
 export interface CallActivityOptions {
@@ -99,6 +126,8 @@ export interface CallActivityOptions {
     propagateAllChildVariables?: boolean;
     /** Mark this activity as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). */
+    documentation?: string;
 }
 /** Options for creating a business rule task. */
 export interface BusinessRuleTaskOptions {
@@ -112,6 +141,8 @@ export interface BusinessRuleTaskOptions {
     resultVariable?: string;
     /** Mark this task as a compensation handler. */
     isForCompensation?: boolean;
+    /** Free-text documentation (`<bpmn:documentation>`). */
+    documentation?: string;
 }
 /** Options for gateway elements. */
 export interface GatewayOptions extends ElementOptions {
@@ -128,6 +159,8 @@ export interface IntermediateCatchEventOptions extends ElementOptions {
     timerCycle?: string;
     /** Message name — creates a message catch event (aspirational). */
     messageName?: string;
+    /** FEEL expression correlating this message to a specific process instance (`zeebe:subscription`). Required for a deployable message catch when `messageName` is set. */
+    correlationKey?: string;
     /** Signal name — creates a signal catch event (aspirational). */
     signalName?: string;
 }
@@ -175,6 +208,8 @@ export interface BoundaryEventOptions extends ElementOptions {
     timerCycle?: string;
     /** Message name — creates a message boundary event (aspirational). */
     messageName?: string;
+    /** FEEL expression correlating this message to a specific process instance (`zeebe:subscription`). Required for a deployable message boundary event when `messageName` is set. */
+    correlationKey?: string;
     /** Signal name — creates a signal boundary event (aspirational). */
     signalName?: string;
     /** Creates a compensation boundary event. */
@@ -217,6 +252,11 @@ export interface AdHocSubProcessOptions extends ElementOptions {
     };
     /** Task header key-value pairs. */
     taskHeaders?: Record<string, string>;
+    /** Zeebe property key-value pairs (`zeebe:properties`/`zeebe:property`). */
+    zeebeProperties?: Array<{
+        name: string;
+        value: string;
+    }>;
     /** Multi-instance loop configuration. */
     loopCharacteristics?: {
         inputCollection: string;
@@ -231,6 +271,13 @@ export interface AdHocSubProcessOptions extends ElementOptions {
     modelerTemplateVersion?: string;
     /** Zeebe modeler template icon (data URI). */
     modelerTemplateIcon?: string;
+    /**
+     * FEEL expression evaluated after each tool activity completes; ends the
+     * ad-hoc scope when true (`bpmn:completionCondition`).
+     */
+    completionCondition?: string;
+    /** Whether still-running inner activity instances are cancelled once the completion condition is met (default true). */
+    cancelRemainingInstances?: boolean;
 }
 /**
  * Builder for a single named branch path from a gateway.
@@ -354,6 +401,15 @@ export declare class SubProcessContentBuilder {
     /** @internal */
     constructor(rootMessages?: BpmnMessage[]);
     private addElement;
+    /**
+     * Add an element with no sequence-flow wiring and no cursor movement.
+     *
+     * Used for ad-hoc sub-process tool activities, which the AI Agent connector
+     * requires to be root nodes (no incoming sequence flow, not a boundary event).
+     * Unlike `serviceTask()`/`userTask()`/etc., this does not auto-connect from
+     * the current cursor and does not move it.
+     */
+    addDisconnected(element: BpmnFlowElement): this;
     startEvent(id?: string, options?: StartEventOptions): this;
     endEvent(id?: string, options?: EndEventOptions): this;
     intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;

package/dist/bpmn/bpmn-builder.js

@@ -15,6 +15,12 @@ function resolveMessage(messageName, rootMessages) {
     }
     return existing.id;
 }
+/** Builds the `zeebe:subscription` extension element for a correlated message catch. */
+function buildMessageSubscriptionExt(correlationKey) {
+    if (!correlationKey)
+        return [];
+    return zeebeExtensionsToXmlElements({ subscription: { correlationKey } });
+}
 function buildEventDefinitions(opts, rootErrors, rootMessages, rootSignals, rootEscalations) {
     const defs = [];
     if (opts.timerDuration || opts.timerDate || opts.timerCycle) {
@@ -86,6 +92,7 @@ function makeFlowElement(id, type, options) {
         name: options?.name,
         incoming: [],
         outgoing: [],
+        documentation: options?.documentation,
         extensionElements: options?.extensionElements ?? [],
         unknownAttributes: {},
     };
@@ -232,6 +239,9 @@ function buildServiceTaskExtensions(options) {
             })),
         };
     }
+    if (options.zeebeProperties) {
+        extensions.properties = { properties: options.zeebeProperties };
+    }
     return zeebeExtensionsToXmlElements(extensions);
 }
 function makeConditionExpression(expression) {
@@ -240,6 +250,72 @@ function makeConditionExpression(expression) {
         attributes: { "xsi:type": "bpmn:tFormalExpression" },
     };
 }
+/** Builds the Zeebe extension elements + completion condition shared by all `adHocSubProcess()` overloads. */
+function buildAdHocSubProcessExtensions(options) {
+    const zeebeExt = {};
+    if (options?.taskDefinition) {
+        zeebeExt.taskDefinition = options.taskDefinition;
+    }
+    if (options?.ioMapping) {
+        zeebeExt.ioMapping = {
+            inputs: options.ioMapping.inputs ?? [],
+            outputs: options.ioMapping.outputs ?? [],
+        };
+    }
+    if (options?.taskHeaders) {
+        zeebeExt.taskHeaders = {
+            headers: Object.entries(options.taskHeaders).map(([key, value]) => ({ key, value })),
+        };
+    }
+    if (options?.zeebeProperties) {
+        zeebeExt.properties = { properties: options.zeebeProperties };
+    }
+    const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
+    const adHocAttrs = {};
+    if (options?.activeElementsCollection) {
+        adHocAttrs.activeElementsCollection = options.activeElementsCollection;
+    }
+    if (options?.outputCollection)
+        adHocAttrs.outputCollection = options.outputCollection;
+    if (options?.outputElement)
+        adHocAttrs.outputElement = options.outputElement;
+    if (Object.keys(adHocAttrs).length > 0) {
+        extensionElements.push({ name: "zeebe:adHoc", attributes: adHocAttrs, children: [] });
+    }
+    return {
+        extensionElements,
+        completionCondition: options?.completionCondition
+            ? makeConditionExpression(options.completionCondition)
+            : undefined,
+    };
+}
+/** Applies modeler-template attrs, sub-process contents, loop characteristics, and completion condition. */
+function finalizeAdHocSubProcessEl(element, options, sub, completionCondition) {
+    if (options?.modelerTemplate)
+        element.unknownAttributes["zeebe:modelerTemplate"] = options.modelerTemplate;
+    if (options?.modelerTemplateVersion) {
+        element.unknownAttributes["zeebe:modelerTemplateVersion"] = options.modelerTemplateVersion;
+    }
+    if (options?.modelerTemplateIcon) {
+        element.unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
+    }
+    if (element.type !== "adHocSubProcess")
+        return;
+    element.flowElements = sub._elements;
+    element.sequenceFlows = sub._flows;
+    element.textAnnotations = sub._textAnnotations;
+    element.associations = sub._associations;
+    if (options?.loopCharacteristics) {
+        element.loopCharacteristics = buildAdHocLoopCharacteristics(options.loopCharacteristics);
+    }
+    else if (options?.multiInstance) {
+        element.loopCharacteristics = buildMultiInstance(options.multiInstance);
+    }
+    element.completionCondition = completionCondition;
+    if (options?.cancelRemainingInstances !== undefined) {
+        element.cancelRemainingInstances = options.cancelRemainingInstances;
+    }
+}
 // ---------------------------------------------------------------------------
 // Element factory functions — shared by all three builder classes
 // ---------------------------------------------------------------------------
@@ -253,6 +329,7 @@ function makeServiceTaskEl(id, options) {
         unknownAttributes["zeebe:modelerTemplateIcon"] = options.modelerTemplateIcon;
     const el = makeFlowElement(id, "serviceTask", {
         name: options.name,
+        documentation: options.documentation,
         extensionElements: buildServiceTaskExtensions(options),
     });
     el.unknownAttributes = unknownAttributes;
@@ -263,6 +340,7 @@ function makeServiceTaskEl(id, options) {
 function makeScriptTaskEl(id, options) {
     const el = makeFlowElement(id, "scriptTask", {
         name: options.name,
+        documentation: options.documentation,
         extensionElements: zeebeExtensionsToXmlElements({
             unknownElements: [
                 {
@@ -281,8 +359,27 @@ function makeUserTaskEl(id, options) {
     const ext = zeebeExtensionsToXmlElements({
         ...(options?.zeebeUserTask ? { userTask: true } : {}),
         ...(options?.formId ? { formDefinition: { formId: options.formId } } : {}),
+        ...(options?.assignee || options?.candidateGroups || options?.candidateUsers
+            ? {
+                assignmentDefinition: {
+                    assignee: options?.assignee,
+                    candidateGroups: options?.candidateGroups,
+                    candidateUsers: options?.candidateUsers,
+                },
+            }
+            : {}),
+        ...(options?.dueDate || options?.followUpDate
+            ? { taskSchedule: { dueDate: options?.dueDate, followUpDate: options?.followUpDate } }
+            : {}),
+        ...(options?.priority !== undefined
+            ? { priorityDefinition: { priority: String(options.priority) } }
+            : {}),
+    });
+    const el = makeFlowElement(id, "userTask", {
+        name: options?.name,
+        documentation: options?.documentation,
+        extensionElements: ext,
     });
-    const el = makeFlowElement(id, "userTask", { name: options?.name, extensionElements: ext });
     if (options?.isForCompensation)
         el.isForCompensation = true;
     return el;
@@ -302,6 +399,7 @@ function makeBusinessRuleTaskEl(id, options) {
     }
     const el = makeFlowElement(id, "businessRuleTask", {
         name: options?.name,
+        documentation: options?.documentation,
         extensionElements: ext,
     });
     if (options?.isForCompensation)
@@ -315,6 +413,7 @@ function makeCallActivityEl(id, options) {
     }
     const el = makeFlowElement(id, "callActivity", {
         name: options.name,
+        documentation: options.documentation,
         extensionElements: zeebeExtensionsToXmlElements({
             unknownElements: [{ name: "zeebe:calledElement", attributes: attrs, children: [] }],
         }),
@@ -667,7 +766,10 @@ export class BranchBuilder {
         return this.addElement(el);
     }
     intermediateCatchEvent(id, options) {
-        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", options);
+        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options?.correlationKey),
+        });
         if (el.type === "intermediateCatchEvent" && options) {
             el.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
@@ -698,7 +800,10 @@ export class BranchBuilder {
      * cursor to return to the task afterward.
      */
     boundaryEvent(id, options) {
-        const element = makeFlowElement(id, "boundaryEvent", options);
+        const element = makeFlowElement(id, "boundaryEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options.correlationKey),
+        });
         if (element.type === "boundaryEvent") {
             element.attachedToRef = options.attachedTo;
             element.cancelActivity = options.cancelActivity;
@@ -770,68 +875,13 @@ export class BranchBuilder {
         resolved.content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
-        const zeebeExt = {};
-        if (resolved.options?.taskDefinition) {
-            zeebeExt.taskDefinition = resolved.options.taskDefinition;
-        }
-        if (resolved.options?.ioMapping) {
-            zeebeExt.ioMapping = {
-                inputs: resolved.options.ioMapping.inputs ?? [],
-                outputs: resolved.options.ioMapping.outputs ?? [],
-            };
-        }
-        if (resolved.options?.taskHeaders) {
-            zeebeExt.taskHeaders = {
-                headers: Object.entries(resolved.options.taskHeaders).map(([key, value]) => ({
-                    key,
-                    value,
-                })),
-            };
-        }
-        const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
-        const adHocAttrs = {};
-        if (resolved.options?.activeElementsCollection) {
-            adHocAttrs.activeElementsCollection = resolved.options.activeElementsCollection;
-        }
-        if (resolved.options?.outputCollection) {
-            adHocAttrs.outputCollection = resolved.options.outputCollection;
-        }
-        if (resolved.options?.outputElement) {
-            adHocAttrs.outputElement = resolved.options.outputElement;
-        }
-        if (Object.keys(adHocAttrs).length > 0) {
-            extensionElements.push({
-                name: "zeebe:adHoc",
-                attributes: adHocAttrs,
-                children: [],
-            });
-        }
+        const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
         const element = makeFlowElement(id, "adHocSubProcess", {
             name: resolved.options?.name,
+            documentation: resolved.options?.documentation,
             extensionElements,
         });
-        if (resolved.options?.modelerTemplate) {
-            element.unknownAttributes["zeebe:modelerTemplate"] = resolved.options.modelerTemplate;
-        }
-        if (resolved.options?.modelerTemplateVersion) {
-            element.unknownAttributes["zeebe:modelerTemplateVersion"] =
-                resolved.options.modelerTemplateVersion;
-        }
-        if (resolved.options?.modelerTemplateIcon) {
-            element.unknownAttributes["zeebe:modelerTemplateIcon"] = resolved.options.modelerTemplateIcon;
-        }
-        if (element.type === "adHocSubProcess") {
-            element.flowElements = sub._elements;
-            element.sequenceFlows = sub._flows;
-            element.textAnnotations = sub._textAnnotations;
-            element.associations = sub._associations;
-            if (resolved.options?.loopCharacteristics) {
-                element.loopCharacteristics = buildAdHocLoopCharacteristics(resolved.options.loopCharacteristics);
-            }
-            else if (resolved.options?.multiInstance) {
-                element.loopCharacteristics = buildMultiInstance(resolved.options.multiInstance);
-            }
-        }
+        finalizeAdHocSubProcessEl(element, resolved.options, sub, completionCondition);
         return this.addElement(element);
     }
     /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
@@ -953,6 +1003,21 @@ export class SubProcessContentBuilder {
         this.lastNodeId = element.id;
         return this;
     }
+    /**
+     * Add an element with no sequence-flow wiring and no cursor movement.
+     *
+     * Used for ad-hoc sub-process tool activities, which the AI Agent connector
+     * requires to be root nodes (no incoming sequence flow, not a boundary event).
+     * Unlike `serviceTask()`/`userTask()`/etc., this does not auto-connect from
+     * the current cursor and does not move it.
+     */
+    addDisconnected(element) {
+        if (this._elements.some((n) => n.id === element.id)) {
+            throw new Error(`Duplicate element ID "${element.id}" in sub-process`);
+        }
+        this._elements.push(element);
+        return this;
+    }
     // ---- Events ----
     startEvent(id, options) {
         const el = makeFlowElement(id ?? generateId("StartEvent"), "startEvent", options);
@@ -976,7 +1041,10 @@ export class SubProcessContentBuilder {
         return this.addElement(el);
     }
     intermediateCatchEvent(id, options) {
-        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", options);
+        const el = makeFlowElement(id ?? generateId("IntermediateCatchEvent"), "intermediateCatchEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options?.correlationKey),
+        });
         if (el.type === "intermediateCatchEvent" && options)
             el.eventDefinitions = buildEventDefinitions(options);
         return this.addElement(el);
@@ -1131,7 +1199,10 @@ export class SubProcessContentBuilder {
      * cursor to return to the task afterward.
      */
     boundaryEvent(id, options) {
-        const element = makeFlowElement(id, "boundaryEvent", options);
+        const element = makeFlowElement(id, "boundaryEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options.correlationKey),
+        });
         if (element.type === "boundaryEvent") {
             element.attachedToRef = options.attachedTo;
             element.cancelActivity = options.cancelActivity;
@@ -1200,68 +1271,13 @@ export class SubProcessContentBuilder {
         resolved.content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
-        const zeebeExt = {};
-        if (resolved.options?.taskDefinition) {
-            zeebeExt.taskDefinition = resolved.options.taskDefinition;
-        }
-        if (resolved.options?.ioMapping) {
-            zeebeExt.ioMapping = {
-                inputs: resolved.options.ioMapping.inputs ?? [],
-                outputs: resolved.options.ioMapping.outputs ?? [],
-            };
-        }
-        if (resolved.options?.taskHeaders) {
-            zeebeExt.taskHeaders = {
-                headers: Object.entries(resolved.options.taskHeaders).map(([key, value]) => ({
-                    key,
-                    value,
-                })),
-            };
-        }
-        const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
-        const adHocAttrs = {};
-        if (resolved.options?.activeElementsCollection) {
-            adHocAttrs.activeElementsCollection = resolved.options.activeElementsCollection;
-        }
-        if (resolved.options?.outputCollection) {
-            adHocAttrs.outputCollection = resolved.options.outputCollection;
-        }
-        if (resolved.options?.outputElement) {
-            adHocAttrs.outputElement = resolved.options.outputElement;
-        }
-        if (Object.keys(adHocAttrs).length > 0) {
-            extensionElements.push({
-                name: "zeebe:adHoc",
-                attributes: adHocAttrs,
-                children: [],
-            });
-        }
+        const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
         const element = makeFlowElement(id, "adHocSubProcess", {
             name: resolved.options?.name,
+            documentation: resolved.options?.documentation,
             extensionElements,
         });
-        if (resolved.options?.modelerTemplate) {
-            element.unknownAttributes["zeebe:modelerTemplate"] = resolved.options.modelerTemplate;
-        }
-        if (resolved.options?.modelerTemplateVersion) {
-            element.unknownAttributes["zeebe:modelerTemplateVersion"] =
-                resolved.options.modelerTemplateVersion;
-        }
-        if (resolved.options?.modelerTemplateIcon) {
-            element.unknownAttributes["zeebe:modelerTemplateIcon"] = resolved.options.modelerTemplateIcon;
-        }
-        if (element.type === "adHocSubProcess") {
-            element.flowElements = sub._elements;
-            element.sequenceFlows = sub._flows;
-            element.textAnnotations = sub._textAnnotations;
-            element.associations = sub._associations;
-            if (resolved.options?.loopCharacteristics) {
-                element.loopCharacteristics = buildAdHocLoopCharacteristics(resolved.options.loopCharacteristics);
-            }
-            else if (resolved.options?.multiInstance) {
-                element.loopCharacteristics = buildMultiInstance(resolved.options.multiInstance);
-            }
-        }
+        finalizeAdHocSubProcessEl(element, resolved.options, sub, completionCondition);
         return this.addElement(element);
     }
     /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
@@ -1421,7 +1437,10 @@ export class ProcessBuilder {
     /** Add an intermediate catch event (timer, message, signal). */
     intermediateCatchEvent(id, options) {
         const nodeId = id ?? generateId("IntermediateCatchEvent");
-        const element = makeFlowElement(nodeId, "intermediateCatchEvent", options);
+        const element = makeFlowElement(nodeId, "intermediateCatchEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options?.correlationKey),
+        });
         if (element.type === "intermediateCatchEvent" && options) {
             element.eventDefinitions = buildEventDefinitions(options, this.rootErrors, this.rootMessages, this.rootSignals, this.rootEscalations);
         }
@@ -1435,7 +1454,10 @@ export class ProcessBuilder {
      * They start a new outgoing chain from the boundary event itself.
      */
     boundaryEvent(id, options) {
-        const element = makeFlowElement(id, "boundaryEvent", options);
+        const element = makeFlowElement(id, "boundaryEvent", {
+            ...options,
+            extensionElements: buildMessageSubscriptionExt(options.correlationKey),
+        });
         if (element.type === "boundaryEvent") {
             element.attachedToRef = options.attachedTo;
             element.cancelActivity = options.cancelActivity;
@@ -1690,69 +1712,13 @@ export class ProcessBuilder {
         resolved.content(sub);
         insertJoinGateways(sub._elements, sub._flows);
         recomputeIncomingOutgoing(sub._elements, sub._flows);
-        const zeebeExt = {};
-        if (resolved.options?.taskDefinition) {
-            zeebeExt.taskDefinition = resolved.options.taskDefinition;
-        }
-        if (resolved.options?.ioMapping) {
-            zeebeExt.ioMapping = {
-                inputs: resolved.options.ioMapping.inputs ?? [],
-                outputs: resolved.options.ioMapping.outputs ?? [],
-            };
-        }
-        if (resolved.options?.taskHeaders) {
-            zeebeExt.taskHeaders = {
-                headers: Object.entries(resolved.options.taskHeaders).map(([key, value]) => ({
-                    key,
-                    value,
-                })),
-            };
-        }
-        const extensionElements = zeebeExtensionsToXmlElements(zeebeExt);
-        // zeebe:adHoc element
-        const adHocAttrs = {};
-        if (resolved.options?.activeElementsCollection) {
-            adHocAttrs.activeElementsCollection = resolved.options.activeElementsCollection;
-        }
-        if (resolved.options?.outputCollection) {
-            adHocAttrs.outputCollection = resolved.options.outputCollection;
-        }
-        if (resolved.options?.outputElement) {
-            adHocAttrs.outputElement = resolved.options.outputElement;
-        }
-        if (Object.keys(adHocAttrs).length > 0) {
-            extensionElements.push({
-                name: "zeebe:adHoc",
-                attributes: adHocAttrs,
-                children: [],
-            });
-        }
+        const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
         const element = makeFlowElement(id, "adHocSubProcess", {
             name: resolved.options?.name,
+            documentation: resolved.options?.documentation,
             extensionElements,
         });
-        if (resolved.options?.modelerTemplate) {
-            element.unknownAttributes["zeebe:modelerTemplate"] = resolved.options.modelerTemplate;
-        }
-        if (resolved.options?.modelerTemplateVersion) {
-            element.unknownAttributes["zeebe:modelerTemplateVersion"] =
-                resolved.options.modelerTemplateVersion;
-        }
-        if (resolved.options?.modelerTemplateIcon) {
-            element.unknownAttributes["zeebe:modelerTemplateIcon"] = resolved.options.modelerTemplateIcon;
-        }
-        if (element.type === "adHocSubProcess") {
-            element.flowElements = sub._elements;
-            element.sequenceFlows = sub._flows;
-            element.textAnnotations = sub._textAnnotations;
-            element.associations = sub._associations;
-            if (resolved.options?.loopCharacteristics) {
-                element.loopCharacteristics = buildAdHocLoopCharacteristics(resolved.options.loopCharacteristics);
-            }
-            else if (resolved.options?.multiInstance) {
-                element.loopCharacteristics = buildMultiInstance(resolved.options.multiInstance);
-            }
-        }
+        finalizeAdHocSubProcessEl(element, resolved.options, sub, completionCondition);
         this.addFlowElement(element);
         return this;
     }

package/dist/bpmn/bpmn-model.d.ts

@@ -183,6 +183,10 @@ export interface BpmnReceiveTask extends BpmnFlowNodeBase {
 export interface BpmnAdHocSubProcess extends BpmnFlowNodeBase {
     type: "adHocSubProcess";
     loopCharacteristics?: BpmnMultiInstanceLoopCharacteristics;
+    /** FEEL expression evaluated after each tool activity completes; ends the ad-hoc scope when true. */
+    completionCondition?: BpmnConditionExpression;
+    /** Whether still-running inner activity instances are cancelled once the completion condition is met (default true). */
+    cancelRemainingInstances?: boolean;
     flowElements: BpmnFlowElement[];
     sequenceFlows: BpmnSequenceFlow[];
     textAnnotations: BpmnTextAnnotation[];

package/dist/bpmn/bpmn-parser.js

@@ -328,13 +328,21 @@ function parseFlowElement(element) {
                 loopCharacteristics: parseLoopCharacteristics(element),
                 isForCompensation: attr(element, "isForCompensation") === "true" ? true : undefined,
             };
-        case "adHocSubProcess":
+        case "adHocSubProcess": {
+            const completionEl = findChild(element, "completionCondition");
             return {
                 ...base,
                 type: "adHocSubProcess",
                 loopCharacteristics: parseLoopCharacteristics(element),
+                completionCondition: completionEl
+                    ? { text: completionEl.text ?? "", attributes: { ...completionEl.attributes } }
+                    : undefined,
+                cancelRemainingInstances: attr(element, "cancelRemainingInstances") !== undefined
+                    ? attr(element, "cancelRemainingInstances") === "true"
+                    : undefined,
                 ...parseProcessContents(element),
             };
+        }
         case "subProcess":
             return {
                 ...base,

package/dist/bpmn/bpmn-serializer.js

@@ -202,8 +202,14 @@ function serializeFlowElement(fe, ns) {
             children.push(...serializeLoopCharacteristics(fe.loopCharacteristics, bp));
             break;
         case "adHocSubProcess":
+            if (fe.cancelRemainingInstances !== undefined) {
+                attrs.cancelRemainingInstances = String(fe.cancelRemainingInstances);
+            }
             children.push(...serializeLoopCharacteristics(fe.loopCharacteristics, bp));
             children.push(...serializeProcessContents(fe, ns));
+            if (fe.completionCondition) {
+                children.push(el(`${bp}:completionCondition`, fe.completionCondition.attributes, [], fe.completionCondition.text));
+            }
             break;
         case "subProcess":
             if (fe.triggeredByEvent !== undefined)

package/dist/bpmn/optimize/agentic.d.ts

@@ -0,0 +1,10 @@
+import type { BpmnProcess } from "../bpmn-model.js";
+import type { OptimizationFinding } from "./types.js";
+/**
+ * Agentic-specific checks for the Camunda 8 AI Agent Sub-process pattern:
+ * tools must be root nodes with a description the LLM can read, every
+ * `fromAi()` call must reference `toolCall.*`, and the agent should aggregate
+ * tool results and cap its model-call budget.
+ */
+export declare function analyzeAgentic(p: BpmnProcess): OptimizationFinding[];
+//# sourceMappingURL=agentic.d.ts.map