@deepstrike/sdk 0.2.15 → 0.2.17

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/runtime/workflow-store.d.ts

@@ -0,0 +1,15 @@
+import type { WorkflowSpec } from "../types/agent.js";
+/** File-backed `WorkflowSpec` store. Default root `~/.deepstrike/workflows`; override via `rootDir`
+ *  (e.g. a skill folder for distribution). One spec per `<name>.json`. */
+export declare class FileWorkflowStore {
+    private readonly root;
+    constructor(opts?: {
+        rootDir?: string;
+    });
+    /** Persist `spec` under `name`; returns the file path written. */
+    save(name: string, spec: WorkflowSpec): Promise<string>;
+    /** Load the spec saved under `name`. Throws if it does not exist. */
+    load(name: string): Promise<WorkflowSpec>;
+    /** The names of all saved workflows (sorted); `[]` when the store dir does not exist yet. */
+    list(): Promise<string[]>;
+}

package/dist/runtime/workflow-store.js

@@ -0,0 +1,47 @@
+//! M6: file-backed persistence for declarative `WorkflowSpec`s — the SDK side of "save & share
+//! workflows". A spec is pure data, so a saved workflow is plain JSON that round-trips exactly. Check
+//! the files into `~/.deepstrike/workflows/`, or ship them inside a skill as templates: put the JSON
+//! in the skill folder and have the agent `load()` + (optionally) tweak the spec before `runWorkflow`.
+import { mkdir, writeFile, readFile, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function defaultRoot() {
+    return join(homedir(), ".deepstrike", "workflows");
+}
+/** Reject names that could escape the store directory; allow a safe slug only. */
+function safeName(name) {
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+        throw new Error(`invalid workflow name "${name}": use only letters, digits, "-", "_"`);
+    }
+    return name;
+}
+/** File-backed `WorkflowSpec` store. Default root `~/.deepstrike/workflows`; override via `rootDir`
+ *  (e.g. a skill folder for distribution). One spec per `<name>.json`. */
+export class FileWorkflowStore {
+    root;
+    constructor(opts) {
+        this.root = opts?.rootDir ?? defaultRoot();
+    }
+    /** Persist `spec` under `name`; returns the file path written. */
+    async save(name, spec) {
+        const path = join(this.root, `${safeName(name)}.json`);
+        await mkdir(this.root, { recursive: true });
+        await writeFile(path, JSON.stringify(spec, null, 2), "utf8");
+        return path;
+    }
+    /** Load the spec saved under `name`. Throws if it does not exist. */
+    async load(name) {
+        const path = join(this.root, `${safeName(name)}.json`);
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    /** The names of all saved workflows (sorted); `[]` when the store dir does not exist yet. */
+    async list() {
+        try {
+            const files = await readdir(this.root);
+            return files.filter(f => f.endsWith(".json")).map(f => f.slice(0, -".json".length)).sort();
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/runtime/worktree-plane.d.ts

@@ -0,0 +1,43 @@
+import type { ExecutionPlane, RunContext } from "./execution-plane.js";
+import type { RegisteredTool } from "../tools/index.js";
+import type { ToolCall, ToolSchema, StreamEvent } from "../types.js";
+/** Creates and removes the worktree directory for one sub-agent. Injectable so the plane can be
+ *  unit-tested without a real git repo (the default is git-backed). */
+export interface WorktreeManager {
+    /** Create the working directory for sub-agent `id`; returns its absolute path. */
+    create(id: string): Promise<string>;
+    /** Remove the working directory previously created at `path`. Must not throw on a missing path. */
+    remove(path: string): Promise<void>;
+}
+/** Default git-backed manager: `git worktree add --detach <root>/<id> <ref>` then `git worktree
+ *  remove --force`. Falls back to a plain recursive delete if `worktree remove` fails (e.g. the dir
+ *  was already detached), so cleanup is best-effort and never throws. */
+export declare class GitWorktreeManager implements WorktreeManager {
+    private readonly opts;
+    constructor(opts?: {
+        repoRoot?: string;
+        ref?: string;
+        rootDir?: string;
+    });
+    create(id: string): Promise<string>;
+    remove(path: string): Promise<void>;
+}
+/** Decorator plane: lazily creates a worktree on first execution, injects it as `RunContext.cwd` for
+ *  every delegated call, and removes it on [`cleanup`]. Tool registration/schemas pass straight
+ *  through to the inner plane. The worktree only *isolates* to the extent the inner plane honors
+ *  `ctx.cwd` (e.g. a subprocess plane rooting commands there). */
+export declare class WorktreeExecutionPlane implements ExecutionPlane {
+    private readonly inner;
+    private readonly manager;
+    private readonly id;
+    private path;
+    constructor(inner: ExecutionPlane, manager: WorktreeManager, id: string);
+    register(...tools: RegisteredTool[]): this;
+    unregister(name: string): this;
+    schemas(): ToolSchema[];
+    /** The created worktree path, or undefined before the first `executeAll` / after `cleanup`. */
+    worktreePath(): string | undefined;
+    executeAll(calls: ToolCall[], ctx: RunContext): AsyncIterable<StreamEvent>;
+    /** Remove the worktree (idempotent — safe to call when none was created). */
+    cleanup(): Promise<void>;
+}

package/dist/runtime/worktree-plane.js

@@ -0,0 +1,81 @@
+//! M3/G4: per-sub-agent git-worktree isolation as an execution-plane decorator.
+//!
+//! An `isolation: "worktree"` workflow node should run its tools in its own working tree so parallel
+//! write-capable nodes (the migration / refactor / evals patterns) don't clobber each other. This
+//! module owns the *worktree lifecycle*: create one git worktree per sub-agent, inject its path as
+//! `RunContext.cwd` so a cwd-aware inner plane scopes its work there, and remove it when the
+//! sub-agent finishes. The git operations are behind an injectable [`WorktreeManager`] so the plane
+//! is testable without mutating a real repository.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const execFileAsync = promisify(execFile);
+/** Default git-backed manager: `git worktree add --detach <root>/<id> <ref>` then `git worktree
+ *  remove --force`. Falls back to a plain recursive delete if `worktree remove` fails (e.g. the dir
+ *  was already detached), so cleanup is best-effort and never throws. */
+export class GitWorktreeManager {
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async create(id) {
+        const root = this.opts.rootDir ?? (await mkdtemp(join(tmpdir(), "deepstrike-wt-")));
+        const path = join(root, id);
+        const ref = this.opts.ref ?? "HEAD";
+        await execFileAsync("git", ["worktree", "add", "--detach", path, ref], { cwd: this.opts.repoRoot });
+        return path;
+    }
+    async remove(path) {
+        try {
+            await execFileAsync("git", ["worktree", "remove", "--force", path], { cwd: this.opts.repoRoot });
+        }
+        catch {
+            await rm(path, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}
+/** Decorator plane: lazily creates a worktree on first execution, injects it as `RunContext.cwd` for
+ *  every delegated call, and removes it on [`cleanup`]. Tool registration/schemas pass straight
+ *  through to the inner plane. The worktree only *isolates* to the extent the inner plane honors
+ *  `ctx.cwd` (e.g. a subprocess plane rooting commands there). */
+export class WorktreeExecutionPlane {
+    inner;
+    manager;
+    id;
+    path;
+    constructor(inner, manager, id) {
+        this.inner = inner;
+        this.manager = manager;
+        this.id = id;
+    }
+    register(...tools) {
+        this.inner.register(...tools);
+        return this;
+    }
+    unregister(name) {
+        this.inner.unregister(name);
+        return this;
+    }
+    schemas() {
+        return this.inner.schemas();
+    }
+    /** The created worktree path, or undefined before the first `executeAll` / after `cleanup`. */
+    worktreePath() {
+        return this.path;
+    }
+    async *executeAll(calls, ctx) {
+        if (this.path === undefined)
+            this.path = await this.manager.create(this.id);
+        yield* this.inner.executeAll(calls, { ...ctx, cwd: this.path });
+    }
+    /** Remove the worktree (idempotent — safe to call when none was created). */
+    async cleanup() {
+        if (this.path === undefined)
+            return;
+        const p = this.path;
+        this.path = undefined;
+        await this.manager.remove(p);
+    }
+}

package/dist/tools/index.d.ts

@@ -1,10 +1,16 @@
 import type { ToolChunk, ToolSchema, ToolResult } from "../types.js";
+/** M3/G4: the runtime context a tool may read when executing. Carries the working directory the tool
+ *  should operate in — set to a sub-agent's git worktree for `isolation: "worktree"` nodes. A narrow,
+ *  dependency-free shape; the execution plane's `RunContext` is structurally assignable to it. */
+export interface ToolExecContext {
+    cwd?: string;
+}
 export interface RegisteredTool {
     schema: ToolSchema;
-    execute(args: Record<string, unknown>): Promise<string> | AsyncIterable<ToolChunk>;
+    execute(args: Record<string, unknown>, ctx?: ToolExecContext): Promise<string> | AsyncIterable<ToolChunk>;
 }
-export declare function tool(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>) => Promise<string> | string): RegisteredTool;
-export declare function streamingTool(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>) => AsyncIterable<ToolChunk>): 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 streamingTool(name: string, description: string, parameters: Record<string, unknown>, fn: (args: Record<string, unknown>, ctx?: ToolExecContext) => AsyncIterable<ToolChunk>): RegisteredTool;
 export declare function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T>;
 export declare function normalizeToolChunk(chunk: ToolChunk): Exclude<ToolChunk, string>;
 export declare function toolChunkText(chunk: ToolChunk): string;

package/dist/tools/index.js

@@ -1,13 +1,13 @@
 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 function streamingTool(name, description, parameters, fn) {
     return {
         schema: { name, description, parameters: JSON.stringify(parameters) },
-        execute(args) { return fn(args); },
+        execute(args, ctx) { return fn(args, ctx); },
     };
 }
 export function isAsyncIterable(value) {

package/dist/types/agent.d.ts

@@ -23,6 +23,11 @@ export interface AgentRunSpec {
     capabilityFilter?: AgentCapabilityFilter;
     milestones?: MilestoneContract;
     metadata?: Record<string, unknown>;
+    /** M1/G3: per-agent model preference (e.g. "opus"/"sonnet"/"haiku"); the host resolves it to a
+     *  provider via `RuntimeOptions.providerFor`. Host-side routing only — not sent to the kernel. */
+    modelHint?: string;
+    /** M4/G5: cumulative token cap for this sub-agent's run (sets the child kernel's `maxTotalTokens`). */
+    tokenBudget?: number;
 }
 /** Kernel process-table observation (Phase 3 canonical spawn signal). */
 export interface AgentProcessChangedObservation {
@@ -48,6 +53,14 @@ export interface LoopResult {
     finalMessage?: Message;
     turnsUsed: number;
     totalTokensUsed: number;
+    /** A#2 v2 loop stop signal: a loop iteration sets `false` to end the loop before `max_iters`.
+     *  `undefined` (every non-loop result) ⇒ no opinion → run to the cap. Sent only when set. */
+    loopContinue?: boolean;
+    /** A#2 classify routing: a classifier node reports the chosen branch label here; the kernel runs
+     *  that branch and prunes the rest. Sent only when set. */
+    classifyBranch?: string;
+    /** A#2 tournament verdict: a judge reports the winning entrant's agent id here. Sent only when set. */
+    tournamentWinner?: string;
 }
 export interface SubAgentResult {
     agentId: string;
@@ -103,6 +116,26 @@ export interface WorkflowNodeSpec {
     /** 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;
+    /** A#2 v2: make this a *loop* node — re-run its agent up to `maxIters` times. An iteration may end
+     *  the loop early by reporting `loopContinue: false` (the runner solicits this from the agent). */
+    loop?: {
+        maxIters: number;
+    };
+    /** A#2: make this a *classify* node — its agent picks exactly one branch `label`; that branch's
+     *  nodes run and the others are pruned. Each branch node must list this node's index in `dependsOn`. */
+    classify?: {
+        branches: Array<{
+            label: string;
+            nodes: number[];
+        }>;
+    };
+    /** A#2: make this a *tournament controller* — generate each `entrants` candidate in parallel, then
+     *  pairwise-judge them to one winner (this node's `task.goal` is the judging criterion). ≥2 entrants. */
+    tournament?: {
+        entrants: WorkflowTaskSpec[];
+    };
+    /** M4/G5: cap this node's child run at `tokenBudget` cumulative tokens (the per-node "use N tokens"). */
+    tokenBudget?: number;
     /** Indices of nodes this node depends on. */
     dependsOn?: number[];
 }
@@ -126,6 +159,20 @@ export interface WorkflowSpawnInfo {
     reducer?: string;
     /** G2: the dependency agent ids whose outputs a reduce node consumes. */
     input_agent_ids?: string[];
+    /** A#2: present only for a tournament *judge* spawn — the two entrant agent ids whose produced
+     *  outputs this judge compares. The runner looks them up and reports the winner as `tournamentWinner`. */
+    judge_match?: {
+        left: string;
+        right: string;
+    };
+    /** A#2 v2: present only for a *loop* iteration spawn — the loop's `max_iters`. Marks the spawn as a
+     *  loop iteration so the runner solicits + reports a `loopContinue` stop signal. */
+    loop_max_iters?: number;
+    /** A#2: present only for a *classify* spawn — the branch labels the classifier must choose among.
+     *  Non-empty marks the spawn as a classifier so the runner instructs the agent + reports `classifyBranch`. */
+    classify_labels?: string[];
+    /** M4/G5: the node's per-node cumulative token cap, if set — the runner caps the child run here. */
+    token_budget?: number;
 }
 /** 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. */
@@ -136,6 +183,11 @@ export interface WorkflowBudget {
     running_subagents: number;
     max_concurrent_subagents?: number;
     concurrency_remaining?: number;
+    /** M4/G5 token headroom: cumulative tokens used, the run-level cap, and tokens remaining before the
+     *  token budget terminates the run — so a coordinator can scale a submission to "use N tokens". */
+    tokens_used?: number;
+    tokens_max?: number;
+    tokens_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
@@ -150,10 +202,21 @@ export declare function workflowSpecToKernel(spec: WorkflowSpec): Record<string,
  *  `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>;
+/** 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 declare function submitWorkflowToKernel(spec: WorkflowSpec, parentSessionId: string, 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;
+/** 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 declare const startWorkflowTool: 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. */