@sema-agent/core 5.19.0 → 5.21.0

package/dist/engine/compaction/compaction.d.ts

@@ -3,88 +3,343 @@ import { type AgentCoreCompletionRuntimeDeps } from "../loop/runtime-deps.js";
 import type { AgentMessage, ThinkingLevel } from "../loop/types.js";
 import { CompactionError, type Result, type SessionTreeEntry } from "../harness/types.js";
 import { type FileOperations, type InvokedSkillRetention } from "./utils.js";
+/** File-operation details stored on generated compaction entries. */
 export interface CompactionDetails {
+    /** Files read in the compacted history. */
     readFiles: string[];
+    /** Files modified in the compacted history (sorted, for stable display). */
     modifiedFiles: string[];
+    /**
+     * The same modified set ordered most-recently-touched FIRST. Top-N consumers (working-file
+     * attachments) pick from here so an alphabetical sort cannot push the file the model actually
+     * needs out of the window (the LONGRUN-2b miss). Optional: absent on details persisted before
+     * this field existed.
+     */
     modifiedFilesByRecency?: string[];
+    /**
+     * Invoked-skill retention area (CC 2.1.207 parity): the skills invoked in the COMPACTED range
+     * (merged over the previous compaction's retained set), most recent invocation first, already
+     * budgeted (per-skill truncation marker + total-area skip semantics — see compaction/utils.ts).
+     * Rendered onto the compaction summary message by `buildSessionContext`; kept OUT of the summary
+     * string so the summarizer LLM never re-chews skill bodies. Optional: absent on details persisted
+     * before this field existed, and omitted when no skill was ever invoked.
+     */
     invokedSkills?: InvokedSkillRetention[];
+    /**
+     * RB-398-b① ([2105]): CUMULATIVE count of transcript messages this compaction's summary stands in
+     * for (this range's folded messages + the previous compaction's carried count). WRITE-side
+     * accounting on purpose: deriving the count at render time from the branch walk broke the F3
+     * "bounded wake equals full wake" invariant (a floored storage cannot see below the floor, so the
+     * two sides disagreed — caught by test/session-floor.test.ts). Drives the summary wrapper's scale
+     * disclosure (`buildSessionContext` → `CompactionSummaryMessage.elidedMessages`). Optional-absent
+     * on pre-field entries (⇒ no disclosure, byte-identical legacy wrapper).
+     */
     elidedMessages?: number;
+    /**
+     * RB-398-c (blackboard [2105]): `<persisted-output ref="…">` handles found in the COMPACTED range
+     * (merged over the previous compaction's retained set, oldest-first, capped at
+     * {@link PERSISTED_OUTPUT_REFS_MAX_ENTRIES} newest). The offloaded blobs outlive the preview that
+     * carried their only address — without this channel the handle survived only if the summarizer
+     * model happened to copy the string. Rendered as a deterministic summary footer by `compact()`
+     * (`formatPersistedOutputRefs`), the same channel `readFiles`/`modifiedFiles` already have.
+     * Optional-absent when the range held no offloaded results.
+     */
     persistedOutputRefs?: string[];
+    /**
+     * RB-402 (blackboard [2132]③c/[2133]): the activated deferred-tool names LIVE at the
+     * moment this compaction landed — the design/36 activation state whose transcript carriers
+     * (the ToolSearch toolCall parts, and since RB-431 the successful direct calls, that
+     * `extractDiscoveredToolNames` replays at every task boundary)
+     * this very compaction just replaced with summary prose. Same field shape as the checkpoint
+     * seed's `CheckpointState.activeTools` (design/45 §4.bis — the sibling seam that already
+     * survives a suspend/resume). Written by the runtask compaction lanes
+     * (`MaybeCompactOptions.activeTools` → `maybeCompact`'s appendCompaction, NOT by
+     * `prepareCompaction` — the engine layer has no view of the runner's activation Set); consumed
+     * by prepare-task's boundary re-derivation via `readCompactionActiveTools` and intersected with
+     * the NEXT leg's own deferred registry (a name no longer deferred there is inert).
+     * Optional-absent on pre-RB-402 entries and on legs with no activations.
+     */
     activeTools?: string[];
 }
+/** Generated compaction data ready to be persisted as a compaction entry. */
 export interface CompactionResult<T = unknown> {
+    /** Summary text that replaces compacted history in future context. */
     summary: string;
+    /** Entry id where retained history starts. */
     firstKeptEntryId: string;
+    /** Estimated context tokens before compaction. */
     tokensBefore: number;
+    /** Optional implementation-specific details stored with the compaction entry. */
     details?: T;
 }
+/** Compaction thresholds and retention settings. */
 export interface CompactionSettings {
+    /** Enable automatic compaction decisions. */
     enabled: boolean;
+    /** Tokens reserved below the context window for the TRIGGER threshold (threshold = window −
+     *  reserve). Historically this single knob ALSO seeded the summary legs' output budget
+     *  (0.8×/0.5×); that second role is now owned by {@link summaryOutputBudgetTokens} (with this
+     *  field as its default base), so trigger-geometry repairs (`sanitizeCompactionSettings`) can
+     *  never silently move the summary budget. */
     reserveTokens: number;
+    /**
+     * Explicit base for the summary OUTPUT budget (the 0.8× history-leg / 0.5× turn-prefix-leg
+     * max_tokens derivation), decoupled from `reserveTokens`' trigger role. Absent ⇒ `reserveTokens`
+     * is the base (historical behavior). Either way the effective base is capped by the SUMMARY
+     * model's own max output (see {@link summaryOutputBudgetTokens}) — budgeting output the model
+     * cannot emit only starves the pre-send input clamp. `sanitizeCompactionSettings` passes this
+     * field through untouched: it is not trigger geometry.
+     */
     summaryOutputBudgetTokens?: number;
+    /** Approximate recent-context tokens to keep after compaction. */
     keepRecentTokens: number;
+    /** design/145 §1 — window-safety clamp tolerance for an independent (smaller-window) compaction
+     *  model: when the summarization input would be clamp-truncated by MORE than this ratio (the
+     *  {@link dryRunSummarizationClamp} judgment), the summary call becomes a candidate to fall back
+     *  to the MAIN model, which is always window-safe (the content grew inside its window). 0 = any
+     *  truncation is a fallback candidate; 1 = never fall back (the pre-145 clamp-only behavior, the
+     *  escape hatch). Default {@link DEFAULT_CLAMP_TOLERANCE}. */
     clampTolerance?: number;
 }
+/** design/145 §1 — default `clampTolerance`: head+tail clamping keeps ≤10% mid-section loss BOUNDED
+ *  AND DISCLOSED (`compaction.clamp_disclosure`), not "lossless" — the honest wording is in the
+ *  design doc. Above this, a cheap-model summary is judged too lossy and the main model takes over. */
 export declare const DEFAULT_CLAMP_TOLERANCE = 0.1;
+/** Default compaction settings used by the harness.
+ *  design/169-C (CC 220 :516151 `messagesToKeep: []` parity): the DEFAULT compaction is a FULL
+ *  compaction — `keepRecentTokens: 0` keeps no verbatim token budget; the summary replaces the
+ *  region entirely (the cut still lands on the nearest valid floor, so tool pairs and the
+ *  in-progress turn's suffix stay intact). Keeping a verbatim tail is the reactive/partial posture
+ *  and remains available as the explicit `keepRecentTokens` knob (the pre-169 default was 20000). */
 export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/**
+ * design/123 D2 — default structural coefficient (chars per token) for every structural token
+ * estimate. 4 = the historical chars/4 heuristic (CC 198's legacy-family value); per-model override
+ * via `Model.charsPerToken` (newer families → 3, CJK-heavy → 2–3). Threaded as an explicit parameter
+ * through the estimate chain so caller-side coordinates never split (estimate vs cut-point vs defense).
+ */
 export declare const DEFAULT_CHARS_PER_TOKEN = 4;
+/** Calculate total context tokens from provider usage. */
 export declare function calculateContextTokens(usage: Usage): number;
+/**
+ * Return usage from the last successful assistant message in session entries.
+ *
+ * design/123 D1 stale-anchor note (fable-m2, same-family point): this scans RAW session entries, so
+ * unlike `buildSessionContext` (which shallow-strips the usage of kept-tail assistants replayed
+ * across a compaction boundary — the anchor "naturally disappears", CC 198 parity) it CAN still see
+ * a pre-compaction anchor. Any consumer using this across a compaction boundary must treat such an
+ * anchor as STALE: it reflects the pre-compaction request and overestimates the post-compaction
+ * context. (Currently exported with no in-repo production consumer.)
+ */
 export declare function getLastAssistantUsage(entries: SessionTreeEntry[]): Usage | undefined;
+/** Estimated context-token usage for a message list. */
 export interface ContextUsageEstimate {
+    /** Estimated total context tokens. */
     tokens: number;
+    /** Tokens reported by the most recent assistant usage block. */
     usageTokens: number;
+    /** Estimated tokens after the most recent assistant usage block. */
     trailingTokens: number;
+    /** Index of the message that provided usage, or null when none exists. */
     lastUsageIndex: number | null;
 }
+/** Estimate context tokens for messages using provider usage when available.
+ *  `charsPerToken` (design/123 D2): structural coefficient for the anchor-less fallback and the
+ *  trailing (post-anchor) increment — pass `Model.charsPerToken` so the estimate matches the model. */
 export declare function estimateContextTokens(messages: AgentMessage[], charsPerToken?: number): ContextUsageEstimate;
+/** Return whether context usage exceeds the configured compaction threshold. */
 export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/** Estimate token count for one message using a conservative character heuristic.
+ *  `charsPerToken` (design/123 D2): per-model structural coefficient (default 4 = byte-compatible
+ *  legacy heuristic). Images contribute a FIXED token weight independent of the coefficient. */
 export declare function estimateTokens(message: AgentMessage, charsPerToken?: number): number;
+/** Find the user-visible message that starts the turn containing an entry. */
 export declare function findTurnStartIndex(entries: SessionTreeEntry[], entryIndex: number, startIndex: number): number;
+/** Cut point selected for compaction. */
 export interface CutPointResult {
+    /** Index of the first entry retained after compaction. */
     firstKeptEntryIndex: number;
+    /** Index of the turn-start entry when the cut splits a turn, otherwise -1. */
     turnStartIndex: number;
+    /** Whether the selected cut point splits an in-progress turn. */
     isSplitTurn: boolean;
 }
+/** Find the compaction cut point that keeps approximately the requested recent-token budget.
+ *  `charsPerToken` (design/123 D2): the keep-recent accumulation must live in the SAME structural
+ *  coordinate as the trigger estimate, or the kept tail is systematically over/under-sized. */
 export declare function findCutPoint(entries: SessionTreeEntry[], startIndex: number, endIndex: number, keepRecentTokens: number, charsPerToken?: number): CutPointResult;
 export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";
+/**
+ * design/169-A (CC 220 :516490-516516 / :387325-387336) — the CC-form FORK context for a summary
+ * request: the main lane's latest REAL request. When present (and the summary model IS the main
+ * model), the summary request is the main conversation itself — same `systemPrompt` bytes, same
+ * message-list byte PREFIX, same tools — plus ONE appended user-role instruction message. The
+ * provider's prompt cache then re-serves the already-paid main prefix, which is the economics that
+ * make "summarize on the main model" cheap (an independent request re-prefills the whole
+ * conversation at full price every boundary).
+ *
+ * Mirrored structurally (not imported — core cannot be imported from the engine layer) by
+ * `CompactionForkContext` in `src/core/auto-compaction.ts`; the two must stay assignable.
+ */
 export interface CompactionForkContext {
+    /** The main request's system prompt, byte-identical (absent when the main request had none). */
     systemPrompt?: string;
+    /** The main request's PHYSICAL system-block layout (Context.systemBlocks), when present — the
+     *  cache-span boundaries are part of the prefix identity a fork must reproduce. */
     systemBlocks?: Context["systemBlocks"];
+    /** The main request's message list — reused as the fork's byte-identical prefix. */
     messages: Message[];
+    /** The main request's tool declarations (part of the provider's cached prefix; optional — the
+     *  instruction forbids tool calls either way). */
     tools?: Tool[];
+    /** The model id that SERVED the recorded request. The model is part of the provider's cache key:
+     *  a fork whose summary call runs on a different model (mid-run budget degradation swapped models
+     *  after the snapshot) pays a full prefill — the eligibility gate compares this against the
+     *  summary model and degrades to the independent form on mismatch. Optional so a direct caller
+     *  that manages its own model constancy can omit it (absent = caller vouches). */
     modelId?: string;
 }
+/** Extract the fork-form summary from its envelope; `undefined` = non-conforming response.
+ *
+ *  Grammar (adversarial round 3, both arms pinned): after stripping the permitted `<analysis>`
+ *  scratch blocks, the ENTIRE remaining response must be one envelope — text outside it is a
+ *  rejection, not noise ("<summary>placeholder</summary> I refuse" must not pass as "placeholder").
+ *  The inner match is GREEDY with the closing tag anchored at the END, because the summary quotes
+ *  user messages VERBATIM — a quoted literal `</summary>` inside the body must not truncate an
+ *  otherwise conforming summary into an accepted fragment (the first-match form silently dropped
+ *  every section after the quote). */
 export declare function extractForkSummaryEnvelope(text: string): string | undefined;
+/** design/169-A — the single user-role instruction message appended to the forked main prefix.
+ *  Semantics = SUMMARIZATION_SYSTEM_PROMPT's text-only contract + SUMMARIZATION_PROMPT's nine-section
+ *  body ("The messages above…" reads exactly right in the fork form: the conversation IS the
+ *  messages above, un-serialized) + the fork-only summary envelope (see
+ *  {@link FORK_SUMMARY_ENVELOPE_DEMAND}; the independent form keeps its envelope-free contract).
+ *  Instructions inject in the same CC-verbatim shape as the independent form so every channel keeps
+ *  one injection grammar. */
 export declare function forkSummarizationInstruction(customInstructions?: string): string;
+/**
+ * Trigger-reserve / summary-budget decoupling (blocker fix, 触发点对标批复审追补): the base for the
+ * summary legs' OUTPUT budget (history leg = 0.8× this, turn-prefix leg = 0.5× this).
+ *
+ * Two semantics used to ride one knob: `reserveTokens` is the TRIGGER deduction (threshold =
+ * window − reserve, repaired by `sanitizeCompactionSettings` against the trigger frontier), and the
+ * same — possibly repaired — value seeded the summary output budget. That coupling made the summary
+ * budget a hostage of trigger geometry: when the frontier moved (0.7W → W−33000), a 200k-window
+ * default's budget silently shrank 48000 → 26400 with zero summary-semantics justification.
+ *
+ * Decoupled shape:
+ *   base      = settings.summaryOutputBudgetTokens ?? settings.reserveTokens  (explicit knob wins)
+ *   effective = min(base, summary model's max output)                          (never budget output
+ *                                                                               the model can't emit)
+ * CC contrast (2.1.207): CC's summary output cap is purely model-derived (its summary call runs at
+ * the model's max output) and fully separate from the trigger deduction — the `min(model.maxTokens,…)`
+ * leg IS that posture. The base deliberately stays reserve-derived rather than jumping to the raw
+ * model max: sema (unlike CC) clamps the summarization INPUT pre-send, and the clamp budgets
+ * `window − max(0.8×base, reasoning floor)` — a model-max base (e.g. 64k) would eat half a small
+ * summarizer's window in output reservation and starve the input side. Callers wanting the pure CC
+ * posture set `summaryOutputBudgetTokens = model.maxTokens` explicitly.
+ *
+ * SINGLE SOURCE: consumed by `compact()` (both real legs), `dryRunSummarizationClamp` (the 1.286
+ * same-params dry-run judgment), and the prepare-time `compaction.window_config_warning` estimate —
+ * so the dry run and the real clamp cannot drift.
+ */
 export declare function summaryOutputBudgetTokens(model: Model, settings: CompactionSettings): number;
+/** Fidelity-disclosure payload for a truncated summarization input (bridged by the caller to the
+ *  `compaction.input_truncated` trace frame). `keptChars` = surviving conversation chars (marker excluded). */
 export interface SummarizationInputTruncation {
     label: "history" | "turn_prefix";
     droppedChars: number;
     keptChars: number;
 }
+/** design/145 §1 — result of a window-safety clamp DRY RUN (see {@link dryRunSummarizationClamp}). */
 export interface SummarizationClampDryRun {
+    /** Conversation chars the clamp would drop across BOTH summary legs (history + split-turn prefix). */
     droppedChars: number;
+    /** Conversation chars that would survive (marker excluded), across both legs. */
     keptChars: number;
+    /** `droppedChars / max(1, droppedChars + keptChars)` — always ∈ [0,1]; 0 for empty content
+     *  (nothing to drop) and <1 even at negative headroom (the clamp keeps a MIN_KEEP floor). */
     truncationRatio: number;
+    /** Total serialized conversation chars (pre-clamp), across both legs — the honest "content size"
+     *  coordinate for the fallback cost gate (chars ÷ the consumer's charsPerToken). */
     conversationChars: number;
 }
+/**
+ * design/145 §1 — the SINGLE-SOURCE window-safety judgment: dry-run `clampSummarizationConversation`
+ * with the SAME parameters the real summary call(s) would use (same serialization, same fixed-prompt
+ * charge, same output reservation), WITHOUT sending anything. Consumed by `maybeCompact` to decide
+ * whether an independent (smaller-window) compaction model would truncate the conversation past
+ * `CompactionSettings.clampTolerance` — the r2 review killed the r1 token-domain twin formula
+ * precisely because two formulas drift; this function IS the clamp, so the judgment cannot.
+ *
+ * Split-turn boundaries aggregate both legs (history + turn prefix): the real path clamps each leg
+ * against its own budget (0.8× vs 0.5× reserve), so the dry run mirrors both and reports the summed
+ * ratio. Multi-round compactions are covered by construction: the preparation's `previousSummary`
+ * charges the fixed-prompt budget exactly as `generateSummary` does, so round 2's judgment is over
+ * "prior summary + new increment", not the original history.
+ */
 export declare function dryRunSummarizationClamp(preparation: CompactionPreparation, model: Model, customInstructions?: string, charsPerToken?: number): SummarizationClampDryRun;
+/** CC 198 jNl — verbatim marker inserted where the oldest conversation groups were dropped. */
 export declare const COMPACTION_PTL_RETRY_MARKER = "[earlier conversation truncated for compaction retry]";
+/** Generate or update a conversation summary for compaction.
+ *  `summaryBudgetTokens` — the OUTPUT budget base (history leg = 0.8× it). Callers going through
+ *  `compact()` get the decoupled, model-capped value from {@link summaryOutputBudgetTokens}; this
+ *  parameter was historically the raw `settings.reserveTokens` (trigger reserve). */
 export declare function generateSummary(currentMessages: AgentMessage[], model: Model, summaryBudgetTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, runtime?: AgentCoreCompletionRuntimeDeps, charsPerToken?: number, onInputTruncated?: (info: SummarizationInputTruncation) => void, onPtlRetry?: () => void): Promise<Result<string, CompactionError>>;
+/** Prepared inputs for a compaction run. */
 export interface CompactionPreparation {
+    /** Entry id where retained history starts. */
     firstKeptEntryId: string;
+    /** Messages summarized into the history summary. */
     messagesToSummarize: AgentMessage[];
+    /** Prefix messages summarized separately when compaction splits a turn. */
     turnPrefixMessages: AgentMessage[];
+    /** Whether compaction splits a turn. */
     isSplitTurn: boolean;
+    /** Estimated context tokens before compaction. */
     tokensBefore: number;
+    /** Previous compaction summary used for iterative updates. */
     previousSummary?: string;
+    /** File operations extracted from summarized history. */
     fileOps: FileOperations;
+    /** Budgeted invoked-skill retention for the DROPPED range (merged over the previous compaction's
+     *  retained set), most-recent-first — ready to persist as `CompactionDetails.invokedSkills`. */
     invokedSkills: InvokedSkillRetention[];
+    /** RB-398-c: offload handles from the DROPPED range (merged over the previous compaction's
+     *  retained set, oldest-first, capped) — ready to persist as
+     *  `CompactionDetails.persistedOutputRefs` and render as the summary footer. Optional so
+     *  hand-built preparations (tests, external callers) stay valid; absent = none. */
     persistedOutputRefs?: string[];
+    /** RB-398-b①: cumulative folded-message count (this range + the previous carrier's count) —
+     *  ready to persist as `CompactionDetails.elidedMessages`. Optional (same rule as above). */
     elidedMessages?: number;
+    /** Settings used to prepare compaction. */
     settings: CompactionSettings;
 }
+/** Prepare session entries for compaction, or return undefined when compaction is not applicable.
+ *  `charsPerToken` (design/123 D2, signature threading): keeps `tokensBefore` and the cut-point
+ *  accounting in the same per-model structural coordinate as the caller's trigger estimate.
+ *  `windowTokens` (window-aware retention clamp): the trigger window of the model that will consume
+ *  the post-compaction context. When provided, the invoked-skills retained area is clamped to the
+ *  headroom that window leaves after the existing geometry (`window − reserveTokens −
+ *  keepRecentTokens`, in chars) — the CC-shaped 20k/100k retention caps are UPPER BOUNDS tuned for
+ *  large windows, and on a small-window model an unclamped area would push every post-compaction
+ *  request straight back over the window the compaction just freed. Absent ⇒ the plain CC-shaped
+ *  budget (legacy behavior). */
 export declare function prepareCompaction(pathEntries: SessionTreeEntry[], settings: CompactionSettings, charsPerToken?: number, windowTokens?: number): Result<CompactionPreparation | undefined, CompactionError>;
 export { computeFileLists, serializeConversation } from "./utils.js";
-export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, runtime?: AgentCoreCompletionRuntimeDeps, charsPerToken?: number, onInputTruncated?: (info: SummarizationInputTruncation) => void, onPtlRetry?: () => void, forkContext?: CompactionForkContext): Promise<Result<CompactionResult, CompactionError>>;
+/** Generate compaction summary data from prepared session history.
+ *  `charsPerToken` (design/123 D2, signature threading): coefficient for the summarization-input
+ *  window guard. Defaults to the SUMMARY model's own `charsPerToken` (the estimated input is sent to
+ *  THAT model), then 4. */
+export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, runtime?: AgentCoreCompletionRuntimeDeps, charsPerToken?: number, onInputTruncated?: (info: SummarizationInputTruncation) => void, onPtlRetry?: () => void, 
+/** design/169-A — when present, the summary is attempted in the CC FORK form first (main prefix +
+ *  one instruction message; see {@link CompactionForkContext}). A prompt-too-long on the fork form
+ *  falls back ONCE to the independent form below (which can clamp; the fork form must not — a
+ *  clamp would rewrite the cached prefix). The caller only passes this when the summary model IS
+ *  the main model; an independent compaction model has no main prefix to share. */
+forkContext?: CompactionForkContext): Promise<Result<CompactionResult, CompactionError>>;
+/** The prefix leg's base prompt, with the caller's instructions injected in the SAME shape the
+ *  history leg uses (`\n\nAdditional Instructions:\n${…}`, CC 198 verbatim). Single source so the
+ *  dry-run clamp charges exactly what the real call sends. */
 export declare function turnPrefixSummarizationPrompt(customInstructions?: string): string;

package/dist/engine/compaction/utils.d.ts

@@ -1,37 +1,131 @@
 import type { Message } from "../llm/index.js";
 import type { AgentMessage } from "../loop/types.js";
+/** File paths touched by a session branch or compaction range. */
 export interface FileOperations {
+    /** Files read but not necessarily modified. */
     read: Set<string>;
+    /** Files written by full-file write operations. */
     written: Set<string>;
+    /** Files modified by edit operations. */
     edited: Set<string>;
+    /**
+     * Cross-set touch order for modified files (written ∪ edited), oldest→newest — a re-touch moves
+     * the path to the end (Set insertion-order semantics via delete-then-add). This is what lets
+     * working-file attachments pick the MOST RECENTLY touched files instead of the first N
+     * alphabetically (the LONGRUN-2b miss: orders.js sorted out of the top-3).
+     */
     modifiedOrder: Set<string>;
 }
+/** Create an empty file-operation accumulator. */
 export declare function createFileOps(): FileOperations;
+/** Add file operations from assistant tool calls to an accumulator. */
 export declare function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void;
+/** One retained invoked skill: the Skill tool result text as it stood in context (possibly
+ *  truncated with {@link SKILL_RETENTION_TRUNCATION_MARKER}). */
 export interface InvokedSkillRetention {
     name: string;
     content: string;
 }
+/** Per-skill retained-content cap (chars; CC: 5000 tokens). Truncation is marker-inclusive: a
+ *  truncated entry is EXACTLY this long, marker included. */
 export declare const SKILL_RETENTION_PER_SKILL_MAX_CHARS = 20000;
+/** Total retained-area budget (chars; CC: 25000 tokens). Skills that do not fit whole are skipped
+ *  individually — later (smaller) skills may still fit. */
 export declare const SKILL_RETENTION_TOTAL_MAX_CHARS = 100000;
+/** In-band truncation marker. CC's marker points at `Read` on the skill's file path; sema skills
+ *  are spec-supplied content with no filesystem path, so the equivalent recovery route here is
+ *  re-invoking the Skill tool (which, post-parity, always serves the FULL text). */
 export declare const SKILL_RETENTION_TRUNCATION_MARKER = "[... skill content truncated for compaction; invoke the Skill tool again if you need the full text]";
+/** Strip the appended model-supplied `## Input` args section from a Skill tool result body (see
+ *  {@link SKILL_INPUT_SECTION_SEPARATOR}); returns the body unchanged when no section is present. */
 export declare function stripSkillInputSection(text: string): string;
+/**
+ * Scan dropped messages for successful Skill tool invocations and merge them over the previous
+ * compaction's retained set. Returns the UNBUDGETED merged list, most recent invocation FIRST.
+ *
+ * - `prevRetained` (the prior compaction's `details.invokedSkills`, newest-first) seeds the set:
+ *   every prior entry is older than anything scanned here, and a re-invocation refreshes both the
+ *   content and the recency rank (delete-then-set Map insertion order).
+ * - Only NON-error Skill results count (an unknown-skill error result carries no skill body).
+ * - The skill NAME comes from the paired assistant toolCall's arguments (`skill`, legacy `name`);
+ *   the result message alone only knows the tool name.
+ */
 export declare function extractInvokedSkills(droppedMessages: AgentMessage[], prevRetained: InvokedSkillRetention[] | undefined): InvokedSkillRetention[];
+/** Apply the CC-shaped retention budget to a newest-first invoked-skill list: per-skill truncation
+ *  (marker-inclusive), then the total budget with SKIP-not-break semantics for over-budget entries.
+ *
+ *  `maxTotalChars` (window-aware clamp): the CC-shaped 20k/100k caps are UPPER BOUNDS tuned for
+ *  ≥100k-token windows, not guarantees — on a small-window model an area that big would push
+ *  「summary + retention + kept tail」 past the window on every post-compaction request. A caller
+ *  that knows the consuming model's window passes its remaining chars headroom here; the effective
+ *  total budget is `min(100k, maxTotalChars)`, and the per-skill cap shrinks to the effective
+ *  total so the MOST RECENT skill is truncated-to-fit rather than skipped whole (skip-whole is the
+ *  right CC semantics between skills, but under a window clamp it would drop the newest skill in
+ *  favor of an older smaller one). A budget too small to hold even the truncation marker retains
+ *  nothing. Absent ⇒ the plain CC-shaped budget. */
 export declare function budgetInvokedSkillsRetention(newestFirst: InvokedSkillRetention[], maxTotalChars?: number): InvokedSkillRetention[];
+/**
+ * Replace the bodies of successful Skill tool results with a bounded placeholder before the
+ * summarizer sees them. Extraction copies those bodies into the retained invoked-skills area, so
+ * leaving the originals in the summarization input would (a) double-charge the window budget and
+ * (b) let multi-thousand-char skill texts crowd real conversation out of the summary input clamp.
+ * The toolResult MESSAGE stays (shallow-copied, same toolCallId/toolName) so the call/result
+ * pairing stays legal for serialization; only its content is swapped for a short note. `groups`
+ * lets a split-turn boundary pass both legs at once so the call→name pairing map spans them.
+ * `retainedNames` keeps the placeholder honest: a skill the retention budget skipped is disclosed
+ * as omitted, not claimed preserved. Non-matching messages pass through by reference.
+ */
 export declare function replaceInvokedSkillBodiesForSummary(groups: AgentMessage[][], retainedNames: ReadonlySet<string>): AgentMessage[][];
+/** Defensive reader for persisted `CompactionDetails.invokedSkills` (details is `unknown` on the
+ *  wire; sessions persisted before this field existed simply yield an empty list). */
 export declare function readRetainedInvokedSkills(details: unknown): InvokedSkillRetention[];
+/** Render the retained invoked-skills area appended to the compaction summary MESSAGE at context
+ *  build time (never baked into the persisted summary string — see the module note above). */
 export declare function renderInvokedSkillsRetention(skills: InvokedSkillRetention[]): string;
+/** Bound on the retained ref list — write-side cap AND the import door's ceiling (import-validate
+ *  bounds against the producer's own constant so the two never drift). The list is oldest-first
+ *  (carry-forward seed, then this range's refs); over the cap the OLDEST refs are dropped — the
+ *  newest elisions are the likeliest to be paged back. */
 export declare const PERSISTED_OUTPUT_REFS_MAX_ENTRIES = 50;
+/** Collect `<persisted-output ref="…">` handles from tool results in `messages` into `into`
+ *  (insertion-ordered Set = first appearance order; duplicates collapse). */
 export declare function extractPersistedOutputRefs(messages: AgentMessage[], into: Set<string>): void;
+/** Defensive reader for persisted `CompactionDetails.elidedMessages` (RB-398-b①): a non-negative
+ *  safe integer, else absent (pre-field sessions / foreign shapes yield undefined ⇒ no wrapper
+ *  disclosure — the byte-identical legacy render). */
 export declare function readElidedMessages(details: unknown): number | undefined;
+/** Defensive reader for persisted `CompactionDetails.activeTools` (RB-402, blackboard [2132]③c/
+ *  [2133]): the ToolSearch activation snapshot each landed compaction restates. details is
+ *  `unknown` on the wire — pre-field sessions and foreign shapes yield an empty list; non-string/
+ *  empty members are dropped (the consumer additionally intersects with the current leg's deferred
+ *  registry, so an unknown name is inert either way). */
 export declare function readCompactionActiveTools(details: unknown): string[];
+/** Defensive reader for persisted `CompactionDetails.persistedOutputRefs` (details is `unknown` on
+ *  the wire; sessions persisted before this field existed simply yield an empty list). */
 export declare function readPersistedOutputRefs(details: unknown): string[];
+/** Render the retained handles as a summary footer section — the deterministic counterpart of the
+ *  `clearStaleToolResults` marker's "full text persisted; call ReadToolResult with ref …" note.
+ *  Empty list ⇒ empty string (pre-existing summaries stay byte-identical). */
 export declare function formatPersistedOutputRefs(refs: string[]): string;
+/**
+ * Compute the file lists from accumulated operations: the display lists stay SORTED (stable
+ * summary-tag output), `modifiedFilesByRecency` carries the same modified set most-recent-FIRST
+ * for consumers that pick a top-N (working-file attachments).
+ */
 export declare function computeFileLists(fileOps: FileOperations): {
     readFiles: string[];
     modifiedFiles: string[];
     modifiedFilesByRecency: string[];
 };
+/** Format file lists as summary metadata tags (each list capped at {@link FILE_LIST_MAX_ENTRIES}). */
 export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string;
+/**
+ * Inverse of {@link formatFileOperations}: strip a TRAILING file-ops footer block from a stored summary.
+ * Every summary persisted by `compact()` ends with this footer; when a prior summary is threaded verbatim
+ * as the history of a later split-turn compaction (bug-hunt #1), the canonical superset footer is
+ * re-appended — so the stale embedded one must be removed first to avoid a duplicate. Anchored at end-of-
+ * string, so a `<read-files>`/`<modified-files>` string that legitimately appears mid-body is untouched.
+ */
 export declare function stripFileOperationsFooter(summary: string): string;
+/** Serialize LLM messages to plain text for summarization prompts. */
 export declare function serializeConversation(messages: Message[]): string;

package/dist/engine/execution-env/kill-tree.d.ts

@@ -4,8 +4,37 @@ export type KillProcessTreeOptions = {
     graceMs?: number;
     detached?: boolean;
     force?: boolean;
+    /**
+     * 1.296 件2 — identity anchor for the graceful SIGKILL escalation. A pid is a NAME, not an
+     * identity: when the original process (group) exits within the grace window and the OS re-uses
+     * the pid (small pid_max containers + fork-heavy build workloads make the window real), the
+     * pid-liveness recheck reads the STRANGER as "still alive" and the SIGKILL lands on an unrelated
+     * process. When provided, the escalation leg consults this callback FIRST — it must return true
+     * only while the ORIGINAL process is known not to have exited (e.g. a retained ChildProcess
+     * handle with `exitCode === null && signalCode === null`); the pid probe remains only an
+     * auxiliary check. Absent ⇒ the pre-existing pid-only behavior (callers without a process handle).
+     *
+     * codex R2 (1.296.1) — `false` cancels the DIRECT-pid escalation (that is where pid-reuse risk
+     * lives), but on the group-kill lane it no longer cancels the GROUP leg: the anchor only knows
+     * the LEADER — a detached shell that honors SIGTERM and exits while its TERM-ignoring descendants
+     * (run89's build workers) keep the group alive. While ANY original member lives, POSIX reserves
+     * the pgid for this group, so a group-scoped SIGKILL cannot land on a stranger; the group leg
+     * therefore probes group liveness and fires group-only. (Residual window — the WHOLE group died
+     * AND the pid was recycled as a NEW group leader inside the grace window — is the same one every
+     * `kill -- -PGID` accepts, documented not closed.)
+     */
     stillRunning?: () => boolean;
 };
+/**
+ * Best-effort process-tree termination with graceful shutdown.
+ * - Windows: use taskkill /T to include descendants. Sends SIGTERM-equivalent
+ *   first (without /F), then force-kills if process survives.
+ * - Unix: send SIGTERM to process group first, wait grace period, then SIGKILL.
+ *
+ * When the child was spawned with `detached: false`, pass `detached: false` to
+ * skip the Unix `process.kill(-pid, ...)` group-kill. That avoids signaling the
+ * gateway's own process group.
+ */
 export declare function killProcessTree(pid: number, opts?: KillProcessTreeOptions): void;
 export declare function signalProcessTree(pid: number, signal: "SIGTERM" | "SIGKILL", opts?: {
     detached?: boolean;