@sema-ai/core 1.275.1

package/dist/core/auto-promote.d.ts

@@ -0,0 +1,126 @@
+import type { OracleIsolationVerdict } from "./oracle-isolation.js";
+import type { SkillManifest } from "./types.js";
+/**
+ * The terminal of {@link decideAutoPromote}.
+ * - `"auto_promote"` — the ONLY exit that skips human review. Reachable only when all four prior guards
+ *   (tripwire / irreversible / statistics / concurrence) clear AND all four gates are present+passing.
+ * - `"candidate_only"` — surface the artifact as a candidate; the SOLE shortfall is the oracle isolation class
+ *   being downgraded to `in_process_probe_only` (oracle-isolation.ts:34) with everything else passing.
+ * - `"needs_human"` — fail-closed default: escalate to a human (any guard tripped, any other gate failing).
+ */
+export type AutoPromoteTerminal = "auto_promote" | "candidate_only" | "needs_human";
+/**
+ * Gate-2 + Gate-3 lineage-bound handle (裁决净增③ / P0#3 / P1 lineage-bind). `gate2Verdict` and `manifest`
+ * MUST come from the SAME atomic `appendPromotable` write (memory.ts:295) — this struct bundles them into one
+ * handle so the decision can never pair a verdict with a divergent manifest ("assume two booleans are
+ * co-sourced" is the bug this prevents). `lineageId` keys the active-skill-scope frame (active-skill-scope.ts).
+ */
+export interface PromotedRecord {
+    /** Stable lineage id of the promoted artifact; the Gate-3 scope key. */
+    lineageId: string;
+    /**
+     * Gate-2 chokepoint result: the promotable write landed WITH a positive utility verdict (memory.ts:240),
+     * or it was absent/ungated. Only `"present_positive"` is gate-passing; `"absent_or_ungated"` ⇒ needs_human.
+     */
+    gate2Verdict: "present_positive" | "absent_or_ungated";
+    /** Gate-3 capability manifest — co-located with `gate2Verdict` in the same store record, never diverging. */
+    manifest: SkillManifest;
+    /**
+     * Gate-3 scope is armed AND has propagated across the subagent boundary (design/79 §4, design/77 §3/§7).
+     * `true` ONLY when either (a) the manifest lists NO subagent-spawn tool, or (b) its scope has propagated to
+     * spawned children. The skill→subagent manifest-scope propagation just landed in this branch (commit
+     * `04f5104`); for an artifact that lists a subagent-spawn tool whose scope has NOT propagated, this is
+     * `false` → the decision falls to `needs_human` (裁决净增⑤ / P1). A bare in-process `gate4Armed`-style
+     * boolean is intentionally NOT enough here: the propagation hole is encoded structurally into this flag.
+     */
+    gate3Scoped: boolean;
+}
+/**
+ * Inputs to {@link decideAutoPromote}. Every field is a PRESENCE/boolean/set the profile has already computed —
+ * the core fold inspects no numeric threshold, no stats shape, no taxonomy. The caller (a profile-promotion job)
+ * has already RE-asserted Gate-1 (`assertOracleIsolation`), run the exec-gate, read the appended Gate-2 verdict,
+ * and armed the Gate-4 seam BEFORE building this struct; this function only READS those outputs.
+ */
+export interface AutoPromoteInputs {
+    /** Gate-1 verdict (oracle-isolation.ts:37); the caller re-asserted it before calling this function. */
+    oracle: OracleIsolationVerdict;
+    /** Gate-2 + Gate-3 lineage-bound single handle (净增③). */
+    record: PromotedRecord;
+    /** Gate-4: the irreversibility tighten is in place (or the artifact touches no irreversible tool). */
+    gate4Armed: boolean;
+    /**
+     * §6 permanent human door (净增①): the artifact touches at least one irreversible TYPED tool. When true the
+     * decision is ALWAYS `needs_human`, even if everything else would pass — because G4 is pure in-process
+     * gate-PRESENCE (2-of-3 asymmetry) and `gate4Armed` alone ("the gate is wired") is not trustworthy for an
+     * irreversible action.
+     */
+    touchesIrreversibleTool: boolean;
+    /**
+     * The profile's statistics RAN for this run (it produced a verdict). Core requires PRESENCE only — the
+     * statistical THRESHOLDS (train/val/test split, canary, min-samples, cost-per-truly-correct) are profile.
+     */
+    statisticsPresent: boolean;
+    /**
+     * The KIND labels of the independent mechanical signals that concur. Core enforces `size >= 2` DISTINCT
+     * kinds (净增②) — feeding the SAME kind twice still yields size 1 (it's a Set keyed by kind). WHICH kinds
+     * count, and whether they are truly de-correlated, are profile concerns (§7 honest residual).
+     */
+    concurringSignals: ReadonlySet<string>;
+    /** Tripwire result — ESCALATE-ONLY (§5 ③); when `escalate` it always wins and is never cleared. */
+    tripwire: TripwireResult;
+}
+/**
+ * The fail-closed PRESENCE AND-chain (design/79 §1 §2). Any missing/failing gate ⇒ NEVER `auto_promote`; it
+ * degrades to `needs_human` (or, for the single oracle-isolation-class shortfall, `candidate_only`). This
+ * function computes NO numeric threshold — only PRESENCE/boolean/set-size checks.
+ *
+ * **Guard order (load-bearing):**
+ *  1. `tripwire.escalate` → needs_human (tripwire always wins, never clears — §5 ③)
+ *  2. `touchesIrreversibleTool` → needs_human (§6 permanent human door — 净增①; even if all else passes)
+ *  3. `!statisticsPresent` → needs_human (statistics must have RAN — core-required; thresholds are profile)
+ *  4. `concurringSignals.size < 2` → needs_human (≥2 DISTINCT KIND mechanical signals concur — 净增②)
+ *  5. the four-gate present-passing check; if not all pass, the SOLE-shortfall arm:
+ *     `in_process_probe_only` oracle (and every other gate passing) → `candidate_only`; otherwise needs_human.
+ *  6. all four gates present+passing (with guards clear) → `auto_promote` (the only auto exit).
+ */
+export declare function decideAutoPromote(i: AutoPromoteInputs): AutoPromoteTerminal;
+/**
+ * The result of {@link deriveTripwire}: an ESCALATE-ONLY advisory. `escalate` can only ever be set to `true`
+ * by a scan; a clean scan contributes nothing and NEVER clears another scan's escalation. `reasons` carries
+ * the matched tokens / drifted symbols for observability.
+ */
+export interface TripwireResult {
+    escalate: boolean;
+    reasons: string[];
+}
+/**
+ * The CORE-FROZEN denylist floor (design/79 §3 净增④ / P0#4): a safety invariant the profile MAY NOT remove.
+ * `deriveTripwire`'s `profileTokens` may only UNION (add) to this — never subtract — resolving the tension
+ * between "the token set can rot (new exfil primitives appear)" and "constitution-minimal". These are RAW-BYTE
+ * substrings scanned against the artifact's raw bytes INCLUDING its markdown bytes (extractSymbols skips
+ * markdown, so the byte scan is what covers prose/fenced-code that names an egress/exec primitive).
+ */
+export declare const FROZEN_DENYLIST_FLOOR: ReadonlySet<string>;
+/**
+ * Build a tripwire verdict over a promoted artifact's text. **ESCALATE-ONLY** (design/79 §3,守 design/76
+ * §5.1 r3): it can ONLY ever raise `escalate:true`; a clean artifact yields `{escalate:false, reasons:[]}` and
+ * NEVER clears anything — the REAL containment is Gate-3 runtime deny-narrowing (exhaustive at call time), not
+ * this advisory. Two mechanical scans, both escalate-only:
+ *
+ *  1. **symbol-mention drift** via {@link extractSymbols} (repo-map.ts). extractSymbols is a v1 heuristic:
+ *     column-0 / source-only, it skips indented lines and is structurally INCAPABLE of being a containment
+ *     proof (it can't enumerate everything the artifact can call). So it is used ONLY to ESCALATE — if a
+ *     surfaced top-level symbol names a tool/capability that is NOT in `declared.allowTools`, escalate.
+ *  2. **raw-byte denylist** over the artifact's RAW bytes INCLUDING markdown bytes — {@link FROZEN_DENYLIST_FLOOR}
+ *     UNIONed with `profileTokens` (add-only). A substring hit → escalate, with the matched token in `reasons`.
+ *
+ * **Fail-closed:** if EITHER scan THROWS on real content, return `{escalate:true, ...}` — a scan failure must
+ * NOT silently become "no escalation". (This is disjoint from the composition-layer "tripwire DOWN ⇒ zero
+ * contribution, never block" case, which is the caller's concern, not a throw inside the scan.)
+ *
+ * @param artifactText the artifact's raw text (markdown body included).
+ * @param declared the artifact's declared manifest — its `allowTools` is the symbol-drift baseline.
+ * @param profileTokens optional ADD-ONLY extra denylist tokens (UNIONed onto the frozen floor; cannot remove).
+ */
+export declare function deriveTripwire(artifactText: string, declared: SkillManifest, profileTokens?: ReadonlySet<string>): TripwireResult;
+//# sourceMappingURL=auto-promote.d.ts.map

package/dist/core/auto-promote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-promote.d.ts","sourceRoot":"","sources":["../../src/core/auto-promote.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,YAAY,EAAE,kBAAkB,GAAG,mBAAmB,CAAC;IACvD,6GAA6G;IAC7G,QAAQ,EAAE,aAAa,CAAC;IACxB;;;;;;;OAOG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,uGAAuG;IACvG,MAAM,EAAE,sBAAsB,CAAC;IAC/B,yDAAyD;IACzD,MAAM,EAAE,cAAc,CAAC;IACvB,sGAAsG;IACtG,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,uBAAuB,EAAE,OAAO,CAAC;IACjC;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,mGAAmG;IACnG,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,CAuB3E;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAuCpD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,aAAa,EACvB,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC,cAAc,CAwChB"}

package/dist/core/auto-promote.js

@@ -0,0 +1,171 @@
+// design/79 — auto-promote 决策 core 合成（mandate-OFF inert，裁决合成版）.
+//
+// This file is the WHOLE core surface of the "§5 决策核": one pure data-in/data-out fold
+// ({@link decideAutoPromote}) over the four already-built gates' verdicts plus statistics/concurrence/tripwire
+// signals, and the two ESCALATE-ONLY mechanical scans ({@link deriveTripwire}). It is a thin composition
+// (repair-loop.ts:18 posture) — it RE-RUNS no gate, computes NO numeric threshold, and owns NO orchestration.
+//
+// 🔴 **mandate-OFF (design/79 §6):** this ships INERT. **Nothing in the Runner or any production path calls
+// `decideAutoPromote` / `deriveTripwire`** — the profile-promotion job that would call them does not exist
+// yet. The `auto_promote` exit is therefore unreachable in shipped code. mandate-OFF is structural-by-absence:
+// there is no `RunnerDeps.autoPromoteEnabled` flag (constitution-minimal); the absence of a caller IS the off
+// switch, and an architecture test (test/auto-promote-decision.test.ts) asserts zero `src/` production callers.
+//
+// **Unifying safety principle (design/76 §0, design/79 §5):** ①core enforces gate-PRESENCE fail-closed
+// (a missing/un-wired gate NEVER auto-passes) ②profile owns every threshold/taxonomy (core checks PRESENCE —
+// `statisticsPresent`, `size>=2 distinct` — never a numeric threshold) ③tripwire is escalate-only, it can only
+// ever set `escalate:true` and NEVER clears ④real protection is the out-of-process structural boundary
+// (G1/G2/G3); probes (the in-process write-probe, the tripwire scans) are necessary-not-sufficient. The G4
+// irreversibility axis is pure in-process gate-PRESENCE (the 2-of-3 asymmetry, §6) → any artifact that touches
+// an irreversible tool is a PERMANENT human door regardless of `gate4Armed`.
+import { extractSymbols } from "../tools/fs/repo-map.js";
+/**
+ * The fail-closed PRESENCE AND-chain (design/79 §1 §2). Any missing/failing gate ⇒ NEVER `auto_promote`; it
+ * degrades to `needs_human` (or, for the single oracle-isolation-class shortfall, `candidate_only`). This
+ * function computes NO numeric threshold — only PRESENCE/boolean/set-size checks.
+ *
+ * **Guard order (load-bearing):**
+ *  1. `tripwire.escalate` → needs_human (tripwire always wins, never clears — §5 ③)
+ *  2. `touchesIrreversibleTool` → needs_human (§6 permanent human door — 净增①; even if all else passes)
+ *  3. `!statisticsPresent` → needs_human (statistics must have RAN — core-required; thresholds are profile)
+ *  4. `concurringSignals.size < 2` → needs_human (≥2 DISTINCT KIND mechanical signals concur — 净增②)
+ *  5. the four-gate present-passing check; if not all pass, the SOLE-shortfall arm:
+ *     `in_process_probe_only` oracle (and every other gate passing) → `candidate_only`; otherwise needs_human.
+ *  6. all four gates present+passing (with guards clear) → `auto_promote` (the only auto exit).
+ */
+export function decideAutoPromote(i) {
+    // FAIL-CLOSED PRESENCE AND-chain. Any missing/failed gate ⇒ never auto; degrade to human/candidate.
+    if (i.tripwire.escalate)
+        return "needs_human"; // tripwire always wins, never clears (§5 ③)
+    if (i.touchesIrreversibleTool)
+        return "needs_human"; // §6 permanent human door; 2-of-3 asymmetry (净增①)
+    if (!i.statisticsPresent)
+        return "needs_human"; // statistics must have RAN (core-required; threshold=profile)
+    if (i.concurringSignals.size < 2)
+        return "needs_human"; // ≥2 DISTINCT KIND mechanical signals concur (净增②)
+    const g1ok = i.oracle.protected && i.oracle.isolationClass === "out_of_process"; // in_process_probe_only caps candidate
+    const g2ok = i.record.gate2Verdict === "present_positive";
+    const allGatesPresentPassing = g1ok && g2ok && i.record.gate3Scoped && i.gate4Armed;
+    if (!allGatesPresentPassing) {
+        // candidate_only ONLY when the oracle probe PASSED (`protected:true`) but the isolation CLASS is merely
+        // downgraded to in_process_probe_only (a BENIGN structural shortfall — grader ran out-of-VM-but-in-process),
+        // with every OTHER gate passing. A FAILED probe (`protected:false` — e.g. the worker can WRITE the oracle
+        // dir, or identity/sandbox collision) is a real Gate-1 FAILURE and must escalate → needs_human (fail-closed).
+        // 🔴 Without the explicit `i.oracle.protected`, a `{protected:false, in_process_probe_only}` verdict — the
+        // single worst case G1 exists to catch — would slip to candidate_only (adversarial round MAJOR, design/79).
+        return (i.oracle.protected && i.oracle.isolationClass === "in_process_probe_only"
+            && g2ok && i.record.gate3Scoped && i.gate4Armed)
+            ? "candidate_only"
+            : "needs_human";
+    }
+    return "auto_promote";
+}
+/**
+ * The CORE-FROZEN denylist floor (design/79 §3 净增④ / P0#4): a safety invariant the profile MAY NOT remove.
+ * `deriveTripwire`'s `profileTokens` may only UNION (add) to this — never subtract — resolving the tension
+ * between "the token set can rot (new exfil primitives appear)" and "constitution-minimal". These are RAW-BYTE
+ * substrings scanned against the artifact's raw bytes INCLUDING its markdown bytes (extractSymbols skips
+ * markdown, so the byte scan is what covers prose/fenced-code that names an egress/exec primitive).
+ */
+export const FROZEN_DENYLIST_FLOOR = new Set([
+    // shell / process / exec primitives
+    "child_process",
+    "execSync",
+    "spawnSync",
+    "exec(",
+    "spawn(",
+    "shell",
+    "/bin/sh",
+    "/bin/bash",
+    "bash -c",
+    "sh -c",
+    // dynamic-code execution
+    "eval(",
+    "Function(",
+    "require(",
+    "import(",
+    // fetch / egress primitives
+    "fetch(",
+    "curl",
+    "wget",
+    "http://",
+    "https://",
+    "nc ",
+    "netcat",
+    // encode/obfuscate primitives commonly used to smuggle payloads
+    "base64",
+    "atob(",
+    "btoa(",
+    "fromCharCode",
+    // shell metacharacters (each scanned as a raw byte)
+    "|",
+    "&&",
+    ";",
+    "`",
+    "$(",
+    ">>",
+    ">",
+    "<",
+]);
+/**
+ * Build a tripwire verdict over a promoted artifact's text. **ESCALATE-ONLY** (design/79 §3,守 design/76
+ * §5.1 r3): it can ONLY ever raise `escalate:true`; a clean artifact yields `{escalate:false, reasons:[]}` and
+ * NEVER clears anything — the REAL containment is Gate-3 runtime deny-narrowing (exhaustive at call time), not
+ * this advisory. Two mechanical scans, both escalate-only:
+ *
+ *  1. **symbol-mention drift** via {@link extractSymbols} (repo-map.ts). extractSymbols is a v1 heuristic:
+ *     column-0 / source-only, it skips indented lines and is structurally INCAPABLE of being a containment
+ *     proof (it can't enumerate everything the artifact can call). So it is used ONLY to ESCALATE — if a
+ *     surfaced top-level symbol names a tool/capability that is NOT in `declared.allowTools`, escalate.
+ *  2. **raw-byte denylist** over the artifact's RAW bytes INCLUDING markdown bytes — {@link FROZEN_DENYLIST_FLOOR}
+ *     UNIONed with `profileTokens` (add-only). A substring hit → escalate, with the matched token in `reasons`.
+ *
+ * **Fail-closed:** if EITHER scan THROWS on real content, return `{escalate:true, ...}` — a scan failure must
+ * NOT silently become "no escalation". (This is disjoint from the composition-layer "tripwire DOWN ⇒ zero
+ * contribution, never block" case, which is the caller's concern, not a throw inside the scan.)
+ *
+ * @param artifactText the artifact's raw text (markdown body included).
+ * @param declared the artifact's declared manifest — its `allowTools` is the symbol-drift baseline.
+ * @param profileTokens optional ADD-ONLY extra denylist tokens (UNIONed onto the frozen floor; cannot remove).
+ */
+export function deriveTripwire(artifactText, declared, profileTokens) {
+    const reasons = [];
+    let escalate = false;
+    // ── Scan 1: symbol-mention drift (escalate-only). A clean scan contributes nothing.
+    try {
+        const allow = new Set(declared.allowTools ?? []);
+        const symbols = extractSymbols(artifactText);
+        for (const sym of symbols) {
+            if (!allow.has(sym)) {
+                escalate = true;
+                reasons.push(`symbol-drift: surfaced symbol "${sym}" not in declared.allowTools`);
+            }
+        }
+    }
+    catch (e) {
+        // Fail-closed: a scan that THROWS on real content must escalate, never silently pass.
+        return {
+            escalate: true,
+            reasons: [...reasons, `symbol-drift scan threw (fail-closed): ${String(e?.message ?? e)}`],
+        };
+    }
+    // ── Scan 2: raw-byte denylist over the RAW bytes (markdown included). Frozen floor ∪ profile add-ons.
+    try {
+        // The profile may only UNION onto the frozen floor — never remove a floor token (净增④ / P0#4).
+        const tokens = new Set([...FROZEN_DENYLIST_FLOOR, ...(profileTokens ?? [])]);
+        for (const token of tokens) {
+            if (token.length > 0 && artifactText.includes(token)) {
+                escalate = true;
+                reasons.push(`denylist: raw-byte token "${token}" present in artifact`);
+            }
+        }
+    }
+    catch (e) {
+        return {
+            escalate: true,
+            reasons: [...reasons, `denylist scan threw (fail-closed): ${String(e?.message ?? e)}`],
+        };
+    }
+    return { escalate, reasons };
+}
+//# sourceMappingURL=auto-promote.js.map

package/dist/core/auto-promote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-promote.js","sourceRoot":"","sources":["../../src/core/auto-promote.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,sFAAsF;AACtF,+GAA+G;AAC/G,yGAAyG;AACzG,8GAA8G;AAC9G,EAAE;AACF,4GAA4G;AAC5G,2GAA2G;AAC3G,+GAA+G;AAC/G,8GAA8G;AAC9G,gHAAgH;AAChH,EAAE;AACF,uGAAuG;AACvG,6GAA6G;AAC7G,+GAA+G;AAC/G,uGAAuG;AACvG,2GAA2G;AAC3G,+GAA+G;AAC/G,6EAA6E;AAI7E,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA0EzD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAoB;IACpD,oGAAoG;IACpG,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ;QAAE,OAAO,aAAa,CAAC,CAAC,4CAA4C;IAC3F,IAAI,CAAC,CAAC,uBAAuB;QAAE,OAAO,aAAa,CAAC,CAAC,kDAAkD;IACvG,IAAI,CAAC,CAAC,CAAC,iBAAiB;QAAE,OAAO,aAAa,CAAC,CAAC,8DAA8D;IAC9G,IAAI,CAAC,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC;QAAE,OAAO,aAAa,CAAC,CAAC,mDAAmD;IAE3G,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,cAAc,KAAK,gBAAgB,CAAC,CAAC,uCAAuC;IACxH,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,YAAY,KAAK,kBAAkB,CAAC;IAC1D,MAAM,sBAAsB,GAAG,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,UAAU,CAAC;IACpF,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC5B,wGAAwG;QACxG,6GAA6G;QAC7G,0GAA0G;QAC1G,8GAA8G;QAC9G,2GAA2G;QAC3G,4GAA4G;QAC5G,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,cAAc,KAAK,uBAAuB;eACtE,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,UAAU,CAAC;YACtD,CAAC,CAAC,gBAAgB;YAClB,CAAC,CAAC,aAAa,CAAC;IACpB,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB,IAAI,GAAG,CAAS;IACxE,oCAAoC;IACpC,eAAe;IACf,UAAU;IACV,WAAW;IACX,OAAO;IACP,QAAQ;IACR,OAAO;IACP,SAAS;IACT,WAAW;IACX,SAAS;IACT,OAAO;IACP,yBAAyB;IACzB,OAAO;IACP,WAAW;IACX,UAAU;IACV,SAAS;IACT,4BAA4B;IAC5B,QAAQ;IACR,MAAM;IACN,MAAM;IACN,SAAS;IACT,UAAU;IACV,KAAK;IACL,QAAQ;IACR,gEAAgE;IAChE,QAAQ;IACR,OAAO;IACP,OAAO;IACP,cAAc;IACd,oDAAoD;IACpD,GAAG;IACH,IAAI;IACJ,GAAG;IACH,GAAG;IACH,IAAI;IACJ,IAAI;IACJ,GAAG;IACH,GAAG;CACJ,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,QAAuB,EACvB,aAAmC;IAEnC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,qFAAqF;IACrF,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,QAAQ,GAAG,IAAI,CAAC;gBAChB,OAAO,CAAC,IAAI,CAAC,kCAAkC,GAAG,8BAA8B,CAAC,CAAC;YACpF,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,sFAAsF;QACtF,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,0CAA0C,MAAM,CAAE,CAAW,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC;SACtG,CAAC;IACJ,CAAC;IAED,uGAAuG;IACvG,IAAI,CAAC;QACH,8FAA8F;QAC9F,MAAM,MAAM,GAAG,IAAI,GAAG,CAAS,CAAC,GAAG,qBAAqB,EAAE,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACrF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrD,QAAQ,GAAG,IAAI,CAAC;gBAChB,OAAO,CAAC,IAAI,CAAC,6BAA6B,KAAK,uBAAuB,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,sCAAsC,MAAM,CAAE,CAAW,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC;SAClG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC"}

package/dist/core/background-shell.d.ts

@@ -0,0 +1,128 @@
+/**
+ * design/103 — 后台 shell seam(detached process)。「手」腿(`ExecutionEnv`)的 long-running 进程能力:启动一个不会
+ * 立刻退出的命令、轮询它的输出、需要时杀掉它。让引擎能跑真实开发循环(起 dev server / build watcher → 轮询日志 →
+ * 迭代),用于自足 make-real。
+ *
+ * 这是一个 **env 上的可选能力**(非一种独立 env 类型),所以不 `extends ExecutionEnv` —— 用交叉类型挂到具体实现上,并经
+ * {@link hasBackgroundShell} 运行时检测(对齐 remote-env.ts 的 `hasDestroy`/`isRemoteExecutionEnv` 模式,零 vendor 接口改动)。
+ *
+ * 设计裁定(经 codex + workflow 5-lens 双轨对抗复审收敛,design/103 v2):
+ * - **不跨 durable suspend**:后台进程在每条退出路径被 dispose;Runner 必须在 suspendVM **之前** 调
+ *   {@link BackgroundShellCapability.disposeBackgroundShells}(detached job 不在 suspendVM 的 in-flight 契约射程内)。
+ * - **越权隔离**:`pollBackground`/`killBackground` 的 shellId MUST 被校验为本 env 自己 spawn 过的;非本 env 走 `not_found`。
+ * - **按-id-可重读**:实现 MUST 保证按 shellId 跨多次独立调用可重复读取累积/增量输出(execStream 的 consume-once 不满足)。
+ */
+import type { ExecutionEnv, ExecutionEnvExecOptions, Result } from "../internal/harness.js";
+/**
+ * 一个 long-running / detached 进程的句柄。**env-local、非 durable、对调用方不透明** —— adapter 内部把它映射到真实进程/
+ * provider job,**绝不**把可猜的 raw provider job id 暴露成 shellId(否则跨租户可枚举,design/103 §3.8 越权红线)。
+ */
+export type BackgroundShellId = string & {
+    readonly __brand: "BackgroundShellId";
+};
+/** 一个后台进程的生命周期状态。`exited` 携带 exitCode;`failed` = 启动后异常终止(非被 kill)。 */
+export type BackgroundShellStatus = "running" | "exited" | "killed" | "failed";
+/**
+ * 类型化错误码(对齐 `RemoteExecutionErrorCode` 风格)。`timeout`/`io` 覆盖 TOB 下的有界 liveness/传输失败 —— 接口规定
+ * 方法 MUST NOT throw(返回 {@link Result}),所以挂掉的 provider RPC 必须有码可表达、而非违约抛异常。
+ */
+export type BackgroundShellErrorCode = "unsupported" | "not_found" | "spawn_failed" | "limit_exceeded" | "timeout" | "io";
+/** 后台 shell 操作的类型化错误。`code` 给程序分类,`message` 给模型自纠(design/103 错误文案纪律)。 */
+export declare class BackgroundShellError extends Error {
+    readonly code: BackgroundShellErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: BackgroundShellErrorCode, message: string, cause?: unknown | undefined);
+}
+/**
+ * `spawnBackground` 的 options。后台进程只用 `cwd`/`env`/`timeout`;流式回调(`onStdout`/`onStderr`)和 `abortSignal`
+ * 都对「启动后轮询」语义无意义(输出进 tail buffer 等 poll;后台进程的生命周期由 kill/timeout/dispose 管,不绑启动它
+ * 的工具调用的 signal),故显式 `Omit` 以免实现者误以为传 abortSignal 能约束进程。`timeout` 在后台是**硬墙**
+ * (到点自杀 → status `killed`,design/103 §3.6)。
+ */
+export type BackgroundSpawnOptions = Omit<ExecutionEnvExecOptions, "onStdout" | "onStderr" | "abortSignal">;
+/** 一次 {@link BackgroundShellCapability.pollBackground} 的返回:自上次 poll 以来的增量 + 当前状态 + cursor 元数据。 */
+export interface BackgroundPoll {
+    /** 自上次 poll 后的新增 stdout(已应用 `filter`,且 filter 先于截断 —— design/103 §3.4)。 */
+    stdout: string;
+    /** 自上次 poll 后的新增 stderr。 */
+    stderr: string;
+    /** 当前生命周期状态。 */
+    status: BackgroundShellStatus;
+    /** `status==="exited"` 时的退出码。 */
+    exitCode?: number;
+    /**
+     * 本 cursor 之前有字节因 **8MB tail buffer 的 head-evict 永久丢失**(配合 {@link bytesDroppedBeforeCursor})。
+     * 🔴 注意:这是**不可恢复**的丢失,不是「可再 poll 拉取」——进程产出超过 8MB tail 时最早段被挤掉。(单次 poll 增量
+     * 超 per-poll 显示上限的 head+tail 截断发生在**工具层**,那是另一回事,由工具的截断 marker 诚实标注。)
+     */
+    truncated?: boolean;
+    /** 从进程启动至今的总输出字节(cursor 元数据,供模型判断是否错过早期日志)。 */
+    bytesFromStart?: number;
+    /** 因 8MB tail buffer head-evict 在本 cursor 之前**永久丢失**的字节数(诚实标注,不谎称「全部」)。 */
+    bytesDroppedBeforeCursor?: number;
+}
+/**
+ * 「手」腿的后台进程能力。一个具体 `ExecutionEnv` 实现可选地附加它(交叉类型),经 {@link hasBackgroundShell} 检测。
+ * 不支持的 env(StubExecutionEnv / SSH / ADB)= 不实现(或 `supported:false`),三个后台工具自动不挂(INERT)。
+ */
+export interface BackgroundShellCapability {
+    /** 显式声明能力(像 `RemoteExecutionEnv.capabilities` 一样不猜)。per-env / per-adapter。 */
+    readonly backgroundCapabilities: {
+        /** 是否真支持后台 spawn;`false` → 三工具不挂(design/103 §3.8)。 */
+        readonly supported: boolean;
+        /** 单 env 同时存活的后台进程上限(防 fork bomb;超限 spawn 返回 `limit_exceeded`)。 */
+        readonly maxConcurrent: number;
+        /** 后台默认 timeout(秒)。**per-端下沉**(E2B 沙箱寿命 ≠ TOC 宿主),非单一 core 常量。 */
+        readonly defaultBgTimeoutSec: number;
+        /** 后台 timeout **硬上限**(秒)。fail-closed 到有限值 —— **绝不允许无界**(design/103 §3.6)。 */
+        readonly maxBgTimeoutSec: number;
+        /** design/116 detach(飞轮 [C]):env 是否支持把前台 exec 的运行中子进程「领养」为后台(exec options 的
+         *  `detachSignal`)。缺省/false ⇒ detach 请求被忽略(exec 继续前台跑完)。 */
+        readonly supportsDetach?: boolean;
+        /** design/128 T1-1 留驻声明(TB 2026-07-08 翻红回归修):env 声明后台进程 **outlive the run** ——
+         *  一切**自动**收割路径(runner 每退出路径的 `disposeBackgroundShells`、registry 的 run-teardown settle
+         *  清扫、session release 的 reap)MUST 跳过 kill,把进程留作孤儿(宿主退出后由部署收尸,e.g. TB 容器)。
+         *  **显式** TaskStop/KillShell 与 per-shell timeout 硬墙不受影响(host 在世期间照常工作)。
+         *  实现侧 `disposeBackgroundShells` 自守 no-op 只护住了 dispose 一条路径;registry 直调 `killBackground`
+         *  的清扫(settleKilledForOwner)在 1.257.3 绕穿了它把 TB 留驻服务全数击杀 —— 声明上浮到能力面,让每个
+         *  自动收割调用方都看得见。缺省 false = 常规回收行为。 */
+        readonly retainBackgroundProcesses?: boolean;
+    };
+    /**
+     * 启动一条命令为后台进程,不等退出,返回 env-local 不透明句柄。MUST NOT block on 进程退出。`timeout` 是硬墙(到点自杀)。
+     * 后台子进程的 env MUST 经与前台 `exec` **完全相同**的 secret-scrub(design/103 §3.1 红线),cwd 默认 = 追踪的逻辑 cwd。
+     */
+    spawnBackground(command: string, options?: BackgroundSpawnOptions): Promise<Result<{
+        shellId: BackgroundShellId;
+    }, BackgroundShellError>>;
+    /**
+     * 读一个后台进程**自上次 poll 以来的新增**输出 + 当前状态(cursor 语义)。退出后仍可读残余 + exitCode,直到被 dispose/reap。
+     *
+     * 🔴 越权契约:`shellId` MUST 被校验为**本 env 自己 spawnBackground 返回过**的;非本 env 一律 `not_found`,绝不解析外部 job id。
+     * 🔴 重读契约:实现 MUST 保证「按 shellId 跨多次独立调用可重复读取累积/增量」(remote 的 execStream consume-once 不满足 —— 见 design/103 §5.2 两条路径)。
+     */
+    pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
+    /** 杀一个后台进程(幂等:杀已死的是 no-op,返回 ok)。`shellId` 同 {@link pollBackground} 的越权校验。 */
+    killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
+    /**
+     * 杀掉并清理**本 env 的所有**后台进程。Runner 在每条退出路径调:finish/abort/throw 在 run-loop tail finally,**suspend/
+     * review 必须在 `suspendVM` 之前**(design/103 §3.7;detached job 不在 suspendVM in-flight 契约内,不能指望 adapter 隐式处理)。
+     * Best-effort,MUST NOT throw(像 `cleanup`/`destroy`)。幂等。
+     *
+     * 飞轮 [492]② `except`(可选):这些 shellId **留活**(session 驻留 persistent Monitor 的进程 —— 它的全部意义
+     * 就是跨 turn 存活;run-end 全灭会留下「registry handle 活着、进程死了」的孤儿 watch)。不认识此参数的旧
+     * 实现照旧全灭 = 今天的行为(诚实降级,not silent corruption:watcher 会打出 env-death 终态通知)。
+     * suspend/review 前的 dispose **不带** except(挂起整个 VM,进程死亡是既有契约)。
+     */
+    disposeBackgroundShells(opts?: {
+        except?: readonly BackgroundShellId[];
+    }): Promise<void>;
+}
+/**
+ * 结构 + 语义检测:`env` 是否暴露后台 shell 能力且声明 `supported:true`。挂载门控用此(对齐 `hasDestroy`)。
+ *
+ * 单谓词足够:remote-env 刻意拆 `isRemoteExecutionEnv`(结构)/`isSuspendable`(语义)是因为 isolation/suspendable 两轴
+ * 彼此独立;这里 `supported` 是唯一语义轴,合进一个谓词不会丢信息。
+ */
+export declare function hasBackgroundShell(env: ExecutionEnv): env is ExecutionEnv & BackgroundShellCapability;
+//# sourceMappingURL=background-shell.d.ts.map

package/dist/core/background-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-shell.d.ts","sourceRoot":"","sources":["../../src/core/background-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAE5F;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAEnF,sEAAsE;AACtE,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAChC,aAAa,GACb,WAAW,GACX,cAAc,GACd,gBAAgB,GAChB,SAAS,GACT,IAAI,CAAC;AAET,yEAAyE;AACzE,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,IAAI,EAAE,wBAAwB;IAEvC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,wBAAwB,EACvC,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,uBAAuB,EAAE,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC,CAAC;AAE5G,kGAAkG;AAClG,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,sBAAsB,EAAE;QAC/B,sDAAsD;QACtD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,mEAAmE;QACnE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,kEAAkE;QAClE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,6EAA6E;QAC7E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC;oEAC4D;QAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAClC;;;;;;6CAMqC;QACrC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;KAC9C,CAAC;IAEF;;;OAGG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,iBAAiB,CAAA;KAAE,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAElG,8EAA8E;IAC9E,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAExF;;;;;;;;;OASG;IACH,uBAAuB,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,GAAG,IAAI,YAAY,GAAG,yBAAyB,CAWrG"}

package/dist/core/background-shell.js

@@ -0,0 +1,42 @@
+/**
+ * design/103 — 后台 shell seam(detached process)。「手」腿(`ExecutionEnv`)的 long-running 进程能力:启动一个不会
+ * 立刻退出的命令、轮询它的输出、需要时杀掉它。让引擎能跑真实开发循环(起 dev server / build watcher → 轮询日志 →
+ * 迭代),用于自足 make-real。
+ *
+ * 这是一个 **env 上的可选能力**(非一种独立 env 类型),所以不 `extends ExecutionEnv` —— 用交叉类型挂到具体实现上,并经
+ * {@link hasBackgroundShell} 运行时检测(对齐 remote-env.ts 的 `hasDestroy`/`isRemoteExecutionEnv` 模式,零 vendor 接口改动)。
+ *
+ * 设计裁定(经 codex + workflow 5-lens 双轨对抗复审收敛,design/103 v2):
+ * - **不跨 durable suspend**:后台进程在每条退出路径被 dispose;Runner 必须在 suspendVM **之前** 调
+ *   {@link BackgroundShellCapability.disposeBackgroundShells}(detached job 不在 suspendVM 的 in-flight 契约射程内)。
+ * - **越权隔离**:`pollBackground`/`killBackground` 的 shellId MUST 被校验为本 env 自己 spawn 过的;非本 env 走 `not_found`。
+ * - **按-id-可重读**:实现 MUST 保证按 shellId 跨多次独立调用可重复读取累积/增量输出(execStream 的 consume-once 不满足)。
+ */
+/** 后台 shell 操作的类型化错误。`code` 给程序分类,`message` 给模型自纠(design/103 错误文案纪律)。 */
+export class BackgroundShellError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = "BackgroundShellError";
+    }
+}
+/**
+ * 结构 + 语义检测:`env` 是否暴露后台 shell 能力且声明 `supported:true`。挂载门控用此(对齐 `hasDestroy`)。
+ *
+ * 单谓词足够:remote-env 刻意拆 `isRemoteExecutionEnv`(结构)/`isSuspendable`(语义)是因为 isolation/suspendable 两轴
+ * 彼此独立;这里 `supported` 是唯一语义轴,合进一个谓词不会丢信息。
+ */
+export function hasBackgroundShell(env) {
+    const e = env;
+    return (typeof e.spawnBackground === "function" &&
+        typeof e.pollBackground === "function" &&
+        typeof e.killBackground === "function" &&
+        typeof e.disposeBackgroundShells === "function" &&
+        typeof e.backgroundCapabilities === "object" &&
+        e.backgroundCapabilities !== null &&
+        e.backgroundCapabilities.supported === true);
+}
+//# sourceMappingURL=background-shell.js.map

package/dist/core/background-shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-shell.js","sourceRoot":"","sources":["../../src/core/background-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyBH,yEAAyE;AACzE,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAElC;IAEA;IAHX,YACW,IAA8B,EACvC,OAAe,EACN,KAAe;QAExB,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,SAAI,GAAJ,IAAI,CAA0B;QAE9B,UAAK,GAAL,KAAK,CAAU;QAGxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AA6FD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAiB;IAClD,MAAM,CAAC,GAAG,GAAyC,CAAC;IACpD,OAAO,CACL,OAAO,CAAC,CAAC,eAAe,KAAK,UAAU;QACvC,OAAO,CAAC,CAAC,cAAc,KAAK,UAAU;QACtC,OAAO,CAAC,CAAC,cAAc,KAAK,UAAU;QACtC,OAAO,CAAC,CAAC,uBAAuB,KAAK,UAAU;QAC/C,OAAO,CAAC,CAAC,sBAAsB,KAAK,QAAQ;QAC5C,CAAC,CAAC,sBAAsB,KAAK,IAAI;QACjC,CAAC,CAAC,sBAAsB,CAAC,SAAS,KAAK,IAAI,CAC5C,CAAC;AACJ,CAAC"}

package/dist/core/cache-break-detector.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Two-phase prefix-cache-break detector (design/31). Each turn it records a structural fingerprint of
+ * the prefix (system prompt / per-tool schema / tool set / model namespace) and compares the turn's
+ * `cacheRead` against the prior warm turn; on a confirmed drop it attributes the break to a root cause
+ * (model switch / a specific tool's drift / tool-set change / system-prefix change / server-or-TTL).
+ *
+ * The strict superset of the task-end "low hit-rate" heuristic: it pinpoints the BREAK TURN and names
+ * the cause, instead of only reporting an aggregate at the end. Provider-agnostic — the only provider
+ * input is `cacheRead` (OpenAI `cached_tokens` / Anthropic `cache_read_input_tokens`, already normalized).
+ *
+ * v1 is task-scoped (compares turns within one run; system/tools are stable so the high-value per-tool
+ * attribution mostly fires on a model switch or across runs). A per-session v2 would feed a persisted
+ * prior snapshot — the `observe` contract is already shaped for that.
+ */
+export interface CacheBreakFinding {
+    turn: number;
+    cacheReadBefore: number;
+    cacheReadAfter: number;
+    cause: "model-switch" | "tool-schema" | "tool-set" | "system-prefix" | "server-or-ttl";
+    detail: string;
+}
+export interface ToolFingerprintInput {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+/**
+ * Project a tool list into the structural inputs the detector fingerprints. Shared by the initial
+ * snapshot in `prepareTask` AND the per-materialization refresh in tool-disclosure (design/36): both
+ * MUST derive the fingerprint the same way, or a deferred tool going placeholder→full schema would
+ * be hashed inconsistently. Keep this the single source of "what counts as the cacheable tool prefix".
+ */
+export declare function toolsToFingerprintInputs(tools: ReadonlyArray<{
+    name: string;
+    description: string;
+    parameters: unknown;
+}>): ToolFingerprintInput[];
+export declare class CacheBreakDetector {
+    private prev;
+    /**
+     * Reset the baseline. **Call ONLY after a SUCCESSFUL compaction** (design/31 red line #11): a legit
+     * prefix shrink isn't a break, but resetting when compaction did NOT happen opens a false-negative
+     * window (a real break right after would be missed).
+     */
+    notifyCompaction(): void;
+    /**
+     * Record this turn's fingerprint + compare cacheRead to the prior warm turn. Returns a finding on a
+     * confirmed break. Hashes are computed here per call **by design**, taking the raw prefix rather than
+     * pre-computed hashes. NOTE (design/36): the inputs are NOT necessarily stable within a run — deferred
+     * tools materialize placeholder→full schema mid-task, so the caller refreshes the fingerprint at
+     * materialization (via `toolsToFingerprintInputs`). A resulting `tool-schema`/`tool-set` finding on
+     * that turn is EXPECTED and truthful (the cacheable prefix genuinely changed); the bug this guards
+     * against is the opposite — a frozen fingerprint hiding that change (a false negative).
+     */
+    observe(input: {
+        turn: number;
+        systemPrompt: string;
+        tools: ToolFingerprintInput[];
+        modelKey: string;
+        cacheRead: number;
+    }): CacheBreakFinding | undefined;
+}
+//# sourceMappingURL=cache-break-detector.d.ts.map

package/dist/core/cache-break-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-break-detector.d.ts","sourceRoot":"","sources":["../../src/core/cache-break-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,eAAe,GAAG,eAAe,CAAC;IACvF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,GAC/E,oBAAoB,EAAE,CAExB;AA0CD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAuB;IAEnC;;;;OAIG;IACH,gBAAgB,IAAI,IAAI;IAIxB;;;;;;;;OAQG;IACH,OAAO,CAAC,KAAK,EAAE;QACb,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,oBAAoB,EAAE,CAAC;QAC9B,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,iBAAiB,GAAG,SAAS;CAmDlC"}

package/dist/core/cache-break-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-break-detector.js","sourceRoot":"","sources":["../../src/core/cache-break-detector.ts"],"names":[],"mappings":"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"}

package/dist/core/canonical-json.d.ts

@@ -0,0 +1,45 @@
+/**
+ * design/80 D-1 §2 (slice 1a.2) — the engine-only **vetted canonical serializer** used to mint a stable,
+ * opaque {@link boundInputHashOf | boundInputHash} over a pending tool call's arguments.
+ *
+ * ## Why a bespoke serializer (and why engine-ONLY)
+ * The package's only runtime deps are typebox + the MCP SDK — there is no canonical/stable JSON serializer,
+ * and `JSON.stringify` is **not** canonical (object key order is insertion order, `-0`/`NaN`/`Infinity` are
+ * mishandled, and it offers no type-tagging). The red-team r3 ruling (design/80 §7) is the load-bearing
+ * constraint: **never let two runtimes each compute a canonical form and compare** — a `JSON.stringify`
+ * divergence (or a serializer-version drift across a worker upgrade) would produce a false mismatch and
+ * fail-closed a *legitimate* approval. So the boundInputHash is **server-minted opaque**: the engine computes
+ * it ONCE at suspend-mint with THIS serializer, persists it on the checkpoint, and a resume verifies by
+ * **opaque string equality** against the persisted value (it never re-serializes the resume-side args). This
+ * serializer therefore only needs to be *internally deterministic* (same value → same bytes within one
+ * runtime); it is deliberately NOT exported from the package index, so no cross-wire consumer (the SDK /
+ * service) can be tempted to recompute it — they treat the hash as opaque and echo it verbatim.
+ *
+ * ## Canonical form
+ * A total function (never throws) that emits a **type-tagged, length-prefixed** string so distinct values of
+ * distinct types can never collide (`number 1` ≠ `string "1"` ≠ `boolean`, and `{"a":"b"}` ≠ `{"ab":""}`):
+ *  - `null` → `N`, `undefined` → `U` (encoded distinctly — `{a:undefined}` must not collide with `{}`)
+ *  - boolean → `b1` / `b0`
+ *  - number → `n:<canonical>`; finite via `String(x)` (shortest round-trippable, deterministic per value);
+ *    `-0` normalized to `0`; `NaN`/`±Infinity` get explicit distinct tokens (never collapsed to `null`)
+ *  - bigint → `i:<value>`
+ *  - string → `s<byteLen>:<raw>` — **length-prefixed, NOT normalized**: equal inputs map to equal output and
+ *    distinct inputs (e.g. a non-NFC string vs its NFC form) map to distinct output. The serializer never
+ *    silently Unicode-normalizes (that would let two different argument payloads share one hash).
+ *  - array → `a<len>:[<el>…]` — order preserved (semantic)
+ *  - object → `o<count>:{<keyLen>:<key>=<val>…}` — **own enumerable keys sorted** by UTF-16 code unit, so
+ *    `{a,b}` and `{b,a}` canonicalize identically. (Duplicate keys cannot exist on a live JS object —
+ *    last-wins already happened at parse/construction — so they need no special handling here.)
+ *  - function / symbol → tagged tokens (`fn` / `y:<desc>`) so the serializer stays total; these never appear
+ *    in design/37 post-hook tool args (which are JSON values), but encoding rather than throwing keeps a
+ *    weird arg from silently degrading a durable suspend to a non-durable fallback.
+ */
+export declare function canonicalize(value: unknown): string;
+/**
+ * design/80 D-1 §2 — the server-minted **opaque** boundInputHash: a SHA-256 (hex) over {@link canonicalize}.
+ * Bound at suspend-mint to the pending tool call's input (`pendingAction.args`) and persisted on the
+ * checkpoint; a resume verifies the echoed value by string equality (never re-hashing the resume-side args).
+ * The hex digest is fixed-length and opaque — exactly what the operator sees / the D-G signer signs.
+ */
+export declare function boundInputHashOf(value: unknown): string;
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/core/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../../src/core/canonical-json.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUnD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEvD"}