@deepstrike/sdk 0.2.6 → 0.2.7

package/dist/runtime/runner.d.ts

@@ -6,7 +6,7 @@ import type { SessionLog, SessionEvent } from "./session-log.js";
 import type { ArchiveStore } from "./archive.js";
 import type { ExecutionPlane } from "./execution-plane.js";
 import { type MemoryPolicy, type ResourceQuota } from "../kernel.js";
-import type { AgentRunSpec, MilestoneCheckResult, MilestoneContract, MilestonePolicy } from "../types/agent.js";
+import type { AgentRunSpec, MilestoneCheckResult, MilestoneContract, MilestonePolicy, WorkflowSpec } from "../types/agent.js";
 import { type SubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 import { type GovernancePolicy } from "../governance.js";
 import { type NativeOsProfile, type OsProfileId } from "./os-profile.js";
@@ -159,6 +159,27 @@ export declare class RuntimeRunner {
      * Requires an active parent run (`run()` / `wake()` in progress or paused at milestone).
      */
     spawnSubAgent(spec: AgentRunSpec): AsyncIterable<StreamEvent>;
+    /**
+     * 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,
+     * feeds their results back, and loops until the kernel reports the workflow complete.
+     * Returns the completed / failed node agent-ids.
+     */
+    runWorkflow(spec: WorkflowSpec, opts?: {
+        resumedCompleted?: string[];
+    }): Promise<{
+        completed: string[];
+        failed: string[];
+    }>;
+    /**
+     * Resume a workflow from the parent session's completed nodes.
+     * Reads the session log, extracts completed workflow node agent_ids, and
+     * calls runWorkflow with resumedCompleted so the kernel skips those nodes.
+     */
+    resumeWorkflow(spec: WorkflowSpec): Promise<{
+        completed: string[];
+        failed: string[];
+    }>;
     interrupt(): void;
     run(req: {
         sessionId: string;

package/dist/runtime/runner.js

@@ -3,10 +3,10 @@ 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, repairEventsForRecovery } from "./session-repair.js";
+import { buildLlmCompletedEvent, buildRunTerminalEvent, buildWorkflowNodeCompletedEvent, recoverCompletedWorkflowNodes, 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, } from "../types/agent.js";
+import { agentRunSpecToKernel, findSpawnProcessObservation, milestoneCheckPass, milestoneCheckResultToKernel, spawnObservationToManifest, subAgentResultToKernel, workflowNodeToManifest, workflowNodeToSpec, workflowSpecToKernel, } from "../types/agent.js";
 import { defaultSubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 import { governancePolicyToKernelEvent } from "../governance.js";
 import { kernelObservationToSessionEvent, withCategory } from "./kernel-event-log.js";
@@ -256,6 +256,72 @@ export class RuntimeRunner {
         });
         yield { type: "done", iterations: result.result.turnsUsed, totalTokens: result.result.totalTokensUsed, status: result.result.termination };
     }
+    /**
+     * 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,
+     * feeds their results back, and loops until the kernel reports the workflow complete.
+     * Returns the completed / failed node agent-ids.
+     */
+    async runWorkflow(spec, opts) {
+        if (!this.activeKernel || !this.currentSessionId) {
+            throw new Error("runWorkflow requires an active parent run");
+        }
+        const parentSessionId = this.currentSessionId;
+        const runtime = this.activeKernel;
+        const orchestrator = this.opts.subAgentOrchestrator ?? defaultSubAgentOrchestrator;
+        let observations = kernelApply(runtime, this.pendingObservations, {
+            kind: "load_workflow",
+            spec: workflowSpecToKernel(spec),
+            parent_session_id: parentSessionId,
+            // W0-ABI resume: skip nodes already completed before an interruption.
+            ...(opts?.resumedCompleted?.length ? { resumed_completed: opts.resumedCompleted } : {}),
+        });
+        for (;;) {
+            const done = observations.find(o => o.kind === "workflow_completed");
+            if (done)
+                return { completed: done.completed ?? [], failed: done.failed ?? [] };
+            const batch = observations.find(o => o.kind === "workflow_batch_spawned");
+            const nodes = batch?.nodes ?? [];
+            if (nodes.length === 0)
+                return { completed: [], failed: [] }; // nothing to run (e.g. all gated)
+            // Run the batch's 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 } : {}),
+            })));
+            // Feed completions back; the draining feed yields the next batch or completion.
+            observations = [];
+            for (const result of results) {
+                observations = kernelApply(runtime, this.pendingObservations, {
+                    kind: "sub_agent_completed",
+                    result: subAgentResultToKernel(result),
+                });
+                // Persist node completion for resume recovery.
+                await this.opts.sessionLog.append(parentSessionId, buildWorkflowNodeCompletedEvent({
+                    turn: runtime.turn(),
+                    agentId: result.agentId,
+                    termination: result.result.termination,
+                }));
+            }
+        }
+    }
+    /**
+     * Resume a workflow from the parent session's completed nodes.
+     * Reads the session log, extracts completed workflow node agent_ids, and
+     * calls runWorkflow with resumedCompleted so the kernel skips those nodes.
+     */
+    async resumeWorkflow(spec) {
+        if (!this.currentSessionId) {
+            throw new Error("resumeWorkflow requires an active parent run");
+        }
+        const events = await this.opts.sessionLog.read(this.currentSessionId);
+        const resumedCompleted = recoverCompletedWorkflowNodes(events);
+        return this.runWorkflow(spec, { resumedCompleted });
+    }
     interrupt() { this.interrupted = true; }
     async *run(req) {
         const prior = req.inheritEvents ?? await this.opts.sessionLog.read(req.sessionId);

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

@@ -236,6 +236,28 @@ export type SessionEvent = {
     kind: "memory_retrieval_result";
     selected_memory_ids: string[];
     selection_rationale: string;
+} | {
+    kind: "workflow_node_completed";
+    turn: number;
+    category?: KernelEventCategory;
+    primitive?: KernelPrimitive;
+    agent_id: string;
+    termination: string;
+} | {
+    kind: "workflow_batch_spawned";
+    turn: number;
+    category?: KernelEventCategory;
+    primitive?: KernelPrimitive;
+    node_count: number;
+    node_ids: string[];
+} | {
+    kind: "workflow_completed";
+    turn: number;
+    category?: KernelEventCategory;
+    primitive?: KernelPrimitive;
+    completed: string[];
+    failed: string[];
+    total_nodes: number;
 } | {
     kind: "run_terminal";
     reason: string;

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

@@ -1,9 +1,15 @@
 import type { ProviderReplay, ToolCall } from "../types.js";
 import type { SessionEvent } from "./session-log.js";
 export { REPLAY_CONTENT_MAX_BYTES as RECOVERY_CONTENT_MAX_BYTES } from "./replay-sanitize.js";
-/** Minimal native blocks when provider_replay was not persisted. */
-export declare function synthesizeProviderReplay(content: string, toolCalls: ToolCall[]): ProviderReplay | undefined;
-export declare function effectiveProviderReplay(content: string, toolCalls: ToolCall[], stored?: ProviderReplay): ProviderReplay | undefined;
+/**
+ * Normalize a persisted llm_completed event for recovery.
+ *
+ * Content is sanitized and token_count backfilled, but the stored
+ * `provider_replay` envelope is passed through verbatim — this layer is
+ * provider-neutral and must never synthesize protocol-specific replay shapes
+ * (e.g. Anthropic `native_blocks`). Legacy reconstruction for a given protocol
+ * is the responsibility of that provider's `seedProviderReplay`.
+ */
 export declare function normalizeLlmCompleted(event: Extract<SessionEvent, {
     kind: "llm_completed";
 }>, maxBytes?: number): Extract<SessionEvent, {
@@ -35,3 +41,20 @@ export declare function buildRunTerminalEvent(input: {
 }): Extract<SessionEvent, {
     kind: "run_terminal";
 }>;
+/** Build workflow_node_completed for persistence after a node finishes. */
+export declare function buildWorkflowNodeCompletedEvent(input: {
+    turn: number;
+    agentId: string;
+    termination: string;
+}): Extract<SessionEvent, {
+    kind: "workflow_node_completed";
+}>;
+/**
+ * Recover completed workflow node agent_ids from a session event stream.
+ * Scans for workflow_node_completed events and returns the agent_ids whose
+ * termination was "completed". Used to rebuild resumedCompleted for resumeWorkflow.
+ */
+export declare function recoverCompletedWorkflowNodes(events: Array<{
+    seq: number;
+    event: SessionEvent;
+}>): string[];

package/dist/runtime/session-repair.js

@@ -3,41 +3,19 @@ export { REPLAY_CONTENT_MAX_BYTES as RECOVERY_CONTENT_MAX_BYTES } from "./replay
 function estimateTokenCount(text) {
     return Math.max(1, Math.ceil(text.length / 4));
 }
-function parseToolInput(args) {
-    try {
-        return JSON.parse(args || "{}");
-    }
-    catch {
-        return {};
-    }
-}
-/** Minimal native blocks when provider_replay was not persisted. */
-export function synthesizeProviderReplay(content, toolCalls) {
-    if (!toolCalls.length)
-        return undefined;
-    const blocks = [];
-    if (content)
-        blocks.push({ type: "text", text: content });
-    for (const tc of toolCalls) {
-        blocks.push({
-            type: "tool_use",
-            id: tc.id,
-            name: tc.name,
-            input: parseToolInput(tc.arguments),
-        });
-    }
-    return { native_blocks: blocks };
-}
-export function effectiveProviderReplay(content, toolCalls, stored) {
-    if (stored?.native_blocks?.length || stored?.reasoning_content != null) {
-        return stored;
-    }
-    return synthesizeProviderReplay(content, toolCalls);
-}
+/**
+ * Normalize a persisted llm_completed event for recovery.
+ *
+ * Content is sanitized and token_count backfilled, but the stored
+ * `provider_replay` envelope is passed through verbatim — this layer is
+ * provider-neutral and must never synthesize protocol-specific replay shapes
+ * (e.g. Anthropic `native_blocks`). Legacy reconstruction for a given protocol
+ * is the responsibility of that provider's `seedProviderReplay`.
+ */
 export function normalizeLlmCompleted(event, maxBytes) {
     const content = sanitizeReplayText(event.content ?? "", maxBytes);
     const toolCalls = event.tool_calls ?? [];
-    const providerReplay = effectiveProviderReplay(content, toolCalls, event.provider_replay);
+    const providerReplay = event.provider_replay;
     return {
         kind: "llm_completed",
         turn: event.turn,
@@ -75,3 +53,26 @@ export function buildRunTerminalEvent(input) {
         total_tokens: Math.max(0, input.totalTokens),
     };
 }
+/** Build workflow_node_completed for persistence after a node finishes. */
+export function buildWorkflowNodeCompletedEvent(input) {
+    return {
+        kind: "workflow_node_completed",
+        turn: input.turn,
+        agent_id: input.agentId,
+        termination: input.termination,
+    };
+}
+/**
+ * Recover completed workflow node agent_ids from a session event stream.
+ * Scans for workflow_node_completed events and returns the agent_ids whose
+ * termination was "completed". Used to rebuild resumedCompleted for resumeWorkflow.
+ */
+export function recoverCompletedWorkflowNodes(events) {
+    const completed = [];
+    for (const { event } of events) {
+        if (event.kind === "workflow_node_completed" && event.termination === "completed") {
+            completed.push(event.agent_id);
+        }
+    }
+    return completed;
+}

package/dist/types/agent.d.ts

@@ -75,3 +75,53 @@ export declare function milestoneCheckResultToKernel(result: MilestoneCheckResul
 export declare function subAgentResultToKernel(result: SubAgentResult): Record<string, unknown>;
 export declare function milestoneCheckPass(phaseId: string): MilestoneCheckResult;
 export declare function milestoneCheckFail(phaseId: string, reason: string): MilestoneCheckResult;
+/** A task for a workflow node: a full object, or a bare goal string. */
+export type WorkflowTaskSpec = {
+    goal: string;
+    criteria?: string[];
+    lane?: string;
+} | string;
+/** W3 trust level for a workflow node. */
+export type NodeTrust = "trusted" | "quarantined";
+/** One node in a declarative workflow DAG (camelCase host shape). */
+export interface WorkflowNodeSpec {
+    task: WorkflowTaskSpec;
+    role: KernelAgentRole;
+    isolation?: AgentIsolation;
+    contextInheritance?: ContextInheritance;
+    modelHint?: string;
+    /** W3: `quarantined` nodes read untrusted content and must run without privileges. */
+    trust?: NodeTrust;
+    /** Indices of nodes this node depends on. */
+    dependsOn?: number[];
+}
+/** A declarative workflow DAG the kernel runs node-by-node, gating each spawn. */
+export interface WorkflowSpec {
+    nodes: WorkflowNodeSpec[];
+}
+/** Per-node spawn descriptor carried in the `workflow_batch_spawned` observation. */
+export interface WorkflowSpawnInfo {
+    agent_id: string;
+    goal: string;
+    role: string;
+    isolation: string;
+    context_inheritance: string;
+    model_hint?: string;
+    /** W3 trust level: `"trusted"` | `"quarantined"`. */
+    trust?: string;
+}
+/** Map a host `WorkflowSpec` to the snake_case kernel JSON (`load_workflow.spec`). */
+export declare function workflowSpecToKernel(spec: WorkflowSpec): Record<string, unknown>;
+/** 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. */
+export declare function workflowNodeToManifest(node: WorkflowSpawnInfo, parentSessionId: string): AgentProcessChangedObservation;
+/** N parallel read-only Explore workers feeding a single Plan synthesizer (barrier). */
+export declare function fanoutSynthesize(workers: WorkflowTaskSpec[], synthesize: WorkflowTaskSpec): WorkflowSpec;
+/** N parallel Implement generators feeding a single Verify filter/dedupe step (barrier). */
+export declare function generateAndFilter(generators: WorkflowTaskSpec[], filter: WorkflowTaskSpec): WorkflowSpec;
+/**
+ * One fresh-context verifier per rule/claim (parallel) + optional skeptic that depends on all and
+ * re-checks flags. Verifiers run read-only with no inherited author context (bias-resistant).
+ */
+export declare function verifyRules(rules: WorkflowTaskSpec[], skeptic?: WorkflowTaskSpec): WorkflowSpec;

package/dist/types/agent.js

@@ -94,3 +94,113 @@ export function milestoneCheckPass(phaseId) {
 export function milestoneCheckFail(phaseId, reason) {
     return { phaseId, passed: false, reason };
 }
+/** Map a host `WorkflowSpec` to the snake_case kernel JSON (`load_workflow.spec`). */
+export function workflowSpecToKernel(spec) {
+    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 } : {}),
+            };
+        }),
+    };
+}
+/** Build a sub-agent run spec for a kernel-generated workflow node. */
+export function workflowNodeToSpec(node, parentSessionId) {
+    return {
+        identity: {
+            agentId: node.agent_id,
+            sessionId: `${parentSessionId}-${node.agent_id}`,
+            isSubAgent: true,
+            parentSessionId,
+        },
+        role: node.role,
+        isolation: node.isolation,
+        goal: node.goal,
+    };
+}
+/** Build the host manifest for a kernel-generated workflow node. */
+export function workflowNodeToManifest(node, parentSessionId) {
+    return {
+        kind: "agent_process_changed",
+        agent_id: node.agent_id,
+        parent_session_id: parentSessionId,
+        role: node.role,
+        isolation: node.isolation,
+        context_inheritance: node.context_inheritance,
+    };
+}
+// ─── W1/W2 workflow templates (the six patterns as one-liners) ───
+// Roles carry the kernel's role_defaults isolation/inheritance so host-built specs match the
+// core `orchestration::workflow` constructors (e.g. verifiers stay bias-resistant).
+function asTask(t) {
+    return typeof t === "string" ? { goal: t } : t;
+}
+/** N parallel read-only Explore workers feeding a single Plan synthesizer (barrier). */
+export function fanoutSynthesize(workers, synthesize) {
+    const nodes = workers.map(t => ({
+        task: asTask(t),
+        role: "explore",
+        isolation: "read_only",
+        contextInheritance: "system_only",
+    }));
+    nodes.push({
+        task: asTask(synthesize),
+        role: "plan",
+        isolation: "shared",
+        contextInheritance: "full",
+        dependsOn: workers.map((_, i) => i),
+    });
+    return { nodes };
+}
+/** N parallel Implement generators feeding a single Verify filter/dedupe step (barrier). */
+export function generateAndFilter(generators, filter) {
+    const nodes = generators.map(t => ({
+        task: asTask(t),
+        role: "implement",
+        isolation: "worktree",
+        contextInheritance: "full",
+    }));
+    nodes.push({
+        task: asTask(filter),
+        role: "verify",
+        isolation: "read_only",
+        contextInheritance: "none",
+        dependsOn: generators.map((_, i) => i),
+    });
+    return { nodes };
+}
+/**
+ * One fresh-context verifier per rule/claim (parallel) + optional skeptic that depends on all and
+ * re-checks flags. Verifiers run read-only with no inherited author context (bias-resistant).
+ */
+export function verifyRules(rules, skeptic) {
+    const nodes = rules.map(t => ({
+        task: asTask(t),
+        role: "verify",
+        isolation: "read_only",
+        contextInheritance: "none",
+    }));
+    if (skeptic !== undefined) {
+        nodes.push({
+            task: asTask(skeptic),
+            role: "verify",
+            isolation: "read_only",
+            contextInheritance: "none",
+            dependsOn: rules.map((_, i) => i),
+        });
+    }
+    return { nodes };
+}

package/dist/types.d.ts

@@ -184,12 +184,34 @@ export interface RetryConfig {
  * Responses `previous_response_id` without leaking those semantics into the kernel.
  */
 export type ProviderRunState = Record<string, unknown>;
+export type ProviderProtocol = "anthropic-messages" | "openai-chat" | "openai-responses" | "gemini";
+export interface ProviderDescriptor {
+    provider: string;
+    protocol: ProviderProtocol;
+    model: string;
+    reasoning: {
+        supported: boolean;
+        preserveAcrossToolTurns: boolean;
+        requiresReplayForToolTurns?: boolean;
+    };
+    toolCalls: {
+        supported: boolean;
+        requiresStrictPairing: boolean;
+    };
+}
 /** Provider-native fields required to replay a turn across requests (thinking blocks, reasoning_content, etc.). */
 export interface ProviderReplay {
+    schema_version?: 1 | 2;
+    provider?: string;
+    protocol?: ProviderProtocol;
+    model?: string;
     /** Anthropic-style assistant content blocks (thinking, text, tool_use). */
     native_blocks?: Array<Record<string, unknown>>;
     /** OpenAI-compatible reasoning field (DeepSeek, etc.). */
     reasoning_content?: string;
+    reasoning_details?: unknown;
+    native_message?: unknown;
+    tool_calls?: unknown[];
 }
 /** Structured render output produced by the kernel for each LLM call. */
 export interface RenderedContext {
@@ -214,6 +236,7 @@ export interface RuntimePolicy {
 }
 export interface LLMProvider {
     createRunState?(): ProviderRunState;
+    descriptor?(): ProviderDescriptor;
     /**
      * Optional: return the recommended runtime policy for this provider's model.
      * RuntimeRunner uses this as a fallback when the caller has not specified

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "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.6",
+    "@deepstrike/core": "0.2.7",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },