@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/execution/engine.js

@@ -1,6 +1,17 @@
+/**
+ * Bounded execution: the generic agent run loop and workflow driver.
+ *
+ * Two execution shapes share the round budget, cancellation and one diagnostic scope. A
+ * `CoreStep` loop owns its own round counter and returns an explicit continue/complete
+ * outcome; a bound workflow is traversed node by node, with routes selected after each
+ * commit. Business rules, tools and models are injected by the host — this module only
+ * enforces ordering, cancellation, budgets and reporting.
+ *
+ * Exports: `AgentCoreEngine` and the engine option/identity types.
+ */
 import { ModelCallBudget, parentModelBudget } from '../model/call-budget.js';
 import { ModelRunner } from '../model/runner.js';
-import { compiledModelBinding, modelBindingId, snapshotModelBinding } from '../model/binding.js';
+import { compiledModelBinding, modelBindingId, snapshotModelBinding, } from '../model/binding.js';
 import { getErrorInfo } from '../errors.js';
 import { invocationId } from '../utils/invocation.js';
 import { synchronous } from '../utils/synchronous.js';
@@ -13,10 +24,20 @@ import { breakWhile } from '../utils/rules.js';
 import { NodeReports } from './reporting.js';
 import { snapshotBranch } from './branch.js';
 export * from './workflow.js';
-/** Bounded execution shared by applications; business rules are registered by each host. */
+/**
+ * Bounded execution shared by applications; business rules are registered by each host.
+ *
+ * Configuration is bound before a run and may be bound only once per model, tool runtime
+ * and workflow. A run resolves its signal from the engine, the request runtime and the
+ * caller, then executes either the bound workflow or a supplied step function until the
+ * round budget, cancellation or a completion stops it.
+ */
 export class AgentCoreEngine {
+    /** Workflow catalog constructor, exposed so hosts do not import two modules. */
     static Workflow = AgentWorkflow;
+    /** Attempt budget, exposed for hosts that gate their own sub-steps. */
     static AttemptBudget = AttemptBudget;
+    /** Factory for a validated workflow definition. */
     static createWorkflow = defineWorkflow;
     maxRounds;
     exhausted;
@@ -27,26 +48,70 @@ export class AgentCoreEngine {
     models;
     selectedModelId;
     maxModelCalls;
+    /**
+     * Compile model options and reject engine-owned settings.
+     *
+     * @param options - Model binding supplied to the engine.
+     * @returns The compiled binding.
+     * @throws TypeError When the binding carries its own execution scope.
+     */
     snapshotModel(options) {
         if (options.execution || options.signal)
             throw new TypeError('Configure model execution on the Engine');
         return snapshotModelBinding(options);
     }
+    /**
+     * Bind the single model this engine will use.
+     *
+     * @param options - App model settings.
+     * @returns This engine, for chaining.
+     * @throws TypeError When a model is already bound or the settings are invalid.
+     */
     bindModel(options) {
         if (this.modelOptions || this.models || this.modelRuntime)
             throw new TypeError('Engine already has a bound model');
         return this.setModel(options);
     }
-    /** Bind an existing request lifetime once, for App services sharing this Runner's budget. */
+    /**
+     * Bind an existing request lifetime once, for App services sharing this Runner's budget.
+     *
+     * Callbacks are bound to the source runtime and the counters stay live getters, so the
+     * engine and the App observe exactly the same budget and signal.
+     *
+     * @param source - Request model runtime owned by the App.
+     * @returns This engine, for chaining.
+     * @throws Error When another model is already bound or the runtime lacks a usable signal.
+     */
     bindModelRuntime(source) {
         breakWhile(!!this.modelOptions || !!this.models || !!this.modelRuntime, 'Engine already has a bound model');
         const execution = source.execution, invoke = source.invoke, prepare = source.prepare;
-        breakWhile(typeof invoke !== 'function' || typeof prepare !== 'function' || typeof execution?.signal?.throwIfAborted !== 'function', 'Invalid request model runtime');
-        this.modelRuntime = Object.freeze({ invoke: invoke.bind(source), prepare: prepare.bind(source),
+        breakWhile(typeof invoke !== 'function' ||
+            typeof prepare !== 'function' ||
+            typeof execution?.signal?.throwIfAborted !== 'function', 'Invalid request model runtime');
+        this.modelRuntime = Object.freeze({
+            invoke: invoke.bind(source),
+            prepare: prepare.bind(source),
             execution: Object.freeze({ signal: execution.signal, diagnostics: execution.diagnostics }),
-            get remainingCalls() { return source.remainingCalls; }, get callCount() { return source.callCount; }, get totalCallCount() { return source.totalCallCount; } });
+            get remainingCalls() {
+                return source.remainingCalls;
+            },
+            get callCount() {
+                return source.callCount;
+            },
+            get totalCallCount() {
+                return source.totalCallCount;
+            },
+        });
         return this;
     }
+    /**
+     * Select a configured model, or replace the single bound model's configuration.
+     *
+     * @param options - A configured model id, or new settings for the single bound model.
+     * @returns This engine, for chaining.
+     * @throws WorkflowContractError When the id is not configured.
+     * @throws TypeError When no single model is bound to switch.
+     */
     switchModel(options) {
         if (typeof options === 'string') {
             this.requireModel(options, this.models);
@@ -57,17 +122,38 @@ export class AgentCoreEngine {
             throw new TypeError('Bind a single model before switching its configuration');
         return this.setModel(options);
     }
+    /**
+     * Look up a configured model by id.
+     *
+     * @param id - Configured model id.
+     * @param models - Configured model map, when the engine uses a catalog.
+     * @returns The compiled binding.
+     * @throws WorkflowContractError When the id is not configured.
+     */
     requireModel(id, models) {
         const options = models?.get(id);
         if (!options)
             throw new WorkflowContractError(`Unknown configured model: ${id}`);
         return options;
     }
+    /**
+     * Compile and store the single bound model.
+     *
+     * @param options - App model settings.
+     * @returns This engine, for chaining.
+     */
     setModel(options) {
         this.modelOptions = this.snapshotModel(options);
         return this;
     }
     invokeTool;
+    /**
+     * Bind the tool runtime used by workflow context.
+     *
+     * @param tools - Registry exposing `invokeAsync`, or an object exposing `invoke`.
+     * @returns This engine, for chaining.
+     * @throws TypeError When tools are already bound or expose no invoke method.
+     */
     bindToolRuntime(tools) {
         if (this.invokeTool)
             throw new TypeError('Engine already has a bound tool runtime');
@@ -85,41 +171,109 @@ export class AgentCoreEngine {
         engine.bind(workflow, app);
         return engine;
     }
+    /**
+     * Store the workflow and its dependencies.
+     *
+     * @param workflow - Workflow to execute.
+     * @param app - App dependencies handed to every node and route.
+     * @throws TypeError When a workflow is already bound.
+     */
     bind(workflow, app) {
         if (this.boundWorkflow)
             throw new TypeError('Engine already has a bound workflow');
         this.boundWorkflow = { workflow, app };
     }
+    /** The bound workflow. */
     get workflow() {
         if (!this.boundWorkflow)
             throw new TypeError('Engine has no bound workflow');
         return this.boundWorkflow.workflow;
     }
+    // A default identity is generated eagerly so checkpoints taken before a run still carry
+    // a stable branch, and a forked engine can point at the parent's ids.
     branchIdentity = Object.freeze({
-        agentId: invocationId(), branchId: invocationId(), agentVersionId: invocationId(),
+        agentId: invocationId(),
+        branchId: invocationId(),
+        agentVersionId: invocationId(),
     });
+    // Membership test for checkpoints: a checkpoint object from another engine (or a
+    // hand-built lookalike) must not be accepted as if it proved branch ownership.
     checkpoints = new WeakSet();
-    get branch() { return this.branchIdentity; }
+    /** Identity of this engine's branch. */
+    get branch() {
+        return this.branchIdentity;
+    }
+    /**
+     * Take an in-memory checkpoint of host-owned data.
+     *
+     * The data is cloned on write and on every read, so neither side can mutate the other.
+     *
+     * @param data - Serializable data to capture.
+     * @returns A checkpoint bound to this branch.
+     */
     checkpoint(data) {
         const snapshot = structuredClone(data);
-        const checkpoint = Object.freeze({ id: invocationId(), source: this.branch, read: () => structuredClone(snapshot) });
+        const checkpoint = Object.freeze({
+            id: invocationId(),
+            source: this.branch,
+            read: () => structuredClone(snapshot),
+        });
         this.checkpoints.add(checkpoint);
         return checkpoint;
     }
+    /**
+     * Export a checkpoint for host-owned persistence.
+     *
+     * @param checkpoint - Checkpoint taken by this engine.
+     * @returns A serializable record with a validated branch identity.
+     * @throws Error When the checkpoint belongs to another engine.
+     */
     exportCheckpoint(checkpoint) {
         breakWhile(!this.checkpoints.has(checkpoint), 'Checkpoint belongs to another branch');
-        return { id: checkpoint.id, source: snapshotBranch(checkpoint.source), data: checkpoint.read() };
+        return {
+            id: checkpoint.id,
+            source: snapshotBranch(checkpoint.source),
+            data: checkpoint.read(),
+        };
     }
+    /**
+     * Recreate a checkpoint from a persisted record.
+     *
+     * The record's branch must match this engine's branch exactly; otherwise persisted data
+     * from another branch would be adopted silently.
+     *
+     * @param record - Record produced by `exportCheckpoint`.
+     * @returns A checkpoint bound to this engine.
+     * @throws Error When the id is invalid or the branch identity differs.
+     */
     restoreCheckpoint(record) {
         const source = snapshotBranch(record.source);
-        breakWhile(typeof record.id !== 'string' || !record.id.trim() || record.id.length > 200
-            || JSON.stringify(source) !== JSON.stringify(snapshotBranch(this.branch)), 'Checkpoint identity does not match the restored branch');
+        breakWhile(typeof record.id !== 'string' ||
+            !record.id.trim() ||
+            record.id.length > 200 ||
+            JSON.stringify(source) !== JSON.stringify(snapshotBranch(this.branch)), 'Checkpoint identity does not match the restored branch');
         const data = structuredClone(record.data);
         const checkpoint = Object.freeze({ id: record.id, source, read: () => structuredClone(data) });
         this.checkpoints.add(checkpoint);
         return checkpoint;
     }
-    fork({ at, workflow, routes, resume }) {
+    /**
+     * Create an engine on a new branch forked at a checkpoint.
+     *
+     * The forked engine keeps the round budget, observation and configuration, receives an
+     * optional workflow extension, and gets a new branch identity whose parent ids point at
+     * this engine. Live handles are not copied: an App dependency, request runtime or tool
+     * runtime must be restored by the `resume` callback, because they cannot be serialized.
+     *
+     * @param request.at - Checkpoint taken by this engine to fork from.
+     * @param request.workflow - Optional extension or replacement workflow.
+     * @param request.routes - Route overrides; only valid with a workflow instance.
+     * @param request.resume - Receives the checkpoint data and returns restored dependencies.
+     * @returns A new engine on the forked branch.
+     * @throws TypeError When the checkpoint is foreign or the App dependency is missing.
+     * @throws Error When a bound request runtime or tool runtime was not restored.
+     */
+    fork({ at, workflow, routes, resume, }) {
         if (!this.boundWorkflow)
             throw new TypeError('Engine has no bound workflow');
         if (!this.checkpoints.has(at))
@@ -134,8 +288,12 @@ export class AgentCoreEngine {
         breakWhile(!!this.modelRuntime && !dependencies?.model, 'Fork requires a restored request model runtime');
         breakWhile(!!this.invokeTool && !dependencies?.tools, 'Fork requires a restored tool runtime');
         const engine = new AgentCoreEngine({
-            maxRounds: this.maxRounds, errors: { exhausted: this.exhausted },
-            execution: { diagnostics: this.options.execution?.diagnostics, observe: this.options.execution?.observe },
+            maxRounds: this.maxRounds,
+            errors: { exhausted: this.exhausted },
+            execution: {
+                diagnostics: this.options.execution?.diagnostics,
+                observe: this.options.execution?.observe,
+            },
         });
         engine.bind(definition, dependencies?.app);
         if (dependencies?.tools)
@@ -149,13 +307,30 @@ export class AgentCoreEngine {
             engine.maxModelCalls = this.maxModelCalls;
         }
         engine.branchIdentity = Object.freeze({
-            agentId: this.branch.agentId, branchId: engine.branch.branchId, agentVersionId: engine.branch.agentVersionId,
-            parentBranchId: this.branch.branchId, parentAgentVersionId: this.branch.agentVersionId, forkPointId: at.id,
+            agentId: this.branch.agentId,
+            branchId: engine.branch.branchId,
+            agentVersionId: engine.branch.agentVersionId,
+            parentBranchId: this.branch.branchId,
+            parentAgentVersionId: this.branch.agentVersionId,
+            forkPointId: at.id,
         });
         return engine;
     }
+    /**
+     * Build an engine and validate its wiring.
+     *
+     * Legacy top-level names (`maxSteps`, `exhausted`, `signal`, `diagnostics`,
+     * `onWorkflowEvent`, `observe`) are rejected rather than ignored, because silently
+     * dropping them would change budgets or observation.
+     *
+     * @param settings - Round budget, errors, execution scope, model, tools, workflow and branch.
+     * @throws TypeError When settings are invalid, removed names are used, or model wiring is
+     * inconsistent.
+     */
     constructor(settings = {}) {
-        if (!settings || typeof settings !== 'object' || ['maxSteps', 'exhausted', 'signal', 'diagnostics', 'onWorkflowEvent', 'observe'].some(key => key in settings)) {
+        if (!settings ||
+            typeof settings !== 'object' ||
+            ['maxSteps', 'exhausted', 'signal', 'diagnostics', 'onWorkflowEvent', 'observe'].some((key) => key in settings)) {
             throw new TypeError('Use maxRounds, execution (including observe) and errors');
         }
         const execution = settings.execution;
@@ -163,10 +338,18 @@ export class AgentCoreEngine {
             this.branchIdentity = snapshotBranch(settings.branch);
         const observer = execution?.observe;
         this.maxRounds = settings.maxRounds ?? 8;
-        this.exhausted = settings.errors?.exhausted?.bind(settings.errors) ?? (() => new BudgetError('Agent round budget exhausted'));
+        this.exhausted =
+            settings.errors?.exhausted?.bind(settings.errors) ??
+                (() => new BudgetError('Agent round budget exhausted'));
         this.options = {
-            execution: { signal: execution?.signal, diagnostics: execution?.diagnostics,
-                observe: observer && { accepts: observer.accepts?.bind(observer), event: observer.event.bind(observer) } },
+            execution: {
+                signal: execution?.signal,
+                diagnostics: execution?.diagnostics,
+                observe: observer && {
+                    accepts: observer.accepts?.bind(observer),
+                    event: observer.event.bind(observer),
+                },
+            },
         };
         breakWhile(!Number.isSafeInteger(this.maxRounds) || this.maxRounds < 1, () => new TypeError('maxRounds must be a positive safe integer'));
         if (settings.workflow)
@@ -216,12 +399,45 @@ export class AgentCoreEngine {
                 this.runtimeActive = false;
         }
     }
+    /**
+     * Resolve the lifetime of one run.
+     *
+     * All three sources are lifetime bounds only, so the strictest wins and no source can
+     * extend another.
+     *
+     * @param requestSignal - Caller-supplied signal for this run.
+     * @returns The combined signal.
+     */
     executionSignal(requestSignal) {
         return combineSignals(this.options.execution?.signal, this.modelRuntime?.execution.signal, requestSignal);
     }
+    /**
+     * Resolve the observation scope for one run.
+     *
+     * A bound request runtime contributes its scope only when the engine has none, so one
+     * fact source serves both the App and the engine.
+     *
+     * @returns Execution options with the effective diagnostic scope.
+     */
     executionOptions() {
-        return { ...this.options.execution, diagnostics: this.options.execution?.diagnostics ?? this.modelRuntime?.execution.diagnostics };
+        return {
+            ...this.options.execution,
+            diagnostics: this.options.execution?.diagnostics ?? this.modelRuntime?.execution.diagnostics,
+        };
     }
+    /**
+     * Drive a caller-supplied step function until it completes or the budget ends.
+     *
+     * Each iteration is a round: the step must return an explicit continue/complete outcome,
+     * the continue path owns the round limit, and a report scope always closes before the
+     * next round starts. Failures leave the loop and are rethrown after the scope closes.
+     *
+     * @param step - Step implementation receiving the round index and context.
+     * @param requestSignal - Caller signal for this run.
+     * @returns The value of the completing step.
+     * @throws WorkflowContractError When the step returns something other than continue/complete.
+     * @throws The configured exhausted error, the step's failure, or the signal reason.
+     */
     async runLoop(step, requestSignal) {
         const signal = this.executionSignal(requestSignal);
         const events = executionEvents(this.executionOptions());
@@ -229,7 +445,14 @@ export class AgentCoreEngine {
         // failures leave the loop and propagate after the report scope closes.
         let failure;
         for (let index = 0;; index++) {
-            const diagnostics = events?.child(invocationId(), { nodeRole: 'loop-step', definitionKind: 'loop', definitionId: 'loop', nodeId: 'step', nodeName: 'step', nodeKind: 'loop-step' });
+            const diagnostics = events?.child(invocationId(), {
+                nodeRole: 'loop-step',
+                definitionKind: 'loop',
+                definitionId: 'loop',
+                nodeId: 'step',
+                nodeName: 'step',
+                nodeKind: 'loop-step',
+            });
             const reports = new NodeReports(diagnostics, signal, 'loop.event');
             let phase = 'boundary';
             try {
@@ -237,10 +460,17 @@ export class AgentCoreEngine {
                 this.emitLoop({ type: 'enter', roundIndex: index }, diagnostics);
                 phase = 'run';
                 signal.throwIfAborted();
-                const result = await awaitWithSignal(step(index, { signal, diagnostics, report: reports.report.bind(reports), createSubFlowLogger: reports.createSubFlowLogger.bind(reports) }), signal);
+                const result = await awaitWithSignal(step(index, {
+                    signal,
+                    diagnostics,
+                    report: reports.report.bind(reports),
+                    createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
+                }), signal);
                 signal.throwIfAborted();
-                if (!result || (typeof result !== 'object' && typeof result !== 'function') || (result.type !== 'continue' && result.type !== 'complete')
-                    || (result.type === 'complete' && !('value' in result)))
+                if (!result ||
+                    (typeof result !== 'object' && typeof result !== 'function') ||
+                    (result.type !== 'continue' && result.type !== 'complete') ||
+                    (result.type === 'complete' && !('value' in result)))
                     throw new WorkflowContractError('Loop steps must return explicit continue/complete outcomes');
                 if (result.type === 'complete') {
                     const value = result.value;
@@ -265,13 +495,36 @@ export class AgentCoreEngine {
         }
         throw failure;
     }
+    /**
+     * Traverse a workflow node by node.
+     *
+     * Per visit the order is fixed: cancellation and round-budget checks, `requires`
+     * validation, the node handler, commit of `provides`, route selection, then either
+     * completion or transition. Failures are reported before any recovery decision, and only
+     * non-aborted, non-contract failures may follow `onErrorNodeId`; anything else propagates.
+     *
+     * @param workflow - Validated workflow catalog.
+     * @param state - Initial state; mutated in place by commits.
+     * @param app - Host dependencies exposed as `context.app`.
+     * @param requestSignal - Caller signal for this run.
+     * @param requestModelId - Per-run configured model override.
+     * @returns The workflow result.
+     * @throws WorkflowContractError for contract violations, or the node failure otherwise.
+     */
     async executeWorkflow(workflow, state, app, requestSignal, requestModelId) {
         const signal = this.executionSignal(requestSignal);
         const invokeTool = this.invokeTool;
         const workflowInvocationId = invocationId();
         // The execution scope also correlates content delivery when no observer or log is installed.
-        const workflowDiagnostics = (executionEvents(this.executionOptions()) ?? createEventScope()).child(workflowInvocationId, { ...this.branch, invocationId: workflowInvocationId, workflowInvocationId,
-            nodeRole: 'invocation', definitionKind: 'workflow', definitionId: workflow.id, definitionRevision: workflow.revision });
+        const workflowDiagnostics = (executionEvents(this.executionOptions()) ?? createEventScope()).child(workflowInvocationId, {
+            ...this.branch,
+            invocationId: workflowInvocationId,
+            workflowInvocationId,
+            nodeRole: 'invocation',
+            definitionKind: 'workflow',
+            definitionId: workflow.id,
+            definitionRevision: workflow.revision,
+        });
         const modelOptions = this.modelOptions;
         const models = this.models;
         const selectedModelId = requestModelId ?? this.selectedModelId;
@@ -291,8 +544,13 @@ export class AgentCoreEngine {
                 throw new WorkflowContractError('Select a configured modelId');
             let runner = runners.get(modelId);
             if (!runner) {
-                const setup = { provider: options.provider, [compiledModelBinding]: options, [modelBindingId]: modelId,
-                    [parentModelBudget]: budget, execution: { signal, diagnostics: workflowDiagnostics } };
+                const setup = {
+                    provider: options.provider,
+                    [compiledModelBinding]: options,
+                    [modelBindingId]: modelId,
+                    [parentModelBudget]: budget,
+                    execution: { signal, diagnostics: workflowDiagnostics },
+                };
                 runner = new ModelRunner(setup);
                 runners.set(modelId, runner);
             }
@@ -311,41 +569,114 @@ export class AgentCoreEngine {
                     throw this.exhausted();
             }
             catch (error) {
-                const diagnostics = workflowDiagnostics?.child(nextVisitId, { nodeRole: 'workflow-boundary', definitionKind: 'workflow', definitionId: workflow.id,
-                    definitionRevision: workflow.revision, nodeId: node.id, workflowNodeId: node.id, nodeName: node.name ?? node.id, nodeKind: 'workflow-node', nodeDescription: node.description.slice(0, 1024) });
-                this.emit({ ...this.branch, workflowId: workflow.id, workflowInvocationId, nodeId: node.id, roundIndex: round,
-                    ...diagnostics?.identity, type: 'error', phase: 'boundary', errorCode: this.errorCode(error, signal) }, diagnostics);
+                const diagnostics = workflowDiagnostics?.child(nextVisitId, {
+                    nodeRole: 'workflow-boundary',
+                    definitionKind: 'workflow',
+                    definitionId: workflow.id,
+                    definitionRevision: workflow.revision,
+                    nodeId: node.id,
+                    workflowNodeId: node.id,
+                    nodeName: node.name ?? node.id,
+                    nodeKind: 'workflow-node',
+                    nodeDescription: node.description.slice(0, 1024),
+                });
+                this.emit({
+                    ...this.branch,
+                    workflowId: workflow.id,
+                    workflowInvocationId,
+                    nodeId: node.id,
+                    roundIndex: round,
+                    ...diagnostics?.identity,
+                    type: 'error',
+                    phase: 'boundary',
+                    errorCode: this.errorCode(error, signal),
+                }, diagnostics);
                 throw error;
             }
             if (node.startsRound)
                 round = rounds++;
             const started = Date.now();
-            const nodeDiagnostics = workflowDiagnostics?.child(nextVisitId, { nodeRole: 'workflow-node', definitionKind: 'workflow', definitionId: workflow.id,
-                definitionRevision: workflow.revision, nodeId: node.id, workflowNodeId: node.id, nodeName: node.name ?? node.id, nodeKind: 'workflow-node', nodeDescription: node.description.slice(0, 1024), invocationId: undefined, stageId: undefined });
-            const event = { ...this.branch, workflowId: workflow.id, workflowInvocationId, errorEventId: failure?.errorEventId, nodeId: node.id, roundIndex: round,
-                ...(nodeDiagnostics?.identity ? { runId: nodeDiagnostics.identity.runId, spanId: nodeDiagnostics.identity.spanId, parentSpanId: nodeDiagnostics.identity.parentSpanId } : {}) };
+            const nodeDiagnostics = workflowDiagnostics?.child(nextVisitId, {
+                nodeRole: 'workflow-node',
+                definitionKind: 'workflow',
+                definitionId: workflow.id,
+                definitionRevision: workflow.revision,
+                nodeId: node.id,
+                workflowNodeId: node.id,
+                nodeName: node.name ?? node.id,
+                nodeKind: 'workflow-node',
+                nodeDescription: node.description.slice(0, 1024),
+                invocationId: undefined,
+                stageId: undefined,
+            });
+            const event = {
+                ...this.branch,
+                workflowId: workflow.id,
+                workflowInvocationId,
+                errorEventId: failure?.errorEventId,
+                nodeId: node.id,
+                roundIndex: round,
+                ...(nodeDiagnostics?.identity
+                    ? {
+                        runId: nodeDiagnostics.identity.runId,
+                        spanId: nodeDiagnostics.identity.spanId,
+                        parentSpanId: nodeDiagnostics.identity.parentSpanId,
+                    }
+                    : {}),
+            };
             function invokeModel(request) {
                 signal.throwIfAborted();
                 const owner = request.prepared && preparedOwners.get(request.prepared);
-                if (request.prepared && (!owner || (request.modelId !== undefined && request.modelId !== owner.modelId)))
+                if (request.prepared &&
+                    (!owner || (request.modelId !== undefined && request.modelId !== owner.modelId)))
                     throw new WorkflowContractError('Prepared model call belongs to another execution or model');
                 const runner = owner?.runner ?? runnerFor(request.modelId);
-                return runner.invoke({ stageId: request.stageId, maxOutputTokens: request.maxOutputTokens, transport: request.transport,
-                    prepared: request.prepared, signal: combineSignals(signal, request.signal), diagnostics: nodeDiagnostics,
-                    ...(typeof request.input === 'string' ? { input: request.input, instructions: request.instructions } : { input: request.input }) });
+                return runner.invoke({
+                    stageId: request.stageId,
+                    maxOutputTokens: request.maxOutputTokens,
+                    transport: request.transport,
+                    prepared: request.prepared,
+                    signal: combineSignals(signal, request.signal),
+                    diagnostics: nodeDiagnostics,
+                    ...(typeof request.input === 'string'
+                        ? { input: request.input, instructions: request.instructions }
+                        : { input: request.input }),
+                });
             }
             const prepareModel = ((request = {}) => {
                 signal.throwIfAborted();
                 const runner = runnerFor(request.modelId);
-                const snapshot = runner.prepare({ stageId: request.stageId, maxOutputTokens: request.maxOutputTokens, transport: request.transport });
+                const snapshot = runner.prepare({
+                    stageId: request.stageId,
+                    maxOutputTokens: request.maxOutputTokens,
+                    transport: request.transport,
+                });
                 preparedOwners.set(snapshot, { runner, modelId: request.modelId ?? selectedModelId });
                 return snapshot;
             });
             const reports = new NodeReports(nodeDiagnostics, signal);
-            const context = { report: reports.report.bind(reports), createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
-                roundIndex: round, app: app, signal, diagnostics: nodeDiagnostics,
-                model: { invoke: invokeModel, prepare: prepareModel, get remainingCalls() { return runnerFor().remainingCalls; }, get callCount() { return runnerFor().callCount; }, get totalCallCount() { return runnerFor().totalCallCount; } },
-                tools: { async invoke(request) {
+            const context = {
+                report: reports.report.bind(reports),
+                createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
+                roundIndex: round,
+                app: app,
+                signal,
+                diagnostics: nodeDiagnostics,
+                model: {
+                    invoke: invokeModel,
+                    prepare: prepareModel,
+                    get remainingCalls() {
+                        return runnerFor().remainingCalls;
+                    },
+                    get callCount() {
+                        return runnerFor().callCount;
+                    },
+                    get totalCallCount() {
+                        return runnerFor().totalCallCount;
+                    },
+                },
+                tools: {
+                    async invoke(request) {
                         const toolSignal = combineSignals(signal, request.signal);
                         toolSignal.throwIfAborted();
                         if (!invokeTool)
@@ -353,7 +684,10 @@ export class AgentCoreEngine {
                         const result = await awaitWithSignal(invokeTool({ ...request, signal: toolSignal, diagnostics: nodeDiagnostics }), toolSignal);
                         toolSignal.throwIfAborted();
                         return result;
-                    } }, ...(failure ?? {}) };
+                    },
+                },
+                ...(failure ?? {}),
+            };
             this.emit({ ...event, type: 'enter' }, nodeDiagnostics);
             let phase = 'requires';
             let selectedRoute;
@@ -369,7 +703,7 @@ export class AgentCoreEngine {
                 phase = 'provides';
                 this.commit(state, update, node.provides ?? [], signal);
                 phase = 'route';
-                const routeIndex = node.routes.findIndex(route => {
+                const routeIndex = node.routes.findIndex((route) => {
                     selectedRoute = route;
                     if (!route.when)
                         return true;
@@ -410,11 +744,29 @@ export class AgentCoreEngine {
                     if (valid !== true)
                         throw new WorkflowContractError(`Invalid workflow result: ${workflow.id}`);
                     signal.throwIfAborted();
-                    this.emit({ ...event, type: 'complete', route: routeIndex, routeId: route.id, conditionId: route.conditionId, durationMs: Date.now() - started }, nodeDiagnostics, node.report ? () => node.report(structuredClone(update), context) : undefined, reports);
+                    this.emit({
+                        ...event,
+                        type: 'complete',
+                        route: routeIndex,
+                        routeId: route.id,
+                        conditionId: route.conditionId,
+                        durationMs: Date.now() - started,
+                    }, nodeDiagnostics, node.report ? () => node.report(structuredClone(update), context) : undefined, reports);
                     return result;
                 }
                 nextVisitId = invocationId();
-                this.emit({ ...event, targetSpanId: workflowDiagnostics?.identity ? `${workflowDiagnostics.identity.spanId}/${nextVisitId}` : undefined, type: 'transition', targetNodeId: route.targetNodeId, route: routeIndex, routeId: route.id, conditionId: route.conditionId, durationMs: Date.now() - started }, nodeDiagnostics, node.report ? () => node.report(structuredClone(update), context) : undefined, reports);
+                this.emit({
+                    ...event,
+                    targetSpanId: workflowDiagnostics?.identity
+                        ? `${workflowDiagnostics.identity.spanId}/${nextVisitId}`
+                        : undefined,
+                    type: 'transition',
+                    targetNodeId: route.targetNodeId,
+                    route: routeIndex,
+                    routeId: route.id,
+                    conditionId: route.conditionId,
+                    durationMs: Date.now() - started,
+                }, nodeDiagnostics, node.report ? () => node.report(structuredClone(update), context) : undefined, reports);
                 target = route.targetNodeId;
                 failure = undefined;
             }
@@ -422,10 +774,22 @@ export class AgentCoreEngine {
                 const recoverable = !signal.aborted && !(error instanceof WorkflowContractError);
                 if (recoverable && node.onErrorNodeId !== undefined)
                     nextVisitId = invocationId();
-                const errorEvent = this.emit({ ...event, targetSpanId: recoverable && node.onErrorNodeId !== undefined && workflowDiagnostics?.identity ? `${workflowDiagnostics.identity.spanId}/${nextVisitId}` : undefined, type: 'error', targetNodeId: recoverable ? node.onErrorNodeId : undefined,
-                    routeId: recoverable ? node.onErrorRouteId : undefined, phase,
-                    failedRouteId: ['route', 'complete', 'result'].includes(phase) ? selectedRoute?.id : undefined,
-                    conditionId: phase === 'route' ? selectedRoute?.conditionId : undefined, durationMs: Date.now() - started, errorCode: this.errorCode(error, signal) }, nodeDiagnostics, undefined, reports);
+                const errorEvent = this.emit({
+                    ...event,
+                    targetSpanId: recoverable && node.onErrorNodeId !== undefined && workflowDiagnostics?.identity
+                        ? `${workflowDiagnostics.identity.spanId}/${nextVisitId}`
+                        : undefined,
+                    type: 'error',
+                    targetNodeId: recoverable ? node.onErrorNodeId : undefined,
+                    routeId: recoverable ? node.onErrorRouteId : undefined,
+                    phase,
+                    failedRouteId: ['route', 'complete', 'result'].includes(phase)
+                        ? selectedRoute?.id
+                        : undefined,
+                    conditionId: phase === 'route' ? selectedRoute?.conditionId : undefined,
+                    durationMs: Date.now() - started,
+                    errorCode: this.errorCode(error, signal),
+                }, nodeDiagnostics, undefined, reports);
                 signal.throwIfAborted();
                 if (node.onErrorNodeId === undefined || error instanceof WorkflowContractError)
                     throw error;
@@ -437,6 +801,20 @@ export class AgentCoreEngine {
             }
         }
     }
+    /**
+     * Merge a node's state update and assert its declared outputs.
+     *
+     * The update is read once, checked against `provides` on the merged view, and only then
+     * written into the state, so a missing output never leaves a half-applied update.
+     * Cancellation is checked between the check and the write.
+     *
+     * @param state - State mutated in place.
+     * @param update - Object returned by the node handler, or undefined for no change.
+     * @param provides - Fields the node promises to leave defined.
+     * @param signal - Signal checked immediately before writing.
+     * @throws WorkflowContractError When the update is not an object or a provided field is
+     * undefined.
+     */
     commit(state, update, provides, signal) {
         if (update !== undefined && (!update || typeof update !== 'object' || Array.isArray(update))) {
             throw new WorkflowContractError('Workflow handlers must return a state update object or undefined');
@@ -456,26 +834,62 @@ export class AgentCoreEngine {
                     state[key] = fields[key];
             }
     }
+    /**
+     * Publish one loop event.
+     *
+     * The report scope is closed before emission for every event type, including `enter`,
+     * so a step cannot report progress against a round that has already ended.
+     *
+     * @param event - Loop event without its id.
+     * @param diagnostics - Scope of the current round.
+     * @param reports - Report scope for the current round.
+     */
     emitLoop(event, diagnostics, reports) {
         const record = Object.freeze({ ...event, eventId: invocationId() });
         reports?.close();
         diagnostics?.emit('loop.event', () => record, reports?.debug());
     }
+    /**
+     * Publish one workflow event and attach the node's report when content is enabled.
+     *
+     * The event is always emitted, even if the report throws or is malformed; a report is
+     * optional evidence, while the event is the authoritative transition record.
+     *
+     * @param input - Event fields without its id.
+     * @param diagnostics - Scope of the current node visit.
+     * @param report - Optional report builder evaluated only when content is enabled.
+     * @param reports - Report scope closed after emission.
+     * @returns The frozen event, so callers can reference its id.
+     */
     emit(input, diagnostics, report, reports) {
         const event = Object.freeze({ ...input, eventId: invocationId() });
         let detail;
-        if (report && diagnostics?.enabled('workflow.event') && diagnostics.enabled('workflow.event', 'content')) {
+        if (report &&
+            diagnostics?.enabled('workflow.event') &&
+            diagnostics.enabled('workflow.event', 'content')) {
             try {
                 const result = synchronous(report(), 'Workflow reports must be synchronous');
                 reports?.receive(result);
                 detail = { payload: structuredClone(result.payload), subs: result.subs };
             }
-            catch { /* A report cannot suppress the workflow event. */ }
+            catch {
+                /* A report cannot suppress the workflow event. */
+            }
         }
         reports?.close();
         diagnostics?.emit('workflow.event', () => ({ event, ...(detail?.payload === undefined ? {} : { payload: detail.payload }) }), reports?.debug(detail));
         return event;
     }
+    /**
+     * Classify a failure for reporting.
+     *
+     * Cancellation takes precedence over the error itself: once the signal is aborted, the
+     * reason matters more than whatever the interrupted code threw.
+     *
+     * @param error - Failure to classify.
+     * @param signal - Execution signal at the time of failure.
+     * @returns `TIMEOUT`, `CANCELLED`, or the error's own code.
+     */
     errorCode(error, signal) {
         if (signal?.aborted)
             return isTimeoutReason(signal.reason) ? 'TIMEOUT' : 'CANCELLED';