agentfootprint 7.16.0 → 7.17.0

package/dist/esm/core/agent/window/strategies/summarizeOldest.js

@@ -0,0 +1,174 @@
+/**
+ * summarizeOldest — fold the oldest foldable turns into one summary message.
+ *
+ * Pattern: WindowStrategy implementation. Its own module, importing nothing
+ *          that registers anything, so a bundle that never mentions it never
+ *          carries it (and never carries the summarizer machinery either).
+ * Role:    core/ layer.
+ * Emits:   N/A — the stage emits, records and costs; this file decides.
+ *
+ * This is what `.compaction({...})` configures, and the market's familiar
+ * move (Claude Code / the Claude Agent SDK call it compaction). What is
+ * different here is not the fold — it is that the fold is filed as a claim:
+ * a summary is a claim ABOUT the past, and the past itself stays in the
+ * commit log, byte for byte.
+ *
+ * Everything it decides, it explains. Every engaged path returns a record —
+ * including the paths that change nothing, which are the ones a person
+ * debugging an over-budget window actually needs.
+ */
+import { CompactionUnmeasurableError } from '../errors.js';
+import { resolveCompactionOptions } from '../options.js';
+import { indexRange } from '../removal.js';
+import { buildSummaryMessage, isCompactedSummary, runSummarizer } from '../summarize.js';
+import { windowChars } from '../turns.js';
+/** `WindowRecord.strategy` written by every record this strategy files. */
+export const SUMMARIZE_OLDEST = 'summarize-oldest';
+/**
+ * Fold the oldest contiguous run of foldable turns into one summary message,
+ * keeping the recent turns and stepping over anything unresolved.
+ *
+ * Triggered by COUNTED tokens: the last call's adapter-reported input tokens
+ * against `thresholdTokens`. A provider that reports no usage gets
+ * `CompactionUnmeasurableError` rather than an invented number.
+ *
+ * @example
+ * ```ts
+ * import { Agent, summarizeOldest } from 'agentfootprint';
+ *
+ * const agent = Agent.create({ provider: anthropic(), model: 'claude-sonnet-4-5' })
+ *   .window(summarizeOldest({ thresholdTokens: 120_000, summarizer: anthropic() }))
+ *   .build();
+ * // `.compaction({ ... })` is this exact line, spelled shorter.
+ * ```
+ */
+export function summarizeOldest(options) {
+    const config = resolveCompactionOptions(options, 'summarizeOldest');
+    return {
+        name: SUMMARIZE_OLDEST,
+        async plan(input) {
+            const { history, turns, iteration, measured } = input;
+            // Iteration 1: nothing has been sent, so nothing has been counted. A
+            // compactor that acted here would be guessing.
+            if (measured === undefined)
+                return undefined;
+            if (measured.input === 0 && measured.output === 0) {
+                throw new CompactionUnmeasurableError(input.providerName);
+            }
+            if (measured.input <= config.thresholdTokens)
+                return undefined;
+            const model = config.model ?? input.agentModel;
+            const charsBefore = windowChars(history);
+            const base = {
+                strategy: SUMMARIZE_OLDEST,
+                iteration,
+                measuredTokens: measured.input,
+                thresholdTokens: config.thresholdTokens,
+                overBudget: true,
+                windowCharsBefore: charsBefore,
+            };
+            const unchanged = (refusals, extra = {}) => ({
+                record: {
+                    ...base,
+                    removedStageIds: [],
+                    removedMessageCount: 0,
+                    foldedStageIds: [],
+                    foldedMessageCount: 0,
+                    windowCharsAfter: charsBefore,
+                    summaryChars: 0,
+                    refusals,
+                    ...extra,
+                },
+                evictions: [],
+                budgetPressure: {
+                    capTokens: config.thresholdTokens,
+                    projectedTokens: measured.input,
+                    planAction: 'none',
+                },
+            });
+            const plan = input.planRemoval(config.keepRecentTurns, (turn) => isCompactedSummary(turn.messages[0]));
+            if (plan.from === -1) {
+                // Nothing foldable. The window stays over budget and the run proceeds
+                // — reported, not silently truncated.
+                return unchanged(plan.refusals);
+            }
+            const spanStart = turns[plan.from].start;
+            const spanEnd = turns[plan.to].start + turns[plan.to].length;
+            const head = history.slice(0, spanStart);
+            const span = history.slice(spanStart, spanEnd);
+            const tail = history.slice(spanEnd);
+            // A broken summarizer must not take down the run.
+            let summary;
+            try {
+                const result = await runSummarizer(config.summarizer, model, span, input.signal);
+                summary = {
+                    text: result.text,
+                    usage: { input: result.usage.input, output: result.usage.output },
+                };
+            }
+            catch (err) {
+                return {
+                    ...unchanged([
+                        { reason: 'summarizer-failed', turnIndex: plan.from, messageIndex: spanStart },
+                        ...plan.refusals,
+                    ]),
+                    warning: `the summarizer threw, so nothing was folded this iteration and the window ` +
+                        `stays over budget (${measured.input} tokens vs a threshold of ` +
+                        `${config.thresholdTokens}). The run continues. Cause: ` +
+                        `${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+            const summaryMessage = buildSummaryMessage(summary.text, {
+                foldedMessageCount: span.length,
+                iteration,
+                model,
+            });
+            const spend = { model, usage: summary.usage };
+            // Would the fold actually help? A summary plus its authored frame can be
+            // LONGER than a handful of short turns; folding then spends a call to
+            // grow the window and lose detail at the same time. Both sides are
+            // measured in chars — one unit, an exact comparison, not a token guess.
+            if (summaryMessage.content.length >= windowChars(span)) {
+                return {
+                    ...unchanged([
+                        { reason: 'summary-not-smaller', turnIndex: plan.from, messageIndex: spanStart },
+                        ...plan.refusals,
+                    ], { summaryChars: summaryMessage.content.length, summarizerTokens: summary.usage }),
+                    spend, // the call still happened, so it still counts
+                };
+            }
+            const foldedAtMs = input.now();
+            const facts = input.removalFacts(indexRange(spanStart, spanEnd), foldedAtMs);
+            const window = [...head, summaryMessage, ...tail];
+            const record = {
+                ...base,
+                removedStageIds: facts.removedStageIds,
+                removedMessageCount: span.length,
+                // The 7.16 names for the two values above, kept and deprecated.
+                foldedStageIds: facts.removedStageIds,
+                foldedMessageCount: span.length,
+                windowCharsAfter: windowChars(window),
+                summaryChars: summaryMessage.content.length,
+                summarizerTokens: summary.usage,
+                refusals: plan.refusals,
+            };
+            return {
+                window,
+                rebase: {
+                    headCount: head.length,
+                    keptTailCount: tail.length,
+                    insertedAtMs: foldedAtMs,
+                },
+                record,
+                evictions: facts.evictions,
+                budgetPressure: {
+                    capTokens: config.thresholdTokens,
+                    projectedTokens: measured.input,
+                    planAction: 'summarize',
+                },
+                spend,
+            };
+        },
+    };
+}
+//# sourceMappingURL=summarizeOldest.js.map

package/dist/esm/core/agent/window/strategies/summarizeOldest.js.map

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

package/dist/esm/core/agent/window/strategies/tokenBudget.d.ts

@@ -0,0 +1,47 @@
+/**
+ * tokenBudget — compaction's trigger discipline, without the summarizer.
+ *
+ * Pattern: WindowStrategy implementation. Its own module, registering
+ *          nothing at import.
+ * Role:    core/ layer.
+ * Emits:   N/A — the stage emits, records and costs; this file decides.
+ *
+ * The market's other familiar policy: cap the window at a token budget
+ * (Mastra's `TokenLimiter` is the closest sibling). What is different here is
+ * the same thing that is different about compaction — the number is COUNTED,
+ * never guessed:
+ *
+ *   • the trigger reads the input tokens the PROVIDER reported for the last
+ *     call, not a character estimate and not a divide-by-four heuristic;
+ *   • a provider that reports no usage gets `CompactionUnmeasurableError` by
+ *     name, the same refusal `.compaction()` makes, rather than an invented
+ *     window size or a configured budget that silently never applies.
+ *
+ * When over budget it drops the oldest contiguous removable span — the same
+ * span compaction would have folded, chosen by the same refusal engine — and
+ * writes no summary at all. Nothing is claimed about what left, because
+ * nothing was read: the record and the eviction events name it, and the
+ * commit log still has it verbatim.
+ *
+ * Use it over `summarizeOldest` when you would rather lose the old turns than
+ * pay a summarizer to paraphrase them, and over `slidingWindow` when the
+ * thing you are actually defending is a token bill rather than a turn depth.
+ */
+import type { WindowStrategy } from '../strategy.js';
+import type { TokenBudgetOptions } from '../types.js';
+/** `WindowRecord.strategy` written by every record this strategy files. */
+export declare const TOKEN_BUDGET = "token-budget";
+/**
+ * Drop the oldest turns whenever the last call's adapter-reported input
+ * tokens exceed `thresholdTokens`.
+ *
+ * @example
+ * ```ts
+ * import { Agent, tokenBudget } from 'agentfootprint';
+ *
+ * const agent = Agent.create({ provider: anthropic(), model: 'claude-sonnet-4-5' })
+ *   .window(tokenBudget({ thresholdTokens: 120_000 }))
+ *   .build();
+ * ```
+ */
+export declare function tokenBudget(options: TokenBudgetOptions): WindowStrategy;

package/dist/esm/core/agent/window/strategies/tokenBudget.js

@@ -0,0 +1,91 @@
+/**
+ * tokenBudget — compaction's trigger discipline, without the summarizer.
+ *
+ * Pattern: WindowStrategy implementation. Its own module, registering
+ *          nothing at import.
+ * Role:    core/ layer.
+ * Emits:   N/A — the stage emits, records and costs; this file decides.
+ *
+ * The market's other familiar policy: cap the window at a token budget
+ * (Mastra's `TokenLimiter` is the closest sibling). What is different here is
+ * the same thing that is different about compaction — the number is COUNTED,
+ * never guessed:
+ *
+ *   • the trigger reads the input tokens the PROVIDER reported for the last
+ *     call, not a character estimate and not a divide-by-four heuristic;
+ *   • a provider that reports no usage gets `CompactionUnmeasurableError` by
+ *     name, the same refusal `.compaction()` makes, rather than an invented
+ *     window size or a configured budget that silently never applies.
+ *
+ * When over budget it drops the oldest contiguous removable span — the same
+ * span compaction would have folded, chosen by the same refusal engine — and
+ * writes no summary at all. Nothing is claimed about what left, because
+ * nothing was read: the record and the eviction events name it, and the
+ * commit log still has it verbatim.
+ *
+ * Use it over `summarizeOldest` when you would rather lose the old turns than
+ * pay a summarizer to paraphrase them, and over `slidingWindow` when the
+ * thing you are actually defending is a token bill rather than a turn depth.
+ */
+import { dropOldestSpan } from './drop.js';
+import { CompactionUnmeasurableError } from '../errors.js';
+import { resolveTokenBudgetOptions } from '../options.js';
+/** `WindowRecord.strategy` written by every record this strategy files. */
+export const TOKEN_BUDGET = 'token-budget';
+/**
+ * Drop the oldest turns whenever the last call's adapter-reported input
+ * tokens exceed `thresholdTokens`.
+ *
+ * @example
+ * ```ts
+ * import { Agent, tokenBudget } from 'agentfootprint';
+ *
+ * const agent = Agent.create({ provider: anthropic(), model: 'claude-sonnet-4-5' })
+ *   .window(tokenBudget({ thresholdTokens: 120_000 }))
+ *   .build();
+ * ```
+ */
+export function tokenBudget(options) {
+    const config = resolveTokenBudgetOptions(options, 'tokenBudget');
+    return {
+        name: TOKEN_BUDGET,
+        async plan(input) {
+            const { measured } = input;
+            // Iteration 1: nothing has been sent, so nothing has been counted.
+            if (measured === undefined)
+                return undefined;
+            // Counted, not guessed — the same wall compaction hits, by the same name.
+            if (measured.input === 0 && measured.output === 0) {
+                throw new CompactionUnmeasurableError(input.providerName);
+            }
+            if (measured.input <= config.thresholdTokens)
+                return undefined;
+            const outcome = dropOldestSpan(input, config.keepRecentTurns, TOKEN_BUDGET);
+            const record = {
+                strategy: TOKEN_BUDGET,
+                iteration: input.iteration,
+                measuredTokens: measured.input,
+                thresholdTokens: config.thresholdTokens,
+                overBudget: true,
+                keepRecentTurns: config.keepRecentTurns,
+                removedStageIds: outcome.removedStageIds,
+                removedMessageCount: outcome.removedMessageCount,
+                windowCharsBefore: outcome.windowCharsBefore,
+                windowCharsAfter: outcome.windowCharsAfter,
+                refusals: outcome.refusals,
+            };
+            return {
+                ...(outcome.window !== undefined && { window: outcome.window }),
+                ...(outcome.rebase !== undefined && { rebase: outcome.rebase }),
+                record,
+                evictions: outcome.evictions,
+                budgetPressure: {
+                    capTokens: config.thresholdTokens,
+                    projectedTokens: measured.input,
+                    planAction: outcome.removedMessageCount > 0 ? 'evict' : 'none',
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=tokenBudget.js.map

package/dist/esm/core/agent/window/strategies/tokenBudget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenBudget.js","sourceRoot":"","sources":["../../../../../../src/core/agent/window/strategies/tokenBudget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAI1D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,MAAM,GAAG,yBAAyB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAEjE,OAAO;QACL,IAAI,EAAE,YAAY;QAElB,KAAK,CAAC,IAAI,CAAC,KAA0B;YACnC,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;YAE3B,mEAAmE;YACnE,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC7C,0EAA0E;YAC1E,IAAI,QAAQ,CAAC,KAAK,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAClD,MAAM,IAAI,2BAA2B,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAC5D,CAAC;YACD,IAAI,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,eAAe;gBAAE,OAAO,SAAS,CAAC;YAE/D,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;YAC5E,MAAM,MAAM,GAAsB;gBAChC,QAAQ,EAAE,YAAY;gBACtB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,cAAc,EAAE,QAAQ,CAAC,KAAK;gBAC9B,eAAe,EAAE,MAAM,CAAC,eAAe;gBACvC,UAAU,EAAE,IAAI;gBAChB,eAAe,EAAE,MAAM,CAAC,eAAe;gBACvC,eAAe,EAAE,OAAO,CAAC,eAAe;gBACxC,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;gBAChD,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;gBAC5C,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;gBAC1C,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC;YAEF,OAAO;gBACL,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC/D,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC/D,MAAM;gBACN,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,cAAc,EAAE;oBACd,SAAS,EAAE,MAAM,CAAC,eAAe;oBACjC,eAAe,EAAE,QAAQ,CAAC,KAAK;oBAC/B,UAAU,EAAE,OAAO,CAAC,mBAAmB,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;iBAC/D;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/core/agent/window/strategy.d.ts

@@ -0,0 +1,181 @@
+/**
+ * window/strategy — PUBLIC. How a window strategy is shaped.
+ *
+ * Pattern: Strategy (GoF), with the dangerous half of the decision handed in
+ *          pre-bound rather than left to the implementer to re-derive.
+ * Role:    core/ layer. The window stage does the wiring — read the meter,
+ *          write the window, emit, record, cost — and delegates the one
+ *          interesting question to a strategy:
+ *
+ *              given the segmented turns and what the provider actually
+ *              counted → what should the window become, and what does the
+ *              ledger need to be told about it?
+ *
+ * Emits:   N/A. A strategy is pure decision + (optionally) its own LLM call;
+ *          it never touches scope, never emits, and never writes. That is
+ *          what makes it testable without a chart, and what keeps the
+ *          "record everything you did" duty in ONE place (the stage) rather
+ *          than duplicated per strategy.
+ *
+ * Three strategies ship — `summarizeOldest` (what `.compaction()`
+ * configures), `slidingWindow`, `tokenBudget` — and `.window(...)` takes any
+ * object that satisfies `WindowStrategy`.
+ *
+ * Two things are deliberately NOT left to the implementer:
+ *
+ *   1. **The refusal rules.** `planRemoval` arrives already bound to this
+ *      iteration's turns and guards. A strategy cannot forget that an
+ *      unanswered tool call must not leave the window, because it never gets
+ *      the chance to decide that for itself — it asks, and it is told, with
+ *      every refusal named. That is safety by construction, not by docs.
+ *   2. **Provenance.** `removalFacts` turns "these indices left" into the
+ *      stage ids that wrote them and how long each lived. A strategy cannot
+ *      file a removal it cannot name.
+ *
+ * The TRIGGER, by contrast, is entirely the strategy's own: `plan` is called
+ * at every ReAct iteration boundary and answers `undefined` when it did not
+ * engage. That is why `slidingWindow` can run on a provider that reports no
+ * usage at all while `summarizeOldest` and `tokenBudget` refuse by name.
+ */
+import type { LLMMessage } from '../../../adapters/types.js';
+import type { Turn, RemovalPlan } from './turns.js';
+import type { WindowRecord } from './types.js';
+/** One message leaving the window, with the facts an eviction event needs. */
+export interface WindowEviction {
+    /** Index in the PRE-change window — the index the content hash was built on. */
+    readonly index: number;
+    /** How long it lived in the window. Exact; 0 when its birth is unknown. */
+    readonly survivalMs: number;
+}
+/** The provenance of a set of removed messages, as the ledger needs it. */
+export interface RemovalFacts {
+    /** `runtimeStageId`s of the stages that appended those messages, in order. */
+    readonly removedStageIds: readonly string[];
+    /** One eviction per message, with its measured lifetime. */
+    readonly evictions: readonly WindowEviction[];
+}
+/** Everything a strategy is allowed to look at. */
+export interface WindowStrategyInput {
+    /** The window as it stands, detached. */
+    readonly history: readonly LLMMessage[];
+    /** The same window, segmented into turns. */
+    readonly turns: readonly Turn[];
+    /**
+     * What the provider REPORTED for the last completed call. Counted, never
+     * guessed. `undefined` before the first call of the run — a strategy that
+     * acted on that would be guessing, which is the one thing this family
+     * refuses to do.
+     *
+     * `{ input: 0, output: 0 }` is a provider that reported NOTHING, not a call
+     * that cost nothing. A token-triggered strategy should throw
+     * `CompactionUnmeasurableError` there rather than invent a size.
+     */
+    readonly measured: {
+        readonly input: number;
+        readonly output: number;
+    } | undefined;
+    /** The ReAct iteration this decision belongs to. */
+    readonly iteration: number;
+    /** The agent's own model — the sensible default for a strategy that bills. */
+    readonly agentModel: string;
+    /** `provider.name` of the MAIN provider, for a refusal that names it. */
+    readonly providerName: string;
+    /** The run's cancellation signal, when there is one. */
+    readonly signal: AbortSignal | undefined;
+    /** Wall clock, injectable so a caller can pin `survivalMs`. */
+    readonly now: () => number;
+    /**
+     * THE shared refusal engine, bound to this iteration.
+     *
+     * Answers: which contiguous span of turns may leave, and every turn that
+     * refused, named. Never removes the system envelope, the last
+     * `keepRecentTurns` turns, an unanswered tool call, the paused tool, or a
+     * pending check-in.
+     *
+     * @param keepRecentTurns   how many trailing turns are off-limits
+     * @param isExistingSummary optional predicate marking a turn that is a
+     *   summary a previous fold wrote; when the whole span is one of those, the
+     *   plan refuses with `only-existing-summary`. Pass it only if your strategy
+     *   spends an LLM call — a drop has nothing to protect against.
+     */
+    readonly planRemoval: (keepRecentTurns: number, isExistingSummary?: (turn: Turn) => boolean) => RemovalPlan;
+    /**
+     * Turn removed message indices into the facts the ledger needs: which
+     * stages wrote them, and how long each lived in the window.
+     *
+     * @param indices indices in the PRE-change window that are leaving
+     * @param atMs    the moment they leave (usually `input.now()`)
+     */
+    readonly removalFacts: (indices: readonly number[], atMs: number) => RemovalFacts;
+}
+/** What the stage should do next. */
+export interface WindowStrategyResult {
+    /** The new window. Absent = leave the window alone. */
+    readonly window?: readonly LLMMessage[];
+    /**
+     * How the meter must re-align its provenance to the new window, which is
+     * `[...head, (one new message)?, ...tail]`. Present exactly when `window`
+     * is. `insertedAtMs` is the birth of the message the strategy put in the
+     * span's place — omit it when the strategy removed messages and inserted
+     * nothing.
+     */
+    readonly rebase?: {
+        readonly headCount: number;
+        readonly keptTailCount: number;
+        readonly insertedAtMs?: number;
+    };
+    /** What the ledger is told. Always present — an engaged visit explains itself. */
+    readonly record: WindowRecord;
+    /** Messages that left the window, for `context.evicted`. */
+    readonly evictions: readonly WindowEviction[];
+    /**
+     * The budget reading to report on `agentfootprint.context.budget_pressure`.
+     *
+     * OMIT IT when the strategy has no token budget. `slidingWindow` does: it
+     * triggers on turn count, and filling `capTokens` with a number nobody
+     * configured would be the invented figure this family refuses. No budget,
+     * no budget_pressure event.
+     */
+    readonly budgetPressure?: {
+        readonly capTokens: number;
+        readonly projectedTokens: number;
+        readonly planAction: 'evict' | 'summarize' | 'none';
+    };
+    /** A billed call the strategy made, for the cost channel. */
+    readonly spend?: {
+        readonly model: string;
+        readonly usage: {
+            readonly input: number;
+            readonly output: number;
+        };
+    };
+    /** A one-per-run dev warning the stage should print. */
+    readonly warning?: string;
+}
+/**
+ * A window strategy: what the live window should become at this iteration
+ * boundary, and what the record must say about the change.
+ *
+ * Pass one to `AgentBuilder.window(...)`. Exactly one per agent —
+ * `.compaction(...)` is the same door with `summarizeOldest` already in it.
+ */
+export interface WindowStrategy {
+    /**
+     * Stable name — it is written onto every record this strategy files
+     * (`WindowRecord.strategy`), so a reader can tell which policy produced a
+     * window, and it names the strategy on the chart's `compact` stage.
+     */
+    readonly name: string;
+    /**
+     * Decide. Called at EVERY ReAct iteration boundary.
+     *
+     * Return `undefined` when this strategy did not engage — nothing was over
+     * budget, nothing was old enough, nothing has been counted yet. The ledger
+     * stays untouched and the run proceeds.
+     *
+     * Return a result for anything else, INCLUDING a visit that changed
+     * nothing because every candidate refused. Those are the visits a person
+     * debugging an oversized window actually needs.
+     */
+    plan(input: WindowStrategyInput): Promise<WindowStrategyResult | undefined>;
+}

package/dist/esm/core/agent/window/strategy.js

@@ -0,0 +1,41 @@
+/**
+ * window/strategy — PUBLIC. How a window strategy is shaped.
+ *
+ * Pattern: Strategy (GoF), with the dangerous half of the decision handed in
+ *          pre-bound rather than left to the implementer to re-derive.
+ * Role:    core/ layer. The window stage does the wiring — read the meter,
+ *          write the window, emit, record, cost — and delegates the one
+ *          interesting question to a strategy:
+ *
+ *              given the segmented turns and what the provider actually
+ *              counted → what should the window become, and what does the
+ *              ledger need to be told about it?
+ *
+ * Emits:   N/A. A strategy is pure decision + (optionally) its own LLM call;
+ *          it never touches scope, never emits, and never writes. That is
+ *          what makes it testable without a chart, and what keeps the
+ *          "record everything you did" duty in ONE place (the stage) rather
+ *          than duplicated per strategy.
+ *
+ * Three strategies ship — `summarizeOldest` (what `.compaction()`
+ * configures), `slidingWindow`, `tokenBudget` — and `.window(...)` takes any
+ * object that satisfies `WindowStrategy`.
+ *
+ * Two things are deliberately NOT left to the implementer:
+ *
+ *   1. **The refusal rules.** `planRemoval` arrives already bound to this
+ *      iteration's turns and guards. A strategy cannot forget that an
+ *      unanswered tool call must not leave the window, because it never gets
+ *      the chance to decide that for itself — it asks, and it is told, with
+ *      every refusal named. That is safety by construction, not by docs.
+ *   2. **Provenance.** `removalFacts` turns "these indices left" into the
+ *      stage ids that wrote them and how long each lived. A strategy cannot
+ *      file a removal it cannot name.
+ *
+ * The TRIGGER, by contrast, is entirely the strategy's own: `plan` is called
+ * at every ReAct iteration boundary and answers `undefined` when it did not
+ * engage. That is why `slidingWindow` can run on a provider that reports no
+ * usage at all while `summarizeOldest` and `tokenBudget` refuse by name.
+ */
+export {};
+//# sourceMappingURL=strategy.js.map

package/dist/esm/core/agent/window/strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../../../../src/core/agent/window/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG"}

package/dist/esm/core/agent/window/summarize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.js","sourceRoot":"","sources":["../../../../../src/core/agent/window/summarize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAE3D,kFAAkF;AAClF,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAC3C,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,wFAAwF;IACxF,kCAAkC;IAClC,EAAE;IACF,kCAAkC,eAAe,QAAQ,gBAAgB,sBAAsB;IAC/F,8FAA8F;IAC9F,6FAA6F;IAC7F,EAAE;IACF,4FAA4F;IAC5F,6FAA6F;IAC7F,gGAAgG;IAChG,yEAAyE;CAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,+EAA+E;AAC/E,SAAS,aAAa,CAAC,GAAe;IACpC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1F,MAAM,IAAI,GACR,GAAG,CAAC,IAAI,KAAK,MAAM;QACjB,CAAC,CAAC,eAAe,GAAG,CAAC,QAAQ,IAAI,SAAS,GAAG;QAC7C,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAC9C,CAAC,CAAC,qBAAqB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC1C,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IACf,OAAO,GAAG,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC;AACnC,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,QAA+B;IAC9D,OAAO,CAAC,eAAe,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,KAIC;IAED,MAAM,KAAK,GACT,GAAG,sBAAsB,MAAM,KAAK,CAAC,kBAAkB,kCAAkC;QACzF,mCAAmC,KAAK,CAAC,SAAS,0CAA0C;QAC5F,cAAc,KAAK,CAAC,KAAK,gEAAgE;QACzF,sEAAsE,CAAC;IACzE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,OAAO,OAAO,EAAE,EAAE,CAAC;AAC7D,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,kBAAkB,CAAC,GAA2B;IAC5D,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,sBAAsB,CAAC,CAAC;AACpG,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAqB,EACrB,KAAa,EACb,IAA2B,EAC3B,MAA+B;IAE/B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC;QACvC,YAAY,EAAE,wBAAwB;QACtC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7D,KAAK;QACL,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;KACxC,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;AAC3D,CAAC"}