@sema-agent/core 5.20.0 → 5.21.1

package/dist/core/auto-compaction.js

@@ -33,10 +33,24 @@ function summarizationCharsCapacity(model) {
 }
 export const STALE_ANCHOR_STRUCTURAL_MARGIN = 2;
 export function sanitizeCompactionSettings(settings, contextWindow) {
+    const wide = settings;
+    const reserveInvalid = !Number.isFinite(wide.reserveTokens);
+    const keepRecentInvalid = !Number.isFinite(wide.keepRecentTokens);
+    const clampToleranceInvalid = wide.clampTolerance !== undefined && !Number.isFinite(wide.clampTolerance);
+    const summaryBudgetInvalid = wide.summaryOutputBudgetTokens !== undefined && !Number.isFinite(wide.summaryOutputBudgetTokens);
+    const base = reserveInvalid || keepRecentInvalid || clampToleranceInvalid || summaryBudgetInvalid
+        ? {
+            ...settings,
+            ...(reserveInvalid ? { reserveTokens: DEFAULT_COMPACTION_SETTINGS.reserveTokens } : {}),
+            ...(keepRecentInvalid ? { keepRecentTokens: DEFAULT_COMPACTION_SETTINGS.keepRecentTokens } : {}),
+            ...(clampToleranceInvalid ? { clampTolerance: DEFAULT_CLAMP_TOLERANCE } : {}),
+            ...(summaryBudgetInvalid ? { summaryOutputBudgetTokens: undefined } : {}),
+        }
+        : settings;
     if (!contextWindow || !Number.isFinite(contextWindow) || contextWindow <= 0) {
-        return settings;
+        return base;
     }
-    let reserveTokens = settings.reserveTokens;
+    let reserveTokens = base.reserveTokens;
     if (contextWindow - reserveTokens <= 0) {
         reserveTokens = Math.ceil(contextWindow * FALLBACK_RESERVE_FRACTION);
     }
@@ -45,14 +59,14 @@ export function sanitizeCompactionSettings(settings, contextWindow) {
         reserveTokens = contextWindow - editAt;
     }
     const threshold = contextWindow - reserveTokens;
-    let keepRecentTokens = settings.keepRecentTokens;
+    let keepRecentTokens = base.keepRecentTokens;
     if (keepRecentTokens >= threshold) {
         keepRecentTokens = Math.max(1, Math.floor(threshold / 2));
     }
-    if (reserveTokens === settings.reserveTokens && keepRecentTokens === settings.keepRecentTokens) {
-        return settings;
+    if (reserveTokens === base.reserveTokens && keepRecentTokens === base.keepRecentTokens) {
+        return base;
     }
-    return { ...settings, reserveTokens, keepRecentTokens };
+    return { ...base, reserveTokens, keepRecentTokens };
 }
 export async function maybeCompact(opts) {
     const compactStartAt = Date.now();

package/dist/core/auto-mode-prompt-assets.d.ts

@@ -1,2 +1,10 @@
+/** The auto-mode classifier SYSTEM prompt shell (CC 2.1.207 `auto_mode_system_prompt`). Contains two
+ *  assembly placeholders consumed by `buildAutoModePrompt`: `<permissions_template>` (replaced by the
+ *  permissions document) and `<cross_session_messages_rule>` (replaced with "" — the 206/207 default). */
 export declare const AUTO_MODE_BASE_PROMPT: string;
+/** The external permissions document (CC 2.1.207 `permissions_external`). Four PAIRED placeholder
+ *  tags wrap the DEFAULT rule sets (environment / hard deny / soft deny / allow) and one UNPAIRED tag
+ *  (`<settings_deny_rules>`) marks the settings-plane deny injection point — all consumed by
+ *  `buildAutoModePrompt` with the CC-exact merge semantics (user rules REPLACE the defaults; the
+ *  `"$defaults"` sentinel splices the default set back in at its position). */
 export declare const AUTO_MODE_PERMISSIONS_EXTERNAL: string;

package/dist/core/auto-mode-prompt.d.ts

@@ -1,6 +1,11 @@
 import type { AutoModeClassifyInput } from "./auto-mode.js";
 import type { Message } from "../internal/llm.js";
+/** The sentinel a deployment puts INSIDE a rule list to splice the CC default rules back in at that
+ *  position (CC `XYt = "$defaults"`). Without it, a non-empty user list REPLACES the default section. */
 export declare const AUTO_MODE_DEFAULTS_SENTINEL = "$defaults";
+/** Deployment-authored rule overrides for the four paired sections of the permissions document.
+ *  Each entry is ONE rule (rendered as a `- ` bullet); omit a field (or pass an empty array) to keep
+ *  the CC default rules for that section verbatim. */
 export interface AutoModeRules {
     allow?: readonly string[];
     softDeny?: readonly string[];
@@ -9,13 +14,35 @@ export interface AutoModeRules {
 }
 export interface BuildAutoModePromptOptions {
     rules?: AutoModeRules;
+    /** Settings-plane deny rules (tool[/argument-pattern] strings) — rendered into the
+     *  `<settings_deny_rules>` slot as the CC circumvention-catching paragraph. */
     settingsDenyRules?: readonly string[];
+    /** Extra session-context facts (e.g. the CC user-identity line) — appended as a
+     *  `## Session Context` bullet block after the assembled document. */
     sessionContext?: readonly string[];
 }
+/**
+ * Assemble the classifier SYSTEM prompt (CC `KRg`, content-equivalent single string — CC splits the
+ * session-context tail into a second uncached block purely as a prompt-cache optimization).
+ * Every `.replace` uses the CALLBACK form: the assets and user rules are full of `$`-patterns
+ * (`$USER/...`) that a string replacement would corrupt via `$&`/`$'` substitution (CC does the same).
+ */
 export declare function buildAutoModePrompt(options?: BuildAutoModePromptOptions): string;
 export interface AutoModeWindowOptions {
+    /** Newest transcript entries included (default 40). */
     maxEntries?: number;
+    /** Per-entry excerpt cap in characters (default 2_000 — tool results and long turns are truncated
+     *  head-first with a `[… N chars truncated]` marker; the classifier weighs shape over bulk). */
     maxCharsPerEntry?: number;
 }
+/**
+ * Render the transcript window half of the classifier's user prompt: the newest `maxEntries` messages,
+ * oldest→newest, each labeled by lane. Plain data — see the module header for the declared v1 gap vs
+ * CC's entry-formatter stack.
+ */
 export declare function renderAutoModeWindow(messages: readonly Message[], options?: AutoModeWindowOptions): string;
+/**
+ * Render the pending action (the classify subject). The 207 process's step 1 keys on "the last tool
+ * call in the transcript" — this block IS that entry for our assembly, placed last in the user prompt.
+ */
 export declare function renderAutoModeAction(input: AutoModeClassifyInput): string;

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

@@ -1,34 +1,85 @@
 import type { ToolCallRequest } from "./tool-policy.js";
+/** The classifier's verdict over one pending `ask`. */
 export type AutoModeVerdict = {
     kind: "allow";
-} | {
+}
+/** `category` is the matched BLOCK rule name (207 output contract); `reason` starts with `[Rule Name]`. */
+ | {
     kind: "block";
     category: string;
     reason: string;
-} | {
+}
+/** The classifier could not run: model error/timeout, or the session breaker is open. NOT a decision. */
+ | {
     kind: "unavailable";
     cause: "error" | "timeout" | "breaker_open";
-} | {
+}
+/** The model responded but not in the `<block>…` contract shape. NOT a decision. */
+ | {
     kind: "parse_error";
     raw: string;
 };
+/**
+ * Parse the 207 classifier output contract:
+ *   blocked: `<block>yes</block><category>Rule Name</category><reason>[Rule Name] …</reason>`
+ *   allowed: `<block>no</block>`
+ * The contract says the ENTIRE response must begin with `<block>` — we strip `<thinking>` blocks
+ * first (CC-anchored: the 206 body's `dJi` removes closed thinking blocks AND a dangling unclosed
+ * tail before its own block-scan — a reasoning model's scratch space is not part of the verdict),
+ * then tolerate leading whitespace (models routinely emit a leading newline) but nothing else: any
+ * other preamble is a `parse_error` (fail-closed; 207 vocabulary: `automode-parsing-error`).
+ *
+ * Declared STRICTER than the CC parser (`iJi`: first `<block>` ANYWHERE in the response, closing tag
+ * optional): a free-scan lets a prompt-injected preamble seed the verdict; our contract-anchored
+ * parse costs only a fallback to the original human chain on the mismatch, never a silent allow.
+ *
+ * Strictness is polarity-asymmetric (codex review, confirmed HIGH):
+ *   - an ALLOW must be UNAMBIGUOUS: `<block>no</block>` followed by anything but whitespace —
+ *     a second conflicting `<block>yes</block>`, trailing prose, any tail at all — violates the
+ *     contract and maps to `parse_error` (the ask flows the original human chain, never a silent
+ *     allow on a malformed response);
+ *   - a stated BLOCK tolerates a tail (that is where `<category>`/`<reason>` live, and extra
+ *     content after a block verdict can only ever be judged in the blocking direction) — a
+ *     `<block>yes</block>` with MISSING/empty `<category>`/`<reason>` still maps to `block`
+ *     (with "" placeholders): the block intent is unambiguous, and downgrading a stated block
+ *     to parse_error (⇒ the ask may later auto-deny OR a human may approve) would weaken the
+ *     classifier's explicit verdict on the exact calls it flagged.
+ */
 export declare function parseAutoModeResponse(text: string): AutoModeVerdict;
+/** What the decider hands the deployment's `classify` hook (the assembled prompt is the hook's job
+ *  when it owns assembly; when using {@link buildAutoModePrompt} the decider passes its output). */
 export interface AutoModeClassifyInput {
+    /** The pending tool call — FINAL post-hook/post-rewrite args (the same args the gate adjudicated). */
     req: ToolCallRequest;
+    /** The human-readable text of the ask being decided (policy/safety message), when present. */
     askMessage?: string;
 }
+/** The pluggable model leg: given the classify input, return the model's raw text response.
+ *  Deployment-injected (roster cheap tier per [672]③); MAY throw / reject — the decider fail-closes. */
 export type AutoModeClassifyFn = (input: AutoModeClassifyInput, signal?: AbortSignal) => Promise<string>;
 export interface AutoModeDeciderOptions {
     classify: AutoModeClassifyFn;
+    /** Hard cap on one classification round-trip. Default 15_000 ms (sema 裁量 — CC's constant is not
+     *  established; a permission gate must not stall the whole run on a slow classifier). */
     timeoutMs?: number;
+    /** Consecutive-failure threshold that opens the session breaker (default 3, [672]② "连续 N 失败").
+     *  Failures = unavailable(error|timeout) + parse_error. A successful round (allow/block) resets it. */
     failureThreshold?: number;
+    /** Fired ONCE when the breaker opens ([672]②: "本 session 退回非 auto + 一次性告警"). */
     onBreakerOpen?: (info: {
         consecutiveFailures: number;
         lastCause: string;
     }) => void;
 }
 export interface AutoModeDecider {
+    /** Never rejects. Any internal failure surfaces as `unavailable`/`parse_error` (fail-closed). */
     decide(input: AutoModeClassifyInput, signal?: AbortSignal): Promise<AutoModeVerdict>;
+    /** True once the session breaker has opened (it never half-opens: [672]② is a SESSION fallback
+     *  to non-auto, not a retry window — a flapping classifier must not oscillate the permission mode). */
     breakerOpen(): boolean;
 }
+/**
+ * Session-scoped decider: timeout + fail-closed error mapping + a one-way circuit breaker.
+ * One instance per run/session — the breaker state is the session's "退回非 auto" latch.
+ */
 export declare function createAutoModeDecider(opts: AutoModeDeciderOptions): AutoModeDecider;

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

@@ -1,25 +1,125 @@
 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;