@deepstrike/sdk 0.1.13 → 0.1.14

package/dist/runtime/mcp-proxy-plane.d.ts

@@ -0,0 +1,51 @@
+import type { ToolCall, ToolSchema, StreamEvent } from "../types.js";
+import type { RegisteredTool } from "../tools/index.js";
+import type { ExecutionPlane, RunContext } from "./execution-plane.js";
+import type { CredentialVault } from "./credential-vault.js";
+export interface McpServerConfig {
+    /** Executable to run (e.g. "npx", "python3", "/usr/local/bin/my-mcp-server"). */
+    command: string;
+    /** Command-line arguments. */
+    args?: string[];
+    /**
+     * Keys to look up in the vault and inject as env vars with the same name.
+     * The credential value is never exposed to the model — only to the subprocess.
+     */
+    credentialKeys?: string[];
+    /** Additional static env vars forwarded to the subprocess. */
+    env?: Record<string, string>;
+}
+/**
+ * ExecutionPlane that proxies tool calls to MCP servers.
+ *
+ * Credentials live in a CredentialVault and are injected into each server's
+ * subprocess environment — the model never sees the credential values.
+ *
+ * Usage:
+ *   const plane = new McpProxyPlane({
+ *     servers: { brave: { command: "npx", args: ["-y", "@modelcontextprotocol/server-brave-search"], credentialKeys: ["BRAVE_API_KEY"] } },
+ *     vault: new EnvCredentialVault(),
+ *   })
+ *   await plane.connect()
+ *   // ... use with RuntimeRunner ...
+ *   await plane.disconnect()
+ */
+export declare class McpProxyPlane implements ExecutionPlane {
+    private readonly opts;
+    private connections;
+    private toolToConn;
+    private localPlane;
+    private localNames;
+    constructor(opts: {
+        servers: Record<string, McpServerConfig>;
+        vault: CredentialVault;
+    });
+    /** Start all configured MCP server processes and discover their tool schemas. */
+    connect(): Promise<void>;
+    /** Gracefully stop all MCP server processes. */
+    disconnect(): Promise<void>;
+    register(...tools: RegisteredTool[]): this;
+    unregister(name: string): this;
+    schemas(): ToolSchema[];
+    executeAll(calls: ToolCall[], ctx: RunContext): AsyncIterable<StreamEvent>;
+}

package/dist/runtime/mcp-proxy-plane.js

@@ -0,0 +1,204 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { LocalExecutionPlane } from "./execution-plane.js";
+class McpConnection {
+    serverName;
+    config;
+    vault;
+    child = null;
+    pending = new Map();
+    nextId = 1;
+    _schemas = [];
+    schemaNames = new Set();
+    constructor(serverName, config, vault) {
+        this.serverName = serverName;
+        this.config = config;
+        this.vault = vault;
+    }
+    async start() {
+        const env = { ...process.env, ...(this.config.env ?? {}) };
+        for (const key of this.config.credentialKeys ?? []) {
+            const val = await this.vault.get(key);
+            if (val !== undefined)
+                env[key] = val;
+        }
+        this.child = spawn(this.config.command, this.config.args ?? [], {
+            env,
+            stdio: ["pipe", "pipe", "inherit"],
+        });
+        const rl = createInterface({ input: this.child.stdout, crlfDelay: Infinity });
+        rl.on("line", line => {
+            if (!line.trim())
+                return;
+            try {
+                const msg = JSON.parse(line);
+                const cb = this.pending.get(msg.id);
+                if (!cb)
+                    return;
+                this.pending.delete(msg.id);
+                if (msg.error)
+                    cb.reject(new Error(`MCP(${this.serverName}) ${msg.error.code}: ${msg.error.message}`));
+                else
+                    cb.resolve(msg.result);
+            }
+            catch { /* ignore malformed lines */ }
+        });
+        // MCP handshake
+        await this.request("initialize", {
+            protocolVersion: "2024-11-05",
+            capabilities: { tools: {} },
+            clientInfo: { name: "deepstrike", version: "0.1.0" },
+        });
+        // initialized is a notification (no id, no response expected)
+        this.notify("notifications/initialized");
+        const listResult = await this.request("tools/list");
+        for (const t of listResult.tools ?? []) {
+            const schema = {
+                name: t.name,
+                description: t.description ?? t.name,
+                parameters: JSON.stringify(t.inputSchema ?? { type: "object", properties: {} }),
+            };
+            this._schemas.push(schema);
+            this.schemaNames.add(t.name);
+        }
+    }
+    request(method, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.child?.stdin) {
+                reject(new Error(`MCP server "${this.serverName}" not running`));
+                return;
+            }
+            const id = this.nextId++;
+            this.pending.set(id, { resolve, reject });
+            const msg = { jsonrpc: "2.0", method, id };
+            if (params !== undefined)
+                msg.params = params;
+            this.child.stdin.write(JSON.stringify(msg) + "\n");
+        });
+    }
+    notify(method, params) {
+        if (!this.child?.stdin)
+            return;
+        const msg = { jsonrpc: "2.0", method };
+        if (params !== undefined)
+            msg.params = params;
+        this.child.stdin.write(JSON.stringify(msg) + "\n");
+    }
+    schemas() { return this._schemas; }
+    hasSchema(name) { return this.schemaNames.has(name); }
+    async execute(call) {
+        try {
+            const args = JSON.parse(call.arguments || "{}");
+            const result = await this.request("tools/call", { name: call.name, arguments: args });
+            const text = (result.content ?? [])
+                .filter(c => c.type === "text")
+                .map(c => c.text ?? "")
+                .join("\n");
+            return { output: text || JSON.stringify(result), isError: result.isError ?? false };
+        }
+        catch (err) {
+            return { output: String(err), isError: true };
+        }
+    }
+    async stop() {
+        this.child?.kill();
+        this.child = null;
+        for (const cb of this.pending.values())
+            cb.reject(new Error(`MCP server "${this.serverName}" stopped`));
+        this.pending.clear();
+    }
+}
+// ── Public plane ──────────────────────────────────────────────────────────────
+/**
+ * ExecutionPlane that proxies tool calls to MCP servers.
+ *
+ * Credentials live in a CredentialVault and are injected into each server's
+ * subprocess environment — the model never sees the credential values.
+ *
+ * Usage:
+ *   const plane = new McpProxyPlane({
+ *     servers: { brave: { command: "npx", args: ["-y", "@modelcontextprotocol/server-brave-search"], credentialKeys: ["BRAVE_API_KEY"] } },
+ *     vault: new EnvCredentialVault(),
+ *   })
+ *   await plane.connect()
+ *   // ... use with RuntimeRunner ...
+ *   await plane.disconnect()
+ */
+export class McpProxyPlane {
+    opts;
+    connections = new Map();
+    toolToConn = new Map();
+    localPlane = new LocalExecutionPlane();
+    localNames = new Set();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Start all configured MCP server processes and discover their tool schemas. */
+    async connect() {
+        for (const [name, config] of Object.entries(this.opts.servers)) {
+            const conn = new McpConnection(name, config, this.opts.vault);
+            await conn.start();
+            this.connections.set(name, conn);
+            for (const schema of conn.schemas())
+                this.toolToConn.set(schema.name, conn);
+        }
+    }
+    /** Gracefully stop all MCP server processes. */
+    async disconnect() {
+        for (const conn of this.connections.values())
+            await conn.stop();
+        this.connections.clear();
+        this.toolToConn.clear();
+    }
+    register(...tools) {
+        this.localPlane.register(...tools);
+        for (const t of tools)
+            this.localNames.add(t.schema.name);
+        return this;
+    }
+    unregister(name) {
+        this.localPlane.unregister(name);
+        this.localNames.delete(name);
+        return this;
+    }
+    schemas() {
+        const mcp = [];
+        for (const conn of this.connections.values())
+            mcp.push(...conn.schemas());
+        return [...this.localPlane.schemas(), ...mcp];
+    }
+    async *executeAll(calls, ctx) {
+        const localCalls = calls.filter(c => this.localNames.has(c.name));
+        const mcpCalls = calls.filter(c => !this.localNames.has(c.name));
+        if (localCalls.length > 0)
+            yield* this.localPlane.executeAll(localCalls, ctx);
+        // MCP calls are inherently sequential per server (JSON-RPC request/response)
+        // but different servers can be called concurrently.
+        const groups = new Map();
+        const unknown = [];
+        for (const call of mcpCalls) {
+            const conn = this.toolToConn.get(call.name);
+            if (!conn) {
+                unknown.push(call);
+                continue;
+            }
+            if (!groups.has(conn))
+                groups.set(conn, []);
+            groups.get(conn).push(call);
+        }
+        for (const call of unknown) {
+            yield { type: "tool_result", callId: call.id, name: call.name, content: `unknown MCP tool: ${call.name}`, isError: true };
+        }
+        const tasks = Array.from(groups.entries()).map(async ([conn, serverCalls]) => {
+            const results = [];
+            for (const call of serverCalls)
+                results.push({ call, result: await conn.execute(call) });
+            return results;
+        });
+        for (const settled of await Promise.all(tasks)) {
+            for (const { call, result } of settled) {
+                yield { type: "tool_result", callId: call.id, name: call.name, content: result.output, isError: result.isError };
+            }
+        }
+    }
+}

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

@@ -0,0 +1,32 @@
+import { LocalExecutionPlane } from "./execution-plane.js";
+export interface SandboxOptions {
+    /** Working directory for all subprocesses. Isolated from the rest of the file system by convention. */
+    sandboxDir: string;
+    /** Env var names from the host environment to forward into subprocesses. Default: none. */
+    allowedEnvKeys?: string[];
+    /** Per-call hard timeout in ms. Defaults to 30 000. */
+    timeoutMs?: number;
+    /** Truncate stdout+stderr after this many bytes. Defaults to 1 MiB. */
+    maxOutputBytes?: number;
+}
+/**
+ * ExecutionPlane that confines subprocess execution to a sandbox directory.
+ * 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.
+ */
+export declare class ProcessSandboxPlane extends LocalExecutionPlane {
+    private readonly sandboxDir;
+    private readonly allowedEnvKeys;
+    private readonly timeoutMs;
+    private readonly maxOutputBytes;
+    constructor(opts: SandboxOptions);
+    private buildEnv;
+    private runSubprocess;
+    private makeBashTool;
+    private makeNodeTool;
+}

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

@@ -0,0 +1,109 @@
+import { spawn } from "node:child_process";
+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.
+ * 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.
+ */
+export class ProcessSandboxPlane extends LocalExecutionPlane {
+    sandboxDir;
+    allowedEnvKeys;
+    timeoutMs;
+    maxOutputBytes;
+    constructor(opts) {
+        super();
+        this.sandboxDir = opts.sandboxDir;
+        this.allowedEnvKeys = opts.allowedEnvKeys ?? [];
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.maxOutputBytes = opts.maxOutputBytes ?? 1_048_576;
+        super.register(this.makeBashTool(), this.makeNodeTool());
+    }
+    buildEnv() {
+        const env = {
+            HOME: this.sandboxDir,
+            TMPDIR: this.sandboxDir,
+            PATH: "/usr/local/bin:/usr/bin:/bin",
+        };
+        for (const key of this.allowedEnvKeys) {
+            const val = process.env[key];
+            if (val !== undefined)
+                env[key] = val;
+        }
+        return env;
+    }
+    runSubprocess(cmd, argv) {
+        return new Promise(resolve => {
+            const chunks = [];
+            let totalBytes = 0;
+            let settled = false;
+            const settle = (output, isError) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ output, isError });
+            };
+            const child = spawn(cmd, argv, {
+                cwd: this.sandboxDir,
+                env: this.buildEnv(),
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                settle(`timed out after ${this.timeoutMs}ms`, true);
+            }, this.timeoutMs);
+            const capture = (chunk) => {
+                if (settled)
+                    return;
+                totalBytes += chunk.length;
+                if (totalBytes > this.maxOutputBytes) {
+                    chunks.push(Buffer.from("\n[output truncated]"));
+                    child.kill("SIGKILL");
+                    return;
+                }
+                chunks.push(chunk);
+            };
+            child.stdout.on("data", capture);
+            child.stderr.on("data", capture);
+            child.on("close", code => settle(Buffer.concat(chunks).toString("utf8"), code !== 0));
+            child.on("error", err => settle(String(err), true));
+        });
+    }
+    makeBashTool() {
+        return tool("run_bash", "Run a bash command confined to the sandbox directory. Paths outside the sandbox are not accessible.", {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "The bash command to execute." },
+            },
+            required: ["command"],
+        }, async (args) => {
+            await mkdir(this.sandboxDir, { recursive: true });
+            const { output, isError } = await this.runSubprocess("bash", ["-c", String(args.command)]);
+            if (isError && !output.trim())
+                return "Process exited with non-zero status and produced no output.";
+            return output || "(no output)";
+        });
+    }
+    makeNodeTool() {
+        return tool("run_node", "Evaluate a Node.js script confined to the sandbox directory.", {
+            type: "object",
+            properties: {
+                code: { type: "string", description: "The JavaScript code to evaluate." },
+            },
+            required: ["code"],
+        }, async (args) => {
+            await mkdir(this.sandboxDir, { recursive: true });
+            const { output, isError } = await this.runSubprocess("node", ["-e", String(args.code)]);
+            if (isError && !output.trim())
+                return "Script exited with non-zero status and produced no output.";
+            return output || "(no output)";
+        });
+    }
+}

package/dist/runtime/remote-vpc-plane.d.ts

@@ -0,0 +1,48 @@
+import type { ToolCall, ToolSchema, StreamEvent } from "../types.js";
+import type { RegisteredTool } from "../tools/index.js";
+import type { ExecutionPlane, RunContext } from "./execution-plane.js";
+import type { CredentialVault } from "./credential-vault.js";
+export interface RemoteVpcOptions {
+    /**
+     * Base URL of the remote worker endpoint inside the customer VPC.
+     * Expected routes:
+     *   POST {baseUrl}/execute  body: { name, arguments }  response: { output, isError }
+     *   GET  {baseUrl}/schemas  response: ToolSchema[]    (optional — or provide `schemas` statically)
+     */
+    baseUrl: string;
+    vault: CredentialVault;
+    /**
+     * Vault key whose value is sent verbatim as the Authorization header.
+     * The credential is fetched once per executeAll call (not cached across calls).
+     */
+    authCredentialKey?: string;
+    /**
+     * Static tool schemas served by this VPC worker.
+     * Provide these when the remote /schemas route is unavailable or schema drift
+     * is undesirable at runtime.
+     */
+    schemas: ToolSchema[];
+    /** Per-call HTTP timeout in ms. Defaults to 30 000. */
+    timeoutMs?: number;
+}
+/**
+ * ExecutionPlane that forwards tool calls over HTTP to a worker inside a customer VPC.
+ *
+ * Credentials are stored in a CredentialVault and injected into HTTP headers at call
+ * time — they are never forwarded to the model or stored in the session log.
+ *
+ * Local tools (registered via `register()`) run in-process and take priority over
+ * any remote schema with the same name.
+ */
+export declare class RemoteVpcPlane implements ExecutionPlane {
+    private readonly opts;
+    private readonly remoteSchemas;
+    private readonly remoteNames;
+    private localPlane;
+    constructor(opts: RemoteVpcOptions);
+    register(...tools: RegisteredTool[]): this;
+    unregister(name: string): this;
+    schemas(): ToolSchema[];
+    executeAll(calls: ToolCall[], ctx: RunContext): AsyncIterable<StreamEvent>;
+    private callRemote;
+}

package/dist/runtime/remote-vpc-plane.js

@@ -0,0 +1,82 @@
+import { LocalExecutionPlane } from "./execution-plane.js";
+/**
+ * ExecutionPlane that forwards tool calls over HTTP to a worker inside a customer VPC.
+ *
+ * Credentials are stored in a CredentialVault and injected into HTTP headers at call
+ * time — they are never forwarded to the model or stored in the session log.
+ *
+ * Local tools (registered via `register()`) run in-process and take priority over
+ * any remote schema with the same name.
+ */
+export class RemoteVpcPlane {
+    opts;
+    remoteSchemas;
+    remoteNames;
+    localPlane = new LocalExecutionPlane();
+    constructor(opts) {
+        this.opts = opts;
+        this.remoteSchemas = opts.schemas;
+        this.remoteNames = new Set(opts.schemas.map(s => s.name));
+    }
+    register(...tools) {
+        this.localPlane.register(...tools);
+        return this;
+    }
+    unregister(name) {
+        this.localPlane.unregister(name);
+        return this;
+    }
+    schemas() {
+        // Local tools shadow remote tools with the same name
+        const localNames = new Set(this.localPlane.schemas().map(s => s.name));
+        const remoteVisible = this.remoteSchemas.filter(s => !localNames.has(s.name));
+        return [...this.localPlane.schemas(), ...remoteVisible];
+    }
+    async *executeAll(calls, ctx) {
+        const localSchemaNames = new Set(this.localPlane.schemas().map(s => s.name));
+        const localCalls = calls.filter(c => localSchemaNames.has(c.name));
+        const remoteCalls = calls.filter(c => !localSchemaNames.has(c.name));
+        if (localCalls.length > 0)
+            yield* this.localPlane.executeAll(localCalls, ctx);
+        if (remoteCalls.length === 0)
+            return;
+        const auth = this.opts.authCredentialKey
+            ? await this.opts.vault.get(this.opts.authCredentialKey)
+            : undefined;
+        const headers = { "Content-Type": "application/json" };
+        if (auth)
+            headers["Authorization"] = auth;
+        // Fire all remote calls concurrently; yield results in dispatch order
+        const pending = remoteCalls.map(call => this.callRemote(call, headers).then(result => ({ call, result })));
+        for (const p of pending) {
+            const { call, result } = await p;
+            yield {
+                type: "tool_result",
+                callId: call.id,
+                name: call.name,
+                content: result.output,
+                isError: result.isError,
+            };
+        }
+    }
+    async callRemote(call, headers) {
+        try {
+            const args = JSON.parse(call.arguments || "{}");
+            const response = await fetch(`${this.opts.baseUrl}/execute`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ name: call.name, arguments: args }),
+                signal: AbortSignal.timeout(this.opts.timeoutMs ?? 30_000),
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => "");
+                return { output: `HTTP ${response.status}${body ? `: ${body}` : ""}`, isError: true };
+            }
+            const result = await response.json();
+            return { output: result.output, isError: result.isError ?? false };
+        }
+        catch (err) {
+            return { output: String(err), isError: true };
+        }
+    }
+}

package/dist/runtime/runner.d.ts

@@ -0,0 +1,49 @@
+import type { LLMProvider, StreamEvent, ToolSuspendEvent } from "../types.js";
+import type { DreamStore, DreamResult } 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 { ExecutionPlane } from "./execution-plane.js";
+export interface RuntimeOptions {
+    provider: LLMProvider;
+    sessionLog: SessionLog;
+    executionPlane: ExecutionPlane;
+    maxTokens: number;
+    maxTurns?: number;
+    timeoutMs?: number;
+    agentId?: string;
+    systemPrompt?: string;
+    initialMemory?: string[];
+    skillDir?: string;
+    dreamStore?: DreamStore;
+    knowledgeSource?: KnowledgeSource;
+    signalSource?: SignalSource;
+    extensions?: Record<string, unknown>;
+    governance?: {
+        setTime?(nowMs: bigint): void;
+        evaluate(name: string, argsJson: string): {
+            kind: string;
+            reason?: string;
+            retryAfterMs?: number;
+        };
+    };
+    onToolSuspend?: (event: ToolSuspendEvent) => Promise<unknown> | unknown;
+}
+export declare class RuntimeRunner {
+    private readonly opts;
+    private interrupted;
+    constructor(opts: RuntimeOptions);
+    interrupt(): void;
+    run(req: {
+        sessionId: string;
+        goal: string;
+        criteria?: string[];
+        extensions?: Record<string, unknown>;
+    }): AsyncIterable<StreamEvent>;
+    wake(sessionId: string, extensions?: Record<string, unknown>): AsyncIterable<StreamEvent>;
+    dream(agentId: string, nowMs?: number): Promise<DreamResult>;
+    private execute;
+    private appendObservations;
+}
+/** Collect all text_delta events from a run into a single string. */
+export declare function collectText(stream: AsyncIterable<StreamEvent>): Promise<string>;