@deepstrike/wasm 0.2.16 → 0.2.18

package/dist/runtime/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 } : {}),
         },
     };
 }
@@ -105,31 +110,58 @@ 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. */
+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 a host `WorkflowSpec` to the snake_case kernel JSON (`load_workflow.spec`). */
 /** Map one host `WorkflowNodeSpec` to its snake_case kernel JSON. Shared by `load_workflow` and
  *  `submit_workflow_nodes` (R3-1) 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,
         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 } } : {}),
+        // 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 } : {}),
     };
 }
@@ -146,33 +178,113 @@ export function submitWorkflowNodesToKernel(nodes, submitterAgentId) {
         ...(submitterAgentId ? { submitter_agent_id: submitterAgentId } : {}),
     };
 }
+/** 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. */
+export function submitWorkflowToKernel(spec, parentSessionId, submitterAgentId) {
+    return {
+        kind: "submit_workflow",
+        spec: workflowSpecToKernel(spec),
+        parent_session_id: parentSessionId,
+        ...(submitterAgentId ? { submitter_agent_id: submitterAgentId } : {}),
+    };
+}
 /** R3-1: the tool a workflow-coordinator node's agent calls to append work to the running DAG. */
+/** 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",
+    items: {
+        type: "object",
+        properties: {
+            task: { description: "The node's goal: a string, or { goal, criteria?, lane? }." },
+            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." },
+            modelHint: { type: "string", description: "Preferred model for this node (e.g. \"opus\"/\"sonnet\"); 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 up to maxIters times, ending early when the agent reports done.",
+                properties: { maxIters: { type: "integer", description: "Hard iteration cap." } },
+                required: ["maxIters"],
+            },
+            classify: {
+                type: "object",
+                description: "Make this a classify node: pick 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 node indices for this branch." },
+                            },
+                            required: ["label", "nodes"],
+                        },
+                    },
+                },
+                required: ["branches"],
+            },
+            tournament: {
+                type: "object",
+                description: "Make this a tournament controller: generate each entrant, then pairwise-judge to one winner.",
+                properties: {
+                    entrants: {
+                        type: "array",
+                        description: "≥2 candidate tasks to generate and judge.",
+                        items: {
+                            oneOf: [
+                                { type: "string" },
+                                { type: "object", properties: { goal: { type: "string" }, criteria: { type: "array", items: { type: "string" } } }, required: ["goal"] },
+                            ],
+                        },
+                    },
+                },
+                required: ["entrants"],
+            },
+            tokenBudget: { type: "integer", description: "Cap this node's child run at this many cumulative tokens." },
+            dependsOn: { type: "array", items: { type: "integer" } },
+        },
+        required: ["task", "role"],
+    },
+};
 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.",
+        "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` / `classify` / `tournament` / `reducer` — " +
+        "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
+ *  composed onto the running workflow. Lowers to the same append path as `submit_workflow_nodes`
+ *  (a `WorkflowSpec` is a node batch). v2 adds top-level bootstrap (the `LoadWorkflow` syscall). */
+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: {
-            nodes: {
-                type: "array",
-                items: {
-                    type: "object",
-                    properties: {
-                        task: { description: "The node's goal: a string, or { goal, criteria?, lane? }." },
-                        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." },
-                        reducer: { type: "string", description: "Make this a deterministic reduce node (no LLM); names a registered reducer." },
-                        dependsOn: { type: "array", items: { type: "integer" } },
-                    },
-                    required: ["task", "role"],
-                },
+            spec: {
+                type: "object",
+                description: "The workflow specification.",
+                properties: { nodes: workflowNodesArraySchema },
+                required: ["nodes"],
             },
         },
-        required: ["nodes"],
+        required: ["spec"],
     }),
 };
 /** Build a sub-agent run spec for a kernel-generated workflow node. */
@@ -187,6 +299,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/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";

package/dist/runtime/workflow-control-flow.js

@@ -0,0 +1,78 @@
+//! A#2: SDK-side execution of the kernel's control-flow workflow node kinds (Loop / Classify /
+//! Tournament). The kernel owns the scheduling — it re-arms loops, prunes classify branches, and
+//! runs the tournament bracket — and tells the SDK *which* kind a spawn is via the spawn descriptor
+//! (`loop_max_iters` / `classify_labels` / `judge_match`). This module is the SDK half of the "one
+//! agent per node + one additive result field" contract: it builds the prompt that solicits the
+//! decision from the node's agent and extracts the matching result signal (`loopContinue` /
+//! `classifyBranch` / `tournamentWinner`) the kernel reads back.
+import { extractJsonValue } from "./output-schema.js";
+/** Instruction appended to a loop node's goal: do the next increment, and signal when done. */
+export function loopInstruction(maxIters) {
+    return (`This task runs as a LOOP (up to ${maxIters} iterations total). Do the next increment of work now. ` +
+        `When you judge the overall task COMPLETE and no further iterations are needed, end your response ` +
+        `with a JSON object {"loop_continue": false}. To request another iteration, omit it or return ` +
+        `{"loop_continue": true}.`);
+}
+/** Instruction appended to a classify node's goal: pick exactly one of the kernel's branch labels. */
+export function classifyInstruction(labels) {
+    return (`Classify the input and choose EXACTLY ONE label from: ${labels.map(l => JSON.stringify(l)).join(", ")}. ` +
+        `Respond with ONLY a JSON object: {"branch": "<one of the labels>"}.`);
+}
+/** Build a tournament judge's goal: the controller's criterion + the two candidates to compare. */
+export function judgeGoal(criterion, leftOutput, rightOutput) {
+    return (`${criterion}\n\nCompare the two candidate outputs below and decide which one better satisfies the ` +
+        `criterion above.\n\n[CANDIDATE left]\n${leftOutput}\n\n[CANDIDATE right]\n${rightOutput}\n\n` +
+        `Respond with ONLY a JSON object: {"winner": "left"} or {"winner": "right"}.`);
+}
+/** 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 function extractLoopContinue(text) {
+    const v = extractJsonValue(text);
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+        const o = v;
+        if (typeof o.loop_continue === "boolean")
+            return o.loop_continue;
+        if (typeof o.loopContinue === "boolean")
+            return o.loopContinue;
+        if (typeof o.done === "boolean")
+            return !o.done;
+    }
+    return 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 function extractClassifyBranch(text, labels) {
+    const v = extractJsonValue(text);
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+        const o = v;
+        if (typeof o.branch === "string")
+            return o.branch;
+        if (typeof o.label === "string")
+            return o.label;
+    }
+    if (typeof v === "string" && labels.includes(v))
+        return v;
+    const trimmed = (text ?? "").trim();
+    if (labels.includes(trimmed))
+        return trimmed;
+    return 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 function extractJudgeWinner(text) {
+    const v = extractJsonValue(text);
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+        const w = v.winner;
+        if (w === "right")
+            return "right";
+        if (w === "left")
+            return "left";
+    }
+    const lowered = (text ?? "").toLowerCase();
+    // Last resort: a bare mention. Bias to "left" on ambiguity (both/neither mentioned).
+    if (lowered.includes("right") && !lowered.includes("left"))
+        return "right";
+    return "left";
+}

package/dist/tools/index.d.ts

@@ -1,9 +1,16 @@
 import type { ToolSchema, ToolResult } from "../types.js";
+/** M3/G4: the runtime context a tool may read when executing (carries the working directory). A
+ *  narrow, dependency-free shape; the execution plane's `RunContext` is structurally assignable to it.
+ *  (WASM has no filesystem, so worktree isolation is N/A here — this keeps the tool ABI in parity
+ *  with the Node/Python ports so a tool authored once works across all of them.) */
+export interface ToolExecContext {
+    cwd?: string;
+}
 export interface RegisteredTool {
     schema: ToolSchema;
-    execute(args: Record<string, unknown>): Promise<string>;
+    execute(args: Record<string, unknown>, ctx?: ToolExecContext): Promise<string>;
 }
-export declare function tool(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>) => Promise<string> | string): RegisteredTool;
+export declare function tool(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>, ctx?: ToolExecContext) => Promise<string> | string): RegisteredTool;
 export declare function executeTools(calls: {
     id: string;
     name: string;

package/dist/tools/index.js

@@ -1,7 +1,7 @@
 export function tool(name, description, parameters, fn) {
     return {
         schema: { name, description, parameters: JSON.stringify(parameters) },
-        async execute(args) { return fn(args); },
+        async execute(args, ctx) { return fn(args, ctx); },
     };
 }
 export async function executeTools(calls, registry) {

package/dist/types.d.ts

@@ -179,7 +179,11 @@ export interface LLMProvider {
     peekProviderReplay?(message: Pick<Message, "content" | "toolCalls">): ProviderReplay | undefined;
     seedProviderReplay?(message: Pick<Message, "content" | "toolCalls">, replay: ProviderReplay): void;
     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 preempt (`interrupt()`) aborts the in-flight request. SDK-client
+     *  providers forward it via `{ signal }`; the runner also breaks the consume loop on abort, so
+     *  providers that ignore it still stop processing immediately. Optional ⇒ backward-compatible. */
+    signal?: AbortSignal): AsyncIterable<StreamEvent>;
 }
 export interface DreamSummarizer {
     summarize(archived: Message[], context: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/wasm",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "DeepStrike WASM SDK — browser, Cloudflare Workers, Deno Deploy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "node --experimental-vm-modules node_modules/.bin/jest"
   },
   "dependencies": {
-    "@deepstrike/wasm-kernel": "0.2.16"
+    "@deepstrike/wasm-kernel": "0.2.18"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",