@nanobpm/bojtos-kit 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { ensureWasm, createBojtosSession, type BojtosSession, type WasmSource, } from "./session.js";
-export { dispatchWorkers, dispatchRound, JobFailure, type JobHandler, type JobResult, type DispatchOptions, type DispatchResult, type RoundResult, } from "./worker.js";
-export type { Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, ActiveEl, WasmEvent, } from "./types.js";
+export { dispatchWorkers, dispatchRound, JobFailure, type JobHandler, type JobResult, type AgentHandler, type DispatchOptions, type DispatchResult, type RoundResult, } from "./worker.js";
+export type { Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, ActiveEl, AgentActivation, AgentResult, WasmEvent, } from "./types.js";

package/dist/session.d.ts

@@ -1,5 +1,5 @@
 import { type InitInput } from "@nanobpm/engine-wasm";
-import type { ActivatedJob, Snapshot, WasmEvent } from "./types.js";
+import type { ActivatedJob, ActivateInstruction, AgentResult, Snapshot, WasmEvent } from "./types.js";
 /**
  * The source of the engine wasm binary. Under a bundler that understands
  * `new URL(..., import.meta.url)` (e.g. Vite) the default loader needs no
@@ -46,8 +46,75 @@ export interface BojtosSession {
     activateJobs(jobType: string, maxJobs: number, timeoutMs: number, worker: string): ActivatedJob[];
     /** Complete a waiting job, merging `variablesJson` into the instance. */
     completeJob(jobKey: string, variablesJson: string): Snapshot;
+    /**
+     * Complete an ad-hoc sub-process's **agent** job — the container's JOB_WORKER
+     * job (Camunda's agentic `aiagent-job-worker`) — carrying the agent's
+     * {@link AgentResult}. Its `activateElements` run the chosen inner tools this
+     * turn; `completionConditionFulfilled` ends the agent loop; `variables` merge
+     * into the instance (e.g. the agent's final decision). This is the ad-hoc seam
+     * plain {@link completeJob} deliberately omits. Register agents on the dispatch
+     * loop via `DispatchOptions.agents` rather than calling this directly.
+     */
+    completeAgentJob(jobKey: string, result: AgentResult): Snapshot;
     /** Fail a waiting job; with no retries left this raises an incident. */
     failJob(jobKey: string, retries: number, message: string): Snapshot;
+    /**
+     * Throw a BPMN business error from a waiting job: interrupts the activity via a
+     * matching error boundary/event-subprocess catch, or raises an incident if
+     * uncaught. The job is consumed either way.
+     */
+    throwError(jobKey: string, errorCode: string, errorMessage: string): Snapshot;
+    /**
+     * Set a job's remaining retries. Used to recover a job parked on a no-retries
+     * incident before resolving that incident; does not itself unblock the job.
+     */
+    updateRetries(jobKey: string, retries: number): Snapshot;
+    /**
+     * Resolve an open incident by key, retrying the work that failed (returns a
+     * parked job to the activatable pool / re-evaluates a gateway / re-creates a
+     * service-task job).
+     */
+    resolveIncident(incidentKey: string): Snapshot;
+    /**
+     * Merge variables into a scope (a process-instance or element-instance key).
+     * When `local` is true they are written strictly into the target scope,
+     * otherwise they propagate up to the nearest ancestor scope defining each name.
+     */
+    setVariables(scopeKey: string, variablesJson: string, local: boolean): Snapshot;
+    /**
+     * Broadcast a signal by name to every open subscription that matches, across
+     * all instances, merging `variablesJson` into each correlated instance.
+     */
+    broadcastSignal(signalName: string, variablesJson: string): Snapshot;
+    /** Cancel (terminate) a running process instance: every token is discarded. */
+    cancelInstance(instanceKey: string): Snapshot;
+    /**
+     * Modify a running process instance (Zeebe "modify process instance"): move
+     * tokens by terminating existing element instances and/or activating new
+     * ones. Each activate instruction places a token at `elementId` (in the
+     * process root scope), first merging its optional `variables` into the root
+     * scope; `terminateElementInstanceKeys` are the keys of active element
+     * instances (from `instances[].activeElements[].key`) to terminate. If the
+     * terminations drain the last token and nothing is activated, the instance is
+     * terminated.
+     */
+    modify(instanceKey: string, activateInstructions: ActivateInstruction[], terminateElementInstanceKeys: string[]): Snapshot;
+    /** Complete a waiting user task, merging `variablesJson` into the instance. */
+    completeUserTask(userTaskKey: string, variablesJson: string): Snapshot;
+    /**
+     * Assign a user task to `assignee`. With `allowOverride` false the command is
+     * rejected if the task already has an assignee (unassign it first).
+     */
+    assignUserTask(userTaskKey: string, assignee: string, allowOverride: boolean): Snapshot;
+    /** Clear a user task's assignee. */
+    unassignUserTask(userTaskKey: string): Snapshot;
+    /**
+     * Update a user task's attributes from a JSON changeset. Recognised keys (all
+     * optional): `candidateGroups` / `candidateUsers` (string arrays),
+     * `dueDate` / `followUpDate` (ISO-8601 string, or `null`/`""` to clear),
+     * `priority` (0..=100). Only present keys are changed.
+     */
+    updateUserTask(userTaskKey: string, changesetJson: string): Snapshot;
     /**
      * Correlate a message to any instance waiting on it: publishes `messageName`
      * with `correlationKey` (the value the waiting subscription's `correlationKey`

package/dist/session.js

@@ -45,9 +45,46 @@ class WasmBojtosSession {
     completeJob(jobKey, variablesJson) {
         return parseSnapshot(this.engine.completeJob(jobKey, variablesJson || "{}"));
     }
+    completeAgentJob(jobKey, result) {
+        const { variables, ...agentResult } = result ?? {};
+        return parseSnapshot(this.engine.completeAgentJob(jobKey, JSON.stringify(variables ?? {}), JSON.stringify(agentResult ?? {})));
+    }
     failJob(jobKey, retries, message) {
         return parseSnapshot(this.engine.failJob(jobKey, retries, message));
     }
+    throwError(jobKey, errorCode, errorMessage) {
+        return parseSnapshot(this.engine.throwError(jobKey, errorCode, errorMessage));
+    }
+    updateRetries(jobKey, retries) {
+        return parseSnapshot(this.engine.updateRetries(jobKey, retries));
+    }
+    resolveIncident(incidentKey) {
+        return parseSnapshot(this.engine.resolveIncident(incidentKey));
+    }
+    setVariables(scopeKey, variablesJson, local) {
+        return parseSnapshot(this.engine.setVariables(scopeKey, variablesJson || "{}", local));
+    }
+    broadcastSignal(signalName, variablesJson) {
+        return parseSnapshot(this.engine.broadcastSignal(signalName, variablesJson || "{}"));
+    }
+    cancelInstance(instanceKey) {
+        return parseSnapshot(this.engine.cancelInstance(instanceKey));
+    }
+    modify(instanceKey, activateInstructions, terminateElementInstanceKeys) {
+        return parseSnapshot(this.engine.modify(instanceKey, JSON.stringify(activateInstructions ?? []), JSON.stringify(terminateElementInstanceKeys ?? [])));
+    }
+    completeUserTask(userTaskKey, variablesJson) {
+        return parseSnapshot(this.engine.completeUserTask(userTaskKey, variablesJson || "{}"));
+    }
+    assignUserTask(userTaskKey, assignee, allowOverride) {
+        return parseSnapshot(this.engine.assignUserTask(userTaskKey, assignee, allowOverride));
+    }
+    unassignUserTask(userTaskKey) {
+        return parseSnapshot(this.engine.unassignUserTask(userTaskKey));
+    }
+    updateUserTask(userTaskKey, changesetJson) {
+        return parseSnapshot(this.engine.updateUserTask(userTaskKey, changesetJson || "{}"));
+    }
     correlateMessage(messageName, correlationKey, variablesJson) {
         return parseSnapshot(this.engine.correlateMessage(messageName, correlationKey, variablesJson || "{}"));
     }

package/dist/types.d.ts

@@ -51,10 +51,107 @@ export interface TimerDto {
     dueAt: number;
     dueInMs: number;
 }
+/** A user task parked on a `userTask` element, awaiting a human. */
+export interface UserTaskDto {
+    key: string;
+    instanceKey: string;
+    elementInstanceKey: string;
+    elementId: string;
+    /** `Created` (waiting), `Completed`, or `Canceled`. */
+    state: string;
+    assignee?: string;
+    candidateGroups: string[];
+    candidateUsers: string[];
+    dueDate?: string;
+    followUpDate?: string;
+    priority: number;
+}
+/** An open message subscription (a waiting message catch/boundary event). */
+export interface MessageSubscriptionDto {
+    key: string;
+    instanceKey: string;
+    elementId: string;
+    messageName: string;
+    correlationKey: string;
+    /** What the subscription guards (intermediate/boundary, interrupting or not). */
+    kind: string;
+}
+/** An open signal subscription (a waiting signal catch/boundary event). */
+export interface SignalSubscriptionDto {
+    key: string;
+    instanceKey: string;
+    elementId: string;
+    signalName: string;
+    kind: string;
+}
+/**
+ * Per-element token statistics for diagram overlays: `active` live tokens,
+ * cumulative `completed` element instances, and current `incidents`.
+ */
+export interface ElementStatDto {
+    elementId: string;
+    active: number;
+    completed: number;
+    incidents: number;
+}
+/** A traversed connection, as source/target element ids. */
+export interface SequenceFlowDto {
+    from: string;
+    to: string;
+}
+/** An evaluated decision instance (from a `businessRuleTask` / DMN). */
+export interface DecisionInstanceDto {
+    instanceKey: string;
+    elementId: string;
+    decisionKey: string;
+    decisionId: string;
+    output: unknown;
+    evaluatedAt: number;
+}
+/**
+ * One activation instruction for {@link BojtosSession.modify}: place a new token
+ * at `elementId`, first merging `variables` into the instance's root scope.
+ * Mirrors Zeebe's process-instance-modification activate instruction (the token
+ * is activated in the process root scope).
+ */
+export interface ActivateInstruction {
+    elementId: string;
+    variables?: Record<string, unknown>;
+}
+/**
+ * One tool activation an agent asks for inside an ad-hoc sub-process (Camunda
+ * agentic `activateElements[]`): activate the inner element `elementId`, seeding
+ * `variables` into its local scope. Distinct from {@link ActivateInstruction}
+ * (process-instance modification) — this activates a *child* of the ad-hoc
+ * container, not a token in the process root.
+ */
+export interface AgentActivation {
+    elementId: string;
+    variables?: Record<string, unknown>;
+}
+/**
+ * The result an agent returns when completing an ad-hoc sub-process's agent job
+ * (Camunda's agentic `JobResult`): the tools to run this turn
+ * (`activateElements`), whether the container's `<completionCondition>` is now
+ * satisfied (`completionConditionFulfilled`), and whether to cancel any
+ * still-running tools (`cancelRemainingInstances`). `variables` merges into the
+ * instance on completion exactly like a plain job result (e.g. the agent's final
+ * decision). All fields optional: an empty result completes the container this
+ * turn with nothing activated.
+ */
+export interface AgentResult {
+    activateElements?: AgentActivation[];
+    completionConditionFulfilled?: boolean;
+    cancelRemainingInstances?: boolean;
+    variables?: Record<string, unknown>;
+}
 /**
  * The full simulation state returned by every engine command. `activeElementIds`
  * / `incidentElementIds` drive the token/incident highlight (the visual
  * contract, ADR 0043 §4); `instances[].variables` is the live payload.
+ * `userTasks`, `messageSubscriptions`, `signalSubscriptions`, `elementStats`,
+ * `takenSequenceFlows` and `decisionInstances` back a Web-Modeler-Play-style UI
+ * (task panels, correlation/broadcast, overlays, DMN results).
  */
 export interface Snapshot {
     now: number;
@@ -67,6 +164,12 @@ export interface Snapshot {
     jobs: JobDto[];
     incidents: IncidentDto[];
     timers: TimerDto[];
+    userTasks: UserTaskDto[];
+    messageSubscriptions: MessageSubscriptionDto[];
+    signalSubscriptions: SignalSubscriptionDto[];
+    elementStats: ElementStatDto[];
+    takenSequenceFlows: SequenceFlowDto[];
+    decisionInstances: DecisionInstanceDto[];
     activeElementIds: string[];
     incidentElementIds: string[];
 }

package/dist/worker.d.ts

@@ -1,5 +1,5 @@
 import type { BojtosSession } from "./session.js";
-import type { ActivatedJob, Snapshot } from "./types.js";
+import type { ActivatedJob, AgentResult, Snapshot } from "./types.js";
 /**
  * The variables a handler merges into its instance on completion. Return an
  * object to merge it, or `void`/`undefined` to complete with no new variables.
@@ -14,6 +14,17 @@ export type JobResult = Record<string, unknown>;
  * completion. May be async. Throw to fail the job.
  */
 export type JobHandler = (job: ActivatedJob) => JobResult | void | Promise<JobResult | void>;
+/**
+ * A handler for an ad-hoc sub-process's **agent** job (the container's
+ * JOB_WORKER job). Given the activated container job (carrying the instance's
+ * current variables — e.g. accumulated tool outputs), return the
+ * {@link AgentResult} for this turn: which inner tools to activate, whether the
+ * agent is done, and any variables to merge. Called once per agent turn; the
+ * engine re-emits the agent job after the activated tools drain, so a stateful
+ * closure can drive a multi-turn agent (activate tools → read results →
+ * decide → complete). May be async. Throw to fail the container job.
+ */
+export type AgentHandler = (job: ActivatedJob) => AgentResult | Promise<AgentResult>;
 /**
  * Throw from a {@link JobHandler} to fail a job with an explicit remaining
  * `retries` count (default is `job.retries - 1`). With `retries: 0` the engine
@@ -40,6 +51,16 @@ export interface DispatchOptions {
      * exceeding the cap throws instead.
      */
     maxRounds?: number;
+    /**
+     * Handlers for ad-hoc sub-process **agent** job types (Camunda agentic
+     * `aiagent-job-worker`), keyed by the container's `zeebe:taskDefinition type`.
+     * Dispatched like {@link JobHandler}s but completed via
+     * {@link BojtosSession.completeAgentJob}, so their returned
+     * {@link AgentResult} drives the tools to activate this turn. The engine
+     * re-emits the agent job across turns, so the standard drain loop advances the
+     * whole agent conversation to quiescence.
+     */
+    agents?: Record<string, AgentHandler>;
 }
 /** What one {@link dispatchRound} pass did. */
 export interface RoundResult {
@@ -66,6 +87,13 @@ export interface DispatchResult {
  * exactly one step. That makes this the animatable unit: drive it on a timer to
  * watch the token(s) hop task-to-task. {@link dispatchWorkers} loops it to
  * quiescence.
+ *
+ * Ad-hoc **agent** job types registered via `opts.agents` are activated and
+ * completed in the same frontier-snapshot pass, but through
+ * {@link BojtosSession.completeAgentJob} so their {@link AgentResult} activates
+ * the chosen tools. A tool a turn activates joins the *next* frontier, and the
+ * engine re-emits the agent job after those tools drain, so the agent's whole
+ * multi-turn conversation animates one step per round like any other token.
  */
 export declare function dispatchRound(session: BojtosSession, workers: Record<string, JobHandler>, opts?: DispatchOptions): Promise<RoundResult>;
 /**

package/dist/worker.js

@@ -35,6 +35,30 @@ async function runOne(session, handler, job) {
     // we let it bubble to the caller.
     session.completeJob(job.key, payload);
 }
+async function runOneAgent(session, handler, job) {
+    let result;
+    try {
+        // As with a plain job, only the handler is treated as demo logic: a throw
+        // (or a result the engine can't serialize) fails the container job rather
+        // than bubbling up as an engine/ABI error.
+        result = await handler(job);
+        // Mirror runOne: a result the engine can't serialize is the demo's own
+        // logic failing, not an engine/ABI error. session.completeAgentJob
+        // stringifies the result internally (outside this try), so probe-serialize
+        // it here to route a serialization failure through failJob instead of
+        // letting it bubble out of the dispatch loop.
+        JSON.stringify(result);
+    }
+    catch (e) {
+        const retries = e instanceof JobFailure && e.retries !== undefined
+            ? e.retries
+            : Math.max(0, job.retries - 1);
+        const message = e instanceof Error ? e.message : String(e);
+        session.failJob(job.key, retries, message);
+        return;
+    }
+    session.completeAgentJob(job.key, result);
+}
 /**
  * Run one activate-and-handle pass: activate every registered job type's
  * currently-`Created` jobs *first* (a snapshot of the token frontier), then hand
@@ -44,25 +68,54 @@ async function runOne(session, handler, job) {
  * exactly one step. That makes this the animatable unit: drive it on a timer to
  * watch the token(s) hop task-to-task. {@link dispatchWorkers} loops it to
  * quiescence.
+ *
+ * Ad-hoc **agent** job types registered via `opts.agents` are activated and
+ * completed in the same frontier-snapshot pass, but through
+ * {@link BojtosSession.completeAgentJob} so their {@link AgentResult} activates
+ * the chosen tools. A tool a turn activates joins the *next* frontier, and the
+ * engine re-emits the agent job after those tools drain, so the agent's whole
+ * multi-turn conversation animates one step per round like any other token.
  */
 export async function dispatchRound(session, workers, opts = {}) {
     const maxJobs = opts.maxJobsPerActivation ?? 10;
     const timeout = opts.lockTimeoutMs ?? 30_000;
     const worker = opts.worker ?? "bojtos";
+    const agents = opts.agents ?? {};
+    // A job type registered as both a worker and an agent is ambiguous: the
+    // worker pass below would activate and plain-complete it first, so its
+    // agentic `activateElements` could never be sent. Reject up front rather than
+    // silently no-op the tool activation.
+    for (const jobType of Object.keys(agents)) {
+        if (jobType in workers) {
+            throw new Error(`dispatchRound: job type "${jobType}" is registered as both a worker and an agent — register it as exactly one`);
+        }
+    }
     // Activation pass: lock the whole current frontier before running any handler,
     // so a job a handler unblocks isn't also picked up this round (which would
     // cascade the entire chain in a single "step").
-    const batch = [];
+    const jobBatch = [];
     for (const [jobType, handler] of Object.entries(workers)) {
         for (const job of session.activateJobs(jobType, maxJobs, timeout, worker)) {
-            batch.push({ handler, job });
+            jobBatch.push({ handler, job });
+        }
+    }
+    const agentBatch = [];
+    for (const [jobType, handler] of Object.entries(agents)) {
+        for (const job of session.activateJobs(jobType, maxJobs, timeout, worker)) {
+            agentBatch.push({ handler, job });
         }
     }
     // Handle pass.
-    for (const { handler, job } of batch) {
+    for (const { handler, job } of jobBatch) {
         await runOne(session, handler, job);
     }
-    return { snapshot: session.snapshot(), handled: batch.length };
+    for (const { handler, job } of agentBatch) {
+        await runOneAgent(session, handler, job);
+    }
+    return {
+        snapshot: session.snapshot(),
+        handled: jobBatch.length + agentBatch.length,
+    };
 }
 /**
  * Drive an in-browser worker loop over a {@link BojtosSession}: repeatedly

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@nanobpm/bojtos-kit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic core of the Bojtos in-browser BPMN demo framework (ADR 0043): a single scenario runner over the @nanobpm/engine-wasm engine (deploy, start instances, complete/fail jobs, advance the clock, read snapshots and the event log), plus the engine's snapshot/event contract types. Consumed by @nanobpm/bojtos-react and the console test-run panel.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Magikcraft/nano-bpm",
+    "url": "git+https://github.com/Magikcraft/nano-bpm.git",
     "directory": "bojtos-kit"
   },
   "main": "./dist/index.js",
@@ -32,7 +32,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nanobpm/engine-wasm": "^0.1.0"
+    "@nanobpm/engine-wasm": "^0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3"

package/src/index.ts

@@ -14,6 +14,7 @@ export {
   JobFailure,
   type JobHandler,
   type JobResult,
+  type AgentHandler,
   type DispatchOptions,
   type DispatchResult,
   type RoundResult,
@@ -26,5 +27,7 @@ export type {
   IncidentDto,
   TimerDto,
   ActiveEl,
+  AgentActivation,
+  AgentResult,
   WasmEvent,
 } from "./types.js";

package/src/session.ts

@@ -1,5 +1,11 @@
 import init, { type InitInput, TestEngine } from "@nanobpm/engine-wasm";
-import type { ActivatedJob, Snapshot, WasmEvent } from "./types.js";
+import type {
+  ActivatedJob,
+  ActivateInstruction,
+  AgentResult,
+  Snapshot,
+  WasmEvent,
+} from "./types.js";
 
 // Lazily initialise the wasm module exactly once per page, no matter how many
 // sessions are created. Mirrors the console's original `ensureWasm`.
@@ -68,8 +74,87 @@ export interface BojtosSession {
   ): ActivatedJob[];
   /** Complete a waiting job, merging `variablesJson` into the instance. */
   completeJob(jobKey: string, variablesJson: string): Snapshot;
+  /**
+   * Complete an ad-hoc sub-process's **agent** job — the container's JOB_WORKER
+   * job (Camunda's agentic `aiagent-job-worker`) — carrying the agent's
+   * {@link AgentResult}. Its `activateElements` run the chosen inner tools this
+   * turn; `completionConditionFulfilled` ends the agent loop; `variables` merge
+   * into the instance (e.g. the agent's final decision). This is the ad-hoc seam
+   * plain {@link completeJob} deliberately omits. Register agents on the dispatch
+   * loop via `DispatchOptions.agents` rather than calling this directly.
+   */
+  completeAgentJob(jobKey: string, result: AgentResult): Snapshot;
   /** Fail a waiting job; with no retries left this raises an incident. */
   failJob(jobKey: string, retries: number, message: string): Snapshot;
+  /**
+   * Throw a BPMN business error from a waiting job: interrupts the activity via a
+   * matching error boundary/event-subprocess catch, or raises an incident if
+   * uncaught. The job is consumed either way.
+   */
+  throwError(jobKey: string, errorCode: string, errorMessage: string): Snapshot;
+  /**
+   * Set a job's remaining retries. Used to recover a job parked on a no-retries
+   * incident before resolving that incident; does not itself unblock the job.
+   */
+  updateRetries(jobKey: string, retries: number): Snapshot;
+  /**
+   * Resolve an open incident by key, retrying the work that failed (returns a
+   * parked job to the activatable pool / re-evaluates a gateway / re-creates a
+   * service-task job).
+   */
+  resolveIncident(incidentKey: string): Snapshot;
+  /**
+   * Merge variables into a scope (a process-instance or element-instance key).
+   * When `local` is true they are written strictly into the target scope,
+   * otherwise they propagate up to the nearest ancestor scope defining each name.
+   */
+  setVariables(
+    scopeKey: string,
+    variablesJson: string,
+    local: boolean,
+  ): Snapshot;
+  /**
+   * Broadcast a signal by name to every open subscription that matches, across
+   * all instances, merging `variablesJson` into each correlated instance.
+   */
+  broadcastSignal(signalName: string, variablesJson: string): Snapshot;
+  /** Cancel (terminate) a running process instance: every token is discarded. */
+  cancelInstance(instanceKey: string): Snapshot;
+  /**
+   * Modify a running process instance (Zeebe "modify process instance"): move
+   * tokens by terminating existing element instances and/or activating new
+   * ones. Each activate instruction places a token at `elementId` (in the
+   * process root scope), first merging its optional `variables` into the root
+   * scope; `terminateElementInstanceKeys` are the keys of active element
+   * instances (from `instances[].activeElements[].key`) to terminate. If the
+   * terminations drain the last token and nothing is activated, the instance is
+   * terminated.
+   */
+  modify(
+    instanceKey: string,
+    activateInstructions: ActivateInstruction[],
+    terminateElementInstanceKeys: string[],
+  ): Snapshot;
+  /** Complete a waiting user task, merging `variablesJson` into the instance. */
+  completeUserTask(userTaskKey: string, variablesJson: string): Snapshot;
+  /**
+   * Assign a user task to `assignee`. With `allowOverride` false the command is
+   * rejected if the task already has an assignee (unassign it first).
+   */
+  assignUserTask(
+    userTaskKey: string,
+    assignee: string,
+    allowOverride: boolean,
+  ): Snapshot;
+  /** Clear a user task's assignee. */
+  unassignUserTask(userTaskKey: string): Snapshot;
+  /**
+   * Update a user task's attributes from a JSON changeset. Recognised keys (all
+   * optional): `candidateGroups` / `candidateUsers` (string arrays),
+   * `dueDate` / `followUpDate` (ISO-8601 string, or `null`/`""` to clear),
+   * `priority` (0..=100). Only present keys are changed.
+   */
+  updateUserTask(userTaskKey: string, changesetJson: string): Snapshot;
   /**
    * Correlate a message to any instance waiting on it: publishes `messageName`
    * with `correlationKey` (the value the waiting subscription's `correlationKey`
@@ -137,10 +222,99 @@ class WasmBojtosSession implements BojtosSession {
     return parseSnapshot(this.engine.completeJob(jobKey, variablesJson || "{}"));
   }
 
+  completeAgentJob(jobKey: string, result: AgentResult): Snapshot {
+    const { variables, ...agentResult } = result ?? {};
+    return parseSnapshot(
+      this.engine.completeAgentJob(
+        jobKey,
+        JSON.stringify(variables ?? {}),
+        JSON.stringify(agentResult ?? {}),
+      ),
+    );
+  }
+
   failJob(jobKey: string, retries: number, message: string): Snapshot {
     return parseSnapshot(this.engine.failJob(jobKey, retries, message));
   }
 
+  throwError(
+    jobKey: string,
+    errorCode: string,
+    errorMessage: string,
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.throwError(jobKey, errorCode, errorMessage),
+    );
+  }
+
+  updateRetries(jobKey: string, retries: number): Snapshot {
+    return parseSnapshot(this.engine.updateRetries(jobKey, retries));
+  }
+
+  resolveIncident(incidentKey: string): Snapshot {
+    return parseSnapshot(this.engine.resolveIncident(incidentKey));
+  }
+
+  setVariables(
+    scopeKey: string,
+    variablesJson: string,
+    local: boolean,
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.setVariables(scopeKey, variablesJson || "{}", local),
+    );
+  }
+
+  broadcastSignal(signalName: string, variablesJson: string): Snapshot {
+    return parseSnapshot(
+      this.engine.broadcastSignal(signalName, variablesJson || "{}"),
+    );
+  }
+
+  cancelInstance(instanceKey: string): Snapshot {
+    return parseSnapshot(this.engine.cancelInstance(instanceKey));
+  }
+
+  modify(
+    instanceKey: string,
+    activateInstructions: ActivateInstruction[],
+    terminateElementInstanceKeys: string[],
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.modify(
+        instanceKey,
+        JSON.stringify(activateInstructions ?? []),
+        JSON.stringify(terminateElementInstanceKeys ?? []),
+      ),
+    );
+  }
+
+  completeUserTask(userTaskKey: string, variablesJson: string): Snapshot {
+    return parseSnapshot(
+      this.engine.completeUserTask(userTaskKey, variablesJson || "{}"),
+    );
+  }
+
+  assignUserTask(
+    userTaskKey: string,
+    assignee: string,
+    allowOverride: boolean,
+  ): Snapshot {
+    return parseSnapshot(
+      this.engine.assignUserTask(userTaskKey, assignee, allowOverride),
+    );
+  }
+
+  unassignUserTask(userTaskKey: string): Snapshot {
+    return parseSnapshot(this.engine.unassignUserTask(userTaskKey));
+  }
+
+  updateUserTask(userTaskKey: string, changesetJson: string): Snapshot {
+    return parseSnapshot(
+      this.engine.updateUserTask(userTaskKey, changesetJson || "{}"),
+    );
+  }
+
   correlateMessage(
     messageName: string,
     correlationKey: string,

package/src/types.ts

@@ -63,10 +63,116 @@ export interface TimerDto {
   dueInMs: number;
 }
 
+/** A user task parked on a `userTask` element, awaiting a human. */
+export interface UserTaskDto {
+  key: string;
+  instanceKey: string;
+  elementInstanceKey: string;
+  elementId: string;
+  /** `Created` (waiting), `Completed`, or `Canceled`. */
+  state: string;
+  assignee?: string;
+  candidateGroups: string[];
+  candidateUsers: string[];
+  dueDate?: string;
+  followUpDate?: string;
+  priority: number;
+}
+
+/** An open message subscription (a waiting message catch/boundary event). */
+export interface MessageSubscriptionDto {
+  key: string;
+  instanceKey: string;
+  elementId: string;
+  messageName: string;
+  correlationKey: string;
+  /** What the subscription guards (intermediate/boundary, interrupting or not). */
+  kind: string;
+}
+
+/** An open signal subscription (a waiting signal catch/boundary event). */
+export interface SignalSubscriptionDto {
+  key: string;
+  instanceKey: string;
+  elementId: string;
+  signalName: string;
+  kind: string;
+}
+
+/**
+ * Per-element token statistics for diagram overlays: `active` live tokens,
+ * cumulative `completed` element instances, and current `incidents`.
+ */
+export interface ElementStatDto {
+  elementId: string;
+  active: number;
+  completed: number;
+  incidents: number;
+}
+
+/** A traversed connection, as source/target element ids. */
+export interface SequenceFlowDto {
+  from: string;
+  to: string;
+}
+
+/** An evaluated decision instance (from a `businessRuleTask` / DMN). */
+export interface DecisionInstanceDto {
+  instanceKey: string;
+  elementId: string;
+  decisionKey: string;
+  decisionId: string;
+  output: unknown;
+  evaluatedAt: number;
+}
+
+/**
+ * One activation instruction for {@link BojtosSession.modify}: place a new token
+ * at `elementId`, first merging `variables` into the instance's root scope.
+ * Mirrors Zeebe's process-instance-modification activate instruction (the token
+ * is activated in the process root scope).
+ */
+export interface ActivateInstruction {
+  elementId: string;
+  variables?: Record<string, unknown>;
+}
+
+/**
+ * One tool activation an agent asks for inside an ad-hoc sub-process (Camunda
+ * agentic `activateElements[]`): activate the inner element `elementId`, seeding
+ * `variables` into its local scope. Distinct from {@link ActivateInstruction}
+ * (process-instance modification) — this activates a *child* of the ad-hoc
+ * container, not a token in the process root.
+ */
+export interface AgentActivation {
+  elementId: string;
+  variables?: Record<string, unknown>;
+}
+
+/**
+ * The result an agent returns when completing an ad-hoc sub-process's agent job
+ * (Camunda's agentic `JobResult`): the tools to run this turn
+ * (`activateElements`), whether the container's `<completionCondition>` is now
+ * satisfied (`completionConditionFulfilled`), and whether to cancel any
+ * still-running tools (`cancelRemainingInstances`). `variables` merges into the
+ * instance on completion exactly like a plain job result (e.g. the agent's final
+ * decision). All fields optional: an empty result completes the container this
+ * turn with nothing activated.
+ */
+export interface AgentResult {
+  activateElements?: AgentActivation[];
+  completionConditionFulfilled?: boolean;
+  cancelRemainingInstances?: boolean;
+  variables?: Record<string, unknown>;
+}
+
 /**
  * The full simulation state returned by every engine command. `activeElementIds`
  * / `incidentElementIds` drive the token/incident highlight (the visual
  * contract, ADR 0043 §4); `instances[].variables` is the live payload.
+ * `userTasks`, `messageSubscriptions`, `signalSubscriptions`, `elementStats`,
+ * `takenSequenceFlows` and `decisionInstances` back a Web-Modeler-Play-style UI
+ * (task panels, correlation/broadcast, overlays, DMN results).
  */
 export interface Snapshot {
   now: number;
@@ -79,6 +185,12 @@ export interface Snapshot {
   jobs: JobDto[];
   incidents: IncidentDto[];
   timers: TimerDto[];
+  userTasks: UserTaskDto[];
+  messageSubscriptions: MessageSubscriptionDto[];
+  signalSubscriptions: SignalSubscriptionDto[];
+  elementStats: ElementStatDto[];
+  takenSequenceFlows: SequenceFlowDto[];
+  decisionInstances: DecisionInstanceDto[];
   activeElementIds: string[];
   incidentElementIds: string[];
 }

package/src/worker.ts

@@ -1,5 +1,5 @@
 import type { BojtosSession } from "./session.js";
-import type { ActivatedJob, Snapshot } from "./types.js";
+import type { ActivatedJob, AgentResult, Snapshot } from "./types.js";
 
 /**
  * The variables a handler merges into its instance on completion. Return an
@@ -19,6 +19,20 @@ export type JobHandler = (
   job: ActivatedJob,
 ) => JobResult | void | Promise<JobResult | void>;
 
+/**
+ * A handler for an ad-hoc sub-process's **agent** job (the container's
+ * JOB_WORKER job). Given the activated container job (carrying the instance's
+ * current variables — e.g. accumulated tool outputs), return the
+ * {@link AgentResult} for this turn: which inner tools to activate, whether the
+ * agent is done, and any variables to merge. Called once per agent turn; the
+ * engine re-emits the agent job after the activated tools drain, so a stateful
+ * closure can drive a multi-turn agent (activate tools → read results →
+ * decide → complete). May be async. Throw to fail the container job.
+ */
+export type AgentHandler = (
+  job: ActivatedJob,
+) => AgentResult | Promise<AgentResult>;
+
 /**
  * Throw from a {@link JobHandler} to fail a job with an explicit remaining
  * `retries` count (default is `job.retries - 1`). With `retries: 0` the engine
@@ -48,6 +62,16 @@ export interface DispatchOptions {
    * exceeding the cap throws instead.
    */
   maxRounds?: number;
+  /**
+   * Handlers for ad-hoc sub-process **agent** job types (Camunda agentic
+   * `aiagent-job-worker`), keyed by the container's `zeebe:taskDefinition type`.
+   * Dispatched like {@link JobHandler}s but completed via
+   * {@link BojtosSession.completeAgentJob}, so their returned
+   * {@link AgentResult} drives the tools to activate this turn. The engine
+   * re-emits the agent job across turns, so the standard drain loop advances the
+   * whole agent conversation to quiescence.
+   */
+  agents?: Record<string, AgentHandler>;
 }
 
 /** What one {@link dispatchRound} pass did. */
@@ -96,6 +120,35 @@ async function runOne(
   session.completeJob(job.key, payload);
 }
 
+async function runOneAgent(
+  session: BojtosSession,
+  handler: AgentHandler,
+  job: ActivatedJob,
+): Promise<void> {
+  let result: AgentResult;
+  try {
+    // As with a plain job, only the handler is treated as demo logic: a throw
+    // (or a result the engine can't serialize) fails the container job rather
+    // than bubbling up as an engine/ABI error.
+    result = await handler(job);
+    // Mirror runOne: a result the engine can't serialize is the demo's own
+    // logic failing, not an engine/ABI error. session.completeAgentJob
+    // stringifies the result internally (outside this try), so probe-serialize
+    // it here to route a serialization failure through failJob instead of
+    // letting it bubble out of the dispatch loop.
+    JSON.stringify(result);
+  } catch (e) {
+    const retries =
+      e instanceof JobFailure && e.retries !== undefined
+        ? e.retries
+        : Math.max(0, job.retries - 1);
+    const message = e instanceof Error ? e.message : String(e);
+    session.failJob(job.key, retries, message);
+    return;
+  }
+  session.completeAgentJob(job.key, result);
+}
+
 /**
  * Run one activate-and-handle pass: activate every registered job type's
  * currently-`Created` jobs *first* (a snapshot of the token frontier), then hand
@@ -105,6 +158,13 @@ async function runOne(
  * exactly one step. That makes this the animatable unit: drive it on a timer to
  * watch the token(s) hop task-to-task. {@link dispatchWorkers} loops it to
  * quiescence.
+ *
+ * Ad-hoc **agent** job types registered via `opts.agents` are activated and
+ * completed in the same frontier-snapshot pass, but through
+ * {@link BojtosSession.completeAgentJob} so their {@link AgentResult} activates
+ * the chosen tools. A tool a turn activates joins the *next* frontier, and the
+ * engine re-emits the agent job after those tools drain, so the agent's whole
+ * multi-turn conversation animates one step per round like any other token.
  */
 export async function dispatchRound(
   session: BojtosSession,
@@ -114,20 +174,44 @@ export async function dispatchRound(
   const maxJobs = opts.maxJobsPerActivation ?? 10;
   const timeout = opts.lockTimeoutMs ?? 30_000;
   const worker = opts.worker ?? "bojtos";
+  const agents = opts.agents ?? {};
+  // A job type registered as both a worker and an agent is ambiguous: the
+  // worker pass below would activate and plain-complete it first, so its
+  // agentic `activateElements` could never be sent. Reject up front rather than
+  // silently no-op the tool activation.
+  for (const jobType of Object.keys(agents)) {
+    if (jobType in workers) {
+      throw new Error(
+        `dispatchRound: job type "${jobType}" is registered as both a worker and an agent — register it as exactly one`,
+      );
+    }
+  }
   // Activation pass: lock the whole current frontier before running any handler,
   // so a job a handler unblocks isn't also picked up this round (which would
   // cascade the entire chain in a single "step").
-  const batch: { handler: JobHandler; job: ActivatedJob }[] = [];
+  const jobBatch: { handler: JobHandler; job: ActivatedJob }[] = [];
   for (const [jobType, handler] of Object.entries(workers)) {
     for (const job of session.activateJobs(jobType, maxJobs, timeout, worker)) {
-      batch.push({ handler, job });
+      jobBatch.push({ handler, job });
+    }
+  }
+  const agentBatch: { handler: AgentHandler; job: ActivatedJob }[] = [];
+  for (const [jobType, handler] of Object.entries(agents)) {
+    for (const job of session.activateJobs(jobType, maxJobs, timeout, worker)) {
+      agentBatch.push({ handler, job });
     }
   }
   // Handle pass.
-  for (const { handler, job } of batch) {
+  for (const { handler, job } of jobBatch) {
     await runOne(session, handler, job);
   }
-  return { snapshot: session.snapshot(), handled: batch.length };
+  for (const { handler, job } of agentBatch) {
+    await runOneAgent(session, handler, job);
+  }
+  return {
+    snapshot: session.snapshot(),
+    handled: jobBatch.length + agentBatch.length,
+  };
 }
 
 /**