@bpmnkit/engine 0.1.29 → 0.1.31

package/README.md

@@ -9,7 +9,7 @@
   [![ai-assisted](https://img.shields.io/badge/AI--assisted-claude-8b5cf6?style=flat-square)](https://github.com/bpmnkit/monorepo)
   [![experimental](https://img.shields.io/badge/status-experimental-f59e0b?style=flat-square)](https://github.com/bpmnkit/monorepo)
 
-  [Website](https://bpmnkit.com) · [Documentation](https://docs.bpmnkit.com) · [GitHub](https://github.com/bpmnkit/monorepo) · [Changelog](https://github.com/bpmnkit/monorepo/blob/main/packages/engine/CHANGELOG.md)
+  [Website](https://bpmnkit.com) · [Documentation](https://bpmnkit.com/docs) · [GitHub](https://github.com/bpmnkit/monorepo) · [Changelog](https://github.com/bpmnkit/monorepo/blob/main/packages/engine/CHANGELOG.md)
 </div>
 
 ---
@@ -117,10 +117,12 @@ const instance = engine.start("my-process", {}, {
 | [`@bpmnkit/plugins`](https://www.npmjs.com/package/@bpmnkit/plugins) | 22 composable canvas plugins |
 | [`@bpmnkit/api`](https://www.npmjs.com/package/@bpmnkit/api) | Camunda 8 REST API TypeScript client |
 | [`@bpmnkit/ascii`](https://www.npmjs.com/package/@bpmnkit/ascii) | Render BPMN diagrams as Unicode ASCII art |
+| [`@bpmnkit/docspack`](https://www.npmjs.com/package/@bpmnkit/docspack) | BPMN Kit docs as an offline docspack package for AI agents |
 | [`@bpmnkit/ui`](https://www.npmjs.com/package/@bpmnkit/ui) | Shared design tokens and UI components |
 | [`@bpmnkit/profiles`](https://www.npmjs.com/package/@bpmnkit/profiles) | Shared auth, profile storage, and client factories for CLI & proxy |
 | [`@bpmnkit/operate`](https://www.npmjs.com/package/@bpmnkit/operate) | Monitoring & operations frontend for Camunda clusters |
 | [`@bpmnkit/connector-gen`](https://www.npmjs.com/package/@bpmnkit/connector-gen) | Generate connector templates from OpenAPI specs |
+| [`@bpmnkit/connectors`](https://www.npmjs.com/package/@bpmnkit/connectors) | Camunda 8 OOTB connector catalog and deterministic template application |
 | [`@bpmnkit/cli`](https://www.npmjs.com/package/@bpmnkit/cli) | Camunda 8 command-line interface (casen) |
 | [`@bpmnkit/proxy`](https://www.npmjs.com/package/@bpmnkit/proxy) | Local AI bridge and Camunda API proxy server |
 | [`@bpmnkit/patterns`](https://www.npmjs.com/package/@bpmnkit/patterns) | Domain process patterns for BPMNKit AIKit |

package/dist/dmn.js

@@ -9,8 +9,14 @@ export function evaluateDecision(decision, vars) {
         return null;
     const hitPolicy = table.hitPolicy ?? "UNIQUE";
     const matchedOutputs = [];
+    // Input expressions do not depend on the rule, so evaluate each column once
+    // instead of once per rule.
+    const inputValues = table.inputs.map((col) => {
+        const inputExpr = col.inputExpression.text ?? "";
+        return inputExpr.trim() === "" ? null : evalExpression(inputExpr, vars);
+    });
     for (const rule of table.rules) {
-        if (ruleMatches(table.inputs, rule.inputEntries, vars)) {
+        if (ruleMatches(table.inputs, inputValues, rule.inputEntries, vars)) {
             const output = {};
             for (let i = 0; i < table.outputs.length; i++) {
                 const col = table.outputs[i];
@@ -27,7 +33,7 @@ export function evaluateDecision(decision, vars) {
     }
     return buildResult(hitPolicy, table.aggregation, matchedOutputs, table.outputs.length);
 }
-function ruleMatches(inputs, inputEntries, vars) {
+function ruleMatches(inputs, inputValues, inputEntries, vars) {
     const feelVars = vars;
     for (let i = 0; i < inputs.length; i++) {
         const col = inputs[i];
@@ -36,8 +42,7 @@ function ruleMatches(inputs, inputEntries, vars) {
             continue;
         if (entry.text.trim() === "")
             continue; // empty = "any"
-        const inputExpr = col.inputExpression.text ?? "";
-        const inputValue = inputExpr.trim() === "" ? null : evalExpression(inputExpr, vars);
+        const inputValue = inputValues[i] ?? null;
         const parsed = parseUnaryTests(entry.text);
         if (parsed.ast === null)
             continue;

package/dist/instance.d.ts

@@ -9,6 +9,10 @@ export declare class ProcessInstance {
     private _error;
     /** tokenId → Token */
     private readonly allTokens;
+    /** elementId → tokens currently sitting on that element. */
+    private readonly tokensByElement;
+    /** Zeebe extensions parsed once per element for the life of this instance. */
+    private readonly zeebeExtCache;
     /** Scope stack: rootScopeId + any active sub-process scopes */
     private readonly scopes;
     /** Message correlation: messageName → resolve callback */
@@ -46,6 +50,9 @@ export declare class ProcessInstance {
     deliverMessage(messageName: string): void;
     private buildScopeCtx;
     private createToken;
+    /** The first token currently on `elementId`, if any. */
+    private tokenOn;
+    private zeebeExt;
     private removeToken;
     /** elementId → set of incomingFlowIds received */
     private readonly joins;

package/dist/instance.js

@@ -13,6 +13,10 @@ export class ProcessInstance {
     _error;
     /** tokenId → Token */
     allTokens = new Map();
+    /** elementId → tokens currently sitting on that element. */
+    tokensByElement = new Map();
+    /** Zeebe extensions parsed once per element for the life of this instance. */
+    zeebeExtCache = new WeakMap();
     /** Scope stack: rootScopeId + any active sub-process scopes */
     scopes = new Map();
     /** Message correlation: messageName → resolve callback */
@@ -78,6 +82,7 @@ export class ProcessInstance {
         this._state = "terminated";
         this.cancelAllTimers();
         this.allTokens.clear();
+        this.tokensByElement.clear();
         for (const ctx of this.scopes.values())
             ctx.tokens.clear();
     }
@@ -141,11 +146,39 @@ export class ProcessInstance {
     createToken(elementId, scopeId) {
         const token = { id: generateId("tok"), elementId, scopeId };
         this.allTokens.set(token.id, token);
+        const onElement = this.tokensByElement.get(elementId);
+        if (onElement)
+            onElement.add(token);
+        else
+            this.tokensByElement.set(elementId, new Set([token]));
         this.scopes.get(scopeId)?.tokens.add(token.id);
         return token;
     }
+    /** The first token currently on `elementId`, if any. */
+    tokenOn(elementId) {
+        const onElement = this.tokensByElement.get(elementId);
+        if (onElement === undefined)
+            return undefined;
+        for (const token of onElement)
+            return token;
+        return undefined;
+    }
+    zeebeExt(el) {
+        let ext = this.zeebeExtCache.get(el);
+        if (ext === undefined) {
+            ext = parseZeebeExt(el.extensionElements);
+            this.zeebeExtCache.set(el, ext);
+        }
+        return ext;
+    }
     removeToken(token) {
         this.allTokens.delete(token.id);
+        const onElement = this.tokensByElement.get(token.elementId);
+        if (onElement !== undefined) {
+            onElement.delete(token);
+            if (onElement.size === 0)
+                this.tokensByElement.delete(token.elementId);
+        }
         this.scopes.get(token.scopeId)?.tokens.delete(token.id);
         this.timerCancels.get(token.id)?.();
         this.timerCancels.delete(token.id);
@@ -186,7 +219,7 @@ export class ProcessInstance {
         }
         this.emit({ type: "element:entering", elementId, elementName: el.name, elementType: el.type });
         // Apply ioMapping inputs
-        const ext = parseZeebeExt(el.extensionElements);
+        const ext = this.zeebeExt(el);
         if (ext.ioMapping) {
             for (const inp of ext.ioMapping.inputs) {
                 let val;
@@ -204,12 +237,16 @@ export class ProcessInstance {
                         val = resolved;
                     }
                 }
-                else {
+                else if (inp.source.trimStart().startsWith("=")) {
                     val = this.evalFeel(inp.source, scopeId, {
                         elementId: el.id,
                         property: `input:${inp.target}`,
                     });
                 }
+                else {
+                    // A zeebe:input source without a leading "=" is a literal value, not FEEL.
+                    val = inp.source;
+                }
                 this.variables.setLocal(scopeId, inp.target, val);
                 this.emit({ type: "variable:set", name: inp.target, value: val, scopeId });
             }
@@ -262,8 +299,21 @@ export class ProcessInstance {
             case "transaction":
                 await this.handleSubProcess(token, el, ctx);
                 break;
+            case "adHocSubProcess":
+                if (ext.taskDefinition) {
+                    // Job-worker implementation (e.g. the AI Agent Sub-process connector) —
+                    // dispatch as a job so scenarios can mock it like any other task.
+                    // The tools nested inside are not individually executed; see the
+                    // scenario runner docs for scope.
+                    await this.handleJobTask(token, el, ext, ctx);
+                }
+                else {
+                    // BPMN-native ad-hoc sub-process — auto-complete (tools not executed).
+                    await this.complete(token, ctx);
+                }
+                break;
             default:
-                // eventSubProcess, adHocSubProcess, callActivity, etc. — auto-complete
+                // eventSubProcess, callActivity, etc. — auto-complete
                 await this.complete(token, ctx);
                 break;
         }
@@ -273,12 +323,11 @@ export class ProcessInstance {
         const eventDef = el.eventDefinitions[0];
         if (eventDef?.type === "terminate") {
             this.cancelAllTimers();
-            for (const [id] of this.allTokens) {
-                const tok = this.allTokens.get(id);
-                if (tok !== undefined)
-                    this.scopes.get(tok.scopeId)?.tokens.delete(id);
+            for (const tok of this.allTokens.values()) {
+                this.scopes.get(tok.scopeId)?.tokens.delete(tok.id);
             }
             this.allTokens.clear();
+            this.tokensByElement.clear();
             this.emit({
                 type: "element:leaving",
                 elementId: el.id,
@@ -414,7 +463,7 @@ export class ProcessInstance {
             });
             return;
         }
-        const result = evaluateDecision(decision, this.variables.getAll(scopeId));
+        const result = evaluateDecision(decision, this.variables.snapshot(scopeId));
         this.variables.set(scopeId, cd.resultVariable, result);
         this.emit({ type: "variable:set", name: cd.resultVariable, value: result, scopeId });
     }
@@ -536,12 +585,9 @@ export class ProcessInstance {
             const cancel = scheduleTimer(timerDef, () => {
                 this.boundaryTimerCancels.delete(elementId);
                 // Remove the parent token
-                for (const [, tok] of this.allTokens) {
-                    if (tok.elementId === elementId) {
-                        this.removeToken(tok);
-                        break;
-                    }
-                }
+                const parentToken = this.tokenOn(elementId);
+                if (parentToken !== undefined)
+                    this.removeToken(parentToken);
                 if (be.cancelActivity !== false) {
                     void this.activate(be.id, scopeId, undefined);
                 }
@@ -562,12 +608,9 @@ export class ProcessInstance {
                     continue;
                 if (errDef.errorRef !== undefined && errDef.errorRef !== errorCode)
                     continue;
-                for (const [, tok] of this.allTokens) {
-                    if (tok.elementId === attachedTo) {
-                        this.removeToken(tok);
-                        break;
-                    }
-                }
+                const hostToken = this.tokenOn(attachedTo);
+                if (hostToken !== undefined)
+                    this.removeToken(hostToken);
                 void this.activate(be.id, ctx.scopeId, undefined);
                 return;
             }
@@ -591,7 +634,7 @@ export class ProcessInstance {
         const el = ctx.elements.get(token.elementId);
         if (el === undefined)
             return;
-        const ext = parseZeebeExt(el.extensionElements);
+        const ext = this.zeebeExt(el);
         // Apply ioMapping outputs
         if (ext.ioMapping) {
             for (const out of ext.ioMapping.outputs) {
@@ -659,14 +702,15 @@ export class ProcessInstance {
     }
     // ── FEEL helpers ───────────────────────────────────────────────────────────
     evalFeel(expr, scopeId, emitCtx) {
-        const vars = this.variables.getAll(scopeId);
+        const vars = this.variables.snapshot(scopeId);
         // Strip Camunda FEEL prefix ("= expr") — the leading "=" is a type indicator, not part of the expression.
         const normalized = expr.trim().replace(/^=\s*/, "");
         const parsed = parseExpression(normalized);
         if (parsed.ast === null)
             return undefined;
         const result = evaluate(parsed.ast, { vars: vars });
-        if (emitCtx !== undefined) {
+        // The event carries a copy of every variable; skip building it when nobody listens.
+        if (emitCtx !== undefined && this.listeners.length > 0) {
             this.emit({
                 type: "feel:evaluated",
                 elementId: emitCtx.elementId,

package/dist/variables.d.ts

@@ -6,6 +6,11 @@
 export declare class VariableStore {
     private readonly scopes;
     private readonly parents;
+    /**
+     * Merged root → scope views, built lazily and then kept current by every
+     * write, so expression evaluation never re-merges the scope chain.
+     */
+    private readonly snapshots;
     createScope(id: string, parentId?: string): void;
     removeScope(id: string): void;
     /** Walk up the chain and return the value, or undefined if not found. */
@@ -17,8 +22,16 @@ export declare class VariableStore {
     set(scopeId: string, name: string, value: unknown): void;
     /** Set a variable in this scope only, regardless of parent state. */
     setLocal(scopeId: string, name: string, value: unknown): void;
-    /** Return all variables merged from root → this scope (child wins). */
+    /** Return a fresh copy of all variables merged from root → this scope (child wins). */
     getAll(scopeId: string): Record<string, unknown>;
+    /**
+     * All variables merged from root → this scope, as a shared object that
+     * later writes update in place. Callers must treat it as read-only and not
+     * hold it across a write.
+     */
+    snapshot(scopeId: string): Record<string, unknown>;
+    /** Store the value and patch every cached view that sees this scope's copy of `name`. */
+    private write;
     private hasOwn;
     private ancestorHas;
 }

package/dist/variables.js

@@ -6,6 +6,11 @@
 export class VariableStore {
     scopes = new Map();
     parents = new Map();
+    /**
+     * Merged root → scope views, built lazily and then kept current by every
+     * write, so expression evaluation never re-merges the scope chain.
+     */
+    snapshots = new Map();
     createScope(id, parentId) {
         this.scopes.set(id, new Map());
         if (parentId !== undefined) {
@@ -15,6 +20,7 @@ export class VariableStore {
     removeScope(id) {
         this.scopes.delete(id);
         this.parents.delete(id);
+        this.snapshots.delete(id);
     }
     /** Walk up the chain and return the value, or undefined if not found. */
     get(scopeId, name) {
@@ -34,7 +40,7 @@ export class VariableStore {
      */
     set(scopeId, name, value) {
         if (this.hasOwn(scopeId, name)) {
-            this.scopes.get(scopeId)?.set(name, value);
+            this.write(scopeId, name, value);
             return;
         }
         const parentId = this.parents.get(scopeId);
@@ -42,25 +48,55 @@ export class VariableStore {
             this.set(parentId, name, value);
             return;
         }
-        this.scopes.get(scopeId)?.set(name, value);
+        this.write(scopeId, name, value);
     }
     /** Set a variable in this scope only, regardless of parent state. */
     setLocal(scopeId, name, value) {
-        this.scopes.get(scopeId)?.set(name, value);
+        this.write(scopeId, name, value);
     }
-    /** Return all variables merged from root → this scope (child wins). */
+    /** Return a fresh copy of all variables merged from root → this scope (child wins). */
     getAll(scopeId) {
+        return { ...this.snapshot(scopeId) };
+    }
+    /**
+     * All variables merged from root → this scope, as a shared object that
+     * later writes update in place. Callers must treat it as read-only and not
+     * hold it across a write.
+     */
+    snapshot(scopeId) {
+        const cached = this.snapshots.get(scopeId);
+        if (cached !== undefined)
+            return cached;
         const parentId = this.parents.get(scopeId);
-        const parentVars = parentId !== undefined ? this.getAll(parentId) : {};
+        const parentVars = parentId !== undefined ? this.snapshot(parentId) : {};
         const scope = this.scopes.get(scopeId);
         if (scope === undefined)
             return parentVars;
         const result = { ...parentVars };
-        for (const [k, v] of scope) {
+        for (const [k, v] of scope)
             result[k] = v;
-        }
+        this.snapshots.set(scopeId, result);
         return result;
     }
+    /** Store the value and patch every cached view that sees this scope's copy of `name`. */
+    write(scopeId, name, value) {
+        const scope = this.scopes.get(scopeId);
+        if (scope === undefined)
+            return;
+        scope.set(name, value);
+        for (const [viewId, view] of this.snapshots) {
+            // Walk from the view's scope up to the writer; a scope in between that
+            // owns the name shadows the write for this view.
+            let current = viewId;
+            while (current !== undefined && current !== scopeId) {
+                if (this.scopes.get(current)?.has(name))
+                    break;
+                current = this.parents.get(current);
+            }
+            if (current === scopeId)
+                view[name] = value;
+        }
+    }
     hasOwn(scopeId, name) {
         return this.scopes.get(scopeId)?.has(name) ?? false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/engine",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,11 +21,11 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@bpmnkit/core": "0.1.1",
-    "@bpmnkit/feel": "0.0.19"
+    "@bpmnkit/core": "0.2.0",
+    "@bpmnkit/feel": "0.0.20"
   },
   "optionalDependencies": {
-    "@bpmnkit/reebe-wasm": "0.1.5"
+    "@bpmnkit/reebe-wasm": "0.1.6"
   },
   "description": "Lightweight BPMN 2.0 process execution engine for browsers and Node.js — zero dependencies",
   "keywords": [