bazis 0.121.0 → 0.124.0

package/core/workflow/internal/WorkflowTools.ts

@@ -0,0 +1,36 @@
+import type { ServiceResolver } from "../../di";
+import { ToolRunner, type AgentToolContract, type BoundToolRunner } from "../../agent";
+
+/** The workflow caller id of TOOLS-001: processes run only Tools whose `callers` list it. */
+export const WORKFLOW_CALLER = "workflow";
+
+/**
+ * The application's Tools as processes see them. `ToolRunner` exists only when
+ * a module declares `tools`; without it there is nothing to call.
+ */
+export class WorkflowTools {
+  private readonly runner: BoundToolRunner | undefined;
+
+  constructor(services: ServiceResolver) {
+    this.runner = services.tryResolve(ToolRunner)?.as(WORKFLOW_CALLER);
+  }
+
+  /** Whether a service task may call `name`. */
+  has(name: string): boolean {
+    return this.runner?.getTool(name) !== undefined;
+  }
+
+  /** Contracts of every Tool processes may call, by name. */
+  list(): readonly AgentToolContract[] {
+    if (this.runner === undefined) return [];
+    return this.runner.listTools()
+      .map((tool) => this.runner!.describe(tool.metadata.name))
+      .filter((contract): contract is AgentToolContract => contract !== undefined)
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /** The bound runner; `undefined` when the application has no Tools. */
+  get bound(): BoundToolRunner | undefined {
+    return this.runner;
+  }
+}

package/core/workflow/internal/http.ts

@@ -0,0 +1,63 @@
+import { ForbiddenError, UnauthorizedError, type HttpContext } from "../../http";
+import { WorkflowAccess, type WorkflowAccessTarget, type WorkflowAction } from "../access/WorkflowAccess";
+import type { WorkflowActor } from "../contracts/types";
+import { WorkflowError } from "../contracts/WorkflowError";
+
+/**
+ * Asks the application's {@link WorkflowAccess} who calls and whether the action
+ * is allowed. Without a registered access every route answers 403.
+ */
+export async function authorize(ctx: HttpContext, action: WorkflowAction, target: WorkflowAccessTarget = {}): Promise<WorkflowActor> {
+  const access = ctx.services.tryResolve(WorkflowAccess);
+  if (access === undefined) throw new ForbiddenError("Workflow HTTP is closed: register a WorkflowAccess implementation");
+  const actor = await access.actor(ctx);
+  if (actor === undefined) throw new UnauthorizedError();
+  if (!await access.can(ctx, action, target)) throw new ForbiddenError();
+  return actor;
+}
+
+/** A route parameter as a string. */
+export function param(ctx: HttpContext, name: string): string {
+  return String(ctx.params[name] ?? "");
+}
+
+/** The JSON body as an object; anything else is `invalid_input`. */
+export async function body(ctx: HttpContext): Promise<Record<string, unknown>> {
+  const text = await ctx.text();
+  if (text.trim() === "") return {};
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new WorkflowError("invalid_input", "The body must be JSON");
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new WorkflowError("invalid_input", "The body must be a JSON object");
+  return value as Record<string, unknown>;
+}
+
+/** An optional string field of a body or a query; another type is `invalid_input`. */
+export function optionalString(value: unknown, name: string, max = 200): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || value.length > max) throw new WorkflowError("invalid_input", `${name} must be a string up to ${max} characters`);
+  return value;
+}
+
+/** A required string field. */
+export function requiredString(value: unknown, name: string, max = 200): string {
+  const text = optionalString(value, name, max);
+  if (text === undefined || text.trim() === "") throw new WorkflowError("invalid_input", `${name} is required`);
+  return text;
+}
+
+/** An optional integer from a query string or a body. */
+export function optionalInteger(value: unknown, name: string): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const number = typeof value === "string" ? Number(value) : value;
+  if (!Number.isSafeInteger(number)) throw new WorkflowError("invalid_input", `${name} must be an integer`);
+  return number as number;
+}
+
+/** `limit` and `offset` of a list query. */
+export function pagingQuery(ctx: HttpContext): { limit?: number; offset?: number } {
+  return { limit: optionalInteger(ctx.query("limit"), "limit"), offset: optionalInteger(ctx.query("offset"), "offset") };
+}

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

@@ -0,0 +1,53 @@
+import { DI, Module, SERVICE_PROVIDER, scoped } from "../../di";
+import { EventBus, LOGGER } from "../../kernel";
+import { DefaultWorkflowInputValidator, WorkflowInputValidator } from "../contracts/WorkflowInputValidator";
+import { WorkflowDefinitionsModule } from "../definitions_module/WorkflowDefinitions.module";
+import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDefinitions.service";
+import { WorkflowTools } from "../internal/WorkflowTools";
+import { WorkflowRetention } from "./background/WorkflowRetention";
+import { WorkflowWorker } from "./background/WorkflowWorker";
+import { workflowRuntimeConfig } from "./config/Runtime.config";
+import { InstancesController } from "./http/Instances.controller";
+import { GraphCache } from "./internal/GraphCache";
+import { ToolStep } from "./internal/ToolStep";
+import { WorkflowEngine } from "./internal/WorkflowEngine";
+import { RUNTIME_ENTITIES, RuntimeDbContext, runtimeStore } from "./model/Runtime.dbContext";
+import { IWorkflowRuntime } from "./services/IWorkflowRuntime.service";
+import { WorkflowRuntime } from "./services/WorkflowRuntime.service";
+
+/**
+ * Runs published versions: instances, tokens, jobs, history, the worker and
+ * retention ([passport](MODULE.md)). Dependencies are explicit: the framework's
+ * classes are not covered by the application's codegen.
+ */
+@Module({
+  imports: [WorkflowDefinitionsModule],
+  config: [workflowRuntimeConfig],
+  ormBazis: { context: RuntimeDbContext, entities: [...RUNTIME_ENTITIES], ownedStore: runtimeStore, registerRepositories: false },
+  providers: [
+    DI.singleton(DI.factoryProvider(GraphCache, [], () => new GraphCache())),
+    DI.scoped(DI.factoryProviderWithResolver(WorkflowEngine, [], (resolver) => new WorkflowEngine(
+      resolver.resolve(RuntimeDbContext),
+      resolver.resolve(IWorkflowDefinitions),
+      resolver.resolve(GraphCache),
+      resolver.resolve(EventBus),
+      resolver,
+      resolver.tryResolve(LOGGER),
+    ))),
+    scoped(ToolStep, ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools] 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),
+      resolver.resolve(WorkflowEngine),
+      resolver.resolve(IWorkflowDefinitions),
+      resolver.resolve(SERVICE_PROVIDER).tryResolve(WorkflowInputValidator) ?? new DefaultWorkflowInputValidator(),
+    ))),
+  ],
+  controllers: [DI.bindDeps(InstancesController, IWorkflowRuntime)],
+  background: [
+    DI.bindDeps(WorkflowWorker, SERVICE_PROVIDER, workflowRuntimeConfig.token),
+    DI.bindDeps(WorkflowRetention, SERVICE_PROVIDER, workflowRuntimeConfig.token),
+  ],
+  exports: [IWorkflowRuntime],
+})
+export class WorkflowRuntimeModule {}

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

@@ -0,0 +1,66 @@
+import { BackgroundService, delay } from "../../../background";
+import type { ServiceProvider } from "../../../di";
+import type { ConfigView } from "../../../kernel";
+import { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
+import { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WorkflowSettings } from "./WorkflowWorker";
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Deletes `completed` and `cancelled` instances older than their process's
+ * `retentionDays`, with tokens, jobs, subscriptions and history (by cascade),
+ * `retention.batchSize` at a time. `failed` instances wait for a person and stay.
+ */
+export class WorkflowRetention extends BackgroundService {
+  constructor(
+    private readonly services: ServiceProvider,
+    private readonly config: ConfigView<WorkflowSettings>,
+  ) {
+    super();
+  }
+
+  protected override async execute(signal: AbortSignal): Promise<void> {
+    if (!this.config.get("retention.enabled")) return;
+    const intervalMs = this.config.get("retention.intervalMs");
+    while (!signal.aborted) {
+      try {
+        await this.sweep(signal);
+      } catch (error) {
+        if (signal.aborted) return;
+        this.reportFailure("retention sweep failed", error);
+      }
+      await delay(intervalMs, signal);
+    }
+  }
+
+  /** One pass over every process with a retention period; returns how many instances went. */
+  async sweep(signal?: AbortSignal): Promise<number> {
+    const batchSize = this.config.get("retention.batchSize");
+    const scope = this.services.createScope();
+    let deleted = 0;
+    try {
+      const definitions = scope.resolve(IWorkflowDefinitions);
+      const db = scope.resolve(RuntimeDbContext);
+      for (const policy of await definitions.retentionPolicies()) {
+        const cutoff = new Date(Date.now() - policy.retentionDays * DAY_MS);
+        for (;;) {
+          if (signal?.aborted) return deleted;
+          const ids = (await db.instances.asNoTracking()
+            .where((i) => i.processKey.eq(policy.key).and(i.status.in(["completed", "cancelled"])).and(i.endedAt.lt(cutoff)))
+            .orderBy((i) => i.id)
+            .take(batchSize)
+            .select((i) => ({ id: i.id }))
+            .toList()).map((row) => row.id);
+          if (ids.length === 0) break;
+          await db.instances.asNoTracking().where((i) => i.id.in(ids)).executeDelete();
+          deleted += ids.length;
+          if (ids.length < batchSize) break;
+        }
+      }
+    } finally {
+      await scope.dispose();
+    }
+    return deleted;
+  }
+}

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

@@ -0,0 +1,92 @@
+import { BackgroundService, delay } from "../../../background";
+import type { ServiceProvider } from "../../../di";
+import type { ConfigView } from "../../../kernel";
+import type { workflowRuntimeConfig } from "../config/Runtime.config";
+import { ToolStep } from "../internal/ToolStep";
+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;
+
+
+/**
+ * Takes due jobs of `bazis_wf_run_jobs` every `worker.intervalMs`, up to
+ * `worker.batchSize` at a time, with `FOR UPDATE SKIP LOCKED` and a lease, so
+ * application instances never take one job twice. A full batch is followed by
+ * the next one at once. Every job runs in its own DI scope.
+ */
+export class WorkflowWorker extends BackgroundService {
+  constructor(
+    private readonly services: ServiceProvider,
+    private readonly config: ConfigView<WorkflowSettings>,
+  ) {
+    super();
+  }
+
+  protected override async execute(signal: AbortSignal): Promise<void> {
+    if (!this.config.get("worker.enabled")) return;
+    const intervalMs = this.config.get("worker.intervalMs");
+    const batchSize = this.config.get("worker.batchSize");
+    while (!signal.aborted) {
+      let claimed = 0;
+      try {
+        const jobs = await this.claim(batchSize);
+        claimed = jobs.length;
+        for (const job of jobs) {
+          if (signal.aborted) return;
+          await this.run(job, signal);
+        }
+      } catch (error) {
+        if (signal.aborted) return;
+        this.reportFailure("claiming jobs failed", error);
+      }
+      if (claimed < batchSize) await delay(intervalMs, signal);
+    }
+  }
+
+  private async run(job: WfJob, signal: AbortSignal): Promise<void> {
+    const scope = this.services.createScope();
+    try {
+      await scope.resolve(ToolStep).run(job, signal);
+    } catch (error) {
+      this.reportFailure("job failed", error, { job: job.id, instance: job.instanceId });
+    } finally {
+      await scope.dispose();
+    }
+  }
+
+  private async claim(batchSize: number): Promise<WfJob[]> {
+    const scope = this.services.createScope();
+    try {
+      const db = scope.resolve(RuntimeDbContext);
+      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))))
+          .orderBy((j) => j.id)
+          .take(batchSize)
+          .forUpdate({ skipLocked: true })
+          .toList();
+        for (const job of jobs) {
+          job.lockedUntil = new Date(now.getTime() + LEASE_MS);
+          job.attempts += 1;
+        }
+        await db.saveChanges();
+        return jobs;
+      });
+    } finally {
+      await scope.dispose();
+    }
+  }
+}
+
+/** The resolved settings of {@link workflowRuntimeConfig}. */
+export interface WorkflowSettings {
+  readonly "worker.enabled": boolean;
+  readonly "worker.intervalMs": number;
+  readonly "worker.batchSize": number;
+  readonly "retention.enabled": boolean;
+  readonly "retention.intervalMs": number;
+  readonly "retention.batchSize": number;
+}

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

@@ -0,0 +1,27 @@
+import { defineConfig } from "../../../kernel";
+
+/**
+ * Settings of the workflow background services (WORKFLOW-001 §4), from the
+ * application configuration: `BAZIS_WORKFLOW__WORKER__ENABLED=false` keeps an
+ * instance from running jobs, for example a web-only one.
+ */
+export const workflowRuntimeConfig = defineConfig("workflow", {
+  default: {
+    "worker.enabled": true,
+    "worker.intervalMs": 1000,
+    "worker.batchSize": 10,
+    "retention.enabled": true,
+    "retention.intervalMs": 3_600_000,
+    "retention.batchSize": 500,
+  },
+  validate: {
+    "worker.intervalMs": (value) => positive(value, 3_600_000),
+    "worker.batchSize": (value) => positive(value, 1000),
+    "retention.intervalMs": (value) => positive(value, 86_400_000),
+    "retention.batchSize": (value) => positive(value, 10_000),
+  },
+});
+
+function positive(value: unknown, max: number): string | undefined {
+  return Number.isSafeInteger(value) && (value as number) >= 1 && (value as number) <= max ? undefined : `must be an integer 1–${max}`;
+}

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

@@ -0,0 +1,36 @@
+import { createEventToken } from "../../../kernel";
+import type { FormSpec } from "../../../../library/workflow";
+import type { InstanceStatus } from "../model/WfInstance.model";
+
+/** A token reached a user task. Published after the step commits. */
+export interface WorkflowTaskRequested {
+  readonly instanceId: string;
+  readonly tokenId: string;
+  readonly processKey: string;
+  readonly nodeId: string;
+  readonly partition: string | null;
+  readonly title: string;
+  readonly assignee: { readonly role: string } | { readonly user: string };
+  readonly form: FormSpec | null;
+  /** When the task is due, from the node's `dueIn`. */
+  readonly dueAt: Date | null;
+}
+
+/** A waiting token was closed otherwise than by its task: the task is dropped. */
+export interface WorkflowTokenClosed {
+  readonly instanceId: string;
+  readonly tokenId: string;
+  readonly reason: "cancelled";
+}
+
+/** An instance finished: completed or cancelled. */
+export interface WorkflowInstanceFinished {
+  readonly instanceId: string;
+  readonly processKey: string;
+  readonly partition: string | null;
+  readonly status: Extract<InstanceStatus, "completed" | "cancelled">;
+}
+
+export const WORKFLOW_TASK_REQUESTED = createEventToken<WorkflowTaskRequested>("workflow.task-requested");
+export const WORKFLOW_TOKEN_CLOSED = createEventToken<WorkflowTokenClosed>("workflow.token-closed");
+export const WORKFLOW_INSTANCE_FINISHED = createEventToken<WorkflowInstanceFinished>("workflow.instance-finished");

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

@@ -0,0 +1,72 @@
+import { Controller, Created, Get, Post, type HttpContext } from "../../../http";
+import { WorkflowError } from "../../contracts/WorkflowError";
+import { authorize, body, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
+import type { InstanceStatus } from "../model/WfInstance.model";
+import { IWorkflowRuntime } from "../services/IWorkflowRuntime.service";
+
+/** Instances over HTTP (WORKFLOW-001 §4); rights come from `WorkflowAccess` with the instance's partition. */
+@Controller("workflow/instances")
+export class InstancesController {
+  constructor(private readonly runtime: IWorkflowRuntime) {}
+
+  @Post()
+  async start(ctx: HttpContext) {
+    const request = await body(ctx);
+    const processKey = requiredString(request.processKey, "processKey", 64);
+    const partition = optionalString(request.partition, "partition") ?? null;
+    const actor = await authorize(ctx, "instances.start", { processKey, partition });
+    const instance = await this.runtime.start(processKey, {
+      input: request.input,
+      partition,
+      businessKey: optionalString(request.businessKey, "businessKey") ?? null,
+      actor,
+    });
+    return Created(`${ctx.path}/${instance.id}`, instance);
+  }
+
+  @Get()
+  async list(ctx: HttpContext) {
+    const partition = optionalString(ctx.query("partition"), "partition");
+    const processKey = optionalString(ctx.query("processKey"), "processKey");
+    await authorize(ctx, "instances.read", { partition: partition ?? null, ...(processKey === undefined ? {} : { processKey }) });
+    const page = await this.runtime.instances({
+      ...pagingQuery(ctx),
+      partition,
+      processKey,
+      status: optionalString(ctx.query("status"), "status") as InstanceStatus | undefined,
+      businessKey: optionalString(ctx.query("businessKey"), "businessKey"),
+      startedById: optionalString(ctx.query("startedById"), "startedById"),
+    });
+    return { data: page.items, meta: { total: page.total } };
+  }
+
+  @Get(":id")
+  async get(ctx: HttpContext) {
+    const instance = await this.runtime.instance(param(ctx, "id"));
+    await authorize(ctx, "instances.read", { processKey: instance.processKey, partition: instance.partition, instanceId: instance.id });
+    return instance;
+  }
+
+  @Get(":id/history")
+  async history(ctx: HttpContext) {
+    const instance = await this.runtime.instance(param(ctx, "id"));
+    await authorize(ctx, "instances.read", { processKey: instance.processKey, partition: instance.partition, instanceId: instance.id });
+    return { data: await this.runtime.history(instance.id) };
+  }
+
+  @Post(":id/cancel")
+  async cancel(ctx: HttpContext) {
+    const instance = await this.runtime.instance(param(ctx, "id"));
+    const request = await body(ctx);
+    const actor = await authorize(ctx, "instances.manage", { processKey: instance.processKey, partition: instance.partition, instanceId: instance.id });
+    return await this.runtime.cancel(instance.id, { reason: optionalString(request.reason, "reason", 1000) ?? null, actor });
+  }
+
+  @Post(":id/retry")
+  async retry(ctx: HttpContext) {
+    const instance = await this.runtime.instance(param(ctx, "id"));
+    const actor = await authorize(ctx, "instances.manage", { processKey: instance.processKey, partition: instance.partition, instanceId: instance.id });
+    return await this.runtime.retry(instance.id, { actor });
+  }
+}
+

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

@@ -0,0 +1,37 @@
+import type { ProcessDocument, ProcessFlow } from "../../../../library/workflow";
+
+/** A version's graph with flows indexed by node. Built once per version. */
+export interface ProcessGraph {
+  readonly versionId: string;
+  readonly processKey: string;
+  readonly version: number;
+  readonly document: ProcessDocument;
+  readonly outgoing: ReadonlyMap<string, readonly (readonly [string, ProcessFlow])[]>;
+  readonly incoming: ReadonlyMap<string, readonly (readonly [string, ProcessFlow])[]>;
+}
+
+export function buildGraph(versionId: string, processKey: string, version: number, document: ProcessDocument): ProcessGraph {
+  const outgoing = new Map<string, (readonly [string, ProcessFlow])[]>();
+  const incoming = new Map<string, (readonly [string, ProcessFlow])[]>();
+  for (const [id, flow] of Object.entries(document.flows)) {
+    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 };
+}
+
+/** Graphs of versions in memory. Versions are immutable, so entries never go stale; the oldest go first past the limit. */
+export class GraphCache {
+  private readonly graphs = new Map<string, ProcessGraph>();
+
+  constructor(private readonly limit = 500) {}
+
+  get(versionId: string): ProcessGraph | undefined {
+    return this.graphs.get(versionId);
+  }
+
+  set(graph: ProcessGraph): void {
+    this.graphs.set(graph.versionId, graph);
+    if (this.graphs.size > this.limit) this.graphs.delete(this.graphs.keys().next().value!);
+  }
+}

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

@@ -0,0 +1,60 @@
+import type { AgentToolResult } from "../../../agent";
+import { resolveInput } from "../../../../library/workflow";
+import type { WorkflowTools } from "../../internal/WorkflowTools";
+import type { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WfJob } from "../model/WfJob.model";
+import { dataOf, type WorkflowEngine } from "./WorkflowEngine";
+
+/**
+ * One `tool` job: call the service task's Tool and apply the result. The Tool
+ * runs outside a transaction, the result is applied in a step transaction; a
+ * token closed meanwhile (a cancel) drops it. The Tool runs on behalf of who
+ * started the instance, with the token id as its idempotency key: after a crash
+ * between the call and the step the call may repeat (TOOLS-001 §7).
+ */
+export class ToolStep {
+  constructor(
+    private readonly db: RuntimeDbContext,
+    private readonly engine: WorkflowEngine,
+    private readonly tools: WorkflowTools,
+  ) {}
+
+  async run(job: WfJob, signal: AbortSignal): Promise<void> {
+    const instance = job.instanceId === null ? undefined : await this.db.instances.asNoTracking().firstOrDefault((i) => i.id.eq(job.instanceId!));
+    const token = job.tokenId === null ? undefined : await this.db.tokens.asNoTracking().firstOrDefault((t) => t.id.eq(job.tokenId!));
+    if (!instance || !token || instance.status !== "running" || token.status !== "waiting") {
+      await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeDelete();
+      return;
+    }
+    const graph = await this.engine.graphOf(instance.versionId);
+    const node = graph.document.nodes[token.nodeId];
+    const name = String(node?.config?.tool ?? "");
+    const input = resolveInput(node?.config?.input ?? {}, dataOf(instance));
+    const runner = this.tools.bound;
+    const result: AgentToolResult = runner === undefined
+      ? { callId: token.id, name, status: "error", error: { code: "TOOL_NOT_FOUND", message: `Tool ${name} is not available to processes` }, metadata: {} } as AgentToolResult
+      : await runner.run(name, input, {
+        idempotencyKey: token.id,
+        actor: { kind: instance.startedByKind, id: instance.startedById },
+        metadata: { instanceId: instance.id, partition: instance.partition, processKey: instance.processKey, nodeId: token.nodeId },
+        signal,
+      });
+
+    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);
+      if (!current || current.status !== "waiting" || step.instance.status !== "running") return;
+      this.engine.history(step, current, current.nodeId, "tool", {
+        tool: name,
+        status: result.status,
+        durationMs: result.durationMs ?? null,
+        ...(result.error ? { error: { code: result.error.code ?? null, message: result.error.message } } : {}),
+      });
+      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`);
+      }
+    });
+  }
+}