@oni.bot/core 1.0.0 → 1.0.2

package/dist/pregel.js

@@ -3,16 +3,17 @@
 // New: interrupt() context management, HITL resume, token streaming
 // ============================================================
 import { START, END, Send, Command, } from "./types.js";
-import { RecursionLimitError, NodeNotFoundError, ONIInterrupt, NodeTimeoutError, ONIError, NodeExecutionError } from "./errors.js";
+import { RecursionLimitError, NodeNotFoundError, ONIInterrupt, NodeTimeoutError, ONIError, NodeExecutionError, CircuitBreakerOpenError } from "./errors.js";
 import { CircuitBreaker } from "./circuit-breaker.js";
 import { withRetry } from "./retry.js";
 import { NamespacedCheckpointer } from "./checkpointers/namespaced.js";
 import { _runWithContext } from "./context.js";
-import { StreamWriterImpl, _installTokenHandler, _clearTokenHandler } from "./streaming.js";
+import { StreamWriterImpl, _withTokenHandler } from "./streaming.js";
 import { NodeInterruptSignal, HITLInterruptException, HITLSessionStore, _installInterruptContext, _clearInterruptContext, } from "./hitl/index.js";
 import { EventBus } from "./events/bus.js";
 import { AuditLog } from "./guardrails/audit.js";
 import { BudgetTracker } from "./guardrails/budget.js";
+import { runFilters } from "./guardrails/filters.js";
 import { ONITracer } from "./telemetry.js";
 const DEFAULT_RECURSION_LIMIT = 25;
 export class ONIPregelRunner {
@@ -34,6 +35,8 @@ export class ONIPregelRunner {
     eventBus;
     auditLog;
     budgetTracker;
+    contentFilters;
+    toolPermissions;
     tracer;
     /** Pre-indexed edges by source node — O(1) lookup instead of O(n) filter */
     _edgesBySource;
@@ -51,6 +54,8 @@ export class ONIPregelRunner {
         this.eventBus = new EventBus(listeners);
         this.auditLog = guardrails?.audit ? new AuditLog() : null;
         this.budgetTracker = guardrails?.budget ? new BudgetTracker(guardrails.budget) : null;
+        this.contentFilters = guardrails?.filters ?? [];
+        this.toolPermissions = guardrails?.toolPermissions;
         this.tracer = new ONITracer(tracer ?? null);
         // Pre-index edges by source for O(1) lookups in getNextNodes
         this._edgesBySource = new Map();
@@ -143,6 +148,7 @@ export class ONIPregelRunner {
                 this.nodeCache.delete(cacheKey);
             }
         }
+        const _tid = config?.threadId ?? "unknown";
         const ctx = {
             config: config ?? {},
             store: this.store,
@@ -152,6 +158,16 @@ export class ONIPregelRunner {
             parentUpdates: [],
             step: step ?? 0,
             recursionLimit: recursionLimit ?? DEFAULT_RECURSION_LIMIT,
+            toolPermissions: this.toolPermissions,
+            _recordUsage: (agentName, modelId, usage) => {
+                if (!this.budgetTracker)
+                    return;
+                const entries = this.budgetTracker.record(agentName, modelId, usage);
+                for (const e of entries)
+                    this.auditLog?.record(_tid, e);
+            },
+            _emitEvent: (event) => this.eventBus.emit(event),
+            _auditRecord: (entry) => this.auditLog?.record(_tid, entry),
         };
         return _runWithContext(ctx, async () => {
             _installInterruptContext({
@@ -160,6 +176,24 @@ export class ONIPregelRunner {
                 hasResume: hasResume ?? false,
             });
             try {
+                // Content filter — input direction
+                if (this.contentFilters.length > 0) {
+                    const inputStr = JSON.stringify(state);
+                    const inputCheck = runFilters(this.contentFilters, inputStr, "input");
+                    if (!inputCheck.passed) {
+                        const threadId = config?.threadId ?? "unknown";
+                        this.eventBus.emit({ type: "filter.blocked", filter: inputCheck.blockedBy, agent: nodeDef.name, direction: "input", reason: inputCheck.reason, timestamp: Date.now() });
+                        this.auditLog?.record(threadId, { timestamp: Date.now(), agent: nodeDef.name, action: "filter.blocked", data: { filter: inputCheck.blockedBy, direction: "input", reason: inputCheck.reason } });
+                        throw new Error(`Content blocked by filter "${inputCheck.blockedBy}" on input to node "${nodeDef.name}": ${inputCheck.reason}`);
+                    }
+                    // Apply redaction if content was rewritten by a redacting filter
+                    if (inputCheck.content !== inputStr) {
+                        try {
+                            state = JSON.parse(inputCheck.content);
+                        }
+                        catch { /* leave state unchanged on parse failure */ }
+                    }
+                }
                 const run = () => Promise.resolve(nodeDef.fn(state, config));
                 // Core execute call: retry-aware
                 const executeCall = async () => {
@@ -204,12 +238,36 @@ export class ONIPregelRunner {
                     // Pass through interrupt signals (thrown by interrupt() inside nodes)
                     if (err instanceof NodeInterruptSignal)
                         throw err;
-                    // Pass through structured ONI errors (NodeExecutionError from retry, NodeTimeoutError, etc.)
-                    if (err instanceof ONIError)
-                        throw err;
-                    // Wrap raw errors and non-Error throws in NodeExecutionError
-                    const cause = err instanceof Error ? err : new Error(String(err));
-                    throw new NodeExecutionError(nodeDef.name, cause);
+                    // Circuit breaker open — invoke user fallback with real state + error
+                    if (err instanceof CircuitBreakerOpenError && nodeDef.circuitBreaker?.fallback) {
+                        result = nodeDef.circuitBreaker.fallback(state, err);
+                    }
+                    else {
+                        // Pass through structured ONI errors (NodeExecutionError from retry, NodeTimeoutError, etc.)
+                        if (err instanceof ONIError)
+                            throw err;
+                        // Wrap raw errors and non-Error throws in NodeExecutionError
+                        const cause = err instanceof Error ? err : new Error(String(err));
+                        throw new NodeExecutionError(nodeDef.name, cause);
+                    }
+                }
+                // Content filter — output direction
+                if (this.contentFilters.length > 0 && result != null) {
+                    const outputStr = JSON.stringify(result);
+                    const outputCheck = runFilters(this.contentFilters, outputStr, "output");
+                    if (!outputCheck.passed) {
+                        const threadId = config?.threadId ?? "unknown";
+                        this.eventBus.emit({ type: "filter.blocked", filter: outputCheck.blockedBy, agent: nodeDef.name, direction: "output", reason: outputCheck.reason, timestamp: Date.now() });
+                        this.auditLog?.record(threadId, { timestamp: Date.now(), agent: nodeDef.name, action: "filter.blocked", data: { filter: outputCheck.blockedBy, direction: "output", reason: outputCheck.reason } });
+                        throw new Error(`Content blocked by filter "${outputCheck.blockedBy}" on output of node "${nodeDef.name}": ${outputCheck.reason}`);
+                    }
+                    // Apply redaction if content was rewritten by a redacting filter
+                    if (outputCheck.content !== outputStr) {
+                        try {
+                            result = JSON.parse(outputCheck.content);
+                        }
+                        catch { /* leave result unchanged on parse failure */ }
+                    }
                 }
                 // Store in cache (reuse key computed above)
                 if (nodeDef.cache && cacheKey) {
@@ -253,20 +311,28 @@ export class ONIPregelRunner {
         const modeMessages = modes.has("messages");
         // Telemetry: graph-level span
         const graphSpan = this.tracer.startGraphSpan("invoke", { threadId, agentId });
-        // Load resume values from config (set by resume() call)
-        const resumeMap = config?.__resumeValues ?? {};
-        // Load or init state
-        let state;
-        let step = 0;
-        let pendingNodes = [];
-        let pendingSends = [];
-        if (this.checkpointer && config?.threadId) {
-            const cp = await this.checkpointer.get(threadId);
-            if (cp) {
-                state = this.applyUpdate(cp.state, input);
-                step = cp.step;
-                pendingNodes = cp.nextNodes;
-                pendingSends = cp.pendingSends ?? [];
+        let step = 0; // declared before try so finally can read it for setAttribute
+        try {
+            // Load resume values from config (set by resume() call)
+            const resumeMap = config?.__resumeValues ?? {};
+            // Load or init state
+            let state;
+            let pendingNodes = [];
+            let pendingSends = [];
+            if (this.checkpointer && config?.threadId) {
+                const cp = await this.checkpointer.get(threadId);
+                if (cp) {
+                    state = this.applyUpdate(cp.state, input);
+                    step = cp.step;
+                    pendingNodes = cp.nextNodes;
+                    pendingSends = cp.pendingSends ?? [];
+                }
+                else {
+                    state = this.applyUpdate(this.buildInitialState(), input);
+                    const init = this.getNextNodes(START, state, config);
+                    pendingNodes = init.nodes;
+                    pendingSends = init.sends;
+                }
             }
             else {
                 state = this.applyUpdate(this.buildInitialState(), input);
@@ -274,58 +340,278 @@ export class ONIPregelRunner {
                 pendingNodes = init.nodes;
                 pendingSends = init.sends;
             }
-        }
-        else {
-            state = this.applyUpdate(this.buildInitialState(), input);
-            const init = this.getNextNodes(START, state, config);
-            pendingNodes = init.nodes;
-            pendingSends = init.sends;
-        }
-        if (modeValues)
-            yield tag(this.evt("state_update", state, step, agentId), "values");
-        // ---- Main superstep loop ----
-        while (true) {
-            const nextNodes = [];
-            const nextSends = [];
-            state = this.resetEphemeral(state);
-            // Drain sends — group by target node for parallel fan-out execution
-            const sendGroups = new Map();
-            for (const send of pendingSends) {
-                if (!sendGroups.has(send.node))
-                    sendGroups.set(send.node, []);
-                sendGroups.get(send.node).push(send);
-                if (modeDebug)
-                    yield tag(this.evt("send", send, step, agentId, send.node), "debug");
-            }
-            // Execute fan-out sends (each Send → separate node execution with its own state)
-            if (sendGroups.size > 0) {
-                // Build promises directly — avoids spread+flatMap intermediate arrays
-                const sendPromises = [];
-                for (const [node, sends] of sendGroups) {
-                    const nodeDef = this.nodes.get(node);
+            if (modeValues)
+                yield tag(this.evt("state_update", state, step, agentId), "values");
+            // ---- Main superstep loop ----
+            while (true) {
+                const nextNodes = [];
+                const nextSends = [];
+                state = this.resetEphemeral(state);
+                // Drain sends — group by target node for parallel fan-out execution
+                const sendGroups = new Map();
+                for (const send of pendingSends) {
+                    if (!sendGroups.has(send.node))
+                        sendGroups.set(send.node, []);
+                    sendGroups.get(send.node).push(send);
+                    if (modeDebug)
+                        yield tag(this.evt("send", send, step, agentId, send.node), "debug");
+                }
+                // Execute fan-out sends (each Send → separate node execution with its own state)
+                if (sendGroups.size > 0) {
+                    // Build promises directly — avoids spread+flatMap intermediate arrays
+                    const sendPromises = [];
+                    for (const [node, sends] of sendGroups) {
+                        const nodeDef = this.nodes.get(node);
+                        if (!nodeDef)
+                            throw new NodeNotFoundError(node);
+                        for (const send of sends) {
+                            sendPromises.push((async () => {
+                                const sendState = this.applyUpdate(state, send.args);
+                                const result = await this.executeNode(nodeDef, sendState, config, undefined, undefined, undefined, step, recursionLimit);
+                                return { name: node, result };
+                            })());
+                        }
+                    }
+                    const sendResults = await Promise.all(sendPromises);
+                    // Reduce all send results through channels
+                    for (const { name, result } of sendResults) {
+                        if (result instanceof Command) {
+                            if (result.update)
+                                state = this.applyUpdate(state, result.update);
+                            const gotos = result.goto
+                                ? (Array.isArray(result.goto) ? result.goto : [result.goto])
+                                : this.getNextNodes(name, state, config).nodes;
+                            nextNodes.push(...gotos);
+                        }
+                        else if (result && typeof result === "object") {
+                            state = this.applyUpdate(state, result);
+                            const { nodes, sends } = this.getNextNodes(name, state, config);
+                            nextNodes.push(...nodes);
+                            nextSends.push(...sends);
+                        }
+                        else {
+                            const { nodes, sends } = this.getNextNodes(name, state, config);
+                            nextNodes.push(...nodes);
+                            nextSends.push(...sends);
+                        }
+                        if (modeUpdates || modeDebug) {
+                            const delta = result instanceof Command ? (result.update ?? {}) : (result ?? {});
+                            if (modeUpdates)
+                                yield tag(this.evt("node_end", delta, step, agentId, name), "updates");
+                            if (modeDebug)
+                                yield tag(this.evt("node_end", delta, step, agentId, name), "debug");
+                        }
+                    }
+                }
+                pendingSends = [];
+                // Filter executable nodes (non-END), excluding nodes already handled by sends
+                const executableNodes = pendingNodes.filter((n) => n !== END && !sendGroups.has(n));
+                if (executableNodes.length === 0 && sendGroups.size === 0)
+                    break;
+                if (step >= recursionLimit)
+                    throw new RecursionLimitError(recursionLimit);
+                // Emit debug node_start events before parallel execution
+                if (modeDebug) {
+                    for (const nodeName of executableNodes) {
+                        const name = nodeName;
+                        if (!this.nodes.has(name))
+                            throw new NodeNotFoundError(name);
+                        // Static interrupt BEFORE (check before emitting start)
+                        if (this.interruptConfig.interruptBefore?.includes(name))
+                            throw new ONIInterrupt(name, "before", state);
+                        this.checkDynamicInterrupt(name, "before", state, config);
+                        yield tag(this.evt("node_start", {}, step, agentId, name), "debug");
+                    }
+                }
+                // Execute all active nodes in parallel
+                const allCustomEvents = [];
+                const allMessageEvents = [];
+                const allSubgraphEvents = [];
+                const nodeWriters = new Map();
+                const nodeResults = await Promise.all(executableNodes.map(async (nodeName) => {
+                    const name = nodeName;
+                    const nodeDef = this.nodes.get(name);
                     if (!nodeDef)
-                        throw new NodeNotFoundError(node);
-                    for (const send of sends) {
-                        sendPromises.push((async () => {
-                            const sendState = this.applyUpdate(state, send.args);
-                            const result = await this.executeNode(nodeDef, sendState, config, undefined, undefined, undefined, step, recursionLimit);
-                            return { name: node, result };
-                        })());
+                        throw new NodeNotFoundError(name);
+                    // Static interrupt BEFORE (non-debug mode)
+                    if (!modeDebug) {
+                        if (this.interruptConfig.interruptBefore?.includes(name))
+                            throw new ONIInterrupt(name, "before", state);
+                        this.checkDynamicInterrupt(name, "before", state, config);
+                    }
+                    // Create a StreamWriter for this node
+                    const messageId = `msg-${threadId}-${step}-${name}`;
+                    const customEvents = [];
+                    const messageEvents = [];
+                    const writerImpl = new StreamWriterImpl((evt) => customEvents.push(evt), (token) => { }, (evt) => messageEvents.push(evt), name, step, messageId, agentId);
+                    nodeWriters.set(name, writerImpl);
+                    // Check if this node has a pending resume value
+                    const resumeValue = resumeMap[name];
+                    const hasResume = name in resumeMap;
+                    // Emit agent.start lifecycle event
+                    const nodeStartTime = Date.now();
+                    this.eventBus.emit({ type: "agent.start", agent: name, timestamp: nodeStartTime, step });
+                    // Telemetry: node-level span
+                    const nodeSpan = this.tracer.startNodeSpan(name, { threadId, step, agentId });
+                    let result;
+                    let subParentUpdates = [];
+                    try {
+                        // Scope emitToken to this node's async context via ALS — parallel nodes each
+                        // get their own handler so tokens are never dropped or misrouted.
+                        result = await _withTokenHandler((token) => writerImpl.token(token), async () => {
+                            if (nodeDef.subgraph) {
+                                // Mark child runner as a subgraph so Command.PARENT works
+                                const childRunner = nodeDef.subgraph._runner;
+                                if (childRunner) {
+                                    childRunner._isSubgraph = true;
+                                    childRunner._parentUpdates = [];
+                                }
+                                // Save original checkpointer before potentially overwriting
+                                const savedChildCheckpointer = childRunner ? childRunner.checkpointer : undefined;
+                                // Namespace the subgraph's checkpointer for isolation
+                                if (this.checkpointer && childRunner) {
+                                    childRunner.checkpointer = new NamespacedCheckpointer(this.checkpointer, name);
+                                }
+                                // Stream the subgraph — always restore child runner state, even on throw/interrupt
+                                let subFinalState;
+                                try {
+                                    const childStreamMode = ["debug", "values"];
+                                    for await (const evt of nodeDef.subgraph.stream(state, {
+                                        ...config,
+                                        parentRunId: config?.threadId,
+                                        streamMode: childStreamMode,
+                                    })) {
+                                        // Namespace-prefix the node name
+                                        allSubgraphEvents.push({
+                                            ...evt,
+                                            node: evt.node ? `${name}:${evt.node}` : name,
+                                        });
+                                        // Track the last state_update as the final subgraph state
+                                        if (evt.event === "state_update") {
+                                            subFinalState = evt.data;
+                                        }
+                                    }
+                                    if (childRunner) {
+                                        subParentUpdates = childRunner._parentUpdates;
+                                    }
+                                }
+                                finally {
+                                    // Restore regardless of success, throw, or interrupt
+                                    if (childRunner) {
+                                        childRunner._isSubgraph = false;
+                                        childRunner._parentUpdates = [];
+                                        childRunner.checkpointer = savedChildCheckpointer;
+                                    }
+                                }
+                                return subFinalState ?? {};
+                            }
+                            else {
+                                return this.executeNode(nodeDef, state, config, resumeValue, hasResume, writerImpl, step, recursionLimit);
+                            }
+                        });
+                    }
+                    catch (err) {
+                        // Catch interrupt() signals thrown from inside nodes
+                        if (err instanceof NodeInterruptSignal) {
+                            const iv = {
+                                value: err.value,
+                                node: name,
+                                resumeId: err.resumeId,
+                                timestamp: Date.now(),
+                            };
+                            // Save checkpoint before surfacing interrupt
+                            await this.saveCheckpoint(threadId, step, state, [name], pendingSends, agentId, config?.metadata);
+                            // Record HITL session if checkpointer exists
+                            if (this.checkpointer) {
+                                const cp = await this.checkpointer.get(threadId);
+                                if (cp)
+                                    this.hitlStore.record(threadId, iv, cp);
+                            }
+                            throw new HITLInterruptException(threadId, iv, state);
+                        }
+                        // Record to DLQ before re-throwing — use original cause if wrapped
+                        if (this.dlq && err instanceof Error) {
+                            const dlqErr = (err instanceof NodeExecutionError && err.cause instanceof Error) ? err.cause : err;
+                            this.dlq.record(threadId, name, state, dlqErr, nodeDef.retry?.maxAttempts ?? 1);
+                        }
+                        // Telemetry: record error on node span — use original cause if wrapped
+                        if (err instanceof Error) {
+                            const telErr = (err instanceof NodeExecutionError && err.cause instanceof Error) ? err.cause : err;
+                            this.tracer.recordError(nodeSpan, telErr);
+                        }
+                        this.tracer.endSpan(nodeSpan);
+                        // Lifecycle event: emit error for non-interrupt failures
+                        if (err instanceof Error) {
+                            this.eventBus.emit({ type: "error", agent: name, error: err, timestamp: Date.now() });
+                        }
+                        throw err;
+                    }
+                    // Telemetry: end node span
+                    this.tracer.endSpan(nodeSpan);
+                    // Emit agent.end lifecycle event
+                    this.eventBus.emit({ type: "agent.end", agent: name, timestamp: Date.now(), step, duration: Date.now() - nodeStartTime });
+                    // Collect events for yielding after parallel execution
+                    allCustomEvents.push(...customEvents);
+                    allMessageEvents.push(...messageEvents);
+                    return { name, result, subParentUpdates };
+                }));
+                // Yield buffered subgraph events — filtered by parent's active modes
+                for (const evt of allSubgraphEvents) {
+                    const e = evt;
+                    if (modeDebug) {
+                        yield tag(e, "debug");
+                    }
+                    else if (modeUpdates && (e.event === "node_end")) {
+                        yield tag(e, "updates");
+                    }
+                    else if (modeValues && e.event === "state_update") {
+                        yield tag(e, "values");
+                    }
+                    // Custom and message events from subgraphs are forwarded if those modes are active
+                    if (modeCustom && e.event === "custom") {
+                        yield tag(e, "custom");
+                    }
+                    if (modeMessages && (e.event === "messages" || e.event === "messages/complete")) {
+                        yield tag(e, "messages");
                     }
                 }
-                const sendResults = await Promise.all(sendPromises);
-                // Reduce all send results through channels
-                for (const { name, result } of sendResults) {
+                // Apply results
+                const stepWrites = [];
+                for (const { name, result, subParentUpdates: parentUpdates } of nodeResults) {
                     if (result instanceof Command) {
-                        if (result.update)
-                            state = this.applyUpdate(state, result.update);
-                        const gotos = result.goto
-                            ? (Array.isArray(result.goto) ? result.goto : [result.goto])
-                            : this.getNextNodes(name, state, config).nodes;
-                        nextNodes.push(...gotos);
+                        if (result.graph === Command.PARENT) {
+                            // Push update to parent — do NOT apply locally
+                            if (!this._isSubgraph) {
+                                throw new Error("Command.PARENT used but graph is not running as a subgraph");
+                            }
+                            if (result.update)
+                                this._parentUpdates.push(result.update);
+                            // Still resolve next nodes normally
+                            const { nodes, sends } = this.getNextNodes(name, state, config);
+                            nextNodes.push(...nodes);
+                            nextSends.push(...sends);
+                        }
+                        else {
+                            if (result.update) {
+                                state = this.applyUpdate(state, result.update);
+                                if (Object.keys(result.update).length > 0) {
+                                    stepWrites.push({ nodeId: name, writes: result.update });
+                                }
+                            }
+                            const gotos = result.goto
+                                ? (Array.isArray(result.goto) ? result.goto : [result.goto])
+                                : this.getNextNodes(name, state, config).nodes;
+                            nextNodes.push(...gotos);
+                            if (result.send)
+                                nextSends.push(...result.send.map((s) => ({ node: s.node, args: s.args })));
+                        }
                     }
                     else if (result && typeof result === "object") {
                         state = this.applyUpdate(state, result);
+                        const writes = result;
+                        if (Object.keys(writes).length > 0) {
+                            stepWrites.push({ nodeId: name, writes });
+                        }
                         const { nodes, sends } = this.getNextNodes(name, state, config);
                         nextNodes.push(...nodes);
                         nextSends.push(...sends);
@@ -335,6 +621,10 @@ export class ONIPregelRunner {
                         nextNodes.push(...nodes);
                         nextSends.push(...sends);
                     }
+                    // Apply parent updates from subgraph Command.PARENT (after normal result)
+                    for (const pu of parentUpdates) {
+                        state = this.applyUpdate(state, pu);
+                    }
                     if (modeUpdates || modeDebug) {
                         const delta = result instanceof Command ? (result.update ?? {}) : (result ?? {});
                         if (modeUpdates)
@@ -342,286 +632,69 @@ export class ONIPregelRunner {
                         if (modeDebug)
                             yield tag(this.evt("node_end", delta, step, agentId, name), "debug");
                     }
-                }
-            }
-            pendingSends = [];
-            // Filter executable nodes (non-END), excluding nodes already handled by sends
-            const executableNodes = pendingNodes.filter((n) => n !== END && !sendGroups.has(n));
-            if (executableNodes.length === 0 && sendGroups.size === 0)
-                break;
-            if (step >= recursionLimit)
-                throw new RecursionLimitError(recursionLimit);
-            // Emit debug node_start events before parallel execution
-            if (modeDebug) {
-                for (const nodeName of executableNodes) {
-                    const name = nodeName;
-                    if (!this.nodes.has(name))
-                        throw new NodeNotFoundError(name);
-                    // Static interrupt BEFORE (check before emitting start)
-                    if (this.interruptConfig.interruptBefore?.includes(name))
-                        throw new ONIInterrupt(name, "before", state);
-                    this.checkDynamicInterrupt(name, "before", state, config);
-                    yield tag(this.evt("node_start", {}, step, agentId, name), "debug");
-                }
-            }
-            // Execute all active nodes in parallel
-            const allCustomEvents = [];
-            const allMessageEvents = [];
-            const allSubgraphEvents = [];
-            const nodeWriters = new Map();
-            const nodeResults = await Promise.all(executableNodes.map(async (nodeName) => {
-                const name = nodeName;
-                const nodeDef = this.nodes.get(name);
-                if (!nodeDef)
-                    throw new NodeNotFoundError(name);
-                // Static interrupt BEFORE (non-debug mode)
-                if (!modeDebug) {
-                    if (this.interruptConfig.interruptBefore?.includes(name))
-                        throw new ONIInterrupt(name, "before", state);
-                    this.checkDynamicInterrupt(name, "before", state, config);
-                }
-                // Create a StreamWriter for this node
-                const messageId = `msg-${threadId}-${step}-${name}`;
-                const customEvents = [];
-                const messageEvents = [];
-                const writerImpl = new StreamWriterImpl((evt) => customEvents.push(evt), (token) => { }, (evt) => messageEvents.push(evt), name, step, messageId, agentId);
-                nodeWriters.set(name, writerImpl);
-                // Install global emitToken handler so emitToken() routes to this node's writer
-                _installTokenHandler((token) => writerImpl.token(token));
-                // Check if this node has a pending resume value
-                const resumeValue = resumeMap[name];
-                const hasResume = name in resumeMap;
-                // Emit agent.start lifecycle event
-                const nodeStartTime = Date.now();
-                this.eventBus.emit({ type: "agent.start", agent: name, timestamp: nodeStartTime, step });
-                // Telemetry: node-level span
-                const nodeSpan = this.tracer.startNodeSpan(name, { threadId, step, agentId });
-                let result;
-                let subParentUpdates = [];
-                try {
-                    if (nodeDef.subgraph) {
-                        // Mark child runner as a subgraph so Command.PARENT works
-                        const childRunner = nodeDef.subgraph._runner;
-                        if (childRunner) {
-                            childRunner._isSubgraph = true;
-                            childRunner._parentUpdates = [];
-                        }
-                        // Namespace the subgraph's checkpointer for isolation
-                        if (this.checkpointer && childRunner) {
-                            childRunner.checkpointer = new NamespacedCheckpointer(this.checkpointer, name);
-                        }
-                        // Stream the subgraph instead of invoke — buffer events for yielding after Promise.all
-                        // Use debug+values so we capture ALL event types AND state_update for final state
-                        let subFinalState;
-                        const childStreamMode = ["debug", "values"];
-                        for await (const evt of nodeDef.subgraph.stream(state, {
-                            ...config,
-                            parentRunId: config?.threadId,
-                            streamMode: childStreamMode,
-                        })) {
-                            // Namespace-prefix the node name
-                            allSubgraphEvents.push({
-                                ...evt,
-                                node: evt.node ? `${name}:${evt.node}` : name,
-                            });
-                            // Track the last state_update as the final subgraph state
-                            if (evt.event === "state_update") {
-                                subFinalState = evt.data;
-                            }
-                        }
-                        // Collect parent updates from child
-                        if (childRunner) {
-                            subParentUpdates = childRunner._parentUpdates;
-                            childRunner._isSubgraph = false;
-                            childRunner._parentUpdates = [];
-                        }
-                        result = subFinalState ?? {};
-                    }
-                    else {
-                        result = await this.executeNode(nodeDef, state, config, resumeValue, hasResume, writerImpl, step, recursionLimit);
+                    // Static interrupt AFTER
+                    if (this.interruptConfig.interruptAfter?.includes(name)) {
+                        await this.saveCheckpoint(threadId, step, state, nextNodes, nextSends, agentId, config?.metadata);
+                        throw new ONIInterrupt(name, "after", state);
                     }
+                    this.checkDynamicInterrupt(name, "after", state, config);
                 }
-                catch (err) {
-                    // Catch interrupt() signals thrown from inside nodes
-                    if (err instanceof NodeInterruptSignal) {
-                        const iv = {
-                            value: err.value,
-                            node: name,
-                            resumeId: err.resumeId,
-                            timestamp: Date.now(),
-                        };
-                        // Save checkpoint before surfacing interrupt
-                        await this.saveCheckpoint(threadId, step, state, [name], pendingSends, agentId, config?.metadata);
-                        // Record HITL session if checkpointer exists
-                        if (this.checkpointer) {
-                            const cp = await this.checkpointer.get(threadId);
-                            if (cp)
-                                this.hitlStore.record(threadId, iv, cp);
-                        }
-                        throw new HITLInterruptException(threadId, iv, state);
-                    }
-                    // Record to DLQ before re-throwing — use original cause if wrapped
-                    if (this.dlq && err instanceof Error) {
-                        const dlqErr = (err instanceof NodeExecutionError && err.cause instanceof Error) ? err.cause : err;
-                        this.dlq.record(threadId, name, state, dlqErr, nodeDef.retry?.maxAttempts ?? 1);
-                    }
-                    // Telemetry: record error on node span — use original cause if wrapped
-                    if (err instanceof Error) {
-                        const telErr = (err instanceof NodeExecutionError && err.cause instanceof Error) ? err.cause : err;
-                        this.tracer.recordError(nodeSpan, telErr);
+                // Yield buffered custom/message events based on stream mode
+                if (modeCustom || modeDebug) {
+                    for (const evt of allCustomEvents) {
+                        if (modeCustom)
+                            yield tag(evt, "custom");
+                        if (modeDebug)
+                            yield tag(evt, "debug");
                     }
-                    this.tracer.endSpan(nodeSpan);
-                    _clearTokenHandler();
-                    throw err;
-                }
-                // Clear emitToken handler after node completes
-                _clearTokenHandler();
-                // Telemetry: end node span
-                this.tracer.endSpan(nodeSpan);
-                // Emit agent.end lifecycle event
-                this.eventBus.emit({ type: "agent.end", agent: name, timestamp: Date.now(), step, duration: Date.now() - nodeStartTime });
-                // Collect events for yielding after parallel execution
-                allCustomEvents.push(...customEvents);
-                allMessageEvents.push(...messageEvents);
-                return { name, result, subParentUpdates };
-            }));
-            // Yield buffered subgraph events — filtered by parent's active modes
-            for (const evt of allSubgraphEvents) {
-                const e = evt;
-                if (modeDebug) {
-                    yield tag(e, "debug");
-                }
-                else if (modeUpdates && (e.event === "node_end")) {
-                    yield tag(e, "updates");
                 }
-                else if (modeValues && e.event === "state_update") {
-                    yield tag(e, "values");
-                }
-                // Custom and message events from subgraphs are forwarded if those modes are active
-                if (modeCustom && e.event === "custom") {
-                    yield tag(e, "custom");
-                }
-                if (modeMessages && (e.event === "messages" || e.event === "messages/complete")) {
-                    yield tag(e, "messages");
-                }
-            }
-            // Apply results
-            const stepWrites = [];
-            for (const { name, result, subParentUpdates: parentUpdates } of nodeResults) {
-                if (result instanceof Command) {
-                    if (result.graph === Command.PARENT) {
-                        // Push update to parent — do NOT apply locally
-                        if (!this._isSubgraph) {
-                            throw new Error("Command.PARENT used but graph is not running as a subgraph");
-                        }
-                        if (result.update)
-                            this._parentUpdates.push(result.update);
-                        // Still resolve next nodes normally
-                        const { nodes, sends } = this.getNextNodes(name, state, config);
-                        nextNodes.push(...nodes);
-                        nextSends.push(...sends);
+                if (modeMessages || modeDebug) {
+                    for (const evt of allMessageEvents) {
+                        if (modeMessages)
+                            yield tag(evt, "messages");
+                        if (modeDebug)
+                            yield tag(evt, "debug");
                     }
-                    else {
-                        if (result.update) {
-                            state = this.applyUpdate(state, result.update);
-                            if (Object.keys(result.update).length > 0) {
-                                stepWrites.push({ nodeId: name, writes: result.update });
-                            }
+                    // Emit messages/complete for each node that produced tokens
+                    for (const [, writer] of nodeWriters) {
+                        const complete = writer._complete();
+                        if (complete) {
+                            if (modeMessages)
+                                yield tag(complete, "messages");
+                            if (modeDebug)
+                                yield tag(complete, "debug");
                         }
-                        const gotos = result.goto
-                            ? (Array.isArray(result.goto) ? result.goto : [result.goto])
-                            : this.getNextNodes(name, state, config).nodes;
-                        nextNodes.push(...gotos);
-                        if (result.send)
-                            nextSends.push(...result.send.map((s) => ({ node: s.node, args: s.args })));
                     }
                 }
-                else if (result && typeof result === "object") {
-                    state = this.applyUpdate(state, result);
-                    const writes = result;
-                    if (Object.keys(writes).length > 0) {
-                        stepWrites.push({ nodeId: name, writes });
-                    }
-                    const { nodes, sends } = this.getNextNodes(name, state, config);
-                    nextNodes.push(...nodes);
-                    nextSends.push(...sends);
+                if (modeValues)
+                    yield tag(this.evt("state_update", state, step, agentId), "values");
+                // Deduplicate nextNodes — avoid Set+spread when no dupes (common case)
+                if (nextNodes.length <= 1) {
+                    pendingNodes = nextNodes;
                 }
                 else {
-                    const { nodes, sends } = this.getNextNodes(name, state, config);
-                    nextNodes.push(...nodes);
-                    nextSends.push(...sends);
-                }
-                // Apply parent updates from subgraph Command.PARENT (after normal result)
-                for (const pu of parentUpdates) {
-                    state = this.applyUpdate(state, pu);
-                }
-                if (modeUpdates || modeDebug) {
-                    const delta = result instanceof Command ? (result.update ?? {}) : (result ?? {});
-                    if (modeUpdates)
-                        yield tag(this.evt("node_end", delta, step, agentId, name), "updates");
-                    if (modeDebug)
-                        yield tag(this.evt("node_end", delta, step, agentId, name), "debug");
-                }
-                // Static interrupt AFTER
-                if (this.interruptConfig.interruptAfter?.includes(name)) {
-                    await this.saveCheckpoint(threadId, step, state, nextNodes, nextSends, agentId, config?.metadata);
-                    throw new ONIInterrupt(name, "after", state);
-                }
-                this.checkDynamicInterrupt(name, "after", state, config);
-            }
-            // Yield buffered custom/message events based on stream mode
-            if (modeCustom || modeDebug) {
-                for (const evt of allCustomEvents) {
-                    if (modeCustom)
-                        yield tag(evt, "custom");
-                    if (modeDebug)
-                        yield tag(evt, "debug");
-                }
-            }
-            if (modeMessages || modeDebug) {
-                for (const evt of allMessageEvents) {
-                    if (modeMessages)
-                        yield tag(evt, "messages");
-                    if (modeDebug)
-                        yield tag(evt, "debug");
-                }
-                // Emit messages/complete for each node that produced tokens
-                for (const [, writer] of nodeWriters) {
-                    const complete = writer._complete();
-                    if (complete) {
-                        if (modeMessages)
-                            yield tag(complete, "messages");
-                        if (modeDebug)
-                            yield tag(complete, "debug");
+                    const seen = new Set();
+                    pendingNodes = [];
+                    for (const n of nextNodes) {
+                        const key = n;
+                        if (!seen.has(key)) {
+                            seen.add(key);
+                            pendingNodes.push(n);
+                        }
                     }
                 }
+                pendingSends = nextSends;
+                step++;
+                await this.saveCheckpoint(threadId, step, state, pendingNodes, pendingSends, agentId, config?.metadata, stepWrites);
             }
             if (modeValues)
                 yield tag(this.evt("state_update", state, step, agentId), "values");
-            // Deduplicate nextNodes — avoid Set+spread when no dupes (common case)
-            if (nextNodes.length <= 1) {
-                pendingNodes = nextNodes;
-            }
-            else {
-                const seen = new Set();
-                pendingNodes = [];
-                for (const n of nextNodes) {
-                    const key = n;
-                    if (!seen.has(key)) {
-                        seen.add(key);
-                        pendingNodes.push(n);
-                    }
-                }
-            }
-            pendingSends = nextSends;
-            step++;
-            await this.saveCheckpoint(threadId, step, state, pendingNodes, pendingSends, agentId, config?.metadata, stepWrites);
         }
-        if (modeValues)
-            yield tag(this.evt("state_update", state, step, agentId), "values");
-        // Telemetry: end graph span
-        graphSpan.setAttribute("oni.steps", step);
-        this.tracer.endSpan(graphSpan);
+        finally {
+            // Telemetry: end graph span — always runs, even on error or interrupt
+            graphSpan.setAttribute("oni.steps", step);
+            this.tracer.endSpan(graphSpan);
+        }
     }
     // ----------------------------------------------------------------
     // Public API
@@ -699,9 +772,6 @@ export class ONIPregelRunner {
             cb = new CircuitBreaker({
                 threshold: nodeDef.circuitBreaker.threshold,
                 resetAfter: nodeDef.circuitBreaker.resetAfter,
-                fallback: nodeDef.circuitBreaker.fallback
-                    ? () => nodeDef.circuitBreaker.fallback(undefined, undefined)
-                    : undefined,
             }, nodeDef.name);
             this.circuitBreakers.set(nodeDef.name, cb);
         }
@@ -716,13 +786,17 @@ export class ONIPregelRunner {
         if (!this.checkpointer)
             return;
         const cpSpan = this.tracer.startCheckpointSpan("put", { threadId });
-        await this.checkpointer.put({
-            threadId, step, state, agentId, metadata, pendingWrites,
-            nextNodes: nextNodes.map(String),
-            pendingSends: pendingSends,
-            timestamp: Date.now(),
-        });
-        this.tracer.endSpan(cpSpan);
+        try {
+            await this.checkpointer.put({
+                threadId, step, state, agentId, metadata, pendingWrites,
+                nextNodes: nextNodes.map(String),
+                pendingSends: pendingSends,
+                timestamp: Date.now(),
+            });
+        }
+        finally {
+            this.tracer.endSpan(cpSpan);
+        }
     }
     evt(event, data, step, agentId, node) {
         return { event, data, step, timestamp: Date.now(), agentId, node };