@deepstrike/sdk 0.2.18 → 0.2.20

package/dist/index.d.ts

@@ -15,6 +15,11 @@ export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export type { ExecutionPlane, RunContext } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
 export type { SessionLog, SessionEvent } from "./runtime/session-log.js";
+export { ReplayProvider } from "./runtime/replay-provider.js";
+export type { ReplayProviderOpts } from "./runtime/replay-provider.js";
+export { extractRecordedMessages } from "./runtime/replay-fixture.js";
+export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "./runtime/eval.js";
+export type { Criterion, Verdict, VerdictDetail, JudgeArgs } from "./runtime/eval.js";
 export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "./runtime/os-profile.js";
 export type { NativeOsProfile, OsProfileId } from "./runtime/os-profile.js";
 export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories, } from "./runtime/os-snapshot.js";

package/dist/index.js

@@ -9,6 +9,9 @@ export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
 export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
+export { ReplayProvider } from "./runtime/replay-provider.js";
+export { extractRecordedMessages } from "./runtime/replay-fixture.js";
+export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "./runtime/eval.js";
 export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, assertNativeProfile, osProfile, } from "./runtime/os-profile.js";
 export { rebuildOsSnapshotFromSessionEvents, sessionLogHasRequiredCategories, } from "./runtime/os-snapshot.js";
 export { categoryForKind, kernelObservationToSessionEvent } from "./runtime/kernel-event-log.js";

package/dist/runtime/eval.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `judge()` — one-shot quality scoring against a goal + criteria using the kernel's `gen_eval`.
+ *
+ * Wraps the three kernel free functions `buildEvalMessages` / `parseVerdict` / `verdictOutputSchema`
+ * (folded out of the old EvalPipeline class in 0.5.0) into a small typed surface that's safe to
+ * call from a benchmark harness, a CI gate, or any caller that just wants "does this result meet
+ * the criteria?" without setting up `HarnessLoop`.
+ *
+ * The judge is a single LLM call: build the eval prompt → stream → parse verdict. No retry loop,
+ * no skill extraction, no harness state. Use `HarnessLoop` if you want the retry/refine flow.
+ */
+import type { LLMProvider, Message } from "../types.js";
+export interface Criterion {
+    /** The criterion text the judge evaluates against. */
+    text: string;
+    /** When true (default), failing this criterion fails the overall verdict. */
+    required?: boolean;
+    /** Optional weight for weighted scoring (kernel-defined semantics). */
+    weight?: number;
+}
+export interface VerdictDetail {
+    criterion: string;
+    passed: boolean;
+    score: number;
+    feedback: string;
+}
+export interface Verdict {
+    passed: boolean;
+    /** 0..1 — kernel-defined aggregate score. */
+    overallScore: number;
+    feedback: string;
+    details: VerdictDetail[];
+}
+export interface JudgeArgs {
+    /** Provider used for the eval LLM call. Often a cheaper model than the main run. */
+    provider: LLMProvider;
+    /** The task goal the result is being evaluated against. */
+    goal: string;
+    /** The criteria the judge scores against. */
+    criteria: Criterion[];
+    /** The agent's result text (final reply, or a structured summary when the run was incomplete). */
+    result: string;
+    /** Optional abort signal forwarded to provider.stream. */
+    signal?: AbortSignal;
+}
+/**
+ * Build the kernel's eval prompt for (goal, criteria, result).
+ * Exposed in case a caller wants to render the prompt without calling the LLM (e.g., dry-run cost
+ * estimation, fixture generation). For the common case, use `judge()`.
+ */
+export declare function buildEvalMessages(goal: string, criteria: Criterion[], result: string): Message[];
+/** Parse a Verdict from raw judge-LLM text. Throws on schema mismatch. */
+export declare function parseVerdict(text: string): Verdict;
+/** The JSON Schema the kernel expects judge output to conform to. */
+export declare function verdictOutputSchema(): Record<string, unknown>;
+/**
+ * Run one judge pass: render the eval prompt, stream the provider, parse the verdict.
+ * Throws when the provider returns no text or returns content that fails verdict parsing.
+ */
+export declare function judge(args: JudgeArgs): Promise<Verdict>;

package/dist/runtime/eval.js

@@ -0,0 +1,55 @@
+/**
+ * `judge()` — one-shot quality scoring against a goal + criteria using the kernel's `gen_eval`.
+ *
+ * Wraps the three kernel free functions `buildEvalMessages` / `parseVerdict` / `verdictOutputSchema`
+ * (folded out of the old EvalPipeline class in 0.5.0) into a small typed surface that's safe to
+ * call from a benchmark harness, a CI gate, or any caller that just wants "does this result meet
+ * the criteria?" without setting up `HarnessLoop`.
+ *
+ * The judge is a single LLM call: build the eval prompt → stream → parse verdict. No retry loop,
+ * no skill extraction, no harness state. Use `HarnessLoop` if you want the retry/refine flow.
+ */
+import { getKernel } from "../kernel.js";
+/**
+ * Build the kernel's eval prompt for (goal, criteria, result).
+ * Exposed in case a caller wants to render the prompt without calling the LLM (e.g., dry-run cost
+ * estimation, fixture generation). For the common case, use `judge()`.
+ */
+export function buildEvalMessages(goal, criteria, result) {
+    return getKernel().buildEvalMessages(goal, criteria.map(c => ({ text: c.text, required: c.required ?? true, weight: c.weight })), result, 1, // attempt
+    false);
+}
+/** Parse a Verdict from raw judge-LLM text. Throws on schema mismatch. */
+export function parseVerdict(text) {
+    const v = getKernel().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 function verdictOutputSchema() {
+    return JSON.parse(getKernel().verdictOutputSchema(false));
+}
+/**
+ * Run one judge pass: render the eval prompt, stream the provider, parse the verdict.
+ * Throws when the provider returns no text or returns content that fails verdict parsing.
+ */
+export async function judge(args) {
+    const msgs = 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/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

@@ -15,6 +15,30 @@ import { LargeResultSpool } from "./large-result-spool.js";
 export interface SchedulerBudget {
     maxWallMs?: number;
 }
+/** P0-C tool-gating telemetry: per-LLM-turn metrics, emitted via `RuntimeOptions.onTurnMetrics`.
+ *  Pure observation — no behavior change. Feeds the go/no-go analysis for epoch skill gating (P1-B):
+ *  - `toolsExposed` vs `toolsCalled` quantifies over-exposure.
+ *  - `activeSkill` across consecutive turns yields the skill *dwell* `D` (how long a skill stays
+ *    loaded) — the break-even input that decides whether dynamic gating beats the cache-bust cost.
+ *  - `cacheReadTokens` / `cacheCreationTokens` give the prompt-cache hit baseline to compare against
+ *    after B/D ship. */
+export interface TurnMetrics {
+    /** 1-based kernel turn this LLM call belongs to. */
+    turn: number;
+    /** Number of tool schemas exposed to the model this turn (base + meta, after run-profile gating). */
+    toolsExposed: number;
+    /** Number of tool calls the model emitted this turn. */
+    toolsCalled: number;
+    /** The skill loaded and in effect going into this turn (the most recent `skill` tool call's name),
+     *  or undefined if none is active. Consecutive equal values measure dwell. */
+    activeSkill?: string;
+    /** Full prompt size the provider reported (uncached + cache read + cache creation). */
+    inputTokens: number;
+    /** Tokens served from the prompt cache this turn (Anthropic `cache_read_input_tokens`). */
+    cacheReadTokens: number;
+    /** Tokens written to the prompt cache this turn (Anthropic `cache_creation_input_tokens`). */
+    cacheCreationTokens: number;
+}
 export interface RuntimeOptions {
     provider: LLMProvider;
     /** M4/G5: cumulative token cap for this run (the kernel's `max_total_tokens`). A workflow node's
@@ -98,6 +122,20 @@ export interface RuntimeOptions {
     }) => Promise<MilestoneCheckResult> | MilestoneCheckResult;
     /** Passed to kernel start_run for role/isolation metadata. */
     runSpec?: AgentRunSpec;
+    /** P0-A tool gating: a static per-run tool profile — only these tool ids (plus the
+     *  skill/memory/knowledge/update_plan meta-tools) are exposed to the model each turn.
+     *  Sugar that 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 are set; synthesizes a minimal run spec when `runSpec` is absent. Omitted/empty
+     *  ⇒ all registered tools exposed (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 that stay exposed even when an active skill narrows the toolset
+     *  (read/search/bash etc.). Empty/absent ⇒ skills narrow to exactly their declared `allowed_tools`
+     *  + meta-tools. Opt-in: with no skill declaring `allowed_tools`, gating never engages. */
+    stableCoreToolIds?: string[];
     /** Loaded via load_milestone_contract before run start. */
     milestoneContract?: MilestoneContract;
     /** Custom sub-agent host driver; defaults to SubAgentOrchestrator. */

package/dist/runtime/runner.js

@@ -819,15 +819,19 @@ export class RuntimeRunner {
         if (this.opts.skillDir) {
             const { scanSkillDir } = await import("../skills/loader.js");
             const metas = await scanSkillDir(this.opts.skillDir);
+            // P1-B: pass the full SkillMetadata (incl. `allowedTools`) straight through — re-mapping it
+            // field-by-field previously dropped `allowedTools`.
             kernelApply(runtime, this.pendingObservations, {
                 kind: "set_available_skills",
-                skills: metas.map((m) => skillMetadataToKernel({
-                    name: m.name,
-                    description: m.description,
-                    whenToUse: m.whenToUse,
-                    effort: m.effort,
-                    estimatedTokens: m.estimatedTokens ?? 0,
-                })),
+                skills: metas.map(m => skillMetadataToKernel(m)),
+            });
+        }
+        // P1-B/D: configure the stable-core tool ids (always exposed under skill gating). Empty/absent
+        // ⇒ skills narrow to exactly their declared tools + meta-tools.
+        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) {
@@ -876,14 +880,43 @@ export class RuntimeRunner {
                 kind: "preload_history",
                 messages: replayed.map(messageToKernelMessage),
             });
+            // P1-B B3: rebuild active-skill gating after a wake by re-emitting SkillActivated for each
+            // `skill` tool call in the replayed history (active_skills is not snapshotted — graceful).
+            // The catalog (set_available_skills) was already fed above, so allowed_tools resolves.
+            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 { /* malformed skill args — 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`. `allowedToolIds` augments an explicit spec's filter, else synthesizes
+        // a minimal top-level spec carrying just the filter (reuses the existing run_spec wire — no
+        // new ABI). Unset on both ⇒ no run_spec ⇒ 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;
@@ -944,6 +977,9 @@ 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 (updated when the model's
+        // `skill` tool call resolves). Drives the per-turn `activeSkill` metric → dwell measurement.
+        let activeSkill;
         while (!runtime.isTerminal()) {
             // Page-in must run before appendObservations drains pending kernel observations.
             if (action.kind === "execute_tool") {
@@ -985,6 +1021,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 {
@@ -999,6 +1037,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;
@@ -1079,6 +1120,32 @@ export class RuntimeRunner {
                     toolCalls: finalToolCalls,
                     providerReplay,
                 }));
+                // P0-C: emit per-turn tool-gating telemetry. `activeSkill` reflects the skill in effect
+                // GOING INTO this turn; a `skill` call here only takes effect next turn, so emit first, then
+                // advance. Wrapped so a faulty sink can never break the run (pure observation).
+                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;
@@ -1214,6 +1281,22 @@ export class RuntimeRunner {
                         this.pendingSpoolOutputs.set(call.id, { tool: call.name, output: result.output });
                     }
                 }
+                // P1-B B3: a `skill` call that resolved successfully activates that skill in the kernel, so
+                // the next `call_provider` narrows the toolset to its declared tools. Fed before `tool_results`
+                // (which computes the next action). Errs-open: a failed/missing skill load doesn't activate.
+                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 { /* malformed skill args — skip activation */ }
+                }
                 action = kernelAction(runtime, this.pendingObservations, {
                     kind: "tool_results",
                     results: toolResults.map(toolResultToKernel),

package/dist/skills/loader.d.ts

@@ -4,6 +4,10 @@ export interface SkillMetadata {
     whenToUse?: string;
     effort?: number;
     estimatedTokens?: number;
+    /** P1-B tool gating: tool ids this skill needs. When the skill is active, the kernel narrows the
+     *  exposed toolset to `stable-core ∪ allowedTools`. Parsed from `allowed_tools:` frontmatter
+     *  (comma-separated or `[a, b]`). Absent ⇒ the skill does not narrow (back-compat). */
+    allowedTools?: string[];
 }
 /** Read one skill file and return its body (frontmatter stripped). */
 export declare function readSkillFile(skillDir: string, name: string): Promise<string | null>;

package/dist/skills/loader.js

@@ -1,5 +1,13 @@
 import { readFile, readdir } from "fs/promises";
 import path from "path";
+/** Parse a frontmatter tool list: `read, write` or `[read, write]` → ["read","write"]. */
+function parseToolList(v) {
+    if (v == null || v === "")
+        return undefined;
+    const ids = String(v).trim().replace(/^\[|\]$/g, "").split(",")
+        .map(x => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+    return ids.length ? ids : undefined;
+}
 function parseFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
     if (!match)
@@ -38,6 +46,7 @@ export async function scanSkillDir(skillDir) {
             whenToUse: meta.when_to_use ? String(meta.when_to_use) : undefined,
             effort: meta.effort ? Number(meta.effort) : undefined,
             estimatedTokens: meta.estimated_tokens ? Number(meta.estimated_tokens) : undefined,
+            allowedTools: parseToolList(meta.allowed_tools),
         });
     }
     return results;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "DeepStrike Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.99.0",
-    "@deepstrike/core": "0.2.18",
+    "@deepstrike/core": "0.2.20",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },