@deepstrike/wasm 0.2.21 → 0.2.25

package/dist/governance.d.ts

@@ -37,7 +37,16 @@ export interface GovernancePolicy {
         windowMs: number;
     }[];
     constraints?: GovernanceConstraint[];
+    /** I5: when true (default), the runner pre-filters denied tools out of the schema. */
+    surfaceDeniedInSystem?: boolean;
 }
+/** I5: bucket tools into allowed/denied per the policy. Pure. Mirrors Node. */
+export declare function governanceFilterSchema<T extends {
+    name: string;
+}>(tools: T[], policy: GovernancePolicy | undefined): {
+    allowed: T[];
+    denied: string[];
+};
 export type GovernanceConstraint = {
     kind: "required";
     tool: string;

package/dist/governance.js

@@ -51,6 +51,31 @@ export class Governance {
         return this._inner.evaluate(toolName, argsJson);
     }
 }
+/** I5: bucket tools into allowed/denied per the policy. Pure. Mirrors Node. */
+export function governanceFilterSchema(tools, policy) {
+    if (!policy)
+        return { allowed: tools, denied: [] };
+    const vetoes = new Set(policy.vetoes ?? []);
+    const allowed = [];
+    const denied = [];
+    const matches = (pat, name) => pat === name || (pat.endsWith("*") && name.startsWith(pat.slice(0, -1)));
+    for (const tool of tools) {
+        if (vetoes.has(tool.name)) {
+            denied.push(tool.name);
+            continue;
+        }
+        let action = policy.defaultAction ?? "allow";
+        for (const r of policy.rules ?? []) {
+            if (matches(r.pattern, tool.name))
+                action = r.action;
+        }
+        if (action === "deny")
+            denied.push(tool.name);
+        else
+            allowed.push(tool);
+    }
+    return { allowed, denied };
+}
 export function governancePolicyToKernelEvent(policy) {
     return {
         kind: "load_governance_policy",

package/dist/harness/index.d.ts

@@ -3,6 +3,10 @@ export interface Criterion {
     text: string;
     required: boolean;
     weight?: number;
+    /** I3.3 (A4): optional stable id from the host's contract layer; threaded to verdictFn. */
+    id?: string;
+    /** I3.3 (A4): host hint — host has a deterministic check for this criterion. */
+    machineCheckable?: boolean;
 }
 export interface CriterionResult {
     criterion: string;
@@ -62,13 +66,22 @@ export declare class SinglePassHarness {
     constructor(runner: RuntimeRunner);
     run(request: HarnessRequest): Promise<HarnessOutcome>;
 }
+/** I3.2 (A2/A3): host-supplied judgment — see Node `VerdictFn` for the full contract. Mirrors. */
+export type VerdictFn = (ctx: {
+    goal: string;
+    criteria: Criterion[];
+    attempt: number;
+    result: string;
+}) => Verdict | undefined | Promise<Verdict | undefined>;
 export interface HarnessLoopOptions {
     maxAttempts?: number;
+    verdictFn?: VerdictFn;
 }
 export declare class HarnessLoop {
     private runner;
     private evalProvider;
     private maxAttempts;
+    private verdictFn?;
     constructor(runner: RuntimeRunner, evalProvider: import("../types.js").LLMProvider, options?: HarnessLoopOptions);
     runStreaming(request: HarnessRequest): AsyncIterable<HarnessEvent>;
 }

package/dist/harness/index.js

@@ -23,10 +23,12 @@ export class HarnessLoop {
     runner;
     evalProvider;
     maxAttempts;
+    verdictFn;
     constructor(runner, evalProvider, options = {}) {
         this.runner = runner;
         this.evalProvider = evalProvider;
         this.maxAttempts = options.maxAttempts ?? 3;
+        this.verdictFn = options.verdictFn;
     }
     async *runStreaming(request) {
         const kernel = await import("@deepstrike/wasm-kernel");
@@ -61,24 +63,31 @@ export class HarnessLoop {
                 }
             }
             yield { type: "supervising" };
-            // #6 (0.5.0): eval/verdict compute is the kernel's stateless free functions (was EvalPipeline).
-            const evalMsgs = kernel.buildEvalMessages(request.goal, criteria, lastResult, attempt, true);
-            let evalText = "";
-            const evalContext = {
-                systemText: "",
-                turns: evalMsgs,
-            };
-            for await (const evt of this.evalProvider.stream(evalContext, [], undefined)) {
-                if (evt.type === "text_delta")
-                    evalText += evt.delta;
+            // I3.2 (A2/A3): host-supplied verdictFn short-circuits the LLM eval. Undefined ⇒ defer.
+            let verdict;
+            if (this.verdictFn) {
+                verdict = await this.verdictFn({ goal: request.goal, criteria, attempt, result: lastResult });
+            }
+            if (!verdict) {
+                // #6 (0.5.0): eval/verdict compute is the kernel's stateless free functions (was EvalPipeline).
+                const evalMsgs = kernel.buildEvalMessages(request.goal, criteria, lastResult, attempt, true);
+                let evalText = "";
+                const evalContext = {
+                    systemText: "",
+                    turns: evalMsgs,
+                };
+                for await (const evt of this.evalProvider.stream(evalContext, [], undefined)) {
+                    if (evt.type === "text_delta")
+                        evalText += evt.delta;
+                }
+                const parsed = kernel.parseVerdict(evalText);
+                verdict = {
+                    passed: parsed.passed,
+                    overallScore: parsed.overallScore,
+                    feedback: parsed.feedback,
+                    details: (parsed.details ?? []),
+                };
             }
-            const parsed = kernel.parseVerdict(evalText);
-            const verdict = {
-                passed: parsed.passed,
-                overallScore: parsed.overallScore,
-                feedback: parsed.feedback,
-                details: (parsed.details ?? []),
-            };
             if (verdict.passed) {
                 yield { type: "done", verdict, iterations: lastIterations, totalTokens: lastTotalTokens, status: lastStatus };
                 return;

package/dist/index.d.ts

@@ -12,15 +12,17 @@ export type { GovernanceVerdict } from "./governance.js";
 export { AnthropicProvider } from "./providers/anthropic.js";
 export { OpenAIProvider, QwenProvider, DeepSeekProvider, MiniMaxProvider, KimiProvider } from "./providers/openai.js";
 export { tool, executeTools } from "./tools/index.js";
-export type { RegisteredTool } from "./tools/index.js";
+export type { RegisteredTool, ToolExecContext } from "./tools/index.js";
+export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
+export type { ToolEnvelope, ToolEnvelopeOk, ToolEnvelopeFail } from "./tools/errors.js";
 export { WorkingMemory } from "./memory/index.js";
 export { InMemoryDreamStore } from "./memory/in-memory-store.js";
 export type { DreamStore, DreamResult, SessionStore, SessionData, SessionMessage, MemoryEntry, CurationResult, CurationStats, } from "./memory/index.js";
 export type { KnowledgeSource } from "./knowledge/index.js";
 export { SinglePassHarness, HarnessLoop } from "./harness/index.js";
-export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions } from "./harness/index.js";
+export type { HarnessRequest, HarnessOutcome, HarnessLoopOptions, CriterionResult, HarnessEvent, VerdictFn } from "./harness/index.js";
 export { ScheduledPrompt } from "./signals/index.js";
 export type { RuntimeSignal, SignalSource } from "./signals/index.js";
 export { PermissionManager, PermissionMode } from "./safety/index.js";
 export type { PermissionDecision } from "./safety/index.js";
-export type { Message, ToolCall, ToolResult, ToolSchema, RenderedContext, ProviderRunState, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolResultEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, } from "./types.js";
+export type { Message, ToolCall, ToolResult, ToolSchema, RenderedContext, ProviderRunState, StreamEvent, TextDelta, ThinkingDelta, ToolCallEvent, ToolResultEvent, ToolAuditFailedEvent, DoneEvent, ErrorEvent, PermissionRequestEvent, PermissionResolvedEvent, PermissionResponse, LLMProvider, CacheBreakpointStrategy, } from "./types.js";

package/dist/index.js

@@ -7,6 +7,7 @@ export { Governance } from "./governance.js";
 export { AnthropicProvider } from "./providers/anthropic.js";
 export { OpenAIProvider, QwenProvider, DeepSeekProvider, MiniMaxProvider, KimiProvider } from "./providers/openai.js";
 export { tool, executeTools } from "./tools/index.js";
+export { safeTool, ok, fail, ToolError, formatToolError } from "./tools/errors.js";
 export { WorkingMemory } from "./memory/index.js";
 export { InMemoryDreamStore } from "./memory/in-memory-store.js";
 export { SinglePassHarness, HarnessLoop } from "./harness/index.js";

package/dist/providers/anthropic.js

@@ -3,18 +3,66 @@ import { assistantReplayKey, collectStreamMessage, toAnthropicMessages } from ".
 const MAX_CACHE_BREAKPOINTS = 4;
 /** Rolling cache breakpoints reserved for the message history (system uses ≤2). */
 const MESSAGE_CACHE_BREAKPOINTS = 2;
-function buildAnthropicTools(tools, anchorCache) {
+function buildAnthropicTools(tools, anchorCache, strategy) {
+    const emitOnLastTool = anchorCache && (strategy === "default" || strategy === "tools-only");
     return tools.map((t, i) => ({
         name: t.name,
         description: t.description,
         input_schema: JSON.parse(t.parameters),
-        // Anchor a tool breakpoint only when the system blocks won't carry one;
-        // otherwise systemStable already caches the tools prefix (tools render
-        // first), and a redundant tool breakpoint would burn a slot the message
-        // history needs to stay within the 4-breakpoint budget.
-        ...(anchorCache && i === tools.length - 1 ? { cache_control: { type: "ephemeral" } } : {}),
+        ...(emitOnLastTool && i === tools.length - 1 ? { cache_control: { type: "ephemeral" } } : {}),
     }));
 }
+/** Recognised values for the `cacheBreakpointStrategy` extension; unknown → "default". */
+const CACHE_BREAKPOINT_STRATEGIES = new Set([
+    "default", "tools-only", "system-only", "frozen-prefix", "none",
+]);
+function resolveCacheBreakpointStrategy(extensions) {
+    const raw = extensions?.cacheBreakpointStrategy;
+    if (typeof raw === "string" && CACHE_BREAKPOINT_STRATEGIES.has(raw)) {
+        return raw;
+    }
+    return "default";
+}
+/** I1: which slots of the outgoing request carry a `cache_control` breakpoint — used to pro-rata
+ *  attribute the response's `cache_read_input_tokens` (a single scalar). Mirrors Node. */
+function countCacheControlSlots(system, builtTools, msgs) {
+    const sysBp = Array.isArray(system) && system.some(b => b?.cache_control != null);
+    const toolBp = !!builtTools && builtTools.some(t => t?.cache_control != null);
+    let msgBp = false;
+    for (const m of msgs) {
+        if (Array.isArray(m.content)) {
+            if (m.content.some(b => b?.cache_control != null)) {
+                msgBp = true;
+                break;
+            }
+        }
+    }
+    return { system: sysBp, tools: toolBp, messages: msgBp };
+}
+/** I1: split `cache_read_input_tokens` evenly across contributing slots. Remainder lands on the
+ *  first contributing slot to keep the sum exact. Mirrors Node. */
+function estimateCacheReadBySlot(cacheRead, slotBp) {
+    if (cacheRead <= 0)
+        return undefined;
+    const count = (slotBp.system ? 1 : 0) + (slotBp.tools ? 1 : 0) + (slotBp.messages ? 1 : 0);
+    if (count === 0)
+        return undefined;
+    const share = Math.floor(cacheRead / count);
+    const remainder = cacheRead - share * count;
+    const out = {};
+    let firstDone = false;
+    const give = () => { if (!firstDone) {
+        firstDone = true;
+        return share + remainder;
+    } return share; };
+    if (slotBp.system)
+        out.system = give();
+    if (slotBp.tools)
+        out.tools = give();
+    if (slotBp.messages)
+        out.messages = give();
+    return out;
+}
 /**
  * Roll cache breakpoints across the conversation tail so the message-history
  * prefix is written once and re-read on later turns (without this the cached
@@ -27,14 +75,16 @@ function buildAnthropicTools(tools, anchorCache) {
  * only the incremental `[frozen..tail]`. Otherwise fall back to the rolling
  * pair: final message + nearest preceding user turn.
  */
-function applyMessageCacheControl(msgs, frozenPrefixLen) {
+function applyMessageCacheControl(msgs, frozenPrefixLen, strategy) {
     if (!msgs.length)
         return;
+    if (strategy === "tools-only" || strategy === "system-only" || strategy === "none")
+        return;
     const targets = new Set([msgs.length - 1]);
     if (typeof frozenPrefixLen === "number" && frozenPrefixLen >= 1 && frozenPrefixLen < msgs.length) {
         targets.add(frozenPrefixLen - 1);
     }
-    else {
+    else if (strategy === "default") {
         for (let i = msgs.length - 2; i >= 0 && targets.size < MESSAGE_CACHE_BREAKPOINTS; i--) {
             if (msgs[i].role === "user")
                 targets.add(i);
@@ -110,16 +160,19 @@ export class AnthropicProvider {
         return collectStreamMessage(this.stream(context, tools, extensions));
     }
     async *stream(context, tools, extensions, _state, signal) {
+        const strategy = resolveCacheBreakpointStrategy(extensions);
+        const emitOnSystemBlocks = strategy === "default" || strategy === "system-only";
+        const cc = { type: "ephemeral" };
         const systemBlocks = [];
         if (context.systemStable) {
-            systemBlocks.push({ type: "text", text: context.systemStable, cache_control: { type: "ephemeral" } });
+            systemBlocks.push({ type: "text", text: context.systemStable, ...(emitOnSystemBlocks ? { cache_control: cc } : {}) });
         }
         if (context.systemKnowledge) {
-            systemBlocks.push({ type: "text", text: context.systemKnowledge, cache_control: { type: "ephemeral" } });
+            systemBlocks.push({ type: "text", text: context.systemKnowledge, ...(emitOnSystemBlocks ? { cache_control: cc } : {}) });
         }
         const system = systemBlocks.length ? systemBlocks : (context.systemText || undefined);
         const msgs = toAnthropicMessages(context, message => this.nativeAssistantBlocks.get(assistantReplayKey(message)));
-        applyMessageCacheControl(msgs, context.frozenPrefixLen);
+        applyMessageCacheControl(msgs, context.frozenPrefixLen, strategy);
         // Append the volatile State turn AFTER the cache breakpoints (uncached tail);
         // absent on un-rebuilt bindings, where the state is already inside `turns`.
         // Render through toAnthropicMessages so assistant tool_use blocks are
@@ -130,13 +183,16 @@ export class AnthropicProvider {
             msgs.push(...stateMsgs);
         }
         assertCacheBudget(system, tools.length);
+        const builtTools = tools.length ? buildAnthropicTools(tools, !Array.isArray(system), strategy) : undefined;
+        // I1: capture which slots will carry cache_control for pro-rata attribution at usage time.
+        const slotBp = countCacheControlSlots(system, builtTools, msgs);
         const body = {
             model: this.model,
             max_tokens: this.maxTokens,
             messages: msgs,
             stream: true,
             ...(system ? { system } : {}),
-            ...(tools.length ? { tools: buildAnthropicTools(tools, !Array.isArray(system)) } : {}),
+            ...(builtTools ? { tools: builtTools } : {}),
         };
         if (extensions?.enable_thinking) {
             body.thinking = { type: "enabled", budget_tokens: 8000 };
@@ -193,6 +249,7 @@ export class AnthropicProvider {
                             // the kernel reads it as the authoritative context size.
                             const inputTokens = uncachedInput + cacheReadTokens + cacheCreationTokens;
                             if (inputTokens > 0 || outputTokens > 0) {
+                                const bySlot = estimateCacheReadBySlot(cacheReadTokens, slotBp);
                                 yield {
                                     type: "usage",
                                     totalTokens: inputTokens + outputTokens,
@@ -200,6 +257,7 @@ export class AnthropicProvider {
                                     outputTokens,
                                     cacheReadInputTokens: cacheReadTokens,
                                     cacheCreationInputTokens: cacheCreationTokens,
+                                    ...(bySlot ? { cacheReadInputTokensBySlot: bySlot } : {}),
                                 };
                             }
                         }

package/dist/runtime/execution-plane.js

@@ -1,4 +1,5 @@
 import { LargeResultSpool } from "./large-result-spool.js";
+import { formatToolError } from "../tools/errors.js";
 function stripFrontmatter(content) {
     const s = content.trimStart();
     if (!s.startsWith("---"))
@@ -71,19 +72,38 @@ export class LocalExecutionPlane {
                 yield { type: "tool_result", callId: call.id, name: call.name, content: `unknown tool: ${call.name}`, isError: true, isFatal: false, errorKind: "recoverable" };
                 continue;
             }
+            // Per-call `audit` helper: failures collected here are surfaced as `tool_audit_failed`
+            // events rather than flipping the main tool result to `isError: true`.
+            const auditFailures = [];
+            const callCtx = {
+                ...(ctx.cwd !== undefined ? { cwd: ctx.cwd } : {}),
+                audit: async (label, fn) => {
+                    try {
+                        await fn();
+                    }
+                    catch (err) {
+                        auditFailures.push({ label, error: formatToolError(err) });
+                    }
+                },
+            };
             try {
                 const args = JSON.parse(call.arguments || "{}");
-                // M3/G4: pass the run context for tool-ABI parity with Node/Python (`RunContext` is
-                // structurally assignable to the tool's `ToolExecContext`).
-                const output = await registered.execute(args, ctx);
+                // M3/G4: pass the run context (incl. `cwd`, `audit`) for tool-ABI parity with Node/Python.
+                const output = await registered.execute(args, callCtx);
+                for (const f of auditFailures) {
+                    yield { type: "tool_audit_failed", callId: call.id, name: call.name, label: f.label, error: f.error };
+                }
                 yield { type: "tool_result", callId: call.id, name: call.name, content: String(output), isError: false };
             }
             catch (err) {
+                for (const f of auditFailures) {
+                    yield { type: "tool_audit_failed", callId: call.id, name: call.name, label: f.label, error: f.error };
+                }
                 yield {
                     type: "tool_result",
                     callId: call.id,
                     name: call.name,
-                    content: String(err),
+                    content: formatToolError(err),
                     isError: true,
                     isFatal: Boolean(err?.isFatal),
                     errorKind: err?.errorKind,
@@ -134,7 +154,7 @@ export async function resolvePermissionRequest(request, ctx) {
         return {
             approved: false,
             responder: "permission_handler",
-            reason: `permission handler failed: ${String(err)}`,
+            reason: `permission handler failed: ${formatToolError(err)}`,
         };
     }
 }

package/dist/runtime/runner.d.ts

@@ -51,6 +51,12 @@ export interface TurnMetrics {
     activeSkill?: string;
     inputTokens: number;
     cacheReadTokens: number;
+    /** I1: pro-rata per-slot attribution of `cacheReadTokens` (Anthropic only). Mirrors Node. */
+    cacheReadTokensBySlot?: {
+        system?: number;
+        tools?: number;
+        messages?: number;
+    };
     cacheCreationTokens: number;
 }
 export interface RuntimeOptions {
@@ -67,6 +73,12 @@ export interface RuntimeOptions {
     maxTurns?: number;
     timeoutMs?: number;
     agentId?: string;
+    /** I4: optional run-start memory pre-fetch hook (mirrors Node SDK). Called once per run before
+     *  the first LLM turn; each returned query string becomes a dreamStore search; hits page into
+     *  the knowledge partition before turn 1. Requires dreamStore + agentId. */
+    preQueryMemory?: (ctx: {
+        goal: string;
+    }) => Promise<string[] | undefined> | string[] | undefined;
     systemPrompt?: string;
     initialMemory?: string[];
     /** Skill name → markdown body (WASM has no filesystem). */