comisai 1.0.42 → 1.0.44

package/node_modules/@comis/agent/dist/context-engine/lcd-leaf-summarizer.js

@@ -0,0 +1,503 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: wrapSummarizerWithFailover (SUM-03) re-throws the last provider error after the fallback list is exhausted (lcd-leaf-summarizer.ts:746); consumed by the summarizer-spend-breaker safety boundary (packages/agent/src/safety/summarizer-spend-breaker.ts), which catches the throw and records EXACTLY ONE per-tenant breaker failure — the existing summarizer-failure contract (a throw is how a summarization failure is signalled to the breaker).
+/**
+ * LCD leaf summarization unit (Phase 129, C1).
+ *
+ * Two pure-ish responsibilities, both proven by a STUB summarizer (no network):
+ *
+ *  1. {@link selectLeafChunk} — pick the OLDEST contiguous chunk OUTSIDE the
+ *     fresh tail, capped at `leafChunkTokens`, then extend the boundary forward
+ *     to a STEP boundary (never end on an assistant `tool_use` without its
+ *     trailing `toolResult`s — the pair-safe walk mirrors
+ *     `extendHeadForPairSafety` in `llm-compaction.ts`). Returns `undefined`
+ *     when no evictable history exists outside the fresh tail (the pass is a
+ *     no-op).
+ *
+ *  2. {@link summarizeLeafChunk} — run the mandatory 3-level escalation
+ *     (normal → aggressive → deterministic truncation) that ALWAYS reduces
+ *     tokens or falls back deterministically. The structural model is
+ *     `compactWithFallback` (`llm-compaction.ts:545-607`), but C1 ADDS a
+ *     per-level token-reduction assertion (LOSSLESS-CLAW §5: "If output > input,
+ *     retry aggressive then truncate") and a BOUNDED Level-3 output (a count-only
+ *     note prefixed with `LEAF_FALLBACK_SUMMARY_MARKER`, capped at
+ *     `LEAF_FALLBACK_TARGET_TOKENS`) — the guaranteed-shrink terminator. The
+ *     ladder is FINITE (Level 1 ≤ 1+COMPACTION_MAX_RETRIES attempts → Level 2 one
+ *     attempt → Level 3 deterministic); it never loops without a floor.
+ *
+ * The LLM summarizer is INJECTED as ONE function ({@link LeafSummarizer}) so
+ * Phase 132 can wrap it with spend governance / a circuit breaker by swapping a
+ * single seam (the binding constraint; the Security DoS row T-129-08). 129 calls
+ * it inline and non-fatally: an error at Levels 1+2 is caught (WARN, errorKind
+ * `dependency`) and the pass falls through to the deterministic Level 3 — it
+ * NEVER throws out of the pass.
+ *
+ * Architecture cut (agent↛memory): this file imports ONLY the agent-side token
+ * estimators + the escalation constants; it NEVER imports `@comis/memory`. It
+ * also NEVER logs `chunkMessages` content or the summary `content` — ids, counts,
+ * level, and durations only (AGENTS.md §2.2; T-129-10). It reads NO wall clock of
+ * its own — the leaf time-range (`earliestAt`/`latestAt`) is derived purely from
+ * the injected `LeafChunkItem.createdAt` values, so there is no globals-gate
+ * surface here (the caller's injected clock stamps timestamps upstream).
+ *
+ * @module
+ */
+import { generateSummary } from "@earendil-works/pi-coding-agent";
+import { buildDepthAwareInstructions } from "./summarize-prompt-style.js";
+import { COMPACTION_MAX_RETRIES, OVERSIZED_MESSAGE_CHARS_THRESHOLD, LEAF_FALLBACK_TARGET_TOKENS, LEAF_FALLBACK_SUMMARY_MARKER, } from "./constants.js";
+import { estimateMessageTokens, estimateMessageChars, CHARS_PER_TOKEN, } from "../safety/token-estimator.js";
+// ---------------------------------------------------------------------------
+// Public constants
+// ---------------------------------------------------------------------------
+/**
+ * The smallest chunk (in tokens) a leaf pass can usefully summarize. The
+ * deterministic Level-3 floor must end up STRICTLY smaller than the chunk with
+ * NON-EMPTY content; the smallest non-empty summary is 1 token
+ * (`estimateMessageTokens` of a 1–4-char user string), so a chunk must be ≥ 2
+ * tokens for any non-empty summary to be strictly smaller. A 1-token chunk is
+ * already trivially tiny — there is nothing to gain — so the caller skips the
+ * pass entirely (WR-01) rather than emitting a degenerate empty/larger fallback.
+ */
+export const MIN_SHRINKABLE_LEAF_CHUNK_TOKENS = 2;
+/**
+ * B-4 (260605-ney): the fraction of a chunk's rendered shrink ceiling used as the
+ * EFFECTIVE summarize target. The configured `reserveTokens` (= `leafTargetTokens`
+ * / `condensedTargetTokens`) can EXCEED a small chunk — telling the model to write
+ * a summary larger than what it compresses → a guaranteed non-reduction → the
+ * spurious deterministic floor seen live (`escalationLevel:3` on a 3-message
+ * chunk). Bounding the target at half the chunk's rendered ceiling guarantees the
+ * ask is to at least halve the chunk, so a real summary can reduce. A fixed sub-1
+ * fraction; only bites when the configured target would otherwise exceed half the
+ * chunk (large chunks are still capped from above by the configured target).
+ */
+export const SHRINK_TARGET_FRACTION = 0.5;
+/**
+ * Compute the self-consistent shrink bounds for a chunk (B-4, 260605-ney). Shared
+ * by {@link summarizeLeafChunk} and `summarizeCondensedChunk` (the rule of three
+ * is met — both summarizers need the identical bounding).
+ *
+ * Two outputs, both derived from the chunk's RENDERED character count:
+ *
+ *  - `shrinkCeilingTokens` — the accept-test ceiling, measured the SAME way the
+ *    candidate summary is (`estimateMessageTokens` of a user string = 4:1 prose):
+ *    `ceil(renderedChars / CHARS_PER_TOKEN)`. The prior code compared a 4:1-prose
+ *    candidate against the chunk's MIXED-ratio STORED `tokenCount` (3:1 structured
+ *    / 4:1 text) — inconsistent units. This makes the comparison like-for-like.
+ *    NOTE: the STORED Σ `tokenCount` remains the BUDGET / before-size / floor
+ *    authority everywhere else (utilization, eviction, the deterministic Level-3
+ *    note + its strict ceiling) — only the accept-test ceiling moves here.
+ *
+ *  - `effectiveReserveTokens` — the bounded summarize target:
+ *    `min(configuredReserveTokens, max(1, floor(shrinkCeilingTokens *
+ *    SHRINK_TARGET_FRACTION)))`. Never zero (a 1-token floor); never above the
+ *    configured target (large chunks are unaffected).
+ *
+ * @param renderedChars - Σ `estimateMessageChars` over the chunk's messages (leaf)
+ *   or `estimateMessageChars` of the one concatenated pseudo-message (condense).
+ * @param configuredReserveTokens - the configured target (`reserveTokens`).
+ * @returns the rendered-4:1 accept ceiling + the bounded effective target.
+ */
+export function computeShrinkBounds(renderedChars, configuredReserveTokens) {
+    // flat-by-design: shrink-ceiling convergence bound over aggregate renderedChars (correctness comes from the shrink loop, see docstring) (TOK-01)
+    const shrinkCeilingTokens = Math.ceil(renderedChars / CHARS_PER_TOKEN);
+    const effectiveReserveTokens = Math.min(configuredReserveTokens, Math.max(1, Math.floor(shrinkCeilingTokens * SHRINK_TARGET_FRACTION)));
+    return { shrinkCeilingTokens, effectiveReserveTokens };
+}
+// ---------------------------------------------------------------------------
+// Chunk selection
+// ---------------------------------------------------------------------------
+/**
+ * Select the OLDEST contiguous chunk OUTSIDE the fresh tail, capped at
+ * `leafChunkTokens` and extended forward to a STEP boundary so it never ends on
+ * an assistant `tool_use` without its trailing `toolResult`s.
+ *
+ * The fresh-tail boundary is the index of the Nth-from-last assistant message
+ * (a STEP = one assistant + the tool results it triggered — mirrors
+ * `freshTailBoundaryIndex` in `lcd-assembler.ts`); everything before it is
+ * evictable history. The chunk greedily accumulates the oldest evictable
+ * messages up to the cap, then walks forward past a trailing assistant
+ * `tool_use` and its `toolResult`s (never crossing the fresh-tail boundary).
+ *
+ * S4: if `pinnedMessageIds` is provided, chunks containing ANY pinned message
+ * are skipped entirely — pinned messages are NEVER selected as eviction candidates.
+ *
+ * @param history - the evictable history items (seq order, oldest first)
+ * @param freshTailSteps - the number of trailing STEPS protected from eviction
+ * @param leafChunkTokens - the chunk token cap
+ * @param pinnedMessageIds - S4: message ids that must never be selected for eviction
+ * @returns the selected chunk, or `undefined` when nothing is evictable
+ */
+export function selectLeafChunk(history, freshTailSteps, leafChunkTokens, pinnedMessageIds) {
+    if (history.length === 0)
+        return undefined;
+    // S4: build a version of history that excludes pinned messages from the selectable set.
+    // Pinned messages are moved to "protected" — they remain in the store but cannot be
+    // selected as eviction candidates. If ALL messages are pinned, return undefined.
+    const evictableHistory = pinnedMessageIds && pinnedMessageIds.size > 0
+        ? history.filter((it) => !pinnedMessageIds.has(it.id))
+        : history;
+    if (evictableHistory.length === 0)
+        return undefined;
+    // The fresh-tail boundary within `evictableHistory`: everything at index >= this is
+    // protected. Counting assistant messages from the end mirrors
+    // freshTailBoundaryIndex (a STEP = an assistant + its trailing results).
+    const tailStart = freshTailBoundaryIndexOf(evictableHistory, freshTailSteps);
+    if (tailStart <= 0)
+        return undefined; // nothing outside the fresh tail — no-op.
+    // Greedily take the oldest contiguous prefix up to the cap. Always include at
+    // least one message (so a single oversized message still gets summarized).
+    let endIndex = 0;
+    let tokens = 0;
+    while (endIndex < tailStart) {
+        const next = evictableHistory[endIndex].tokens;
+        if (endIndex > 0 && tokens + next > leafChunkTokens)
+            break;
+        tokens += next;
+        endIndex++;
+    }
+    // Extend forward past a trailing assistant `tool_use` to its `toolResult`s so
+    // the boundary never lands mid-pair — but never cross the fresh-tail boundary.
+    endIndex = extendForPairSafety(evictableHistory, endIndex, tailStart);
+    const slice = evictableHistory.slice(0, endIndex);
+    const messages = slice.map((it) => it.msg);
+    const messageIds = slice.map((it) => it.id);
+    const createdAts = slice.map((it) => it.createdAt);
+    const summed = slice.reduce((acc, it) => acc + it.tokens, 0);
+    return {
+        startIndex: 0,
+        endIndex,
+        messages,
+        descendantCount: messages.length,
+        messageIds,
+        earliestAt: Math.min(...createdAts),
+        latestAt: Math.max(...createdAts),
+        tokens: summed,
+    };
+}
+/**
+ * The index in `history` where the fresh tail begins: the position of the Nth-
+ * from-last assistant message (mirrors `freshTailBoundaryIndex` in the
+ * assembler). Returns 0 when there are fewer than N assistant steps (everything
+ * is fresh tail → nothing evictable).
+ */
+function freshTailBoundaryIndexOf(history, freshTailSteps) {
+    let stepsSeen = 0;
+    for (let i = history.length - 1; i >= 0; i--) {
+        if (roleOf(history[i].msg) === "assistant") {
+            stepsSeen++;
+            if (stepsSeen === freshTailSteps)
+                return i;
+        }
+    }
+    return 0;
+}
+/**
+ * Walk the (exclusive) `endIndex` forward so the chunk never ends mid-pair.
+ *
+ * `endIndex` is exclusive, so the LAST INCLUDED message is `history[endIndex-1]`.
+ * When that message is an assistant carrying a `tool_use`, its `toolResult`s sit
+ * at `endIndex`, `endIndex+1`, … — pull them all in (and any further tool_use
+ * the included results chain into), bounded by `limit` (the fresh-tail boundary).
+ * Mirrors `extendHeadForPairSafety` in `llm-compaction.ts`, adapted to an
+ * exclusive end index.
+ */
+function extendForPairSafety(history, endIndex, limit) {
+    let extended = endIndex;
+    // Keep extending while the last INCLUDED message is an assistant tool_use whose
+    // results have not all been pulled in yet.
+    while (extended > 0 && extended < limit) {
+        const lastIncluded = history[extended - 1].msg;
+        if (roleOf(lastIncluded) === "assistant" && hasToolUse(lastIncluded)) {
+            // Pull every immediately-following toolResult into the chunk.
+            let advanced = false;
+            while (extended < limit && roleOf(history[extended].msg) === "toolResult") {
+                extended++;
+                advanced = true;
+            }
+            if (advanced)
+                continue; // re-check (the new last-included is a toolResult → loop exits).
+        }
+        break;
+    }
+    return extended;
+}
+/** True when an assistant message carries a `tool_use` / `toolCall` block. */
+function hasToolUse(msg) {
+    const content = msg.content;
+    if (!Array.isArray(content))
+        return false;
+    return content.some((block) => {
+        const type = block.type;
+        return type === "tool_use" || type === "toolCall";
+    });
+}
+/** Read a message's `role` without widening to the concrete pi-ai union. */
+function roleOf(m) {
+    return m.role;
+}
+// ---------------------------------------------------------------------------
+// 3-level escalation
+// ---------------------------------------------------------------------------
+/**
+ * Summarize a leaf chunk via the mandatory 3-level escalation. ALWAYS returns a
+ * summary whose token count is STRICTLY LESS than the chunk's token count (the
+ * C1 invariant) — accepting an LLM summary only when it actually reduces, and
+ * otherwise falling through to the deterministic, bounded Level-3 truncation.
+ *
+ * B-4 (260605-ney): the EFFECTIVE summarize target is bounded below the chunk's
+ * rendered shrink ceiling ({@link computeShrinkBounds}) so the model is never asked
+ * to write more than it compresses (the spurious-floor fix), and the accept-test
+ * ceiling is the RENDERED 4:1 measure — self-consistent with the candidate's units.
+ * The STORED Σ `tokenCount` stays the budget / floor authority: the deterministic
+ * Level-3 floor must still beat the real stored before-size.
+ *
+ * @param chunkItems - the chunk's items (pre-computed tokens + ids + timestamps)
+ * @param deps - the injected summarizer + model getters + logger
+ * @param opts - reserveTokens (= leafTargetTokens) + optional previousSummary
+ * @returns the leaf summary + escalation level + coverage metadata
+ */
+export async function summarizeLeafChunk(chunkItems, deps, opts) {
+    const messages = chunkItems.map((it) => it.msg);
+    const messageIds = chunkItems.map((it) => it.id);
+    const createdAts = chunkItems.map((it) => it.createdAt);
+    // Before-size authority: the caller's pre-computed per-message tokens (counts
+    // F3 thinking on store-sourced rows, which re-estimation would under-count).
+    // This stays the BUDGET / floor authority — the deterministic Level-3 floor must
+    // still beat the REAL stored before-size (NOT the smaller rendered ceiling).
+    const chunkTokens = chunkItems.reduce((acc, it) => acc + it.tokens, 0);
+    const earliestAt = createdAts.length > 0 ? Math.min(...createdAts) : 0;
+    const latestAt = createdAts.length > 0 ? Math.max(...createdAts) : 0;
+    // B-4: self-consistent shrink bounds from the chunk's RENDERED chars. The
+    // accept ceiling (`shrinkCeilingTokens`) is measured the SAME way the candidate
+    // summary is (4:1 prose); the EFFECTIVE target is bounded below the chunk so the
+    // summarizer is never asked to write more than it compresses (the dominant fix).
+    const renderedChars = messages.reduce((acc, m) => acc + estimateMessageChars(m), 0);
+    const { shrinkCeilingTokens, effectiveReserveTokens } = computeShrinkBounds(renderedChars, opts.reserveTokens);
+    const base = {
+        descendantCount: chunkItems.length,
+        messageIds,
+        earliestAt,
+        latestAt,
+    };
+    // --- Level 1: full summarization, up to 1 + COMPACTION_MAX_RETRIES attempts.
+    //     Accept ONLY when the summary is strictly smaller than the rendered-4:1
+    //     ceiling (self-consistent units), with the EFFECTIVE bounded target.
+    const maxAttempts = 1 + COMPACTION_MAX_RETRIES;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const accepted = await tryLevel(deps, messages, {
+            reserveTokens: effectiveReserveTokens,
+            previousSummary: opts.previousSummary,
+        }, shrinkCeilingTokens, attempt);
+        if (accepted !== undefined) {
+            return { ...base, content: accepted.content, level: 1, fallback: false, tokenCount: accepted.tokenCount };
+        }
+    }
+    // --- Level 2: aggressive — one best-effort retry. Prefer the oversized-filtered
+    //     set (dropping huge messages often lets the model reduce), but when EVERY
+    //     message is oversized the filter empties the set; rather than skip Level 2
+    //     and drop straight to the count-only floor (WR-03), make the one aggressive
+    //     attempt on the FULL (unfiltered) set. An aggressive LLM summary — even of
+    //     large inputs — is strictly better context than the deterministic floor,
+    //     and continuity (`previousSummary`) is forwarded either way.
+    const filtered = messages.filter((m) => estimateMessageChars(m) < OVERSIZED_MESSAGE_CHARS_THRESHOLD);
+    const level2Messages = filtered.length > 0 ? filtered : messages;
+    if (level2Messages.length > 0) {
+        deps.logger.debug({
+            step: "lcd-leaf-escalate",
+            level: 2,
+            descendantCount: chunkItems.length,
+            oversizedFilterEmptied: filtered.length === 0,
+            hint: filtered.length === 0
+                ? "level-1 summary did not reduce and every message is oversized; retrying aggressive on the full set"
+                : "level-1 summary did not reduce; retrying aggressive (oversized-filtered)",
+        }, "lcd leaf escalation");
+        const accepted = await tryLevel(deps, level2Messages, {
+            reserveTokens: effectiveReserveTokens,
+            previousSummary: opts.previousSummary,
+            aggressive: true,
+        }, shrinkCeilingTokens, maxAttempts);
+        if (accepted !== undefined) {
+            return { ...base, content: accepted.content, level: 2, fallback: false, tokenCount: accepted.tokenCount };
+        }
+    }
+    // --- Level 3: deterministic bounded truncation (the guaranteed terminator).
+    const content = buildDeterministicFallback(chunkItems.length, chunkTokens);
+    const tokenCount = estimateMessageTokens({ role: "user", content });
+    deps.logger.debug({
+        step: "lcd-leaf-escalate",
+        level: 3,
+        descendantCount: chunkItems.length,
+        fallback: true,
+        hint: "both LLM levels failed to reduce; using deterministic bounded truncation",
+    }, "lcd leaf escalation");
+    return { ...base, content, level: 3, fallback: true, tokenCount };
+}
+/**
+ * Attempt one summarizer call and accept it ONLY when the produced summary is
+ * strictly smaller (in tokens) than `shrinkCeilingTokens` — the chunk's RENDERED
+ * 4:1 measure (B-4, 260605-ney), so the candidate (a 4:1-prose user string) and
+ * the ceiling are like-for-like units. Non-fatal: a throwing summarizer is caught
+ * (WARN, errorKind `dependency`) and reported as "not accepted" so the ladder
+ * escalates rather than failing.
+ */
+async function tryLevel(deps, messages, opts, shrinkCeilingTokens, attempt) {
+    try {
+        const summary = await deps.summarize(messages, opts);
+        const tokenCount = estimateMessageTokens({ role: "user", content: summary });
+        if (tokenCount < shrinkCeilingTokens)
+            return { content: summary, tokenCount };
+        // Non-reduction → escalate (LOSSLESS-CLAW §5).
+        deps.logger.debug({
+            step: "lcd-leaf-escalate",
+            attempt,
+            hint: "summary not smaller than chunk; escalating",
+        }, "lcd leaf escalation");
+        return undefined;
+    }
+    catch (err) {
+        deps.logger.warn({
+            err,
+            attempt,
+            errorKind: "dependency",
+            hint: "leaf summarizer call failed; escalating to the next level",
+        }, "lcd leaf summarizer failed");
+        return undefined;
+    }
+}
+/**
+ * Build the deterministic Level-3 leaf summary: a count-only note prefixed with
+ * `LEAF_FALLBACK_SUMMARY_MARKER`, bounded strictly below BOTH the chunk it
+ * replaces AND `LEAF_FALLBACK_TARGET_TOKENS`. This is the guaranteed terminator —
+ * it NEVER exceeds the chunk and NEVER calls an LLM.
+ *
+ * The bound is the token ESTIMATOR ITSELF, not a hand-derived chars-per-token
+ * ceiling (WR-01 / IN-03): the prior code clamped chars with `CHARS_PER_TOKEN_RATIO`
+ * (3.5) while the result is measured by `estimateMessageTokens` (4:1 for a
+ * user-role string), and a `Math.max(MARKER.length, …)` floor overrode the clamp
+ * for tiny chunks — so a 3-token chunk produced a 19-char marker = 5 tokens,
+ * LARGER than the chunk. Truncating the note in a loop that re-measures with the
+ * estimator until it is strictly below the chunk removes both the 3.5-vs-4
+ * mismatch and the marker-floor overshoot. The marker survives intact for any
+ * normal-size chunk; only a sub-marker chunk truncates it (and a chunk too small
+ * to ever shrink with non-empty content is skipped by the {@link summarizeLeafChunk}
+ * caller before this is reached, so `maxTokens` here is always ≥ 1).
+ *
+ * @param messageCount - number of chunk messages (recorded in the note)
+ * @param chunkTokens - the chunk's token count (the strict ceiling to beat)
+ * @returns a bounded, marker-prefixed summary string strictly smaller than the chunk
+ */
+function buildDeterministicFallback(messageCount, chunkTokens) {
+    const note = `${LEAF_FALLBACK_SUMMARY_MARKER} ${messageCount} earlier messages ` +
+        `(~${chunkTokens} tokens) were truncated without an LLM summary; ` +
+        `their content is preserved losslessly in the message store.`;
+    // The strict ceiling: strictly below the chunk AND at/below the fallback
+    // target. The chunk-too-small-to-shrink case (maxTokens < 1) is guarded by the
+    // caller; clamp defensively so this never returns a non-shrinking note.
+    const maxTokens = Math.min(chunkTokens - 1, LEAF_FALLBACK_TARGET_TOKENS);
+    if (maxTokens < 1)
+        return ""; // unreachable in practice (caller guards); empty is strictly smaller.
+    // Measure with the SAME estimator the result is judged by (a user-role string).
+    const tokensOf = (content) => estimateMessageTokens({ role: "user", content });
+    if (tokensOf(note) <= maxTokens)
+        return note;
+    // Truncate keeping the marker at the head, re-measuring with the estimator each
+    // step (the estimator is the bound, not a fixed ratio). estimateMessageTokens is
+    // monotonic in a user string's length, so stepping the length down by the
+    // over-by amount (≥1 char) converges in a handful of iterations and terminates
+    // at worst at the empty string.
+    let len = note.length;
+    while (len > 0 && tokensOf(note.slice(0, len)) > maxTokens) {
+        const over = tokensOf(note.slice(0, len)) - maxTokens;
+        // CHARS_PER_TOKEN (4) is only a convergence STEP here — correctness comes from
+        // re-measuring tokensOf in the loop condition, not from this multiplier.
+        len = Math.max(0, len - Math.max(1, over * 4));
+    }
+    return note.slice(0, len);
+}
+// ---------------------------------------------------------------------------
+// Production summarizer (the SDK generateSummary seam)
+// ---------------------------------------------------------------------------
+/**
+ * Construct the PRODUCTION {@link LeafSummarizer} — the seam that wraps the SDK
+ * `generateSummary`. Phase 132 swaps THIS factory's output for a spend-governed /
+ * circuit-broken variant; 129 calls `generateSummary` directly. The override
+ * model + key are used when {@link LeafSummarizerDeps.overrideModel} is present
+ * (a cheaper compaction model resolved by the operation-model chain), else the
+ * primary REAL model (`getRealModel`) + `getApiKey` (B-5 — a real pi-ai
+ * `Model<any>`, never the 4-field snapshot). Mirrors `compactWithFallback`'s call shape
+ * (`llm-compaction.ts:561`); the 8th param threads `previousSummary` for
+ * continuity. The function may return a too-large string — the escalation ladder
+ * in {@link summarizeLeafChunk} re-checks size and escalates.
+ *
+ * @param deps - the model getters + optional override (the logger is unused here;
+ *   the ladder owns the WARN on a throw — this factory just performs the call).
+ * @returns a LeafSummarizer bound to the resolved model + key.
+ */
+export function buildLeafSummarizeFn(deps) {
+    return async (messages, opts) => {
+        // B-5: resolve a REAL Model<any> for generateSummary — prefer the cheaper
+        // override's real Model when the operation chain picked one (parity with
+        // getCompactionDeps), else the PRIMARY real model (the executor-resolved
+        // `resolvedModel`, threaded via deps.getRealModel). The bare 4-field
+        // CompactionModelSnapshot is NEVER passed to generateSummary — it lacks the
+        // provider-client runtime the SDK invokes and throws at call time.
+        const model = deps.overrideModel?.model ?? deps.getRealModel();
+        const apiKey = deps.overrideModel
+            ? await deps.overrideModel.getApiKey()
+            : await deps.getApiKey();
+        const instructions = buildDepthAwareInstructions(opts.depth ?? 0, opts.aggressive ?? false);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK generateSummary takes an opaque Model<any>
+        return generateSummary(messages, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        model, opts.reserveTokens, apiKey, undefined, // headers
+        undefined, // signal
+        instructions, opts.previousSummary);
+    };
+}
+/**
+ * SUM-03: wraps a primary {@link LeafSummarizer} with an ordered fallback list.
+ *
+ * On primary failure, tries each fallback in sequence (ordered by the caller's
+ * `fallbacks` array). Only when ALL providers in the list are exhausted does the
+ * wrapper throw the last error — so the per-tenant circuit breaker that wraps the
+ * OUTER spend-governed seam records exactly ONE failure per exhausted-list event
+ * (Pitfall 4 in 171-RESEARCH: throw-last, not throw-per-provider).
+ *
+ * Content-free: logs `providerIndex`, `totalProviders`, and `errorKind: "dependency"`
+ * only — NEVER message content, summary text, or provider credentials (T-171-09).
+ *
+ * @param primary - the primary LeafSummarizer (already spend-governed by the outer seam)
+ * @param fallbacks - ordered list of fallback LeafSummarizer callables
+ * @param logger - structured logger (content-free)
+ * @returns a LeafSummarizer that transparently tries all providers in order
+ */
+export function wrapSummarizerWithFailover(primary, fallbacks, logger) {
+    // Fast path: empty fallback list = zero behavior change (default []).
+    if (fallbacks.length === 0)
+        return primary;
+    return async (messages, opts) => {
+        let lastError;
+        const all = [primary, ...fallbacks];
+        for (let i = 0; i < all.length; i++) {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                return await all[i](messages, opts);
+            }
+            catch (err) {
+                lastError = err;
+                // Emit a content-free WARN for every failure — including the last one so
+                // the operator can see the full exhaustion trace. The outer breaker records
+                // a single failure after the throw below.
+                logger.warn({
+                    errorKind: "dependency",
+                    step: "summarizer-failover",
+                    providerIndex: i,
+                    totalProviders: all.length,
+                    hint: i < all.length - 1
+                        ? `Summarizer provider ${i} failed; trying next in fallback list`
+                        : `Summarizer provider ${i} failed; all ${all.length} providers exhausted`,
+                }, `Summarizer failover: provider ${i} failed`);
+            }
+        }
+        throw lastError;
+    };
+}

package/node_modules/@comis/agent/dist/context-engine/lcd-preflight.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pre-flight fit check for the LCD dag assembler (Phase 166 CWF-02).
+ *
+ * Enforces the invariant: assembledInputTokens ≤ effectiveWindow − outputHeadroom.
+ * Security-pinned messages (T-S4) are NEVER evicted in the harder-eviction pass.
+ *
+ * Escalation ladder:
+ *  (a) Evict harder with security-pinned messages excluded.
+ *  (c) Down-shift thinkingLevel via downshiftThinkingLevel() when reasoningStyle="native".
+ *  (d) Throw ContextExhaustionError when infeasible even at the floor level.
+ *
+ * Separated from lcd-assembler.ts to keep that file ≤ 820 lines.
+ *
+ * Root-cause context-exhaustion guard (2026-06-22): the NON-EVICTABLE fixed
+ * overhead S (system prompt + tool schemas) is the dominant term on small
+ * windows. The window-aware tool-budget fit pass (executor-tool-assembly.ts
+ * `enforceToolBudgetFit`) defers tools so S fits BEFORE this pre-flight runs,
+ * which keeps a `nano`-class model (~16K window) from throwing on every turn. The
+ * only residual infeasible case is window < system-prompt-alone — genuinely
+ * unusable. This pass throws `fixed_overhead_exceeds_window` there (honest), and
+ * the degraded reply names the window / tool footprint / a larger model — never
+ * the misleading "your message is too big".
+ *
+ * TODO(2026-Q3): a minimal-system-prompt fallback (drop verbose bootstrap/tooling
+ * guidance, keep identity + essential behavior) would let the agent still reply
+ * on a window < full-prompt. Deferred: it is deeply invasive in the 1954-line
+ * prompt-assembly.ts (per-session bootstrap snapshot + once-per-session
+ * systemPromptOverride). Tracked against the codex nano-window context-exhaustion
+ * incident. Until then the degenerate case fails honestly (above).
+ *
+ * @module
+ */
+import { type BudgetItem } from "./lcd-budget-eviction.js";
+import type { ContextEngineDeps, ContextWindowCapInfo } from "./types.js";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+/**
+ * Run the CWF-02 pre-flight fit check.
+ *
+ * @param deps              - ContextEngineDeps (reads securityPinMarkers, callbacks, logger).
+ * @param effectiveWindow   - budget.windowTokens for this turn.
+ * @param evictable         - The full BudgetItem evictable array (before any pre-flight eviction).
+ *                            Used to compute kept-token sums because evictHistoryUnderBudget
+ *                            returns AgentMessage[] (strips token metadata).
+ * @param keptCount         - Number of BudgetItems kept by the normal budget eviction pass.
+ *                            The NEWEST keptCount items from evictable were kept.
+ * @param freshTail         - The unconditional fresh-tail messages.
+ * @param reasoningStyle    - profile.reasoningStyle ("none" | "native").
+ * @param capInfo           - W1 cap provenance (budget.rawContextWindowTokens +
+ *                            budget.windowCapSource). When the effective window was
+ *                            clamped by a capability-class cap, the exhaustion throw
+ *                            and WARN name the raw window and the exact config knob.
+ *
+ * Throws ContextExhaustionError if infeasible even at the thinking-level floor.
+ * Emits onEffectiveWindow, onThinkingDownshifted, onAssembledInputTokens callbacks as side effects.
+ * Returns the ORIGINAL assembled input token count (CR-03 — what is actually
+ * dispatched) so the assembler's INFO line can log the budget equation (W5).
+ */
+export declare function runPreflightFitCheck(deps: ContextEngineDeps, effectiveWindow: number, evictable: BudgetItem[], keptCount: number, freshTail: AgentMessage[], reasoningStyle: "none" | "native", capInfo?: ContextWindowCapInfo): number;