agentfootprint 7.16.0 → 7.18.0

package/dist/types/core/agent/window/options.d.ts

@@ -0,0 +1,34 @@
+/**
+ * window/options — validate a window strategy's options ONCE, at build time.
+ *
+ * Pattern: Guard functions returning a resolved config.
+ * Role:    core/ layer. Every message here takes a `label`, because the same
+ *          option bag arrives through two doors — `.compaction({...})` and
+ *          `summarizeOldest({...})` — and an error should name the door the
+ *          caller actually used. One implementation, so the two doors can
+ *          never drift into validating differently.
+ * Emits:   N/A.
+ *
+ * Everything fails at `.build()`, never mid-run. A window policy that turns
+ * out to be nonsense on iteration 40 of a paid run is a policy that cost you
+ * money to discover.
+ */
+import type { CompactionOptions, ResolvedCompaction, SlidingWindowOptions, TokenBudgetOptions } from './types.js';
+/** Default depth of the "never touch this" recent window. */
+export declare const DEFAULT_KEEP_RECENT_TURNS = 6;
+/**
+ * Validate `.compaction()` / `summarizeOldest()` options.
+ *
+ * @param label the door being used, so the error names it
+ */
+export declare function resolveCompactionOptions(options: CompactionOptions, label: string): ResolvedCompaction;
+/** Validate `slidingWindow()` options. */
+export declare function resolveSlidingWindowOptions(options: SlidingWindowOptions, label: string): {
+    readonly keepRecentTurns: number;
+};
+/** Validate `tokenBudget()` options. */
+export declare function resolveTokenBudgetOptions(options: TokenBudgetOptions, label: string): {
+    readonly thresholdTokens: number;
+    readonly keepRecentTurns: number;
+};
+//# sourceMappingURL=options.d.ts.map

package/dist/types/core/agent/window/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/window/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAgC3C;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,MAAM,GACZ,kBAAkB,CAyBpB;AAED,0CAA0C;AAC1C,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,MAAM,GACZ;IAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAWtC;AAED,wCAAwC;AACxC,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,MAAM,GACZ;IAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAMxE"}

package/dist/types/core/agent/window/removal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * window/removal — "these messages left" → the facts the ledger needs.
+ *
+ * Pattern: Pure function over the meter's provenance.
+ * Role:    core/ layer. The stage binds this into every
+ *          `WindowStrategyInput.removalFacts`, so a strategy can name what it
+ *          removed without ever touching the meter — and cannot file a
+ *          removal it is unable to name.
+ * Emits:   N/A.
+ */
+import type { MessageOrigin } from '../../../recorders/core/CompactionMeter.js';
+import type { RemovalFacts } from './strategy.js';
+/**
+ * Resolve which stages wrote the removed messages, and how long each lived.
+ *
+ * `survivalMs` is measured (`atMs - bornAtMs`), and is 0 — not a guess — when
+ * a message's birth is unknown, which happens only for a window seeded from
+ * outside this run.
+ */
+export declare function removalFacts(origins: readonly MessageOrigin[], indices: readonly number[], atMs: number): RemovalFacts;
+/** `[from, toExclusive)` as a list of indices. */
+export declare function indexRange(from: number, toExclusive: number): number[];
+//# sourceMappingURL=removal.d.ts.map

package/dist/types/core/agent/window/removal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"removal.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/window/removal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4CAA4C,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,eAAe,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,EAAE,MAAM,GACX,YAAY,CAcd;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAItE"}

package/dist/types/core/agent/window/strategies/drop.d.ts

@@ -0,0 +1,55 @@
+/**
+ * window/strategies/drop — the mechanic both drop strategies share.
+ *
+ * Pattern: One pure function over a `WindowStrategyInput`.
+ * Role:    core/ layer. `slidingWindow` and `tokenBudget` differ ONLY in when
+ *          they engage and what they file; what actually leaves the window is
+ *          decided here, once, so a refusal reason means the same thing under
+ *          both — and under compaction, which asks the same `planRemoval`.
+ * Emits:   N/A.
+ *
+ * A drop makes no LLM call and writes no summary. What it must still do is
+ * keep the request valid and keep the record honest:
+ *
+ *   • the span comes from the shared refusal engine, so an unanswered tool
+ *     call, the paused tool, a pending check-in and the recent turns never
+ *     leave, and each refusal is named;
+ *   • when the span reaches the window's HEAD, an authored notice takes that
+ *     position — the window must open on a user turn (see notice.ts), and a
+ *     message we are forced to author should tell the truth;
+ *   • when it does not, nothing is inserted: the original opening turn is
+ *     still there, so there is no wire problem to solve.
+ */
+import type { LLMMessage } from '../../../../adapters/types.js';
+import type { WindowEviction, WindowStrategyInput } from '../strategy.js';
+import type { WindowRefusal } from '../types.js';
+/** What a drop attempt did, in the terms a record needs. */
+export interface DropOutcome {
+    /** Every turn that refused to leave, named. */
+    readonly refusals: readonly WindowRefusal[];
+    /** The new window; absent when nothing was dropped. */
+    readonly window?: readonly LLMMessage[];
+    readonly rebase?: {
+        readonly headCount: number;
+        readonly keptTailCount: number;
+        readonly insertedAtMs?: number;
+    };
+    readonly removedStageIds: readonly string[];
+    readonly removedMessageCount: number;
+    readonly evictions: readonly WindowEviction[];
+    readonly windowCharsBefore: number;
+    readonly windowCharsAfter: number;
+    /** Turns in the window before / after. Counted from the segmentation. */
+    readonly turnsBefore: number;
+    readonly turnsAfter: number;
+}
+/**
+ * Drop the oldest contiguous removable span, if there is one.
+ *
+ * @param input            the strategy's input, with the bound refusal engine
+ * @param keepRecentTurns  how many trailing turns are off-limits
+ * @param strategyName     named in the authored notice, so a reader of the
+ *                         window itself can tell which policy removed things
+ */
+export declare function dropOldestSpan(input: WindowStrategyInput, keepRecentTurns: number, strategyName: string): DropOutcome;
+//# sourceMappingURL=drop.d.ts.map

package/dist/types/core/agent/window/strategies/drop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drop.d.ts","sourceRoot":"","sources":["../../../../../../src/core/agent/window/strategies/drop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGhE,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,EAC1B,eAAe,EAAE,MAAM,EACvB,YAAY,EAAE,MAAM,GACnB,WAAW,CAsEb"}

package/dist/types/core/agent/window/strategies/slidingWindow.d.ts

@@ -0,0 +1,49 @@
+/**
+ * slidingWindow — keep the last N turns, drop what is older.
+ *
+ * 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 simplest window policy (LangChain's `trim_messages`, the
+ * "last N messages" every framework ships). Two things are different here:
+ *
+ *   1. **It refuses by name.** It goes through the SAME turn segmentation and
+ *      the SAME refusal engine as compaction, so it will not drop half of a
+ *      `tool_use` / `tool_result` pair, will not drop an unanswered tool call
+ *      whose answer may still arrive, will not drop the tool a paused run is
+ *      waiting on or a pending check-in, and cannot touch the system
+ *      envelope. Message-counting trimmers split those pairs and the vendor
+ *      rejects the request; this one steps over them and says so in the
+ *      record.
+ *   2. **It says what it dropped.** Every dropped message is an eviction
+ *      event with its measured lifetime, and the record names the stage ids
+ *      the messages came from. The turns themselves stay in the commit log,
+ *      byte for byte.
+ *
+ * It triggers on turn COUNT, not tokens — so it needs no summarizer, makes no
+ * LLM call, and runs on ANY provider, including the ones that report no usage
+ * at all. Nothing here is unmeasurable, so nothing here throws.
+ */
+import type { WindowStrategy } from '../strategy.js';
+import type { SlidingWindowOptions } from '../types.js';
+/** `WindowRecord.strategy` written by every record this strategy files. */
+export declare const SLIDING_WINDOW = "sliding-window";
+/**
+ * Keep the most recent `keepRecentTurns` turns in the live window and drop
+ * the older ones — except anything that refuses.
+ *
+ * @example
+ * ```ts
+ * import { Agent, slidingWindow } from 'agentfootprint';
+ * import { ollama } from 'agentfootprint/llm-providers';
+ *
+ * // Works on a provider that reports no usage at all: the trigger is turns.
+ * const agent = Agent.create({ provider: ollama(), model: 'llama3' })
+ *   .window(slidingWindow({ keepRecentTurns: 12 }))
+ *   .build();
+ * ```
+ */
+export declare function slidingWindow(options: SlidingWindowOptions): WindowStrategy;
+//# sourceMappingURL=slidingWindow.d.ts.map

package/dist/types/core/agent/window/strategies/slidingWindow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slidingWindow.d.ts","sourceRoot":"","sources":["../../../../../../src/core/agent/window/strategies/slidingWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,cAAc,EAA6C,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,oBAAoB,EAAuB,MAAM,aAAa,CAAC;AAE7E,2EAA2E;AAC3E,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAqC3E"}

package/dist/types/core/agent/window/strategies/summarizeOldest.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 type { WindowStrategy } from '../strategy.js';
+import type { CompactionOptions } from '../types.js';
+/** `WindowRecord.strategy` written by every record this strategy files. */
+export declare 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 declare function summarizeOldest(options: CompactionOptions): WindowStrategy;
+//# sourceMappingURL=summarizeOldest.d.ts.map

package/dist/types/core/agent/window/strategies/summarizeOldest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizeOldest.d.ts","sourceRoot":"","sources":["../../../../../../src/core/agent/window/strategies/summarizeOldest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EAAE,cAAc,EAA6C,MAAM,gBAAgB,CAAC;AAGhG,OAAO,KAAK,EAAE,iBAAiB,EAAmC,MAAM,aAAa,CAAC;AAEtF,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAiJ1E"}

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

@@ -0,0 +1,48 @@
+/**
+ * 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;
+//# sourceMappingURL=tokenBudget.d.ts.map

package/dist/types/core/agent/window/strategies/tokenBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenBudget.d.ts","sourceRoot":"","sources":["../../../../../../src/core/agent/window/strategies/tokenBudget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,KAAK,EAAE,cAAc,EAA6C,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,aAAa,CAAC;AAEzE,2EAA2E;AAC3E,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CA6CvE"}

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

@@ -0,0 +1,182 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=strategy.d.ts.map

package/dist/types/core/agent/window/strategy.d.ts.map

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

package/dist/types/core/agent/window/summarize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/window/summarize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEvF,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAM3D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAYzB,CAAC;AAcb,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;IACL,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACA,UAAU,CAOZ;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAEvE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,eAAe,CAAC,CAQ1B"}

package/dist/types/core/agent/window/turns.d.ts

@@ -0,0 +1,109 @@
+/**
+ * window/turns — where a turn boundary is, and which turns may leave.
+ *
+ * Pattern: Pure functions over the window (no scope, no I/O, no clock).
+ * Role:    core/ layer. THE refusal engine. Every window strategy — the three
+ *          that ship, and any a consumer writes — decides what leaves the
+ *          window by calling these functions and nothing else, because the
+ *          whole safety argument of the family lives here:
+ *
+ *            a removal that splits an assistant's `tool_use` from its
+ *            `tool_result` produces a request the vendor rejects, and a
+ *            removal that swallows an unanswered question destroys the
+ *            referent of the answer that has not arrived yet.
+ *
+ *          Strategies never import this module. `WindowStrategyInput` hands
+ *          them `planRemoval` already bound to this iteration's turns and
+ *          guards, so a strategy CANNOT skip the refusal rules — that is a
+ *          property of the seam, not of the documentation.
+ * Emits:   N/A.
+ *
+ * Testable on its own — see `test/core/window-turns.test.ts`.
+ */
+import type { LLMMessage } from '../../../adapters/types.js';
+import type { WindowRefusal, WindowRefusalReason } from './types.js';
+/**
+ * One turn: a `user` / `assistant` / `system` message plus every `tool`
+ * message that answers it. Tool results belong to the assistant turn that
+ * requested them — that pairing is the thing a removal must never break.
+ */
+export interface Turn {
+    /** Index of this turn in the segmentation. */
+    readonly index: number;
+    /** Index of the turn's FIRST message in the window. */
+    readonly start: number;
+    /** Number of messages in the turn. */
+    readonly length: number;
+    readonly messages: readonly LLMMessage[];
+}
+/**
+ * Segment a window into turns.
+ *
+ * A new turn starts at any non-`tool` message; `tool` messages join the turn
+ * in progress. A leading `tool` message (only reachable from a hand-built
+ * history) starts its own turn rather than being silently dropped.
+ */
+export declare function segmentTurns(history: readonly LLMMessage[]): readonly Turn[];
+/**
+ * Context a removal decision needs beyond the turn itself.
+ *
+ * Internal: the stage builds it from scope and binds it into the
+ * `planRemoval` a strategy is handed, so no strategy has to know it exists.
+ */
+export interface RemovalGuards {
+    /** Every `toolCallId` answered anywhere in the window. */
+    readonly answeredCallIds: ReadonlySet<string>;
+    /** The tool call this run is paused on, when it is paused. */
+    readonly pausedToolCallId?: string;
+    /** True when the pause is a check-in (human consent) rather than askHuman. */
+    readonly pausedCheckIn?: boolean;
+}
+/** Every tool_call id that has a matching `role: 'tool'` message. */
+export declare function answeredCallIds(history: readonly LLMMessage[]): ReadonlySet<string>;
+/**
+ * Why this turn may NOT leave the window, or `undefined` when it may.
+ *
+ * Order matters only for which reason gets reported first; every check is
+ * independent. `paused-tool` / `pending-check-in` are separated from
+ * `unresolved-tool-call` on purpose: they are the same shape but a different
+ * fact about the world, and "we are waiting on a human" is what the person
+ * reading the trace needs to see.
+ */
+export declare function refusalFor(turn: Turn, guards: RemovalGuards): WindowRefusalReason | undefined;
+/** The span a removal will take, plus every refusal it had to name to get there. */
+export interface RemovalPlan {
+    /** First turn index in the span; -1 when nothing may be removed. */
+    readonly from: number;
+    /** Last turn index in the span (inclusive); -1 when nothing may be removed. */
+    readonly to: number;
+    readonly refusals: readonly WindowRefusal[];
+}
+/**
+ * Choose the removal span: the LONGEST CONTIGUOUS run of removable candidate
+ * turns, starting at the oldest removable one.
+ *
+ * Contiguity is not fussiness — it is what keeps the conversation in order.
+ * A fold replaces its span with ONE summary message; if the span skipped over
+ * an unremovable turn, that turn would end up after a summary of things that
+ * happened before it. So an unremovable turn at the front is stepped over (the
+ * span "takes the next oldest instead") and an unremovable turn in the middle
+ * ends the span. Everything not removed keeps its position.
+ *
+ * The drop strategies take the same span for a second reason: it is what makes
+ * a refusal reason mean the same thing under every strategy. A turn that ends
+ * the span this iteration is retried the next one — by which time the tool
+ * result it was waiting on has usually arrived.
+ *
+ * @param turns             the window's turn segmentation
+ * @param keepRecent        how many trailing turns are off-limits
+ * @param guards            what must not leave (unanswered calls, the pause)
+ * @param isExistingSummary optional: true for a turn that is a summary a prior
+ *   fold wrote. When the whole span is one such turn, the plan refuses with
+ *   `only-existing-summary` — re-summarizing a summary spends an LLM call to
+ *   lose detail. The drop strategies omit it: a drop spends nothing, so there
+ *   is nothing to protect against.
+ */
+export declare function planRemoval(turns: readonly Turn[], keepRecent: number, guards: RemovalGuards, isExistingSummary?: (turn: Turn) => boolean): RemovalPlan;
+/** Total characters of message content in a window. Exact; not tokens. */
+export declare function windowChars(history: readonly LLMMessage[]): number;
+//# sourceMappingURL=turns.d.ts.map

package/dist/types/core/agent/window/turns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turns.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/window/turns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,IAAI;IACnB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,IAAI,EAAE,CAqB5E;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9C,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,CAMnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,GAAG,mBAAmB,GAAG,SAAS,CAkB7F;AAED,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,aAAa,EACrB,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,GAC1C,WAAW,CA8Cb;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAIlE"}