@nanobpm/bojtos-kit 0.4.0 → 0.6.0

package/README.md

@@ -27,7 +27,30 @@ Every command returns the post-run `Snapshot`: `activeElementIds` /
 For React, use [`@nanobpm/bojtos-react`](../bojtos-react), which owns the session
 lifecycle and reactive state on top of this kit.
 
+## Trace model
+
+The kit also holds the framework-agnostic **trace model** the shared
+`<TraceTimeline>` (in `@nanobpm/bojtos-react`) renders — one normalized
+row/turn-group model plus the two adapters that map a source into it, so the two
+formerly forked timelines share one fold instead of drifting apart:
+
+- **`foldEngineEvents(events)`** — the engine-event fold: a `WasmEvent[]` (from
+  `session.events()` / `useBojtos().events`) → normalized `TraceRow[]`, keeping the
+  run's milestones and dropping low-signal lifecycle noise. The non-agentic /
+  test-view case.
+- **`traceEntriesToRows(entries)`** — the handler-emitted adapter: agent/tool/turn
+  `TraceEntry` lines (with the additive `turn` grouping field) → `TraceRow[]`. The
+  agentic web-demo case.
+- **`buildTraceItems(rows)`** — folds consecutive same-`turn` rows into
+  `TraceTurnGroup`s; rows with no `turn` stay flat. `isTraceTurnGroup` narrows an
+  item. This is the grouping the view consumes.
+
+It is pure and React-free (no React import in the kit), keeping the presentational
+layer thin.
+
 ## Build
 
-`dist/` (the tsc-emitted JS + `.d.ts`) is committed so `file:` consumers and CI
-need no build-on-install step. Regenerate with `npm run build`.
+`dist/` (the tsc-emitted JS + `.d.ts`) is what ships, built by `prepack` on
+publish and by `npm test` locally. It is **not** committed — `.gitignore` covers
+it — so build before pointing a `file:` consumer at this workspace. Regenerate
+with `npm run build`.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { ensureWasm, createBojtosSession, type BojtosSession, type WasmSource, } from "./session.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";
+export { dispatchWorkers, dispatchRound, settleReason, unhandledJobTypes, JobFailure, type JobHandler, type JobResult, type AgentHandler, type DispatchOptions, type DispatchResult, type RoundResult, type SettleReason, } from "./worker.js";
+export { buildTraceItems, isTraceTurnGroup, foldEngineEvents, traceEntriesToRows, } from "./trace.js";
+export type { TraceRowKind, TraceEntry, TraceRow, TraceTurnGroup, TraceItem, TraceAdapter, } from "./trace.js";
+export type { Snapshot, InstanceDto, JobDto, ActivatedJob, IncidentDto, TimerDto, UserTaskDto, MessageSubscriptionDto, SignalSubscriptionDto, ElementStatDto, SequenceFlowDto, DecisionInstanceDto, ActiveEl, ActivateInstruction, AgentActivation, AgentResult, WasmEvent, } from "./types.js";

package/dist/index.js

@@ -2,4 +2,8 @@
 // framework (ADR 0043). Wraps the in-browser wasm engine as a single scenario
 // runner and re-exports the engine's snapshot/event contract types.
 export { ensureWasm, createBojtosSession, } from "./session.js";
-export { dispatchWorkers, dispatchRound, JobFailure, } from "./worker.js";
+export { dispatchWorkers, dispatchRound, settleReason, unhandledJobTypes, JobFailure, } from "./worker.js";
+// The shared trace model + both adapters (engine-event fold and handler-emitted
+// `TraceEntry`) that retired the two forked `TraceTimeline` copies (#9). Pure and
+// React-free — the presentational component lives in @nanobpm/bojtos-react.
+export { buildTraceItems, isTraceTurnGroup, foldEngineEvents, traceEntriesToRows, } from "./trace.js";

package/dist/trace.d.ts

@@ -0,0 +1,97 @@
+import type { WasmEvent } from "./types.js";
+/**
+ * Semantic classification of a trace row, driving how the view styles it (the
+ * `log-<kind>` class the two forked timelines already keyed off) and which
+ * affordance it carries. Framework-agnostic — an engine-event fold and an
+ * agentic handler stream both land in this shared vocabulary:
+ *
+ * - `start` — the run/instance began.
+ * - `agent` — an agent decision, or a tool the agent activated this turn.
+ * - `llm`   — a raw model reply.
+ * - `tool`  — a tool/handler log line (a job running, a timer, a message).
+ * - `human` — a user task awaiting or completed by a person.
+ * - `done`  — the final outcome (the instance completed/terminated).
+ * - `error` — a failure, incident, or thrown error.
+ * - `vars`  — a variables/result update (e.g. what a tool returned).
+ */
+export type TraceRowKind = "start" | "agent" | "llm" | "tool" | "human" | "done" | "error" | "vars";
+/**
+ * A source line before it is placed in the normalized model. This is the shape a
+ * handler emits (the web-demo framework's `TraceEntry`): `kind`/`text` are all a
+ * plain consumer needs; every other field is additive and safe to ignore.
+ */
+export interface TraceEntry {
+    kind: TraceRowKind;
+    /** The human-readable line. */
+    text: string;
+    /**
+     * Stable id for an entry that updates in place — a streaming completion grows
+     * one line rather than spamming forty.
+     */
+    key?: string;
+    /** True while the entry is still being produced (renders a spinner). */
+    pending?: boolean;
+    /**
+     * Groups every entry produced by one agent turn together (the streamed LLM
+     * reply, each tool it activated, and that tool's result). Consecutive entries
+     * sharing a `turn` fold into one turn card; entries with no `turn` render as
+     * plain rows in their original order.
+     */
+    turn?: number;
+    /** The BPMN element (tool or task) this entry concerns. */
+    elementId?: string;
+    /** Arguments supplied when activating a tool — the coerced values, not the raw reply. */
+    args?: Record<string, unknown>;
+    /** What a tool/handler returned, paired with its activation by `elementId`. */
+    result?: unknown;
+}
+/**
+ * A normalized row: a {@link TraceEntry} stamped with a stable, monotonic `id`.
+ * The `id` is what the view keys off and what pairs a tool's result with its
+ * activation and orders loose lines within a turn.
+ */
+export interface TraceRow extends TraceEntry {
+    id: number;
+}
+/** Consecutive same-turn rows, folded into one group by {@link buildTraceItems}. */
+export interface TraceTurnGroup {
+    turn: number;
+    rows: TraceRow[];
+}
+/** A top-level item the view renders: either a plain row or a turn group. */
+export type TraceItem = TraceRow | TraceTurnGroup;
+/** Narrow a {@link TraceItem} to a {@link TraceTurnGroup}. */
+export declare function isTraceTurnGroup(item: TraceItem): item is TraceTurnGroup;
+/**
+ * An adapter maps a source (`WasmEvent[]`, a `TraceEntry[]`, …) into the shared
+ * normalized row model. Both built-in adapters — {@link foldEngineEvents} and
+ * {@link traceEntriesToRows} — satisfy this; a consumer can supply its own for a
+ * bespoke source.
+ */
+export type TraceAdapter<TSource> = (source: TSource) => TraceRow[];
+/**
+ * Fold a flat list of normalized rows into the view model: consecutive rows
+ * sharing a `turn` become one {@link TraceTurnGroup}; everything else stays a
+ * plain row in its original order. A row with no `turn` breaks the current group,
+ * so an interleaved non-turn line never gets swallowed into a card. This is the
+ * grouping both forked timelines did by hand, lifted into the shared kit.
+ */
+export declare function buildTraceItems(rows: TraceRow[]): TraceItem[];
+/**
+ * The handler-emitted `TraceEntry` adapter: stamp each entry with a stable `id`
+ * (its index) to lift it into a {@link TraceRow}. The entries already carry the
+ * additive `turn`/`elementId`/`args`/`result` fields, so {@link buildTraceItems}
+ * over the result reproduces the agentic turn-grouped card view without any
+ * re-forked grouping logic. The input is never mutated.
+ */
+export declare function traceEntriesToRows(entries: readonly TraceEntry[]): TraceRow[];
+/**
+ * The engine-event fold adapter: map a `WasmEvent[]` (the flattened
+ * `{ seq, now, type, …snake_case }` stream from `useBojtos().events`) into
+ * normalized rows, keeping only the meaningful milestones (see
+ * {@link ENGINE_EVENT_RULES}). Each row's `id` is the event's `seq`, so ids stay
+ * stable and monotonic across re-reads of a growing log. Engine events carry no
+ * turn, so {@link buildTraceItems} over the result is a flat list of rows — the
+ * non-agentic test-view shape.
+ */
+export declare function foldEngineEvents(events: readonly WasmEvent[]): TraceRow[];

package/dist/trace.js

@@ -0,0 +1,185 @@
+// The framework-agnostic trace model shared by the Bojtos demo framework and the
+// console test-view — the single source that retired the two drifted, forked
+// `TraceTimeline` copies (nanobpm/bojtos#9). It defines one normalized row/turn
+// model plus the two adapters that map a source into it:
+//
+//   1. the **engine-event fold** — `WasmEvent[]` (from `useBojtos().events`) →
+//      rows, covering the non-agentic / test-view case; and
+//   2. the **handler-emitted `TraceEntry`** adapter — the agent/tool/turn entries
+//      (with the additive `turn` grouping field) → rows, covering the agentic
+//      web-demo case.
+//
+// It is deliberately React-free: the presentational component (`TraceTimeline` in
+// `@nanobpm/bojtos-react`) renders this model, keeping the view layer thin.
+/** Narrow a {@link TraceItem} to a {@link TraceTurnGroup}. */
+export function isTraceTurnGroup(item) {
+    return item.rows !== undefined;
+}
+/**
+ * Fold a flat list of normalized rows into the view model: consecutive rows
+ * sharing a `turn` become one {@link TraceTurnGroup}; everything else stays a
+ * plain row in its original order. A row with no `turn` breaks the current group,
+ * so an interleaved non-turn line never gets swallowed into a card. This is the
+ * grouping both forked timelines did by hand, lifted into the shared kit.
+ */
+export function buildTraceItems(rows) {
+    const items = [];
+    let current = null;
+    for (const row of rows) {
+        if (row.turn !== undefined) {
+            if (current && current.turn === row.turn) {
+                current.rows.push(row);
+            }
+            else {
+                current = { turn: row.turn, rows: [row] };
+                items.push(current);
+            }
+        }
+        else {
+            current = null;
+            items.push(row);
+        }
+    }
+    return items;
+}
+/**
+ * The handler-emitted `TraceEntry` adapter: stamp each entry with a stable `id`
+ * (its index) to lift it into a {@link TraceRow}. The entries already carry the
+ * additive `turn`/`elementId`/`args`/`result` fields, so {@link buildTraceItems}
+ * over the result reproduces the agentic turn-grouped card view without any
+ * re-forked grouping logic. The input is never mutated.
+ */
+export function traceEntriesToRows(entries) {
+    return entries.map((entry, id) => ({ ...entry, id }));
+}
+/** Read a string field off a `WasmEvent`'s open payload, or `undefined`. */
+function str(ev, key) {
+    const v = ev[key];
+    return typeof v === "string" ? v : undefined;
+}
+/** The element this event concerns, if it names one — for pairing/labelling. */
+function elementOf(ev) {
+    return str(ev, "element_id");
+}
+const ENGINE_EVENT_RULES = {
+    ProcessInstanceCreated: {
+        kind: "start",
+        text: (ev) => `Process ${str(ev, "process_id") ?? "instance"} started`,
+    },
+    JobCreated: {
+        kind: "tool",
+        text: (ev) => `Job ${str(ev, "job_type") ?? ""} created`.trim() +
+            (elementOf(ev) ? ` on ${elementOf(ev)}` : ""),
+    },
+    JobCompleted: {
+        kind: "vars",
+        text: (ev) => `Job ${str(ev, "job_type") ?? ""} completed`.trim(),
+    },
+    JobFailed: {
+        kind: "error",
+        text: (ev) => `Job ${str(ev, "job_type") ?? ""} failed`.trim(),
+    },
+    JobErrorThrown: {
+        kind: "error",
+        text: (ev) => `Job threw error ${str(ev, "error_code") ?? ""}`.trim() +
+            (elementOf(ev) ? ` on ${elementOf(ev)}` : ""),
+    },
+    IncidentRaised: {
+        kind: "error",
+        text: (ev) => `Incident on ${elementOf(ev) ?? "instance"}` +
+            (str(ev, "reason") ? `: ${str(ev, "reason")}` : ""),
+    },
+    IncidentResolved: {
+        kind: "tool",
+        text: (ev) => `Incident resolved on ${elementOf(ev) ?? "instance"}`,
+    },
+    UserTaskCreated: {
+        kind: "human",
+        text: (ev) => `User task ${elementOf(ev) ?? ""} awaiting a human`.trim(),
+    },
+    UserTaskAssigned: {
+        kind: "human",
+        text: (ev) => `User task ${elementOf(ev) ?? ""} assigned`.trim() +
+            (str(ev, "assignee") ? ` to ${str(ev, "assignee")}` : ""),
+    },
+    UserTaskCompleted: {
+        kind: "human",
+        text: (ev) => `User task ${elementOf(ev) ?? ""} completed`.trim(),
+    },
+    UserTaskCanceled: {
+        kind: "human",
+        text: (ev) => `User task ${elementOf(ev) ?? ""} canceled`.trim(),
+    },
+    TimerCreated: {
+        kind: "tool",
+        text: (ev) => `Timer set on ${elementOf(ev) ?? "instance"}`,
+    },
+    TimerTriggered: {
+        kind: "tool",
+        text: (ev) => `Timer fired on ${elementOf(ev) ?? "instance"}`,
+    },
+    MessagePublished: {
+        kind: "tool",
+        text: (ev) => `Message ${str(ev, "message_name") ?? ""} published`.trim(),
+    },
+    MessageCorrelated: {
+        kind: "tool",
+        text: (ev) => `Message ${str(ev, "message_name") ?? ""} correlated`.trim(),
+    },
+    SignalBroadcast: {
+        kind: "tool",
+        text: (ev) => `Signal ${str(ev, "signal_name") ?? ""} broadcast`.trim(),
+    },
+    SignalCorrelated: {
+        kind: "tool",
+        text: (ev) => `Signal ${str(ev, "signal_name") ?? ""} correlated`.trim(),
+    },
+    AdHocActivated: {
+        kind: "agent",
+        text: (ev) => `Ad-hoc sub-process ${elementOf(ev) ?? ""} activated`.trim(),
+    },
+    AdHocToolActivated: {
+        kind: "agent",
+        text: (ev) => `Tool ${elementOf(ev) ?? ""} activated`.trim(),
+    },
+    AdHocToolCompleted: {
+        kind: "vars",
+        text: (ev) => `Tool ${elementOf(ev) ?? ""} returned`.trim(),
+    },
+    AdHocCompleted: {
+        kind: "agent",
+        text: (ev) => `Ad-hoc sub-process ${elementOf(ev) ?? ""} completed`.trim(),
+    },
+    ProcessInstanceCompleted: {
+        kind: "done",
+        text: () => "Process completed",
+    },
+    ProcessInstanceTerminated: {
+        kind: "error",
+        text: () => "Process terminated",
+    },
+};
+/**
+ * The engine-event fold adapter: map a `WasmEvent[]` (the flattened
+ * `{ seq, now, type, …snake_case }` stream from `useBojtos().events`) into
+ * normalized rows, keeping only the meaningful milestones (see
+ * {@link ENGINE_EVENT_RULES}). Each row's `id` is the event's `seq`, so ids stay
+ * stable and monotonic across re-reads of a growing log. Engine events carry no
+ * turn, so {@link buildTraceItems} over the result is a flat list of rows — the
+ * non-agentic test-view shape.
+ */
+export function foldEngineEvents(events) {
+    const rows = [];
+    for (const ev of events) {
+        const rule = ENGINE_EVENT_RULES[ev.type];
+        if (!rule)
+            continue;
+        rows.push({
+            id: ev.seq,
+            kind: rule.kind,
+            text: rule.text(ev),
+            elementId: elementOf(ev),
+        });
+    }
+    return rows;
+}

package/dist/types.d.ts

@@ -169,6 +169,15 @@ export interface Snapshot {
     signalSubscriptions: SignalSubscriptionDto[];
     elementStats: ElementStatDto[];
     takenSequenceFlows: SequenceFlowDto[];
+    /**
+     * Evaluated DMN decisions.
+     *
+     * **Reserved.** `BojtosSession.deploy` takes a BPMN resource only, so there is
+     * currently no way to deploy a decision and nothing can populate this — treat
+     * a consumer that renders it as writing for a future engine, not reading live
+     * data. Kept in the contract so the shape doesn't change when deployment of
+     * decision resources lands.
+     */
     decisionInstances: DecisionInstanceDto[];
     activeElementIds: string[];
     incidentElementIds: string[];

package/dist/worker.d.ts

@@ -61,13 +61,72 @@ export interface DispatchOptions {
      * whole agent conversation to quiescence.
      */
     agents?: Record<string, AgentHandler>;
+    /**
+     * Let the drain loop move the virtual clock when it runs out of work but a
+     * timer is still pending: it jumps to the next due timer and keeps going.
+     *
+     * Off by default, because advancing time is a decision about what the demo is
+     * showing, not a detail. With it off, a model that waits on a timer settles
+     * with `reason: "timers"` — the loop is *done*, the process isn't — and the
+     * caller advances the clock itself.
+     *
+     * `true` advances as far as needed. `{ maxTotalMs }` sets a **budget for the
+     * whole drain**, not per jump — the loop advances while it can afford to and
+     * then settles with `reason: "timers"`, so "run for up to an hour of virtual
+     * time" is expressible and a `PT24H` timer can't be reached a second at a
+     * time.
+     */
+    advanceTimers?: boolean | {
+        maxTotalMs: number;
+    };
 }
+/**
+ * Why a drain stopped. `handled === 0` alone can't say: a completed instance, a
+ * human step, a pending timer, a message that never arrived and a job type
+ * nobody registered all look identical from the outside, and each one needs a
+ * different response from the UI above.
+ */
+export type SettleReason = 
+/** No live instances remain — every one completed or was terminated. */
+"completed"
+/** Waiting on a `userTask`; complete it with `session.completeUserTask`. */
+ | "userTasks"
+/** Waiting on a timer; advance the clock (or pass `advanceTimers`). */
+ | "timers"
+/** Waiting on a message subscription; publish with `correlateMessage`. */
+ | "messages"
+/** Waiting on a signal subscription; publish with `broadcastSignal`. */
+ | "signals"
+/** Jobs are waiting whose job type has no registered handler. */
+ | "unhandledJobs"
+/** An incident is blocking progress; resolve it to continue. */
+ | "incidents"
+/** Nothing is running and nothing is waiting — an empty or unstarted engine. */
+ | "idle";
+/**
+ * Classify why the loop has nothing left to do. Pure, and exported so a consumer
+ * can label a snapshot it obtained some other way (and so it can be tested
+ * without an engine).
+ *
+ * Order matters: it reports the thing a caller can act on first. Incidents come
+ * before waiting states because an incident is why the wait will never end.
+ */
+export declare function settleReason(snapshot: Snapshot, handledJobTypes?: Iterable<string>): SettleReason;
+/** Job types with waiting jobs that no registered handler serves. */
+export declare function unhandledJobTypes(snapshot: Snapshot, handledJobTypes?: Iterable<string>): string[];
 /** What one {@link dispatchRound} pass did. */
 export interface RoundResult {
     /** The snapshot after this pass. */
     snapshot: Snapshot;
     /** How many jobs were completed or failed in this pass. */
     handled: number;
+    /**
+     * Why there was nothing left to do, when `handled === 0`. Undefined while the
+     * round did work — the loop hasn't settled, so there is nothing to explain.
+     */
+    reason?: SettleReason;
+    /** Waiting job types no registered handler serves (usually a typo). */
+    unhandled?: string[];
 }
 /** What {@link dispatchWorkers} did. */
 export interface DispatchResult {
@@ -77,6 +136,15 @@ export interface DispatchResult {
     handled: number;
     /** How many activate rounds ran (including the final quiescent one). */
     rounds: number;
+    /**
+     * Why the drain stopped. Always set: a settled drain always has a reason, and
+     * "the loop finished" is not the same claim as "the process finished".
+     */
+    reason: SettleReason;
+    /** Waiting job types no registered handler serves (usually a typo). */
+    unhandled: string[];
+    /** How far the virtual clock was moved, when `advanceTimers` is on. */
+    advancedMs: number;
 }
 /**
  * Run one activate-and-handle pass: activate every registered job type's

package/dist/worker.js

@@ -12,6 +12,40 @@ export class JobFailure extends Error {
         this.retries = opts?.retries;
     }
 }
+/**
+ * Classify why the loop has nothing left to do. Pure, and exported so a consumer
+ * can label a snapshot it obtained some other way (and so it can be tested
+ * without an engine).
+ *
+ * Order matters: it reports the thing a caller can act on first. Incidents come
+ * before waiting states because an incident is why the wait will never end.
+ */
+export function settleReason(snapshot, handledJobTypes = []) {
+    const live = snapshot.instances.filter((i) => !i.completed);
+    if (live.length === 0)
+        return snapshot.totalInstances > 0 ? "completed" : "idle";
+    if (snapshot.incidents.length > 0)
+        return "incidents";
+    const known = new Set(handledJobTypes);
+    if (snapshot.jobs.some((j) => !known.has(j.jobType)))
+        return "unhandledJobs";
+    if (snapshot.userTasks.some((t) => t.state === "Created"))
+        return "userTasks";
+    if (snapshot.timers.length > 0)
+        return "timers";
+    if (snapshot.messageSubscriptions.length > 0)
+        return "messages";
+    if (snapshot.signalSubscriptions.length > 0)
+        return "signals";
+    return "idle";
+}
+/** Job types with waiting jobs that no registered handler serves. */
+export function unhandledJobTypes(snapshot, handledJobTypes = []) {
+    const known = new Set(handledJobTypes);
+    return [...new Set(snapshot.jobs.map((j) => j.jobType))]
+        .filter((t) => !known.has(t))
+        .sort();
+}
 async function runOne(session, handler, job) {
     let payload;
     try {
@@ -112,9 +146,18 @@ export async function dispatchRound(session, workers, opts = {}) {
     for (const { handler, job } of agentBatch) {
         await runOneAgent(session, handler, job);
     }
+    const snapshot = session.snapshot();
+    const handled = jobBatch.length + agentBatch.length;
+    if (handled > 0)
+        return { snapshot, handled };
+    // Nothing left to do this round — say why, so the caller isn't left to infer
+    // "finished" from "quiet".
+    const known = [...Object.keys(workers), ...Object.keys(agents)];
     return {
-        snapshot: session.snapshot(),
-        handled: jobBatch.length + agentBatch.length,
+        snapshot,
+        handled,
+        reason: settleReason(snapshot, known),
+        unhandled: unhandledJobTypes(snapshot, known),
     };
 }
 /**
@@ -129,8 +172,16 @@ export async function dispatchRound(session, workers, opts = {}) {
  */
 export async function dispatchWorkers(session, workers, opts = {}) {
     const maxRounds = opts.maxRounds ?? 1000;
+    // `typeof null === "object"`, so guard against a JS caller passing `null`
+    // (via `any`) — otherwise reading `.maxTotalMs` off it throws.
+    const advanceTimers = opts.advanceTimers;
+    const timeBudgetMs = advanceTimers != null && typeof advanceTimers === "object"
+        ? advanceTimers.maxTotalMs
+        : Infinity;
+    const mayAdvance = advanceTimers != null && advanceTimers !== false;
     let handled = 0;
     let rounds = 0;
+    let advancedMs = 0;
     for (;;) {
         if (rounds >= maxRounds) {
             throw new Error(`dispatchWorkers exceeded maxRounds (${maxRounds}) — a handler may be creating work without end`);
@@ -138,8 +189,40 @@ export async function dispatchWorkers(session, workers, opts = {}) {
         rounds++;
         const round = await dispatchRound(session, workers, opts);
         handled += round.handled;
-        if (round.handled === 0) {
-            return { snapshot: round.snapshot, handled, rounds };
+        if (round.handled > 0)
+            continue;
+        // Out of jobs. If the only thing standing between here and more work is the
+        // clock, and the caller asked us to, jump to the next due timer and carry
+        // on — otherwise a timer-bearing model looks finished when it is waiting.
+        if (mayAdvance && round.reason === "timers") {
+            const due = round.snapshot.timers.reduce((min, t) => Math.min(min, t.dueInMs), Infinity);
+            // `dueInMs` can be <= 0 for a timer that is already due but hasn't been
+            // triggered; nudge by 1ms so the clock always moves and the loop can't spin.
+            const jump = Math.max(due, 1);
+            // Only jump if the whole hop fits the budget. A partial hop would burn the
+            // budget without firing anything, which is strictly worse than stopping
+            // and telling the caller a timer is still pending.
+            if (Number.isFinite(jump) && advancedMs + jump <= timeBudgetMs) {
+                session.advanceTime(jump);
+                advancedMs += jump;
+                continue;
+            }
         }
+        return {
+            snapshot: round.snapshot,
+            handled,
+            rounds,
+            // `round.reason` is always set once `round.handled === 0` (the only way to
+            // reach here), so the fallback is currently unreachable — but if it ever
+            // did fire it must use the same handler set as the round, or it would
+            // recompute against an empty set and flag every job type as unhandled.
+            reason: round.reason ??
+                settleReason(round.snapshot, [
+                    ...Object.keys(workers),
+                    ...Object.keys(opts.agents ?? {}),
+                ]),
+            unhandled: round.unhandled ?? [],
+            advancedMs,
+        };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/bojtos-kit",
-  "version": "0.4.0",
+  "version": "0.6.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",

package/src/index.ts

@@ -11,6 +11,8 @@ export {
 export {
   dispatchWorkers,
   dispatchRound,
+  settleReason,
+  unhandledJobTypes,
   JobFailure,
   type JobHandler,
   type JobResult,
@@ -18,7 +20,28 @@ export {
   type DispatchOptions,
   type DispatchResult,
   type RoundResult,
+  type SettleReason,
 } from "./worker.js";
+// The shared trace model + both adapters (engine-event fold and handler-emitted
+// `TraceEntry`) that retired the two forked `TraceTimeline` copies (#9). Pure and
+// React-free — the presentational component lives in @nanobpm/bojtos-react.
+export {
+  buildTraceItems,
+  isTraceTurnGroup,
+  foldEngineEvents,
+  traceEntriesToRows,
+} from "./trace.js";
+export type {
+  TraceRowKind,
+  TraceEntry,
+  TraceRow,
+  TraceTurnGroup,
+  TraceItem,
+  TraceAdapter,
+} from "./trace.js";
+// Every type reachable from `Snapshot` is exported: a consumer that can read
+// `snapshot.userTasks` must also be able to name `UserTaskDto` to write a
+// helper for it. Keep this list exhaustive when adding to `types.ts`.
 export type {
   Snapshot,
   InstanceDto,
@@ -26,7 +49,14 @@ export type {
   ActivatedJob,
   IncidentDto,
   TimerDto,
+  UserTaskDto,
+  MessageSubscriptionDto,
+  SignalSubscriptionDto,
+  ElementStatDto,
+  SequenceFlowDto,
+  DecisionInstanceDto,
   ActiveEl,
+  ActivateInstruction,
   AgentActivation,
   AgentResult,
   WasmEvent,

package/src/trace.ts

@@ -0,0 +1,291 @@
+// The framework-agnostic trace model shared by the Bojtos demo framework and the
+// console test-view — the single source that retired the two drifted, forked
+// `TraceTimeline` copies (nanobpm/bojtos#9). It defines one normalized row/turn
+// model plus the two adapters that map a source into it:
+//
+//   1. the **engine-event fold** — `WasmEvent[]` (from `useBojtos().events`) →
+//      rows, covering the non-agentic / test-view case; and
+//   2. the **handler-emitted `TraceEntry`** adapter — the agent/tool/turn entries
+//      (with the additive `turn` grouping field) → rows, covering the agentic
+//      web-demo case.
+//
+// It is deliberately React-free: the presentational component (`TraceTimeline` in
+// `@nanobpm/bojtos-react`) renders this model, keeping the view layer thin.
+
+import type { WasmEvent } from "./types.js";
+
+/**
+ * Semantic classification of a trace row, driving how the view styles it (the
+ * `log-<kind>` class the two forked timelines already keyed off) and which
+ * affordance it carries. Framework-agnostic — an engine-event fold and an
+ * agentic handler stream both land in this shared vocabulary:
+ *
+ * - `start` — the run/instance began.
+ * - `agent` — an agent decision, or a tool the agent activated this turn.
+ * - `llm`   — a raw model reply.
+ * - `tool`  — a tool/handler log line (a job running, a timer, a message).
+ * - `human` — a user task awaiting or completed by a person.
+ * - `done`  — the final outcome (the instance completed/terminated).
+ * - `error` — a failure, incident, or thrown error.
+ * - `vars`  — a variables/result update (e.g. what a tool returned).
+ */
+export type TraceRowKind =
+  | "start"
+  | "agent"
+  | "llm"
+  | "tool"
+  | "human"
+  | "done"
+  | "error"
+  | "vars";
+
+/**
+ * A source line before it is placed in the normalized model. This is the shape a
+ * handler emits (the web-demo framework's `TraceEntry`): `kind`/`text` are all a
+ * plain consumer needs; every other field is additive and safe to ignore.
+ */
+export interface TraceEntry {
+  kind: TraceRowKind;
+  /** The human-readable line. */
+  text: string;
+  /**
+   * Stable id for an entry that updates in place — a streaming completion grows
+   * one line rather than spamming forty.
+   */
+  key?: string;
+  /** True while the entry is still being produced (renders a spinner). */
+  pending?: boolean;
+  /**
+   * Groups every entry produced by one agent turn together (the streamed LLM
+   * reply, each tool it activated, and that tool's result). Consecutive entries
+   * sharing a `turn` fold into one turn card; entries with no `turn` render as
+   * plain rows in their original order.
+   */
+  turn?: number;
+  /** The BPMN element (tool or task) this entry concerns. */
+  elementId?: string;
+  /** Arguments supplied when activating a tool — the coerced values, not the raw reply. */
+  args?: Record<string, unknown>;
+  /** What a tool/handler returned, paired with its activation by `elementId`. */
+  result?: unknown;
+}
+
+/**
+ * A normalized row: a {@link TraceEntry} stamped with a stable, monotonic `id`.
+ * The `id` is what the view keys off and what pairs a tool's result with its
+ * activation and orders loose lines within a turn.
+ */
+export interface TraceRow extends TraceEntry {
+  id: number;
+}
+
+/** Consecutive same-turn rows, folded into one group by {@link buildTraceItems}. */
+export interface TraceTurnGroup {
+  turn: number;
+  rows: TraceRow[];
+}
+
+/** A top-level item the view renders: either a plain row or a turn group. */
+export type TraceItem = TraceRow | TraceTurnGroup;
+
+/** Narrow a {@link TraceItem} to a {@link TraceTurnGroup}. */
+export function isTraceTurnGroup(item: TraceItem): item is TraceTurnGroup {
+  return (item as TraceTurnGroup).rows !== undefined;
+}
+
+/**
+ * An adapter maps a source (`WasmEvent[]`, a `TraceEntry[]`, …) into the shared
+ * normalized row model. Both built-in adapters — {@link foldEngineEvents} and
+ * {@link traceEntriesToRows} — satisfy this; a consumer can supply its own for a
+ * bespoke source.
+ */
+export type TraceAdapter<TSource> = (source: TSource) => TraceRow[];
+
+/**
+ * Fold a flat list of normalized rows into the view model: consecutive rows
+ * sharing a `turn` become one {@link TraceTurnGroup}; everything else stays a
+ * plain row in its original order. A row with no `turn` breaks the current group,
+ * so an interleaved non-turn line never gets swallowed into a card. This is the
+ * grouping both forked timelines did by hand, lifted into the shared kit.
+ */
+export function buildTraceItems(rows: TraceRow[]): TraceItem[] {
+  const items: TraceItem[] = [];
+  let current: TraceTurnGroup | null = null;
+  for (const row of rows) {
+    if (row.turn !== undefined) {
+      if (current && current.turn === row.turn) {
+        current.rows.push(row);
+      } else {
+        current = { turn: row.turn, rows: [row] };
+        items.push(current);
+      }
+    } else {
+      current = null;
+      items.push(row);
+    }
+  }
+  return items;
+}
+
+/**
+ * The handler-emitted `TraceEntry` adapter: stamp each entry with a stable `id`
+ * (its index) to lift it into a {@link TraceRow}. The entries already carry the
+ * additive `turn`/`elementId`/`args`/`result` fields, so {@link buildTraceItems}
+ * over the result reproduces the agentic turn-grouped card view without any
+ * re-forked grouping logic. The input is never mutated.
+ */
+export function traceEntriesToRows(entries: readonly TraceEntry[]): TraceRow[] {
+  return entries.map((entry, id) => ({ ...entry, id }));
+}
+
+/**
+ * How one engine event type folds into the trace: its row {@link TraceRowKind}
+ * and a function turning the event's snake_case payload into a line. Returning
+ * a mapping opts the event into the story; every type absent from the table
+ * below is deliberately dropped as low-signal lifecycle noise (`ElementActivating`
+ * / `ElementCompleting`, `JobActivated`, `SequenceFlowTaken`, the scoped-variable
+ * and parallel-join bookkeeping), so the fold reads as a run's milestones rather
+ * than a raw trace.
+ */
+interface EngineEventRule {
+  kind: TraceRowKind;
+  text: (ev: WasmEvent) => string;
+}
+
+/** Read a string field off a `WasmEvent`'s open payload, or `undefined`. */
+function str(ev: WasmEvent, key: string): string | undefined {
+  const v = ev[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+/** The element this event concerns, if it names one — for pairing/labelling. */
+function elementOf(ev: WasmEvent): string | undefined {
+  return str(ev, "element_id");
+}
+
+const ENGINE_EVENT_RULES: Record<string, EngineEventRule> = {
+  ProcessInstanceCreated: {
+    kind: "start",
+    text: (ev) => `Process ${str(ev, "process_id") ?? "instance"} started`,
+  },
+  JobCreated: {
+    kind: "tool",
+    text: (ev) =>
+      `Job ${str(ev, "job_type") ?? ""} created`.trim() +
+      (elementOf(ev) ? ` on ${elementOf(ev)}` : ""),
+  },
+  JobCompleted: {
+    kind: "vars",
+    text: (ev) => `Job ${str(ev, "job_type") ?? ""} completed`.trim(),
+  },
+  JobFailed: {
+    kind: "error",
+    text: (ev) => `Job ${str(ev, "job_type") ?? ""} failed`.trim(),
+  },
+  JobErrorThrown: {
+    kind: "error",
+    text: (ev) =>
+      `Job threw error ${str(ev, "error_code") ?? ""}`.trim() +
+      (elementOf(ev) ? ` on ${elementOf(ev)}` : ""),
+  },
+  IncidentRaised: {
+    kind: "error",
+    text: (ev) =>
+      `Incident on ${elementOf(ev) ?? "instance"}` +
+      (str(ev, "reason") ? `: ${str(ev, "reason")}` : ""),
+  },
+  IncidentResolved: {
+    kind: "tool",
+    text: (ev) => `Incident resolved on ${elementOf(ev) ?? "instance"}`,
+  },
+  UserTaskCreated: {
+    kind: "human",
+    text: (ev) => `User task ${elementOf(ev) ?? ""} awaiting a human`.trim(),
+  },
+  UserTaskAssigned: {
+    kind: "human",
+    text: (ev) =>
+      `User task ${elementOf(ev) ?? ""} assigned`.trim() +
+      (str(ev, "assignee") ? ` to ${str(ev, "assignee")}` : ""),
+  },
+  UserTaskCompleted: {
+    kind: "human",
+    text: (ev) => `User task ${elementOf(ev) ?? ""} completed`.trim(),
+  },
+  UserTaskCanceled: {
+    kind: "human",
+    text: (ev) => `User task ${elementOf(ev) ?? ""} canceled`.trim(),
+  },
+  TimerCreated: {
+    kind: "tool",
+    text: (ev) => `Timer set on ${elementOf(ev) ?? "instance"}`,
+  },
+  TimerTriggered: {
+    kind: "tool",
+    text: (ev) => `Timer fired on ${elementOf(ev) ?? "instance"}`,
+  },
+  MessagePublished: {
+    kind: "tool",
+    text: (ev) => `Message ${str(ev, "message_name") ?? ""} published`.trim(),
+  },
+  MessageCorrelated: {
+    kind: "tool",
+    text: (ev) => `Message ${str(ev, "message_name") ?? ""} correlated`.trim(),
+  },
+  SignalBroadcast: {
+    kind: "tool",
+    text: (ev) => `Signal ${str(ev, "signal_name") ?? ""} broadcast`.trim(),
+  },
+  SignalCorrelated: {
+    kind: "tool",
+    text: (ev) => `Signal ${str(ev, "signal_name") ?? ""} correlated`.trim(),
+  },
+  AdHocActivated: {
+    kind: "agent",
+    text: (ev) => `Ad-hoc sub-process ${elementOf(ev) ?? ""} activated`.trim(),
+  },
+  AdHocToolActivated: {
+    kind: "agent",
+    text: (ev) => `Tool ${elementOf(ev) ?? ""} activated`.trim(),
+  },
+  AdHocToolCompleted: {
+    kind: "vars",
+    text: (ev) => `Tool ${elementOf(ev) ?? ""} returned`.trim(),
+  },
+  AdHocCompleted: {
+    kind: "agent",
+    text: (ev) => `Ad-hoc sub-process ${elementOf(ev) ?? ""} completed`.trim(),
+  },
+  ProcessInstanceCompleted: {
+    kind: "done",
+    text: () => "Process completed",
+  },
+  ProcessInstanceTerminated: {
+    kind: "error",
+    text: () => "Process terminated",
+  },
+};
+
+/**
+ * The engine-event fold adapter: map a `WasmEvent[]` (the flattened
+ * `{ seq, now, type, …snake_case }` stream from `useBojtos().events`) into
+ * normalized rows, keeping only the meaningful milestones (see
+ * {@link ENGINE_EVENT_RULES}). Each row's `id` is the event's `seq`, so ids stay
+ * stable and monotonic across re-reads of a growing log. Engine events carry no
+ * turn, so {@link buildTraceItems} over the result is a flat list of rows — the
+ * non-agentic test-view shape.
+ */
+export function foldEngineEvents(events: readonly WasmEvent[]): TraceRow[] {
+  const rows: TraceRow[] = [];
+  for (const ev of events) {
+    const rule = ENGINE_EVENT_RULES[ev.type];
+    if (!rule) continue;
+    rows.push({
+      id: ev.seq,
+      kind: rule.kind,
+      text: rule.text(ev),
+      elementId: elementOf(ev),
+    });
+  }
+  return rows;
+}

package/src/types.ts

@@ -190,6 +190,15 @@ export interface Snapshot {
   signalSubscriptions: SignalSubscriptionDto[];
   elementStats: ElementStatDto[];
   takenSequenceFlows: SequenceFlowDto[];
+  /**
+   * Evaluated DMN decisions.
+   *
+   * **Reserved.** `BojtosSession.deploy` takes a BPMN resource only, so there is
+   * currently no way to deploy a decision and nothing can populate this — treat
+   * a consumer that renders it as writing for a future engine, not reading live
+   * data. Kept in the contract so the shape doesn't change when deployment of
+   * decision resources lands.
+   */
   decisionInstances: DecisionInstanceDto[];
   activeElementIds: string[];
   incidentElementIds: string[];

package/src/worker.ts

@@ -72,6 +72,84 @@ export interface DispatchOptions {
    * whole agent conversation to quiescence.
    */
   agents?: Record<string, AgentHandler>;
+  /**
+   * Let the drain loop move the virtual clock when it runs out of work but a
+   * timer is still pending: it jumps to the next due timer and keeps going.
+   *
+   * Off by default, because advancing time is a decision about what the demo is
+   * showing, not a detail. With it off, a model that waits on a timer settles
+   * with `reason: "timers"` — the loop is *done*, the process isn't — and the
+   * caller advances the clock itself.
+   *
+   * `true` advances as far as needed. `{ maxTotalMs }` sets a **budget for the
+   * whole drain**, not per jump — the loop advances while it can afford to and
+   * then settles with `reason: "timers"`, so "run for up to an hour of virtual
+   * time" is expressible and a `PT24H` timer can't be reached a second at a
+   * time.
+   */
+  advanceTimers?: boolean | { maxTotalMs: number };
+}
+
+/**
+ * Why a drain stopped. `handled === 0` alone can't say: a completed instance, a
+ * human step, a pending timer, a message that never arrived and a job type
+ * nobody registered all look identical from the outside, and each one needs a
+ * different response from the UI above.
+ */
+export type SettleReason =
+  /** No live instances remain — every one completed or was terminated. */
+  | "completed"
+  /** Waiting on a `userTask`; complete it with `session.completeUserTask`. */
+  | "userTasks"
+  /** Waiting on a timer; advance the clock (or pass `advanceTimers`). */
+  | "timers"
+  /** Waiting on a message subscription; publish with `correlateMessage`. */
+  | "messages"
+  /** Waiting on a signal subscription; publish with `broadcastSignal`. */
+  | "signals"
+  /** Jobs are waiting whose job type has no registered handler. */
+  | "unhandledJobs"
+  /** An incident is blocking progress; resolve it to continue. */
+  | "incidents"
+  /** Nothing is running and nothing is waiting — an empty or unstarted engine. */
+  | "idle";
+
+/**
+ * Classify why the loop has nothing left to do. Pure, and exported so a consumer
+ * can label a snapshot it obtained some other way (and so it can be tested
+ * without an engine).
+ *
+ * Order matters: it reports the thing a caller can act on first. Incidents come
+ * before waiting states because an incident is why the wait will never end.
+ */
+export function settleReason(
+  snapshot: Snapshot,
+  handledJobTypes: Iterable<string> = [],
+): SettleReason {
+  const live = snapshot.instances.filter((i) => !i.completed);
+  if (live.length === 0)
+    return snapshot.totalInstances > 0 ? "completed" : "idle";
+  if (snapshot.incidents.length > 0) return "incidents";
+
+  const known = new Set(handledJobTypes);
+  if (snapshot.jobs.some((j) => !known.has(j.jobType))) return "unhandledJobs";
+
+  if (snapshot.userTasks.some((t) => t.state === "Created")) return "userTasks";
+  if (snapshot.timers.length > 0) return "timers";
+  if (snapshot.messageSubscriptions.length > 0) return "messages";
+  if (snapshot.signalSubscriptions.length > 0) return "signals";
+  return "idle";
+}
+
+/** Job types with waiting jobs that no registered handler serves. */
+export function unhandledJobTypes(
+  snapshot: Snapshot,
+  handledJobTypes: Iterable<string> = [],
+): string[] {
+  const known = new Set(handledJobTypes);
+  return [...new Set(snapshot.jobs.map((j) => j.jobType))]
+    .filter((t) => !known.has(t))
+    .sort();
 }
 
 /** What one {@link dispatchRound} pass did. */
@@ -80,6 +158,13 @@ export interface RoundResult {
   snapshot: Snapshot;
   /** How many jobs were completed or failed in this pass. */
   handled: number;
+  /**
+   * Why there was nothing left to do, when `handled === 0`. Undefined while the
+   * round did work — the loop hasn't settled, so there is nothing to explain.
+   */
+  reason?: SettleReason;
+  /** Waiting job types no registered handler serves (usually a typo). */
+  unhandled?: string[];
 }
 
 /** What {@link dispatchWorkers} did. */
@@ -90,6 +175,15 @@ export interface DispatchResult {
   handled: number;
   /** How many activate rounds ran (including the final quiescent one). */
   rounds: number;
+  /**
+   * Why the drain stopped. Always set: a settled drain always has a reason, and
+   * "the loop finished" is not the same claim as "the process finished".
+   */
+  reason: SettleReason;
+  /** Waiting job types no registered handler serves (usually a typo). */
+  unhandled: string[];
+  /** How far the virtual clock was moved, when `advanceTimers` is on. */
+  advancedMs: number;
 }
 
 async function runOne(
@@ -208,9 +302,17 @@ export async function dispatchRound(
   for (const { handler, job } of agentBatch) {
     await runOneAgent(session, handler, job);
   }
+  const snapshot = session.snapshot();
+  const handled = jobBatch.length + agentBatch.length;
+  if (handled > 0) return { snapshot, handled };
+  // Nothing left to do this round — say why, so the caller isn't left to infer
+  // "finished" from "quiet".
+  const known = [...Object.keys(workers), ...Object.keys(agents)];
   return {
-    snapshot: session.snapshot(),
-    handled: jobBatch.length + agentBatch.length,
+    snapshot,
+    handled,
+    reason: settleReason(snapshot, known),
+    unhandled: unhandledJobTypes(snapshot, known),
   };
 }
 
@@ -230,8 +332,18 @@ export async function dispatchWorkers(
   opts: DispatchOptions = {},
 ): Promise<DispatchResult> {
   const maxRounds = opts.maxRounds ?? 1000;
+  // `typeof null === "object"`, so guard against a JS caller passing `null`
+  // (via `any`) — otherwise reading `.maxTotalMs` off it throws.
+  const advanceTimers = opts.advanceTimers;
+  const timeBudgetMs =
+    advanceTimers != null && typeof advanceTimers === "object"
+      ? advanceTimers.maxTotalMs
+      : Infinity;
+  const mayAdvance = advanceTimers != null && advanceTimers !== false;
+
   let handled = 0;
   let rounds = 0;
+  let advancedMs = 0;
   for (;;) {
     if (rounds >= maxRounds) {
       throw new Error(
@@ -241,8 +353,45 @@ export async function dispatchWorkers(
     rounds++;
     const round = await dispatchRound(session, workers, opts);
     handled += round.handled;
-    if (round.handled === 0) {
-      return { snapshot: round.snapshot, handled, rounds };
+    if (round.handled > 0) continue;
+
+    // Out of jobs. If the only thing standing between here and more work is the
+    // clock, and the caller asked us to, jump to the next due timer and carry
+    // on — otherwise a timer-bearing model looks finished when it is waiting.
+    if (mayAdvance && round.reason === "timers") {
+      const due = round.snapshot.timers.reduce(
+        (min, t) => Math.min(min, t.dueInMs),
+        Infinity,
+      );
+      // `dueInMs` can be <= 0 for a timer that is already due but hasn't been
+      // triggered; nudge by 1ms so the clock always moves and the loop can't spin.
+      const jump = Math.max(due, 1);
+      // Only jump if the whole hop fits the budget. A partial hop would burn the
+      // budget without firing anything, which is strictly worse than stopping
+      // and telling the caller a timer is still pending.
+      if (Number.isFinite(jump) && advancedMs + jump <= timeBudgetMs) {
+        session.advanceTime(jump);
+        advancedMs += jump;
+        continue;
+      }
     }
+
+    return {
+      snapshot: round.snapshot,
+      handled,
+      rounds,
+      // `round.reason` is always set once `round.handled === 0` (the only way to
+      // reach here), so the fallback is currently unreachable — but if it ever
+      // did fire it must use the same handler set as the round, or it would
+      // recompute against an empty set and flag every job type as unhandled.
+      reason:
+        round.reason ??
+        settleReason(round.snapshot, [
+          ...Object.keys(workers),
+          ...Object.keys(opts.agents ?? {}),
+        ]),
+      unhandled: round.unhandled ?? [],
+      advancedMs,
+    };
   }
 }