@deepstrike/wasm 0.1.6

package/README.md

@@ -0,0 +1,299 @@
+# DeepStrike WASM SDK
+
+Agent framework built on a Rust kernel compiled to WebAssembly. Runs in browsers, Cloudflare Workers, Deno Deploy, and Vercel Edge — anywhere that supports `fetch` and WASM.
+
+## Install
+
+```bash
+npm install @deepstrike/wasm
+```
+
+The Rust kernel is distributed as a pre-built `.wasm` binary (`@deepstrike/wasm-kernel`), which is an indirect dependency — you never import from it directly.
+
+---
+
+## Quick start
+
+```typescript
+import { Agent, AnthropicProvider, tool } from "@deepstrike/wasm"
+
+const add = tool("add", "Add two numbers.", {
+  type: "object",
+  properties: { x: { type: "number" }, y: { type: "number" } },
+  required: ["x", "y"],
+}, async ({ x, y }) => String((x as number) + (y as number)))
+
+const agent = new Agent(
+  new AnthropicProvider(apiKey),
+  { maxTokens: 32_000, maxTurns: 10 },
+)
+agent.register(add)
+
+const answer = await agent.run("What is 2 + 3?")
+console.log(answer) // "5"
+```
+
+Streaming:
+
+```typescript
+for await (const event of agent.runStreaming("Summarize this page")) {
+  if (event.type === "text_delta") process.stdout.write(event.delta)
+  else if (event.type === "tool_call") console.log(`\n[→ ${event.name}]`)
+  else if (event.type === "done") console.log(`\ndone in ${event.iterations} turns (${event.status})`)
+}
+```
+
+---
+
+## Architecture
+
+```
+src/
+├── index.ts          # Public exports
+├── agent.ts          # Agent — top-level entry point
+├── types.ts          # Shared type definitions
+├── providers/        # LLM adapters (fetch-based SSE)
+├── tools/            # tool() helper, executeTools (no fs/shell)
+├── memory/           # WorkingMemory + MemorySource/Extractor interfaces
+├── knowledge/        # KnowledgeSource interface
+├── harness/          # SinglePassHarness, EvalLoopHarness, QualityGate
+├── signals/          # RuntimeSignal, SignalSource, ScheduledPrompt
+└── safety/           # PermissionManager
+```
+
+The kernel (`@deepstrike/wasm-kernel`, Rust/wasm-bindgen) owns:
+- `LoopStateMachine` — drives `call_llm → execute_tools → load_skills → done`
+- `ContextEngine` — 5-partition context with pressure-based compression
+- `Governance` — tool veto authority
+- `SignalRouter` — external interrupt queue
+
+### WASM constraints vs Node SDK
+
+| Capability | Browser | Cloudflare Worker | Node |
+|---|---|---|---|
+| `fs` read/write | no | no | yes |
+| `bash` tool | no | no | yes |
+| Long-term storage | IndexedDB | KV / D1 | SQLite |
+| External signals | `postMessage` | event | any |
+
+The WASM SDK ships **no `readFile` built-in**. Tools must be pure JS / serializable data. Skill loading is delegated to the host (fetch from a URL, read from IndexedDB, etc.).
+
+---
+
+## Providers
+
+All providers use `fetch` — no Node.js `http` module.
+
+| Class | Backend |
+|-------|---------|
+| `AnthropicProvider` | Anthropic API (SSE) |
+| `OpenAIProvider` | OpenAI API (SSE) |
+| `QwenProvider` | DashScope |
+| `DeepSeekProvider` | DeepSeek API |
+| `MiniMaxProvider` | MiniMax API |
+
+```typescript
+import { AnthropicProvider } from "@deepstrike/wasm"
+
+const provider = new AnthropicProvider("sk-...", "claude-opus-4-7")
+```
+
+Thinking / reasoning:
+
+```typescript
+for await (const event of agent.runStreaming("...", undefined, { enable_thinking: true })) {
+  if (event.type === "thinking_delta") console.log(event.delta)
+}
+```
+
+---
+
+## Tools
+
+Tools must be pure functions — no shell, no filesystem.
+
+```typescript
+import { tool, Agent } from "@deepstrike/wasm"
+
+const fetchUrl = tool("fetch_url", "Fetch a URL and return its text.", {
+  type: "object",
+  properties: { url: { type: "string" } },
+  required: ["url"],
+}, async ({ url }) => {
+  const resp = await fetch(url as string)
+  return resp.text()
+})
+
+agent.register(fetchUrl)
+```
+
+---
+
+## Governance
+
+```typescript
+import { Agent, AnthropicProvider, Governance } from "@deepstrike/wasm"
+
+const gov = new Governance()
+gov.blockTool("dangerous_tool")
+
+const agent = new Agent(provider, {
+  maxTokens: 32_000,
+  governance: gov,
+})
+```
+
+---
+
+## Memory
+
+`WorkingMemory` is an in-process scratch pad for within-run state:
+
+```typescript
+import { WorkingMemory } from "@deepstrike/wasm"
+
+const mem = new WorkingMemory()
+mem.set("step", 1)
+mem.get("step")   // 1
+```
+
+---
+
+## Knowledge
+
+```typescript
+import type { KnowledgeSource } from "@deepstrike/wasm"
+
+class VectorSearch implements KnowledgeSource {
+  async retrieve(goal: string, topK = 5): Promise<string[]> {
+    const resp = await fetch(`/api/search?q=${encodeURIComponent(goal)}&k=${topK}`)
+    return resp.json()
+  }
+}
+
+const agent = new Agent(provider, {
+  maxTokens: 32_000,
+  maxTurns: 10,
+  knowledgeSource: new VectorSearch(),
+})
+```
+
+---
+
+## Harness
+
+```typescript
+import { SinglePassHarness, HarnessLoop } from "@deepstrike/wasm"
+
+// Single pass — always passes
+const harness = new SinglePassHarness(agent)
+const outcome = await harness.run({ goal: "Write a haiku" })
+console.log(outcome.result)
+
+// Eval loop — LLM-judges the output; retries up to 3 times
+const loop = new HarnessLoop(agent, evalProvider, { maxAttempts: 3 })
+for await (const event of loop.runStreaming({
+  goal: "Write a haiku",
+  criteria: [
+    { text: "Exactly 3 lines", required: true },
+    { text: "Contains a seasonal reference", required: false },
+  ],
+})) {
+  if (event.type === "done") console.log(event.verdict.passed, event.verdict.overallScore)
+}
+```
+
+---
+
+## Signals & interrupts
+
+```typescript
+import { ScheduledPrompt } from "@deepstrike/wasm"
+import type { SignalSource, RuntimeSignal } from "@deepstrike/wasm"
+
+// Interrupt from a UI button
+document.getElementById("stop")!.onclick = () => agent.interrupt()
+
+// Convert a scheduled prompt to a RuntimeSignal
+const prompt = new ScheduledPrompt("Daily standup summary", 1_700_000_000_000)
+const signal = prompt.toSignal()
+// signal.source === "cron", signal.signalType === "job"
+
+// Feed signals from postMessage (browser) or Cloudflare event
+class PostMessageSource implements SignalSource {
+  private queue: RuntimeSignal[] = []
+  constructor() {
+    self.addEventListener("message", (e: MessageEvent) => {
+      if (e.data?.source) this.queue.push(e.data as RuntimeSignal)
+    })
+  }
+  async nextSignal(): Promise<RuntimeSignal | null> {
+    return this.queue.shift() ?? null
+  }
+}
+```
+
+---
+
+## Permissions
+
+```typescript
+import { PermissionManager, PermissionMode } from "@deepstrike/wasm"
+
+const pm = new PermissionManager(PermissionMode.DEFAULT)
+pm.grant("fetch", "execute")
+pm.grant("storage", "*")
+pm.revoke("fetch", "execute")
+
+const decision = pm.evaluate("fetch", "execute")
+decision.allowed   // boolean
+decision.reason    // string
+```
+
+Modes: `DEFAULT` (evaluate grants), `PLAN` (block all), `AUTO` (allow all).
+
+---
+
+## Edge runtime examples
+
+### Cloudflare Worker
+
+```typescript
+import init from "@deepstrike/wasm-kernel"
+import { Agent, AnthropicProvider } from "@deepstrike/wasm"
+import wasmBinary from "@deepstrike/wasm-kernel/deepstrike_wasm_bg.wasm"
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    await init(wasmBinary)
+    const agent = new Agent(new AnthropicProvider(env.ANTHROPIC_KEY), { maxTokens: 32_000, maxTurns: 10 })
+    const result = await agent.run(await request.text())
+    return new Response(result)
+  },
+}
+```
+
+### Browser (Vite / bundler)
+
+```typescript
+import init from "@deepstrike/wasm-kernel"
+import { Agent, AnthropicProvider } from "@deepstrike/wasm"
+
+await init()
+const agent = new Agent(new AnthropicProvider(import.meta.env.VITE_ANTHROPIC_KEY), { maxTokens: 32_000, maxTurns: 10 })
+```
+
+---
+
+## Stream events
+
+| Event type | Fields |
+|------------|--------|
+| `text_delta` | `delta: string` |
+| `thinking_delta` | `delta: string` |
+| `tool_call` | `id, name, arguments` |
+| `tool_result` | `callId, name, content, isError` |
+| `done` | `iterations, totalTokens, status` |
+| `error` | `message: string` |
+
+`status` mirrors the kernel termination reason: `completed` / `max_turns` / `token_budget` / `timeout` / `user_abort` / `error`.

package/dist/agent.d.ts

@@ -0,0 +1,57 @@
+import type { LLMProvider, StreamEvent } from "./types.js";
+import type { RegisteredTool } from "./tools/index.js";
+import type { KnowledgeSource } from "./knowledge/index.js";
+import type { SignalSource } from "./signals/index.js";
+import type { DreamStore } from "./memory/index.js";
+import { Governance } from "./governance.js";
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    allowedTools?: string[];
+    effort?: number;
+    estimatedTokens?: number;
+}
+export interface AgentOptions {
+    maxTokens: number;
+    maxTurns?: number;
+    timeoutMs?: number;
+    extensions?: Record<string, unknown>;
+    /**
+     * System-level instructions prepended to every context render.
+     * Passed to the kernel's `system` partition before the first LLM call.
+     */
+    systemPrompt?: string;
+    /**
+     * Long-term memory snippets pre-seeded into the context before the first LLM call.
+     * Each string is pushed to the kernel's `memory` partition.
+     */
+    initialMemory?: string[];
+    skillDir?: string;
+    knowledgeSource?: KnowledgeSource;
+    signalSource?: SignalSource;
+    dreamStore?: DreamStore;
+    agentId?: string;
+    governance?: Governance;
+    /** Host-provided skill content map (name → markdown body). WASM has no fs access. */
+    skillContentMap?: Map<string, string>;
+}
+export declare class Agent {
+    private readonly provider;
+    private readonly options;
+    private tools;
+    private blockedTools;
+    private extensions;
+    private interrupted;
+    private pendingInterrupt;
+    private _pendingSkills;
+    constructor(provider: LLMProvider, options: AgentOptions);
+    register(...tools: RegisteredTool[]): this;
+    unregister(name: string): this;
+    blockTool(name: string): this;
+    interrupt(): void;
+    run(goal: string, criteria?: string[], extensions?: Record<string, unknown>): Promise<string>;
+    runStreaming(goal: string, criteria?: string[], extensions?: Record<string, unknown>): AsyncIterable<StreamEvent>;
+    /** Register available skills from host-provided metadata (WASM has no fs access). */
+    setAvailableSkills(skills: SkillMetadata[]): void;
+}

package/dist/agent.js

@@ -0,0 +1,244 @@
+import { executeTools } from "./tools/index.js";
+async function loadKernel() {
+    return import("@deepstrike/wasm-kernel");
+}
+export class Agent {
+    provider;
+    options;
+    tools = new Map();
+    blockedTools = new Set();
+    extensions;
+    interrupted = false;
+    pendingInterrupt = false;
+    _pendingSkills = [];
+    constructor(provider, options) {
+        this.provider = provider;
+        this.options = options;
+        this.extensions = options.extensions ?? {};
+    }
+    register(...tools) {
+        for (const t of tools)
+            this.tools.set(t.schema.name, t);
+        return this;
+    }
+    unregister(name) { this.tools.delete(name); return this; }
+    blockTool(name) { this.blockedTools.add(name); return this; }
+    interrupt() { this.interrupted = true; }
+    async run(goal, criteria, extensions) {
+        let text = "";
+        for await (const evt of this.runStreaming(goal, criteria, extensions)) {
+            if (evt.type === "text_delta")
+                text += evt.delta;
+        }
+        return text;
+    }
+    async *runStreaming(goal, criteria, extensions) {
+        this.interrupted = false;
+        this.pendingInterrupt = false;
+        if (this.options.knowledgeSource) {
+            await this.options.knowledgeSource.init();
+        }
+        const kernel = await loadKernel();
+        if (this.options.governance)
+            this.options.governance._attach(kernel);
+        const ext = { ...this.extensions, ...(extensions ?? {}) };
+        const sm = new kernel.LoopStateMachine({
+            maxTokens: this.options.maxTokens,
+            maxTurns: this.options.maxTurns ?? 25,
+            timeoutMs: this.options.timeoutMs,
+        });
+        sm.setTools(Array.from(this.tools.values()).map(t => t.schema));
+        if (this.options.systemPrompt) {
+            const tokens = Math.max(1, Math.ceil(this.options.systemPrompt.length / 4));
+            sm.addSystemMessage(this.options.systemPrompt, tokens);
+        }
+        for (const mem of this.options.initialMemory ?? []) {
+            sm.addMemoryMessage(mem, Math.max(1, Math.ceil(mem.length / 4)));
+        }
+        if (this._pendingSkills.length > 0) {
+            sm.setAvailableSkills(this._pendingSkills);
+        }
+        if (this.options.dreamStore && this.options.agentId)
+            sm.setMemoryEnabled(true);
+        if (this.options.knowledgeSource)
+            sm.setKnowledgeEnabled(true);
+        const router = new kernel.SignalRouter(256);
+        let action = sm.start({ goal, criteria: criteria ?? [] });
+        let finalText = "";
+        const sessionStart = Date.now();
+        const sessionMsgs = [{ role: "user", content: goal }];
+        while (!sm.isTerminal()) {
+            if (this.interrupted) {
+                action = sm.feedTimeout();
+                break;
+            }
+            if (this.pendingInterrupt) {
+                this.pendingInterrupt = false;
+                action = sm.feedTimeout();
+                break;
+            }
+            if (this.options.signalSource) {
+                const sig = await this.options.signalSource.nextSignal();
+                if (sig) {
+                    const kernelSig = {
+                        id: crypto.randomUUID(),
+                        source: sig.source,
+                        signalType: sig.signalType,
+                        urgency: sig.urgency,
+                        summary: String(sig.payload?.goal ?? sig.signalType),
+                        payload: JSON.stringify(sig.payload ?? {}),
+                        dedupeKey: sig.dedupeKey,
+                        timestampMs: Date.now(),
+                    };
+                    const disposition = router.ingest(kernelSig, action.kind === "execute_tools");
+                    if (disposition === "interrupt_now") {
+                        action = sm.feedTimeout();
+                        break;
+                    }
+                    if (disposition === "interrupt")
+                        this.pendingInterrupt = true;
+                }
+            }
+            sm.takeObservations();
+            if (action.kind === "call_llm") {
+                finalText = "";
+                const finalToolCalls = [];
+                const messages = (action.messages ?? []);
+                const tools = (action.tools ?? []);
+                try {
+                    for await (const evt of this.provider.stream(messages, tools, Object.keys(ext).length ? ext : undefined)) {
+                        yield evt;
+                        if (evt.type === "text_delta")
+                            finalText += evt.delta;
+                        else if (evt.type === "tool_call") {
+                            const tc = evt;
+                            finalToolCalls.push({ id: tc.id, name: tc.name, arguments: JSON.stringify(tc.arguments) });
+                        }
+                    }
+                }
+                catch (err) {
+                    yield { type: "error", message: String(err) };
+                    action = sm.feedTimeout();
+                    break;
+                }
+                action = sm.feedLlmResponse({ role: "assistant", content: finalText, toolCalls: finalToolCalls });
+                sessionMsgs.push({ role: "assistant", content: finalText, toolCalls: finalToolCalls });
+            }
+            else if (action.kind === "execute_tools") {
+                const allCalls = (action.calls ?? []);
+                // Governance check
+                const permittedCalls = [];
+                for (const c of allCalls) {
+                    if (this.blockedTools.has(c.name)) {
+                        yield { type: "error", message: `tool blocked: ${c.name}` };
+                        continue;
+                    }
+                    if (this.options.governance) {
+                        this.options.governance.setTime(Date.now());
+                        const verdict = this.options.governance.evaluate(c.name, c.arguments);
+                        if (verdict.kind === "deny") {
+                            yield { type: "error", message: `permission denied: ${c.name} — ${verdict.reason}` };
+                            continue;
+                        }
+                        if (verdict.kind === "ask_user") {
+                            yield { type: "permission_request", callId: c.id, toolName: c.name, arguments: c.arguments, reason: verdict.reason };
+                            continue;
+                        }
+                    }
+                    permittedCalls.push(c);
+                }
+                const skillCalls = permittedCalls.filter(c => c.name === "skill");
+                const memoryCalls = permittedCalls.filter(c => c.name === "memory");
+                const knowledgeCalls = permittedCalls.filter(c => c.name === "knowledge");
+                const regularCalls = permittedCalls.filter(c => !["skill", "memory", "knowledge"].includes(c.name));
+                // skill: WASM host must provide skill content via a registered tool or extension
+                const skillContentMap = this.options.skillContentMap ?? new Map();
+                const skillResults = skillCalls.map(c => {
+                    const args = tryParseJson(c.arguments);
+                    const name = String(args?.name ?? "");
+                    const content = skillContentMap.get(name);
+                    const output = content ?? `Skill "${name}" not found.`;
+                    return { callId: c.id, output, isError: content === undefined };
+                });
+                const memoryResults = [];
+                if (this.options.dreamStore && this.options.agentId) {
+                    for (const c of memoryCalls) {
+                        const args = tryParseJson(c.arguments);
+                        const query = String(args?.query ?? "");
+                        const topK = typeof args?.top_k === "number" ? args.top_k : 5;
+                        const entries = await this.options.dreamStore.search(this.options.agentId, query, topK);
+                        const output = entries.length ? entries.map(e => `[score=${e.score.toFixed(3)}] ${e.text}`).join("\n---\n") : "No relevant memories found.";
+                        yield { type: "tool_result", callId: c.id, name: c.name, content: output, isError: false };
+                        memoryResults.push({ callId: c.id, output, isError: false });
+                    }
+                }
+                else {
+                    for (const c of memoryCalls)
+                        memoryResults.push({ callId: c.id, output: "Memory retrieval not configured.", isError: true });
+                }
+                const knowledgeResults = [];
+                if (this.options.knowledgeSource) {
+                    for (const c of knowledgeCalls) {
+                        const args = tryParseJson(c.arguments);
+                        const query = String(args?.query ?? "");
+                        const topK = typeof args?.top_k === "number" ? args.top_k : 5;
+                        const snippets = await this.options.knowledgeSource.retrieve(query, topK);
+                        const output = snippets.length ? snippets.join("\n---\n") : "No relevant knowledge found.";
+                        yield { type: "tool_result", callId: c.id, name: c.name, content: output, isError: false };
+                        knowledgeResults.push({ callId: c.id, output, isError: false });
+                    }
+                }
+                else {
+                    for (const c of knowledgeCalls)
+                        knowledgeResults.push({ callId: c.id, output: "Knowledge source not configured.", isError: true });
+                }
+                const results = await executeTools(regularCalls, this.tools);
+                for (const r of results) {
+                    const name = regularCalls.find(c => c.id === r.callId)?.name ?? "";
+                    yield { type: "tool_result", callId: r.callId, name, content: r.output, isError: r.isError };
+                }
+                action = sm.feedToolResults([
+                    ...skillResults,
+                    ...memoryResults,
+                    ...knowledgeResults,
+                    ...results.map(r => ({ callId: r.callId, output: r.output, isError: r.isError })),
+                ]);
+            }
+            else if (action.kind === "done") {
+                break;
+            }
+        }
+        const result = action.result;
+        if (this.options.dreamStore && this.options.agentId && sessionMsgs.length > 1) {
+            try {
+                await this.options.dreamStore.saveSession({
+                    sessionId: crypto.randomUUID(),
+                    agentId: this.options.agentId,
+                    messages: sessionMsgs,
+                    metadata: null,
+                    createdAtMs: sessionStart,
+                    updatedAtMs: Date.now(),
+                });
+            }
+            catch { /* session save failure must not surface to caller */ }
+        }
+        yield {
+            type: "done",
+            iterations: result?.turnsUsed ?? 0,
+            totalTokens: Number(result?.totalTokensUsed ?? 0),
+            status: result?.termination ?? "error",
+        };
+    }
+    /** Register available skills from host-provided metadata (WASM has no fs access). */
+    setAvailableSkills(skills) {
+        this._pendingSkills = skills;
+    }
+}
+function tryParseJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/governance.d.ts

@@ -0,0 +1,14 @@
+export interface GovernanceVerdict {
+    kind: "allow" | "deny" | "rate_limited" | "ask_user";
+    reason?: string;
+    retryAfterMs?: number;
+}
+export declare class Governance {
+    private _inner;
+    private _pendingBlocks;
+    /** Called by Agent after the WASM kernel module is loaded. */
+    _attach(kernel: typeof import("@deepstrike/wasm-kernel")): void;
+    blockTool(name: string): this;
+    setTime(nowMs: number): this;
+    evaluate(toolName: string, argsJson: string): GovernanceVerdict;
+}

package/dist/governance.js

@@ -0,0 +1,28 @@
+export class Governance {
+    _inner = null;
+    _pendingBlocks = [];
+    /** Called by Agent after the WASM kernel module is loaded. */
+    _attach(kernel) {
+        if (this._inner)
+            return;
+        this._inner = new kernel.Governance();
+        for (const name of this._pendingBlocks)
+            this._inner.blockTool(name);
+    }
+    blockTool(name) {
+        if (this._inner)
+            this._inner.blockTool(name);
+        else
+            this._pendingBlocks.push(name);
+        return this;
+    }
+    setTime(nowMs) {
+        this._inner?.setTime(nowMs);
+        return this;
+    }
+    evaluate(toolName, argsJson) {
+        if (!this._inner)
+            return { kind: "allow" };
+        return this._inner.evaluate(toolName, argsJson);
+    }
+}