@deepstrike/sdk 0.2.16 → 0.2.18

package/dist/runtime/runner.js

@@ -6,10 +6,11 @@ import { sanitizeReplayText } from "./replay-sanitize.js";
 import { buildLlmCompletedEvent, buildRunTerminalEvent, buildWorkflowNodeCompletedEvent, buildWorkflowNodesSubmittedEvent, recoverCompletedWorkflowNodes, recoverSubmittedWorkflowNodes, repairEventsForRecovery, } from "./session-repair.js";
 import { KernelPrimitivesDashboard } from "./kernel-primitives-dashboard.js";
 import { capabilityMarker, capabilitySkill, capabilityTool, capabilityCommandMount, capabilityCommandUnmount, kernelAction, kernelApply, kernelMaybeAction, forceCompact, messageToKernelMessage, skillMetadataToKernel, taskUpdateToKernel, toolResultToKernel, toolSchemaToKernel, } from "./kernel-step.js";
-import { agentRunSpecToKernel, findSpawnProcessObservation, milestoneCheckPass, milestoneCheckResultToKernel, spawnObservationToManifest, subAgentResultToKernel, submitWorkflowNodesToKernel, workflowBudgetNote, workflowNodeToManifest, workflowNodeToSpec, workflowSpecToKernel, } from "../types/agent.js";
+import { agentRunSpecToKernel, findSpawnProcessObservation, milestoneCheckPass, milestoneCheckResultToKernel, spawnObservationToManifest, subAgentResultToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, workflowBudgetNote, workflowNodeToManifest, workflowNodeToSpec, workflowSpecToKernel, } from "../types/agent.js";
 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 { kernelObservationToSessionEvent, withCategory } from "./kernel-event-log.js";
 import { assertNativeProfile } from "./os-profile.js";
@@ -17,6 +18,9 @@ import { LargeResultSpool } from "./large-result-spool.js";
 export class RuntimeRunner {
     opts;
     interrupted = false;
+    /** #2-B-ii: aborts the in-flight provider stream when the run is interrupted/preempted. Recreated
+     *  per `execute`; `interrupt()` fires it so a Critical `InterruptNow` cancels the live LLM call. */
+    abortController = null;
     activeKernel = null;
     pendingObservations = [];
     currentSessionId = null;
@@ -25,6 +29,9 @@ export class RuntimeRunner {
     pendingSpoolOutputs = new Map();
     /** Local cache of paged-out/archived messages for priority memory retrieval. */
     localPageOutCache = [];
+    /** M5 v2.1: sub-workflow specs a top-level agent authored via `start_workflow`, awaiting auto-drive
+     *  at the next safe point (after the tool turn resolves, kernel back in Reason — not suspended). */
+    pendingAuthoredWorkflows = [];
     dashboard = null;
     constructor(opts) {
         this.opts = opts;
@@ -126,6 +133,8 @@ export class RuntimeRunner {
         return new KernelRuntime({
             maxTokens: this.opts.maxTokens,
             maxTurns: this.opts.maxTurns,
+            // M4/G5: per-node token cap → child run's cumulative token budget.
+            maxTotalTokens: this.opts.maxTotalTokens !== undefined ? BigInt(this.opts.maxTotalTokens) : undefined,
             timeoutMs: this.opts.timeoutMs !== undefined ? BigInt(this.opts.timeoutMs) : undefined,
         });
     }
@@ -266,7 +275,7 @@ export class RuntimeRunner {
      * validation reason — a node that cannot meet its declared output contract starves its dependents,
      * exactly as a denied spawn does.
      */
-    async runWorkflowNode(node, parentSessionId, orchestrator, budget, outputs) {
+    async runWorkflowNode(node, parentSessionId, orchestrator, budget, outputs, abortSignal) {
         // G2: a reduce node runs no LLM — execute the registered pure function over its dependency
         // outputs and feed the result back as an ordinary completion. Deterministic; no agent burned.
         if (node.reducer) {
@@ -284,8 +293,45 @@ export class RuntimeRunner {
             spec: { ...baseSpec, goal: withBudget(goal) },
             manifest,
             sessionLog: this.opts.sessionLog,
+            // M5 v2.1: this child IS a workflow node — its `start_workflow` flattens to this kernel (the
+            // workflow it would author joins the running DAG) rather than bootstrapping a nested pivot.
+            isWorkflowNode: true,
+            // #2-B-ii: the per-node abort signal the driver fires when the kernel preempts this node.
+            ...(abortSignal ? { abortSignal } : {}),
             ...(this.opts.subAgentHarness ? { harness: this.opts.subAgentHarness } : {}),
         });
+        const textOf = (r) => {
+            const c = r.result.finalMessage?.content;
+            return typeof c === "string" ? c : c != null ? JSON.stringify(c) : "";
+        };
+        const withSignal = (r, patch) => ({ ...r, result: { ...r.result, ...patch } });
+        // A#2 tournament judge: this node compares two entrants' produced outputs rather than running its
+        // own goal. Look up both candidates, run a judge over the controller's criterion, and report the
+        // winning entrant's agent id as `tournamentWinner` (the kernel advances the bracket with it).
+        if (node.judge_match) {
+            const out = outputs ?? new Map();
+            const left = out.get(node.judge_match.left) ?? "";
+            const right = out.get(node.judge_match.right) ?? "";
+            const result = await orchestrator.run(mkCtx(judgeGoal(baseSpec.goal, left, right)));
+            const winner = extractJudgeWinner(textOf(result));
+            const winnerId = winner === "right" ? node.judge_match.right : node.judge_match.left;
+            return withSignal(result, { tournamentWinner: winnerId });
+        }
+        // A#2 v2 loop iteration: run the increment, then extract a stop signal so the kernel can end the
+        // loop early (`loopContinue: false`). No signal ⇒ run to `max_iters`.
+        if (node.loop_max_iters != null) {
+            const result = await orchestrator.run(mkCtx(`${baseSpec.goal}\n\n${loopInstruction(node.loop_max_iters)}`));
+            const cont = extractLoopContinue(textOf(result));
+            return cont === undefined ? result : withSignal(result, { loopContinue: cont });
+        }
+        // A#2 classify: run the classifier, then extract the chosen branch label; the kernel runs that
+        // branch and prunes the rest. No recognizable choice ⇒ leave unset (kernel prunes all branches).
+        if (node.classify_labels && node.classify_labels.length) {
+            const labels = node.classify_labels;
+            const result = await orchestrator.run(mkCtx(`${baseSpec.goal}\n\n${classifyInstruction(labels)}`));
+            const branch = extractClassifyBranch(textOf(result), labels);
+            return branch === undefined ? result : withSignal(result, { classifyBranch: branch });
+        }
         const schema = node.output_schema;
         if (!schema)
             return orchestrator.run(mkCtx(baseSpec.goal));
@@ -350,8 +396,7 @@ export class RuntimeRunner {
         }
         const parentSessionId = this.currentSessionId;
         const runtime = this.activeKernel;
-        const orchestrator = this.opts.subAgentOrchestrator ?? defaultSubAgentOrchestrator;
-        let observations = kernelApply(runtime, this.pendingObservations, {
+        const observations = kernelApply(runtime, this.pendingObservations, {
             kind: "load_workflow",
             spec: workflowSpecToKernel(spec),
             parent_session_id: parentSessionId,
@@ -360,6 +405,87 @@ export class RuntimeRunner {
             // R3-1: re-apply recorded runtime submissions so dynamically-appended nodes are reconstructed.
             ...(opts?.resumedSubmissions?.length ? { resumed_submissions: opts.resumedSubmissions } : {}),
         });
+        return this.driveWorkflow(observations, parentSessionId, runtime);
+    }
+    /**
+     * M5/G1: bootstrap an **agent-authored** workflow ("the model writes its own harness"). Unlike
+     * `runWorkflow` (the host fires the privileged `load_workflow`), this routes the spec through the
+     * agent-reachable `Syscall::LoadWorkflow` (the `submit_workflow` event): with no workflow active the
+     * kernel **bootstraps** the DAG; if one is already active it **flattens** the spec's nodes onto it
+     * (bootstrap-or-flatten — one kernel, one quota, never a workflow stack). Gated by the same
+     * `max_workflow_nodes` backstop as runtime submission, so an authored harness can't overgrow the run.
+     * The resulting batches are driven by the same shared driver as `runWorkflow`.
+     */
+    async bootstrapWorkflow(spec, opts) {
+        if (!this.activeKernel || !this.currentSessionId) {
+            throw new Error("bootstrapWorkflow requires an active parent run");
+        }
+        const parentSessionId = this.currentSessionId;
+        const runtime = this.activeKernel;
+        const observations = kernelApply(runtime, this.pendingObservations, submitWorkflowToKernel(spec, parentSessionId, opts?.submitterAgentId));
+        return this.driveWorkflow(observations, parentSessionId, runtime);
+    }
+    /**
+     * M5 v2.1: drive the sub-workflow(s) a top-level agent authored via `start_workflow`. Called at the
+     * verified-safe point (right after the tool turn resolved to `call_provider` — kernel in Reason, not
+     * suspended). For each authored spec: `bootstrapWorkflow` runs it in THIS kernel (the kernel resumes
+     * the agent reason loop on `workflow_completed` — `finish_workflow` sets phase=Reason), then the
+     * outcome is injected as a user message so the agent's next turn sees the result. Returns a fresh
+     * `call_provider` synthesized from the updated context (the workflow drive consumed its own kernel
+     * actions, so we re-render — the same pattern as the reactive-compact retry path).
+     */
+    async driveAuthoredWorkflows(runtime, action) {
+        const specs = this.pendingAuthoredWorkflows;
+        this.pendingAuthoredWorkflows = [];
+        for (const spec of specs) {
+            const outcome = await this.bootstrapWorkflow(spec);
+            kernelApply(runtime, this.pendingObservations, {
+                kind: "add_history_message",
+                message: messageToKernelMessage({ role: "user", content: authoredWorkflowOutcomeNote(outcome) }),
+            });
+        }
+        return { kind: "call_provider", context: runtime.render(), tools: action.tools };
+    }
+    /**
+     * #2-B-ii: while a workflow batch is in flight, poll the signal source. A Critical `InterruptNow`
+     * routes through the kernel (which, with the root suspended in `SubAgentAwait`, preempts — marks the
+     * running nodes `UserAbort`, tears the `WorkflowRun` down, emits `AgentPreempted`); we then abort the
+     * matching children's in-flight LLM calls (via their per-node `AbortController` → `interrupt()`).
+     * Returns the torn-down workflow's outcome on preemption, else `null`. No-op (null) without a signal
+     * source. Non-preempting signals (queue/observe/soft-interrupt) are still applied as they arrive.
+     */
+    async monitorWorkflowPreemption(runtime, controllers, batchState) {
+        const source = this.opts.signalSource;
+        if (!source)
+            return null;
+        while (!batchState.settled) {
+            const sig = await source.nextSignal();
+            if (batchState.settled)
+                break;
+            if (!sig) {
+                await new Promise(resolve => setTimeout(resolve, 5));
+                continue;
+            }
+            const obs = kernelApply(runtime, this.pendingObservations, signalToKernelEvent(sig));
+            const preempted = obs.find(o => o.kind === "agent_preempted");
+            if (preempted) {
+                for (const id of preempted.agent_ids ?? [])
+                    controllers.get(id)?.abort();
+                const wc = obs.find(o => o.kind === "workflow_completed");
+                return { completed: wc?.completed ?? [], failed: wc?.failed ?? [] };
+            }
+        }
+        return null;
+    }
+    /**
+     * Shared workflow driver for `runWorkflow` (host `load_workflow`) and `bootstrapWorkflow` (agent
+     * `submit_workflow`): given the observations from the initial load/bootstrap, run each kernel-emitted
+     * batch in parallel, feed completions back (appending any agent-submitted nodes first), and loop
+     * until the kernel reports the workflow complete. Returns the completed / failed node agent-ids.
+     */
+    async driveWorkflow(initial, parentSessionId, runtime) {
+        let observations = initial;
+        const orchestrator = this.opts.subAgentOrchestrator ?? defaultSubAgentOrchestrator;
         const collectNodes = (obs) => obs.find(o => o.kind === "workflow_batch_spawned")
             ?.nodes ?? [];
         // G4: the batch observation also carries the workflow's remaining budget; track the latest so a
@@ -368,7 +494,7 @@ export class RuntimeRunner {
         const findDone = (obs) => obs.find(o => o.kind === "workflow_completed");
         let done = findDone(observations);
         if (done)
-            return { completed: done.completed ?? [], failed: done.failed ?? [] };
+            return { completed: done.completed ?? [], failed: done.failed ?? [], outputs: {} };
         let nodes = collectNodes(observations);
         let budget = collectBudget(observations);
         // G2: each completed node's output, keyed by agent id — a reduce node reads its dependencies'
@@ -377,10 +503,21 @@ export class RuntimeRunner {
         const outputs = new Map();
         for (;;) {
             if (nodes.length === 0)
-                return { completed: [], failed: [] }; // nothing to run (e.g. all gated)
+                return { completed: [], failed: [], outputs: Object.fromEntries(outputs) }; // nothing to run (e.g. all gated)
             // Run the currently-runnable nodes in parallel — each is independent within a round.
             const roundBudget = budget;
-            const results = await Promise.all(nodes.map(node => this.runWorkflowNode(node, parentSessionId, orchestrator, roundBudget, outputs)));
+            // #2-B-ii: per-node abort controllers + a concurrent preemption monitor. While the batch is in
+            // flight the monitor polls the signal source; a Critical `InterruptNow` routes through the kernel
+            // (which preempts → `AgentPreempted` + tears the workflow down) and we abort the matching child's
+            // in-flight LLM call. If the kernel preempted, stop driving and return the torn-down outcome.
+            const controllers = new Map(nodes.map(n => [n.agent_id, new AbortController()]));
+            const batchState = { settled: false };
+            const monitor = this.monitorWorkflowPreemption(runtime, controllers, batchState);
+            const results = await Promise.all(nodes.map(node => this.runWorkflowNode(node, parentSessionId, orchestrator, roundBudget, outputs, controllers.get(node.agent_id)?.signal)));
+            batchState.settled = true;
+            const preempted = await monitor;
+            if (preempted)
+                return { ...preempted, outputs: Object.fromEntries(outputs) };
             // Feed completions back one at a time. The kernel's run-queue executor may spawn a node's
             // dependents the moment *that* node completes (per-node unblock), so each feed can emit its
             // own `workflow_batch_spawned`; ACCUMULATE them across the round rather than keeping only the
@@ -427,7 +564,7 @@ export class RuntimeRunner {
                 }));
             }
             if (done && nextNodes.length === 0) {
-                return { completed: done.completed ?? [], failed: done.failed ?? [] };
+                return { completed: done.completed ?? [], failed: done.failed ?? [], outputs: Object.fromEntries(outputs) };
             }
             nodes = nextNodes;
         }
@@ -446,7 +583,7 @@ export class RuntimeRunner {
         const resumedSubmissions = recoverSubmittedWorkflowNodes(events);
         return this.runWorkflow(spec, { resumedCompleted, resumedSubmissions });
     }
-    interrupt() { this.interrupted = true; }
+    interrupt() { this.interrupted = true; this.abortController?.abort(); }
     async *run(req) {
         const prior = req.inheritEvents ?? await this.opts.sessionLog.read(req.sessionId);
         const midRun = isMidRun(prior);
@@ -626,6 +763,7 @@ export class RuntimeRunner {
     }
     async *execute(sessionId, goal, criteria, extensions, priorEvents, resumeMidRun = false, attachments) {
         this.interrupted = false;
+        this.abortController = new AbortController();
         this.pendingObservations = [];
         this.pendingSpoolOutputs.clear();
         this.currentSessionId = sessionId;
@@ -820,28 +958,10 @@ export class RuntimeRunner {
             if (this.opts.signalSource) {
                 const sig = await this.opts.signalSource.nextSignal();
                 if (sig) {
-                    const id = crypto.randomUUID();
-                    const source = sig.source ?? "custom";
-                    const signalType = sig.signalType ?? "event";
-                    const urgency = sig.urgency ?? "normal";
-                    const summary = String(sig.payload?.goal ?? sig.kind ?? "signal");
-                    // 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).
-                    // Wire shape is snake_case RuntimeSignal with an object payload.
-                    const sigAction = kernelMaybeAction(runtime, this.pendingObservations, {
-                        kind: "signal",
-                        signal: {
-                            id,
-                            source,
-                            signal_type: signalType,
-                            urgency,
-                            summary,
-                            payload: sig.payload ?? {},
-                            ...(sig.dedupeKey ? { dedupe_key: sig.dedupeKey } : {}),
-                            timestamp_ms: Date.now(),
-                        },
-                    });
+                    // 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;
                 }
@@ -849,6 +969,15 @@ export class RuntimeRunner {
             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 finalToolCalls = [];
                 let finalText = "";
                 const context = action.context;
@@ -857,8 +986,14 @@ export class RuntimeRunner {
                 let turnInputTokens = 0;
                 let turnOutputTokens = 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)) {
+                    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;
@@ -876,6 +1011,11 @@ export class RuntimeRunner {
                     }
                 }
                 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 = String(err).toLowerCase();
                     if ((errMsg.includes("413") || errMsg.includes("too long") || errMsg.includes("context length exceeded") || errMsg.includes("context_length_exceeded")) &&
                         !hasAttemptedReactiveCompact) {
@@ -891,6 +1031,13 @@ export class RuntimeRunner {
                         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",
@@ -946,9 +1093,11 @@ export class RuntimeRunner {
                     resultSpool: this.opts.resultSpool ?? new LargeResultSpool(),
                 };
                 const toolResults = [];
-                const normalCalls = allCalls.filter(c => c.name !== "update_plan" && c.name !== "submit_workflow_nodes");
+                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");
-                const submitCalls = allCalls.filter(c => c.name === "submit_workflow_nodes");
+                // 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, {
@@ -965,7 +1114,24 @@ export class RuntimeRunner {
                 // 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) {
-                    const nodes = parseSubmitWorkflowNodesArgs(call.arguments);
+                    // 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);
@@ -1487,3 +1653,63 @@ function parseSubmitWorkflowNodesArgs(argsStr) {
     }
     return Array.isArray(parsed.nodes) ? parsed.nodes : [];
 }
+/** M5 v1: parse the `start_workflow` tool arguments (`{ spec: { nodes: WorkflowNodeSpec[] } }`) into
+ *  the spec's node batch — flattened onto the running workflow via the same append path. A malformed
+ *  payload yields no nodes rather than throwing. */
+function parseStartWorkflowArgs(argsStr) {
+    let parsed = {};
+    try {
+        parsed = JSON.parse(argsStr);
+    }
+    catch {
+        // Ignore parse error → no nodes.
+    }
+    const spec = parsed.spec;
+    return Array.isArray(spec?.nodes) ? spec.nodes : [];
+}
+/** M5 v2.1: parse the full `WorkflowSpec` from a top-level `start_workflow` call, for auto-pivot drive
+ *  (vs `parseStartWorkflowArgs`, which returns only the node batch for the flatten path). Returns
+ *  `undefined` on a malformed / empty payload so the caller falls back to the flatten path. */
+function parseStartWorkflowSpec(argsStr) {
+    try {
+        const parsed = JSON.parse(argsStr);
+        if (Array.isArray(parsed.spec?.nodes) && parsed.spec.nodes.length > 0) {
+            return { nodes: parsed.spec.nodes };
+        }
+    }
+    catch {
+        // Ignore parse error → undefined (fall back to flatten).
+    }
+    return undefined;
+}
+/** M5 v2.1: render an authored-workflow outcome into a user-message note injected back into the
+ *  agent's context, so the agent's next turn continues with the sub-workflow's results in view. */
+function authoredWorkflowOutcomeNote(outcome) {
+    const lines = [
+        `[authored workflow result] ${outcome.completed.length} node(s) completed` +
+            (outcome.failed.length ? `, ${outcome.failed.length} failed` : "") + ".",
+    ];
+    for (const id of outcome.completed) {
+        const out = outcome.outputs[id];
+        if (out)
+            lines.push(`- ${id}: ${out.length > 500 ? out.slice(0, 500) + "…" : out}`);
+    }
+    return lines.join("\n");
+}
+/** Lower a host `RuntimeSignal` to the kernel's snake_case `signal` input event. Shared by the main
+ *  loop's per-turn poll and #2-B-ii's workflow-batch preemption monitor (so the two never drift). */
+function signalToKernelEvent(sig) {
+    return {
+        kind: "signal",
+        signal: {
+            id: crypto.randomUUID(),
+            source: sig.source ?? "custom",
+            signal_type: sig.signalType ?? "event",
+            urgency: sig.urgency ?? "normal",
+            summary: String(sig.payload?.goal ?? sig.kind ?? "signal"),
+            payload: sig.payload ?? {},
+            ...(sig.dedupeKey ? { dedupe_key: sig.dedupeKey } : {}),
+            timestamp_ms: Date.now(),
+        },
+    };
+}

package/dist/runtime/sub-agent-orchestrator.d.ts

@@ -12,7 +12,18 @@ export interface SubAgentRunContext {
         evalProvider: import("../types.js").LLMProvider;
         maxAttempts?: number;
     };
+    /** M5 v2.1: set when this child is a workflow node (spawned by the workflow driver). Propagated to
+     *  the child runner so a nested `start_workflow` FLATTENS to the parent kernel rather than
+     *  auto-pivoting into its own bootstrap (which would fragment the one-kernel/one-quota governance). */
+    isWorkflowNode?: boolean;
+    /** #2-B-ii: parent-controlled abort. When this fires (the kernel preempted this node via
+     *  `InterruptNow` → `AgentPreempted`), the orchestrator interrupts the child runner, cancelling its
+     *  in-flight LLM call. */
+    abortSignal?: AbortSignal;
 }
+/** M1/G3 intelligence routing: resolve the provider for a sub-agent from its spec's `modelHint`.
+ *  Falls back to the parent provider when there is no hint or no `providerFor` hook resolves it. */
+export declare function resolveProvider(opts: RuntimeOptions, modelHint?: string): RuntimeOptions["provider"];
 /** Host-side driver for kernel-isolated sub-agent runs. */
 export declare class SubAgentOrchestrator {
     stream(ctx: SubAgentRunContext): AsyncIterable<StreamEvent>;

package/dist/runtime/sub-agent-orchestrator.js

@@ -1,5 +1,6 @@
 import { agentRunSpecToKernel, findSpawnProcessObservation, spawnObservationToManifest } from "../types/agent.js";
 import { FilteredExecutionPlane } from "./filtered-plane.js";
+import { WorktreeExecutionPlane } from "./worktree-plane.js";
 import { kernelApply } from "./kernel-step.js";
 function terminationFromStatus(status) {
     const normalized = status.toLowerCase();
@@ -14,6 +15,38 @@ function terminationFromStatus(status) {
     }
     return status;
 }
+/** M3/G4: if this sub-agent is an `isolation: "worktree"` node and a worktree manager is configured,
+ *  wrap its plane in a `WorktreeExecutionPlane` (creates a git worktree, injects it as `cwd`, removes
+ *  it on cleanup). Returns the plane to use plus a cleanup hook the caller must run when the sub-agent
+ *  finishes. Without a manager (or for non-worktree nodes) this is a pass-through with a no-op cleanup. */
+function withWorktree(ctx, plane) {
+    if (ctx.manifest.isolation === "worktree" && ctx.parentOpts.worktreeManager) {
+        const wt = new WorktreeExecutionPlane(plane, ctx.parentOpts.worktreeManager, ctx.spec.identity.agentId);
+        return { plane: wt, cleanup: () => wt.cleanup() };
+    }
+    return { plane, cleanup: async () => { } };
+}
+/** M1/G3 intelligence routing: resolve the provider for a sub-agent from its spec's `modelHint`.
+ *  Falls back to the parent provider when there is no hint or no `providerFor` hook resolves it. */
+export function resolveProvider(opts, modelHint) {
+    if (modelHint && opts.providerFor) {
+        const routed = opts.providerFor(modelHint);
+        if (routed)
+            return routed;
+    }
+    return opts.provider;
+}
+/** #2-B-ii: bridge a parent-controlled AbortSignal to a child runner's `interrupt()` — fires now if
+ *  the signal is already aborted (creation race), else once when it aborts. */
+function linkAbort(signal, runner) {
+    if (!signal)
+        return;
+    if (signal.aborted) {
+        runner.interrupt();
+        return;
+    }
+    signal.addEventListener("abort", () => runner.interrupt(), { once: true });
+}
 /** Derive which meta-tools a child runner should expose based on permitted IDs and available sources. */
 function deriveMetaTools(permitted, opts) {
     const metaTools = new Set();
@@ -33,6 +66,8 @@ export class SubAgentOrchestrator {
         const permitted = new Set(ctx.manifest.permitted_capability_ids ?? []);
         const metaTools = deriveMetaTools(permitted, ctx.parentOpts);
         const filteredPlane = new FilteredExecutionPlane(ctx.parentOpts.executionPlane, permitted, metaTools);
+        // M3/G4: a worktree node runs inside its own git worktree (created here, removed in `finally`).
+        const { plane: execPlane, cleanup: cleanupWorktree } = withWorktree(ctx, filteredPlane);
         let systemPrompt = ctx.parentOpts.systemPrompt;
         let inheritEvents;
         if (ctx.manifest.context_inheritance === "full") {
@@ -48,7 +83,11 @@ export class SubAgentOrchestrator {
         const { RuntimeRunner } = await import("./runner.js");
         const childRunner = new RuntimeRunner({
             ...ctx.parentOpts,
-            executionPlane: filteredPlane,
+            // M1/G3: route to the node's hinted model (falls back to the parent provider).
+            provider: resolveProvider(ctx.parentOpts, ctx.spec.modelHint),
+            // M4/G5: cap the child run at the node's token budget (falls back to the inherited cap).
+            maxTotalTokens: ctx.spec.tokenBudget ?? ctx.parentOpts.maxTotalTokens,
+            executionPlane: execPlane,
             agentId: ctx.spec.identity.agentId,
             systemPrompt,
             sessionLog: ctx.sessionLog,
@@ -56,12 +95,22 @@ export class SubAgentOrchestrator {
             dreamStore: metaTools.has("memory") ? ctx.parentOpts.dreamStore : undefined,
             knowledgeSource: metaTools.has("knowledge") ? ctx.parentOpts.knowledgeSource : undefined,
             enablePlanTool: metaTools.has("update_plan") ? ctx.parentOpts.enablePlanTool : undefined,
+            // M5 v2.1: a workflow node's `start_workflow` flattens to the parent kernel (no nested pivot).
+            isWorkflowNode: ctx.isWorkflowNode,
         });
-        yield* childRunner.run({
-            sessionId: ctx.spec.identity.sessionId,
-            goal: ctx.spec.goal,
-            inheritEvents,
-        });
+        // #2-B-ii: when the parent preempts this node (kernel `AgentPreempted`), interrupt the child —
+        // cancelling its in-flight LLM call. Handle an already-aborted signal too (creation race).
+        linkAbort(ctx.abortSignal, childRunner);
+        try {
+            yield* childRunner.run({
+                sessionId: ctx.spec.identity.sessionId,
+                goal: ctx.spec.goal,
+                inheritEvents,
+            });
+        }
+        finally {
+            await cleanupWorktree();
+        }
     }
     async run(ctx) {
         if (ctx.harness) {
@@ -70,25 +119,41 @@ export class SubAgentOrchestrator {
             const permitted = new Set(ctx.manifest.permitted_capability_ids ?? []);
             const metaTools = deriveMetaTools(permitted, ctx.parentOpts);
             const filteredPlane = new FilteredExecutionPlane(ctx.parentOpts.executionPlane, permitted, metaTools);
+            // M3/G4: worktree isolation for a worktree node (cleaned up in `finally` below).
+            const { plane: execPlane, cleanup: cleanupWorktree } = withWorktree(ctx, filteredPlane);
             const childRunner = new RuntimeRunner({
                 ...ctx.parentOpts,
-                executionPlane: filteredPlane,
+                // M1/G3: route to the node's hinted model (falls back to the parent provider).
+                provider: resolveProvider(ctx.parentOpts, ctx.spec.modelHint),
+                // M4/G5: cap the child run at the node's token budget (falls back to the inherited cap).
+                maxTotalTokens: ctx.spec.tokenBudget ?? ctx.parentOpts.maxTotalTokens,
+                executionPlane: execPlane,
                 agentId: ctx.spec.identity.agentId,
                 sessionLog: ctx.sessionLog,
                 skillDir: metaTools.has("skill") ? ctx.parentOpts.skillDir : undefined,
                 dreamStore: metaTools.has("memory") ? ctx.parentOpts.dreamStore : undefined,
                 knowledgeSource: metaTools.has("knowledge") ? ctx.parentOpts.knowledgeSource : undefined,
                 enablePlanTool: metaTools.has("update_plan") ? ctx.parentOpts.enablePlanTool : undefined,
+                // M5 v2.1: a workflow node's `start_workflow` flattens to the parent kernel (no nested pivot).
+                isWorkflowNode: ctx.isWorkflowNode,
             });
+            // #2-B-ii: parent preempt → interrupt the child (cancels its in-flight LLM call).
+            linkAbort(ctx.abortSignal, childRunner);
             const loop = new HarnessLoop(childRunner, ctx.harness.evalProvider, {
                 maxAttempts: ctx.harness.maxAttempts ?? 3,
             });
-            const outcome = await loop.run({
-                goal: ctx.spec.goal,
-                criteria: (ctx.spec.milestones?.phases.flatMap(p => p.criteria) ?? [])
-                    .filter((t) => typeof t === "string")
-                    .map(text => ({ text, required: true })),
-            });
+            let outcome;
+            try {
+                outcome = await loop.run({
+                    goal: ctx.spec.goal,
+                    criteria: (ctx.spec.milestones?.phases.flatMap(p => p.criteria) ?? [])
+                        .filter((t) => typeof t === "string")
+                        .map(text => ({ text, required: true })),
+                });
+            }
+            finally {
+                await cleanupWorktree();
+            }
             return {
                 agentId: ctx.spec.identity.agentId,
                 result: {

package/dist/runtime/workflow-control-flow.d.ts

@@ -0,0 +1,17 @@
+/** Instruction appended to a loop node's goal: do the next increment, and signal when done. */
+export declare function loopInstruction(maxIters: number): string;
+/** Instruction appended to a classify node's goal: pick exactly one of the kernel's branch labels. */
+export declare function classifyInstruction(labels: string[]): string;
+/** Build a tournament judge's goal: the controller's criterion + the two candidates to compare. */
+export declare function judgeGoal(criterion: string, leftOutput: string, rightOutput: string): string;
+/** Extract a loop stop signal from a loop iteration's output. Returns the `loopContinue` value, or
+ *  `undefined` when the agent gave no clear signal (⇒ the kernel runs the loop to `max_iters`).
+ *  Accepts `{loop_continue: bool}` or, leniently, `{done: bool}` (continue = !done). */
+export declare function extractLoopContinue(text: string): boolean | undefined;
+/** Extract the chosen branch label from a classifier's output. Prefers `{branch: "..."}`; falls back
+ *  to a bare label string that exactly matches one of the valid labels. Returns `undefined` when no
+ *  recognizable choice was made (the kernel then prunes every branch — a safe "none matched"). */
+export declare function extractClassifyBranch(text: string, labels: string[]): string | undefined;
+/** Extract a tournament judge's verdict ("left" or "right"). Defaults to "left" when the verdict is
+ *  unparseable, so the bracket always advances to a champion rather than stalling with no winner. */
+export declare function extractJudgeWinner(text: string): "left" | "right";