agentfootprint 7.14.0 → 7.16.0

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

@@ -0,0 +1,145 @@
+/**
+ * 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`.
+ */
+/**
+ * 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 function segmentTurns(history) {
+    const turns = [];
+    let current = [];
+    let start = 0;
+    const flush = () => {
+        if (current.length === 0)
+            return;
+        turns.push({ index: turns.length, start, length: current.length, messages: current });
+        current = [];
+    };
+    for (let i = 0; i < history.length; i++) {
+        const msg = history[i];
+        if (msg.role !== 'tool' || current.length === 0) {
+            flush();
+            start = i;
+        }
+        current.push(msg);
+    }
+    flush();
+    return turns;
+}
+/** Every tool_call id that has a matching `role: 'tool'` message. */
+export function answeredCallIds(history) {
+    const answered = new Set();
+    for (const msg of history) {
+        if (msg.role === 'tool' && msg.toolCallId)
+            answered.add(msg.toolCallId);
+    }
+    return answered;
+}
+/**
+ * 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 function refusalFor(turn, ctx) {
+    for (const msg of turn.messages) {
+        if (msg.role === 'system')
+            return 'system-envelope';
+    }
+    const paused = ctx.pausedToolCallId;
+    if (paused !== undefined && paused.length > 0) {
+        for (const msg of turn.messages) {
+            const holdsPaused = msg.toolCallId === paused || (msg.toolCalls ?? []).some((tc) => tc.id === paused);
+            if (holdsPaused)
+                return ctx.pausedCheckIn === true ? 'pending-check-in' : 'paused-tool';
+        }
+    }
+    for (const msg of turn.messages) {
+        for (const call of msg.toolCalls ?? []) {
+            if (!ctx.answeredCallIds.has(call.id))
+                return 'unresolved-tool-call';
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 function planFold(turns, keepRecent, ctx, isSummaryTurn) {
+    const refusals = [];
+    const candidateCount = Math.max(0, turns.length - keepRecent);
+    for (let i = candidateCount; i < turns.length; i++) {
+        const turn = turns[i];
+        refusals.push({ reason: 'inside-keep-window', turnIndex: i, messageIndex: turn.start });
+    }
+    if (candidateCount === 0)
+        return { from: -1, to: -1, refusals };
+    const before = [];
+    let from = -1;
+    let to = -1;
+    for (let i = 0; i < candidateCount; i++) {
+        const turn = turns[i];
+        const reason = refusalFor(turn, ctx);
+        if (reason === undefined) {
+            if (from === -1)
+                from = i;
+            to = i;
+            continue;
+        }
+        before.push({ reason, turnIndex: i, messageIndex: turn.start });
+        if (from !== -1)
+            break; // an unfoldable turn ENDS the span
+    }
+    // A span that is nothing but one existing summary is not worth a call:
+    // re-summarizing a summary spends tokens to lose detail and names nothing
+    // new. It becomes foldable again as soon as a real turn joins it.
+    if (from !== -1 && from === to && isSummaryTurn(turns[from])) {
+        return {
+            from: -1,
+            to: -1,
+            refusals: [
+                ...before,
+                { reason: 'only-existing-summary', turnIndex: from, messageIndex: turns[from].start },
+                ...refusals,
+            ],
+        };
+    }
+    return { from, to, refusals: [...before, ...refusals] };
+}
+/** Total characters of message content in a window. Exact; not tokens. */
+export function windowChars(history) {
+    let total = 0;
+    for (const msg of history)
+        total += msg.content.length;
+    return total;
+}
+//# sourceMappingURL=turns.js.map

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

@@ -0,0 +1 @@
+{"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

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

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

@@ -0,0 +1 @@
+{"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

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

package/dist/esm/core/agent/stages/compact.js

@@ -0,0 +1,126 @@
+/**
+ * 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 { typedEmit } from '../../../recorders/core/typedEmit.js';
+import { fnv1a } from '../../slots/helpers.js';
+import { emitCostTick } from '../../cost.js';
+import { CompactionUnmeasurableError } from '../compaction/errors.js';
+import { summarizeOldestStrategy } from '../compaction/strategy.js';
+import { answeredCallIds, segmentTurns } from '../compaction/turns.js';
+/** Build the compaction stage function. */
+export function buildCompactStage(deps) {
+    const { config, meter } = deps;
+    const now = deps.now ?? (() => Date.now());
+    const strategy = summarizeOldestStrategy(config, deps.defaultModel);
+    // Dedup latch for the strategy's warning: a summarizer that is down is down
+    // for the whole run, and one warning is a warning while ten is noise.
+    let warned = false;
+    return async (scope) => {
+        const metered = meter.lastCall();
+        // Iteration 1: nothing has been sent, so nothing has been counted. A
+        // compactor that acted here would be guessing, which is the one thing
+        // this feature refuses to do.
+        if (metered === undefined)
+            return;
+        if (metered.input === 0 && metered.output === 0) {
+            throw new CompactionUnmeasurableError(deps.providerName);
+        }
+        if (metered.input <= config.thresholdTokens)
+            return;
+        // ── Over budget. Ask the strategy what the window should become. ──
+        const history = (scope.history ?? []).slice();
+        const pausedToolCallId = scope.pausedToolCallId;
+        const foldability = {
+            answeredCallIds: answeredCallIds(history),
+            ...(pausedToolCallId !== undefined && { pausedToolCallId }),
+            ...(scope.pausedCheckIn === true && { pausedCheckIn: true }),
+        };
+        const result = await strategy.plan({
+            history,
+            turns: segmentTurns(history),
+            origins: meter.origins(),
+            measuredTokens: metered.input,
+            foldability,
+            iteration: scope.iteration ?? 1,
+            signal: scope.$getEnv?.()?.signal,
+            now,
+        });
+        // ── Apply. The stage owns every side effect. ─────────────────────
+        if (result.window !== undefined && result.rebase !== undefined) {
+            // Tell the meter before writing: the fold is the one window shape it
+            // cannot infer (the set trap JSON-round-trips every write).
+            meter.rebaseForFold(result.rebase.headCount, result.rebase.keptTailCount, now());
+            scope.history = result.window;
+        }
+        const prior = scope.compactions ?? [];
+        scope.compactions = [...prior, result.record];
+        // One eviction per message that left, in the slot vocabulary consumers
+        // already subscribe to. The hash uses the SAME formula the messages slot
+        // used to report the piece as injected, so evicted and injected refer to
+        // the same piece by the same name.
+        for (const eviction of result.evictions) {
+            const msg = history[eviction.index];
+            if (msg === undefined)
+                continue;
+            typedEmit(scope, 'agentfootprint.context.evicted', {
+                slot: 'messages',
+                contentHash: fnv1a(`${msg.role}:${eviction.index}:${msg.content}`),
+                reason: 'budget',
+                survivalMs: eviction.survivalMs,
+            });
+        }
+        // `capTokens` / `projectedTokens` are the historical names on
+        // `BudgetPressureRecord`; the slots measure them in chars, and this
+        // measures them in the tokens the decision was actually made on.
+        typedEmit(scope, 'agentfootprint.context.budget_pressure', {
+            slot: 'messages',
+            capTokens: config.thresholdTokens,
+            projectedTokens: metered.input,
+            overflowBy: Math.max(0, metered.input - config.thresholdTokens),
+            planAction: result.planAction,
+        });
+        // A summarizer call is real money. It counts against the same budget.
+        if (result.spend !== undefined) {
+            emitCostTick(scope, deps.pricingTable, deps.costBudget, result.spend.model, result.spend.usage);
+        }
+        if (result.warning !== undefined && !warned) {
+            warned = true;
+            // eslint-disable-next-line no-console
+            console.warn(`[agentfootprint compaction] ${result.warning}`);
+        }
+    };
+}
+//# sourceMappingURL=compact.js.map

package/dist/esm/core/agent/stages/compact.js.map

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

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

@@ -18,6 +18,7 @@ import type { CredentialProvider } from '../../identity/types.js';
 import type { ToolArgValidationMode } from './toolArgsValidation.js';
 import type { ThinkingBlock } from '../../thinking/types.js';
 import type { ReliabilityScope } from '../../reliability/types.js';
+import type { CompactionRecord } from './compaction/types.js';
 /**
  * Dials for the deferred observer queue (RFC-001) — only meaningful with
  * `observerDelivery: 'deferred'` (passing them without it throws at
@@ -407,6 +408,16 @@ export interface AgentState {
     /** The base system prompt `.configure()` resolved for THIS run, replacing
      *  `.system(...)`. Same rule: absent unless a resolver returned one. */
     resolvedInstructions?: string;
+    /** One record per OVER-BUDGET visit to the compaction stage — including the
+     *  visits that folded nothing, which are the interesting ones. Written only
+     *  by an agent built with `.compaction()`; absent otherwise, so an agent
+     *  without it commits exactly the keys it always did.
+     *
+     *  This array is the fold's half of the law: the window shrank, and the
+     *  ledger says which stages' messages left it, how many, and what the last
+     *  call actually measured. The messages themselves are untouched in the
+     *  commit bundles that wrote them. */
+    compactions?: readonly CompactionRecord[];
     /** Set when a `PermissionChecker` returns `{ result: 'halt', ... }`.
      *  `Agent.run()` reads these at the API boundary and throws a typed
      *  `PolicyHaltError` carrying the same context — the chart $break's