@nanobpm/bojtos-kit 0.2.0 → 0.4.0

package/README.md

@@ -1,9 +1,9 @@
 # @nanobpm/bojtos-kit
 
 Framework-agnostic core of the **Bojtos** in-browser BPMN demo framework
-([ADR 0043](../docs/adr/0043-bojtos-demo-framework.md)).
+([ADR 0043](../README.md#design)).
 
-It wraps [`@nanobpm/engine-wasm`](../engine-wasm) as a single scenario runner —
+It wraps [`@nanobpm/engine-wasm`](https://www.npmjs.com/package/@nanobpm/engine-wasm) as a single scenario runner —
 the one runner the whole framework (and the console test-run panel) drives, so
 there is no second, drift-prone engine harness — and re-exports the engine's
 snapshot/event contract types.

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, ActivateInstruction, 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,6 +46,16 @@ 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;
     /**

package/dist/session.js

@@ -45,6 +45,10 @@ 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));
     }

package/dist/types.d.ts

@@ -118,6 +118,33 @@ 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

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.2.0",
+  "version": "0.4.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/nanobpm/bojtos.git",
     "directory": "bojtos-kit"
   },
   "main": "./dist/index.js",
@@ -32,7 +32,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nanobpm/engine-wasm": "^0.2.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, ActivateInstruction, 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,6 +74,16 @@ 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;
   /**
@@ -206,6 +222,17 @@ 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));
   }

package/src/types.ts

@@ -137,6 +137,35 @@ export interface ActivateInstruction {
   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

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,
+  };
 }
 
 /**