@deepstrike/sdk 0.2.45 → 0.2.47

package/dist/harness/manifest.d.ts

@@ -0,0 +1,71 @@
+import type { RuntimeOptions } from "../runtime/runner.js";
+import type { NudgeRule } from "./nudge.js";
+export interface InstructionProfile {
+    /** Start-up protocol (paper: build_bootstrap_instruction). */
+    bootstrap?: string;
+    /** Execution protocol. */
+    execution?: string;
+    /** Closing verification protocol. */
+    verification?: string;
+    /** Failure-recovery protocol. */
+    failureRecovery?: string;
+}
+/**
+ * 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`
+ * unchanged (identity — the zero-instructions run is byte-for-byte the pre-feature run). The order is
+ * fixed and empty slots are dropped so the composed prefix is byte-stable (prefix-cache axiom).
+ */
+export declare function composeSystemPrompt(base: string | undefined, instructions?: InstructionProfile): string | undefined;
+/**
+ * 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 interface HarnessManifest {
+    manifestVersion: 1;
+    /** Parent manifest digest; `null` for a seed. */
+    parent: string | null;
+    /** Target-model identifier (per-model profile scenarios). */
+    modelProfile?: string;
+    instructions?: InstructionProfile;
+    nudges?: NudgeRule[];
+    runtime?: HarnessRuntimePatch;
+    /** The proposer's edit whitelist — patches may only target a surface listed here. */
+    editableSurfaces: string[];
+    audit?: {
+        round: number;
+        createdBy: "seed" | "proposer";
+        targetCluster?: string;
+        rationale?: string;
+        deltaHeldIn?: number;
+        deltaHeldOut?: number;
+    };
+}
+export interface HarnessPatch {
+    /** Surface path — must be in the manifest's `editableSurfaces`. */
+    targetSurface: string;
+    /** `append` applies only to nudges; `remove` clears a slot or drops a nudge by id. */
+    op: "set" | "append" | "remove";
+    value?: unknown;
+    rationale: string;
+    /** Failure-cluster key this edit is bound to (paper: one edit per failure mechanism). */
+    targetCluster: string;
+    expectedEffect: string;
+}
+/** sha-256 hex over the manifest's canonical JSON — the manifest's stable identity. */
+export declare function manifestDigest(manifest: HarnessManifest): string;
+/** Structural load check — throws on anything a manifest is forbidden to carry. */
+export declare function validateManifest(manifest: HarnessManifest): void;
+/**
+ * Fold a validated manifest onto `base` runtime options. Instructions ride through as DATA — the
+ * runner composes the system prompt once at option normalization so `run_started` and the kernel's
+ * AddSystemMessage stay byte-identical. Runtime keys outside the whitelist throw.
+ */
+export declare function applyManifest(manifest: HarnessManifest, base: RuntimeOptions): RuntimeOptions;
+/**
+ * Apply one structural edit, returning a NEW manifest whose `parent` is the source's digest. Throws
+ * when the surface is off-whitelist, the patch is malformed, or the result violates a bound
+ * (instruction ≤4000 chars, nudge load rules). The source manifest is never mutated.
+ */
+export declare function applyPatch(manifest: HarnessManifest, patch: HarnessPatch): HarnessManifest;

package/dist/harness/manifest.js

@@ -0,0 +1,304 @@
+/**
+ * Self-Harness H1.1 + H1.3 — 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`
+ * subset — plus the audit trail binding each edit to the failure cluster it targets. Every function
+ * here is pure and deterministic (no clock, no randomness, no I/O), so a manifest digest is a stable
+ * identity across processes and the propose→validate→promote loop replays byte-for-byte.
+ *
+ * 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).
+ */
+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;
+/**
+ * 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`
+ * unchanged (identity — the zero-instructions run is byte-for-byte the pre-feature run). The order is
+ * fixed and empty slots are dropped so the composed prefix is byte-stable (prefix-cache axiom).
+ */
+export function composeSystemPrompt(base, instructions) {
+    const parts = [];
+    if (base)
+        parts.push(base);
+    for (const slot of INSTRUCTION_SLOTS) {
+        const text = instructions?.[slot];
+        if (text)
+            parts.push(text);
+    }
+    return parts.length === 0 ? base : parts.join("\n\n");
+}
+const RUNTIME_PATCH_KEYS = [
+    "maxTurns",
+    "maxTotalTokens",
+    "criteriaGate",
+    "repeatFuse",
+    "entropyWatch",
+    "knowledgeBudgetRatio",
+    "skillLeaseTurns",
+];
+// ── Canonical JSON + digest ──────────────────────────────────────────────────
+/** Deterministic serialization: recursive key sort, undefined-valued keys skipped, arrays ordered. */
+function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("harness manifest requires finite numbers");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).filter(key => obj[key] !== undefined).sort();
+        return `{${keys.map(key => `${JSON.stringify(key)}:${canonicalJson(obj[key])}`).join(",")}}`;
+    }
+    throw new TypeError(`harness manifest holds a non-serializable value: ${typeof value}`);
+}
+/** sha-256 hex over the manifest's canonical JSON — the manifest's stable identity. */
+export function manifestDigest(manifest) {
+    return createHash("sha256").update(canonicalJson(manifest), "utf8").digest("hex");
+}
+// ── Load validation ──────────────────────────────────────────────────────────
+function validateInstructionProfile(profile) {
+    if (typeof profile !== "object" || profile === null || Array.isArray(profile)) {
+        throw new TypeError("instructions must be an object");
+    }
+    for (const slot of INSTRUCTION_SLOTS) {
+        const text = profile[slot];
+        if (text === undefined)
+            continue;
+        if (typeof text !== "string")
+            throw new TypeError(`instructions.${slot} must be a string`);
+        if (text.length > MAX_INSTRUCTION_CHARS) {
+            throw new RangeError(`instructions.${slot} exceeds ${MAX_INSTRUCTION_CHARS} chars`);
+        }
+    }
+}
+function validateRuntimePatch(runtime) {
+    if (typeof runtime !== "object" || runtime === null) {
+        throw new TypeError("manifest.runtime must be an object");
+    }
+    for (const [key, value] of Object.entries(runtime)) {
+        if (!RUNTIME_PATCH_KEYS.includes(key)) {
+            throw new RangeError(`runtime patch key not in the editable whitelist: ${key}`);
+        }
+        if (value !== undefined)
+            validateRuntimeValue(key, value);
+    }
+}
+/** 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
+ *  discardable candidate. */
+function validateRuntimeValue(key, value) {
+    const positiveInt = (v) => typeof v === "number" && Number.isInteger(v) && v > 0;
+    switch (key) {
+        case "maxTurns":
+        case "maxTotalTokens":
+        case "skillLeaseTurns":
+            if (!positiveInt(value))
+                throw new TypeError(`runtime.${key} must be a positive integer`);
+            return;
+        case "criteriaGate":
+            if (typeof value !== "boolean")
+                throw new TypeError("runtime.criteriaGate must be a boolean");
+            return;
+        case "knowledgeBudgetRatio":
+            if (typeof value !== "number" || !(value > 0 && value <= 1)) {
+                throw new TypeError("runtime.knowledgeBudgetRatio must be a number in (0, 1]");
+            }
+            return;
+        case "repeatFuse": {
+            if (value === false)
+                return;
+            if (typeof value !== "object" || value === null) {
+                throw new TypeError("runtime.repeatFuse must be false or { denyAfter?, terminateAfter? }");
+            }
+            const fuse = value;
+            for (const k of Object.keys(fuse)) {
+                if (k !== "denyAfter" && k !== "terminateAfter") {
+                    throw new RangeError(`runtime.repeatFuse has unknown key: ${k}`);
+                }
+                if (fuse[k] !== undefined && !positiveInt(fuse[k])) {
+                    throw new TypeError(`runtime.repeatFuse.${k} must be a positive integer`);
+                }
+            }
+            return;
+        }
+        case "entropyWatch": {
+            if (typeof value !== "object" || value === null) {
+                throw new TypeError("runtime.entropyWatch must be an object");
+            }
+            const watch = value;
+            for (const k of Object.keys(watch)) {
+                const v = watch[k];
+                if (v === undefined)
+                    continue;
+                if (k === "enabled" || k === "notifyModel") {
+                    if (typeof v !== "boolean")
+                        throw new TypeError(`runtime.entropyWatch.${k} must be a boolean`);
+                }
+                else if (k === "threshold" || k === "hysteresis") {
+                    if (typeof v !== "number" || !(v >= 0 && v <= 1)) {
+                        throw new TypeError(`runtime.entropyWatch.${k} must be a number in [0, 1]`);
+                    }
+                }
+                else if (k === "cooldownTurns") {
+                    if (!positiveInt(v))
+                        throw new TypeError("runtime.entropyWatch.cooldownTurns must be a positive integer");
+                }
+                else {
+                    throw new RangeError(`runtime.entropyWatch has unknown key: ${k}`);
+                }
+            }
+            return;
+        }
+        default:
+            throw new RangeError(`runtime patch key not in the editable whitelist: ${key}`);
+    }
+}
+/** Structural load check — throws on anything a manifest is forbidden to carry. */
+export function validateManifest(manifest) {
+    if (typeof manifest !== "object" || manifest === null)
+        throw new TypeError("manifest must be an object");
+    if (manifest.manifestVersion !== 1)
+        throw new TypeError("manifest.manifestVersion must be 1");
+    if (!(manifest.parent === null || typeof manifest.parent === "string")) {
+        throw new TypeError("manifest.parent must be a digest string or null");
+    }
+    if (!Array.isArray(manifest.editableSurfaces) || manifest.editableSurfaces.some(s => typeof s !== "string")) {
+        throw new TypeError("manifest.editableSurfaces must be a string[]");
+    }
+    if (manifest.instructions !== undefined)
+        validateInstructionProfile(manifest.instructions);
+    if (manifest.nudges !== undefined)
+        validateNudgeRules(manifest.nudges);
+    if (manifest.runtime !== undefined)
+        validateRuntimePatch(manifest.runtime);
+}
+// ── Apply ────────────────────────────────────────────────────────────────────
+/**
+ * Fold a validated manifest onto `base` runtime options. Instructions ride through as DATA — the
+ * runner composes the system prompt once at option normalization so `run_started` and the kernel's
+ * AddSystemMessage stay byte-identical. Runtime keys outside the whitelist throw.
+ */
+export function applyManifest(manifest, base) {
+    validateManifest(manifest);
+    const out = { ...base };
+    if (manifest.instructions !== undefined)
+        out.instructions = manifest.instructions;
+    if (manifest.nudges !== undefined)
+        out.nudges = manifest.nudges;
+    if (manifest.runtime !== undefined) {
+        for (const [key, value] of Object.entries(manifest.runtime)) {
+            if (value !== undefined)
+                out[key] = value;
+        }
+    }
+    return out;
+}
+function validatePatchShape(patch) {
+    if (typeof patch !== "object" || patch === null)
+        throw new TypeError("patch must be an object");
+    if (typeof patch.targetSurface !== "string" || patch.targetSurface.length === 0) {
+        throw new TypeError("patch.targetSurface must be a non-empty string");
+    }
+    if (patch.op !== "set" && patch.op !== "append" && patch.op !== "remove") {
+        throw new TypeError(`patch.op must be set|append|remove, got ${String(patch.op)}`);
+    }
+    for (const field of ["rationale", "targetCluster", "expectedEffect"]) {
+        if (typeof patch[field] !== "string" || patch[field].length === 0) {
+            throw new TypeError(`patch.${field} must be a non-empty string`);
+        }
+    }
+}
+function editInstructionSlot(manifest, slot, patch) {
+    if (slot === undefined || !INSTRUCTION_SLOTS.includes(slot)) {
+        throw new RangeError(`unknown instruction slot: ${patch.targetSurface}`);
+    }
+    if (patch.op === "append")
+        throw new RangeError("append applies only to nudges");
+    const key = slot;
+    if (patch.op === "remove") {
+        if (manifest.instructions)
+            delete manifest.instructions[key];
+        return;
+    }
+    if (typeof patch.value !== "string")
+        throw new TypeError(`instructions.${key} set requires a string value`);
+    if (patch.value.length > MAX_INSTRUCTION_CHARS) {
+        throw new RangeError(`instructions.${key} exceeds ${MAX_INSTRUCTION_CHARS} chars`);
+    }
+    manifest.instructions = { ...(manifest.instructions ?? {}), [key]: patch.value };
+}
+function editNudges(manifest, patch) {
+    const current = manifest.nudges ?? [];
+    if (patch.op === "set") {
+        const rules = patch.value;
+        validateNudgeRules(rules);
+        manifest.nudges = rules;
+        return;
+    }
+    if (patch.op === "append") {
+        const additions = Array.isArray(patch.value) ? patch.value : [patch.value];
+        const merged = [...current, ...additions];
+        validateNudgeRules(merged);
+        manifest.nudges = merged;
+        return;
+    }
+    // remove — by id
+    if (typeof patch.value !== "string")
+        throw new TypeError("nudges remove requires a rule id string");
+    manifest.nudges = current.filter(rule => rule.id !== patch.value);
+}
+function editRuntime(manifest, key, patch) {
+    if (key === undefined || !RUNTIME_PATCH_KEYS.includes(key)) {
+        throw new RangeError(`runtime patch key not in the editable whitelist: ${patch.targetSurface}`);
+    }
+    if (patch.op === "append")
+        throw new RangeError("append applies only to nudges");
+    const runtime = { ...(manifest.runtime ?? {}) };
+    if (patch.op === "remove")
+        delete runtime[key];
+    else {
+        validateRuntimeValue(key, patch.value);
+        runtime[key] = patch.value;
+    }
+    manifest.runtime = runtime;
+}
+function applySurfaceEdit(manifest, patch) {
+    const [head, sub] = patch.targetSurface.split(".");
+    if (head === "instructions")
+        return editInstructionSlot(manifest, sub, patch);
+    if (head === "nudges") {
+        if (sub !== undefined)
+            throw new RangeError(`nudges surface takes no sub-path: ${patch.targetSurface}`);
+        return editNudges(manifest, patch);
+    }
+    if (head === "runtime")
+        return editRuntime(manifest, sub, patch);
+    throw new RangeError(`unknown surface path: ${patch.targetSurface}`);
+}
+/**
+ * Apply one structural edit, returning a NEW manifest whose `parent` is the source's digest. Throws
+ * when the surface is off-whitelist, the patch is malformed, or the result violates a bound
+ * (instruction ≤4000 chars, nudge load rules). The source manifest is never mutated.
+ */
+export function applyPatch(manifest, patch) {
+    validatePatchShape(patch);
+    if (!manifest.editableSurfaces.includes(patch.targetSurface)) {
+        throw new RangeError(`surface not in the editable whitelist: ${patch.targetSurface}`);
+    }
+    const next = structuredClone(manifest);
+    applySurfaceEdit(next, patch);
+    next.parent = manifestDigest(manifest);
+    validateManifest(next);
+    return next;
+}

package/dist/harness/nudge.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Self-Harness H1.2 — 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
+ * self-harness loop can rewrite. `NudgeEngine` is a pure, clock-free class: `observe(event)` folds one
+ * session event into its per-rule state and returns the notes that fired, which the runner lowers to
+ * the `injectNote` signal channel. No I/O, no randomness — so the trigger matrix is exhaustively
+ * unit-testable and two engines never share state.
+ */
+import type { RuntimeSignalUrgency } from "../signals/types.js";
+import type { SessionEvent } from "../runtime/session-log.js";
+export type NudgeTrigger = {
+    kind: "tool_error";
+    errorKind?: string;
+    toolName?: string;
+} | {
+    kind: "tool_denied";
+    reasonIncludes?: string;
+} | {
+    kind: "tool_calls_at_least";
+    count: number;
+} | {
+    kind: "turns_at_least";
+    count: number;
+} | {
+    kind: "entropy_alert";
+};
+export interface NudgeRule {
+    id: string;
+    on: NudgeTrigger;
+    /** Template — supports {{tool_name}} {{error_kind}} {{turn}} only. */
+    note: string;
+    /** Default "normal" (the injectNote default). */
+    urgency?: RuntimeSignalUrgency;
+    /** Turns that must pass after a fire before the rule may fire again. Default 3. */
+    cooldownTurns?: number;
+    /** Total fires allowed for the whole run. Default 2. */
+    maxFires?: number;
+}
+/** Structural load check — throws on a malformed / oversized / duplicate-id rule set. */
+export declare function validateNudgeRules(rules: NudgeRule[]): void;
+export interface NudgeOutput {
+    note: string;
+    urgency: RuntimeSignalUrgency;
+}
+export declare class NudgeEngine {
+    private readonly rules;
+    private readonly state;
+    /** Cumulative tool_requested calls, for `tool_calls_at_least` edge detection. */
+    private toolCallsSeen;
+    /** Highest turn observed, for cooldown + `turns_at_least` edge detection. */
+    private currentTurn;
+    /** call_id → tool name, so a tool_completed error can name its tool (results carry no name). */
+    private readonly callNames;
+    constructor(rules: NudgeRule[]);
+    /** Fold one session event into rule state; return the notes that fired this event, in rule order. */
+    observe(event: SessionEvent): NudgeOutput[];
+    /** Returns the template context when the trigger matches this event, else null. */
+    private match;
+}

package/dist/harness/nudge.js

@@ -0,0 +1,176 @@
+const MAX_RULES = 16;
+const MAX_NOTE_CHARS = 2000;
+const DEFAULT_COOLDOWN_TURNS = 3;
+const DEFAULT_MAX_FIRES = 2;
+const ALLOWED_TEMPLATE_VARS = ["tool_name", "error_kind", "turn"];
+const URGENCIES = ["low", "normal", "high", "critical"];
+// ── Load validation ──────────────────────────────────────────────────────────
+function validateTrigger(on, id) {
+    if (typeof on !== "object" || on === null)
+        throw new TypeError(`nudge rule ${id}: trigger must be an object`);
+    switch (on.kind) {
+        case "tool_error":
+            if (on.errorKind !== undefined && typeof on.errorKind !== "string") {
+                throw new TypeError(`nudge rule ${id}: tool_error.errorKind must be a string`);
+            }
+            if (on.toolName !== undefined && typeof on.toolName !== "string") {
+                throw new TypeError(`nudge rule ${id}: tool_error.toolName must be a string`);
+            }
+            return;
+        case "tool_denied":
+            if (on.reasonIncludes !== undefined && typeof on.reasonIncludes !== "string") {
+                throw new TypeError(`nudge rule ${id}: tool_denied.reasonIncludes must be a string`);
+            }
+            return;
+        case "tool_calls_at_least":
+        case "turns_at_least":
+            if (!Number.isInteger(on.count) || on.count < 1) {
+                throw new RangeError(`nudge rule ${id}: ${on.kind}.count must be a positive integer`);
+            }
+            return;
+        case "entropy_alert":
+            return;
+        default:
+            throw new RangeError(`nudge rule ${id}: unknown trigger kind: ${on.kind}`);
+    }
+}
+function validateTemplateVars(note, id) {
+    const re = /\{\{([^{}]*)\}\}/g;
+    let match;
+    while ((match = re.exec(note)) !== null) {
+        if (!ALLOWED_TEMPLATE_VARS.includes(match[1])) {
+            throw new RangeError(`nudge rule ${id}: unsupported template variable {{${match[1]}}}`);
+        }
+    }
+}
+/** Structural load check — throws on a malformed / oversized / duplicate-id rule set. */
+export function validateNudgeRules(rules) {
+    if (!Array.isArray(rules))
+        throw new TypeError("nudges must be an array");
+    if (rules.length > MAX_RULES)
+        throw new RangeError(`at most ${MAX_RULES} nudge rules (got ${rules.length})`);
+    const ids = new Set();
+    for (const rule of rules) {
+        if (typeof rule !== "object" || rule === null)
+            throw new TypeError("each nudge rule must be an object");
+        if (typeof rule.id !== "string" || rule.id.length === 0) {
+            throw new TypeError("nudge rule id must be a non-empty string");
+        }
+        if (ids.has(rule.id))
+            throw new RangeError(`duplicate nudge rule id: ${rule.id}`);
+        ids.add(rule.id);
+        validateTrigger(rule.on, rule.id);
+        if (typeof rule.note !== "string" || rule.note.length === 0) {
+            throw new TypeError(`nudge rule ${rule.id}: note must be a non-empty string`);
+        }
+        if (rule.note.length > MAX_NOTE_CHARS) {
+            throw new RangeError(`nudge rule ${rule.id}: note exceeds ${MAX_NOTE_CHARS} chars`);
+        }
+        validateTemplateVars(rule.note, rule.id);
+        if (rule.cooldownTurns !== undefined && (!Number.isInteger(rule.cooldownTurns) || rule.cooldownTurns < 0)) {
+            throw new RangeError(`nudge rule ${rule.id}: cooldownTurns must be a non-negative integer`);
+        }
+        if (rule.maxFires !== undefined && (!Number.isInteger(rule.maxFires) || rule.maxFires < 1)) {
+            throw new RangeError(`nudge rule ${rule.id}: maxFires must be a positive integer`);
+        }
+        if (rule.urgency !== undefined && !URGENCIES.includes(rule.urgency)) {
+            throw new RangeError(`nudge rule ${rule.id}: invalid urgency ${rule.urgency}`);
+        }
+    }
+}
+function renderNote(template, ctx) {
+    return template
+        .replace(/\{\{tool_name\}\}/g, ctx.tool_name ?? "")
+        .replace(/\{\{error_kind\}\}/g, ctx.error_kind ?? "")
+        .replace(/\{\{turn\}\}/g, String(ctx.turn));
+}
+export class NudgeEngine {
+    rules;
+    state;
+    /** Cumulative tool_requested calls, for `tool_calls_at_least` edge detection. */
+    toolCallsSeen = 0;
+    /** Highest turn observed, for cooldown + `turns_at_least` edge detection. */
+    currentTurn = 0;
+    /** call_id → tool name, so a tool_completed error can name its tool (results carry no name). */
+    callNames = new Map();
+    constructor(rules) {
+        validateNudgeRules(rules);
+        // Defensive shallow copy: the caller can mutate its array afterwards without touching the engine.
+        this.rules = rules.map(rule => ({ ...rule }));
+        this.state = this.rules.map(() => ({ fires: 0, lastFireTurn: 0 }));
+    }
+    /** Fold one session event into rule state; return the notes that fired this event, in rule order. */
+    observe(event) {
+        const prevToolCalls = this.toolCallsSeen;
+        const prevTurn = this.currentTurn;
+        if (event.kind === "tool_requested") {
+            for (const call of event.calls)
+                this.callNames.set(call.id, call.name);
+            this.toolCallsSeen += event.calls.length;
+        }
+        if ("turn" in event && typeof event.turn === "number") {
+            this.currentTurn = Math.max(this.currentTurn, event.turn);
+        }
+        const out = [];
+        for (let i = 0; i < this.rules.length; i++) {
+            const rule = this.rules[i];
+            const matched = this.match(rule.on, event, prevToolCalls, prevTurn);
+            if (!matched)
+                continue;
+            const st = this.state[i];
+            if (st.fires >= (rule.maxFires ?? DEFAULT_MAX_FIRES))
+                continue;
+            if (st.fires > 0 && this.currentTurn - st.lastFireTurn < (rule.cooldownTurns ?? DEFAULT_COOLDOWN_TURNS))
+                continue;
+            st.fires += 1;
+            st.lastFireTurn = this.currentTurn;
+            out.push({ note: renderNote(rule.note, matched), urgency: rule.urgency ?? "normal" });
+        }
+        return out;
+    }
+    /** Returns the template context when the trigger matches this event, else null. */
+    match(on, event, prevToolCalls, prevTurn) {
+        switch (on.kind) {
+            case "tool_error": {
+                if (event.kind !== "tool_completed")
+                    return null;
+                for (const result of event.results) {
+                    if (!result.is_error)
+                        continue;
+                    if (on.errorKind !== undefined && result.error_kind !== on.errorKind)
+                        continue;
+                    const name = this.callNames.get(result.call_id);
+                    if (on.toolName !== undefined && name !== on.toolName)
+                        continue;
+                    return { tool_name: name ?? "", error_kind: result.error_kind ?? "", turn: event.turn };
+                }
+                return null;
+            }
+            case "tool_denied": {
+                if (event.kind !== "tool_denied")
+                    return null;
+                if (on.reasonIncludes !== undefined && !event.reason.includes(on.reasonIncludes))
+                    return null;
+                return { tool_name: event.tool_name, error_kind: "", turn: event.turn };
+            }
+            case "tool_calls_at_least": {
+                // Edge: the cumulative count crosses the threshold on THIS event (monotonic ⇒ fires once).
+                if (prevToolCalls < on.count && this.toolCallsSeen >= on.count) {
+                    return { turn: this.currentTurn };
+                }
+                return null;
+            }
+            case "turns_at_least": {
+                if (prevTurn < on.count && this.currentTurn >= on.count) {
+                    return { turn: this.currentTurn };
+                }
+                return null;
+            }
+            case "entropy_alert": {
+                if (event.kind !== "entropy_alert")
+                    return null;
+                return { turn: event.turn };
+            }
+        }
+    }
+}

package/dist/harness/public.d.ts

@@ -4,3 +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 { NudgeEngine, validateNudgeRules } from "./nudge.js";
+export type { NudgeTrigger, NudgeRule, NudgeOutput } from "./nudge.js";

package/dist/harness/public.js

@@ -2,3 +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
+// 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 { NudgeEngine, validateNudgeRules } from "./nudge.js";

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type { LoopSpec, LoopOutcome } from "./runtime/loop-driver.js";
 export type { RunAgentOptions, RunFanoutOptions } from "./runtime/facade.js";
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
 export type { RuntimeOptions, KernelReliabilityOptions, OperationCancellationReason, PromptBudget, SchedulerPolicy } from "./runtime/runner.js";
+export type { InstructionProfile, NudgeRule, NudgeTrigger } from "./harness/public.js";
 export type { SignalPolicy } from "./runtime/os-profile.js";
 export { readKernelDiagnostics, restoreKernelRuntime, snapshotKernelRuntime } from "./runtime/kernel-step.js";
 export type { KernelDiagnostics, KernelSnapshot } from "./runtime/kernel-step.js";

package/dist/runtime/runner.d.ts

@@ -16,6 +16,8 @@ import { type NativeOsProfile, type OsProfileId, type SignalPolicy } from "./os-
 import { LargeResultSpool } from "./large-result-spool.js";
 import type { BackgroundTaskErrorHandler } from "./reliability.js";
 import { type ContextPolicyOverridesV1 } from "./context-policy.js";
+import { type InstructionProfile } from "../harness/manifest.js";
+import { type NudgeRule } from "../harness/nudge.js";
 export interface SchedulerPolicy {
     version: 1;
     criticalPathWeight: number;
@@ -142,6 +144,16 @@ 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)
+     *  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
+     *  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;
     dreamStore?: DreamStore;
@@ -255,6 +267,13 @@ export interface RuntimeOptions {
      * concurrency stays vehicle-scoped (spec §2.5).
      */
     runGroup?: RunGroup;
+    /**
+     * Set by the SubAgentOrchestrator for host-derived child runs: the child still joins the
+     * `runGroup` (lineage) and settles its actual terminal usage into the group ledger, but reserves
+     * no budget axes — group admission governs peer vehicles only. The child's caps stay local
+     * (kernel `maxTotalTokens` policy + `resourceQuota`). Never set this for a top-level run.
+     */
+    nestedGroupVehicle?: boolean;
     /**
      * Optional long-term memory policy (`set_memory_policy`). Tunes the kernel's memory subsystem
      * (retrieval top-k, stale-warning age, write validation, memory path). Unset leaves the kernel
@@ -365,6 +384,11 @@ export declare class RuntimeRunner {
     private dashboard;
     /** Most recent kernel entropy sample of the active/last run (see `latestEntropy`). */
     private lastEntropySample;
+    /** H1.1: `systemPrompt` with the instruction slots composed in, computed ONCE so `run_started` and
+     *  the kernel AddSystemMessage take the identical string. */
+    private readonly composedSystemPrompt;
+    /** H1.2: present only when `opts.nudges` is non-empty; else null and the append funnel is untouched. */
+    private readonly nudgeEngine;
     constructor(opts: RuntimeOptions);
     /** Host configuration (for coordinator / sub-agent spawn). */
     get hostOptions(): RuntimeOptions;

package/dist/runtime/runner.js

@@ -19,6 +19,8 @@ import { LargeResultSpool } from "./large-result-spool.js";
 import { formatToolError } from "../tools/errors.js";
 import { ManagedTaskScope } from "./reliability.js";
 import { contextPolicyV1, normalizeContextPolicyV1, } from "./context-policy.js";
+import { composeSystemPrompt } from "../harness/manifest.js";
+import { NudgeEngine } from "../harness/nudge.js";
 export function schedulerPolicyToKernel(policy) {
     const allowed = new Set([
         "version", "criticalPathWeight", "fanoutWeight", "ageWeight", "tokenCostWeight",
@@ -97,12 +99,18 @@ export class RuntimeRunner {
     dashboard = null;
     /** Most recent kernel entropy sample of the active/last run (see `latestEntropy`). */
     lastEntropySample = null;
+    /** H1.1: `systemPrompt` with the instruction slots composed in, computed ONCE so `run_started` and
+     *  the kernel AddSystemMessage take the identical string. */
+    composedSystemPrompt;
+    /** H1.2: present only when `opts.nudges` is non-empty; else null and the append funnel is untouched. */
+    nudgeEngine;
     constructor(opts) {
         this.opts = opts;
         const schemaAttempts = opts.workflowSchemaValidationAttempts ?? 2;
         if (!Number.isInteger(schemaAttempts) || schemaAttempts < 1 || schemaAttempts > 16) {
             throw new RangeError("workflowSchemaValidationAttempts must be an integer between 1 and 16");
         }
+        this.composedSystemPrompt = composeSystemPrompt(opts.systemPrompt, opts.instructions);
         if (opts.enableDiagnosticsDashboard) {
             const originalAppend = opts.sessionLog.append.bind(opts.sessionLog);
             opts.sessionLog.append = async (sessionId, event) => {
@@ -114,6 +122,21 @@ export class RuntimeRunner {
                 return seq;
             };
         }
+        // H1.2: feed the nudge engine at the append funnel, stacking OVER any prior wrapping so the event
+        // is durably logged before a nudge observes it. Notes drain through the same `injectNote` channel
+        // as host `onToolResult` notes, surfacing in the NEXT provider request. Skipped entirely when no
+        // rules are configured, keeping the default event stream byte-identical.
+        this.nudgeEngine = opts.nudges?.length ? new NudgeEngine(opts.nudges) : null;
+        if (this.nudgeEngine) {
+            const priorAppend = opts.sessionLog.append.bind(opts.sessionLog);
+            opts.sessionLog.append = async (sessionId, event) => {
+                const seq = await priorAppend(sessionId, event);
+                for (const { note, urgency } of this.nudgeEngine.observe(event)) {
+                    this.injectNote(note, urgency);
+                }
+                return seq;
+            };
+        }
     }
     /** Host configuration (for coordinator / sub-agent spawn). */
     get hostOptions() {
@@ -559,6 +582,7 @@ export class RuntimeRunner {
             spec,
             manifest,
             sessionLog: this.opts.sessionLog,
+            toolAccess: spec.toolAccess,
             ...(this.opts.subAgentHarness ? { harness: this.opts.subAgentHarness } : {}),
         });
         await this.commitKernelApply(runtime, this.pendingObservations, {
@@ -1221,7 +1245,7 @@ export class RuntimeRunner {
                 goal: req.goal,
                 criteria: req.criteria ?? [],
                 agent_id: this.opts.agentId,
-                system_prompt: this.opts.systemPrompt,
+                system_prompt: this.composedSystemPrompt,
                 ...(attachments ? { attachments } : {}),
             });
         }
@@ -1423,11 +1447,11 @@ export class RuntimeRunner {
                 kind: "set_tools",
                 tools: this.opts.executionPlane.schemas().map(toolSchemaToKernel),
             });
-            if (this.opts.systemPrompt) {
+            if (this.composedSystemPrompt) {
                 await this.commitKernelApply(runtime, this.pendingObservations, {
                     kind: "add_system_message",
-                    content: this.opts.systemPrompt,
-                    tokens: Math.max(1, Math.ceil(this.opts.systemPrompt.length / 4)),
+                    content: this.composedSystemPrompt,
+                    tokens: Math.max(1, Math.ceil(this.composedSystemPrompt.length / 4)),
                 });
             }
             if (this.opts.initialMemory) {
@@ -1567,13 +1591,24 @@ export class RuntimeRunner {
                 startPayload.run_spec = agentRunSpecToKernel(spec);
             }
             // Reserve capacity before start_run. The kernel enforces only this vehicle's grant and reports
-            // exact terminal usage against the same opaque reservation identity.
+            // exact terminal usage against the same opaque reservation identity. A nested vehicle joins for
+            // lineage/settlement only: it reserves no budget axes (group admission governs peer vehicles),
+            // so the parent's held reservation cannot squeeze the child's grant to zero.
             if (this.opts.runGroup) {
                 const g = this.opts.runGroup;
-                groupBudgetScope = await GroupBudgetScope.open(g, { sessionId, role: this.opts.agentId, kind: "vehicle" }, this.groupBudgetRequest());
+                groupBudgetScope = await GroupBudgetScope.open(g, { sessionId, role: this.opts.agentId, kind: "vehicle" }, this.opts.nestedGroupVehicle ? { limits: {}, requested: {} } : this.groupBudgetRequest());
                 this.activeGroupBudgetScope = groupBudgetScope;
             }
-            await this.applyKernelPolicies(runtime, groupBudgetScope);
+            try {
+                await this.applyKernelPolicies(runtime, groupBudgetScope);
+            }
+            catch (err) {
+                // Admission failure (e.g. the kernel rejecting a zero-capacity grant): release the
+                // reservation so it cannot linger in the group ledger, then surface the error.
+                await groupBudgetScope?.release();
+                this.activeGroupBudgetScope = undefined;
+                throw err;
+            }
             // Multimodal upload: seed the user's attachments (images/audio) as a history
             // message before start_run pushes the "[TASK STATE]" anchor. init_task does not
             // clear history, so order becomes [attachment user msg, "Proceed…"] — both land

package/dist/runtime/sub-agent-orchestrator.js

@@ -89,6 +89,15 @@ export class SubAgentOrchestrator {
         const inherit = ctx.toolAccess === "inherit";
         const permitted = new Set(ctx.manifest.permitted_capability_ids ?? []);
         const metaTools = inherit ? availableMetaTools(ctx.parentOpts) : deriveMetaTools(permitted, ctx.parentOpts);
+        // A "filtered" spawn with no capability grants and no meta-tools resolves to a deny-all plane —
+        // the child model sees zero tools and reports "no tools available". Warn the host (visible, not
+        // fatal) with the fix, mirroring `maybeWarnFailureShapedChunk`'s tone. Exempt workflow nodes:
+        // `!inherit && workflow-node ⇒ quarantined ⇒ intentional deny-all, not a misconfiguration.
+        if (!inherit && !ctx.isWorkflowNode && permitted.size === 0 && metaTools.size === 0) {
+            console.warn(`[deepstrike] spawned sub-agent "${ctx.spec.identity.agentId}" resolved to zero tools ` +
+                `(deny-all filter). Mount tools as capabilities and grant via spec.capabilityFilter, or pass ` +
+                `spec.toolAccess:'inherit' to run on the parent's plane. If a tool-less child is intentional, ignore this.`);
+        }
         const basePlane = inherit
             ? ctx.parentOpts.executionPlane
             : new FilteredExecutionPlane(ctx.parentOpts.executionPlane, permitted, metaTools);
@@ -126,6 +135,10 @@ export class SubAgentOrchestrator {
             enablePlanTool: metaTools.has("update_plan") ? ctx.parentOpts.enablePlanTool : undefined,
             // M5 v2.1: a workflow node's `start_workflow` flattens to the parent kernel (no nested pivot).
             isWorkflowNode: ctx.isWorkflowNode,
+            // Nested vehicle: the child joins the inherited runGroup for lineage/settlement only — it
+            // must NOT re-reserve budget axes the parent already holds (that double-reserve squeezed the
+            // child's grant to 0 and the kernel stripped its first-turn tools).
+            nestedGroupVehicle: true,
             // The child runs under ITS OWN spec, never the parent's: the spread above would otherwise
             // leak the parent's `runSpec` (identity, capability filter — and a LoopDriver's armed
             // `loopRound`, giving every child a phantom pace tool). A loop-node iteration carries its

package/dist/types/agent.d.ts

@@ -52,6 +52,13 @@ export interface AgentRunSpec {
     /** O3: per-child wall-clock cap in milliseconds (sets the child runner's `timeoutMs`; falls back to
      *  the parent's). A hung child terminates `timeout` instead of stalling the parent indefinitely. */
     maxWallMs?: number;
+    /** Tool surface for a spawned sub-agent. Host-side only (like `modelHint`) — NOT sent to the kernel
+     *  (`agentRunSpecToKernel` maps fields explicitly and omits it). Default `"filtered"` keeps the spawn
+     *  path's deny-all-safe default: the child is filtered to its manifest grants, and a grant-less spawn
+     *  resolves to zero tools. `"inherit"` runs the child on the parent's execution plane with the
+     *  parent's meta-tool availability (same mechanism trusted workflow nodes use) — the child's surface
+     *  is a subset of the parent's, never a privilege escalation. */
+    toolAccess?: "inherit" | "filtered";
 }
 /** Kernel process-table observation (Phase 3 canonical spawn signal). */
 export interface AgentProcessChangedObservation {

package/package.json

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