agentfootprint 8.1.0 → 8.2.0

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

@@ -0,0 +1,90 @@
+/**
+ * window/folded — join a summary sitting in a conversation back to what it
+ * stands for.
+ *
+ * Pattern: Pure lookup over recorded facts. No I/O, no inference.
+ * Role:    core/ layer, and the ONE public door onto retained originals.
+ * Emits:   N/A.
+ *
+ * ── Why a fingerprint and not an index ──────────────────────────────────────
+ * The obvious join key is "the summary is at `history[3]`". It is also wrong.
+ * A later fold swallows the span that CONTAINS an earlier summary, and every
+ * index after it moves; a conversation that folded four times would need its
+ * stored indices rewritten on every fold, and any reader holding an old one
+ * would silently be pointing at somebody else's message.
+ *
+ * So the join key is a fingerprint of the summary message's full content —
+ * authored frame included. Three things follow, and all three are the point:
+ *
+ *   • it costs NO extra bytes on the wire (no id token planted in the frame);
+ *   • it survives JSON, storage, and being read by a runtime that has never
+ *     heard of this function;
+ *   • it cannot be FORGED. A model that writes a message opening with the
+ *     frame's own words produces different content, therefore a different
+ *     fingerprint, therefore no match — `isCompactedSummary` alone says "this
+ *     LOOKS like a frame", and this says "this IS the frame of a fold that was
+ *     recorded". The two answers are different questions and the gap between
+ *     them is exactly where a forgery would live.
+ *
+ * ── Absent is an answer ─────────────────────────────────────────────────────
+ * `undefined` means "no fold was recorded for this message" and never "there
+ * were no originals". A conversation stored by 8.1 has summaries and no spans
+ * at all; one folded under `retain: 'discard'` has a span whose `messages` is
+ * absent. Those are three different facts and the caller can tell them apart:
+ * no span, a span with no messages, a span with messages.
+ */
+import type { LLMMessage } from '../../../adapters/types.js';
+import type { FoldedSpan } from './types.js';
+/**
+ * The join key for one summary message: a fingerprint of its whole content.
+ *
+ * @internal Consumers join through {@link foldedSpanFor}; this is exported for
+ *   the strategy that stamps the span and for tests that pin the two agree.
+ */
+export declare function summaryFingerprint(content: string): string;
+/**
+ * The smallest thing that can answer "what did this conversation fold?".
+ *
+ * Structural rather than `AgentRunCheckpoint` on purpose: it also fits a
+ * paused run's `conversation`, a hand-built fixture, and anything a consumer
+ * pulled out of their own store — and it keeps this file from importing the
+ * checkpoint module, which imports this one's sibling types.
+ */
+export interface FoldedConversation {
+    readonly folded?: readonly FoldedSpan[];
+}
+/**
+ * What one summary message in a conversation stands for.
+ *
+ * Hand it the conversation you stored and a message out of its `history`; get
+ * back the fold that produced that message, with the original messages when
+ * the policy retained them.
+ *
+ * @returns the span, or `undefined` when this conversation recorded no fold
+ *   for this message — see "Absent is an answer" above.
+ *
+ * @example  Show a user what the agent actually saw last week
+ * ```ts
+ * import { foldedSpanFor, isCompactedSummary } from 'agentfootprint';
+ *
+ * const conversation = readEnvelope(await sessions.hydrate(sessionId));
+ * for (const message of conversation.history) {
+ *   if (!isCompactedSummary(message)) continue;
+ *   const span = foldedSpanFor(conversation, message);
+ *   console.log(`summary of ${span?.messageCount ?? '?'} messages`);
+ *   for (const original of span?.messages ?? []) {
+ *     console.log(`  ${original.role}: ${original.content}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function foldedSpanFor(conversation: FoldedConversation, message: LLMMessage): FoldedSpan | undefined;
+/**
+ * Every message this conversation ever folded, oldest fold first, flattened.
+ *
+ * The transcript-shaped answer to `foldedSpanFor`'s message-shaped one: what
+ * a support view prints when somebody asks what the agent was told before the
+ * summaries. Spans that were discarded contribute nothing — they have nothing
+ * to contribute, and `foldedSpanFor` is where you find out that they existed.
+ */
+export declare function foldedMessages(conversation: FoldedConversation): readonly LLMMessage[];

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

@@ -0,0 +1,92 @@
+/**
+ * window/folded — join a summary sitting in a conversation back to what it
+ * stands for.
+ *
+ * Pattern: Pure lookup over recorded facts. No I/O, no inference.
+ * Role:    core/ layer, and the ONE public door onto retained originals.
+ * Emits:   N/A.
+ *
+ * ── Why a fingerprint and not an index ──────────────────────────────────────
+ * The obvious join key is "the summary is at `history[3]`". It is also wrong.
+ * A later fold swallows the span that CONTAINS an earlier summary, and every
+ * index after it moves; a conversation that folded four times would need its
+ * stored indices rewritten on every fold, and any reader holding an old one
+ * would silently be pointing at somebody else's message.
+ *
+ * So the join key is a fingerprint of the summary message's full content —
+ * authored frame included. Three things follow, and all three are the point:
+ *
+ *   • it costs NO extra bytes on the wire (no id token planted in the frame);
+ *   • it survives JSON, storage, and being read by a runtime that has never
+ *     heard of this function;
+ *   • it cannot be FORGED. A model that writes a message opening with the
+ *     frame's own words produces different content, therefore a different
+ *     fingerprint, therefore no match — `isCompactedSummary` alone says "this
+ *     LOOKS like a frame", and this says "this IS the frame of a fold that was
+ *     recorded". The two answers are different questions and the gap between
+ *     them is exactly where a forgery would live.
+ *
+ * ── Absent is an answer ─────────────────────────────────────────────────────
+ * `undefined` means "no fold was recorded for this message" and never "there
+ * were no originals". A conversation stored by 8.1 has summaries and no spans
+ * at all; one folded under `retain: 'discard'` has a span whose `messages` is
+ * absent. Those are three different facts and the caller can tell them apart:
+ * no span, a span with no messages, a span with messages.
+ */
+import { fnv1a } from '../../slots/helpers.js';
+/**
+ * The join key for one summary message: a fingerprint of its whole content.
+ *
+ * @internal Consumers join through {@link foldedSpanFor}; this is exported for
+ *   the strategy that stamps the span and for tests that pin the two agree.
+ */
+export function summaryFingerprint(content) {
+    return fnv1a(content);
+}
+/**
+ * What one summary message in a conversation stands for.
+ *
+ * Hand it the conversation you stored and a message out of its `history`; get
+ * back the fold that produced that message, with the original messages when
+ * the policy retained them.
+ *
+ * @returns the span, or `undefined` when this conversation recorded no fold
+ *   for this message — see "Absent is an answer" above.
+ *
+ * @example  Show a user what the agent actually saw last week
+ * ```ts
+ * import { foldedSpanFor, isCompactedSummary } from 'agentfootprint';
+ *
+ * const conversation = readEnvelope(await sessions.hydrate(sessionId));
+ * for (const message of conversation.history) {
+ *   if (!isCompactedSummary(message)) continue;
+ *   const span = foldedSpanFor(conversation, message);
+ *   console.log(`summary of ${span?.messageCount ?? '?'} messages`);
+ *   for (const original of span?.messages ?? []) {
+ *     console.log(`  ${original.role}: ${original.content}`);
+ *   }
+ * }
+ * ```
+ */
+export function foldedSpanFor(conversation, message) {
+    const spans = conversation.folded;
+    if (spans === undefined || spans.length === 0)
+        return undefined;
+    const fingerprint = summaryFingerprint(message.content);
+    return spans.find((span) => span.summaryFingerprint === fingerprint);
+}
+/**
+ * Every message this conversation ever folded, oldest fold first, flattened.
+ *
+ * The transcript-shaped answer to `foldedSpanFor`'s message-shaped one: what
+ * a support view prints when somebody asks what the agent was told before the
+ * summaries. Spans that were discarded contribute nothing — they have nothing
+ * to contribute, and `foldedSpanFor` is where you find out that they existed.
+ */
+export function foldedMessages(conversation) {
+    const out = [];
+    for (const span of conversation.folded ?? [])
+        out.push(...(span.messages ?? []));
+    return out;
+}
+//# sourceMappingURL=folded.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"folded.js","sourceRoot":"","sources":["../../../../../src/core/agent/window/folded.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAI/C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC;AACxB,CAAC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,aAAa,CAC3B,YAAgC,EAChC,OAAmB;IAEnB,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChE,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,kBAAkB,KAAK,WAAW,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,YAAgC;IAC7D,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,MAAM,IAAI,EAAE;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;IACjF,OAAO,GAAG,CAAC;AACb,CAAC"}

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

@@ -8,6 +8,11 @@
  * is a claim about the past, so this library files it as a claim — not as the
  * past. A drop is an absence, and it is named the same way.
  *
+ * A commit log lives as long as the process. A conversation lives longer, so
+ * `.compaction({ retain })` also carries the folded originals on the
+ * conversation checkpoint — `foldedSpanFor(conversation, message)` is the door
+ * back to them, in this process or the one after the deploy.
+ *
  * Three strategies ship, all sharing one turn segmentation and one refusal
  * engine:
  *   `summarizeOldest`  fold the oldest span into a summary (`.compaction()`)
@@ -17,7 +22,8 @@
  * Public surface (re-exported from the package root).
  */
 export { CompactionUnmeasurableError } from './errors.js';
-export type { CompactionOptions, CompactionRecord, FoldRefusal, FoldRefusalReason, ResolvedCompaction, SlidingWindowOptions, SlidingWindowRecord, TokenBudgetOptions, TokenBudgetRecord, WindowRecord, WindowRefusal, WindowRefusalReason, } from './types.js';
+export type { CompactionOptions, CompactionRecord, CompactionRetention, FoldedSpan, FoldRefusal, FoldRefusalReason, ResolvedCompaction, SlidingWindowOptions, SlidingWindowRecord, TokenBudgetOptions, TokenBudgetRecord, WindowRecord, WindowRefusal, WindowRefusalReason, } from './types.js';
+export { foldedMessages, foldedSpanFor, type FoldedConversation } from './folded.js';
 export type { RemovalFacts, WindowEviction, WindowStrategy, WindowStrategyInput, WindowStrategyResult, } from './strategy.js';
 export type { RemovalPlan, Turn } from './turns.js';
 export { COMPACTED_FRAME_PREFIX, isCompactedSummary } from './summarize.js';

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

@@ -8,6 +8,11 @@
  * is a claim about the past, so this library files it as a claim — not as the
  * past. A drop is an absence, and it is named the same way.
  *
+ * A commit log lives as long as the process. A conversation lives longer, so
+ * `.compaction({ retain })` also carries the folded originals on the
+ * conversation checkpoint — `foldedSpanFor(conversation, message)` is the door
+ * back to them, in this process or the one after the deploy.
+ *
  * Three strategies ship, all sharing one turn segmentation and one refusal
  * engine:
  *   `summarizeOldest`  fold the oldest span into a summary (`.compaction()`)
@@ -17,6 +22,7 @@
  * Public surface (re-exported from the package root).
  */
 export { CompactionUnmeasurableError } from './errors.js';
+export { foldedMessages, foldedSpanFor } from './folded.js';
 export { COMPACTED_FRAME_PREFIX, isCompactedSummary } from './summarize.js';
 export { DROP_NOTICE_PREFIX, isDropNotice } from './notice.js';
 export { summarizeOldest } from './strategies/summarizeOldest.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/core/agent/window/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAuB1D,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/core/agent/window/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAiB1D,OAAO,EAAE,cAAc,EAAE,aAAa,EAA2B,MAAM,aAAa,CAAC;AASrF,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC"}

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

@@ -13,9 +13,15 @@
  * 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';
+import type { CompactionOptions, CompactionRetention, ResolvedCompaction, SlidingWindowOptions, TokenBudgetOptions } from './types.js';
 /** Default depth of the "never touch this" recent window. */
 export declare const DEFAULT_KEEP_RECENT_TURNS = 6;
+/**
+ * What happens to folded messages when nobody said. The originals ride with
+ * the conversation: losing them has to be a choice somebody typed, not a
+ * default they inherited.
+ */
+export declare const DEFAULT_RETENTION: CompactionRetention;
 /**
  * Validate `.compaction()` / `summarizeOldest()` options.
  *

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

@@ -15,6 +15,13 @@
  */
 /** Default depth of the "never touch this" recent window. */
 export const DEFAULT_KEEP_RECENT_TURNS = 6;
+/**
+ * What happens to folded messages when nobody said. The originals ride with
+ * the conversation: losing them has to be a choice somebody typed, not a
+ * default they inherited.
+ */
+export const DEFAULT_RETENTION = 'conversation';
+const RETENTIONS = ['conversation', 'discard'];
 function requireObject(options, label, shape) {
     if (options === null || typeof options !== 'object') {
         throw new Error(`${label}: expected an options object (${shape}), got ${typeof options}.`);
@@ -43,7 +50,7 @@ function requireKeepRecentTurns(keepRecentTurns, label) {
  */
 export function resolveCompactionOptions(options, label) {
     requireObject(options, label, '{ thresholdTokens, summarizer, ... }');
-    const { thresholdTokens, summarizer, keepRecentTurns, model } = options;
+    const { thresholdTokens, summarizer, keepRecentTurns, model, retain } = options;
     requireThreshold(thresholdTokens, label);
     if (summarizer === null ||
         typeof summarizer !== 'object' ||
@@ -57,11 +64,20 @@ export function resolveCompactionOptions(options, 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)}.`);
     }
+    if (retain !== undefined && !RETENTIONS.includes(retain)) {
+        throw new Error(`${label}: retain must be ${RETENTIONS.map((r) => `'${r}'`).join(' or ')}, got ` +
+            `${String(retain)}. It decides what happens to the messages a fold removes: ` +
+            `'conversation' (the default) carries them on the conversation checkpoint so a ` +
+            `restart can still produce them, and 'discard' does not. A value this library does ` +
+            `not recognise is refused rather than treated as one of them — guessing here would ` +
+            `mean guessing whether to keep somebody's transcript.`);
+    }
     return {
         thresholdTokens,
         keepRecentTurns: keepRecentTurns ?? DEFAULT_KEEP_RECENT_TURNS,
         summarizer,
         model,
+        retain: retain ?? DEFAULT_RETENTION,
     };
 }
 /** Validate `slidingWindow()` options. */

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

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

@@ -10,8 +10,10 @@
  * 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.
+ * a summary is a claim ABOUT the past, and the past itself stays. In the
+ * commit log for as long as the process lives, and — since 8.2, under
+ * `retain: 'conversation'` — on the conversation checkpoint for as long as
+ * the conversation does, which is the half a standing agent actually needs.
  *
  * Everything it decides, it explains. Every engaged path returns a record —
  * including the paths that change nothing, which are the ones a person

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

@@ -10,14 +10,17 @@
  * 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.
+ * a summary is a claim ABOUT the past, and the past itself stays. In the
+ * commit log for as long as the process lives, and — since 8.2, under
+ * `retain: 'conversation'` — on the conversation checkpoint for as long as
+ * the conversation does, which is the half a standing agent actually needs.
  *
  * Everything it decides, it explains. Every engaged path returns a record —
  * including the paths that change nothing, which are the ones a person
  * debugging an over-budget window actually needs.
  */
 import { CompactionUnmeasurableError } from '../errors.js';
+import { summaryFingerprint } from '../folded.js';
 import { resolveCompactionOptions } from '../options.js';
 import { indexRange } from '../removal.js';
 import { buildSummaryMessage, isCompactedSummary, runSummarizer } from '../summarize.js';
@@ -122,6 +125,7 @@ export function summarizeOldest(options) {
                 foldedMessageCount: span.length,
                 iteration,
                 model,
+                retain: config.retain,
             });
             const spend = { model, usage: summary.usage };
             // Would the fold actually help? A summary plus its authored frame can be
@@ -140,6 +144,24 @@ export function summarizeOldest(options) {
             const foldedAtMs = input.now();
             const facts = input.removalFacts(indexRange(spanStart, spanEnd), foldedAtMs);
             const window = [...head, summaryMessage, ...tail];
+            // The durable half. It rides the SAME result the window change rides,
+            // so the stage commits both together — there is no ordering in which
+            // the messages leave and the record of what they were does not follow.
+            // Under 'discard' the span is still filed: a discard is an absence, and
+            // this family files absences the same way it files claims.
+            const foldedSpan = {
+                summaryFingerprint: summaryFingerprint(summaryMessage.content),
+                runId: input.runId,
+                iteration,
+                foldedAtMs,
+                model,
+                messageCount: span.length,
+                removedStageIds: facts.removedStageIds,
+                retained: config.retain,
+                // Detached before it is handed on: `history` came off a live scope and
+                // a stored conversation must never hold a reference into the heap.
+                ...(config.retain === 'conversation' && { messages: span.map((m) => ({ ...m })) }),
+            };
             const record = {
                 ...base,
                 removedStageIds: facts.removedStageIds,
@@ -161,6 +183,7 @@ export function summarizeOldest(options) {
                 },
                 record,
                 evictions: facts.evictions,
+                folded: [foldedSpan],
                 budgetPressure: {
                     capTokens: config.thresholdTokens,
                     projectedTokens: measured.input,

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

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

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

@@ -39,7 +39,7 @@
  */
 import type { LLMMessage } from '../../../adapters/types.js';
 import type { Turn, RemovalPlan } from './turns.js';
-import type { WindowRecord } from './types.js';
+import type { FoldedSpan, 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. */
@@ -76,6 +76,16 @@ export interface WindowStrategyInput {
     } | undefined;
     /** The ReAct iteration this decision belongs to. */
     readonly iteration: number;
+    /**
+     * The run this decision belongs to.
+     *
+     * A strategy that retains what it removed has to name the run whose commit
+     * log held it — that is the honest answer to "where else could I have found
+     * this?", and the answer is "nowhere, once that process ended", which is the
+     * whole reason retention exists. `'unknown'` when the runtime could not name
+     * the run, never a fabricated id.
+     */
+    readonly runId: string;
     /** 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. */
@@ -128,6 +138,21 @@ export interface WindowStrategyResult {
     readonly record: WindowRecord;
     /** Messages that left the window, for `context.evicted`. */
     readonly evictions: readonly WindowEviction[];
+    /**
+     * Spans this visit removed, in the form that OUTLIVES the process: appended
+     * to the conversation checkpoint, so a restart can still say what a summary
+     * stands for — and, under `retain: 'conversation'`, produce it verbatim.
+     *
+     * OMIT IT unless your strategy replaced messages with something that stands
+     * for them. `summarizeOldest` fills it because a summary is a claim that
+     * needs its evidence; the drop strategies do not, because a drop replaces
+     * nothing and its authored notice claims nothing.
+     *
+     * The stage writes these in the SAME commit as the window change, so there
+     * is no state in which messages left the window and the record of what they
+     * were did not follow them.
+     */
+    readonly folded?: readonly FoldedSpan[];
     /**
      * The budget reading to report on `agentfootprint.context.budget_pressure`.
      *

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

@@ -17,9 +17,15 @@
  *
  *          The frame is authored. The summary is data. Neither can become
  *          the other.
+ *
+ *          A third rule joined them in 8.2: the frame may only claim what is
+ *          true. It names where the folded messages went, and it reads that
+ *          from the resolved retention policy rather than asserting a
+ *          constant — see {@link retentionSentence}.
  * Emits:   N/A (the stage emits; this file only builds and calls).
  */
 import type { LLMMessage, LLMProvider, LLMResponse } from '../../../adapters/types.js';
+import type { CompactionRetention } from './types.js';
 /** Opening of the authored label. Stable — tests and readers match on it. */
 export declare const COMPACTED_FRAME_PREFIX = "[compacted history";
 /**
@@ -39,11 +45,16 @@ export declare function renderTranscript(messages: readonly LLMMessage[]): strin
  * The label is written by this function and always comes first. `summary` is
  * appended to it verbatim: the library never edits model output, and it never
  * lets model output speak in the library's voice either.
+ *
+ * The label states the retention policy, and states it truthfully — see
+ * {@link retentionSentence}. `COMPACTED_FRAME_PREFIX` is unchanged: it is what
+ * every reader and every test matches on, and it stays put.
  */
 export declare function buildSummaryMessage(summary: string, facts: {
     readonly foldedMessageCount: number;
     readonly iteration: number;
     readonly model: string;
+    readonly retain: CompactionRetention;
 }): LLMMessage;
 /** True when this message is a frame a previous fold wrote. */
 export declare function isCompactedSummary(msg: LLMMessage | undefined): boolean;

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

@@ -17,6 +17,11 @@
  *
  *          The frame is authored. The summary is data. Neither can become
  *          the other.
+ *
+ *          A third rule joined them in 8.2: the frame may only claim what is
+ *          true. It names where the folded messages went, and it reads that
+ *          from the resolved retention policy rather than asserting a
+ *          constant — see {@link retentionSentence}.
  * Emits:   N/A (the stage emits; this file only builds and calls).
  */
 /** Opening of the authored label. Stable — tests and readers match on it. */
@@ -56,6 +61,23 @@ function renderMessage(msg) {
 export function renderTranscript(messages) {
     return [TRANSCRIPT_OPEN, ...messages.map(renderMessage), TRANSCRIPT_CLOSE].join('\n');
 }
+/**
+ * Where the folded messages went, said in the frame itself.
+ *
+ * Through 8.1 this sentence was a constant: *"The folded messages are retained
+ * verbatim in this run's commit log."* True inside the process, and false the
+ * moment the run ended — which is exactly when a standing agent reads it back
+ * out of storage. A library asserting something false inside the model's own
+ * context is worse than saying nothing, so the sentence is now written FROM
+ * the resolved retention policy and can only say what actually happened.
+ */
+function retentionSentence(retain) {
+    return retain === 'conversation'
+        ? `The folded messages are retained verbatim with this conversation and can be produced ` +
+            `on request.`
+        : `The folded messages were not retained beyond the run that folded them; only this ` +
+            `summary carries them forward.`;
+}
 /**
  * Build the message that replaces the folded span IN THE WINDOW.
  *
@@ -65,12 +87,16 @@ export function renderTranscript(messages) {
  * The label is written by this function and always comes first. `summary` is
  * appended to it verbatim: the library never edits model output, and it never
  * lets model output speak in the library's voice either.
+ *
+ * The label states the retention policy, and states it truthfully — see
+ * {@link retentionSentence}. `COMPACTED_FRAME_PREFIX` is unchanged: it is what
+ * every reader and every test matches on, and it stays put.
  */
 export function buildSummaryMessage(summary, facts) {
     const label = `${COMPACTED_FRAME_PREFIX} — ${facts.foldedMessageCount} earlier message(s) were folded ` +
         `out of this window at iteration ${facts.iteration}. The text after this line is a SUMMARY ` +
         `written by ${facts.model}; it is a claim about the conversation, not the conversation. ` +
-        `The folded messages are retained verbatim in this run's commit log.]`;
+        `${retentionSentence(facts.retain)}]`;
     return { role: 'user', content: `${label}\n\n${summary}` };
 }
 /** True when this message is a frame a previous fold wrote. */

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

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