@deepstrike/sdk 0.2.15 → 0.2.17

package/dist/types/agent.js

@@ -85,6 +85,11 @@ export function subAgentResultToKernel(result) {
                 : null,
             turns_used: result.result.turnsUsed,
             total_tokens_used: result.result.totalTokensUsed,
+            // A#2: control-flow signals — additive, omitted on the wire when unset so a plain spawn's
+            // result is byte-identical to before. The kernel reads each only for the matching node kind.
+            ...(result.result.loopContinue !== undefined ? { loop_continue: result.result.loopContinue } : {}),
+            ...(result.result.classifyBranch !== undefined ? { classify_branch: result.result.classifyBranch } : {}),
+            ...(result.result.tournamentWinner !== undefined ? { tournament_winner: result.result.tournamentWinner } : {}),
         },
     };
 }
@@ -107,22 +112,49 @@ export function workflowBudgetNote(budget) {
     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 (budget.tokens_remaining != null && budget.tokens_max != null) {
+        parts.push(`tokens ${budget.tokens_used ?? 0}/${budget.tokens_max} used, ${budget.tokens_remaining} remaining`);
+    }
     if (parts.length === 0)
         return "";
     return (`[workflow budget] ${parts.join(" · ")}. ` +
-        "If you submit more workflow nodes, keep the batch within the remaining node budget.");
+        "If you submit more workflow nodes, keep the batch within the remaining node and token budget.");
+}
+/** Normalize a `WorkflowTaskSpec` (object or bare goal string) to the kernel's `RuntimeTask` JSON. */
+function workflowTaskToKernel(t) {
+    const task = typeof t === "string" ? { goal: t } : t;
+    return {
+        goal: task.goal,
+        // `criteria` is required by the kernel's RuntimeTask serde (no default).
+        criteria: task.criteria ?? [],
+        ...(task.lane ? { lane: task.lane } : {}),
+    };
+}
+/** Lower a node's control-flow kind to the kernel's serde-tagged `NodeKind` JSON, or `undefined` for
+ *  a plain spawn. `reducer` / `loop` / `classify` / `tournament` are mutually exclusive — declaring
+ *  more than one is a spec error (a node has exactly one kind). */
+function nodeKindToKernel(n) {
+    const declared = [n.reducer != null, n.loop != null, n.classify != null, n.tournament != null].filter(Boolean).length;
+    if (declared > 1) {
+        throw new Error("a workflow node may declare at most one of: reducer, loop, classify, tournament");
+    }
+    if (n.reducer != null)
+        return { type: "reduce", reducer: n.reducer };
+    if (n.loop != null)
+        return { type: "loop", max_iters: n.loop.maxIters };
+    if (n.classify != null) {
+        return { type: "classify", branches: n.classify.branches.map(b => ({ label: b.label, nodes: b.nodes })) };
+    }
+    if (n.tournament != null)
+        return { type: "tournament", entrants: n.tournament.entrants.map(workflowTaskToKernel) };
+    return undefined;
 }
 /** 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;
+    const kind = nodeKindToKernel(n);
     return {
-        task: {
-            goal: task.goal,
-            // `criteria` is required by the kernel's RuntimeTask serde (no default).
-            criteria: task.criteria ?? [],
-            ...(task.lane ? { lane: task.lane } : {}),
-        },
+        task: workflowTaskToKernel(n.task),
         role: n.role,
         // role/isolation/context_inheritance have no serde default in the kernel — always emit.
         isolation: n.isolation ?? "shared",
@@ -130,8 +162,10 @@ export function workflowNodeSpecToKernel(n) {
         ...(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 } } : {}),
+        // A#2/G2: loop / classify / tournament / reduce lower to a serde-tagged `NodeKind`; spawn omits it.
+        ...(kind ? { kind } : {}),
+        // M4/G5: per-node token cap (additive; omitted when unset).
+        ...(n.tokenBudget != null ? { token_budget: n.tokenBudget } : {}),
         ...(n.dependsOn && n.dependsOn.length ? { depends_on: n.dependsOn } : {}),
     };
 }
@@ -149,24 +183,94 @@ export function submitWorkflowNodesToKernel(nodes, submitterAgentId) {
         ...(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({
+/** M5/G1: map an agent-authored spec to the `submit_workflow` kernel event body (the agent-reachable
+ *  `Syscall::LoadWorkflow`). The kernel bootstraps the DAG when none is active, else flattens onto it.
+ *  `parentSessionId` seeds child session ids on bootstrap; `submitterAgentId` carries G1 trust coercion
+ *  on the flatten case (a quarantined author's nodes are coerced quarantined). */
+export function submitWorkflowToKernel(spec, parentSessionId, submitterAgentId) {
+    return {
+        kind: "submit_workflow",
+        spec: workflowSpecToKernel(spec),
+        parent_session_id: parentSessionId,
+        ...(submitterAgentId ? { submitter_agent_id: submitterAgentId } : {}),
+    };
+}
+/** Shared JSON-Schema for a workflow-node batch (a DAG). Used by both `submit_workflow_nodes`
+ *  (append) and `start_workflow` (M5 v1: author a sub-workflow), so the two tools never drift. */
+const workflowNodesArraySchema = {
+    type: "array",
+    description: "Workflow nodes (a DAG); each runs as a gated sub-agent. A node may declare ONE control-flow kind " +
+        "— `loop` / `classify` / `tournament` / `reducer` — otherwise it is a plain spawn. `dependsOn` and " +
+        "`classify.branches[].nodes` are batch-relative (index 0 = this batch's first node).",
+    items: {
         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? }.",
+            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).",
+            },
+            modelHint: {
+                type: "string",
+                description: "Preferred model for this node (e.g. \"opus\"/\"sonnet\"/\"haiku\"); the host routes it.",
+            },
+            reducer: {
+                type: "string",
+                description: "Make this a deterministic reduce node (no LLM); names a registered reducer.",
+            },
+            loop: {
+                type: "object",
+                description: "Make this a loop node: re-run its agent up to maxIters times, ending early when it reports done.",
+                properties: { maxIters: { type: "integer", description: "Hard iteration cap." } },
+                required: ["maxIters"],
+            },
+            classify: {
+                type: "object",
+                description: "Make this a classify node: its agent picks one branch label; that branch's nodes run, the rest are pruned.",
+                properties: {
+                    branches: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                label: { type: "string" },
+                                nodes: {
+                                    type: "array",
+                                    items: { type: "integer" },
+                                    description: "Batch-relative indices of the nodes to run when this branch is chosen.",
+                                },
+                            },
+                            required: ["label", "nodes"],
+                        },
+                    },
+                },
+                required: ["branches"],
+            },
+            tournament: {
+                type: "object",
+                description: "Make this a tournament controller: generate each entrant, then pairwise-judge to one winner (this node's task is the criterion).",
+                properties: {
+                    entrants: {
+                        type: "array",
+                        description: "≥2 candidate tasks to generate and judge.",
+                        items: {
                             oneOf: [
                                 { type: "string" },
                                 {
@@ -179,31 +283,63 @@ export const submitWorkflowNodesTool = {
                                 },
                             ],
                         },
-                        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: ["entrants"],
+            },
+            tokenBudget: {
+                type: "integer",
+                description: "Cap this node's child run at this many cumulative tokens.",
+            },
+            dependsOn: {
+                type: "array",
+                items: { type: "integer" },
+                description: "Batch-relative, backward-only dependency indices within this submission.",
             },
         },
+        required: ["task", "role"],
+    },
+};
+/** 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. " +
+        "A node may declare ONE control-flow kind — `loop` (re-run until done), `classify` (route to one " +
+        "branch), `tournament` (pairwise-judge candidates to a winner), or `reducer` (deterministic, no " +
+        "LLM) — otherwise it is a plain spawn. Within a submission, `dependsOn` and `classify.branches[].nodes` " +
+        "are batch-relative (index 0 = this batch's first node).",
+    parameters: JSON.stringify({
+        type: "object",
+        properties: { nodes: workflowNodesArraySchema },
         required: ["nodes"],
     }),
 };
+/** M5 v1 (flatten): the tool an agent calls to **author a sub-workflow** — a cohesive DAG of nodes
+ *  (incl. loop/classify/tournament/reduce) composed onto the running workflow. Mechanically it lowers
+ *  to the same append path as `submit_workflow_nodes` (a `WorkflowSpec` is a node batch), but reads as
+ *  "write a harness" rather than "append nodes". v2 adds top-level bootstrap (the `LoadWorkflow`
+ *  kernel syscall) so a plain run can start a workflow from scratch. */
+export const startWorkflowTool = {
+    name: "start_workflow",
+    description: "Author and run a sub-workflow: a DAG of nodes (fan-out / classify / tournament / loop / reduce) " +
+        "composed onto the current run. Use to structure a multi-step task as its own harness. The nodes " +
+        "spawn as gated sub-agents; `dependsOn` / `classify.branches[].nodes` are spec-relative.",
+    parameters: JSON.stringify({
+        type: "object",
+        properties: {
+            spec: {
+                type: "object",
+                description: "The workflow specification.",
+                properties: { nodes: workflowNodesArraySchema },
+                required: ["nodes"],
+            },
+        },
+        required: ["spec"],
+    }),
+};
 /** Build a sub-agent run spec for a kernel-generated workflow node. */
 export function workflowNodeToSpec(node, parentSessionId) {
     return {
@@ -216,6 +352,10 @@ export function workflowNodeToSpec(node, parentSessionId) {
         role: node.role,
         isolation: node.isolation,
         goal: node.goal,
+        // M1/G3: carry the node's model preference so the orchestrator can route to a provider.
+        ...(node.model_hint ? { modelHint: node.model_hint } : {}),
+        // M4/G5: carry the node's token cap so the orchestrator can bound the child run.
+        ...(node.token_budget != null ? { tokenBudget: node.token_budget } : {}),
     };
 }
 /** Build the host manifest for a kernel-generated workflow node. */

package/dist/types.d.ts

@@ -304,7 +304,12 @@ export interface LLMProvider {
      */
     assessReplayability?(context: RenderedContext, extensions?: Record<string, unknown>): ReplayabilityAssessment;
     complete(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>): Promise<Message>;
-    stream(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>, state?: ProviderRunState): AsyncIterable<StreamEvent>;
+    stream(context: RenderedContext, tools: ToolSchema[], extensions?: Record<string, unknown>, state?: ProviderRunState, 
+    /** #2-B-ii: when provided, a preempting `InterruptNow` (or `interrupt()`) aborts the in-flight
+     *  request. SDK-client providers should forward it to the client (`{ signal }`); the runner also
+     *  breaks the consume loop on abort, so providers that ignore it still stop processing immediately
+     *  (only the socket lingers). Optional ⇒ backward-compatible; providers may ignore it. */
+    signal?: AbortSignal): AsyncIterable<StreamEvent>;
 }
 /**
  * Optional async summarizer called after context compression.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.15",
+    "@deepstrike/core": "0.2.17",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },