@deepstrike/sdk 0.2.10 → 0.2.12

package/dist/runtime/runner.js

@@ -3,11 +3,13 @@ import { resolvePermissionRequest } from "./execution-plane.js";
 import { getKernel } from "../kernel.js";
 import { peekProviderReplay, seedProviderReplayFromEvents } from "./provider-replay.js";
 import { sanitizeReplayText } from "./replay-sanitize.js";
-import { buildLlmCompletedEvent, buildRunTerminalEvent, buildWorkflowNodeCompletedEvent, recoverCompletedWorkflowNodes, repairEventsForRecovery, } from "./session-repair.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, workflowNodeToManifest, workflowNodeToSpec, workflowSpecToKernel, } from "../types/agent.js";
+import { agentRunSpecToKernel, findSpawnProcessObservation, milestoneCheckPass, milestoneCheckResultToKernel, spawnObservationToManifest, subAgentResultToKernel, submitWorkflowNodesToKernel, 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 { governancePolicyToKernelEvent } from "../governance.js";
 import { kernelObservationToSessionEvent, withCategory } from "./kernel-event-log.js";
 import { assertNativeProfile } from "./os-profile.js";
@@ -256,6 +258,86 @@ export class RuntimeRunner {
         });
         yield { type: "done", iterations: result.result.turnsUsed, totalTokens: result.result.totalTokensUsed, status: result.result.termination };
     }
+    /**
+     * G3: run one workflow node, enforcing its `output_schema` (if any). Without a schema this is a
+     * plain `orchestrator.run`. With one, the node's agent is instructed to emit conforming JSON, its
+     * output is validated (the supported JSON-Schema subset), and on mismatch the node is re-run once
+     * with the validation errors fed back. If it still does not conform, the node is failed with the
+     * 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) {
+        // 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) {
+            return this.runReduceNode(node, outputs ?? new Map());
+        }
+        const baseSpec = workflowNodeToSpec(node, parentSessionId);
+        const manifest = workflowNodeToManifest(node, parentSessionId);
+        // G4: surface the workflow's remaining budget to the node's agent so a coordinator can size its
+        // `submit_workflow_nodes` batch to what is available (empty string ⇒ unbounded, no note).
+        const budgetNote = workflowBudgetNote(budget);
+        const withBudget = (goal) => (budgetNote ? `${goal}\n\n${budgetNote}` : goal);
+        const mkCtx = (goal) => ({
+            parentOpts: this.opts,
+            parentSessionId,
+            spec: { ...baseSpec, goal: withBudget(goal) },
+            manifest,
+            sessionLog: this.opts.sessionLog,
+            ...(this.opts.subAgentHarness ? { harness: this.opts.subAgentHarness } : {}),
+        });
+        const schema = node.output_schema;
+        if (!schema)
+            return orchestrator.run(mkCtx(baseSpec.goal));
+        const MAX_ATTEMPTS = 2;
+        let last;
+        let lastErrors = [];
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+            const goal = attempt === 1
+                ? `${baseSpec.goal}\n\n${schemaInstruction(schema)}`
+                : `${baseSpec.goal}\n\n${schemaRetryInstruction(schema, lastErrors)}`;
+            const result = await orchestrator.run(mkCtx(goal));
+            const content = result.result.finalMessage?.content;
+            const text = typeof content === "string" ? content : content != null ? JSON.stringify(content) : "";
+            const v = validateAgainstSchema(extractJsonValue(text), schema);
+            if (v.ok)
+                return result;
+            last = result;
+            lastErrors = v.errors;
+        }
+        const reason = `output_schema validation failed after ${MAX_ATTEMPTS} attempts: ${lastErrors.join("; ")}`;
+        const fallback = last;
+        return {
+            ...fallback,
+            result: {
+                ...fallback.result,
+                termination: "error",
+                finalMessage: { role: "assistant", content: reason, toolCalls: [] },
+            },
+        };
+    }
+    /**
+     * G2: execute a deterministic reduce node. Looks up the named reducer (built-ins overlaid with
+     * `opts.reducers`), runs it over the node's dependency outputs (gathered from `outputs`), and
+     * returns a synthetic completion carrying the reducer's output — no LLM, zero tokens. An unknown
+     * reducer or a thrown reducer fails the node (`Error` termination → the kernel starves dependents).
+     */
+    runReduceNode(node, outputs) {
+        const ok = (content, termination) => ({
+            agentId: node.agent_id,
+            result: { termination, finalMessage: { role: "assistant", content, toolCalls: [] }, turnsUsed: 0, totalTokensUsed: 0 },
+        });
+        const reducer = resolveReducer(node.reducer, this.opts.reducers);
+        if (!reducer)
+            return ok(`unknown reducer "${node.reducer}"`, "error");
+        const inputs = (node.input_agent_ids ?? []).map(agentId => ({ agentId, output: outputs.get(agentId) ?? "" }));
+        try {
+            return ok(reducer(inputs), "completed");
+        }
+        catch (err) {
+            return ok(`reducer "${node.reducer}" threw: ${err instanceof Error ? err.message : String(err)}`, "error");
+        }
+    }
     /**
      * W0-ABI: run a declarative workflow DAG. The kernel owns the DAG and gates every node spawn
      * through the syscall trap; this driver runs each kernel-emitted batch of nodes in parallel,
@@ -275,26 +357,30 @@ export class RuntimeRunner {
             parent_session_id: parentSessionId,
             // W0-ABI resume: skip nodes already completed before an interruption.
             ...(opts?.resumedCompleted?.length ? { resumed_completed: opts.resumedCompleted } : {}),
+            // R3-1: re-apply recorded runtime submissions so dynamically-appended nodes are reconstructed.
+            ...(opts?.resumedSubmissions?.length ? { resumed_submissions: opts.resumedSubmissions } : {}),
         });
         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
+        // coordinator node's prompt reflects current headroom when it decides how much to submit.
+        const collectBudget = (obs) => obs.find(o => o.kind === "workflow_batch_spawned")?.budget;
         const findDone = (obs) => obs.find(o => o.kind === "workflow_completed");
         let done = findDone(observations);
         if (done)
             return { completed: done.completed ?? [], failed: done.failed ?? [] };
         let nodes = collectNodes(observations);
+        let budget = collectBudget(observations);
+        // G2: each completed node's output, keyed by agent id — a reduce node reads its dependencies'
+        // outputs from here. Deps always complete in an earlier round than the reduce node that needs
+        // them (the kernel keeps the reduce node un-ready until its deps finish), so this is populated.
+        const outputs = new Map();
         for (;;) {
             if (nodes.length === 0)
                 return { completed: [], failed: [] }; // nothing to run (e.g. all gated)
             // Run the currently-runnable nodes in parallel — each is independent within a round.
-            const results = await Promise.all(nodes.map(node => orchestrator.run({
-                parentOpts: this.opts,
-                parentSessionId,
-                spec: workflowNodeToSpec(node, parentSessionId),
-                manifest: workflowNodeToManifest(node, parentSessionId),
-                sessionLog: this.opts.sessionLog,
-                ...(this.opts.subAgentHarness ? { harness: this.opts.subAgentHarness } : {}),
-            })));
+            const roundBudget = budget;
+            const results = await Promise.all(nodes.map(node => this.runWorkflowNode(node, parentSessionId, orchestrator, roundBudget, 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
@@ -304,11 +390,32 @@ export class RuntimeRunner {
             const nextNodes = [];
             done = undefined;
             for (const result of results) {
+                // G2: record this node's output so a downstream reduce node can consume it.
+                const outContent = result.result.finalMessage?.content;
+                outputs.set(result.agentId, typeof outContent === "string" ? outContent : outContent != null ? JSON.stringify(outContent) : "");
+                // R3-1: if this node's agent submitted more nodes, append them to the parent DAG BEFORE
+                // reporting the node's completion — the workflow is still active (the kernel hasn't seen this
+                // node finish), so even a submission from the last running node keeps the DAG alive. The
+                // appended nodes' `workflow_batch_spawned` is collected into this round like any other.
+                if (result.submittedNodes?.length) {
+                    // G1: stamp the submitting node's agent id so the kernel can coerce a quarantined
+                    // submitter's nodes to quarantined (no topological privilege escalation).
+                    const submitEvent = submitWorkflowNodesToKernel(result.submittedNodes, result.agentId);
+                    const subObs = kernelApply(runtime, this.pendingObservations, submitEvent);
+                    nextNodes.push(...collectNodes(subObs));
+                    budget = collectBudget(subObs) ?? budget;
+                    // R3-1: persist the submission (kernel-shape nodes) so resume can re-apply it.
+                    await this.opts.sessionLog.append(parentSessionId, buildWorkflowNodesSubmittedEvent({
+                        turn: runtime.turn(),
+                        nodes: submitEvent.nodes ?? [],
+                    }));
+                }
                 const obs = kernelApply(runtime, this.pendingObservations, {
                     kind: "sub_agent_completed",
                     result: subAgentResultToKernel(result),
                 });
                 nextNodes.push(...collectNodes(obs));
+                budget = collectBudget(obs) ?? budget;
                 const d = findDone(obs);
                 if (d)
                     done = d;
@@ -336,7 +443,8 @@ export class RuntimeRunner {
         }
         const events = await this.opts.sessionLog.read(this.currentSessionId);
         const resumedCompleted = recoverCompletedWorkflowNodes(events);
-        return this.runWorkflow(spec, { resumedCompleted });
+        const resumedSubmissions = recoverSubmittedWorkflowNodes(events);
+        return this.runWorkflow(spec, { resumedCompleted, resumedSubmissions });
     }
     interrupt() { this.interrupted = true; }
     async *run(req) {
@@ -350,9 +458,10 @@ export class RuntimeRunner {
                 criteria: req.criteria ?? [],
                 agent_id: this.opts.agentId,
                 system_prompt: this.opts.systemPrompt,
+                ...(req.attachments?.length ? { attachments: req.attachments } : {}),
             });
         }
-        yield* this.execute(req.sessionId, req.goal, req.criteria ?? [], req.extensions, prior.length > 0 ? prior : undefined, midRun);
+        yield* this.execute(req.sessionId, req.goal, req.criteria ?? [], req.extensions, prior.length > 0 ? prior : undefined, midRun, req.attachments);
     }
     async *wake(sessionId, extensions) {
         const events = await this.opts.sessionLog.read(sessionId);
@@ -362,7 +471,7 @@ export class RuntimeRunner {
         if (!startEntry)
             throw new Error(`No run_started event for session: ${sessionId}`);
         const start = startEntry.event;
-        yield* this.execute(sessionId, start.goal, start.criteria, extensions, events, true);
+        yield* this.execute(sessionId, start.goal, start.criteria, extensions, events, true, start.attachments);
     }
     async *dream(agentId, nowMs = Date.now()) {
         if (!this.opts.dreamStore)
@@ -515,7 +624,7 @@ export class RuntimeRunner {
         }
         return { approved, denied, events };
     }
-    async *execute(sessionId, goal, criteria, extensions, priorEvents, resumeMidRun = false) {
+    async *execute(sessionId, goal, criteria, extensions, priorEvents, resumeMidRun = false, attachments) {
         this.interrupted = false;
         this.pendingObservations = [];
         this.pendingSpoolOutputs.clear();
@@ -683,6 +792,16 @@ export class RuntimeRunner {
                 },
             });
         }
+        // Multimodal upload: seed the user's attachments (images/audio) as a history
+        // message before start_run pushes the "[TASK STATE]" anchor. init_task does not
+        // clear history, so order becomes [attachment user msg, "Proceed…"] — both land
+        // in the first render. On resume the message is already in the replayed history.
+        if (!resumeMidRun && attachments?.length) {
+            kernelApply(runtime, this.pendingObservations, {
+                kind: "add_history_message",
+                message: attachmentsToKernelMessage(attachments),
+            });
+        }
         let action = resumeMidRun
             ? kernelAction(runtime, this.pendingObservations, { kind: "resume" })
             : kernelAction(runtime, this.pendingObservations, startPayload);
@@ -827,8 +946,9 @@ export class RuntimeRunner {
                     resultSpool: this.opts.resultSpool ?? new LargeResultSpool(),
                 };
                 const toolResults = [];
-                const normalCalls = allCalls.filter(c => c.name !== "update_plan");
+                const normalCalls = allCalls.filter(c => c.name !== "update_plan" && c.name !== "submit_workflow_nodes");
                 const planCalls = allCalls.filter(c => c.name === "update_plan");
+                const submitCalls = allCalls.filter(c => c.name === "submit_workflow_nodes");
                 for (const call of planCalls) {
                     const update = parseUpdatePlanArgs(call.arguments);
                     kernelApply(runtime, this.pendingObservations, {
@@ -839,6 +959,18 @@ export class RuntimeRunner {
                     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) {
+                    const nodes = 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;
@@ -1106,6 +1238,31 @@ export class RuntimeRunner {
 function isMidRun(events) {
     return events.length > 0 && !events.some(e => e.event.kind === "run_terminal");
 }
+/**
+ * Build a kernel `add_history_message` payload from user attachments: a `user`
+ * message whose content is the multimodal parts in the kernel's serde shape
+ * (`Content::Parts`; image `media_type`, not `mediaType`). Lets a caller upload
+ * images/audio with the task — the message lands in history before the first render.
+ */
+function attachmentsToKernelMessage(parts) {
+    const content = parts.map(p => {
+        if (p.type === "image") {
+            return {
+                type: "image",
+                ...(p.url ? { url: p.url } : {}),
+                ...(p.data ? { data: p.data } : {}),
+                ...(p.mediaType ? { media_type: p.mediaType } : {}),
+                ...(p.detail ? { detail: p.detail } : {}),
+            };
+        }
+        if (p.type === "audio")
+            return { type: "audio", data: p.data, media_type: p.mediaType };
+        if (p.type === "text")
+            return { type: "text", text: p.text };
+        return { type: "text", text: "" };
+    });
+    return { role: "user", content };
+}
 function compressionAction(action) {
     if (action === "snip_compact" ||
         action === "micro_compact" ||
@@ -1317,3 +1474,16 @@ function parseUpdatePlanArgs(argsStr) {
             : parsed.blocked_on,
     };
 }
+/** R3-1: parse the `submit_workflow_nodes` tool arguments (`{ nodes: WorkflowNodeSpec[] }`). Node
+ *  shapes are trusted structurally here; the kernel validates them (dep range, quarantine, quota) on
+ *  append. A malformed payload yields no nodes rather than throwing. */
+function parseSubmitWorkflowNodesArgs(argsStr) {
+    let parsed = {};
+    try {
+        parsed = JSON.parse(argsStr);
+    }
+    catch {
+        // Ignore parse error → no nodes submitted.
+    }
+    return Array.isArray(parsed.nodes) ? parsed.nodes : [];
+}

package/dist/runtime/session-log.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderReplay, ToolCall, ToolErrorKind } from "../types.js";
+import type { ContentPart, ProviderReplay, ToolCall, ToolErrorKind } from "../types.js";
 import type { KernelEventCategory, KernelPrimitive } from "./kernel-event-log.js";
 export type RollbackReason = {
     kind: "fatal_tool_error";
@@ -26,6 +26,7 @@ export type SessionEvent = {
     criteria: string[];
     agent_id?: string;
     system_prompt?: string;
+    attachments?: ContentPart[];
 } | {
     kind: "llm_completed";
     turn: number;
@@ -243,6 +244,13 @@ export type SessionEvent = {
     primitive?: KernelPrimitive;
     agent_id: string;
     termination: string;
+} | {
+    kind: "workflow_nodes_submitted";
+    turn: number;
+    category?: KernelEventCategory;
+    primitive?: KernelPrimitive;
+    /** Kernel-shape (snake_case) submitted node specs — persisted so resume can re-apply them. */
+    nodes: Record<string, unknown>[];
 } | {
     kind: "workflow_batch_spawned";
     turn: number;

package/dist/runtime/session-repair.d.ts

@@ -58,3 +58,17 @@ export declare function recoverCompletedWorkflowNodes(events: Array<{
     seq: number;
     event: SessionEvent;
 }>): string[];
+/** R3-1: build workflow_nodes_submitted for persistence after a runtime submission, so resume can
+ *  re-apply it. `nodes` is the kernel-shape (snake_case) submitted node array. */
+export declare function buildWorkflowNodesSubmittedEvent(input: {
+    turn: number;
+    nodes: Record<string, unknown>[];
+}): Extract<SessionEvent, {
+    kind: "workflow_nodes_submitted";
+}>;
+/** R3-1: recover the runtime submission batches (in order) from a session event stream, to rebuild
+ *  `resumed_submissions` for resumeWorkflow so dynamically-appended nodes are reconstructed. */
+export declare function recoverSubmittedWorkflowNodes(events: Array<{
+    seq: number;
+    event: SessionEvent;
+}>): Record<string, unknown>[][];

package/dist/runtime/session-repair.js

@@ -76,3 +76,18 @@ export function recoverCompletedWorkflowNodes(events) {
     }
     return completed;
 }
+/** R3-1: build workflow_nodes_submitted for persistence after a runtime submission, so resume can
+ *  re-apply it. `nodes` is the kernel-shape (snake_case) submitted node array. */
+export function buildWorkflowNodesSubmittedEvent(input) {
+    return { kind: "workflow_nodes_submitted", turn: input.turn, nodes: input.nodes };
+}
+/** R3-1: recover the runtime submission batches (in order) from a session event stream, to rebuild
+ *  `resumed_submissions` for resumeWorkflow so dynamically-appended nodes are reconstructed. */
+export function recoverSubmittedWorkflowNodes(events) {
+    const submissions = [];
+    for (const { event } of events) {
+        if (event.kind === "workflow_nodes_submitted")
+            submissions.push(event.nodes);
+    }
+    return submissions;
+}

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

@@ -74,15 +74,24 @@ export class SubAgentOrchestrator {
                     totalTokensUsed: outcome.totalTokens,
                     ...(outcome.result ? { finalMessage: { role: "assistant", content: outcome.result, toolCalls: [] } } : {}),
                 },
+                // R3-1: surface nodes the agent submitted under the harness so `runWorkflow` appends them.
+                ...(outcome.submittedNodes?.length ? { submittedNodes: outcome.submittedNodes } : {}),
             };
         }
         let done;
         let finalText = "";
+        // R3-1: collect any nodes this node's agent submitted via the `submit_workflow_nodes` tool (the
+        // runner surfaces them as `workflow_nodes_submitted` because the workflow lives in the parent
+        // kernel, not this child's). `runWorkflow` sends them to the parent kernel.
+        const submittedNodes = [];
         for await (const evt of this.stream(ctx)) {
             if (evt.type === "text_delta")
                 finalText += evt.delta;
             if (evt.type === "done")
                 done = evt;
+            if (evt.type === "workflow_nodes_submitted") {
+                submittedNodes.push(...evt.nodes);
+            }
         }
         const loopResult = {
             termination: terminationFromStatus(done?.status ?? "error"),
@@ -90,7 +99,11 @@ export class SubAgentOrchestrator {
             totalTokensUsed: done?.totalTokens ?? 0,
             ...(finalText ? { finalMessage: { role: "assistant", content: finalText, toolCalls: [] } } : {}),
         };
-        return { agentId: ctx.spec.identity.agentId, result: loopResult };
+        return {
+            agentId: ctx.spec.identity.agentId,
+            result: loopResult,
+            ...(submittedNodes.length ? { submittedNodes } : {}),
+        };
     }
 }
 export const defaultSubAgentOrchestrator = new SubAgentOrchestrator();

package/dist/types/agent.d.ts

@@ -1,4 +1,4 @@
-import type { Message } from "../types.js";
+import type { Message, ToolSchema } from "../types.js";
 export type KernelAgentRole = "explore" | "plan" | "implement" | "verify" | "custom";
 export type AgentIsolation = "shared" | "read_only" | "worktree" | "remote";
 export type ContextInheritance = "none" | "system_only" | "full";
@@ -52,6 +52,11 @@ export interface LoopResult {
 export interface SubAgentResult {
     agentId: string;
     result: LoopResult;
+    /** R3-1: nodes this node's agent asked to append to the parent workflow DAG (via the
+     *  `submit_workflow_nodes` tool). Surfaced by the orchestrator; the `runWorkflow` driver sends
+     *  them to the parent kernel before this node's completion. SDK-internal — not sent over the wire
+     *  on the kernel `SubAgentResult` (see `subAgentResultToKernel`). */
+    submittedNodes?: WorkflowNodeSpec[];
 }
 export interface MilestoneCheckResult {
     phaseId: string;
@@ -92,6 +97,12 @@ export interface WorkflowNodeSpec {
     modelHint?: string;
     /** W3: `quarantined` nodes read untrusted content and must run without privileges. */
     trust?: NodeTrust;
+    /** G3: JSON Schema the node's output must conform to. The kernel carries it to the spawn
+     *  descriptor; the runner instructs the agent and validates + retries once on mismatch. */
+    outputSchema?: Record<string, unknown>;
+    /** G2: make this a deterministic *reduce* node — it runs no LLM agent. The runner routes it to the
+     *  registered reducer of this name, over its `dependsOn` nodes' outputs (dedupe / filter / merge). */
+    reducer?: string;
     /** Indices of nodes this node depends on. */
     dependsOn?: number[];
 }
@@ -109,9 +120,40 @@ export interface WorkflowSpawnInfo {
     model_hint?: string;
     /** W3 trust level: `"trusted"` | `"quarantined"`. */
     trust?: string;
+    /** G3: JSON Schema the node's output must conform to (carried verbatim from the spec). */
+    output_schema?: Record<string, unknown>;
+    /** G2: for a reduce node, the name of the registered host function to run (no LLM). */
+    reducer?: string;
+    /** G2: the dependency agent ids whose outputs a reduce node consumes. */
+    input_agent_ids?: string[];
 }
+/** G4 budget-as-signal: the workflow's remaining headroom under the active quota, carried on the
+ *  `workflow_batch_spawned` observation so a coordinator node can scale its next submission. */
+export interface WorkflowBudget {
+    nodes_used: number;
+    nodes_max?: number;
+    nodes_remaining?: number;
+    running_subagents: number;
+    max_concurrent_subagents?: number;
+    concurrency_remaining?: number;
+}
+/** G4: a concise, human-readable budget note appended to a coordinator node's goal, so its agent can
+ *  size a `submit_workflow_nodes` batch to what is actually available. Returns "" when nothing is
+ *  bounded (no quota ⇒ no signal). */
+export declare function workflowBudgetNote(budget: WorkflowBudget | undefined): string;
+/** Map one host `WorkflowNodeSpec` to its snake_case kernel JSON. Shared by `load_workflow` (the
+ *  whole spec) and `submit_workflow_nodes` (R3-1 runtime append) so the two encodings never drift. */
+export declare function workflowNodeSpecToKernel(n: WorkflowNodeSpec): Record<string, unknown>;
 /** Map a host `WorkflowSpec` to the snake_case kernel JSON (`load_workflow.spec`). */
 export declare function workflowSpecToKernel(spec: WorkflowSpec): Record<string, unknown>;
+/** R3-1: map a batch of host nodes to the `submit_workflow_nodes` kernel event body. G1: pass
+ *  `submitterAgentId` (the node that requested the append) so the kernel can enforce no-privilege-
+ *  escalation — a quarantined submitter's nodes are coerced to quarantined. Omitted ⇒ no coercion. */
+export declare function submitWorkflowNodesToKernel(nodes: WorkflowNodeSpec[], submitterAgentId?: string): Record<string, unknown>;
+/** R3-1: the tool a workflow-coordinator node's agent calls to append work to the running DAG
+ *  (true loop-until-done / dynamic fan-out). Give it to nodes meant to fan out; the runner intercepts
+ *  the call and routes the nodes to the parent kernel (the child's own kernel holds no workflow). */
+export declare const submitWorkflowNodesTool: ToolSchema;
 /** Build a sub-agent run spec for a kernel-generated workflow node. */
 export declare function workflowNodeToSpec(node: WorkflowSpawnInfo, parentSessionId: string): AgentRunSpec;
 /** Build the host manifest for a kernel-generated workflow node. */

package/dist/types/agent.js

@@ -94,29 +94,116 @@ export function milestoneCheckPass(phaseId) {
 export function milestoneCheckFail(phaseId, reason) {
     return { phaseId, passed: false, reason };
 }
+/** G4: a concise, human-readable budget note appended to a coordinator node's goal, so its agent can
+ *  size a `submit_workflow_nodes` batch to what is actually available. Returns "" when nothing is
+ *  bounded (no quota ⇒ no signal). */
+export function workflowBudgetNote(budget) {
+    if (!budget)
+        return "";
+    const parts = [];
+    if (budget.nodes_remaining != null && budget.nodes_max != null) {
+        parts.push(`nodes ${budget.nodes_used}/${budget.nodes_max} used, ${budget.nodes_remaining} remaining`);
+    }
+    if (budget.concurrency_remaining != null && budget.max_concurrent_subagents != null) {
+        parts.push(`concurrency ${budget.running_subagents}/${budget.max_concurrent_subagents} running, ${budget.concurrency_remaining} free`);
+    }
+    if (parts.length === 0)
+        return "";
+    return (`[workflow budget] ${parts.join(" · ")}. ` +
+        "If you submit more workflow nodes, keep the batch within the remaining node budget.");
+}
+/** Map one host `WorkflowNodeSpec` to its snake_case kernel JSON. Shared by `load_workflow` (the
+ *  whole spec) and `submit_workflow_nodes` (R3-1 runtime append) so the two encodings never drift. */
+export function workflowNodeSpecToKernel(n) {
+    const task = typeof n.task === "string" ? { goal: n.task } : n.task;
+    return {
+        task: {
+            goal: task.goal,
+            // `criteria` is required by the kernel's RuntimeTask serde (no default).
+            criteria: task.criteria ?? [],
+            ...(task.lane ? { lane: task.lane } : {}),
+        },
+        role: n.role,
+        // role/isolation/context_inheritance have no serde default in the kernel — always emit.
+        isolation: n.isolation ?? "shared",
+        context_inheritance: n.contextInheritance ?? "none",
+        ...(n.modelHint ? { model_hint: n.modelHint } : {}),
+        ...(n.trust && n.trust !== "trusted" ? { trust: n.trust } : {}),
+        ...(n.outputSchema ? { output_schema: n.outputSchema } : {}),
+        // G2: a reducer name lowers to the kernel's `NodeKind::Reduce` (serde-tagged by `type`).
+        ...(n.reducer ? { kind: { type: "reduce", reducer: n.reducer } } : {}),
+        ...(n.dependsOn && n.dependsOn.length ? { depends_on: n.dependsOn } : {}),
+    };
+}
 /** Map a host `WorkflowSpec` to the snake_case kernel JSON (`load_workflow.spec`). */
 export function workflowSpecToKernel(spec) {
+    return { nodes: spec.nodes.map(workflowNodeSpecToKernel) };
+}
+/** R3-1: map a batch of host nodes to the `submit_workflow_nodes` kernel event body. G1: pass
+ *  `submitterAgentId` (the node that requested the append) so the kernel can enforce no-privilege-
+ *  escalation — a quarantined submitter's nodes are coerced to quarantined. Omitted ⇒ no coercion. */
+export function submitWorkflowNodesToKernel(nodes, submitterAgentId) {
     return {
-        nodes: spec.nodes.map(n => {
-            const task = typeof n.task === "string" ? { goal: n.task } : n.task;
-            return {
-                task: {
-                    goal: task.goal,
-                    // `criteria` is required by the kernel's RuntimeTask serde (no default).
-                    criteria: task.criteria ?? [],
-                    ...(task.lane ? { lane: task.lane } : {}),
-                },
-                role: n.role,
-                // role/isolation/context_inheritance have no serde default in the kernel — always emit.
-                isolation: n.isolation ?? "shared",
-                context_inheritance: n.contextInheritance ?? "none",
-                ...(n.modelHint ? { model_hint: n.modelHint } : {}),
-                ...(n.trust && n.trust !== "trusted" ? { trust: n.trust } : {}),
-                ...(n.dependsOn && n.dependsOn.length ? { depends_on: n.dependsOn } : {}),
-            };
-        }),
+        kind: "submit_workflow_nodes",
+        nodes: nodes.map(workflowNodeSpecToKernel),
+        ...(submitterAgentId ? { submitter_agent_id: submitterAgentId } : {}),
     };
 }
+/** R3-1: the tool a workflow-coordinator node's agent calls to append work to the running DAG
+ *  (true loop-until-done / dynamic fan-out). Give it to nodes meant to fan out; the runner intercepts
+ *  the call and routes the nodes to the parent kernel (the child's own kernel holds no workflow). */
+export const submitWorkflowNodesTool = {
+    name: "submit_workflow_nodes",
+    description: "Append new nodes to the running workflow DAG (dynamic fan-out / loop-until-done). Each node " +
+        "spawns as a gated sub-agent. Use when you discover more work that should run as its own node.",
+    parameters: JSON.stringify({
+        type: "object",
+        properties: {
+            nodes: {
+                type: "array",
+                description: "Workflow nodes to append; each runs as a gated sub-agent.",
+                items: {
+                    type: "object",
+                    properties: {
+                        task: {
+                            description: "The node's goal: a string, or an object { goal, criteria?, lane? }.",
+                            oneOf: [
+                                { type: "string" },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        goal: { type: "string" },
+                                        criteria: { type: "array", items: { type: "string" } },
+                                    },
+                                    required: ["goal"],
+                                },
+                            ],
+                        },
+                        role: { type: "string", enum: ["explore", "plan", "implement", "verify", "custom"] },
+                        isolation: { type: "string", enum: ["shared", "read_only", "worktree", "remote"] },
+                        contextInheritance: { type: "string", enum: ["none", "system_only", "full"] },
+                        trust: { type: "string", enum: ["trusted", "quarantined"] },
+                        outputSchema: {
+                            type: "object",
+                            description: "Optional JSON Schema the node's output must conform to (validated + retried SDK-side).",
+                        },
+                        reducer: {
+                            type: "string",
+                            description: "Make this a deterministic reduce node (no LLM); names a registered reducer.",
+                        },
+                        dependsOn: {
+                            type: "array",
+                            items: { type: "integer" },
+                            description: "Batch-relative, backward-only dependency indices within this submission.",
+                        },
+                    },
+                    required: ["task", "role"],
+                },
+            },
+        },
+        required: ["nodes"],
+    }),
+};
 /** Build a sub-agent run spec for a kernel-generated workflow node. */
 export function workflowNodeToSpec(node, parentSessionId) {
     return {