@deepstrike/sdk 0.2.22 → 0.2.24

package/dist/runtime/runner.js

@@ -11,10 +11,11 @@ import { defaultSubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 import { extractJsonValue, schemaInstruction, schemaRetryInstruction, validateAgainstSchema, } from "./output-schema.js";
 import { resolveReducer } from "./reducers.js";
 import { loopInstruction, classifyInstruction, judgeGoal, extractLoopContinue, extractClassifyBranch, extractJudgeWinner, } from "./workflow-control-flow.js";
-import { governancePolicyToKernelEvent } from "../governance.js";
+import { governancePolicyToKernelEvent, governanceFilterSchema } from "../governance.js";
 import { kernelObservationToSessionEvent, withCategory } from "./kernel-event-log.js";
 import { assertNativeProfile } from "./os-profile.js";
 import { LargeResultSpool } from "./large-result-spool.js";
+import { formatToolError } from "../tools/errors.js";
 export class RuntimeRunner {
     opts;
     interrupted = false;
@@ -381,7 +382,7 @@ export class RuntimeRunner {
             return ok(reducer(inputs), "completed");
         }
         catch (err) {
-            return ok(`reducer "${node.reducer}" threw: ${err instanceof Error ? err.message : String(err)}`, "error");
+            return ok(`reducer "${node.reducer}" threw: ${formatToolError(err)}`, "error");
         }
     }
     /**
@@ -973,6 +974,26 @@ export class RuntimeRunner {
                 message: attachmentsToKernelMessage(attachments),
             });
         }
+        // I4: pre-fetch memory into the knowledge partition before the first LLM turn. Skipped on
+        // resumes (memory was already on the prior context) and when dreamStore/agentId is absent.
+        if (!resumeMidRun && this.opts.preQueryMemory && this.opts.dreamStore && this.opts.agentId) {
+            try {
+                const queries = await this.opts.preQueryMemory({ goal, runSpec: this.opts.runSpec });
+                const entries = [];
+                for (const q of queries ?? []) {
+                    if (typeof q !== "string" || !q.trim())
+                        continue;
+                    const hits = await this.opts.dreamStore.search(this.opts.agentId, q, 5);
+                    for (const hit of hits) {
+                        entries.push({ content: `[memory score=${hit.score.toFixed(3)}] ${hit.text}`, source: "memory" });
+                    }
+                }
+                if (entries.length > 0) {
+                    kernelApply(runtime, this.pendingObservations, { kind: "page_in", entries });
+                }
+            }
+            catch { /* errs-open — a faulty pre-fetch never breaks the run */ }
+        }
         let action = resumeMidRun
             ? kernelAction(runtime, this.pendingObservations, { kind: "resume" })
             : kernelAction(runtime, this.pendingObservations, startPayload);
@@ -980,369 +1001,440 @@ export class RuntimeRunner {
         // P0-C: the skill loaded and in effect going into the current turn (updated when the model's
         // `skill` tool call resolves). Drives the per-turn `activeSkill` metric → dwell measurement.
         let activeSkill;
-        while (!runtime.isTerminal()) {
-            // Page-in must run before appendObservations drains pending kernel observations.
-            if (action.kind === "execute_tool") {
-                await this.applyKernelPageIn(runtime, sessionId);
-            }
-            nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);
-            this.nextArchiveStart = nextCompressedArchiveStart;
-            if (this.interrupted) {
-                action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
-                break;
-            }
-            if (this.opts.signalSource) {
-                const sig = await this.opts.signalSource.nextSignal();
-                if (sig) {
-                    // Kernel-routed: the kernel decides disposition (dedup/queue/interrupt) and emits
-                    // `signal_disposed`. An actionable disposition yields a new action to adopt; queued/observed/
-                    // ignored yields none (kernel buffers).
-                    const sigAction = kernelMaybeAction(runtime, this.pendingObservations, signalToKernelEvent(sig));
-                    if (sigAction)
-                        action = sigAction;
+        // I0b: wrap the main loop so any uncaught kernel exception (typically a NAPI
+        // Status::InvalidArg from a malformed input — e.g. RuntimeSignal.source with a wrong shape,
+        // or an unrecognized event kind) is observable rather than silently propagating out of the
+        // async generator. Without this wrap the runner emits no `run_terminal` event, so downstream
+        // observability (session log, bench mechanism hooks) can't distinguish "the kernel rejected
+        // an input" from "the run is still in progress."
+        try {
+            while (!runtime.isTerminal()) {
+                // Page-in must run before appendObservations drains pending kernel observations.
+                if (action.kind === "execute_tool") {
+                    await this.applyKernelPageIn(runtime, sessionId);
                 }
-            }
-            if (runtime.isTerminal())
-                break;
-            if (action.kind === "call_provider") {
-                // M5 v2.1: top-level auto-pivot at the safe point. If the agent authored sub-workflow(s) via
-                // `start_workflow`, drive each in THIS kernel now (the kernel is in Reason / `call_provider`,
-                // NOT suspended — driving mid-suspend would clobber the single-slot suspend state), inject the
-                // outcome into context, and re-render. Loop-top placement (vs only after `tool_results`) catches
-                // EVERY path to `call_provider` — including resuming after an approval gate — so a queued spec
-                // is never stranded. Drains the queue; fires once per authored batch.
-                if (this.pendingAuthoredWorkflows.length > 0) {
-                    action = await this.driveAuthoredWorkflows(runtime, action);
+                nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);
+                this.nextArchiveStart = nextCompressedArchiveStart;
+                if (this.interrupted) {
+                    action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
+                    break;
                 }
-                const finalToolCalls = [];
-                let finalText = "";
-                const context = action.context;
-                const tools = action.tools;
-                let turnTokens = 0;
-                let turnInputTokens = 0;
-                let turnOutputTokens = 0;
-                let turnCacheReadTokens = 0;
-                let turnCacheCreationTokens = 0;
-                let shouldRetry = false;
-                const abortSignal = this.abortController?.signal;
-                try {
-                    for await (const evt of this.opts.provider.stream(context, tools, Object.keys(ext).length ? ext : undefined, providerState, abortSignal)) {
-                        // #2-B-ii: a preempting `interrupt()` fires `abortController` — stop consuming the live
-                        // stream immediately (providers that forward `signal` also abort the socket; the rest at
-                        // least stop here at the next event). The loop-top `interrupted` check then ends the run.
-                        if (abortSignal?.aborted)
-                            break;
-                        if (evt.type === "usage") {
-                            const usageEvt = evt;
-                            turnTokens = usageEvt.totalTokens;
-                            turnInputTokens = usageEvt.inputTokens ?? 0;
-                            turnOutputTokens = usageEvt.outputTokens ?? 0;
-                            // P0-C: capture the prompt-cache split for the tool-gating hit-rate baseline.
-                            turnCacheReadTokens = usageEvt.cacheReadInputTokens ?? 0;
-                            turnCacheCreationTokens = usageEvt.cacheCreationInputTokens ?? 0;
-                            continue;
-                        }
-                        yield evt;
-                        if (evt.type === "text_delta")
-                            finalText += evt.delta;
-                        else if (evt.type === "tool_call") {
-                            const tc = evt;
-                            finalToolCalls.push({ id: tc.id, name: tc.name, arguments: JSON.stringify(tc.arguments) });
-                        }
+                if (this.opts.signalSource) {
+                    const sig = await this.opts.signalSource.nextSignal();
+                    if (sig) {
+                        // Kernel-routed: the kernel decides disposition (dedup/queue/interrupt) and emits
+                        // `signal_disposed`. An actionable disposition yields a new action to adopt; queued/observed/
+                        // ignored yields none (kernel buffers).
+                        const sigAction = kernelMaybeAction(runtime, this.pendingObservations, signalToKernelEvent(sig));
+                        if (sigAction)
+                            action = sigAction;
+                        // I0a: a Critical-urgency signal carries user_abort intent. The kernel disposes it as
+                        // InterruptNow (forces a Reason turn) but does NOT call abortController.abort() unless
+                        // sub-agents are suspended — so the no-sub-agent path (e.g. the signal-injection bench
+                        // scenario) wouldn't otherwise set `this.interrupted`, and the eventual run_terminal would
+                        // report `reason: "error"` indistinguishable from a crash. Mark it here so the final
+                        // classification in the run_terminal emit picks `user_abort`.
+                        if (sig.urgency === "critical")
+                            this.interrupted = true;
                     }
                 }
-                catch (err) {
-                    // #2-B-ii: an aborted in-flight request surfaces as an AbortError — treat it as an interrupt
-                    // (the loop-top `interrupted` check converts it to a clean `timeout`/UserAbort), not a crash.
-                    if (abortSignal?.aborted) {
-                        this.interrupted = true;
+                if (runtime.isTerminal())
+                    break;
+                if (action.kind === "call_provider") {
+                    // M5 v2.1: top-level auto-pivot at the safe point. If the agent authored sub-workflow(s) via
+                    // `start_workflow`, drive each in THIS kernel now (the kernel is in Reason / `call_provider`,
+                    // NOT suspended — driving mid-suspend would clobber the single-slot suspend state), inject the
+                    // outcome into context, and re-render. Loop-top placement (vs only after `tool_results`) catches
+                    // EVERY path to `call_provider` — including resuming after an approval gate — so a queued spec
+                    // is never stranded. Drains the queue; fires once per authored batch.
+                    if (this.pendingAuthoredWorkflows.length > 0) {
+                        action = await this.driveAuthoredWorkflows(runtime, action);
                     }
-                    const errMsg = String(err).toLowerCase();
-                    if ((errMsg.includes("413") || errMsg.includes("too long") || errMsg.includes("context length exceeded") || errMsg.includes("context_length_exceeded")) &&
-                        !hasAttemptedReactiveCompact) {
-                        hasAttemptedReactiveCompact = true;
-                        if (forceCompact(runtime, this.pendingObservations)) {
-                            nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);
-                            shouldRetry = true;
+                    const finalToolCalls = [];
+                    let finalText = "";
+                    // I5: governance schema-level pre-filter. When a declarative GovernancePolicy is loaded
+                    // and `surfaceDeniedInSystem !== false`, drop denied tools from the schema BEFORE the
+                    // model sees them — the model can't plan a call it doesn't know about, so the rollback
+                    // overhead disappears. The list of denied names is appended to systemKnowledge so the
+                    // model knows not to plan around them.
+                    let context = action.context;
+                    let tools = action.tools;
+                    if (this.opts.governancePolicy && this.opts.governancePolicy.surfaceDeniedInSystem !== false) {
+                        const { allowed, denied } = governanceFilterSchema(tools, this.opts.governancePolicy);
+                        if (denied.length > 0) {
+                            tools = allowed;
+                            const note = `[governance] the following tools are denied for this run and will fail if called: ${denied.join(", ")}.`;
+                            context = {
+                                ...context,
+                                systemKnowledge: context.systemKnowledge
+                                    ? `${context.systemKnowledge}\n\n${note}`
+                                    : note,
+                            };
                         }
                     }
-                    if (!shouldRetry) {
-                        yield { type: "error", message: String(err) };
+                    let turnTokens = 0;
+                    let turnInputTokens = 0;
+                    let turnOutputTokens = 0;
+                    let turnCacheReadTokens = 0;
+                    let turnCacheCreationTokens = 0;
+                    let turnCacheReadBySlot;
+                    let shouldRetry = false;
+                    const abortSignal = this.abortController?.signal;
+                    try {
+                        for await (const evt of this.opts.provider.stream(context, tools, Object.keys(ext).length ? ext : undefined, providerState, abortSignal)) {
+                            // #2-B-ii: a preempting `interrupt()` fires `abortController` — stop consuming the live
+                            // stream immediately (providers that forward `signal` also abort the socket; the rest at
+                            // least stop here at the next event). The loop-top `interrupted` check then ends the run.
+                            if (abortSignal?.aborted)
+                                break;
+                            if (evt.type === "usage") {
+                                const usageEvt = evt;
+                                turnTokens = usageEvt.totalTokens;
+                                turnInputTokens = usageEvt.inputTokens ?? 0;
+                                turnOutputTokens = usageEvt.outputTokens ?? 0;
+                                // P0-C: capture the prompt-cache split for the tool-gating hit-rate baseline.
+                                turnCacheReadTokens = usageEvt.cacheReadInputTokens ?? 0;
+                                turnCacheCreationTokens = usageEvt.cacheCreationInputTokens ?? 0;
+                                // I1: per-slot attribution forwarded into TurnMetrics. Undefined when the provider
+                                // doesn't honor cache_control (OpenAI-family auto-cache).
+                                turnCacheReadBySlot = usageEvt.cacheReadInputTokensBySlot;
+                                continue;
+                            }
+                            yield evt;
+                            if (evt.type === "text_delta")
+                                finalText += evt.delta;
+                            else if (evt.type === "tool_call") {
+                                const tc = evt;
+                                finalToolCalls.push({ id: tc.id, name: tc.name, arguments: JSON.stringify(tc.arguments) });
+                            }
+                        }
+                    }
+                    catch (err) {
+                        // #2-B-ii: an aborted in-flight request surfaces as an AbortError — treat it as an interrupt
+                        // (the loop-top `interrupted` check converts it to a clean `timeout`/UserAbort), not a crash.
+                        if (abortSignal?.aborted) {
+                            this.interrupted = true;
+                        }
+                        const errMsg = formatToolError(err).toLowerCase();
+                        if ((errMsg.includes("413") || errMsg.includes("too long") || errMsg.includes("context length exceeded") || errMsg.includes("context_length_exceeded")) &&
+                            !hasAttemptedReactiveCompact) {
+                            hasAttemptedReactiveCompact = true;
+                            if (forceCompact(runtime, this.pendingObservations)) {
+                                nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);
+                                shouldRetry = true;
+                            }
+                        }
+                        if (!shouldRetry) {
+                            yield { type: "error", message: formatToolError(err) };
+                            action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
+                            break;
+                        }
+                    }
+                    // #2-B-ii: stream aborted (preempt/interrupt) via the break path (provider yielded no error) —
+                    // end the turn now with a timeout so the kernel terminates the run, rather than feeding the
+                    // partial assistant output as a normal turn.
+                    if (abortSignal?.aborted) {
                         action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
                         break;
                     }
-                }
-                // #2-B-ii: stream aborted (preempt/interrupt) via the break path (provider yielded no error) —
-                // end the turn now with a timeout so the kernel terminates the run, rather than feeding the
-                // partial assistant output as a normal turn.
-                if (abortSignal?.aborted) {
-                    action = kernelAction(runtime, this.pendingObservations, { kind: "timeout" });
-                    break;
-                }
-                if (shouldRetry) {
-                    action = {
-                        kind: "call_provider",
-                        context: runtime.render(),
-                        tools,
+                    if (shouldRetry) {
+                        action = {
+                            kind: "call_provider",
+                            context: runtime.render(),
+                            tools,
+                        };
+                        continue;
+                    }
+                    const assistantMessage = {
+                        role: "assistant",
+                        content: finalText,
+                        toolCalls: finalToolCalls,
+                        tokenCount: turnOutputTokens || turnTokens || undefined,
                     };
-                    continue;
-                }
-                const assistantMessage = {
-                    role: "assistant",
-                    content: finalText,
-                    toolCalls: finalToolCalls,
-                    tokenCount: turnOutputTokens || turnTokens || undefined,
-                };
-                const providerEvent = {
-                    kind: "provider_result",
-                    message: messageToKernelMessage(assistantMessage),
-                    ...(turnInputTokens > 0 ? { observed_input_tokens: turnInputTokens } : {}),
-                    ...(turnOutputTokens > 0 ? { observed_output_tokens: turnOutputTokens } : {}),
-                    now_ms: Date.now(),
-                };
-                let nextAction = kernelMaybeAction(runtime, this.pendingObservations, providerEvent);
-                if (!nextAction && this.pendingObservations.some(o => o.kind === "suspended")) {
-                    const resolved = await this.resolveKernelSuspend(runtime, sessionId);
-                    for (const evt of resolved.events)
-                        yield evt;
-                    nextAction = kernelAction(runtime, this.pendingObservations, {
-                        kind: "resume",
-                        approved_calls: resolved.approved,
-                        denied_calls: resolved.denied,
-                    });
-                }
-                action = nextAction ?? kernelAction(runtime, this.pendingObservations, providerEvent);
-                const providerReplay = peekProviderReplay(this.opts.provider, finalText, finalToolCalls);
-                await this.opts.sessionLog.append(sessionId, buildLlmCompletedEvent({
-                    turn: runtime.turn(),
-                    content: finalText,
-                    tokenCount: turnOutputTokens || turnTokens || undefined,
-                    toolCalls: finalToolCalls,
-                    providerReplay,
-                }));
-                // P0-C: emit per-turn tool-gating telemetry. `activeSkill` reflects the skill in effect
-                // GOING INTO this turn; a `skill` call here only takes effect next turn, so emit first, then
-                // advance. Wrapped so a faulty sink can never break the run (pure observation).
-                if (this.opts.onTurnMetrics) {
-                    try {
-                        this.opts.onTurnMetrics({
-                            turn: runtime.turn(),
-                            toolsExposed: tools.length,
-                            toolsCalled: finalToolCalls.length,
-                            activeSkill,
-                            inputTokens: turnInputTokens,
-                            cacheReadTokens: turnCacheReadTokens,
-                            cacheCreationTokens: turnCacheCreationTokens,
+                    const providerEvent = {
+                        kind: "provider_result",
+                        message: messageToKernelMessage(assistantMessage),
+                        ...(turnInputTokens > 0 ? { observed_input_tokens: turnInputTokens } : {}),
+                        ...(turnOutputTokens > 0 ? { observed_output_tokens: turnOutputTokens } : {}),
+                        now_ms: Date.now(),
+                    };
+                    let nextAction = kernelMaybeAction(runtime, this.pendingObservations, providerEvent);
+                    if (!nextAction && this.pendingObservations.some(o => o.kind === "suspended")) {
+                        const resolved = await this.resolveKernelSuspend(runtime, sessionId);
+                        for (const evt of resolved.events)
+                            yield evt;
+                        nextAction = kernelAction(runtime, this.pendingObservations, {
+                            kind: "resume",
+                            approved_calls: resolved.approved,
+                            denied_calls: resolved.denied,
                         });
                     }
-                    catch { /* metrics must never break the run */ }
-                }
-                const skillCall = finalToolCalls.find(c => c.name === "skill");
-                if (skillCall) {
-                    try {
-                        const name = JSON.parse(skillCall.arguments || "{}").name;
-                        if (name)
-                            activeSkill = name;
-                    }
-                    catch { /* malformed skill args — leave activeSkill unchanged */ }
-                }
-            }
-            else if (action.kind === "execute_tool") {
-                const allCalls = action.calls;
-                await this.opts.sessionLog.append(sessionId, { kind: "tool_requested", turn: runtime.turn(), calls: allCalls });
-                const runCtx = {
-                    agentId: this.opts.agentId,
-                    skillDir: this.opts.skillDir,
-                    dreamStore: this.opts.dreamStore,
-                    knowledgeSource: this.opts.knowledgeSource,
-                    onToolSuspend: this.opts.onToolSuspend,
-                    onPermissionRequest: this.opts.onPermissionRequest,
-                    resultSpool: this.opts.resultSpool ?? new LargeResultSpool(),
-                };
-                const toolResults = [];
-                const normalCalls = allCalls.filter(c => c.name !== "update_plan" && c.name !== "submit_workflow_nodes" && c.name !== "start_workflow");
-                const planCalls = allCalls.filter(c => c.name === "update_plan");
-                // M5 v1: `start_workflow` (author a sub-workflow) flattens to the same append path as
-                // `submit_workflow_nodes` — a `WorkflowSpec` is a node batch. (v2 adds top-level bootstrap.)
-                const submitCalls = allCalls.filter(c => c.name === "submit_workflow_nodes" || c.name === "start_workflow");
-                for (const call of planCalls) {
-                    const update = parseUpdatePlanArgs(call.arguments);
-                    kernelApply(runtime, this.pendingObservations, {
-                        kind: "update_task",
-                        update: taskUpdateToKernel(update),
-                    });
-                    const result = { callId: call.id, output: "success", isError: false };
-                    toolResults.push(result);
-                    yield { type: "tool_result", callId: call.id, content: "success", isError: false };
-                }
-                // R3-1: `submit_workflow_nodes` cannot be applied to this runner's kernel — when this runner
-                // is a workflow node, the workflow lives in the *parent* kernel. Surface the requested nodes
-                // as a stream event; the orchestrator collects them onto the node's result and `runWorkflow`
-                // sends `submit_workflow_nodes` to the parent kernel. (When not a workflow node, the event is
-                // simply unconsumed — a no-op.)
-                for (const call of submitCalls) {
-                    // M5 v2.1: a TOP-LEVEL agent authoring a whole sub-workflow via `start_workflow` — record the
-                    // full spec and AUTO-PIVOT once this tool turn resolves (the loop drives it in this kernel and
-                    // injects the outcome). A workflow-NODE's `start_workflow` (and every `submit_workflow_nodes`)
-                    // instead FLATTENS: the batch is surfaced for the parent `runWorkflow` to append.
-                    if (call.name === "start_workflow" && !this.opts.isWorkflowNode) {
-                        const spec = parseStartWorkflowSpec(call.arguments);
-                        if (spec) {
-                            this.pendingAuthoredWorkflows.push(spec);
-                            const out = "workflow authored; executing now";
-                            toolResults.push({ callId: call.id, output: out, isError: false });
-                            yield { type: "tool_result", callId: call.id, content: out, isError: false };
-                            continue;
-                        }
-                    }
-                    // `start_workflow` wraps the batch as `{ spec: { nodes } }`; `submit_workflow_nodes` is `{ nodes }`.
-                    const nodes = call.name === "start_workflow"
-                        ? parseStartWorkflowArgs(call.arguments)
-                        : parseSubmitWorkflowNodesArgs(call.arguments);
-                    yield { type: "workflow_nodes_submitted", nodes };
-                    const result = { callId: call.id, output: "submitted", isError: false };
-                    toolResults.push(result);
-                    yield { type: "tool_result", callId: call.id, content: "submitted", isError: false };
-                }
-                if (normalCalls.length > 0) {
-                    for await (const evt of this.opts.executionPlane.executeAll(normalCalls, runCtx)) {
-                        yield evt;
-                        if (evt.type === "tool_result") {
-                            const tre = evt;
-                            toolResults.push({
-                                callId: tre.callId,
-                                output: tre.content,
-                                isError: tre.isError,
-                                isFatal: tre.isFatal,
-                                errorKind: tre.errorKind,
-                            });
-                        }
-                        else if (evt.type === "tool_argument_repaired") {
-                            const tare = evt;
-                            await this.opts.sessionLog.append(sessionId, {
-                                kind: "tool_argument_repaired",
+                    action = nextAction ?? kernelAction(runtime, this.pendingObservations, providerEvent);
+                    const providerReplay = peekProviderReplay(this.opts.provider, finalText, finalToolCalls);
+                    await this.opts.sessionLog.append(sessionId, buildLlmCompletedEvent({
+                        turn: runtime.turn(),
+                        content: finalText,
+                        tokenCount: turnOutputTokens || turnTokens || undefined,
+                        toolCalls: finalToolCalls,
+                        providerReplay,
+                    }));
+                    // P0-C: emit per-turn tool-gating telemetry. `activeSkill` reflects the skill in effect
+                    // GOING INTO this turn; a `skill` call here only takes effect next turn, so emit first, then
+                    // advance. Wrapped so a faulty sink can never break the run (pure observation).
+                    if (this.opts.onTurnMetrics) {
+                        try {
+                            this.opts.onTurnMetrics({
                                 turn: runtime.turn(),
-                                tool: tare.name,
-                                original_arguments: tare.originalArguments,
-                                repaired_arguments: tare.repairedArguments,
+                                toolsExposed: tools.length,
+                                toolsCalled: finalToolCalls.length,
+                                activeSkill,
+                                inputTokens: turnInputTokens,
+                                cacheReadTokens: turnCacheReadTokens,
+                                cacheCreationTokens: turnCacheCreationTokens,
+                                ...(turnCacheReadBySlot ? { cacheReadTokensBySlot: turnCacheReadBySlot } : {}),
                             });
                         }
-                        else if (evt.type === "tool_denied") {
-                            const tde = evt;
-                            await this.opts.sessionLog.append(sessionId, {
-                                kind: "tool_denied",
-                                turn: runtime.turn(),
-                                call_id: tde.callId,
-                                tool_name: tde.toolName,
-                                reason: tde.reason,
-                            });
+                        catch { /* metrics must never break the run */ }
+                    }
+                    const skillCall = finalToolCalls.find(c => c.name === "skill");
+                    if (skillCall) {
+                        try {
+                            const name = JSON.parse(skillCall.arguments || "{}").name;
+                            if (name)
+                                activeSkill = name;
                         }
-                        else if (evt.type === "permission_request") {
-                            const pre = evt;
-                            const turn = runtime.turn();
-                            await this.opts.sessionLog.append(sessionId, {
-                                kind: "permission_requested",
-                                turn,
-                                tool: pre.toolName,
-                                arguments: pre.arguments,
-                                reason: pre.reason,
-                            });
+                        catch { /* malformed skill args — leave activeSkill unchanged */ }
+                    }
+                }
+                else if (action.kind === "execute_tool") {
+                    const allCalls = action.calls;
+                    await this.opts.sessionLog.append(sessionId, { kind: "tool_requested", turn: runtime.turn(), calls: allCalls });
+                    const runCtx = {
+                        agentId: this.opts.agentId,
+                        skillDir: this.opts.skillDir,
+                        dreamStore: this.opts.dreamStore,
+                        knowledgeSource: this.opts.knowledgeSource,
+                        onToolSuspend: this.opts.onToolSuspend,
+                        onPermissionRequest: this.opts.onPermissionRequest,
+                        resultSpool: this.opts.resultSpool ?? new LargeResultSpool(),
+                    };
+                    const toolResults = [];
+                    const normalCalls = allCalls.filter(c => c.name !== "update_plan" && c.name !== "submit_workflow_nodes" && c.name !== "start_workflow");
+                    const planCalls = allCalls.filter(c => c.name === "update_plan");
+                    // M5 v1: `start_workflow` (author a sub-workflow) flattens to the same append path as
+                    // `submit_workflow_nodes` — a `WorkflowSpec` is a node batch. (v2 adds top-level bootstrap.)
+                    const submitCalls = allCalls.filter(c => c.name === "submit_workflow_nodes" || c.name === "start_workflow");
+                    for (const call of planCalls) {
+                        const update = parseUpdatePlanArgs(call.arguments);
+                        kernelApply(runtime, this.pendingObservations, {
+                            kind: "update_task",
+                            update: taskUpdateToKernel(update),
+                        });
+                        const result = { callId: call.id, output: "success", isError: false };
+                        toolResults.push(result);
+                        yield { type: "tool_result", callId: call.id, content: "success", isError: false };
+                    }
+                    // R3-1: `submit_workflow_nodes` cannot be applied to this runner's kernel — when this runner
+                    // is a workflow node, the workflow lives in the *parent* kernel. Surface the requested nodes
+                    // as a stream event; the orchestrator collects them onto the node's result and `runWorkflow`
+                    // sends `submit_workflow_nodes` to the parent kernel. (When not a workflow node, the event is
+                    // simply unconsumed — a no-op.)
+                    for (const call of submitCalls) {
+                        // M5 v2.1: a TOP-LEVEL agent authoring a whole sub-workflow via `start_workflow` — record the
+                        // full spec and AUTO-PIVOT once this tool turn resolves (the loop drives it in this kernel and
+                        // injects the outcome). A workflow-NODE's `start_workflow` (and every `submit_workflow_nodes`)
+                        // instead FLATTENS: the batch is surfaced for the parent `runWorkflow` to append.
+                        if (call.name === "start_workflow" && !this.opts.isWorkflowNode) {
+                            const spec = parseStartWorkflowSpec(call.arguments);
+                            if (spec) {
+                                this.pendingAuthoredWorkflows.push(spec);
+                                const out = "workflow authored; executing now";
+                                toolResults.push({ callId: call.id, output: out, isError: false });
+                                yield { type: "tool_result", callId: call.id, content: out, isError: false };
+                                continue;
+                            }
                         }
-                        else if (evt.type === "permission_resolved") {
-                            const resolved = evt;
-                            const turn = runtime.turn();
-                            await this.opts.sessionLog.append(sessionId, {
-                                kind: "permission_resolved",
-                                turn,
-                                approved: resolved.approved,
-                                responder: resolved.responder,
-                            });
+                        // `start_workflow` wraps the batch as `{ spec: { nodes } }`; `submit_workflow_nodes` is `{ nodes }`.
+                        const nodes = call.name === "start_workflow"
+                            ? parseStartWorkflowArgs(call.arguments)
+                            : parseSubmitWorkflowNodesArgs(call.arguments);
+                        yield { type: "workflow_nodes_submitted", nodes };
+                        const result = { callId: call.id, output: "submitted", isError: false };
+                        toolResults.push(result);
+                        yield { type: "tool_result", callId: call.id, content: "submitted", isError: false };
+                    }
+                    if (normalCalls.length > 0) {
+                        for await (const evt of this.opts.executionPlane.executeAll(normalCalls, runCtx)) {
+                            yield evt;
+                            if (evt.type === "tool_result") {
+                                const tre = evt;
+                                toolResults.push({
+                                    callId: tre.callId,
+                                    output: tre.content,
+                                    isError: tre.isError,
+                                    isFatal: tre.isFatal,
+                                    errorKind: tre.errorKind,
+                                });
+                            }
+                            else if (evt.type === "tool_argument_repaired") {
+                                const tare = evt;
+                                await this.opts.sessionLog.append(sessionId, {
+                                    kind: "tool_argument_repaired",
+                                    turn: runtime.turn(),
+                                    tool: tare.name,
+                                    original_arguments: tare.originalArguments,
+                                    repaired_arguments: tare.repairedArguments,
+                                });
+                            }
+                            else if (evt.type === "tool_denied") {
+                                const tde = evt;
+                                await this.opts.sessionLog.append(sessionId, {
+                                    kind: "tool_denied",
+                                    turn: runtime.turn(),
+                                    call_id: tde.callId,
+                                    tool_name: tde.toolName,
+                                    reason: tde.reason,
+                                });
+                            }
+                            else if (evt.type === "permission_request") {
+                                const pre = evt;
+                                const turn = runtime.turn();
+                                await this.opts.sessionLog.append(sessionId, {
+                                    kind: "permission_requested",
+                                    turn,
+                                    tool: pre.toolName,
+                                    arguments: pre.arguments,
+                                    reason: pre.reason,
+                                });
+                            }
+                            else if (evt.type === "permission_resolved") {
+                                const resolved = evt;
+                                const turn = runtime.turn();
+                                await this.opts.sessionLog.append(sessionId, {
+                                    kind: "permission_resolved",
+                                    turn,
+                                    approved: resolved.approved,
+                                    responder: resolved.responder,
+                                });
+                            }
                         }
+                        const names = normalCalls.map(c => c.name).join(", ");
+                        kernelApply(runtime, this.pendingObservations, {
+                            kind: "update_task",
+                            update: taskUpdateToKernel({ progress: `Executed tools: ${names}` }),
+                        });
                     }
-                    const names = normalCalls.map(c => c.name).join(", ");
-                    kernelApply(runtime, this.pendingObservations, {
-                        kind: "update_task",
-                        update: taskUpdateToKernel({ progress: `Executed tools: ${names}` }),
+                    await this.opts.sessionLog.append(sessionId, {
+                        kind: "tool_completed",
+                        turn: runtime.turn(),
+                        results: toolResults.map(r => ({
+                            call_id: r.callId,
+                            output: r.output,
+                            is_error: r.isError,
+                            token_count: r.tokenCount,
+                        })),
                     });
-                }
-                await this.opts.sessionLog.append(sessionId, {
-                    kind: "tool_completed",
-                    turn: runtime.turn(),
-                    results: toolResults.map(r => ({
-                        call_id: r.callId,
-                        output: r.output,
-                        is_error: r.isError,
-                        token_count: r.tokenCount,
-                    })),
-                });
-                for (const call of normalCalls) {
-                    const result = toolResults.find(r => r.callId === call.id);
-                    if (result) {
-                        this.pendingSpoolOutputs.set(call.id, { tool: call.name, output: result.output });
+                    for (const call of normalCalls) {
+                        const result = toolResults.find(r => r.callId === call.id);
+                        if (result) {
+                            this.pendingSpoolOutputs.set(call.id, { tool: call.name, output: result.output });
+                        }
                     }
-                }
-                // P1-B B3: a `skill` call that resolved successfully activates that skill in the kernel, so
-                // the next `call_provider` narrows the toolset to its declared tools. Fed before `tool_results`
-                // (which computes the next action). Errs-open: a failed/missing skill load doesn't activate.
-                for (const call of allCalls) {
-                    if (call.name !== "skill")
-                        continue;
-                    const res = toolResults.find(r => r.callId === call.id);
-                    if (!res || res.isError)
-                        continue;
-                    try {
-                        const name = JSON.parse(call.arguments || "{}").name;
-                        if (name)
-                            kernelApply(runtime, this.pendingObservations, { kind: "skill_activated", name });
+                    // P1-B B3: a `skill` call that resolved successfully activates that skill in the kernel, so
+                    // the next `call_provider` narrows the toolset to its declared tools. Fed before `tool_results`
+                    // (which computes the next action). Errs-open: a failed/missing skill load doesn't activate.
+                    for (const call of allCalls) {
+                        if (call.name !== "skill")
+                            continue;
+                        const res = toolResults.find(r => r.callId === call.id);
+                        if (!res || res.isError)
+                            continue;
+                        try {
+                            const name = JSON.parse(call.arguments || "{}").name;
+                            if (name)
+                                kernelApply(runtime, this.pendingObservations, { kind: "skill_activated", name });
+                        }
+                        catch { /* malformed skill args — skip activation */ }
                     }
-                    catch { /* malformed skill args — skip activation */ }
-                }
-                action = kernelAction(runtime, this.pendingObservations, {
-                    kind: "tool_results",
-                    results: toolResults.map(toolResultToKernel),
-                });
-            }
-            else if (action.kind === "evaluate_milestone") {
-                const milestonePolicy = this.opts.milestonePolicy ?? "require_verifier";
-                if (milestonePolicy === "auto_pass") {
                     action = kernelAction(runtime, this.pendingObservations, {
-                        kind: "milestone_result",
-                        result: milestoneCheckResultToKernel(milestoneCheckPass(action.phaseId)),
+                        kind: "tool_results",
+                        results: toolResults.map(toolResultToKernel),
                     });
-                    this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
                 }
-                else if (this.opts.onMilestoneEvaluate) {
-                    const check = await this.opts.onMilestoneEvaluate({
-                        phaseId: action.phaseId,
-                        criteria: action.criteria,
-                        requiredEvidence: action.requiredEvidence,
-                    });
-                    action = kernelAction(runtime, this.pendingObservations, {
-                        kind: "milestone_result",
-                        result: milestoneCheckResultToKernel(check),
-                    });
-                    this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
+                else if (action.kind === "evaluate_milestone") {
+                    const milestonePolicy = this.opts.milestonePolicy ?? "require_verifier";
+                    if (milestonePolicy === "auto_pass") {
+                        action = kernelAction(runtime, this.pendingObservations, {
+                            kind: "milestone_result",
+                            result: milestoneCheckResultToKernel(milestoneCheckPass(action.phaseId)),
+                        });
+                        this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
+                    }
+                    else if (this.opts.onMilestoneEvaluate) {
+                        const check = await this.opts.onMilestoneEvaluate({
+                            phaseId: action.phaseId,
+                            criteria: action.criteria,
+                            requiredEvidence: action.requiredEvidence,
+                        });
+                        action = kernelAction(runtime, this.pendingObservations, {
+                            kind: "milestone_result",
+                            result: milestoneCheckResultToKernel(check),
+                        });
+                        this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
+                    }
+                    else {
+                        this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
+                        const turnsUsed = Math.max(1, runtime.turn());
+                        await this.opts.sessionLog.append(sessionId, buildRunTerminalEvent({
+                            reason: "milestone_pending",
+                            turnsUsed,
+                            totalTokens: 0,
+                        }));
+                        yield { type: "done", iterations: turnsUsed, totalTokens: 0, status: "milestone_pending" };
+                        this.activeKernel = null;
+                        this.currentSessionId = null;
+                        return;
+                    }
                 }
-                else {
-                    this.nextArchiveStart = await this.appendObservations(sessionId, runtime, this.nextArchiveStart);
-                    const turnsUsed = Math.max(1, runtime.turn());
-                    await this.opts.sessionLog.append(sessionId, buildRunTerminalEvent({
-                        reason: "milestone_pending",
-                        turnsUsed,
-                        totalTokens: 0,
-                    }));
-                    yield { type: "done", iterations: turnsUsed, totalTokens: 0, status: "milestone_pending" };
-                    this.activeKernel = null;
-                    this.currentSessionId = null;
-                    return;
+                else if (action.kind === "done") {
+                    break;
                 }
             }
-            else if (action.kind === "done") {
-                break;
+        }
+        catch (err) {
+            // I0b: kernel rejection (or any other thrown error inside the loop) reaches us here.
+            // Classify by NAPI status code or message pattern — `invalid_arg` for surface-shape rejects,
+            // `error` for everything else — then emit run_terminal so observability sees a clean end.
+            // The yield-error path mirrors what the in-flight provider-stream catch does.
+            const errMsg = formatToolError(err);
+            const code = err.code;
+            const isInvalidArg = code === "InvalidArg" ||
+                errMsg.toLowerCase().includes("invalidarg") ||
+                errMsg.toLowerCase().includes("invalid argument");
+            const reason = isInvalidArg ? "invalid_arg" : "error";
+            yield { type: "error", message: errMsg };
+            try {
+                await this.opts.sessionLog.append(sessionId, buildRunTerminalEvent({
+                    reason,
+                    turnsUsed: runtime.turn() || 0,
+                    totalTokens: 0,
+                }));
             }
+            catch { /* session log failure must not mask the original error */ }
+            yield { type: "done", iterations: runtime.turn() || 0, totalTokens: 0, status: reason };
+            this.activeKernel = null;
+            this.currentSessionId = null;
+            this.dashboard = null;
+            return;
         }
         const result = action.kind === "done" ? action.result : undefined;
-        const status = result?.termination ?? "error";
+        // I0a: when the loop exits without a clean kernel-done — typically because a hard interrupt
+        // aborted the in-flight LLM stream and the catch path sent `timeout` (which the kernel handles
+        // by injecting a rollback note and continuing, not by terminating) — preserve the preempt
+        // intent in the run_terminal reason. Without this, every interrupt-curtailed run reports
+        // `reason: "error"` and the bench / observability layer can't distinguish preemption from a
+        // genuine crash. Mirrors WASM/Python/Rust.
+        const status = result?.termination ?? (this.interrupted ? "user_abort" : "error");
         const turnsUsed = result ? Math.max(1, result.turnsUsed) : runtime.turn() || 0;
         const totalTokens = result?.totalTokensUsed ?? 0;
         nextCompressedArchiveStart = await this.appendObservations(sessionId, runtime, nextCompressedArchiveStart);