@deepstrike/sdk 0.1.16 → 0.2.0

package/dist/runtime/kernel-step.d.ts

@@ -0,0 +1,88 @@
+import type { Message, RenderedContext, TaskUpdate, ToolCall, ToolResult, ToolSchema } from "../types.js";
+import type { SkillMetadata } from "../skills/loader.js";
+import type { RollbackReason } from "./session-log.js";
+export declare const KERNEL_ABI_VERSION = 1;
+export interface KernelRuntimeHandle {
+    step(inputJson: string): string;
+    isTerminal(): boolean;
+    turn(): number;
+    recoveryContentBytes(): number;
+    render(): RenderedContext;
+    drainNewMessages(): Message[];
+    preservedRefs(): string[];
+}
+export interface KernelLoopResult {
+    termination: string;
+    turnsUsed: number;
+    totalTokensUsed: number;
+}
+export type MilestoneVerifierKind = {
+    kind: "machine_check";
+} | {
+    kind: "harness_eval";
+} | {
+    kind: "llm_judge";
+} | {
+    kind: "human_approval";
+} | {
+    kind: "external_command";
+    cmd: string;
+};
+export type KernelRunnerAction = {
+    kind: "call_provider";
+    context: RenderedContext;
+    tools: ToolSchema[];
+} | {
+    kind: "execute_tool";
+    calls: ToolCall[];
+} | {
+    kind: "evaluate_milestone";
+    phaseId: string;
+    criteria: string[];
+    verifier?: MilestoneVerifierKind;
+    requiredEvidence: string[];
+} | {
+    kind: "done";
+    result: KernelLoopResult;
+};
+export interface KernelObservation {
+    kind: string;
+    action?: string;
+    rho_after?: number;
+    sprint?: number;
+    summary?: string;
+    archived?: Message[];
+    turn?: number;
+    checkpoint_history_len?: number;
+    history_len?: number;
+    added?: string[];
+    removed?: string[];
+    change_kind?: string;
+    capability_id?: string;
+    version?: string;
+    mounted_by?: string;
+    mount_reason?: string;
+    phase_id?: string;
+    capabilities_unlocked?: string[];
+    evidence?: string[];
+    reason?: RollbackReason;
+    agent_id?: string;
+    parent_session_id?: string;
+    role?: string;
+    isolation?: string;
+    context_inheritance?: string;
+    permitted_capability_ids?: string[];
+}
+export declare function toolSchemaToKernel(schema: ToolSchema): Record<string, unknown>;
+export declare function skillMetadataToKernel(skill: SkillMetadata): Record<string, unknown>;
+export declare function messageToKernelMessage(message: Message): Record<string, unknown>;
+export declare function toolResultToKernel(result: ToolResult): Record<string, unknown>;
+export declare function taskUpdateToKernel(update: TaskUpdate): Record<string, unknown>;
+export declare function capabilityTool(schema: ToolSchema): Record<string, unknown>;
+export declare function capabilitySkill(skill: SkillMetadata): Record<string, unknown>;
+export declare function capabilityMarker(kind: string, id: string, description: string): Record<string, unknown>;
+export declare function capabilityCommandMount(capability: Record<string, unknown>, mountedBy?: string, mountReason?: string): Record<string, unknown>;
+export declare function capabilityCommandUnmount(capabilityKind: string, id: string): Record<string, unknown>;
+export declare function kernelApply(runtime: KernelRuntimeHandle, pending: KernelObservation[], event: Record<string, unknown>): KernelObservation[];
+export declare function kernelAction(runtime: KernelRuntimeHandle, pending: KernelObservation[], event: Record<string, unknown>): KernelRunnerAction;
+export declare function forceCompact(runtime: KernelRuntimeHandle, pending: KernelObservation[]): boolean;

package/dist/runtime/kernel-step.js

@@ -0,0 +1,262 @@
+export const KERNEL_ABI_VERSION = 1;
+function tryParseJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}
+export function toolSchemaToKernel(schema) {
+    return {
+        name: schema.name,
+        description: schema.description,
+        parameters: tryParseJson(schema.parameters) ?? {},
+    };
+}
+export function skillMetadataToKernel(skill) {
+    const out = {
+        name: skill.name,
+        description: skill.description,
+        estimated_tokens: skill.estimatedTokens ?? 0,
+    };
+    if (skill.whenToUse)
+        out.when_to_use = skill.whenToUse;
+    if (skill.effort !== undefined)
+        out.effort = skill.effort;
+    return out;
+}
+export function messageToKernelMessage(message) {
+    const out = {
+        role: message.role,
+        tool_calls: (message.toolCalls ?? []).map(tc => ({
+            id: tc.id,
+            name: tc.name,
+            arguments: tryParseJson(tc.arguments) ?? {},
+        })),
+    };
+    if (message.tokenCount !== undefined) {
+        out.token_count = message.tokenCount;
+    }
+    if (message.contentParts && message.contentParts.length > 0) {
+        out.content = message.contentParts.map(part => {
+            if (part.type === "text")
+                return { type: "text", text: part.text };
+            if (part.type === "tool_result") {
+                return {
+                    type: "tool_result",
+                    call_id: part.callId,
+                    output: part.output,
+                    is_error: part.isError,
+                };
+            }
+            if (part.type === "image") {
+                return {
+                    type: "image",
+                    url: part.url,
+                    data: part.data,
+                    media_type: part.mediaType,
+                    detail: part.detail,
+                };
+            }
+            if (part.type === "audio") {
+                return { type: "audio", data: part.data, media_type: part.mediaType };
+            }
+            return { type: "text", text: message.content };
+        });
+    }
+    else {
+        out.content = message.content;
+    }
+    return out;
+}
+export function toolResultToKernel(result) {
+    const out = {
+        call_id: result.callId,
+        output: result.output,
+        is_error: result.isError,
+        is_fatal: result.isFatal ?? false,
+        token_count: result.tokenCount ?? null,
+    };
+    if (result.errorKind !== undefined) {
+        out.error_kind = result.errorKind;
+    }
+    return out;
+}
+export function taskUpdateToKernel(update) {
+    return {
+        plan: update.plan,
+        current_step: update.currentStep,
+        progress: update.progress,
+        scratchpad: update.scratchpad,
+        blocked_on: update.blockedOn,
+        preserved_refs: update.preservedRefs,
+    };
+}
+export function capabilityTool(schema) {
+    return {
+        id: schema.name,
+        kind: "tool",
+        description: schema.description,
+        tool_schema: toolSchemaToKernel(schema),
+    };
+}
+export function capabilitySkill(skill) {
+    return {
+        id: skill.name,
+        kind: "skill",
+        description: skill.description,
+        skill: skillMetadataToKernel(skill),
+    };
+}
+export function capabilityMarker(kind, id, description) {
+    return { id, kind, description };
+}
+export function capabilityCommandMount(capability, mountedBy = "sdk:runtime", mountReason = "dynamic_register") {
+    return {
+        kind: "capability_command",
+        command: {
+            action: "mount",
+            capability,
+            mounted_by: mountedBy,
+            mount_reason: mountReason,
+        },
+    };
+}
+export function capabilityCommandUnmount(capabilityKind, id) {
+    return {
+        kind: "capability_command",
+        command: { action: "unmount", kind: capabilityKind, id },
+    };
+}
+function parseStep(raw) {
+    return JSON.parse(raw);
+}
+function kernelMessageToSdk(raw) {
+    const content = raw.content;
+    const message = {
+        role: raw.role,
+        content: typeof content === "string"
+            ? content
+            : Array.isArray(content)
+                ? content
+                    .filter((part) => {
+                    return typeof part === "object" && part !== null && part.type === "text";
+                })
+                    .map(part => String(part.text ?? ""))
+                    .join("")
+                : "",
+        toolCalls: (raw.tool_calls ?? []).map(tc => ({
+            id: String(tc.id ?? ""),
+            name: String(tc.name ?? ""),
+            arguments: JSON.stringify(tc.arguments ?? {}),
+        })),
+    };
+    if (typeof raw.token_count === "number") {
+        message.tokenCount = raw.token_count;
+    }
+    if (Array.isArray(content)) {
+        message.contentParts = content
+            .filter((part) => typeof part === "object" && part !== null)
+            .map(part => {
+            if (part.type === "text") {
+                return { type: "text", text: String(part.text ?? "") };
+            }
+            if (part.type === "tool_result") {
+                return {
+                    type: "tool_result",
+                    callId: String(part.call_id ?? ""),
+                    output: String(part.output ?? ""),
+                    isError: Boolean(part.is_error),
+                };
+            }
+            if (part.type === "image") {
+                return {
+                    type: "image",
+                    url: part.url,
+                    data: part.data,
+                    mediaType: part.media_type,
+                    detail: part.detail,
+                };
+            }
+            if (part.type === "audio") {
+                return {
+                    type: "audio",
+                    data: String(part.data ?? ""),
+                    mediaType: String(part.media_type ?? "audio/wav"),
+                };
+            }
+            return { type: "text", text: "" };
+        });
+    }
+    return message;
+}
+function renderedContextToSdk(raw) {
+    return {
+        systemText: String(raw.system_text ?? raw.systemText ?? ""),
+        turns: (raw.turns ?? []).map(kernelMessageToSdk),
+    };
+}
+function mapKernelAction(raw) {
+    switch (raw.kind) {
+        case "call_provider":
+            return {
+                kind: "call_provider",
+                context: renderedContextToSdk(raw.context ?? {}),
+                tools: (raw.tools ?? []).map(t => ({
+                    name: String(t.name ?? ""),
+                    description: String(t.description ?? ""),
+                    parameters: JSON.stringify(t.parameters ?? {}),
+                })),
+            };
+        case "execute_tool":
+            return {
+                kind: "execute_tool",
+                calls: (raw.calls ?? []).map(c => ({
+                    id: String(c.id ?? ""),
+                    name: String(c.name ?? ""),
+                    arguments: JSON.stringify(c.arguments ?? {}),
+                })),
+            };
+        case "evaluate_milestone":
+            return {
+                kind: "evaluate_milestone",
+                phaseId: String(raw.phase_id ?? ""),
+                criteria: raw.criteria ?? [],
+                verifier: raw.verifier,
+                requiredEvidence: raw.required_evidence ?? [],
+            };
+        case "done": {
+            const result = raw.result ?? {};
+            return {
+                kind: "done",
+                result: {
+                    termination: String(result.termination ?? "error"),
+                    turnsUsed: Number(result.turns_used ?? 0),
+                    totalTokensUsed: Number(result.total_tokens_used ?? 0),
+                },
+            };
+        }
+        default:
+            throw new Error(`unknown KernelAction kind: ${String(raw.kind)}`);
+    }
+}
+function stepInput(event) {
+    return JSON.stringify({ version: KERNEL_ABI_VERSION, event });
+}
+export function kernelApply(runtime, pending, event) {
+    const step = parseStep(runtime.step(stepInput(event)));
+    pending.push(...step.observations);
+    return step.observations;
+}
+export function kernelAction(runtime, pending, event) {
+    const step = parseStep(runtime.step(stepInput(event)));
+    pending.push(...step.observations);
+    const raw = step.actions[0];
+    if (!raw)
+        throw new Error("kernel transition must return one action");
+    return mapKernelAction(raw);
+}
+export function forceCompact(runtime, pending) {
+    return kernelApply(runtime, pending, { kind: "force_compact" }).some(o => o.kind === "compressed");
+}

package/dist/runtime/process-sandbox-plane.d.ts

@@ -1,6 +1,6 @@
 import { LocalExecutionPlane } from "./execution-plane.js";
 export interface SandboxOptions {
-    /** Working directory for all subprocesses. Isolated from the rest of the file system by convention. */
+    /** Working directory for all subprocesses. This is not an OS-enforced filesystem boundary. */
     sandboxDir: string;
     /** Env var names from the host environment to forward into subprocesses. Default: none. */
     allowedEnvKeys?: string[];
@@ -10,14 +10,14 @@ export interface SandboxOptions {
     maxOutputBytes?: number;
 }
 /**
- * ExecutionPlane that confines subprocess execution to a sandbox directory.
+ * ExecutionPlane that runs subprocesses with a sandbox directory as cwd.
  * Extends LocalExecutionPlane with two built-in tools:
  *  - `run_bash`  — executes a bash command inside sandboxDir.
  *  - `run_node`  — evaluates a Node.js script inside sandboxDir.
  *
  * All registered JS tools continue to run in-process (identical to LocalExecutionPlane).
- * The sandboxing guarantee is: subprocesses spawned by the built-in tools cannot reach
- * files outside sandboxDir unless the host OS allows it.
+ * Subprocesses are launched with a stripped environment and sandboxDir as cwd;
+ * this is execution hygiene, not an OS-enforced filesystem sandbox.
  */
 export declare class ProcessSandboxPlane extends LocalExecutionPlane {
     private readonly sandboxDir;

package/dist/runtime/process-sandbox-plane.js

@@ -3,14 +3,14 @@ import { mkdir } from "node:fs/promises";
 import { tool } from "../tools/index.js";
 import { LocalExecutionPlane } from "./execution-plane.js";
 /**
- * ExecutionPlane that confines subprocess execution to a sandbox directory.
+ * ExecutionPlane that runs subprocesses with a sandbox directory as cwd.
  * Extends LocalExecutionPlane with two built-in tools:
  *  - `run_bash`  — executes a bash command inside sandboxDir.
  *  - `run_node`  — evaluates a Node.js script inside sandboxDir.
  *
  * All registered JS tools continue to run in-process (identical to LocalExecutionPlane).
- * The sandboxing guarantee is: subprocesses spawned by the built-in tools cannot reach
- * files outside sandboxDir unless the host OS allows it.
+ * Subprocesses are launched with a stripped environment and sandboxDir as cwd;
+ * this is execution hygiene, not an OS-enforced filesystem sandbox.
  */
 export class ProcessSandboxPlane extends LocalExecutionPlane {
     sandboxDir;
@@ -77,7 +77,7 @@ export class ProcessSandboxPlane extends LocalExecutionPlane {
         });
     }
     makeBashTool() {
-        return tool("run_bash", "Run a bash command confined to the sandbox directory. Paths outside the sandbox are not accessible.", {
+        return tool("run_bash", "Run a bash command with the sandbox directory as cwd and a stripped environment. This is not an OS-enforced filesystem sandbox.", {
             type: "object",
             properties: {
                 command: { type: "string", description: "The bash command to execute." },
@@ -92,7 +92,7 @@ export class ProcessSandboxPlane extends LocalExecutionPlane {
         });
     }
     makeNodeTool() {
-        return tool("run_node", "Evaluate a Node.js script confined to the sandbox directory.", {
+        return tool("run_node", "Evaluate a Node.js script with the sandbox directory as cwd and a stripped environment.", {
             type: "object",
             properties: {
                 code: { type: "string", description: "The JavaScript code to evaluate." },

package/dist/runtime/provider-replay.js

@@ -1,3 +1,4 @@
+import { effectiveProviderReplay } from "./session-repair.js";
 function sortObjectKeys(val) {
     if (val === null || typeof val !== "object") {
         return val;
@@ -37,9 +38,13 @@ export function seedProviderReplayFromEvents(provider, events) {
     if (!provider.seedProviderReplay)
         return;
     for (const { event } of events) {
-        if (event.kind !== "llm_completed" || !event.provider_replay)
+        if (event.kind !== "llm_completed")
             continue;
-        provider.seedProviderReplay({ content: event.content, toolCalls: event.tool_calls ?? [] }, event.provider_replay);
+        const toolCalls = event.tool_calls ?? [];
+        const replay = effectiveProviderReplay(event.content, toolCalls, event.provider_replay);
+        if (!replay)
+            continue;
+        provider.seedProviderReplay({ content: event.content, toolCalls }, replay);
     }
 }
 export function peekProviderReplay(provider, content, toolCalls) {

package/dist/runtime/replay-sanitize.d.ts

@@ -0,0 +1,5 @@
+/** UTF-8-safe text helpers for session replay (defense in depth). */
+/** Soft cap — only snip very large llm_completed bodies before preload. */
+export declare const REPLAY_CONTENT_MAX_BYTES = 32768;
+export declare function truncateBytesAtCharBoundary(text: string, maxBytes: number): string;
+export declare function sanitizeReplayText(text: string, maxBytes?: number): string;

package/dist/runtime/replay-sanitize.js

@@ -0,0 +1,25 @@
+/** UTF-8-safe text helpers for session replay (defense in depth). */
+/** Soft cap — only snip very large llm_completed bodies before preload. */
+export const REPLAY_CONTENT_MAX_BYTES = 32_768;
+export function truncateBytesAtCharBoundary(text, maxBytes) {
+    const data = Buffer.from(text, "utf8");
+    if (data.length <= maxBytes)
+        return text;
+    let end = maxBytes;
+    while (end > 0) {
+        const slice = data.subarray(0, end).toString("utf8");
+        if (Buffer.byteLength(slice, "utf8") <= end)
+            return slice;
+        end -= 1;
+    }
+    return "";
+}
+export function sanitizeReplayText(text, maxBytes = REPLAY_CONTENT_MAX_BYTES) {
+    if (!text)
+        return text;
+    const safe = Buffer.from(text, "utf8").toString("utf8");
+    if (Buffer.byteLength(safe, "utf8") <= maxBytes)
+        return safe;
+    const prefix = truncateBytesAtCharBoundary(safe, maxBytes);
+    return `${prefix}… [replay truncated]`;
+}

package/dist/runtime/runner.d.ts

@@ -1,9 +1,12 @@
-import type { LLMProvider, StreamEvent, ToolSuspendEvent } from "../types.js";
-import type { DreamStore, DreamResult } from "../memory/protocols.js";
+import type { LLMProvider, Message, ToolSchema, StreamEvent, ToolSuspendEvent } from "../types.js";
+import type { DreamStore } from "../memory/protocols.js";
 import type { KnowledgeSource } from "../knowledge/source.js";
 import type { SignalSource } from "../signals/types.js";
-import type { SessionLog } from "./session-log.js";
+import type { SessionLog, SessionEvent } from "./session-log.js";
+import type { ArchiveStore } from "./archive.js";
 import type { ExecutionPlane } from "./execution-plane.js";
+import type { AgentRunSpec, MilestoneCheckResult, MilestoneContract, MilestonePolicy } from "../types/agent.js";
+import { type SubAgentOrchestrator } from "./sub-agent-orchestrator.js";
 export interface RuntimeOptions {
     provider: LLMProvider;
     sessionLog: SessionLog;
@@ -27,23 +30,76 @@ export interface RuntimeOptions {
             retryAfterMs?: number;
         };
     };
+    tokenizer?: string;
+    enablePlanTool?: boolean;
+    compressionStore?: ArchiveStore;
     onToolSuspend?: (event: ToolSuspendEvent) => Promise<unknown> | unknown;
+    /** Default: terminate — stop with milestone_pending when a phase needs evaluation. */
+    milestonePolicy?: MilestonePolicy;
+    /** Optional external verifier when milestonePolicy is not auto_pass. */
+    onMilestoneEvaluate?: (ctx: {
+        phaseId: string;
+        criteria: string[];
+        requiredEvidence: string[];
+    }) => Promise<MilestoneCheckResult> | MilestoneCheckResult;
+    /** Passed to kernel start_run for role/isolation metadata. */
+    runSpec?: AgentRunSpec;
+    /** Loaded via load_milestone_contract before run start. */
+    milestoneContract?: MilestoneContract;
+    /** Custom sub-agent host driver; defaults to SubAgentOrchestrator. */
+    subAgentOrchestrator?: SubAgentOrchestrator;
+    /** Optional system prompt injected into the dream synthesis call. */
+    dreamSystemPrompt?: string;
 }
 export declare class RuntimeRunner {
     private readonly opts;
     private interrupted;
+    private activeKernel;
+    private pendingObservations;
+    private currentSessionId;
+    private nextArchiveStart;
     constructor(opts: RuntimeOptions);
+    /** Host configuration (for coordinator / sub-agent spawn). */
+    get hostOptions(): RuntimeOptions;
+    /** Mount a tool capability on the currently-running kernel runtime. No-op if not running. */
+    mountTool(schema: ToolSchema): void;
+    /** Mount a skill capability on the currently-running kernel runtime. No-op if not running. */
+    mountSkill(name: string, description: string): void;
+    /** Mount a generic marker capability (e.g. MCP server, agent) on the active run. No-op if not running. */
+    mountMarker(kind: string, id: string, description: string): void;
+    /** Unmount a capability by kind + id from the active run. No-op if not running. */
+    unmountCapability(kind: string, id: string): void;
+    /** Push a large artifact into the kernel artifacts partition (not inlined in history). */
+    pushArtifact(message: Message, tokens?: number): void;
+    /**
+     * Spawn an isolated sub-agent via the kernel, run it on the host, and feed the result back.
+     * Requires an active parent run (`run()` / `wake()` in progress or paused at milestone).
+     */
+    spawnSubAgent(spec: AgentRunSpec): AsyncIterable<StreamEvent>;
     interrupt(): void;
     run(req: {
         sessionId: string;
         goal: string;
         criteria?: string[];
         extensions?: Record<string, unknown>;
+        /** Parent transcript to preload (e.g. sub-agent full context inheritance). */
+        inheritEvents?: Array<{
+            seq: number;
+            event: SessionEvent;
+        }>;
     }): AsyncIterable<StreamEvent>;
     wake(sessionId: string, extensions?: Record<string, unknown>): AsyncIterable<StreamEvent>;
-    dream(agentId: string, nowMs?: number): Promise<DreamResult>;
+    dream(agentId: string, nowMs?: number): AsyncIterable<StreamEvent>;
     private execute;
     private appendObservations;
 }
+export declare function replayMessages(events: Array<{
+    seq: number;
+    event: SessionEvent;
+}>, maxBytes?: number): Message[];
+export declare function replayMessagesAsync(events: Array<{
+    seq: number;
+    event: SessionEvent;
+}>, maxBytes?: number, loadArchive?: (archiveRef: string) => Promise<Message[]>): Promise<Message[]>;
 /** Collect all text_delta events from a run into a single string. */
 export declare function collectText(stream: AsyncIterable<StreamEvent>): Promise<string>;