@deepstrike/sdk 0.2.47 → 0.2.49

package/dist/harness/manifest.d.ts

@@ -1,3 +1,4 @@
+import type { MemoryPolicy } from "../kernel.js";
 import type { RuntimeOptions } from "../runtime/runner.js";
 import type { NudgeRule } from "./nudge.js";
 export interface InstructionProfile {
@@ -21,13 +22,44 @@ 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">;
+export type HarnessRuntimePatch = Pick<RuntimeOptions, "maxTurns" | "maxTotalTokens" | "criteriaGate" | "repeatFuse" | "entropyWatch" | "knowledgeBudgetRatio" | "skillLeaseTurns" | "allowedToolIds" | "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".
+ */
+export type SurfaceTier = "auto" | "screened" | "human";
+/**
+ * Map an editable surface to its promotion tier. Maintained HERE beside the whitelist so a surface can
+ * never be whitelisted without also being assigned a tier (the spec's same-place maintenance rule):
+ *   - "auto"     (Tier A): every `runtime.*` whitelist surface. Typed validation + the capability
+ *                 ceiling invariant + the acceptance rule already guard them, so promotion is fully
+ *                 automatic — there is no free text and no injection surface.
+ *   - "screened" (Tier B): `instructions.*` and `nudges`. Free text can smuggle instructions
+ *                 (persistent prompt-injection laundered through the evidence loop), so a screen runs
+ *                 before promotion.
+ *   - "human"    (Tier C): reserved for capability-WIDENING surfaces. None currently exist — intersection
+ *                 semantics make widening structurally inexpressible — but the enum value exists so a new
+ *                 capability-widening surface cannot be added without consciously assigning it a tier (and
+ *                 building the human gate). `surfaceTier` therefore never returns "human" today — no
+ *                 capability-widening surface is expressible.
+ * An unknown surface / slot / runtime key THROWS (same discipline as applySurfaceEdit): a surface with
+ * no tier must never fall through to auto-promotion.
+ */
+export declare function surfaceTier(targetSurface: string): SurfaceTier;
 export interface HarnessManifest {
     manifestVersion: 1;
     /** Parent manifest digest; `null` for a seed. */
     parent: string | null;
     /** Target-model identifier (per-model profile scenarios). */
     modelProfile?: string;
+    /**
+     * Opaque isolation key — host decides its semantics (user / tenant / agent-group). Orthogonal to
+     * `modelProfile` (never concatenate the two — that reprises the identity-scoping bug class); absent
+     * ⇒ the host treats it as `"default"`. It rides canonical JSON, so digests domain-separate by scope,
+     * but an absent scope leaves a pre-scope manifest's digest byte-identical (canonicalJson skips
+     * undefined). Becomes a lineage directory name downstream, hence the path-safe character bound.
+     */
+    scope?: string;
     instructions?: InstructionProfile;
     nudges?: NudgeRule[];
     runtime?: HarnessRuntimePatch;
@@ -40,6 +72,10 @@ export interface HarnessManifest {
         rationale?: string;
         deltaHeldIn?: number;
         deltaHeldOut?: number;
+        /** Promotion tier of the driving edit. */
+        tier?: SurfaceTier;
+        /** Injection-screen verdict — present only for a screened (Tier B) promotion. */
+        screenVerdict?: "pass" | "screened_out";
     };
 }
 export interface HarnessPatch {

package/dist/harness/manifest.js

@@ -1,5 +1,5 @@
 /**
- * Self-Harness H1.1 + H1.3 — the harness face as DATA.
+ * Self-Harness editable surfaces — the harness face as DATA.
  *
  * A `HarnessManifest` is a versioned, hashable lineage node: the editable surfaces a fixed model may
  * rewrite about its OWN harness — instruction slots, nudge rules, and a whitelisted `RuntimeOptions`
@@ -9,12 +9,22 @@
  *
  * The whitelist is the safety boundary: governance / quota / reliability surfaces are deliberately
  * 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.)
  */
 import { createHash } from "node:crypto";
 import { validateNudgeRules } from "./nudge.js";
 const INSTRUCTION_SLOTS = ["bootstrap", "execution", "verification", "failureRecovery"];
 /** Per-slot upper bound enforced at load and on every `applyPatch` set. */
 const MAX_INSTRUCTION_CHARS = 4000;
+/** A scope key becomes a directory segment; restrict it to a single path-safe token (no separators). */
+const SCOPE_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
 /**
  * Compose the four instruction slots onto `base` in the fixed order base → bootstrap → execution →
  * verification → failureRecovery, joined with `"\n\n"`, skipping empty slots. All-empty ⇒ `base`
@@ -32,6 +42,9 @@ export function composeSystemPrompt(base, instructions) {
     }
     return parts.length === 0 ? base : parts.join("\n\n");
 }
+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 RUNTIME_PATCH_KEYS = [
     "maxTurns",
     "maxTotalTokens",
@@ -40,7 +53,53 @@ const RUNTIME_PATCH_KEYS = [
     "entropyWatch",
     "knowledgeBudgetRatio",
     "skillLeaseTurns",
+    "allowedToolIds",
+    "stableCoreToolIds",
+    "enablePlanTool",
+    "skillFilter",
+    ...MEMORY_POLICY_PATCH_KEYS,
 ];
+/** Bounds for the id-list surfaces (allowedToolIds / stableCoreToolIds / skillFilter). */
+const MAX_TOOL_ID_CHARS = 128;
+const MAX_TOOL_LIST_ENTRIES = 128;
+/**
+ * Map an editable surface to its promotion tier. Maintained HERE beside the whitelist so a surface can
+ * never be whitelisted without also being assigned a tier (the spec's same-place maintenance rule):
+ *   - "auto"     (Tier A): every `runtime.*` whitelist surface. Typed validation + the capability
+ *                 ceiling invariant + the acceptance rule already guard them, so promotion is fully
+ *                 automatic — there is no free text and no injection surface.
+ *   - "screened" (Tier B): `instructions.*` and `nudges`. Free text can smuggle instructions
+ *                 (persistent prompt-injection laundered through the evidence loop), so a screen runs
+ *                 before promotion.
+ *   - "human"    (Tier C): reserved for capability-WIDENING surfaces. None currently exist — intersection
+ *                 semantics make widening structurally inexpressible — but the enum value exists so a new
+ *                 capability-widening surface cannot be added without consciously assigning it a tier (and
+ *                 building the human gate). `surfaceTier` therefore never returns "human" today — no
+ *                 capability-widening surface is expressible.
+ * An unknown surface / slot / runtime key THROWS (same discipline as applySurfaceEdit): a surface with
+ * no tier must never fall through to auto-promotion.
+ */
+export function surfaceTier(targetSurface) {
+    const [head, sub] = targetSurface.split(".");
+    if (head === "instructions") {
+        if (sub === undefined || !INSTRUCTION_SLOTS.includes(sub)) {
+            throw new RangeError(`unknown instruction slot: ${targetSurface}`);
+        }
+        return "screened";
+    }
+    if (head === "nudges") {
+        if (sub !== undefined)
+            throw new RangeError(`nudges surface takes no sub-path: ${targetSurface}`);
+        return "screened";
+    }
+    if (head === "runtime") {
+        if (sub === undefined || !RUNTIME_PATCH_KEYS.includes(sub)) {
+            throw new RangeError(`runtime patch key not in the editable whitelist: ${targetSurface}`);
+        }
+        return "auto";
+    }
+    throw new RangeError(`unknown surface path: ${targetSurface}`);
+}
 // ── Canonical JSON + digest ──────────────────────────────────────────────────
 /** Deterministic serialization: recursive key sort, undefined-valued keys skipped, arrays ordered. */
 function canonicalJson(value) {
@@ -93,6 +152,48 @@ function validateRuntimePatch(runtime) {
         if (value !== undefined)
             validateRuntimeValue(key, value);
     }
+    // Same-manifest structural invariant: stable-core keeps tools exposed while a skill narrows, so it
+    // must never name a tool outside this manifest's OWN exposure ceiling (`allowedToolIds`). Checked
+    // only when both are present; either absent means the ceiling is broader (the whole registered set).
+    const allowed = runtime.allowedToolIds;
+    const stable = runtime.stableCoreToolIds;
+    if (Array.isArray(allowed) && Array.isArray(stable)) {
+        const allowedSet = new Set(allowed);
+        const outside = stable.filter(id => !allowedSet.has(id));
+        if (outside.length > 0) {
+            throw new RangeError(`runtime.stableCoreToolIds must be a subset of runtime.allowedToolIds; outside the ceiling: ${outside.join(", ")}`);
+        }
+    }
+}
+/**
+ * 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) {
+    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) {
+        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`);
+    }
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new TypeError(`runtime.${key} entries must be non-empty strings`);
+        }
+        if (entry.length > MAX_TOOL_ID_CHARS) {
+            throw new RangeError(`runtime.${key} entry exceeds ${MAX_TOOL_ID_CHARS} chars: ${entry.slice(0, 16)}…`);
+        }
+        if (seen.has(entry))
+            throw new RangeError(`runtime.${key} entries must be unique; duplicate: ${entry}`);
+        seen.add(entry);
+    }
 }
 /** Per-key value typing for runtime patches. An LLM proposer WILL eventually put instruction prose
  *  where a boolean belongs; rejecting it here turns a mid-run kernel `InvalidConfig` crash into a
@@ -103,6 +204,8 @@ function validateRuntimeValue(key, value) {
         case "maxTurns":
         case "maxTotalTokens":
         case "skillLeaseTurns":
+        case "retrievalTopK":
+        case "promotionRecallThreshold":
             if (!positiveInt(value))
                 throw new TypeError(`runtime.${key} must be a positive integer`);
             return;
@@ -110,6 +213,17 @@ function validateRuntimeValue(key, value) {
             if (typeof value !== "boolean")
                 throw new TypeError("runtime.criteriaGate must be a boolean");
             return;
+        case "enablePlanTool":
+            if (typeof value !== "boolean")
+                throw new TypeError("runtime.enablePlanTool must be a boolean");
+            return;
+        case "allowedToolIds":
+        case "stableCoreToolIds":
+            validateIdList(key, value, /* allowEmpty */ false);
+            return;
+        case "skillFilter":
+            validateIdList(key, value, /* allowEmpty */ true);
+            return;
         case "knowledgeBudgetRatio":
             if (typeof value !== "number" || !(value > 0 && value <= 1)) {
                 throw new TypeError("runtime.knowledgeBudgetRatio must be a number in (0, 1]");
@@ -176,6 +290,11 @@ export function validateManifest(manifest) {
     if (!Array.isArray(manifest.editableSurfaces) || manifest.editableSurfaces.some(s => typeof s !== "string")) {
         throw new TypeError("manifest.editableSurfaces must be a string[]");
     }
+    if (manifest.scope !== undefined) {
+        if (typeof manifest.scope !== "string" || !SCOPE_PATTERN.test(manifest.scope)) {
+            throw new TypeError("manifest.scope must be a non-empty path-safe token matching /^[A-Za-z0-9._-]{1,64}$/");
+        }
+    }
     if (manifest.instructions !== undefined)
         validateInstructionProfile(manifest.instructions);
     if (manifest.nudges !== undefined)
@@ -198,12 +317,51 @@ export function applyManifest(manifest, base) {
         out.nudges = manifest.nudges;
     if (manifest.runtime !== undefined) {
         for (const [key, value] of Object.entries(manifest.runtime)) {
-            if (value !== undefined)
+            if (value === undefined)
+                continue;
+            if (MEMORY_POLICY_PATCH_KEYS.includes(key)) {
+                out.memoryPolicy = { ...out.memoryPolicy, [key]: value };
+            }
+            else if (INTERSECTION_PATCH_KEYS.includes(key)) {
+                out[key] = foldIntersection(key, value, out[key]);
+            }
+            else {
+                // enablePlanTool + numeric/boolean knobs: plain assignment.
                 out[key] = value;
+            }
         }
     }
     return out;
 }
+/**
+ * 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:
+ *
+ *   - 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
+ *     manifest list verbatim; only a NON-EMPTY baseline is a real ceiling to intersect against. An
+ *     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.
+ */
+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);
+    const effective = constrained
+        ? manifestList.filter(id => baseList.includes(id)) // manifest order → deterministic
+        : manifestList;
+    if (!skillLike && 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).`);
+    }
+    return effective;
+}
 function validatePatchShape(patch) {
     if (typeof patch !== "object" || patch === null)
         throw new TypeError("patch must be an object");

package/dist/harness/nudge.d.ts

@@ -1,5 +1,5 @@
 /**
- * Self-Harness H1.2 — declarative event→note rules (the runtime control-policy surface).
+ * Self-Harness nudge rules — declarative event→note rules (the runtime control-policy surface).
  *
  * A `NudgeRule` says "when this session event fires, push this note to the model". It generalizes the
  * two hard-coded precedents (EntropyWatch.notify_model, the RepeatFuse STOP text) into data the

package/dist/harness/public.d.ts

@@ -4,7 +4,7 @@ export { VerdictFnJudge, LlmEvalJudge, HybridJudge } from "./judge.js";
 export type { AttemptJudge, JudgeContext, JudgeResult, SkillCandidate } from "./judge.js";
 export { judge } from "../runtime/eval.js";
 export type { VerdictDetail, JudgeArgs } from "../runtime/eval.js";
-export { composeSystemPrompt, manifestDigest, applyManifest, applyPatch, validateManifest, } from "./manifest.js";
-export type { InstructionProfile, HarnessManifest, HarnessRuntimePatch, HarnessPatch, } from "./manifest.js";
+export { composeSystemPrompt, manifestDigest, applyManifest, applyPatch, validateManifest, surfaceTier, } from "./manifest.js";
+export type { InstructionProfile, HarnessManifest, HarnessRuntimePatch, HarnessPatch, SurfaceTier, } from "./manifest.js";
 export { NudgeEngine, validateNudgeRules } from "./nudge.js";
 export type { NudgeTrigger, NudgeRule, NudgeOutput } from "./nudge.js";

package/dist/harness/public.js

@@ -2,7 +2,7 @@
 export { AttemptLoop, RuntimeAttemptBody, continueSession, freshWithFeedback, freshWithDigest, } from "./harness.js";
 export { VerdictFnJudge, LlmEvalJudge, HybridJudge } from "./judge.js";
 export { judge } from "../runtime/eval.js";
-// Self-Harness H1: the harness face as data (manifest lineage + declarative event→note rules). The
+// Self-Harness editable surfaces: the harness face as data (manifest lineage + declarative event→note rules). The
 // lab layer loads these through the compiled dist, so they live on this public barrel.
-export { composeSystemPrompt, manifestDigest, applyManifest, applyPatch, validateManifest, } from "./manifest.js";
+export { composeSystemPrompt, manifestDigest, applyManifest, applyPatch, validateManifest, surfaceTier, } from "./manifest.js";
 export { NudgeEngine, validateNudgeRules } from "./nudge.js";

package/dist/runtime/filtered-plane.js

@@ -1,4 +1,7 @@
-const DEFAULT_META_TOOLS = new Set(["skill", "memory", "knowledge", "update_plan"]);
+// Mirrors the kernel's EXPOSURE_EXEMPT_META_TOOLS invariant: kernel-owned meta surfaces are
+// never narrowed away by a tool allow-list. `read_result` is runner-resolved before reaching any
+// plane today, but the lists must not drift.
+const DEFAULT_META_TOOLS = new Set(["skill", "memory", "knowledge", "update_plan", "read_result"]);
 /** Wraps an execution plane, allowing only manifest-permitted tool IDs (+ meta-tools). */
 export class FilteredExecutionPlane {
     inner;

package/dist/runtime/runner.d.ts

@@ -144,18 +144,24 @@ export interface RuntimeOptions {
         phase?: "initial" | "renewal";
     }) => Promise<MemoryQuery[] | undefined> | MemoryQuery[] | undefined;
     systemPrompt?: string;
-    /** Self-Harness H1.1: the four instruction slots (bootstrap/execution/verification/failureRecovery)
+    /** Self-Harness instruction surface: the four instruction slots (bootstrap/execution/verification/failureRecovery)
      *  composed onto `systemPrompt` in fixed order at option normalization. The kernel still sees ONE
      *  system prompt; this is the editable instruction surface the self-harness loop rewrites. Absent ⇒
      *  `systemPrompt` is used verbatim (zero behavior difference). */
     instructions?: InstructionProfile;
-    /** Self-Harness H1.2: declarative event→note rules. On each matching session event a rendered note
+    /** Self-Harness nudge surface: declarative event→note rules. On each matching session event a rendered note
      *  is pushed through the `injectNote` signal channel (same path as `onToolResult`'s `{note}`).
      *  ≤16 rules, validated at construction. Absent/empty ⇒ no engine, no append wrapping, zero
      *  behavior difference. */
     nudges?: NudgeRule[];
     initialMemory?: string[];
     skillDir?: string;
+    /** Host-layer allowlist over the `skillDir` catalog by skill NAME. When set, only scanned skills
+     *  whose name is listed are fed to the kernel via `set_available_skills` (the manifest layer
+     *  intersects onto this host baseline in `applyManifest`). Absent ⇒ zero behavior difference (all
+     *  scanned skills fed); empty array ⇒ no skills (a legitimate narrowing — unlike an empty
+     *  `allowedToolIds`, which the runner reads as "no gating"). Only takes effect when `skillDir` is set. */
+    skillFilter?: string[];
     dreamStore?: DreamStore;
     /** M4: advisory callback when a recalled record crosses the promotion threshold. The host/model
      *  decides whether to pin the record or promote its content into knowledge. */
@@ -301,7 +307,7 @@ export interface RuntimeOptions {
     /** 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.
+     *  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

package/dist/runtime/runner.js

@@ -1466,11 +1466,17 @@ export class RuntimeRunner {
             if (this.opts.skillDir) {
                 const { scanSkillDir } = await import("../skills/loader.js");
                 const metas = await scanSkillDir(this.opts.skillDir);
+                // S2 host-layer skill allowlist: keep only scanned skills named in `skillFilter` before feeding
+                // the catalog. Absent ⇒ feed all (identical to the pre-feature message); empty ⇒ feed none. The
+                // `set_available_skills` message is ALWAYS sent when a skillDir exists (shape preserved) — only
+                // the list narrows; the no-skillDir path stays untouched.
+                const filter = this.opts.skillFilter;
+                const selected = filter === undefined ? metas : metas.filter(m => filter.includes(m.name));
                 // P1-B: pass the full SkillMetadata (incl. `allowedTools`) straight through — re-mapping it
                 // field-by-field previously dropped `allowedTools`.
                 await this.commitKernelApply(runtime, this.pendingObservations, {
                     kind: "set_available_skills",
-                    skills: metas.map(m => skillMetadataToKernel(m)),
+                    skills: selected.map(m => skillMetadataToKernel(m)),
                 });
             }
             // P1-B/D: configure the stable-core tool ids (always exposed under skill gating). Empty/absent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/sdk",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "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.47",
+    "@deepstrike/core": "0.2.49",
     "@google/generative-ai": "^0.24.1",
     "openai": "^5.23.2"
   },