@deepstrike/sdk 0.2.49 → 0.2.50

package/dist/harness/manifest.d.ts

@@ -22,7 +22,7 @@ export declare function composeSystemPrompt(base: string | undefined, instructio
  * The exact `RuntimeOptions` fields a manifest may drive. Derived via `Pick` so field names and types
  * track `RuntimeOptions` verbatim; anything outside this set is rejected by `applyManifest`/`applyPatch`.
  */
-export type HarnessRuntimePatch = Pick<RuntimeOptions, "maxTurns" | "maxTotalTokens" | "criteriaGate" | "repeatFuse" | "entropyWatch" | "knowledgeBudgetRatio" | "skillLeaseTurns" | "allowedToolIds" | "stableCoreToolIds" | "enablePlanTool" | "skillFilter"> & Pick<MemoryPolicy, "retrievalTopK" | "promotionRecallThreshold">;
+export type HarnessRuntimePatch = Pick<RuntimeOptions, "maxTurns" | "maxTotalTokens" | "criteriaGate" | "repeatFuse" | "entropyWatch" | "knowledgeBudgetRatio" | "skillLeaseTurns" | "allowedToolIds" | "baselineToolIds" | "stableCoreToolIds" | "enablePlanTool" | "skillFilter"> & Pick<MemoryPolicy, "retrievalTopK" | "promotionRecallThreshold">;
 /**
  * The promotion tier of an editable surface — the SECOND axis of the safety boundary (the whitelist is
  * the first). Even a whitelisted surface may need a heavier gate than "typed validation passed".

package/dist/harness/manifest.js

@@ -11,12 +11,16 @@
  * absent, so a proposer can never rewrite them (spec design principle: conservative promotion).
  *
  * Tool/skill surfaces add the SECOND safety invariant (spec design principle A — the capability
- * ceiling): `allowedToolIds`, `stableCoreToolIds`, and `skillFilter` fold onto the host baseline by
- * INTERSECTION, never assignment. A manifest can only NARROW the tools/skills the host already
- * exposes — never widen. Capability expansion (naming a tool the host does not expose) is therefore
- * structurally inexpressible, and the whole security audit stays O(1): read the whitelist, check the
- * one invariant. (`enablePlanTool` is exempt — it toggles a kernel-owned meta-tool, attention-shaping
- * not capability-granting, so it folds by plain assignment.)
+ * ceiling): `allowedToolIds`, `baselineToolIds`, `stableCoreToolIds`, and `skillFilter` fold onto the
+ * host baseline by INTERSECTION, never assignment. A manifest can only NARROW the tools/skills the
+ * host already exposes — never widen. Capability expansion (naming a tool the host does not expose) is
+ * therefore structurally inexpressible, and the whole security audit stays O(1): read the whitelist,
+ * check the one invariant. (`enablePlanTool` is exempt — it toggles a kernel-owned meta-tool,
+ * attention-shaping not capability-granting, so it folds by plain assignment.)
+ *
+ * `toolDispatchGate` is deliberately ABSENT from the whitelist and must stay so: it selects whether
+ * the kernel enforces the exposure surface at dispatch. A proposer that could set it to `"registered"`
+ * would disable the enforcement half of the ceiling it is otherwise structurally unable to widen.
  */
 import { createHash } from "node:crypto";
 import { validateNudgeRules } from "./nudge.js";
@@ -44,7 +48,12 @@ export function composeSystemPrompt(base, instructions) {
 }
 const MEMORY_POLICY_PATCH_KEYS = ["retrievalTopK", "promotionRecallThreshold"];
 /** Tool/skill surfaces whose fold is intersection-with-baseline (capability ceiling), not assignment. */
-const INTERSECTION_PATCH_KEYS = ["allowedToolIds", "stableCoreToolIds", "skillFilter"];
+const INTERSECTION_PATCH_KEYS = [
+    "allowedToolIds",
+    "baselineToolIds",
+    "stableCoreToolIds",
+    "skillFilter",
+];
 const RUNTIME_PATCH_KEYS = [
     "maxTurns",
     "maxTotalTokens",
@@ -54,12 +63,13 @@ const RUNTIME_PATCH_KEYS = [
     "knowledgeBudgetRatio",
     "skillLeaseTurns",
     "allowedToolIds",
+    "baselineToolIds",
     "stableCoreToolIds",
     "enablePlanTool",
     "skillFilter",
     ...MEMORY_POLICY_PATCH_KEYS,
 ];
-/** Bounds for the id-list surfaces (allowedToolIds / stableCoreToolIds / skillFilter). */
+/** Bounds for the id-list surfaces (allowedToolIds / baselineToolIds / stableCoreToolIds / skillFilter). */
 const MAX_TOOL_ID_CHARS = 128;
 const MAX_TOOL_LIST_ENTRIES = 128;
 /**
@@ -165,23 +175,19 @@ function validateRuntimePatch(runtime) {
         }
     }
 }
-/**
- * Validate an id-list surface: array of unique, non-empty strings (each ≤128 chars), ≤128 entries.
- * `allowEmpty` is the load-bearing asymmetry. For the tool-id arrays it is FALSE: the runner reads an
- * empty/absent `allowedToolIds` as "no gating — expose ALL registered tools", so an empty array would
- * WIDEN exposure to everything if it reached the runner (and a zero-tool run is the v0.2.46 pathology).
- * For `skillFilter` it is TRUE: the runner's no-gating sentinel is ONLY `undefined`, and an empty array
- * legitimately means "no skills available" (a proposer may find skills are a distraction) — a narrowing.
- */
-function validateIdList(key, value, allowEmpty) {
+/** Validate an id-list surface: array of unique, non-empty strings (each ≤128 chars), ≤128 entries. */
+function validateIdList(key, value, emptyPolicy) {
     if (!Array.isArray(value))
         throw new TypeError(`runtime.${key} must be a string[]`);
     if (value.length > MAX_TOOL_LIST_ENTRIES) {
         throw new RangeError(`runtime.${key} exceeds ${MAX_TOOL_LIST_ENTRIES} entries`);
     }
-    if (!allowEmpty && value.length === 0) {
+    if (emptyPolicy === "reject:widens" && value.length === 0) {
         throw new RangeError(`runtime.${key} must be a non-empty list — an empty array is read by the runner as "no gating" (expose all registered tools), which WIDENS exposure`);
     }
+    if (emptyPolicy === "reject:drastic" && value.length === 0) {
+        throw new RangeError(`runtime.${key} must be a non-empty list — an empty baseline collapses the pre-activation surface to meta-tools only, which stays a human/host decision`);
+    }
     const seen = new Set();
     for (const entry of value) {
         if (typeof entry !== "string" || entry.length === 0) {
@@ -219,10 +225,13 @@ function validateRuntimeValue(key, value) {
             return;
         case "allowedToolIds":
         case "stableCoreToolIds":
-            validateIdList(key, value, /* allowEmpty */ false);
+            validateIdList(key, value, "reject:widens");
+            return;
+        case "baselineToolIds":
+            validateIdList(key, value, "reject:drastic");
             return;
         case "skillFilter":
-            validateIdList(key, value, /* allowEmpty */ true);
+            validateIdList(key, value, "allow");
             return;
         case "knowledgeBudgetRatio":
             if (typeof value !== "number" || !(value > 0 && value <= 1)) {
@@ -335,7 +344,9 @@ export function applyManifest(manifest, base) {
 }
 /**
  * Fold one intersection surface (capability ceiling): effective = manifest ∩ host-baseline, so a
- * manifest can only NARROW. The empty-baseline meaning is surface-specific and load-bearing:
+ * manifest can only NARROW. The empty-baseline meaning is surface-specific and load-bearing — it
+ * tracks whatever the RUNNER's own no-gating sentinel is for that option, not whether the option
+ * happens to hold tool ids:
  *
  *   - allowedToolIds / stableCoreToolIds — the runner reads an empty OR absent baseline as
  *     "no gating = all registered tools" (the universe), so a non-array/empty baseline yields the
@@ -343,19 +354,22 @@ export function applyManifest(manifest, base) {
  *     empty intersection THROWS: a zero-tool run reprises the v0.2.46 pathology AND the runner would
  *     silently reinterpret the empty result as "no gating" (full exposure) — so we turn the candidate
  *     into a discardable error instead.
- *   - skillFilter — the runner's no-gating sentinel is ONLY `undefined`; an empty-array baseline is a
- *     genuine, maximally-tight ceiling (no skills). So ANY present array (even `[]`) is intersected,
- *     and an empty result is FINE (= no skills). This mirrors the validation asymmetry exactly.
+ *   - skillFilter / baselineToolIds — the runner's no-gating sentinel is ONLY `undefined`; an
+ *     empty-array baseline is a genuine, maximally-tight ceiling (no skills / the minimal meta-only
+ *     tool surface). So ANY present array (even `[]`) is intersected, and an empty result is FINE —
+ *     it reaches the runner as exactly that maximally-tight value, never as "no gating". This mirrors
+ *     the validation asymmetry exactly. `baselineToolIds` sits on THIS side despite being a tool-id
+ *     list: `[]` is its documented minimal surface (kernel `Some([])`), distinct from absent.
  */
 function foldIntersection(key, manifestList, baseList) {
-    const skillLike = key === "skillFilter";
-    // Is the host baseline a real constraining set?  Tool ids: non-empty array only (empty == universe).
-    // skillFilter: any array (empty == the empty set).
-    const constrained = Array.isArray(baseList) && (skillLike || baseList.length > 0);
+    // Is an EMPTY host baseline a maximally-tight ceiling (intersect it, empty result fine) or the
+    // universe (ignore it, empty result is a bug)?
+    const emptyBaselineIsTight = key === "skillFilter" || key === "baselineToolIds";
+    const constrained = Array.isArray(baseList) && (emptyBaselineIsTight || baseList.length > 0);
     const effective = constrained
         ? manifestList.filter(id => baseList.includes(id)) // manifest order → deterministic
         : manifestList;
-    if (!skillLike && effective.length === 0) {
+    if (!emptyBaselineIsTight && effective.length === 0) {
         throw new RangeError(`applyManifest: runtime.${key} intersection is empty — manifest [${manifestList.join(", ")}] ∩ ` +
             `host [${(baseList ?? []).join(", ")}] names no shared tool. A zero-tool run is rejected (it ` +
             `reprises the v0.2.46 pathology and the runner would read empty as "no gating" = full exposure).`);

package/dist/runtime/runner.d.ts

@@ -306,13 +306,57 @@ 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/read_result 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). */
+    /**
+     * The run's **exposure ceiling** — the outer bound on what this run may EVER advertise to the
+     * model. Not a static profile: it is an INTERSECTION applied on every turn (`exposed ⊆ ceiling`),
+     * so every narrowing mechanism operates *within* it and none can widen past it. Skills narrow
+     * inside the ceiling (`allowed_tools`), `baselineToolIds` selects which of the ceiling's tools are
+     * exposed before any skill activates, `stableCoreToolIds` pins tools against skill narrowing, and
+     * the self-harness manifest surface folds by intersection for exactly this reason.
+     *
+     * Exempt on the id axis: the kernel-owned meta-tools (`skill`, `memory`, `knowledge`,
+     * `update_plan`, `read_result`) stay exposed regardless of this list — a ceiling that hid `skill`
+     * would make progressive disclosure unreachable. The KIND axis
+     * (`runSpec.capabilityFilter.allowedKinds`) still applies to them.
+     *
+     * Byte-stable across the run, so it never busts the prompt-cache prefix. Lowers to the same
+     * `capability_filter` sub-agents use: augments `runSpec`'s filter when both are set, else
+     * synthesizes a minimal run spec. Omitted **or empty** ⇒ no ceiling (all registered tools) — the
+     * empty array is NOT a minimal surface here; use `baselineToolIds: []` for that.
+     *
+     * Enforcement: `toolDispatchGate` (default `"exposed"`) makes this a real boundary — a call to a
+     * tool outside the advertised set never executes.
+     */
     allowedToolIds?: string[];
+    /**
+     * The **pre-activation** exposure surface, selected from under the `allowedToolIds` ceiling.
+     * Makes the narrow→wide progressive-disclosure shape expressible: start the run advertising only
+     * these tools, and let a skill activation widen the surface by exactly its declared
+     * `allowed_tools` (still ∩ the ceiling). Per turn:
+     *
+     *   `exposed = meta ∪ ((baseline ∪ stableCore ∪ ⋃ activeSkills.allowed_tools) ∩ ceiling)`
+     *
+     * An active skill that declares no `allowed_tools` contributes nothing — with a baseline set the
+     * surface stays narrow (strict; the legacy errs-open widening is deliberately not inherited).
+     *
+     * `undefined` ⇒ legacy behavior, byte-identical (ceiling + errs-open skill narrowing). `[]` is a
+     * legitimate, distinct value: the minimal surface (meta-tools + `stableCoreToolIds` only) — the
+     * `allowedToolIds` "empty means no gating" trap does NOT recur here. Entries outside the ceiling
+     * silently intersect away (no start_run error), the same fold every id-list surface uses.
+     */
+    baselineToolIds?: string[];
+    /**
+     * Dispatch enforcement for the exposure surface. `"exposed"` (default) is fail-closed: a tool call
+     * the model was never advertised this turn never reaches the host — the kernel commits a
+     * model-visible `governance_denied` result instead ("Tool 'X' is not part of this run's toolset"),
+     * which feeds the repeat fuse like any other denial. Allowed siblings in the same batch still
+     * execute; `pace` and the meta-tool family always pass through.
+     *
+     * `"registered"` is the escape hatch restoring the pre-gate permissive behavior (any registered
+     * tool the model names executes, even if it was gated out of the tools schema). Set it only when a
+     * host deliberately relies on blind calls to unadvertised tools.
+     */
+    toolDispatchGate?: "exposed" | "registered";
     /** 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;

package/dist/runtime/runner.js

@@ -438,6 +438,11 @@ export class RuntimeRunner {
         if (this.opts.criteriaGate !== undefined) {
             config.criteria_gate = this.opts.criteriaGate;
         }
+        // P1: fail-closed dispatch selector (absent ⇒ kernel default "exposed"). "registered" is the
+        // escape hatch back to permissive dispatch; the kernel rejects any other value.
+        if (this.opts.toolDispatchGate !== undefined) {
+            config.tool_dispatch_gate = this.opts.toolDispatchGate;
+        }
         // K2: knowledge budget ratio (absent ⇒ kernel default 0.25; 0 disables).
         if (this.opts.knowledgeBudgetRatio !== undefined) {
             config.knowledge_budget_ratio = this.opts.knowledgeBudgetRatio;
@@ -1579,21 +1584,28 @@ export class RuntimeRunner {
                 kind: "start_run",
                 task: { goal, criteria },
             };
-            // 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).
+            // P0-A: lower an explicit `runSpec`, the `allowedToolIds` ceiling, and/or the `baselineToolIds`
+            // pre-activation surface to the kernel run spec. Each augments an explicit spec, else
+            // synthesizes a minimal top-level spec carrying just the exposure config (reuses the existing
+            // run_spec wire — no new ABI). Unset on all ⇒ 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) {
+            // NOT the `length > 0` idiom above: `baselineToolIds: []` is the legitimate minimal surface
+            // (meta + stable-core only), so mere presence triggers the lowering.
+            const baselineToolIds = this.opts.baselineToolIds;
+            const hasBaseline = baselineToolIds !== undefined;
+            if (this.opts.runSpec || hasProfile || hasBaseline) {
                 const baseSpec = this.opts.runSpec ?? {
                     identity: { agentId: this.opts.agentId ?? "root", sessionId, isSubAgent: false },
                     role: "custom",
                     goal,
                 };
-                const spec = hasProfile
+                let spec = hasProfile
                     ? { ...baseSpec, capabilityFilter: { ...baseSpec.capabilityFilter, allowedIds: allowedToolIds } }
                     : baseSpec;
+                if (hasBaseline)
+                    spec = { ...spec, exposureBaseline: baselineToolIds };
                 startPayload.run_spec = agentRunSpecToKernel(spec);
             }
             // Reserve capacity before start_run. The kernel enforces only this vehicle's grant and reports

package/dist/types/agent.d.ts

@@ -41,6 +41,15 @@ export interface AgentRunSpec {
     /** ③ loop-agent rounds: presence makes this run ONE round of a paced loop (gates the
      *  kernel `pace` meta-tool and arms the pacing trap). */
     loopRound?: LoopRoundSpec;
+    /** Exposure baseline — the PRE-ACTIVATION tool surface *under* the `capabilityFilter` ceiling.
+     *  The ceiling bounds what this run may EVER expose; the baseline selects which of those are
+     *  advertised before any skill activates, so `exposed = meta ∪ ((baseline ∪ stableCore ∪
+     *  ⋃ activeSkills.allowed_tools) ∩ ceiling)`. That makes narrow→wide progressive disclosure
+     *  expressible: a tool can be reachable after `skill(x)` without being advertised beforehand.
+     *  Absent ⇒ legacy behavior (ceiling + errs-open skill narrowing). `[]` is meaningful and
+     *  distinct from absent: the minimal surface (meta-tools + stable-core only). Entries outside
+     *  the ceiling silently intersect away. Lowered from `RuntimeOptions.baselineToolIds`. */
+    exposureBaseline?: string[];
     /** M1/G3: per-agent model preference (e.g. "opus"/"sonnet"/"haiku"); the host resolves it to a
      *  provider via `RuntimeOptions.providerFor`. Host-side routing only — not sent to the kernel. */
     modelHint?: string;

package/dist/types/agent.js

@@ -54,6 +54,11 @@ export function agentRunSpecToKernel(spec) {
             ...(spec.loopRound.defaultAction !== undefined ? { default_action: spec.loopRound.defaultAction } : {}),
         };
     }
+    // Exposure baseline: `undefined` ⇒ omit the field entirely (kernel `None` = legacy behavior);
+    // `[]` ⇒ send `[]` (kernel `Some([])` = the minimal surface). The unset/minimal distinction is
+    // load-bearing, so this is deliberately NOT the `length > 0` idiom `allowedToolIds` uses.
+    if (spec.exposureBaseline !== undefined)
+        out.exposure_baseline = [...spec.exposureBaseline];
     return out;
 }
 export function milestoneContractToKernel(contract) {

package/package.json

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