agentfootprint 7.16.0 → 7.18.0

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

@@ -1,103 +0,0 @@
-/**
- * compaction/strategy — INTERNAL. How a window strategy is shaped.
- *
- * Pattern: Strategy (GoF), deliberately kept private for now.
- * Role:    core/ layer. The compaction 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, the meter readings, and the
- *              options → 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.
- *
- * **Not exported from any barrel, and not part of the public API.** The only
- * shipped implementation is `summarizeOldestStrategy` (what `.compaction()`
- * configures). The interface lives here so that the day a second window
- * strategy is warranted it is an added file rather than a rewrite of the
- * stage — but a seam nobody has used twice is a guess, so it stays private
- * until it has a second implementation to be right about.
- */
-import type { LLMMessage } from '../../../adapters/types.js';
-import type { MessageOrigin } from '../../../recorders/core/CompactionMeter.js';
-import { type FoldabilityContext, type Turn } from './turns.js';
-import type { CompactionRecord, ResolvedCompaction } from './types.js';
-/** 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[];
-    /** Per-message provenance, aligned index-for-index with `history`. */
-    readonly origins: readonly MessageOrigin[];
-    /** What the provider REPORTED for the last call. Counted, never guessed. */
-    readonly measuredTokens: number;
-    /** What must not fold: unanswered calls, the paused tool, a pending check-in. */
-    readonly foldability: FoldabilityContext;
-    /** The ReAct iteration this decision belongs to. */
-    readonly iteration: number;
-    /** 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;
-}
-/** 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;
-}
-/** What the stage should do next. Everything is optional except the record. */
-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.
-     */
-    readonly rebase?: {
-        readonly headCount: number;
-        readonly keptTailCount: number;
-    };
-    /** What the ledger is told. Always present — a visit always explains itself. */
-    readonly record: CompactionRecord;
-    /** Messages that left the window, for `context.evicted`. */
-    readonly evictions: readonly WindowEviction[];
-    /** `planAction` for `context.budget_pressure`. */
-    readonly planAction: '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 when it is over
- * budget, and what the record must say about the change.
- */
-export interface WindowStrategy {
-    /** Stable name — goes nowhere public yet; used in messages and tests. */
-    readonly name: string;
-    plan(input: WindowStrategyInput): Promise<WindowStrategyResult>;
-}
-/**
- * The shipped strategy: fold the oldest contiguous run of foldable turns into
- * one summary message, keeping the recent turns and stepping over anything
- * unresolved.
- *
- * Everything it decides, it explains. Every path returns a record — including
- * the paths that change nothing, which are the ones a person debugging an
- * over-budget window actually needs.
- */
-export declare function summarizeOldestStrategy(config: ResolvedCompaction, defaultModel: string): WindowStrategy;

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

@@ -1,148 +0,0 @@
-/**
- * compaction/strategy — INTERNAL. How a window strategy is shaped.
- *
- * Pattern: Strategy (GoF), deliberately kept private for now.
- * Role:    core/ layer. The compaction 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, the meter readings, and the
- *              options → 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.
- *
- * **Not exported from any barrel, and not part of the public API.** The only
- * shipped implementation is `summarizeOldestStrategy` (what `.compaction()`
- * configures). The interface lives here so that the day a second window
- * strategy is warranted it is an added file rather than a rewrite of the
- * stage — but a seam nobody has used twice is a guess, so it stays private
- * until it has a second implementation to be right about.
- */
-import { buildSummaryMessage, isCompactedSummary, runSummarizer } from './summarize.js';
-import { planFold, windowChars } from './turns.js';
-/**
- * The shipped strategy: fold the oldest contiguous run of foldable turns into
- * one summary message, keeping the recent turns and stepping over anything
- * unresolved.
- *
- * Everything it decides, it explains. Every path returns a record — including
- * the paths that change nothing, which are the ones a person debugging an
- * over-budget window actually needs.
- */
-export function summarizeOldestStrategy(config, defaultModel) {
-    const model = config.model ?? defaultModel;
-    return {
-        name: 'summarize-oldest',
-        async plan(input) {
-            const { history, turns, origins, iteration } = input;
-            const charsBefore = windowChars(history);
-            const base = {
-                iteration,
-                measuredTokens: input.measuredTokens,
-                thresholdTokens: config.thresholdTokens,
-                overBudget: true,
-                windowCharsBefore: charsBefore,
-            };
-            const unchanged = (refusals, extra = {}) => ({
-                record: {
-                    ...base,
-                    foldedStageIds: [],
-                    foldedMessageCount: 0,
-                    windowCharsAfter: charsBefore,
-                    summaryChars: 0,
-                    refusals,
-                    ...extra,
-                },
-                evictions: [],
-                planAction: 'none',
-            });
-            const plan = planFold(turns, config.keepRecentTurns, input.foldability, (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 (${input.measuredTokens} 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 foldedStageIds = [];
-            const evictions = [];
-            for (let i = spanStart; i < spanEnd; i++) {
-                const origin = origins[i];
-                if (origin !== undefined && !foldedStageIds.includes(origin.stageId)) {
-                    foldedStageIds.push(origin.stageId);
-                }
-                evictions.push({
-                    index: i,
-                    survivalMs: origin === undefined ? 0 : Math.max(0, foldedAtMs - origin.bornAtMs),
-                });
-            }
-            const window = [...head, summaryMessage, ...tail];
-            return {
-                window,
-                rebase: { headCount: head.length, keptTailCount: tail.length },
-                record: {
-                    ...base,
-                    foldedStageIds,
-                    foldedMessageCount: span.length,
-                    windowCharsAfter: windowChars(window),
-                    summaryChars: summaryMessage.content.length,
-                    summarizerTokens: summary.usage,
-                    refusals: plan.refusals,
-                },
-                evictions,
-                planAction: 'summarize',
-                spend,
-            };
-        },
-    };
-}
-//# sourceMappingURL=strategy.js.map

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

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

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

@@ -1 +0,0 @@
-{"version":3,"file":"summarize.js","sourceRoot":"","sources":["../../../../../src/core/agent/compaction/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"}

package/dist/esm/core/agent/compaction/turns.d.ts

@@ -1,85 +0,0 @@
-/**
- * compaction/turns — where a turn boundary is, and which turns may fold.
- *
- * Pattern: Pure functions over the window (no scope, no I/O, no clock).
- * Role:    core/ layer. The whole safety argument of compaction lives here:
- *          a fold that splits an assistant's `tool_use` from its
- *          `tool_result` produces a request the vendor rejects, and a fold
- *          that swallows an unanswered question destroys the referent of the
- *          answer that has not arrived yet.
- * Emits:   N/A.
- *
- * Testable on its own — see `test/core/agent/compaction-turns.test.ts`.
- */
-import type { LLMMessage } from '../../../adapters/types.js';
-import type { FoldRefusal, FoldRefusalReason } 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 fold 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 foldability decision needs beyond the turn itself. */
-export interface FoldabilityContext {
-    /** 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 fold, 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, ctx: FoldabilityContext): FoldRefusalReason | undefined;
-/** The span a fold will take, plus every refusal it had to name to get there. */
-export interface FoldPlan {
-    /** First turn index in the fold span; -1 when nothing folds. */
-    readonly from: number;
-    /** Last turn index in the fold span (inclusive); -1 when nothing folds. */
-    readonly to: number;
-    readonly refusals: readonly FoldRefusal[];
-}
-/**
- * Choose the fold span: the LONGEST CONTIGUOUS run of foldable candidate
- * turns, starting at the oldest foldable 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 unfoldable turn, that turn would end up after a summary of things that
- * happened before it. So an unfoldable turn at the front is stepped over (the
- * fold "takes the next oldest instead") and an unfoldable turn in the middle
- * ends the span. Everything not folded keeps its position.
- *
- * @param turns         the window's turn segmentation
- * @param keepRecent    how many trailing turns are off-limits
- * @param ctx           foldability inputs
- * @param isSummaryTurn true for a turn that is a summary a prior fold wrote
- */
-export declare function planFold(turns: readonly Turn[], keepRecent: number, ctx: FoldabilityContext, isSummaryTurn: (turn: Turn) => boolean): FoldPlan;
-/** Total characters of message content in a window. Exact; not tokens. */
-export declare function windowChars(history: readonly LLMMessage[]): number;

package/dist/esm/core/agent/compaction/turns.js.map

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

package/dist/esm/core/agent/compaction/types.d.ts

@@ -1,148 +0,0 @@
-/**
- * compaction/types — the public shape of `.compaction()` and the record it
- * writes into the ledger.
- *
- * Pattern: Value objects (no behavior) + one resolved-config type.
- * Role:    core/ layer. The law this feature exists to keep is stated once,
- *          here, because every other file in this folder implements a piece
- *          of it: **compaction edits the WINDOW, never the LEDGER.**
- * Emits:   N/A (types only).
- *
- * The window is `scope.history` — the array `call-llm` hands the provider.
- * The ledger is footprintjs's commit log, which is append-only: the turns a
- * fold removes from the window were committed by `seed#0` / `tool-calls#N`
- * BEFORE the fold and stay in those bundles byte-identical forever. A fold
- * therefore cannot destroy history even in principle; it can only stop
- * re-sending it. The summary is a CLAIM about the past, so it is filed as a
- * claim — its own recorded step, naming every `runtimeStageId` it folded.
- */
-import type { LLMProvider } from '../../../adapters/types.js';
-/**
- * What `.compaction({...})` accepts.
- *
- * @example
- * ```ts
- * const agent = Agent.create({ provider: anthropic(), model: 'claude-sonnet-4-5' })
- *   .compaction({
- *     thresholdTokens: 120_000,
- *     summarizer: anthropic(),          // usually the cheap one
- *     model: 'claude-haiku-4-5',
- *     keepRecentTurns: 6,
- *   })
- *   .build();
- * ```
- */
-export interface CompactionOptions {
-    /**
-     * Fold when the LAST call's adapter-reported input tokens exceed this.
-     *
-     * REQUIRED, with no default. A default budget here would be a number the
-     * library invented for a window whose size only the consumer's model and
-     * wallet know — and every run would silently inherit it.
-     */
-    readonly thresholdTokens: number;
-    /**
-     * How many of the most recent turns are never folded. Default 6.
-     *
-     * The recent turns are what the model is actually reasoning over; folding
-     * them is how a compacting agent loses the thread.
-     */
-    readonly keepRecentTurns?: number;
-    /**
-     * The provider that writes the summary. Explicitly chosen — the library
-     * never quietly bills your main model for compaction.
-     */
-    readonly summarizer: LLMProvider;
-    /**
-     * Model id for the summarizer call. Defaults to the agent's own model, so
-     * `summarizer: anthropic()` alone works; name a cheap model to spend less.
-     */
-    readonly model?: string;
-}
-/** Resolved form — defaults applied at build time, validated once. */
-export interface ResolvedCompaction {
-    readonly thresholdTokens: number;
-    readonly keepRecentTurns: number;
-    readonly summarizer: LLMProvider;
-    readonly model: string | undefined;
-}
-/**
- * Why a turn refused to fold. Every one of these is NAMED in the commit —
- * a fold that took less than it could have has to say why, or the next
- * person debugging an over-budget window has to guess.
- */
-export type FoldRefusalReason = 
-/** The turn holds a `role: 'system'` message. The envelope never folds. */
-'system-envelope'
-/**
- * An assistant `tool_use` in this turn has no matching `tool_result` in the
- * window. Folding an unanswered question destroys the answer's referent —
- * and the referent may still arrive (a paused run resumes).
- */
- | 'unresolved-tool-call'
-/** The turn holds the tool call this run is currently paused on. */
- | 'paused-tool'
-/** The turn holds a tool call waiting on a human check-in decision. */
- | 'pending-check-in'
-/** Inside `keepRecentTurns` — the recent window is never a candidate. */
- | 'inside-keep-window'
-/**
- * The only foldable candidate is a summary a previous fold wrote. Folding a
- * summary of a summary with nothing new to add spends a call to lose detail.
- */
- | 'only-existing-summary'
-/** The summarizer threw. No fold this iteration; the window stays big. */
- | 'summarizer-failed'
-/**
- * The summary came back no smaller than the span it would replace, so the
- * fold was abandoned. Measured in chars on both sides — the same unit, an
- * exact comparison, not a token guess. Folding here would spend a call to
- * make the window BIGGER and lose the detail as well.
- */
- | 'summary-not-smaller';
-/** One named refusal, positioned so a reader can find the turn. */
-export interface FoldRefusal {
-    readonly reason: FoldRefusalReason;
-    /** Index of the turn in this iteration's turn segmentation. */
-    readonly turnIndex: number;
-    /** Index of the turn's first message in the pre-fold window. */
-    readonly messageIndex: number;
-}
-/**
- * What one visit to the compaction stage put in the ledger. Appended to
- * `scope.compactions`, so the run's whole compaction story is one array in
- * the commit log — including the visits that folded NOTHING, which are the
- * interesting ones.
- *
- * On `windowChars*` vs tokens: the char counts are EXACT and measured here.
- * There is deliberately no `tokensAfter` — nothing can count the tokens of a
- * window that has not been sent yet, and inventing one would be exactly the
- * guess this feature exists to refuse. The honest "after" is the NEXT call's
- * `stream.llm_end` usage.
- */
-export interface CompactionRecord {
-    /** ReAct iteration this visit belongs to. */
-    readonly iteration: number;
-    /** Adapter-reported input tokens of the last call — what tripped the check. */
-    readonly measuredTokens: number;
-    /** The budget it was compared against. */
-    readonly thresholdTokens: number;
-    /** True when the measurement was over budget (a fold was attempted). */
-    readonly overBudget: boolean;
-    /** `runtimeStageId`s of the stages that appended the folded messages. */
-    readonly foldedStageIds: readonly string[];
-    /** How many messages left the window. */
-    readonly foldedMessageCount: number;
-    /** Window size in chars before / after this visit. Exact, and not tokens. */
-    readonly windowCharsBefore: number;
-    readonly windowCharsAfter: number;
-    /** Length of the summary text the summarizer produced (0 when none). */
-    readonly summaryChars: number;
-    /** What the summarizer call itself cost, when it reported usage. */
-    readonly summarizerTokens?: {
-        readonly input: number;
-        readonly output: number;
-    };
-    /** Every turn that refused to fold, named. */
-    readonly refusals: readonly FoldRefusal[];
-}

package/dist/esm/core/agent/compaction/types.js

@@ -1,20 +0,0 @@
-/**
- * compaction/types — the public shape of `.compaction()` and the record it
- * writes into the ledger.
- *
- * Pattern: Value objects (no behavior) + one resolved-config type.
- * Role:    core/ layer. The law this feature exists to keep is stated once,
- *          here, because every other file in this folder implements a piece
- *          of it: **compaction edits the WINDOW, never the LEDGER.**
- * Emits:   N/A (types only).
- *
- * The window is `scope.history` — the array `call-llm` hands the provider.
- * The ledger is footprintjs's commit log, which is append-only: the turns a
- * fold removes from the window were committed by `seed#0` / `tool-calls#N`
- * BEFORE the fold and stay in those bundles byte-identical forever. A fold
- * therefore cannot destroy history even in principle; it can only stop
- * re-sending it. The summary is a CLAIM about the past, so it is filed as a
- * claim — its own recorded step, naming every `runtimeStageId` it folded.
- */
-export {};
-//# sourceMappingURL=types.js.map

package/dist/esm/core/agent/compaction/types.js.map

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

package/dist/esm/core/agent/stages/compact.d.ts

@@ -1,59 +0,0 @@
-/**
- * compact — the loop-head stage that keeps the window inside budget.
- *
- * Reads the last call's ADAPTER-REPORTED input tokens from the compaction
- * meter and, when they exceed `thresholdTokens`, hands the window to a window
- * strategy. Runs once per ReAct iteration boundary, as the loop target, so
- * everything downstream in the turn — the injection engine's triggers, all
- * three context slots, and the wire itself — sees ONE window. No component
- * gets a different past than the model does.
- *
- * The law: **it edits the window, never the ledger.** The turns a fold removes
- * were committed by `seed#0` / `tool-calls#N` before this stage ran and stay
- * in those bundles byte-identical; footprintjs's commit log is append-only, so
- * a fold cannot erase history even in principle. What it can do is stop
- * re-sending it — and say so, in its own commit, naming every runtimeStageId
- * it folded. A compacted run is still a provable run.
- *
- * This file is deliberately all WIRING. The decision — what the window should
- * become — lives behind `WindowStrategy` (compaction/strategy.ts, internal),
- * so the duty to record, emit and cost what happened stays in exactly one
- * place instead of being re-implemented per strategy. `.compaction()` is the
- * only strategy that ships.
- *
- * Emits (existing vocabulary only — no new event types):
- *   agentfootprint.context.evicted          — one per message leaving the window
- *   agentfootprint.context.budget_pressure  — one per over-budget visit
- *   agentfootprint.cost.tick                — when a pricingTable is set: the
- *                                             summarizer's call is a real
- *                                             billed call and counts
- *
- * The summarizer call is deliberately NOT bracketed with
- * `stream.llm_start` / `llm_end`: those carry an `iteration` and every
- * consumer pairs them by it, so a second bracket inside one iteration would
- * corrupt the pairing. Its cost rides the cost channel and its tokens are
- * recorded in the commit instead.
- */
-import type { TypedScope } from 'footprintjs';
-import type { PricingTable } from '../../../adapters/types.js';
-import type { CompactionMeterHandle } from '../../../recorders/core/CompactionMeter.js';
-import type { ResolvedCompaction } from '../compaction/types.js';
-import type { AgentState } from '../types.js';
-export interface CompactStageDeps {
-    /** Resolved `.compaction()` config (defaults already applied). */
-    readonly config: ResolvedCompaction;
-    /** The meter this stage reads. Attached inline by `Agent.createExecutor`. */
-    readonly meter: CompactionMeterHandle;
-    /** The agent's own model — the summarizer's default. */
-    readonly defaultModel: string;
-    /** The MAIN provider's name, for the unmeasurable refusal. */
-    readonly providerName: string;
-    /** Optional pricing adapter, so a summarizer call is costed like any other. */
-    readonly pricingTable?: PricingTable;
-    /** Optional cumulative USD cap per run. */
-    readonly costBudget?: number;
-    /** Injectable clock (tests pin survivalMs). */
-    readonly now?: () => number;
-}
-/** Build the compaction stage function. */
-export declare function buildCompactStage(deps: CompactStageDeps): (scope: TypedScope<AgentState>) => Promise<void>;