@deepstrike/wasm 0.2.18 → 0.2.20

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { RuntimeRunner, collectText, InMemorySessionLog, LocalExecutionPlane, DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, } from "./runtime/index.js";
+export { RuntimeRunner, collectText, InMemorySessionLog, LocalExecutionPlane, DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, ReplayProvider, extractRecordedMessages, judge, buildEvalMessages, parseVerdict, verdictOutputSchema, } from "./runtime/index.js";
+export type { ReplayProviderOpts, Criterion, Verdict, VerdictDetail, JudgeArgs, } from "./runtime/index.js";
 export type { NativeOsProfile, OsProfileId, MemoryPolicy, MemoryWriteRateLimit, ResourceQuota, RuntimeOptions, SchedulerBudget, SessionEvent, SessionLog, RunContext, ExecutionPlane, } from "./runtime/index.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { RuntimeRunner, collectText, InMemorySessionLog, LocalExecutionPlane, DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, } from "./runtime/index.js";
+export { RuntimeRunner, collectText, InMemorySessionLog, LocalExecutionPlane, DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, ReplayProvider, extractRecordedMessages, judge, buildEvalMessages, parseVerdict, verdictOutputSchema, } from "./runtime/index.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
 export { workflowSpecToKernel, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, submitWorkflowNodesTool, startWorkflowTool, fanoutSynthesize, generateAndFilter, verifyRules } from "./runtime/types/agent.js";

package/dist/runtime/eval.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `judge()` — one-shot quality scoring against a goal + criteria using the kernel's `gen_eval`.
+ *
+ * Mirrors the Node SDK's `node/src/runtime/eval.ts`. WASM port differences:
+ *   - The kernel is loaded asynchronously via `getKernel()`, so the wrapper functions are async
+ *     where the Node versions are sync. `judge()` was already async on both ports.
+ *
+ * See node/src/runtime/eval.ts for the full design rationale.
+ */
+import type { LLMProvider, Message } from "../types.js";
+export interface Criterion {
+    text: string;
+    required?: boolean;
+    weight?: number;
+}
+export interface VerdictDetail {
+    criterion: string;
+    passed: boolean;
+    score: number;
+    feedback: string;
+}
+export interface Verdict {
+    passed: boolean;
+    overallScore: number;
+    feedback: string;
+    details: VerdictDetail[];
+}
+export interface JudgeArgs {
+    provider: LLMProvider;
+    goal: string;
+    criteria: Criterion[];
+    result: string;
+    signal?: AbortSignal;
+}
+/** Build the kernel's eval prompt for (goal, criteria, result). Async — the WASM kernel loads lazily. */
+export declare function buildEvalMessages(goal: string, criteria: Criterion[], result: string): Promise<Message[]>;
+/** Parse a Verdict from raw judge-LLM text. */
+export declare function parseVerdict(text: string): Promise<Verdict>;
+/** The JSON Schema the kernel expects judge output to conform to. */
+export declare function verdictOutputSchema(): Promise<Record<string, unknown>>;
+/**
+ * Run one judge pass: render the eval prompt, stream the provider, parse the verdict.
+ * Throws when the provider returns no text.
+ */
+export declare function judge(args: JudgeArgs): Promise<Verdict>;

package/dist/runtime/eval.js

@@ -0,0 +1,51 @@
+/**
+ * `judge()` — one-shot quality scoring against a goal + criteria using the kernel's `gen_eval`.
+ *
+ * Mirrors the Node SDK's `node/src/runtime/eval.ts`. WASM port differences:
+ *   - The kernel is loaded asynchronously via `getKernel()`, so the wrapper functions are async
+ *     where the Node versions are sync. `judge()` was already async on both ports.
+ *
+ * See node/src/runtime/eval.ts for the full design rationale.
+ */
+import { getKernel } from "./kernel.js";
+/** Build the kernel's eval prompt for (goal, criteria, result). Async — the WASM kernel loads lazily. */
+export async function buildEvalMessages(goal, criteria, result) {
+    const kernel = await getKernel();
+    return kernel.buildEvalMessages(goal, criteria.map(c => ({ text: c.text, required: c.required ?? true, weight: c.weight })), result, 1, false);
+}
+/** Parse a Verdict from raw judge-LLM text. */
+export async function parseVerdict(text) {
+    const kernel = await getKernel();
+    const v = kernel.parseVerdict(text);
+    return {
+        passed: v.passed,
+        overallScore: v.overallScore,
+        feedback: v.feedback,
+        details: (v.details ?? []),
+    };
+}
+/** The JSON Schema the kernel expects judge output to conform to. */
+export async function verdictOutputSchema() {
+    const kernel = await getKernel();
+    return JSON.parse(kernel.verdictOutputSchema(false));
+}
+/**
+ * Run one judge pass: render the eval prompt, stream the provider, parse the verdict.
+ * Throws when the provider returns no text.
+ */
+export async function judge(args) {
+    const msgs = await buildEvalMessages(args.goal, args.criteria, args.result);
+    const ctx = {
+        systemText: msgs.filter(m => m.role === "system").map(m => m.content).join("\n\n"),
+        turns: msgs.filter(m => m.role !== "system"),
+    };
+    let text = "";
+    for await (const evt of args.provider.stream(ctx, [], undefined, undefined, args.signal)) {
+        if (evt.type === "text_delta")
+            text += evt.delta;
+    }
+    if (!text) {
+        throw new Error("judge: provider produced no text");
+    }
+    return parseVerdict(text);
+}

package/dist/runtime/index.d.ts

@@ -7,5 +7,10 @@ export { RuntimeRunner, collectText } from "./runner.js";
 export { builtinReducers, resolveReducer } from "./reducers.js";
 export type { Reducer, ReducerRegistry, ReducerInput } from "./reducers.js";
 export { getKernel } from "./kernel.js";
+export { ReplayProvider } from "./replay-provider.js";
+export type { ReplayProviderOpts } from "./replay-provider.js";
+export { extractRecordedMessages } from "./replay-fixture.js";
+export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "./eval.js";
+export type { Criterion, Verdict, VerdictDetail, JudgeArgs } from "./eval.js";
 export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, } from "./os-profile.js";
 export type { NativeOsProfile, OsProfileId } from "./os-profile.js";

package/dist/runtime/index.js

@@ -3,4 +3,7 @@ export { LocalExecutionPlane } from "./execution-plane.js";
 export { RuntimeRunner, collectText } from "./runner.js";
 export { builtinReducers, resolveReducer } from "./reducers.js";
 export { getKernel } from "./kernel.js";
+export { ReplayProvider } from "./replay-provider.js";
+export { extractRecordedMessages } from "./replay-fixture.js";
+export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "./eval.js";
 export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, } from "./os-profile.js";

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

@@ -14,6 +14,9 @@ interface SkillMetadata {
     whenToUse?: string;
     effort?: number;
     estimatedTokens?: number;
+    /** P1-B tool gating: tool ids this skill needs; when active the kernel narrows the toolset to
+     *  `stable-core ∪ allowedTools`. Absent ⇒ no narrowing (back-compat). */
+    allowedTools?: string[];
 }
 export declare const KERNEL_ABI_VERSION = 1;
 export interface KernelRuntimeHandle {

package/dist/runtime/kernel-step.js

@@ -24,6 +24,9 @@ export function skillMetadataToKernel(skill) {
         out.when_to_use = skill.whenToUse;
     if (skill.effort !== undefined)
         out.effort = skill.effort;
+    // P1-B: forward declared tool ids (additive; omitted when empty so existing skills' wire is unchanged).
+    if (skill.allowedTools?.length)
+        out.allowed_tools = skill.allowedTools;
     return out;
 }
 export function messageToKernelMessage(message) {

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

@@ -0,0 +1,26 @@
+/**
+ * Fixture helpers for `ReplayProvider`.
+ *
+ * The canonical persistence shape for a recorded run is a `SessionLog` of `llm_completed` events
+ * (already written by the runner on every live run). `extractRecordedMessages` walks such a log and
+ * pulls the assistant turns in order, so the fixture is just "a prior session log + the messages
+ * the LLM produced". No new on-disk format.
+ */
+import type { Message } from "../types.js";
+import type { SessionEvent } from "./session-log.js";
+/**
+ * Extract the ordered list of assistant Messages from a recorded session log.
+ *
+ * Walks `llm_completed` events (which is what the runner appends for every LLM call) and produces
+ * one Message per event. Pass the result directly to `new ReplayProvider(messages)`.
+ *
+ * Accepts both wire shapes the SDK uses interchangeably:
+ *   - in-memory: `{ toolCalls, tokenCount, providerReplay }` (camelCase)
+ *   - serialised session-log: `{ tool_calls, token_count, provider_replay }` (snake_case)
+ *
+ * @param events Session events, in original order. Accepts both `{ event, seq }` (the shape
+ *               `SessionLog.read()` returns) and a bare `SessionEvent[]`.
+ */
+export declare function extractRecordedMessages(events: Array<{
+    event: SessionEvent;
+} | SessionEvent>): Message[];

package/dist/runtime/replay-fixture.js

@@ -0,0 +1,51 @@
+/**
+ * Fixture helpers for `ReplayProvider`.
+ *
+ * The canonical persistence shape for a recorded run is a `SessionLog` of `llm_completed` events
+ * (already written by the runner on every live run). `extractRecordedMessages` walks such a log and
+ * pulls the assistant turns in order, so the fixture is just "a prior session log + the messages
+ * the LLM produced". No new on-disk format.
+ */
+/**
+ * Extract the ordered list of assistant Messages from a recorded session log.
+ *
+ * Walks `llm_completed` events (which is what the runner appends for every LLM call) and produces
+ * one Message per event. Pass the result directly to `new ReplayProvider(messages)`.
+ *
+ * Accepts both wire shapes the SDK uses interchangeably:
+ *   - in-memory: `{ toolCalls, tokenCount, providerReplay }` (camelCase)
+ *   - serialised session-log: `{ tool_calls, token_count, provider_replay }` (snake_case)
+ *
+ * @param events Session events, in original order. Accepts both `{ event, seq }` (the shape
+ *               `SessionLog.read()` returns) and a bare `SessionEvent[]`.
+ */
+export function extractRecordedMessages(events) {
+    const out = [];
+    for (const entry of events) {
+        const event = isWrapped(entry) ? entry.event : entry;
+        if (event.kind !== "llm_completed")
+            continue;
+        const e = event;
+        const tcRaw = (e.toolCalls ?? e.tool_calls);
+        const tokenCount = (e.tokenCount ?? e.token_count);
+        out.push({
+            role: "assistant",
+            content: typeof e.content === "string" ? e.content : "",
+            ...(Array.isArray(tcRaw) && tcRaw.length > 0
+                ? { toolCalls: normalizeToolCalls(tcRaw) }
+                : {}),
+            ...(tokenCount !== undefined ? { tokenCount } : {}),
+        });
+    }
+    return out;
+}
+function isWrapped(x) {
+    return !!x && typeof x === "object" && "event" in x;
+}
+function normalizeToolCalls(tcs) {
+    return tcs.map(tc => ({
+        id: tc.id,
+        name: tc.name,
+        arguments: typeof tc.arguments === "string" ? tc.arguments : JSON.stringify(tc.arguments),
+    }));
+}

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

@@ -0,0 +1,69 @@
+/**
+ * ReplayProvider — an LLMProvider that emits previously-recorded assistant messages
+ * instead of calling a real LLM API.
+ *
+ * Purpose: deterministic re-runs for benchmarking, CI, and golden regression. Useful when you want
+ * to hold the model's behavior constant and measure something else (prompt-size cost Δ across
+ * RuntimeOptions variants, codegen of follow-on kernel work, etc.).
+ *
+ * Distinct from `provider-replay.ts`: that file's `seedProviderReplay` / `peekProviderReplay` is a
+ * session-repair *reasoning-content cache* — it preserves `reasoning_content` / `native_blocks` so
+ * the model sees its own thinking when context is re-rendered. It does NOT skip LLM calls.
+ * `ReplayProvider` is the orthogonal, request-skipping mechanism: it returns recorded responses
+ * directly, never hitting an API.
+ *
+ * Cost-accounting under replay:
+ *   - `inputTokens` is ESTIMATED from the rendered context this call carries (NOT a recorded value
+ *     from the original run). That's the point of replay-for-benchmarking: prompt may differ across
+ *     variants, response is pinned, so a cost Δ purely reflects the prompt change.
+ *   - `outputTokens` is taken from `message.tokenCount` when present; otherwise estimated from
+ *     `message.content.length / 4`.
+ *   - `cacheReadInputTokens` / `cacheCreationInputTokens` are emitted as 0 — replay has no real
+ *     cache state. Mechanisms whose Δ depends on cache behavior must validate with a live A/B too.
+ *
+ * Tokenizer: by default a `chars/4` estimator (±20% for English; worse for code/JSON). For tighter
+ * numbers plug `opts.tokenizer = tiktokenEncoder` or similar.
+ */
+import type { LLMProvider, Message, ProviderDescriptor, ProviderRunState, RenderedContext, StreamEvent, ToolSchema } from "../types.js";
+export interface ReplayProviderOpts {
+    /**
+     * Maps a rendered-context text payload to a token count. Defaults to `chars / 4`.
+     * Pass a real encoder (tiktoken etc.) for accurate cost accounting under replay.
+     */
+    tokenizer?: (text: string) => number;
+    /**
+     * Provider descriptor advertised via `descriptor()`. Defaults to a generic
+     * `{ provider: "replay", protocol: "replay", ... }` shape. Override when a downstream consumer
+     * needs to detect the original provider (e.g., for protocol-specific decoding paths).
+     */
+    descriptor?: ProviderDescriptor;
+    /**
+     * When true, `stream()` and `complete()` wrap to the start once the fixture is exhausted,
+     * instead of throwing. Useful for loop tests that need to keep going past the recorded length.
+     * Defaults to false.
+     */
+    wrap?: boolean;
+}
+export declare class ReplayProvider implements LLMProvider {
+    private cursor;
+    private readonly messages;
+    private readonly tokenizer;
+    private readonly _descriptor;
+    private readonly wrap;
+    /**
+     * @param messages Ordered list of assistant messages to replay (one per LLM call).
+     * @param opts Optional tokenizer / descriptor / wrap-around behavior.
+     */
+    constructor(messages: ReadonlyArray<Message>, opts?: ReplayProviderOpts);
+    descriptor(): ProviderDescriptor;
+    /** Number of messages consumed so far. */
+    consumed(): number;
+    /** Number of messages remaining in the fixture (returns 0 in wrap mode once cursor passes end). */
+    remaining(): number;
+    /** Reset the cursor — useful for re-running the same fixture in a fresh session. */
+    reset(): void;
+    complete(_context: RenderedContext, _tools: ToolSchema[]): Promise<Message>;
+    stream(context: RenderedContext, tools: ToolSchema[], _extensions?: Record<string, unknown>, _state?: ProviderRunState, _signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    private pull;
+    private estimateInputTokens;
+}

package/dist/runtime/replay-provider.js

@@ -0,0 +1,152 @@
+/**
+ * ReplayProvider — an LLMProvider that emits previously-recorded assistant messages
+ * instead of calling a real LLM API.
+ *
+ * Purpose: deterministic re-runs for benchmarking, CI, and golden regression. Useful when you want
+ * to hold the model's behavior constant and measure something else (prompt-size cost Δ across
+ * RuntimeOptions variants, codegen of follow-on kernel work, etc.).
+ *
+ * Distinct from `provider-replay.ts`: that file's `seedProviderReplay` / `peekProviderReplay` is a
+ * session-repair *reasoning-content cache* — it preserves `reasoning_content` / `native_blocks` so
+ * the model sees its own thinking when context is re-rendered. It does NOT skip LLM calls.
+ * `ReplayProvider` is the orthogonal, request-skipping mechanism: it returns recorded responses
+ * directly, never hitting an API.
+ *
+ * Cost-accounting under replay:
+ *   - `inputTokens` is ESTIMATED from the rendered context this call carries (NOT a recorded value
+ *     from the original run). That's the point of replay-for-benchmarking: prompt may differ across
+ *     variants, response is pinned, so a cost Δ purely reflects the prompt change.
+ *   - `outputTokens` is taken from `message.tokenCount` when present; otherwise estimated from
+ *     `message.content.length / 4`.
+ *   - `cacheReadInputTokens` / `cacheCreationInputTokens` are emitted as 0 — replay has no real
+ *     cache state. Mechanisms whose Δ depends on cache behavior must validate with a live A/B too.
+ *
+ * Tokenizer: by default a `chars/4` estimator (±20% for English; worse for code/JSON). For tighter
+ * numbers plug `opts.tokenizer = tiktokenEncoder` or similar.
+ */
+const DEFAULT_DESCRIPTOR = {
+    provider: "replay",
+    protocol: "openai-chat",
+    model: "replay",
+    reasoning: { supported: false, preserveAcrossToolTurns: false },
+    toolCalls: { supported: true, requiresStrictPairing: false },
+};
+export class ReplayProvider {
+    cursor = 0;
+    messages;
+    tokenizer;
+    _descriptor;
+    wrap;
+    /**
+     * @param messages Ordered list of assistant messages to replay (one per LLM call).
+     * @param opts Optional tokenizer / descriptor / wrap-around behavior.
+     */
+    constructor(messages, opts = {}) {
+        this.messages = messages;
+        this.tokenizer = opts.tokenizer ?? defaultTokenizer;
+        this._descriptor = opts.descriptor ?? DEFAULT_DESCRIPTOR;
+        this.wrap = !!opts.wrap;
+    }
+    descriptor() {
+        return this._descriptor;
+    }
+    /** Number of messages consumed so far. */
+    consumed() {
+        return this.cursor;
+    }
+    /** Number of messages remaining in the fixture (returns 0 in wrap mode once cursor passes end). */
+    remaining() {
+        return Math.max(0, this.messages.length - this.cursor);
+    }
+    /** Reset the cursor — useful for re-running the same fixture in a fresh session. */
+    reset() {
+        this.cursor = 0;
+    }
+    async complete(_context, _tools) {
+        const msg = this.pull();
+        return {
+            role: "assistant",
+            content: msg.content,
+            ...(msg.toolCalls ? { toolCalls: msg.toolCalls } : {}),
+            ...(msg.tokenCount !== undefined ? { tokenCount: msg.tokenCount } : {}),
+        };
+    }
+    async *stream(context, tools, _extensions, _state, _signal) {
+        const msg = this.pull();
+        const inputTokens = this.estimateInputTokens(context, tools);
+        const outputTokens = msg.tokenCount !== undefined ? msg.tokenCount : this.tokenizer(msg.content || "");
+        const usage = {
+            type: "usage",
+            totalTokens: inputTokens + outputTokens,
+            inputTokens,
+            outputTokens,
+            cacheReadInputTokens: 0,
+            cacheCreationInputTokens: 0,
+        };
+        yield usage;
+        if (msg.content) {
+            const delta = { type: "text_delta", delta: msg.content };
+            yield delta;
+        }
+        for (const tc of msg.toolCalls ?? []) {
+            let args = {};
+            try {
+                args = JSON.parse(tc.arguments || "{}");
+            }
+            catch {
+                // Malformed recorded arguments — pass an empty object. The runner's downstream tool
+                // execution will surface the error if the tool needs them.
+            }
+            const call = { type: "tool_call", id: tc.id, name: tc.name, arguments: args };
+            yield call;
+        }
+    }
+    pull() {
+        if (this.cursor >= this.messages.length) {
+            if (this.wrap && this.messages.length > 0) {
+                this.cursor = 0;
+            }
+            else {
+                throw new Error(`ReplayProvider: fixture exhausted (consumed=${this.cursor}, total=${this.messages.length})`);
+            }
+        }
+        return this.messages[this.cursor++];
+    }
+    estimateInputTokens(context, tools) {
+        const text = renderContextToText(context, tools);
+        return this.tokenizer(text);
+    }
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+function defaultTokenizer(text) {
+    return Math.ceil(text.length / 4);
+}
+function renderContextToText(context, tools) {
+    const parts = [];
+    if (context.systemText)
+        parts.push(context.systemText);
+    if (context.systemStable)
+        parts.push(context.systemStable);
+    if (context.systemKnowledge)
+        parts.push(context.systemKnowledge);
+    if (context.stateTurn?.content)
+        parts.push(context.stateTurn.content);
+    for (const turn of context.turns ?? []) {
+        if (turn.content)
+            parts.push(turn.content);
+        for (const part of turn.contentParts ?? []) {
+            const p = part;
+            if (typeof p.output === "string")
+                parts.push(p.output);
+            else if (typeof p.text === "string")
+                parts.push(p.text);
+        }
+        for (const tc of turn.toolCalls ?? []) {
+            parts.push(`${tc.name} ${tc.arguments}`);
+        }
+    }
+    for (const tool of tools) {
+        parts.push(`${tool.name} ${tool.description} ${tool.parameters}`);
+    }
+    return parts.join("\n");
+}

package/dist/runtime/runner.d.ts

@@ -40,6 +40,19 @@ export interface MemoryPolicy {
     maxContentBytes?: number;
     maxNameLength?: number;
 }
+/** P0-C tool-gating telemetry: per-LLM-turn metrics, emitted via `RuntimeOptions.onTurnMetrics`.
+ *  Pure observation — no behavior change. `toolsExposed` vs `toolsCalled` quantifies over-exposure;
+ *  consecutive equal `activeSkill` values measure skill dwell `D`; the cache split gives the
+ *  prompt-cache hit baseline. Mirrors the node SDK. */
+export interface TurnMetrics {
+    turn: number;
+    toolsExposed: number;
+    toolsCalled: number;
+    activeSkill?: string;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
 export interface RuntimeOptions {
     provider: LLMProvider;
     /** M1/G3 intelligence routing: resolve a per-node provider from a workflow node's `modelHint`.
@@ -90,6 +103,18 @@ export interface RuntimeOptions {
         requiredEvidence: string[];
     }) => Promise<MilestoneCheckResult> | MilestoneCheckResult;
     runSpec?: AgentRunSpec;
+    /** P0-A tool gating: a static per-run tool profile — only these tool ids (plus the meta-tools)
+     *  are exposed to the model each turn. Lowers to the same `capability_filter` sub-agents use;
+     *  byte-stable across the run, so it never busts the prompt-cache prefix. Augments `runSpec`'s
+     *  filter when both set; synthesizes a minimal spec otherwise. Omitted/empty ⇒ no gating. */
+    allowedToolIds?: string[];
+    /** P0-C: optional per-turn metrics sink for tool-gating telemetry (see `TurnMetrics`). Pure
+     *  observation; invoked once per LLM turn. Never throws into the run loop (errors are swallowed). */
+    onTurnMetrics?: (metrics: TurnMetrics) => void;
+    /** P1-B/D stable-core: tool ids always exposed under skill gating. Empty/absent ⇒ skills narrow
+     *  to exactly their declared tools + meta-tools. (wasm skills come from `skillContentMap`; gating
+     *  engages only once that carries per-skill tool lists.) */
+    stableCoreToolIds?: string[];
     dreamProvider?: LLMProvider;
     dreamSummarizer?: DreamSummarizer;
     dreamSystemPrompt?: string;

package/dist/runtime/runner.js

@@ -313,6 +313,13 @@ export class RuntimeRunner {
                 skills: metas.map(skillMetadataToKernel),
             });
         }
+        // P1-B/D: configure stable-core tool ids (always exposed under skill gating).
+        if (this.opts.stableCoreToolIds?.length) {
+            kernelApply(runtime, this.pendingObservations, {
+                kind: "set_stable_core_tools",
+                tool_ids: this.opts.stableCoreToolIds,
+            });
+        }
         if (this.opts.dreamStore && this.opts.agentId) {
             kernelApply(runtime, this.pendingObservations, { kind: "set_memory_enabled", enabled: true });
         }
@@ -337,18 +344,45 @@ export class RuntimeRunner {
         if (priorEvents && priorEvents.length > 0) {
             const repaired = repairEventsForRecovery(priorEvents, maxBytes);
             seedProviderReplayFromEvents(this.opts.provider, repaired);
+            const replayed = replayMessages(repaired, maxBytes);
             kernelApply(runtime, this.pendingObservations, {
                 kind: "preload_history",
-                messages: replayMessages(repaired, maxBytes).map(messageToKernelMessage),
+                messages: replayed.map(messageToKernelMessage),
             });
+            // P1-B B3: rebuild active-skill gating after a wake (active_skills is not snapshotted).
+            for (const m of replayed) {
+                for (const tc of m.toolCalls ?? []) {
+                    if (tc.name !== "skill")
+                        continue;
+                    try {
+                        const name = JSON.parse(tc.arguments || "{}").name;
+                        if (name)
+                            kernelApply(runtime, this.pendingObservations, { kind: "skill_activated", name });
+                    }
+                    catch { /* skip */ }
+                }
+            }
         }
         const sessionStart = Date.now();
         const startPayload = {
             kind: "start_run",
             task: { goal, criteria },
         };
-        if (this.opts.runSpec) {
-            startPayload.run_spec = agentRunSpecToKernel(this.opts.runSpec);
+        // P0-A: lower an explicit `runSpec` and/or the `allowedToolIds` profile to the kernel's
+        // `capability_filter` (reuses the existing run_spec wire — no new ABI). Unset on both ⇒ no
+        // gating (铁律: no config = old behavior).
+        const allowedToolIds = this.opts.allowedToolIds;
+        const hasProfile = allowedToolIds !== undefined && allowedToolIds.length > 0;
+        if (this.opts.runSpec || hasProfile) {
+            const baseSpec = this.opts.runSpec ?? {
+                identity: { agentId: this.opts.agentId ?? "root", sessionId, isSubAgent: false },
+                role: "custom",
+                goal,
+            };
+            const spec = hasProfile
+                ? { ...baseSpec, capabilityFilter: { ...baseSpec.capabilityFilter, allowedIds: allowedToolIds } }
+                : baseSpec;
+            startPayload.run_spec = agentRunSpecToKernel(spec);
         }
         const osProfile = assertNativeProfile(this.opts.osProfile ?? "native");
         const attentionPolicy = this.opts.attentionPolicy ?? osProfile.attentionPolicy;
@@ -404,6 +438,8 @@ export class RuntimeRunner {
             ? kernelAction(runtime, this.pendingObservations, { kind: "resume" })
             : kernelAction(runtime, this.pendingObservations, startPayload);
         let hasAttemptedReactiveCompact = false;
+        // P0-C: the skill loaded and in effect going into the current turn → per-turn `activeSkill` metric.
+        let activeSkill;
         while (!runtime.isTerminal()) {
             if (action.kind === "execute_tool") {
                 await this.applyKernelPageIn(runtime, sessionId);
@@ -437,6 +473,8 @@ export class RuntimeRunner {
                 let turnTokens = 0;
                 let turnInputTokens = 0;
                 let turnOutputTokens = 0;
+                let turnCacheReadTokens = 0;
+                let turnCacheCreationTokens = 0;
                 let shouldRetry = false;
                 const abortSignal = this.abortController?.signal;
                 try {
@@ -449,6 +487,9 @@ export class RuntimeRunner {
                             turnTokens = usageEvt.totalTokens;
                             turnInputTokens = usageEvt.inputTokens ?? 0;
                             turnOutputTokens = usageEvt.outputTokens ?? 0;
+                            // P0-C: capture the prompt-cache split for the tool-gating hit-rate baseline.
+                            turnCacheReadTokens = usageEvt.cacheReadInputTokens ?? 0;
+                            turnCacheCreationTokens = usageEvt.cacheCreationInputTokens ?? 0;
                             continue;
                         }
                         yield evt;
@@ -527,6 +568,31 @@ export class RuntimeRunner {
                     toolCalls: finalToolCalls,
                     providerReplay,
                 }));
+                // P0-C: per-turn tool-gating telemetry. `activeSkill` reflects the skill in effect GOING INTO
+                // this turn; a `skill` call here only takes effect next turn — emit first, then advance.
+                if (this.opts.onTurnMetrics) {
+                    try {
+                        this.opts.onTurnMetrics({
+                            turn: runtime.turn(),
+                            toolsExposed: tools.length,
+                            toolsCalled: finalToolCalls.length,
+                            activeSkill,
+                            inputTokens: turnInputTokens,
+                            cacheReadTokens: turnCacheReadTokens,
+                            cacheCreationTokens: turnCacheCreationTokens,
+                        });
+                    }
+                    catch { /* metrics must never break the run */ }
+                }
+                const skillCall = finalToolCalls.find(c => c.name === "skill");
+                if (skillCall) {
+                    try {
+                        const name = JSON.parse(skillCall.arguments || "{}").name;
+                        if (name)
+                            activeSkill = name;
+                    }
+                    catch { /* malformed skill args — leave activeSkill unchanged */ }
+                }
             }
             else if (action.kind === "execute_tool") {
                 const allCalls = action.calls;
@@ -637,6 +703,20 @@ export class RuntimeRunner {
                         this.pendingSpoolOutputs.set(call.id, { tool: call.name, output: result.output });
                     }
                 }
+                // P1-B B3: a successfully-resolved `skill` call activates that skill for the next turn.
+                for (const call of allCalls) {
+                    if (call.name !== "skill")
+                        continue;
+                    const res = toolResults.find(r => r.callId === call.id);
+                    if (!res || res.isError)
+                        continue;
+                    try {
+                        const name = JSON.parse(call.arguments || "{}").name;
+                        if (name)
+                            kernelApply(runtime, this.pendingObservations, { kind: "skill_activated", name });
+                    }
+                    catch { /* skip */ }
+                }
                 action = kernelAction(runtime, this.pendingObservations, {
                     kind: "tool_results",
                     results: toolResults.map(toolResultToKernel),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/wasm",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "DeepStrike WASM SDK — browser, Cloudflare Workers, Deno Deploy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "node --experimental-vm-modules node_modules/.bin/jest"
   },
   "dependencies": {
-    "@deepstrike/wasm-kernel": "0.2.18"
+    "@deepstrike/wasm-kernel": "0.2.20"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",