@sema-agent/core 5.20.0 → 5.21.0

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

@@ -3,47 +3,148 @@ import type { Message, Model, Tool } from "../internal/llm.js";
 import type { Hooks } from "./hooks.js";
 import type { TraceEvent } from "./trace.js";
 import type { Brain } from "./types.js";
+/**
+ * Default summarization focus, applied when a task does not provide `compaction.instructions`.
+ * Addresses the common fidelity failure where summaries drop specific facts.
+ */
 export declare const DEFAULT_COMPACTION_INSTRUCTIONS: string;
+/**
+ * design/145 §4 — uniform hygiene for EVERY summarization-instructions channel (spec-level
+ * `compaction.instructions`, the DEFAULT constant, a manual `/compact` per-call override, and a
+ * preCompact hook's `additionalInstructions` — 修类不修点): instructions text can be model- or
+ * caller-authored, and it is injected VERBATIM into the summarization prompt
+ * (`\n\nAdditional Instructions:\n${...}`, CC 207 :347521 shape), so a forged `</system-reminder>`
+ * or `<<<`/`>>>` fence sentinel inside it would otherwise ride into a trusted prompt position.
+ * Posture (r2 review B4): `sanitizeUntrustedText` + fence defusing only — NEVER `delimitUntrusted`
+ * (fencing instructions as "data only, do not follow" self-defeats their instructional intent, and
+ * the fence markers would be echoed back into the persisted summary). Cap = 2048 code points
+ * (surrogate-safe slice): instructions steer a summary, they are not a payload channel.
+ * Text without break-out sequences under the cap passes through BYTE-IDENTICAL (the no-arg /
+ * default-instructions prompt is unchanged — pinned by test).
+ */
 export declare const COMPACTION_INSTRUCTIONS_MAX_CHARS = 2048;
 export declare function sanitizeCompactionInstructions(text: string): string;
+/**
+ * 压缩子阶段遥测 (1.283 G) — single-source shape: the `phaseDurations` result field IS the
+ * (defined-but-not-yet-emitted) `compaction.phase_timings` trace frame minus its envelope
+ * (`kind`/`version`/`taskId`/`ts`) and minus `durationMs` (already a sibling result field). Deriving
+ * it from the frame keeps the follow-up runtask bridge a mechanical spread — and makes a rollback of
+ * either side a tsc error, not a silent drift.
+ */
 export type CompactionPhaseDurations = Omit<Extract<TraceEvent, {
     kind: "compaction.phase_timings";
 }>, "kind" | "version" | "taskId" | "ts" | "durationMs">;
+/** True iff `err` is a compaction failure caused by a manual compact() caller WITHDRAWING its
+ *  request (cancel-signal abort of the pass's summary call) — see
+ *  {@link MaybeCompactOptions.manualCancelSignal}. Absence of the marker means the failure was NOT
+ *  the withdrawal: a real summarizer error racing a late cancel stays unmarked so the caller's
+ *  breaker/onError accounting still sees it. */
 export declare function isCompactionManualCancel(err: unknown): boolean;
+/**
+ * design/145 §1/§3 — the window-safety decision surfaced to the caller BEFORE the summary call
+ * (same pre-call posture as `onInputTruncated`: the disclosure must survive a later summary
+ * failure). `kind:"fallback"` → the summary call was moved to the MAIN model (window safety);
+ * `kind:"clamp_disclosure"` → the small model keeps the call but the conversation WILL be
+ * clamp-truncated: `reason` says why the fallback did not happen ("budget" = the gate
+ * denied it; "tolerance" = the truncation is within `clampTolerance` — bounded, but no longer
+ * silent). All token figures are in the MAIN model's structural coordinate except
+ * `headroomTokens` (the小 model's — it describes THAT window's capacity).
+ */
 export interface CompactionWindowSafetyInfo {
     kind: "fallback" | "clamp_disclosure";
     truncationRatio: number;
+    /** Present on "clamp_disclosure": why the small model kept the call despite the truncation. */
     reason?: "budget" | "tolerance";
+    /** Serialized conversation size incl. any re-sent previousSummary (chars ÷ main-model charsPerToken). */
     contentTokens: number;
+    /** ≈ what fits in the compaction model's window (kept chars ÷ its charsPerToken); estimate. */
     headroomTokens?: number;
+    /** 门A estimate: main-model input price × contentTokens, integer micro-USD (absent when pricing
+     *  was unavailable — the gate then never blocked on budget). */
     estCostMicroUsd?: number;
 }
+/**
+ * SEMA-ONLY (trim-seam defense, no CC analogue) — stale-anchor freshness margin: a usage anchor is
+ * trusted only while the anchored estimate stays within `structural × margin + overhead` of the
+ * current message list. 2 covers the worst measured structural under-count (charsPerToken=3 vs a
+ * measured ~2.18 true ratio ⇒ ≤ ~1.4x) plus reasoning-block accounting slop, while still catching
+ * the live deception band (anchored estimates 2.9x–18x over the real context — docs/TOKEN-ESTIMATE-
+ * CALIBRATION-LIVE-2026-07-09.md §3/§4).
+ */
 export declare const STALE_ANCHOR_STRUCTURAL_MARGIN = 2;
 export declare function sanitizeCompactionSettings(settings: CompactionSettings, contextWindow: number | undefined): CompactionSettings;
+/**
+ * design/169-A — the CC-form fork context: the main lane's latest REAL brain request (same
+ * `systemPrompt` bytes, same message-list bytes, same tools). The summary request built from it is
+ * that request plus ONE appended user-role instruction message, so the provider's prompt cache
+ * re-serves the already-paid main prefix — the economics that make "summarize on the main model"
+ * cheap. Structural twin of the engine-side `CompactionForkContext` (engine/compaction/compaction.ts
+ * — the engine layer cannot import core, so the shape is declared on both faces and must stay
+ * assignable; `compact()`'s parameter type is the checked seam).
+ */
 export interface CompactionForkContext {
     systemPrompt?: string;
+    /** The physical cache-span block layout of the main request, when it had one (Context.systemBlocks)
+     *  — the fork must reproduce it or a multi-block pack's cache boundaries are silently lost. */
     systemBlocks?: Array<{
         text: string;
         cacheControlBoundary: boolean;
     }>;
     messages: Message[];
     tools?: Tool[];
+    /** The model id that served the recorded request — part of the provider cache key; the fork
+     *  eligibility gate refuses a snapshot from a different model (see the engine-side twin's doc). */
     modelId?: string;
 }
 export interface MaybeCompactOptions {
+    /** RB-473 — disclosure channel for CONTAINED host-callback failures in this scope (the RB-463
+     *  isolation primitive's bounded first-failure per site). Absent ⇒ failures are counted only. */
     onNotifyError?: (failure: import("./safe-notify.js").SafeNotifyFailure) => void;
+    /** The session to compact. Typed on the INTERFACE face (typecheck 车 2026-07-24): every member this
+     *  module touches lives on `Session` (the optional `getPromptEpoch` degrades honestly via `?.()`). */
     session: Session;
+    /** [1068] ruling a — this run's provider-declared prompt sections (the epoch declaration axis):
+     *  the compaction-boundary epoch restatement/advance must hash the SAME artifact identity as the
+     *  prepare-time pin, or every compaction under a declaration-carrying run would flap the pin. */
     epochDeclaredSections?: import("../prompt-assembly/epoch.js").EpochDeclaredSections;
+    /** RB-31 (design/148 S2) — a compaction-boundary CENTER CANDIDATE ADOPTION, pre-assembled by the
+     *  caller (prepare's seam): the descriptor advances with the candidate's declarations + provenance
+     *  in the SAME CAS append as the new baseline, and `apply()` (the live prefix/fingerprint swap)
+     *  runs ONLY after that append succeeded — a failed/blocked compaction must swap nothing. */
     centerAdoption?: {
+        /** Absent together with `clear` ⇒ never happens; adoption carries the new digest, ROLLBACK
+         *  (explicit center disable, codex F1) carries `clear:true` and no digest. */
         centerArtifactDigest?: string;
         sourceRevision?: string;
         clear?: true;
         declaredSections: import("../prompt-assembly/epoch.js").EpochDeclaredSections;
+        /** codex F2 — the post-swap prompt overhead in the trigger estimate's coordinate: used for THIS
+         *  compaction's post-measurement so PTL recovery/anti-thrash see the swapped prefix size. */
         overheadTokensAfter: number;
         apply: (committedArtifactDigest?: string) => void;
     };
+    /** Model whose context window bounds the budget (the model that runs the next turn). */
     model: Model;
+    /** Optional cheaper model used to produce the summary. Falls back to `model`.
+     *  design/145 §1 (semantics精确化): used only while WINDOW-SAFE and the budget gate allows — when a
+     *  dry-run clamp shows the conversation would lose more than `settings.clampTolerance` of its
+     *  chars to fit this model's window, the summary call falls back to the MAIN model (`model`),
+     *  which is always window-safe (the content grew inside its window; CC 207 :348496 compresses
+     *  with the main-loop model unconditionally — the fallback IS the CC posture, the independent
+     *  compaction model is sema's superset). Subagent note (design/145 §5): delegated children never
+     *  inherit this option (subagent.ts buildChildSpec carries no compactionModel), so a child always
+     *  self-compacts on its own main model — the judgment is structurally never triggered there. */
     compactionModel?: Model;
+    /**
+     * design/169-A — accessor for the main lane's latest real request context (see
+     * {@link CompactionForkContext}). Consulted per pass, at call time (the ref advances with every
+     * main request). Used ONLY when the summary call runs on the MAIN model (no `compactionModel` in
+     * play — an independent small model has no main prefix to share); `undefined` (or an accessor
+     * returning `undefined`: no main request issued yet, or a library caller driving maybeCompact
+     * directly) keeps the independent request form byte-for-byte. A fork-form prompt-too-long falls
+     * back ONCE to the independent form inside `compact()` (the fork form must not clamp — a clamp
+     * rewrites the cached prefix, defeating the form's purpose).
+     */
     forkContext?: () => CompactionForkContext | undefined;
     brain: Brain;
     getApiKeyAndHeaders?: (model: Model) => Promise<{
@@ -52,104 +153,470 @@ export interface MaybeCompactOptions {
     } | undefined>;
     thinking?: ThinkingLevel;
     settings?: CompactionSettings;
+    /** Appended to the summarization prompt to steer what must be preserved. Sanitized inside
+     *  maybeCompact via {@link sanitizeCompactionInstructions} (design/145 §4 — every channel,
+     *  including the preCompact hook's additions, gets the same treatment). */
     customInstructions?: string;
     signal?: AbortSignal;
+    /**
+     * Manual compact() withdrawal signal — the composed cancel signals of the manual callers THIS
+     * pass claimed (a strict SUBSET of `signal`, which additionally carries the task's own abort).
+     * Used only for failure ATTRIBUTION: when the summary call's failure is its abort outcome and
+     * this signal has fired, the thrown error is stamped so {@link isCompactionManualCancel} holds —
+     * the caller then treats the pass as withdrawn ("mooted") instead of summarizer evidence. It
+     * never aborts anything by itself (the same signals already ride inside `signal`).
+     */
     manualCancelSignal?: AbortSignal;
+    /**
+     * design/145 门A — budget interaction for the window-safety fallback: a MAIN-model re-compaction
+     * of a near-window conversation is one giant prefill whose cost lands in the SAME ledger the
+     * budget gate enforces (`recordCompactionUsage` → `stats.costMicroUsd` → `overBudget()`), so an
+     * un-gated fallback under a cost cap is the "钱花了任务照死" double loss. When present AND
+     * `mainInputPer1M` is known, the fallback is denied if `spentMicroUsd() + contentTokens ×
+     * mainInputPer1M > capMicroUsd` — the pass then keeps the small model and DISCLOSES the clamp
+     * (`clamp_disclosure`, reason "budget"). Absent field / absent pricing = the gate never blocks
+     * (design: "pricing/cap 不可得=门不拦").
+     */
     fallbackBudget?: {
+        /** Live cumulative spend reader (the caller's `stats.costMicroUsd` at decision time). */
         spentMicroUsd: () => number;
+        /** The run's cost ceiling, integer micro-USD. */
         capMicroUsd: number;
+        /** MAIN-model input price, absolute USD per 1M tokens (`ModelPricing.inputPer1M`) — numerically
+         *  equal to micro-USD per token, so `est = contentTokens × mainInputPer1M` needs no unit dance. */
         mainInputPer1M?: number;
     };
+    /**
+     * design/145 §3 — pre-call observer for the window-safety decision (fallback / disclosed clamp).
+     * Fired BEFORE the summary call (survives a later failure, `onInputTruncated` posture); throws
+     * are swallowed (observe-only). The caller bridges it to the `compaction.model_fallback` /
+     * `compaction.clamp_disclosure` trace frames.
+     */
     onWindowSafety?: (info: CompactionWindowSafetyInfo) => void;
+    /**
+     * Anti-thrash re-trigger floor (design/64 §25.2): ALSO require the estimated context to exceed this
+     * many tokens before compacting. The within-task caller sets it after each compaction (post-compaction
+     * size × regrowth factor) so a compaction that could not free much headroom — small window, chunky
+     * turns, large summary — does not re-fire a real summary LLM call at every subsequent boundary
+     * (LONGRUN-1b measured 26/39 boundaries firing, +135% wall, without it). 0/undefined = no floor.
+     */
     minTokens?: number;
+    /**
+     * Force a compaction even when context is UNDER the auto-threshold (and ignore `minTokens`) — the
+     * manual `/compact` path (TaskStream.compact, shell K-1c). It bypasses ONLY the threshold gate, not the
+     * structural floor: if there is no valid cut point (too little history to summarize) the call still
+     * returns `{compacted:false}` quietly. Default `false` = the auto-threshold policy.
+     */
     force?: boolean;
+    /**
+     * design/123 D4 (r5 final discriminant) — trim→compaction pressure propagation: force a compaction
+     * whenever the NATURAL gate would not fire, i.e. `est < max(threshold, minTokens-floor)`. Trim
+     * dropping real messages is external hard evidence that compaction is overdue, and it must override
+     * BOTH gates that can wrongly hold it back:
+     *   - est < threshold — the deceived-estimate regime (request-only trim deflates the next usage
+     *     anchor while the session stays full-size; the 16k-live sawtooth), and
+     *   - threshold ≤ est < floor — the floor-blocked regime (post-compaction §25.2 floor above an
+     *     HONEST over-threshold estimate; 5th live run: 27 boundaries trim-dropping while the floor
+     *     held compaction off and input climbed 16k→27.4k).
+     * `est ≥ max(threshold, floor)` fires naturally anyway (no force needed/applied — the result then
+     * reports `naturalTrigger: true`). Spiral protection lives in the CALLER via
+     * {@link nextTrimForceBackoff}: any landed compaction that still posts over the threshold
+     * (incompressible transcript, the LONGRUN-1b shape) disables further trim-forces until a landed
+     * compaction posts under the threshold again. Like `force`, this never bypasses the structural
+     * floor (no valid cut point ⇒ `{compacted:false}`).
+     */
     forceUnderThreshold?: boolean;
+    /**
+     * Working-file attachments (LONGRUN-2, CC-compact parity review 2026-06-12): after a successful
+     * summary, re-read up to `maxFiles` of the files the summarized region MODIFIED (from
+     * CompactionDetails.modifiedFiles) and append their current on-disk contents to the summary text.
+     * Why: LONGRUN-2 measured the model spending ≈2.3 extra read calls per compaction re-fetching
+     * files it had just lost — each one a full request round-trip at post-compaction context size.
+     * CC ships the same idea ("attachments", ≤5 files × ~5k tokens). Bounded: per-file char cap plus
+     * a total cap that self-scales to ~15% of the model window, so small windows never drown in
+     * attachments; the §25.2 freedTokens measurement naturally accounts for the added mass (the
+     * anti-thrash floor stays truthful). Reader failures skip the file (best-effort, never fails the
+     * compaction). Absent (default) = current behavior, paths-only.
+     * Pick order (design/71 P2-① resolved the LONGRUN-2b limitation): `maxFiles` picks the most
+     * RECENTLY touched files first (`CompactionDetails.modifiedFilesByRecency`, recency threaded
+     * through the engine fileOps accumulator); alphabetical `modifiedFiles` remains the fallback for
+     * details persisted before the field existed.
+     */
     workingFileAttachments?: {
+        /** Read a task workspace file; null/throw = skip it. Wired by the Runner from the task's ExecutionEnv. */
         readFile: (path: string) => Promise<string | null>;
+        /** Max modified files to attach. Default 3. */
         maxFiles?: number;
+        /** Per-file char cap (≈4 chars/token). Default 16_000 (~4k tokens). */
         maxCharsPerFile?: number;
+        /**
+         * Blackboard 2026-07-03 (CC-parity selection set): the files the task has READ, most recent
+         * first (CC 198's post-compact restore sorts readFileState by timestamp — the read set is wider
+         * than the modified set and includes reference files the model consulted). When provided and
+         * non-empty it WINS over `modifiedFilesByRecency`; absent/empty falls back to the modified set
+         * (the pre-2026-07-03 behavior, and the right answer for callers with no read tracking).
+         */
         recentlyReadFiles?: () => string[];
+        /**
+         * RB-197② (CC `compact.ts:1415-1463` `shouldExcludeFromPostCompactRestore` parity): paths already
+         * re-seeded through a DIFFERENT channel every turn (the deployment's declared instruction files —
+         * `ProjectMemoryLoad.instructionSources`, e.g. a project/user CLAUDE.md) are excluded from the
+         * `recentlyReadFiles`/fallback candidate set — re-attaching them here would just duplicate content
+         * the system-prompt lane already carries. A plain path list, not a hardcoded filename: core still
+         * never decides what counts as "an instruction file" on its own (types.ts's own seam rule) — it
+         * only trusts what the deployment already declared.
+         */
         instructionSourcePaths?: ReadonlyArray<string>;
+        /**
+         * RB-197②(独立复审 + codex 命中,已修): `recentlyReadFiles()` yields CANONICAL keys (resolveKey
+         * output — the same coordinate `ReadFileState` is keyed in), but `instructionSourcePaths` and the
+         * kept-tail scan inside `maybeCompact` (which reads raw tool-call arguments via
+         * `extractFileOpsFromMessage`) do NOT share that coordinate — a model-typed relative path and its
+         * canonical form are different strings, so a plain `Set.has()` between them silently never matches
+         * even for the identical file. Optional callback (present exactly when there's a containment root
+         * to resolve against — i.e. hands enabled) that canonicalizes a raw path the SAME way the hands
+         * toolkit does, so `maybeCompact` can normalize every side of the comparison before excluding.
+         * Best-effort: a throw/rejection is caught by the caller and treated as "leave this one path
+         * unnormalized" (a safe direction — worst case is a missed exclusion, not a wrong one). Absent
+         * when there is no containment root (hands disabled) — in that regime every path source is
+         * ALREADY in the same raw coordinate, so the fallback exact-string comparison is already correct.
+         */
         normalizePath?: (raw: string) => Promise<string>;
+        /**
+         * RB-197②(codex 交叉复审命中,已修) — a kept-tail Read tool-CALL's mere presence does not prove the
+         * file's real content is visible there: its toolRESULT may be a dedup stub ("unchanged since you
+         * last read it…") whose ORIGINAL full transmission sits in the summarized prefix THIS compaction is
+         * about to cut away — preserving read-state for such a path would leave both the kept tail and the
+         * next read pointing at content that is nowhere in context (RB-197①'s failure, reintroduced one hop
+         * removed). Optional predicate (present exactly when the caller's Read tool actually emits a
+         * recognizable stub marker) so `maybeCompact` can require at least one SUBSTANTIVE kept-tail Read
+         * result before trusting a path as genuinely visible; absent ⇒ every non-error kept-tail Read is
+         * trusted (the pre-this-fix behavior — still safe when the caller has no stub concept at all).
+         */
         isDedupStubResult?: (resultText: string) => boolean;
     };
+    /**
+     * RB-197: fires ONCE per LANDED compaction (after `appendCompaction` committed the new baseline), with the
+     * files that were attached WHOLE (untruncated) into the summary. The Runner wires this to the read-state
+     * invalidation (`applyCompactionToReadFileState`): the summary just replaced the history the read-dedup
+     * stubs point at, so stale entries must drop and the re-attached content re-registers. Kept OUTSIDE
+     * `workingFileAttachments` deliberately — the invalidation is owed even when attachments are disabled
+     * (an empty array then). Best-effort: a throwing callback must not fail the landed compaction.
+     *
+     * RB-197②(codex 命中,已修;独立复审第二轮又命中一条同族缺口,已修) `preserveReadState`:
+     * canonical-coordinate paths (same shape as `normalizePath`'s output) whose read-state entry must
+     * survive the compaction's clear even though they are NOT in `attachedComplete` — every file
+     * `maybeCompact` deliberately skipped re-attaching, for EITHER exclusion reason (kept-tail-visible,
+     * or matches a declared instruction source). Without this the read-state clear (see
+     * `applyCompactionToReadFileState`) would wipe them anyway, defeating both the read-before-edit gate
+     * and the next read's dedup for exactly the files this optimization was supposed to leave untouched.
+     * (The instruction-source half of this was missing in an earlier revision: `instructionSources` and
+     * `seededFiles` are independent `ProjectMemoryLoad` fields — a path can be declared in the former
+     * without ever being seeded via the latter, so an instruction-excluded file the model explicitly Read
+     * has a live, non-seeded entry that needs the SAME preservation as a kept-tail one.)
+     */
     onApplied?: (attachedComplete: ReadonlyArray<{
         path: string;
         content: string;
     }>, preserveReadState?: ReadonlyArray<string>) => void;
+    /**
+     * Fixed per-request prompt overhead (system prompt + tool schemas, in tokens), applied ONLY in the
+     * anchor-less regime (design/64 §26.7, search [91] fourth candidate): when no assistant in the
+     * visible history carries real usage (custom Brain implementations that don't report usage), the
+     * chars/4 fallback counts MESSAGES only and is blind to this overhead — the threshold would compare
+     * apples to oranges and under-trigger. When usage-anchored, the anchor IS the provider-billed input
+     * (system+tools included), so the overhead is already in and this is not added.
+     */
     overheadTokens?: number;
+    /**
+     * design/84 Seam C — compact-boundary COST optimization (data-gated). Fidelity is already achieved by
+     * the iterative-merge UPDATE_SUMMARY path (compaction.ts); the only remaining cost is one LLM call per
+     * boundary. A `summaryProvider` lets a caller supply a summary WITHOUT an LLM call: when it returns a
+     * NON-EMPTY string, that string is reused verbatim as the summary (the real `generateSummary` LLM call
+     * is skipped, `reused:true`). Returning `null`/`undefined`/an empty-or-whitespace string falls back to
+     * the existing `generateSummary` path — IDENTICAL to current behavior. **Absent (default) = no behavior
+     * change whatsoever**: the LLM path runs byte-for-byte as before.
+     *
+     * THIS IS A THIN SEAM ONLY: no provider is implemented in core. The provider implementation is gated on
+     * design/82 cost-per-truly-correct data (§3/§7-5). Reuse is guarded against degradation (see below).
+     *
+     * Inputs:
+     *  - `messagesToSummarize`: the message range that would be summarized this boundary.
+     *  - `previousSummary`: the prior compaction's summary (present on the UPDATE/iterative-merge path).
+     *  - `modifiedFiles`: files the summarized range modified, newest-first (same source the working-file
+     *    attachments use), so a provider can decide whether the reused summary is still representative.
+     */
     summaryProvider?: (input: {
         messagesToSummarize: AgentMessage[];
         previousSummary?: string;
         modifiedFiles: string[];
     }) => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * design/84 Seam C reuse guard (c): after this many CONSECUTIVE provider-reuse compactions, the next
+     * compaction is FORCED through the real `generateSummary` LLM path even if the provider would hit — this
+     * bounds summary drift from indefinite reuse. The caller owns the counter via {@link onCompaction}
+     * (`reused`) and feeds it back via this option; core treats `summaryProvider` as if absent for that one
+     * boundary when `consecutiveProviderReuse >= maxConsecutiveProviderReuse`. Default `3` (CC parity).
+     * `0`/undefined with no `consecutiveProviderReuse` = provider always consulted (no forced refresh).
+     */
     maxConsecutiveProviderReuse?: number;
+    /**
+     * design/84 Seam C reuse guard (c) — counter input: how many consecutive provider-reuse compactions have
+     * happened so far (caller-tracked from {@link onCompaction}'s `reused`). When this reaches
+     * `maxConsecutiveProviderReuse`, the provider is bypassed for this one boundary to force a real summary.
+     */
     consecutiveProviderReuse?: number;
+    /**
+     * design/84 Seam C — pure observer fired AFTER a successful compaction (never on a no-op/under-threshold
+     * return). Does NOT alter control flow. `reused` distinguishes a provider-supplied summary from a real
+     * LLM `generateSummary`. `freedTokens` is the §25.2 structural delta (may be ~0 when a reused summary
+     * frees little — see reuse guard (b): such a compaction does NOT raise the caller's anti-thrash floor).
+     */
     onCompaction?: (info: {
         messagesCompacted: number;
         freedTokens: number;
         tokensBefore: number;
         reused: boolean;
     }) => void;
+    /**
+     * design/134 §3.2 — which trigger this pass runs under, threaded into the pre/postCompact callback
+     * contexts and driving the block semantics: "auto" (threshold/boundary, the default) | "manual"
+     * (/compact) | "forced" (promptTooLong recovery and trim-pressure propagation — the compaction is
+     * not optional there, so a preCompact `block` is IGNORED on "forced").
+     */
     trigger?: "auto" | "manual" | "forced";
+    /**
+     * design/134 (CC PreCompact parity) — fired AFTER the trigger gate and a CONFIRMED valid cut point
+     * (so every invocation corresponds to a compaction that would actually happen), BEFORE the
+     * provider/summary call. `block` skips this compaction on auto/manual (`{compacted:false,
+     * blocked:true}`); ignored on "forced". `additionalInstructions` is APPENDED to the summarization
+     * instructions (never replaces them). A throw is swallowed on every path — treated as
+     * no-block/no-instructions (the caller's wrapper owns tracing; an observer bug must never feed the
+     * caller's breaker or kill PTL recovery).
+     */
     preCompact?: Hooks["preCompact"];
+    /**
+     * design/134 (CC PostCompact parity) — observe-only, fired after the compaction LANDED
+     * (appendCompaction done, post measurement taken). A throw is swallowed (same isolation contract
+     * as {@link onCompaction}: the compaction already succeeded).
+     */
     postCompact?: Hooks["postCompact"];
+    /**
+     * MF-18 修② ([496]③) — observe-only: fired when a summary call's serialized conversation INPUT was
+     * truncated to fit the compaction model's context window (the ~300K-session shape that previously
+     * guaranteed a provider prompt-too-long throw at every boundary). The caller bridges it to the
+     * `compaction.input_truncated` trace frame (fidelity disclosure). Fired BEFORE the summary call, so
+     * it reports truncation even when the attempt later fails.
+     */
     onInputTruncated?: (info: {
         label: "history" | "turn_prefix";
         droppedChars: number;
         keptChars: number;
     }) => void;
+    /**
+     * RB-402 ([2132]③c/[2133]) — the design/36 ToolSearch activation set LIVE at this pass (the
+     * runner threads `[...prepared.activeTools]` on all three lanes: boundary, PTL recovery, finish).
+     * Persisted into the landed compaction entry's details (`CompactionDetails.activeTools`) so the
+     * NEXT task boundary's re-derivation — whose transcript source (ToolSearch toolCall parts) this
+     * compaction just replaced with prose — re-seeds from a structured carrier instead (the
+     * checkpoint seed's `resume.seed.activeTools` sibling; prepare-task consumes it). Absent or
+     * empty ⇒ no key is written, byte-identical to pre-RB-402 entries.
+     */
     activeTools?: ReadonlyArray<string>;
 }
+/**
+ * Compact the session in place when context usage exceeds the threshold.
+ *
+ * Two call sites, same policy: the within-task `turn_boundary` hook (design/64 §25 (A) — after the
+ * session flush, before the next request's context rebuild) and `finish()` at task end. The caller
+ * must ensure no session write is in flight (both sites are between model requests, post-flush).
+ *
+ * THROWS (council §26.6 #6 contract note): a summarization failure — including a summary that came
+ * back EMPTY after the analysis-block strip (a real LLM call was burned, history left untouched) —
+ * is thrown, not swallowed; callers are expected to catch, count it toward the §17.4 breaker, and
+ * surface it via onError. A legitimate nothing-to-compact (under threshold/floor, no cut point)
+ * returns `{compacted:false}` quietly.
+ * Honors an optional cheaper `compactionModel` without mutating the harness's active model.
+ * Zero-config: uses DEFAULT_COMPACTION_SETTINGS unless overridden; settings pathological for the
+ * model's window are repaired via {@link sanitizeCompactionSettings}.
+ */
 export declare function maybeCompact(opts: MaybeCompactOptions): Promise<{
     compacted: boolean;
+    /** design/134: set (with `compacted:false`) when a preCompact callback blocked this compaction
+     *  (auto/manual triggers only — never on "forced"). NOT a failure: the caller must not count it
+     *  toward the compaction breaker; the next boundary consults the callback again. */
     blocked?: boolean;
+    /** MF-18 修① ([496]③): set (with `compacted:false`) when compaction is DISABLED by settings
+     *  (`enabled:false`) — the request can never be honored this run. Lets the caller resolve a manual
+     *  /compact with the honest `"disabled"` outcome (and trace frame) instead of a structural noop. */
     disabled?: boolean;
+    /** RB-398-b ([2105] ANG-5): set (with `compacted:false`) when the pass PASSED the trigger gate
+     *  (natural or forced) but found nothing to summarize — no valid cut point / empty history. Was
+     *  previously indistinguishable from the quiet under-threshold return, so a forced pass with
+     *  nothing to do looked identical to one that never wanted to run; the caller's outcome event
+     *  (`compaction_outcome{outcome:"noop"}`) reads this flag. */
     noop?: true;
     tokensBefore?: number;
     freedTokens?: number;
     triggerTokens?: number;
+    /** P-13: post-compaction context size in the SAME coordinate as `triggerTokens` (estimate + anchor-less
+     *  overhead). The caller's §25.2 regrowth floor = `postTriggerTokens × factor`, single-coordinate — never
+     *  `triggerTokens − freedTokens` (which mixed a usage-anchored trigger with a chars/4 freed delta). */
     postTriggerTokens?: number;
+    /** design/99 MF-18 `preserved_segment`: the session-tree entry id where the KEPT TAIL begins (the floor of
+     *  the surviving history after this compaction). Surfaced so the `compacted` wire event can carry it (CC
+     *  `SDKCompactBoundary.preserved_segment` parity); a consumer maps it to wire messages via its eventId↔entryId
+     *  map (the same one service keeps for resumeAt). Set only when `compacted` is true. */
     firstKeptEntryId?: string;
+    /** design/84 Seam C: true when this compaction reused a `summaryProvider` summary (no LLM call). */
     reused?: boolean;
+    /** Blackboard 2026-07-03 (ask ②): the working files re-read into the summary, in attachment order —
+     *  surfaced so the `compacted` wire event carries them and a shell renders CC's post-compact
+     *  `Read {path} (…)` cards. Set only when `compacted` is true and attachments were added. */
     attachedFiles?: Array<{
         path: string;
         chars: number;
         truncated: boolean;
     }>;
+    /** design/123 D4: true when the NATURAL gate fired (est ≥ max(threshold, minTokens) — no force was
+     *  needed); false on a forced landing (`force`/`forceUnderThreshold`). Set only when `compacted`. */
     naturalTrigger?: boolean;
+    /** design/123 D4: whether the post-compaction size (`postTriggerTokens` coordinate) is STILL over the
+     *  sanitized auto threshold — the "couldn't compact it down" signal {@link nextTrimForceBackoff}
+     *  consumes. Set only when `compacted` and the post measurement succeeded. */
     postOverThreshold?: boolean;
+    /** TB telemetry B4 (service [397]): wall time of the whole compaction pass (context build → summary
+     *  call → history rewrite → post measurement). Set only when `compacted` — the `compacted` wire event
+     *  carries it so a consumer sees what a boundary pause actually cost. */
     durationMs?: number;
+    /** 压缩子阶段遥测 (1.283 批 G 观察项 / design/145 §6 正交后续批 — TB 观测到整段 ~55s 停顿,需要
+     *  子阶段读数支撑归因): wall-time split of THIS landed pass, in the same Date.now() coordinate as
+     *  `durationMs`. `prepareMs` = context build → trigger math → cut-point selection → hooks/provider
+     *  consult → clamp dry run + 门A/门B gating (everything before the summary call). `summaryMs` = the
+     *  summary LLM leg (`compact()`: serialization → clamp → completion, incl. any PTL retries) — ABSENT
+     *  on a provider-reuse pass (no LLM call happened; its provider consult time sits in `prepareMs`).
+     *  `persistMs` = working-file attachments → session rewrite (`appendCompaction`) → post measurement →
+     *  observers. The phases tile the pass exactly: prepareMs + (summaryMs ?? 0) + persistMs ===
+     *  durationMs. `ptlRetries` = reactive prompt-too-long retries burned inside this pass's summary
+     *  call(s) (both split-turn legs accumulate into the one counter; 0 on provider reuse). Set only when
+     *  `compacted`. Exposure path note: runtask deliberately NOT touched this batch — the bridge to the
+     *  `compaction.phase_timings` trace frame (trace.ts, defined-not-yet-emitted) is a follow-up wiring
+     *  batch that adds an additive passthrough next to runtask's existing
+     *  `...(comp.durationMs !== undefined ? { durationMs: comp.durationMs } : {})` spread. */
     phaseDurations?: CompactionPhaseDurations;
+    /** service [398] C3: set (with `compacted:false`) when the pass was over the auto threshold but the
+     *  anti-thrash floor (`minTokens`) suppressed it — the caller bridges this to `compaction.suppressed`. */
     suppressedByFloor?: {
         estTokens: number;
         floor: number;
     };
+    /**
+     * Set (with `compacted:false`) when the trigger predicate could not be EVALUATED at all: the model
+     * declares no usable autocompact window (non-finite or <= 0), so `shouldCompact` refuses on the
+     * sentinel and `contextUsage` is honestly absent.
+     *
+     * This is a different state from "under the threshold", and it used to be indistinguishable from it:
+     * both returned a bare `{compacted:false}` with no `contextUsage`, no trace and no error, so a
+     * deployment whose model config lost its window had auto-compaction permanently disabled and the
+     * only notification was that nothing ever happened. The context still grows, the provider still
+     * eventually refuses the request, and the operator has nothing to read. The caller bridges this to
+     * a once-per-task host disclosure — silence is the defect here, so a noisy line is the fix.
+     *
+     * `estTokens` is the size this pass DID manage to estimate (structural + prompt overhead when no
+     * usage anchor is available), so the disclosure can say how big the context already is even though
+     * it cannot say how big the window is.
+     */
     unevaluableWindow?: {
         estTokens: number;
+        /** WHICH of the three window fields the `??` precedence actually selected. A defined-but-unusable
+         *  higher-precedence field (`autoCompactTokens: 0`) shadows a healthy lower one, so "no window is
+         *  declared" is the wrong story on that path — the caller reports THIS field, not all three. */
         windowField: "autoCompactTokens" | "contextTokens" | "contextWindow";
+        /** The unusable value that field carried, when it carried one at all (absent = nothing declared). */
         windowValue?: number;
         modelId?: string;
     };
+    /**
+     * RB-126 / blackboard [1669]⑥ (2026-07-25, server's ask): the trigger inputs THIS pass used, reported on
+     * EVERY return path — including the ordinary "nothing to do" one. A consumer rendering "how full is the
+     * context" was otherwise forced to re-derive the numerator itself, and a re-derivation that drifts from
+     * the engine's own is the projection-antipattern this repo keeps paying for: the displayed percentage
+     * would disagree with when compaction actually fires.
+     *
+     * `usedTokens` is the exact first argument to `shouldCompact` (usage-anchored when the anchor is fresh,
+     * structural + fixed prompt overhead otherwise — see the derivation above). `windowTokens` is the
+     * AUTOCOMPACT window (`autoCompactTokens` when the model declares one, else its context window), NOT
+     * necessarily the physical request window. `compactAtTokens` is the threshold those two are compared
+     * against, so `usedTokens > compactAtTokens` is precisely the engine's own trigger predicate.
+     */
     contextUsage?: {
         usedTokens: number;
         windowTokens: number;
         compactAtTokens: number;
     };
+    /** design/145 §3: this pass's summary call FELL BACK from the independent compaction model to the
+     *  main model (window safety). Rides the `compacted` wire event as an additive field. */
     modelFallback?: true;
+    /** design/145 §3: why the fallback happened — "window" is the only reason today. */
     fallbackReason?: "window";
+    /** design/145 §3: the dry-run truncation ratio of a pass whose summary input WAS (or would be)
+     *  clamp-truncated on the small model — set when a gate denied the fallback OR the ratio was
+     *  within tolerance but non-zero. */
     clampedRatio?: number;
+    /** design/145 §3: "budget" = the gate denied the fallback; "tolerance" = within-tolerance
+     *  ordinary truncation (disclosed, not silent). */
     clampReason?: "budget" | "tolerance";
 }>;
+/**
+ * design/123 D4 (r5) — trim-force BACKOFF transition (pure; the run-scoped bit lives in the caller).
+ * Spiral protection replacing the §25.2 floor's role on the trim-force path: trim pressure re-arms
+ * every request while the transcript is oversized, so an unconditional force would burn a summary
+ * call at every boundary when summaries CANNOT shrink the context (the LONGRUN-1b incompressible
+ * shape). The invariant: trim-force is permitted only while the LATEST landed compaction proved it
+ * can bring the context back under the threshold (or no compaction has landed yet). Transitions,
+ * evaluated after each maybeCompact result:
+ *   1. no compaction landed → state unchanged (a structural no-op proves nothing either way);
+ *   2. a landed compaction with `postOverThreshold` → "压不动": BACKOFF ON — compaction demonstrably
+ *      cannot reach under-threshold, so forcing more of them only burns summary calls; the §25.2
+ *      floor policy takes back over (natural triggers are never gated by this bit);
+ *   3. a landed compaction that posted UNDER the threshold → summaries compress again: BACKOFF OFF
+ *      (this is how the natural floor-crossing compaction of design/123 D4's reset clause re-enables
+ *      the trim-force — its healthy landing posts under threshold);
+ *   4. post measurement unavailable → state unchanged (never flip on missing evidence);
+ *   5. (COMPACTION-LIVE-AUDIT D-1, evaluated BEFORE rule 3) a TRIM-FORCED landing with
+ *      `freedTokens ≤ 0` → negative-yield: BACKOFF ON. The trim layer deceives the usage-anchored
+ *      estimate down into the sawtooth trough (live: est 18807 on a ~55k session), the forced pass
+ *      finds little compressible history, and summary + working-file attachments make the transcript
+ *      LARGER (live: 18807→44609, 12679→35214). `freedTokens` is the structural pre/post delta
+ *      (clamped ≥0, so ≤0 means "freed nothing") — orthogonal to rule 2/3's threshold test, which
+ *      misses this shape because the bloated post (44609) can still sit UNDER the threshold (44800),
+ *      so rule 3 alone would re-enable the force and repeat the negative-yield pass every boundary.
+ *      SEMA-ONLY DEFENSE, not a CC port: CC's full compact keeps tail 0 and monotonically shrinks
+ *      (capture §A4), and CC has no request-layer trim, so this regime cannot exist there — it is a
+ *      derived interaction of our trim seam × keep-tail × attachment mass. Scoped to trim-forced
+ *      passes only (`trimForced`), so Seam C reused-summary landings (freed≈0 by design) on the
+ *      natural/manual paths never trip it. Release path unchanged: backoff gates only the FORCE, a
+ *      later natural landing that posts under threshold (rule 3, non-trim-forced) turns it back off.
+ */
 export declare function nextTrimForceBackoff(prev: boolean, comp: {
     compacted: boolean;
     postOverThreshold?: boolean;
     freedTokens?: number;
     naturalTrigger?: boolean;
 }, trimForced?: boolean): boolean;
+/** design/119 S3 (CC 198 rapid_refill_breaker): mutable per-task refill tracking state. */
 export interface RapidRefillState {
     lastCompactionTurn: number;
     count: number;
 }
+/** Fresh tracking state (no compaction seen yet). */
 export declare function createRapidRefillState(): RapidRefillState;
+/**
+ * design/119 S3 (CC 2.1.198 rapid_refill_breaker, :229717/:476338): record that a compaction just
+ * happened at `turn` and report whether the thrash breaker should TRIP. A compaction landing within
+ * `minGapTurns` of the previous one is a "rapid refill"; `tripAt` consecutive rapid refills = the
+ * context is dominated by incompressible content and further compaction only burns summary calls.
+ * CC terminates the task; sema's caller (runtask) deviates conservatively — it opens the existing
+ * compaction breaker (no more compaction this task) and lets budget/PTL/turn limits end the run.
+ */
 export declare function recordCompactionAndCheckRapidRefill(state: RapidRefillState, turn: number, minGapTurns?: number, tripAt?: number): boolean;