bazis 0.124.0 → 0.125.0

package/core/agent/AgentToolExecutor.ts

@@ -2146,7 +2146,7 @@ export class AgentToolExecutor {
     details?: JsonObject,
   ): AgentToolResult {
     if (error instanceof ToolError) {
-      return this.errorResult(call, code, error.message, metadata, startedAt, details);
+      return this.errorResult(call, code, error.message, metadata, startedAt, error.reason === undefined ? details : { ...details, reason: error.reason });
     }
     this.logger?.error("Agent tool failed", { agent: agentName ?? null, tool: call.name, callId: call.id, code, error: redactSensitive(error) });
     return this.errorResult(call, code, fallback, metadata, startedAt, details);

package/core/agent/errors.ts

@@ -29,9 +29,20 @@ export class AgentToolExecutionError extends Error {
  * goes to the application log with its stack.
  */
 export class ToolError extends Error {
-  constructor(message: string) {
+  /**
+   * A business reason the caller can act on, such as `card_declined`: it comes
+   * back as `error.details.reason`. A process routes it to an error boundary
+   * and does not retry it (WORKFLOW-001).
+   */
+  readonly reason?: string;
+
+  constructor(message: string, options: { readonly reason?: string } = {}) {
     super(message);
     this.name = "ToolError";
+    if (options.reason !== undefined) {
+      if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(options.reason)) throw new TypeError("ToolError reason must match ^[A-Za-z][A-Za-z0-9_.-]{0,63}$");
+      this.reason = options.reason;
+    }
   }
 }
 
@@ -41,8 +52,8 @@ export class ToolError extends Error {
  * for an idempotency-gated retry. Its message reaches the model like a ToolError.
  */
 export class AgentToolPreCommitError extends ToolError {
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options: { readonly reason?: string } = {}) {
+    super(message, options);
     this.name = "AgentToolPreCommitError";
   }
 }

package/core/app/ui/uiSurfaceHttp.ts

@@ -1,3 +1,4 @@
+import { contextOnlyController } from "../../http/Routing/contextOnlyControllers";
 import {
   Controller,
   ForbiddenError,
@@ -183,6 +184,7 @@ export class UiSurfaceHttpController {
     return versionedJson(ctx, document, document.metadata.revision);
   }
 }
+contextOnlyController(UiSurfaceHttpController);
 
 function validateSurfaceRegistration(
   options: RunAppUiSurfaceOptions,

package/core/http/Routing/RouterBuilder.ts

@@ -2,6 +2,7 @@ import type { Class, Token } from "../../di";
 import { assertConsumes, bindArguments } from "../Binding/ParameterBinder";
 import { resolveGeneratedBindings } from "../Binding/autoBindings";
 import { generatedSourcesAreStale } from "../../generatedFingerprint";
+import { isContextOnlyController } from "./contextOnlyControllers";
 import { controllerMetaOf, type ActionMeta, type ControllerMeta } from "../Decorators/metadata";
 import { HttpSetupError } from "../Errors/HttpError";
 import type { HttpContext } from "../HttpContext/HttpContext";
@@ -237,7 +238,7 @@ function assertBindingsFresh(
   methodName: string | symbol,
   bindings: readonly unknown[] | undefined,
 ): void {
-  if (bindings !== undefined || !generatedSourcesAreStale()) {
+  if (bindings !== undefined || isContextOnlyController(controllerClass) || !generatedSourcesAreStale()) {
     return;
   }
   const method = (controllerClass.prototype as Record<string | symbol, unknown>)[methodName];

package/core/http/Routing/contextOnlyControllers.ts

@@ -0,0 +1,16 @@
+const contextOnly = new WeakSet<object>();
+
+/**
+ * @internal Marks a framework controller whose actions read the `HttpContext`
+ * themselves. The application's codegen never covers framework classes, so a
+ * stale application codegen says nothing about them and must not stop the start.
+ */
+export function contextOnlyController<T extends object>(controller: T): T {
+  contextOnly.add(controller);
+  return controller;
+}
+
+/** @internal */
+export function isContextOnlyController(controller: object): boolean {
+  return contextOnly.has(controller);
+}

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.124.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.125.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/workflow/definitions_module/http/Processes.controller.ts

@@ -1,3 +1,4 @@
+import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
 import { Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
 import { authorize, body, optionalInteger, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
 import { WorkflowError } from "../../contracts/WorkflowError";
@@ -90,3 +91,4 @@ export class ProcessesController {
     return { data: this.definitions.tools() };
   }
 }
+contextOnlyController(ProcessesController);

package/core/workflow/runtime_module/WorkflowRuntime.module.ts

@@ -9,6 +9,7 @@ import { WorkflowWorker } from "./background/WorkflowWorker";
 import { workflowRuntimeConfig } from "./config/Runtime.config";
 import { InstancesController } from "./http/Instances.controller";
 import { GraphCache } from "./internal/GraphCache";
+import { TimerStep } from "./internal/TimerStep";
 import { ToolStep } from "./internal/ToolStep";
 import { WorkflowEngine } from "./internal/WorkflowEngine";
 import { RUNTIME_ENTITIES, RuntimeDbContext, runtimeStore } from "./model/Runtime.dbContext";
@@ -35,6 +36,7 @@ import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
       resolver.tryResolve(LOGGER),
     ))),
     scoped(ToolStep, ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools] as const),
+    scoped(TimerStep, TimerStep, [RuntimeDbContext, WorkflowEngine] as const),
     // The application's input validator, if it registered one anywhere; the built-in one otherwise.
     DI.scoped(DI.factoryProviderWithResolver(IWorkflowRuntime, [], (resolver) => new WorkflowRuntime(
       resolver.resolve(RuntimeDbContext),

package/core/workflow/runtime_module/background/WorkflowWorker.ts

@@ -2,12 +2,16 @@ import { BackgroundService, delay } from "../../../background";
 import type { ServiceProvider } from "../../../di";
 import type { ConfigView } from "../../../kernel";
 import type { workflowRuntimeConfig } from "../config/Runtime.config";
+import { TimerStep } from "../internal/TimerStep";
 import { ToolStep } from "../internal/ToolStep";
+import { WorkflowEngine } from "../internal/WorkflowEngine";
 import { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
 
 /** How long a claimed job belongs to this worker; if it dies, another one takes the job after that. */
 const LEASE_MS = 5 * 60_000;
+/** A job that keeps failing outside its Tool (the database, a lost version) fails its step after this many tries. */
+const MAX_JOB_ATTEMPTS = 5;
 
 
 /**
@@ -48,9 +52,32 @@ export class WorkflowWorker extends BackgroundService {
   private async run(job: WfJob, signal: AbortSignal): Promise<void> {
     const scope = this.services.createScope();
     try {
-      await scope.resolve(ToolStep).run(job, signal);
+      if (job.kind === "timer") await scope.resolve(TimerStep).run(job);
+      else await scope.resolve(ToolStep).run(job, signal);
     } catch (error) {
-      this.reportFailure("job failed", error, { job: job.id, instance: job.instanceId });
+      this.reportFailure("job failed", error, { job: job.id, instance: job.instanceId, attempts: job.attempts });
+      await this.giveUpOrDelay(job, error).catch((failure: unknown) => this.reportFailure("job failure handling failed", failure, { job: job.id }));
+    } finally {
+      await scope.dispose();
+    }
+  }
+
+  /** A job that failed outside its Tool waits a minute per try, then fails its step for a person to retry. */
+  private async giveUpOrDelay(job: WfJob, error: unknown): Promise<void> {
+    const message = error instanceof Error ? error.message : String(error);
+    const scope = this.services.createScope();
+    try {
+      const db = scope.resolve(RuntimeDbContext);
+      if (job.attempts < MAX_JOB_ATTEMPTS || job.instanceId === null || job.tokenId === null) {
+        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: new Date(Date.now() + job.attempts * 60_000), lockedUntil: null, lastError: message.slice(0, 1000) });
+        return;
+      }
+      const engine = scope.resolve(WorkflowEngine);
+      await engine.inStep(job.instanceId, async (step) => {
+        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+        const token = step.tokens.find((t) => t.id === job.tokenId);
+        if (token && token.status === "waiting" && step.instance.status === "running") engine.fail(step, token, "job_failed", message.slice(0, 1000));
+      });
     } finally {
       await scope.dispose();
     }
@@ -63,7 +90,7 @@ export class WorkflowWorker extends BackgroundService {
       return await db.transactionScope(async () => {
         const now = new Date();
         const jobs = await db.jobs
-          .where((j) => j.kind.eq("tool").and(j.dueAt.lte(now)).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
+          .where((j) => j.kind.in(["tool", "timer"]).and(j.dueAt.lte(now)).and(j.lockedUntil.isNull().or(j.lockedUntil.lt(now))))
           .orderBy((j) => j.id)
           .take(batchSize)
           .forUpdate({ skipLocked: true })

package/core/workflow/runtime_module/events/Runtime.events.ts

@@ -20,7 +20,8 @@ export interface WorkflowTaskRequested {
 export interface WorkflowTokenClosed {
   readonly instanceId: string;
   readonly tokenId: string;
-  readonly reason: "cancelled";
+  /** `cancelled` — the instance was cancelled; `interrupted` — a boundary timer took over the step. */
+  readonly reason: "cancelled" | "interrupted";
 }
 
 /** An instance finished: completed or cancelled. */

package/core/workflow/runtime_module/http/Instances.controller.ts

@@ -1,3 +1,4 @@
+import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
 import { Controller, Created, Get, Post, type HttpContext } from "../../../http";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import { authorize, body, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
@@ -69,4 +70,5 @@ export class InstancesController {
     return await this.runtime.retry(instance.id, { actor });
   }
 }
+contextOnlyController(InstancesController);
 

package/core/workflow/runtime_module/internal/GraphCache.ts

@@ -1,4 +1,4 @@
-import type { ProcessDocument, ProcessFlow } from "../../../../library/workflow";
+import type { ProcessDocument, ProcessFlow, ProcessNode } from "../../../../library/workflow";
 
 /** A version's graph with flows indexed by node. Built once per version. */
 export interface ProcessGraph {
@@ -8,6 +8,8 @@ export interface ProcessGraph {
   readonly document: ProcessDocument;
   readonly outgoing: ReadonlyMap<string, readonly (readonly [string, ProcessFlow])[]>;
   readonly incoming: ReadonlyMap<string, readonly (readonly [string, ProcessFlow])[]>;
+  /** Boundary nodes by the step they are attached to. */
+  readonly boundaries: ReadonlyMap<string, readonly (readonly [string, ProcessNode])[]>;
 }
 
 export function buildGraph(versionId: string, processKey: string, version: number, document: ProcessDocument): ProcessGraph {
@@ -17,7 +19,11 @@ export function buildGraph(versionId: string, processKey: string, version: numbe
     outgoing.set(flow.source, [...outgoing.get(flow.source) ?? [], [id, flow]]);
     incoming.set(flow.target, [...incoming.get(flow.target) ?? [], [id, flow]]);
   }
-  return { versionId, processKey, version, document, outgoing, incoming };
+  const boundaries = new Map<string, (readonly [string, ProcessNode])[]>();
+  for (const [id, node] of Object.entries(document.nodes)) {
+    if (node.attachedTo !== undefined) boundaries.set(node.attachedTo, [...boundaries.get(node.attachedTo) ?? [], [id, node]]);
+  }
+  return { versionId, processKey, version, document, outgoing, incoming, boundaries };
 }
 
 /** Graphs of versions in memory. Versions are immutable, so entries never go stale; the oldest go first past the limit. */

package/core/workflow/runtime_module/internal/TimerStep.ts

@@ -0,0 +1,21 @@
+import type { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WfJob } from "../model/WfJob.model";
+import type { WorkflowEngine } from "./WorkflowEngine";
+
+/** One `timer` job: a `timerCatch` step or a boundary timer is due. A closed token drops it. */
+export class TimerStep {
+  constructor(
+    private readonly db: RuntimeDbContext,
+    private readonly engine: WorkflowEngine,
+  ) {}
+
+  async run(job: WfJob): Promise<void> {
+    const fired = job.instanceId === null || job.tokenId === null
+      ? null
+      : await this.engine.inStep(job.instanceId, async (step) => {
+        await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+        return await this.engine.timerFired(step, job.tokenId!);
+      });
+    if (fired === null) await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+  }
+}

package/core/workflow/runtime_module/internal/ToolStep.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult } from "../../../agent";
-import { resolveInput } from "../../../../library/workflow";
+import { durationMs, resolveInput } from "../../../../library/workflow";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
@@ -40,21 +40,57 @@ export class ToolStep {
         signal,
       });
 
+    const reason = reasonOf(result);
     await this.engine.inStep(instance.id, async (step) => {
-      await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
       const current = step.tokens.find((t) => t.id === token.id);
+      const retryAt = current?.status === "waiting" && step.instance.status === "running" && result.status === "error" && reason === undefined
+        ? nextAttempt(node?.config?.retry, job.attempts)
+        : undefined;
+      if (retryAt !== undefined) {
+        // The same job runs again later: its attempts keep counting.
+        await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ dueAt: retryAt, lockedUntil: null, lastError: result.error?.message ?? null });
+      } else {
+        await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+      }
       if (!current || current.status !== "waiting" || step.instance.status !== "running") return;
       this.engine.history(step, current, current.nodeId, "tool", {
         tool: name,
         status: result.status,
+        attempt: job.attempts,
         durationMs: result.durationMs ?? null,
-        ...(result.error ? { error: { code: result.error.code ?? null, message: result.error.message } } : {}),
+        ...(result.error ? { error: { code: result.error.code ?? null, message: result.error.message, ...(reason === undefined ? {} : { reason }) } } : {}),
+        ...(retryAt === undefined ? {} : { retryAt: retryAt.toISOString() }),
       });
+      if (retryAt !== undefined) return;
       if (result.status === "success") {
         await this.engine.complete(step, current.id, result.output ?? null);
       } else {
-        this.engine.fail(step, current, result.error?.code ?? "TOOL_FAILED", result.error?.message ?? `Tool ${name} failed`);
+        await this.engine.failStep(step, current, {
+          code: result.error?.code ?? "TOOL_FAILED",
+          message: result.error?.message ?? `Tool ${name} failed`,
+          ...(reason === undefined ? {} : { reason }),
+        });
       }
     });
   }
 }
+
+/** The business reason of a `ToolError`, if the Tool gave one. */
+function reasonOf(result: AgentToolResult): string | undefined {
+  const details = result.error?.details;
+  const reason = typeof details === "object" && details !== null && !Array.isArray(details) ? (details as Record<string, unknown>).reason : undefined;
+  return typeof reason === "string" ? reason : undefined;
+}
+
+/**
+ * When to try a failed call again under the node's `retry` policy, or
+ * `undefined` when the attempts are used up. The pause doubles from `backoff`
+ * (10 seconds by default) and stops growing at a day.
+ */
+export function nextAttempt(policy: unknown, attempts: number): Date | undefined {
+  if (typeof policy !== "object" || policy === null) return undefined;
+  const { maxAttempts, backoff } = policy as { maxAttempts?: unknown; backoff?: unknown };
+  if (typeof maxAttempts !== "number" || attempts >= maxAttempts) return undefined;
+  const base = typeof backoff === "string" ? durationMs(backoff) ?? 10_000 : 10_000;
+  return new Date(Date.now() + Math.min(base * 2 ** Math.max(attempts - 1, 0), 86_400_000));
+}

package/core/workflow/runtime_module/internal/WorkflowEngine.ts

@@ -1,6 +1,6 @@
 import type { ServiceResolver } from "../../../di";
 import { EventBus, type EventToken, type Logger } from "../../../kernel";
-import { durationMs, evaluateCondition, nodeKindOf, type FormSpec, type InstanceData, type ProcessFlow, type ProcessNode } from "../../../../library/workflow";
+import { durationMs, evaluateCondition, nodeKindOf, readPath, type FormSpec, type InstanceData, type ProcessFlow, type ProcessNode } from "../../../../library/workflow";
 import type { WorkflowActor } from "../../contracts/types";
 import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import { WORKFLOW_INSTANCE_FINISHED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED } from "../events/Runtime.events";
@@ -37,7 +37,7 @@ export interface BeginOptions {
 }
 
 /** Node kinds that come with later stages: an instance reaching one fails with a clear reason. */
-const NOT_YET = new Set(["timerCatch", "eventWait"]);
+const NOT_YET = new Set(["eventWait"]);
 const LIVE = new Set(["active", "waiting", "failed"]);
 
 /**
@@ -132,12 +132,68 @@ export class WorkflowEngine {
     const saveTo = node.config?.saveTo;
     if (typeof saveTo === "string") step.instance.vars = { ...step.instance.vars, [saveTo]: output ?? null };
     if (actor !== undefined) this.history(step, token, token.nodeId, "completed", null, actor);
+    this.disarm(step, token.nodeId);
+    await this.advance(step, this.leave(step, token, this.single(step, token.nodeId)));
+    return true;
+  }
+
+  /**
+   * A step's Tool failed for good. An error boundary attached to the step takes
+   * the token (first one whose `errorCode` equals the Tool's `reason` or error
+   * code, else one without `errorCode`); otherwise the instance fails.
+   */
+  async failStep(step: Step, token: WfToken, error: { readonly code: string; readonly message: string; readonly reason?: string }): Promise<void> {
+    const boundaries = (step.graph.boundaries.get(token.nodeId) ?? []).filter(([, node]) => node.kind === "boundaryError");
+    const matching = boundaries.find(([, node]) => node.config?.errorCode !== undefined && (node.config.errorCode === error.reason || node.config.errorCode === error.code))
+      ?? boundaries.find(([, node]) => node.config?.errorCode === undefined);
+    if (!matching) {
+      this.fail(step, token, error.code, error.message);
+      return;
+    }
+    const [boundaryId] = matching;
+    const caught = { code: error.code, message: error.message, ...(error.reason === undefined ? {} : { reason: error.reason }) };
+    token.output = { error: caught };
+    this.close(token, "done");
+    this.disarm(step, token.nodeId);
+    this.history(step, token, token.nodeId, "error", { ...caught, boundary: boundaryId });
+    step.instance.nodes = { ...step.instance.nodes, [boundaryId]: caught };
+    await this.advance(step, [this.spawn(step, boundaryId, null)]);
+  }
+
+  /**
+   * A timer job is due. A `timerCatch` step moves on. A `boundaryTimer` takes
+   * its own flow; an interrupting one (the default) first closes the step it
+   * watches. `false` when the token no longer waits.
+   */
+  async timerFired(step: Step, tokenId: string): Promise<boolean> {
+    const token = step.tokens.find((t) => t.id === tokenId);
+    if (!token || token.status !== "waiting" || step.instance.status !== "running") return false;
+    const node = step.graph.document.nodes[token.nodeId];
+    const firedAt = new Date().toISOString();
+    if (node?.kind === "timerCatch") {
+      this.history(step, token, token.nodeId, "timer", { firedAt });
+      return await this.complete(step, tokenId, { firedAt });
+    }
+    if (node?.kind !== "boundaryTimer" || node.attachedTo === undefined) return false;
+    const interrupting = node.config?.interrupting !== false;
+    this.history(step, token, token.nodeId, "timer", { firedAt, interrupting });
+    if (interrupting) {
+      for (const host of step.tokens.filter((t) => t.nodeId === node.attachedTo && LIVE.has(t.status))) {
+        this.close(host, "cancelled");
+        if (step.graph.document.nodes[host.nodeId]?.kind === "userTask") {
+          step.events.push({ event: WORKFLOW_TOKEN_CLOSED as EventToken<unknown>, payload: { instanceId: step.instance.id, tokenId: host.id, reason: "interrupted" } });
+        }
+      }
+      this.disarm(step, node.attachedTo, token.id);
+    }
+    step.instance.nodes = { ...step.instance.nodes, [token.nodeId]: { firedAt } };
     await this.advance(step, this.leave(step, token, this.single(step, token.nodeId)));
     return true;
   }
 
   /** A step failed: the token waits for a retry, the instance is `failed` with the reason. */
   fail(step: Step, token: WfToken, code: string, message: string): void {
+    this.disarm(step, token.nodeId);
     token.status = "failed";
     step.instance.status = "failed";
     step.instance.error = { node: token.nodeId, code, message };
@@ -219,15 +275,19 @@ export class WorkflowEngine {
       this.close(token, "done");
       return [];
     }
+    // An error boundary that caught a step's failure: it only leads on.
+    if (role === "boundary") return this.leave(step, token, this.single(step, token.nodeId));
     if (NOT_YET.has(node.kind)) {
       this.fail(step, token, "not_supported", `${node.kind} steps are not supported yet`);
       return [];
     }
     switch (node.kind) {
       case "serviceTask":
-        return this.waitForTool(step, token);
+        return this.arm(step, token, this.waitForTool(step, token));
       case "userTask":
-        return this.waitForTask(step, token, node);
+        return this.arm(step, token, this.waitForTask(step, token, node));
+      case "timerCatch":
+        return this.arm(step, token, this.waitForTimer(step, token, node));
       case "exclusiveGateway":
         return this.choose(step, token);
       case "parallelGateway":
@@ -238,6 +298,46 @@ export class WorkflowEngine {
     }
   }
 
+  private waitForTimer(step: Step, token: WfToken, node: ProcessNode): WfToken[] {
+    const dueAt = timerDue(node.config ?? {}, dataOf(step.instance));
+    if (dueAt === undefined) {
+      this.fail(step, token, "bad_timer", `the timer of ${token.nodeId} has no valid date`);
+      return [];
+    }
+    token.status = "waiting";
+    this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "timer" as const, instanceId: step.instance.id, tokenId: token.id, dueAt }));
+    return [];
+  }
+
+  /**
+   * A step started waiting: its boundary timers start too, each as a waiting
+   * token on the boundary node with a timer job.
+   */
+  private arm(step: Step, host: WfToken, next: WfToken[]): WfToken[] {
+    if (host.status !== "waiting") return next;
+    for (const [id, node] of step.graph.boundaries.get(host.nodeId) ?? []) {
+      if (node.kind !== "boundaryTimer") continue;
+      const dueAt = timerDue(node.config ?? {}, dataOf(step.instance));
+      if (dueAt === undefined) {
+        this.fail(step, host, "bad_timer", `the timer of ${id} has no valid date`);
+        return [];
+      }
+      const watcher = this.spawn(step, id, null);
+      watcher.status = "waiting";
+      this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "timer" as const, instanceId: step.instance.id, tokenId: watcher.id, dueAt }));
+    }
+    return next;
+  }
+
+  /** The step left or failed: its boundary tokens close; their jobs find the tokens closed and drop. */
+  private disarm(step: Step, hostNodeId: string, except?: string): void {
+    const boundaries = new Set((step.graph.boundaries.get(hostNodeId) ?? []).map(([id]) => id));
+    if (boundaries.size === 0) return;
+    for (const token of step.tokens) {
+      if (token.id !== except && boundaries.has(token.nodeId) && LIVE.has(token.status)) this.close(token, "cancelled");
+    }
+  }
+
   private waitForTool(step: Step, token: WfToken): WfToken[] {
     token.status = "waiting";
     this.db.jobs.add(Object.assign(new WfJob(), { id: Bun.randomUUIDv7(), kind: "tool" as const, instanceId: step.instance.id, tokenId: token.id, dueAt: new Date() }));
@@ -351,6 +451,20 @@ export class WorkflowEngine {
   }
 }
 
+/** When a timer fires: `duration` from now, or the date at the `at` path; `undefined` if neither is valid. */
+export function timerDue(config: Readonly<Record<string, unknown>>, data: InstanceData): Date | undefined {
+  if (typeof config.duration === "string") {
+    const ms = durationMs(config.duration);
+    return ms === undefined ? undefined : new Date(Date.now() + ms);
+  }
+  if (typeof config.at === "string") {
+    const value = readPath(data, config.at);
+    const date = value instanceof Date ? value : typeof value === "string" || typeof value === "number" ? new Date(value) : undefined;
+    return date === undefined || Number.isNaN(date.getTime()) ? undefined : date;
+  }
+  return undefined;
+}
+
 export function dataOf(instance: WfInstance): InstanceData {
   return { input: instance.input, vars: instance.vars, nodes: instance.nodes };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.124.0",
+  "version": "0.125.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",