@nanobpm/bojtos-react 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -2,5 +2,5 @@ export { useBojtos, type UseBojtosOptions, type BojtosControls, type BojtosPhase
 export { Bojtos, type BojtosProps, type TraceEvent } from "./Bojtos.js";
 export { OrderFulfillmentDemo, ORDER_FULFILLMENT_BPMN, orderFulfillmentWorkers, } from "./examples/orderFulfillment.js";
 export { BpmnRuntimeView, type BpmnRuntimeViewProps, } from "./BpmnRuntimeView.js";
-export { JobFailure, type JobHandler, type JobResult, type DispatchOptions, type DispatchResult, type RoundResult, } from "@nanobpm/bojtos-kit";
-export type { BojtosSession, Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, ActiveEl, WasmEvent, } from "@nanobpm/bojtos-kit";
+export { JobFailure, type JobHandler, type JobResult, type AgentHandler, type DispatchOptions, type DispatchResult, type RoundResult, } from "@nanobpm/bojtos-kit";
+export type { BojtosSession, Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, ActiveEl, AgentActivation, AgentResult, WasmEvent, } from "@nanobpm/bojtos-kit";

package/dist/useBojtos.d.ts

@@ -1,4 +1,4 @@
-import { type DispatchOptions, type JobHandler, type RoundResult, type Snapshot, type WasmEvent, type WasmSource } from "@nanobpm/bojtos-kit";
+import { type AgentResult, type DispatchOptions, type JobHandler, type RoundResult, type Snapshot, type WasmEvent, type WasmSource } from "@nanobpm/bojtos-kit";
 /** Lifecycle of the in-browser engine load. */
 export type BojtosPhase = "loading" | "ready" | "error";
 export interface UseBojtosOptions {
@@ -28,6 +28,13 @@ export interface BojtosControls {
     createInstance(processId: string, variablesJson: string): Snapshot | null;
     /** Complete a waiting job, merging output variables. */
     completeJob(jobKey: string, variablesJson: string): Snapshot | null;
+    /**
+     * Complete an ad-hoc sub-process's **agent** job with an {@link AgentResult}
+     * (activate tools this turn / signal completion / merge variables). For the
+     * usual dispatch-loop case, register agents via `runWorkers`/`stepWorkers`
+     * `opts.agents` instead of calling this directly.
+     */
+    completeAgentJob(jobKey: string, result: AgentResult): Snapshot | null;
     /** Fail a waiting job (raises an incident with no retries left). */
     failJob(jobKey: string, retries: number, message: string): Snapshot | null;
     /**
@@ -42,7 +49,9 @@ export interface BojtosControls {
     /**
      * Run the registered worker handlers until the process settles (activate →
      * handler → complete/fail), then reflect the resulting snapshot/events.
-     * Resolves to the settled snapshot, or null if there is no live session.
+     * Register ad-hoc **agent** handlers via `opts.agents` to drive
+     * `adHocSubProcess` tool activation in the same loop. Resolves to the settled
+     * snapshot, or null if there is no live session.
      */
     runWorkers(workers: Record<string, JobHandler>, opts?: DispatchOptions): Promise<Snapshot | null>;
     /**

package/dist/useBojtos.js

@@ -92,6 +92,7 @@ export function useBojtos({ bpmn, wasm }) {
     }, []);
     const createInstance = useCallback((processId, variablesJson) => run((s) => s.createInstance(processId, variablesJson)), [run]);
     const completeJob = useCallback((jobKey, variablesJson) => run((s) => s.completeJob(jobKey, variablesJson)), [run]);
+    const completeAgentJob = useCallback((jobKey, result) => run((s) => s.completeAgentJob(jobKey, result)), [run]);
     const failJob = useCallback((jobKey, retries, message) => run((s) => s.failJob(jobKey, retries, message)), [run]);
     const advanceTime = useCallback((byMs) => run((s) => s.advanceTime(byMs)), [run]);
     const correlateMessage = useCallback((messageName, correlationKey, variablesJson) => run((s) => s.correlateMessage(messageName, correlationKey, variablesJson)), [run]);
@@ -167,6 +168,7 @@ export function useBojtos({ bpmn, wasm }) {
         events,
         createInstance,
         completeJob,
+        completeAgentJob,
         failJob,
         advanceTime,
         correlateMessage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/bojtos-react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React binding for the Bojtos in-browser BPMN demo framework (ADR 0043): the useBojtos hook (owns the engine session + reactive snapshot/event state) and the <BpmnRuntimeView> live token/incident diagram. Built on @nanobpm/bojtos-kit; the console test-run panel is its first consumer.",
   "type": "module",
   "license": "Apache-2.0",
@@ -30,7 +30,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nanobpm/bojtos-kit": "^0.2.0"
+    "@nanobpm/bojtos-kit": "^0.3.0"
   },
   "peerDependencies": {
     "bpmn-js": ">=17",

package/src/index.ts

@@ -24,6 +24,7 @@ export {
   JobFailure,
   type JobHandler,
   type JobResult,
+  type AgentHandler,
   type DispatchOptions,
   type DispatchResult,
   type RoundResult,
@@ -37,5 +38,7 @@ export type {
   IncidentDto,
   TimerDto,
   ActiveEl,
+  AgentActivation,
+  AgentResult,
   WasmEvent,
 } from "@nanobpm/bojtos-kit";

package/src/useBojtos.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
+  type AgentResult,
   type BojtosSession,
   createBojtosSession,
   type DispatchOptions,
@@ -43,6 +44,13 @@ export interface BojtosControls {
   createInstance(processId: string, variablesJson: string): Snapshot | null;
   /** Complete a waiting job, merging output variables. */
   completeJob(jobKey: string, variablesJson: string): Snapshot | null;
+  /**
+   * Complete an ad-hoc sub-process's **agent** job with an {@link AgentResult}
+   * (activate tools this turn / signal completion / merge variables). For the
+   * usual dispatch-loop case, register agents via `runWorkers`/`stepWorkers`
+   * `opts.agents` instead of calling this directly.
+   */
+  completeAgentJob(jobKey: string, result: AgentResult): Snapshot | null;
   /** Fail a waiting job (raises an incident with no retries left). */
   failJob(jobKey: string, retries: number, message: string): Snapshot | null;
   /**
@@ -61,7 +69,9 @@ export interface BojtosControls {
   /**
    * Run the registered worker handlers until the process settles (activate →
    * handler → complete/fail), then reflect the resulting snapshot/events.
-   * Resolves to the settled snapshot, or null if there is no live session.
+   * Register ad-hoc **agent** handlers via `opts.agents` to drive
+   * `adHocSubProcess` tool activation in the same loop. Resolves to the settled
+   * snapshot, or null if there is no live session.
    */
   runWorkers(
     workers: Record<string, JobHandler>,
@@ -189,6 +199,11 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
       run((s) => s.completeJob(jobKey, variablesJson)),
     [run],
   );
+  const completeAgentJob = useCallback(
+    (jobKey: string, result: AgentResult) =>
+      run((s) => s.completeAgentJob(jobKey, result)),
+    [run],
+  );
   const failJob = useCallback(
     (jobKey: string, retries: number, message: string) =>
       run((s) => s.failJob(jobKey, retries, message)),
@@ -285,6 +300,7 @@ export function useBojtos({ bpmn, wasm }: UseBojtosOptions): BojtosControls {
     events,
     createInstance,
     completeJob,
+    completeAgentJob,
     failJob,
     advanceTime,
     correlateMessage,