agentfootprint 7.16.0 → 7.17.0

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

@@ -0,0 +1,52 @@
+/**
+ * window/notice — the authored message a DROP leaves behind, and why it has
+ * to exist at all.
+ *
+ * Pattern: Authored envelope with no untrusted payload whatsoever.
+ * Role:    core/ layer. Shared by both drop strategies.
+ * Emits:   N/A.
+ *
+ * The first reason for this message is the WIRE, not the prose. An agent
+ * window looks like `user, assistant+tool, assistant+tool, …`, so dropping
+ * the oldest turns leaves an ASSISTANT message at the head — and the
+ * providers that care (Anthropic) require the window to open on a user turn.
+ * A silent drop of the window's head therefore produces a request the vendor
+ * rejects. Something must occupy that position.
+ *
+ * Given that we have to author a message there anyway, it should say what
+ * happened rather than be filler. So it does: how many messages left, at
+ * which iteration, by which strategy, and where they still are. Unlike the
+ * compaction frame there is no model output involved at ALL — every character
+ * below is written by this library, which is why a drop has no prompt-
+ * injection surface to speak of.
+ *
+ * It appears ONLY when the removal reaches the window's head. A removal in
+ * the middle leaves the original opening turn in place, so there is no wire
+ * problem to solve — and splicing a lone `user` message between two assistant
+ * turns is its own risk. The ledger names that removal either way.
+ *
+ * It does not accumulate: the notice is an ordinary oldest turn next time
+ * round, so the next drop absorbs it and files a fresh one.
+ */
+/** Opening of the authored notice. Stable — tests and readers match on it. */
+export const DROP_NOTICE_PREFIX = '[dropped history';
+/**
+ * Build the message that takes the head position after a drop.
+ *
+ * `role: 'user'` for the same reason the compaction frame is: it is the head
+ * of the window, and the head of the window must be a user turn.
+ */
+export function buildDropNotice(facts) {
+    return {
+        role: 'user',
+        content: `${DROP_NOTICE_PREFIX} — ${facts.droppedMessageCount} earlier message(s) were dropped ` +
+            `from this window at iteration ${facts.iteration} by the '${facts.strategy}' window ` +
+            `strategy. Nothing was summarized: those turns are simply not being re-sent. They are ` +
+            `retained verbatim in this run's commit log.]`,
+    };
+}
+/** True when this message is a notice a previous drop wrote. */
+export function isDropNotice(msg) {
+    return msg !== undefined && msg.role === 'user' && msg.content.startsWith(DROP_NOTICE_PREFIX);
+}
+//# sourceMappingURL=notice.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notice.js","sourceRoot":"","sources":["../../../../../src/core/agent/window/notice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAI/B;IACC,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EACL,GAAG,kBAAkB,MAAM,KAAK,CAAC,mBAAmB,mCAAmC;YACvF,iCAAiC,KAAK,CAAC,SAAS,YAAY,KAAK,CAAC,QAAQ,WAAW;YACrF,uFAAuF;YACvF,8CAA8C;KACjD,CAAC;AACJ,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,YAAY,CAAC,GAA2B;IACtD,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AAChG,CAAC"}

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

@@ -0,0 +1,33 @@
+/**
+ * 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;
+};

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

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+/** Default depth of the "never touch this" recent window. */
+export const DEFAULT_KEEP_RECENT_TURNS = 6;
+function requireObject(options, label, shape) {
+    if (options === null || typeof options !== 'object') {
+        throw new Error(`${label}: expected an options object (${shape}), got ${typeof options}.`);
+    }
+}
+function requireThreshold(thresholdTokens, label) {
+    if (typeof thresholdTokens !== 'number' ||
+        !Number.isFinite(thresholdTokens) ||
+        thresholdTokens <= 0) {
+        throw new Error(`${label}: thresholdTokens must be a positive number of tokens, got ` +
+            `${String(thresholdTokens)}. There is no default: the right budget depends on your ` +
+            `model and your bill, and a number this library invented would be inherited silently ` +
+            `by every run.`);
+    }
+}
+function requireKeepRecentTurns(keepRecentTurns, label) {
+    if (!Number.isInteger(keepRecentTurns) || keepRecentTurns < 1) {
+        throw new Error(`${label}: keepRecentTurns must be an integer >= 1, got ${String(keepRecentTurns)}. ` +
+            `Keeping zero recent turns would remove the turn the model is reasoning over right now.`);
+    }
+}
+/**
+ * Validate `.compaction()` / `summarizeOldest()` options.
+ *
+ * @param label the door being used, so the error names it
+ */
+export function resolveCompactionOptions(options, label) {
+    requireObject(options, label, '{ thresholdTokens, summarizer, ... }');
+    const { thresholdTokens, summarizer, keepRecentTurns, model } = options;
+    requireThreshold(thresholdTokens, label);
+    if (summarizer === null ||
+        typeof summarizer !== 'object' ||
+        typeof summarizer.complete !== 'function') {
+        throw new Error(`${label}: summarizer must be an LLMProvider (an object with a ` +
+            'complete() method). It is explicit on purpose — the library will not quietly bill ' +
+            'your main model for compaction. Pass a cheap provider/model here.');
+    }
+    if (keepRecentTurns !== undefined)
+        requireKeepRecentTurns(keepRecentTurns, label);
+    if (model !== undefined && (typeof model !== 'string' || model.length === 0)) {
+        throw new Error(`${label}: model must be a non-empty model id, got ${String(model)}.`);
+    }
+    return {
+        thresholdTokens,
+        keepRecentTurns: keepRecentTurns ?? DEFAULT_KEEP_RECENT_TURNS,
+        summarizer,
+        model,
+    };
+}
+/** Validate `slidingWindow()` options. */
+export function resolveSlidingWindowOptions(options, label) {
+    requireObject(options, label, '{ keepRecentTurns }');
+    const { keepRecentTurns } = options;
+    if (keepRecentTurns === undefined) {
+        throw new Error(`${label}: keepRecentTurns is required and has no default. It IS the policy — how much ` +
+            `past your agent needs is a fact about your agent, not about this library.`);
+    }
+    requireKeepRecentTurns(keepRecentTurns, label);
+    return { keepRecentTurns };
+}
+/** Validate `tokenBudget()` options. */
+export function resolveTokenBudgetOptions(options, label) {
+    requireObject(options, label, '{ thresholdTokens, keepRecentTurns? }');
+    const { thresholdTokens, keepRecentTurns } = options;
+    requireThreshold(thresholdTokens, label);
+    if (keepRecentTurns !== undefined)
+        requireKeepRecentTurns(keepRecentTurns, label);
+    return { thresholdTokens, keepRecentTurns: keepRecentTurns ?? DEFAULT_KEEP_RECENT_TURNS };
+}
+//# sourceMappingURL=options.js.map

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * 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[];

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function removalFacts(origins, indices, atMs) {
+    const removedStageIds = [];
+    const evictions = [];
+    for (const index of indices) {
+        const origin = origins[index];
+        if (origin !== undefined && !removedStageIds.includes(origin.stageId)) {
+            removedStageIds.push(origin.stageId);
+        }
+        evictions.push({
+            index,
+            survivalMs: origin === undefined ? 0 : Math.max(0, atMs - origin.bornAtMs),
+        });
+    }
+    return { removedStageIds, evictions };
+}
+/** `[from, toExclusive)` as a list of indices. */
+export function indexRange(from, toExclusive) {
+    const out = [];
+    for (let i = from; i < toExclusive; i++)
+        out.push(i);
+    return out;
+}
+//# sourceMappingURL=removal.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"removal.js","sourceRoot":"","sources":["../../../../../src/core/agent/window/removal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAiC,EACjC,OAA0B,EAC1B,IAAY;IAEZ,MAAM,eAAe,GAAa,EAAE,CAAC;IACrC,MAAM,SAAS,GAAqB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACtE,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;QACD,SAAS,CAAC,IAAI,CAAC;YACb,KAAK;YACL,UAAU,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC;SAC3E,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC;AACxC,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,WAAmB;IAC1D,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrD,OAAO,GAAG,CAAC;AACb,CAAC"}

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

@@ -0,0 +1,54 @@
+/**
+ * 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;

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

@@ -0,0 +1,102 @@
+/**
+ * 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 { buildDropNotice } from '../notice.js';
+import { indexRange } from '../removal.js';
+import { segmentTurns, windowChars } from '../turns.js';
+/**
+ * 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 function dropOldestSpan(input, keepRecentTurns, strategyName) {
+    const { history, turns, iteration } = input;
+    const charsBefore = windowChars(history);
+    const nothing = (refusals) => ({
+        refusals,
+        removedStageIds: [],
+        removedMessageCount: 0,
+        evictions: [],
+        windowCharsBefore: charsBefore,
+        windowCharsAfter: charsBefore,
+        turnsBefore: turns.length,
+        turnsAfter: turns.length,
+    });
+    // No `isExistingSummary` predicate: that refusal exists to stop a strategy
+    // spending an LLM call to re-summarize a summary. A drop spends nothing, so
+    // there is nothing to protect against — a stale summary is as droppable as
+    // any other old turn.
+    const plan = input.planRemoval(keepRecentTurns);
+    if (plan.from === -1)
+        return nothing(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);
+    let window;
+    let insertedAtMs;
+    const droppedAtMs = input.now();
+    if (spanStart === 0) {
+        // The head is leaving: something must open the window, and it must be a
+        // user turn. Author the notice — and refuse the whole drop if that notice
+        // would not be smaller than what it replaces, because dropping two tiny
+        // turns to insert a longer notice is pure loss.
+        const notice = buildDropNotice({
+            droppedMessageCount: span.length,
+            iteration,
+            strategy: strategyName,
+        });
+        if (notice.content.length >= windowChars(span)) {
+            return nothing([
+                { reason: 'summary-not-smaller', turnIndex: plan.from, messageIndex: spanStart },
+                ...plan.refusals,
+            ]);
+        }
+        window = [notice, ...tail];
+        insertedAtMs = droppedAtMs;
+    }
+    else {
+        window = [...head, ...tail];
+    }
+    const facts = input.removalFacts(indexRange(spanStart, spanEnd), droppedAtMs);
+    return {
+        refusals: plan.refusals,
+        window,
+        rebase: {
+            headCount: head.length,
+            keptTailCount: tail.length,
+            ...(insertedAtMs !== undefined && { insertedAtMs }),
+        },
+        removedStageIds: facts.removedStageIds,
+        removedMessageCount: span.length,
+        evictions: facts.evictions,
+        windowCharsBefore: charsBefore,
+        windowCharsAfter: windowChars(window),
+        turnsBefore: turns.length,
+        turnsAfter: segmentTurns(window).length,
+    };
+}
+//# sourceMappingURL=drop.js.map

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

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

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

@@ -0,0 +1,48 @@
+/**
+ * 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;

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

@@ -0,0 +1,83 @@
+/**
+ * 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 { dropOldestSpan } from './drop.js';
+import { resolveSlidingWindowOptions } from '../options.js';
+/** `WindowRecord.strategy` written by every record this strategy files. */
+export 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 function slidingWindow(options) {
+    const config = resolveSlidingWindowOptions(options, 'slidingWindow');
+    return {
+        name: SLIDING_WINDOW,
+        async plan(input) {
+            // Did not engage: the window is already within its target depth. No
+            // record — the ledger tracks what this strategy DID, not every time it
+            // looked and there was nothing to do.
+            if (input.turns.length <= config.keepRecentTurns)
+                return undefined;
+            const outcome = dropOldestSpan(input, config.keepRecentTurns, SLIDING_WINDOW);
+            const record = {
+                strategy: SLIDING_WINDOW,
+                iteration: input.iteration,
+                keepRecentTurns: config.keepRecentTurns,
+                removedStageIds: outcome.removedStageIds,
+                removedMessageCount: outcome.removedMessageCount,
+                windowCharsBefore: outcome.windowCharsBefore,
+                windowCharsAfter: outcome.windowCharsAfter,
+                turnsBefore: outcome.turnsBefore,
+                turnsAfter: outcome.turnsAfter,
+                refusals: outcome.refusals,
+            };
+            // No `budgetPressure`: this strategy has no token budget. Reporting a
+            // cap nobody configured would be the invented number the family exists
+            // to refuse — so it reports evictions and stays quiet about budgets.
+            return {
+                ...(outcome.window !== undefined && { window: outcome.window }),
+                ...(outcome.rebase !== undefined && { rebase: outcome.rebase }),
+                record,
+                evictions: outcome.evictions,
+            };
+        },
+    };
+}
+//# sourceMappingURL=slidingWindow.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"slidingWindow.js","sourceRoot":"","sources":["../../../../../../src/core/agent/window/strategies/slidingWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAI5D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,MAAM,GAAG,2BAA2B,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAErE,OAAO;QACL,IAAI,EAAE,cAAc;QAEpB,KAAK,CAAC,IAAI,CAAC,KAA0B;YACnC,oEAAoE;YACpE,uEAAuE;YACvE,sCAAsC;YACtC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,eAAe;gBAAE,OAAO,SAAS,CAAC;YAEnE,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC;YAC9E,MAAM,MAAM,GAAwB;gBAClC,QAAQ,EAAE,cAAc;gBACxB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,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,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC3B,CAAC;YAEF,sEAAsE;YACtE,uEAAuE;YACvE,qEAAqE;YACrE,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;aAC7B,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,42 @@
+/**
+ * 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;