agentfootprint 8.0.0 → 8.2.0

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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"}

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

@@ -17,8 +17,14 @@
  * filed as a claim — its own recorded step, naming every `runtimeStageId` it
  * folded. A drop is an ABSENCE, and it is filed the same way: the record and
  * the eviction events name what left, by id.
+ *
+ * That law holds for as long as the PROCESS holds — a commit log is memory.
+ * A conversation outlives its process, so the durable half of the same law
+ * lives on the conversation checkpoint: `.compaction({ retain })` carries the
+ * folded originals there, beside the summary that stands for them. See
+ * {@link CompactionRetention} and {@link FoldedSpan}.
  */
-import type { LLMProvider } from '../../../adapters/types.js';
+import type { LLMMessage, LLMProvider } from '../../../adapters/types.js';
 /**
  * Why a turn refused to leave the window. Every one of these is NAMED in the
  * commit — a removal that took less than it could have has to say why, or the
@@ -169,6 +175,87 @@ export interface TokenBudgetRecord extends WindowRecord {
     /** How many recent turns were off-limits to this visit. */
     readonly keepRecentTurns: number;
 }
+/**
+ * What becomes of the messages a fold removes from the window.
+ *
+ * The commit log keeps them for as long as the PROCESS keeps them, and that
+ * is the whole of what 8.1 offered. A standing agent outlives its process, so
+ * "the folded turns are still in the commit log" stops being true the moment
+ * the run ends — and the summary sitting in the restored conversation went on
+ * claiming otherwise. Retention is the fix: the originals ride with the
+ * CONVERSATION, which is the thing that actually survives.
+ *
+ * The trade is stated rather than hidden: **compaction shrinks the wire, not
+ * the record.** A stored session grows as it folds. That is the right way
+ * round — the model's context window is scarce and a session row is not.
+ */
+export type CompactionRetention = 
+/**
+ * The folded messages ride with the conversation checkpoint, so a restart —
+ * a new process, a new machine, a deploy — can still produce them verbatim.
+ * The default: originals are never destroyed unless you say so.
+ */
+'conversation'
+/**
+ * The folded messages are NOT carried forward. The span is still recorded,
+ * naming what left and how much of it, because a discard is an absence and
+ * this family files absences the same way it files claims. Choose it when
+ * the conversation is the only thing you want to keep and the storage cost
+ * of the transcript is not worth paying.
+ */
+ | 'discard';
+/**
+ * One fold, as it survives the process: the summary's fingerprint, what it
+ * stands for, and — under `retain: 'conversation'` — the messages themselves.
+ *
+ * These accumulate on the conversation checkpoint across every turn and every
+ * restart, so a standing agent that folded week one in April can still produce
+ * week one in July.
+ *
+ * ## Joining a span to its summary
+ *
+ * By CONTENT FINGERPRINT, never by index: a later fold can swallow an earlier
+ * summary, and every index in the window moves when it does. {@link
+ * foldedSpanFor} does the join for you.
+ */
+export interface FoldedSpan {
+    /**
+     * Fingerprint of the summary message this span was folded into — the join
+     * key back to the message sitting in `history`.
+     *
+     * It is a hash of the message's full content (authored frame included), so
+     * it costs no extra bytes on the wire and cannot be forged by a summary that
+     * merely copies the frame's opening words: different content, different
+     * fingerprint, no match.
+     */
+    readonly summaryFingerprint: string;
+    /**
+     * The run whose commit log held these messages. Diagnostic, and the honest
+     * answer to "where else could I have found this?" — that log is gone with
+     * the process, which is why the messages are here.
+     */
+    readonly runId: string;
+    /** ReAct iteration the fold happened at, in that run. */
+    readonly iteration: number;
+    /** Wall clock of the fold. */
+    readonly foldedAtMs: number;
+    /** The model that wrote the summary — a claim's author is part of the claim. */
+    readonly model: string;
+    /** How many messages the summary stands for. Always recorded, both policies. */
+    readonly messageCount: number;
+    /** `runtimeStageId`s of the stages that appended those messages. */
+    readonly removedStageIds: readonly string[];
+    /** Which policy this fold ran under. */
+    readonly retained: CompactionRetention;
+    /**
+     * The folded messages, verbatim and in order. Present exactly when
+     * `retained` is `'conversation'`.
+     *
+     * Absent under `'discard'` — and absent is the honest shape there, rather
+     * than an empty array that reads like "there were none".
+     */
+    readonly messages?: readonly LLMMessage[];
+}
 /**
  * What `.compaction({...})` — and `summarizeOldest({...})` — accepts.
  *
@@ -210,6 +297,23 @@ export interface CompactionOptions {
      * `summarizer: anthropic()` alone works; name a cheap model to spend less.
      */
     readonly model?: string;
+    /**
+     * What happens to the messages a fold removes. Default `'conversation'` —
+     * they ride with the conversation checkpoint and survive the process.
+     *
+     * Pass `'discard'` to opt out. Nothing is ever destroyed silently: the only
+     * way to lose the originals is to name this.
+     *
+     * @example
+     * ```ts
+     * .compaction({
+     *   thresholdTokens: 120_000,
+     *   summarizer: anthropic(),
+     *   retain: 'conversation',   // the default, spelled out
+     * })
+     * ```
+     */
+    readonly retain?: CompactionRetention;
 }
 /** Resolved form — defaults applied at build time, validated once. */
 export interface ResolvedCompaction {
@@ -217,6 +321,7 @@ export interface ResolvedCompaction {
     readonly keepRecentTurns: number;
     readonly summarizer: LLMProvider;
     readonly model: string | undefined;
+    readonly retain: CompactionRetention;
 }
 /**
  * What `slidingWindow({...})` accepts.

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

@@ -17,6 +17,12 @@
  * filed as a claim — its own recorded step, naming every `runtimeStageId` it
  * folded. A drop is an ABSENCE, and it is filed the same way: the record and
  * the eviction events name what left, by id.
+ *
+ * That law holds for as long as the PROCESS holds — a commit log is memory.
+ * A conversation outlives its process, so the durable half of the same law
+ * lives on the conversation checkpoint: `.compaction({ retain })` carries the
+ * folded originals there, beside the summary that stands for them. See
+ * {@link CompactionRetention} and {@link FoldedSpan}.
  */
 export {};
 //# sourceMappingURL=types.js.map

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

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

package/dist/esm/core/runCheckpoint.d.ts

@@ -54,6 +54,7 @@
  *          DFS stage).
  */
 import type { LLMMessage } from '../adapters/types.js';
+import type { FoldedSpan } from './agent/window/types.js';
 /**
  * JSON-serializable checkpoint of an in-progress agent run. Persist
  * to ANY durable store (Redis / Postgres / S3 / disk / queue) and
@@ -85,6 +86,29 @@ export interface AgentRunCheckpoint {
     };
     /** Wall-clock when the checkpoint was captured. Diagnostic only. */
     readonly checkpointedAt: number;
+    /**
+     * Every span this conversation folded into a summary, oldest first — what
+     * makes a compacted conversation still a provable one after the process
+     * that compacted it is gone.
+     *
+     * Written by `.compaction()`; absent on a conversation that never folded,
+     * and absent on one stored by a runtime older than 8.2. Under the default
+     * `retain: 'conversation'` each span carries the folded messages verbatim;
+     * under `retain: 'discard'` the span is still here, naming what left, and
+     * only `messages` is absent.
+     *
+     * Join a summary in {@link history} to its span with `foldedSpanFor(...)` —
+     * by content fingerprint, never by index, because a later fold moves every
+     * index after it.
+     *
+     * **Version 1 still, deliberately.** An optional field is not a format
+     * change: a runtime that has never heard of `folded` reads this checkpoint,
+     * ignores it, and continues the conversation correctly — the summary is an
+     * ordinary message in `history` either way. Bumping the version would make
+     * an older deployment REFUSE a session it can serve perfectly well, which is
+     * the opposite of what the version field is for.
+     */
+    readonly folded?: readonly FoldedSpan[];
     /** Where the failure happened. Diagnostic — surfaces in oncall
      *  triage so you can tell "LLM 500 mid-iteration" from "tool
      *  threw" from "validation kept failing". */
@@ -159,7 +183,14 @@ export declare function buildCheckpoint(tracker: RunCheckpointTracker, failurePo
     phase: AgentRunCheckpoint['failurePoint'] extends infer F ? F extends {
         phase: infer P;
     } ? P : never : never;
-}): AgentRunCheckpoint;
+}, 
+/**
+ * Spans this run folded, read from committed state by the caller. Passed in
+ * rather than tracked, because the tracker follows `history` through events
+ * and a fold's span is committed state — and because the same reader then
+ * serves both checkpoint carriers, so neither can lose what the other keeps.
+ */
+folded?: readonly FoldedSpan[]): AgentRunCheckpoint;
 /**
  * Validate a checkpoint at deserialization time. Catches forward-
  * incompatible payloads (someone tries to resume a v3 checkpoint on

package/dist/esm/core/runCheckpoint.js

@@ -103,7 +103,14 @@ export class RunCheckpointError extends Error {
  *
  * @internal
  */
-export function buildCheckpoint(tracker, failurePoint) {
+export function buildCheckpoint(tracker, failurePoint, 
+/**
+ * Spans this run folded, read from committed state by the caller. Passed in
+ * rather than tracked, because the tracker follows `history` through events
+ * and a fold's span is committed state — and because the same reader then
+ * serves both checkpoint carriers, so neither can lose what the other keeps.
+ */
+folded) {
     return {
         version: 1,
         runId: tracker.runId,
@@ -112,6 +119,7 @@ export function buildCheckpoint(tracker, failurePoint) {
         originalInput: tracker.originalInput,
         checkpointedAt: Date.now(),
         ...(failurePoint && { failurePoint }),
+        ...(folded !== undefined && folded.length > 0 && { folded }),
     };
 }
 /**

package/dist/esm/core/runCheckpoint.js.map

@@ -1 +1 @@
-{"version":3,"file":"runCheckpoint.js","sourceRoot":"","sources":["../../../src/core/runCheckpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AA4CH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,oBAA6B,CAAC;IAC9C;;6BAEyB;IACP,KAAK,CAAQ;IAC/B;mEAC+D;IACtD,UAAU,CAAqB;IAExC,YAAY,KAAY,EAAE,UAA8B;QACtD,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,EAAE,KAAK,IAAI,SAAS,CAAC;QAC1D,KAAK,CACH,mCAAmC,UAAU,CAAC,YAAY,EAAE,SAAS,IAAI,GAAG,KAAK,KAAK,KAAK;YACzF,8CAA8C,UAAU,CAAC,sBAAsB,IAAI;YACnF,uDAAuD;YACvD,qBAAqB,KAAK,CAAC,OAAO,EAAE,CACvC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAuBD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA6B,EAC7B,YAOC;IAED,OAAO;QACL,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;QACtD,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE;QAC1B,GAAG,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,CAAC,GAAG,KAAoC,CAAC;IAC/C,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CACjB,mDAAmD,CAAC,CAAC,OAAO,IAAI;YAC9D,uEAAuE;YACvE,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,SAAS,CAAC,sEAAsE,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,sBAAsB,KAAK,QAAQ,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CACjB,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,CAAC,aAAa,IAAI,OAAO,CAAC,CAAC,aAAa,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpE,MAAM,IAAI,SAAS,CACjB,2EAA2E,CAC5E,CAAC;IACJ,CAAC;IACD,OAAO,CAAuB,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAU;IAC7C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,MAAM,IAAI,GAAI,GAAyB,CAAC,IAAI,IAAI,EAAE,CAAC;IACnD,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAC9B,sDAAsD;IACtD,IACE,IAAI,KAAK,kBAAkB,IAAI,0BAA0B;QACzD,IAAI,KAAK,gBAAgB;QACzB,IAAI,KAAK,aAAa;QACtB,IAAI,KAAK,cAAc;QACvB,8CAA8C,CAAC,IAAI,CAAC,GAAG,CAAC,EACxD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/D,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC;IAC/C,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"runCheckpoint.js","sourceRoot":"","sources":["../../../src/core/runCheckpoint.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -31,7 +31,7 @@ export { LLMCall, LLMCallBuilder, type LLMCallInput, type LLMCallOptions, type L
 export { type MessageApiChartDeps } from './core/agent/buildMessageApiChart.js';
 export { buildAgentMessageApiChart, type AgentMessageApiChartDeps, } from './core/agent/buildAgentMessageApiChart.js';
 export { Agent, AgentBuilder, type AgentInput, type AgentOptions, type AgentOutput, type ObserverDeliveryOptions, } from './core/Agent.js';
-export { CompactionUnmeasurableError, COMPACTED_FRAME_PREFIX, DROP_NOTICE_PREFIX, isCompactedSummary, isDropNotice, slidingWindow, summarizeOldest, tokenBudget, type CompactionOptions, type CompactionRecord, type FoldRefusal, type FoldRefusalReason, type RemovalFacts, type RemovalPlan, type SlidingWindowOptions, type SlidingWindowRecord, type TokenBudgetOptions, type TokenBudgetRecord, type Turn, type WindowEviction, type WindowRecord, type WindowRefusal, type WindowRefusalReason, type WindowStrategy, type WindowStrategyInput, type WindowStrategyResult, } from './core/agent/window/index.js';
+export { CompactionUnmeasurableError, COMPACTED_FRAME_PREFIX, DROP_NOTICE_PREFIX, foldedMessages, foldedSpanFor, isCompactedSummary, isDropNotice, slidingWindow, summarizeOldest, tokenBudget, type CompactionOptions, type CompactionRecord, type CompactionRetention, type FoldedConversation, type FoldedSpan, type FoldRefusal, type FoldRefusalReason, type RemovalFacts, type RemovalPlan, type SlidingWindowOptions, type SlidingWindowRecord, type TokenBudgetOptions, type TokenBudgetRecord, type Turn, type WindowEviction, type WindowRecord, type WindowRefusal, type WindowRefusalReason, type WindowStrategy, type WindowStrategyInput, type WindowStrategyResult, } from './core/agent/window/index.js';
 export type { SelfExplainOptions } from './lib/trace-toolpack/selfExplain.js';
 export type { ObserverDrainResult, ObserverStats } from 'footprintjs';
 export type { ToolArgValidationMode } from './core/agent/toolArgsValidation.js';

package/dist/esm/index.js

@@ -112,7 +112,12 @@ export { Agent, AgentBuilder, } from './core/Agent.js';
 //   summarizeOldest  fold the oldest span into a summary  (what `.compaction()` is)
 //   slidingWindow    keep the last N turns, drop older ones
 //   tokenBudget      counted-token trigger, drop instead of summarize
-export { CompactionUnmeasurableError, COMPACTED_FRAME_PREFIX, DROP_NOTICE_PREFIX, isCompactedSummary, isDropNotice, slidingWindow, summarizeOldest, tokenBudget, } from './core/agent/window/index.js';
+//
+// A commit log lives as long as the process; a conversation lives longer. So
+// `.compaction({ retain })` carries the folded originals on the conversation
+// checkpoint too, and `foldedSpanFor(conversation, message)` is the door back
+// to them after a restart.
+export { CompactionUnmeasurableError, COMPACTED_FRAME_PREFIX, DROP_NOTICE_PREFIX, foldedMessages, foldedSpanFor, isCompactedSummary, isDropNotice, slidingWindow, summarizeOldest, tokenBudget, } from './core/agent/window/index.js';
 export { OutputSchemaError, applyOutputSchema, } from './core/outputSchema.js';
 // 7.26 — the loop's side of the output contract. `OutputAttempt` is the row
 // shape `snapshot.sharedState.outputAttempts` carries; the frame prefix and

package/dist/esm/index.js.map

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

package/dist/esm/providers.d.ts

@@ -14,18 +14,26 @@
  *
  * What's here today:
  *   • `mock` / `MockProvider` — deterministic + realistic-mode mock
+ *   • `ollama` / `OllamaProvider` — local models, free, no API key
  *   • `anthropic` / `AnthropicProvider` — real provider (Claude)
  *   • `openai` / `OpenAIProvider` — real provider (GPT)
+ *   • `bedrock`, `azureOpenai`, and the `browser*` variants
+ *
+ * The ladder these are FOR: `mock()` while you shape the logic →
+ * `ollama('<model>')` for a real model that costs nothing and needs no
+ * key → a paid API in production. The agent code above them does not
+ * change between the three; that is the whole point of the port.
  *
  * Bring your own (BYO):
- *   For Bedrock / Ollama / Cohere / on-prem / fine-tuned models,
- *   implement the `LLMProvider` interface (see `LLMProvider` exported
- *   from the main barrel) — `complete()` is required, `stream()` is
- *   optional. The `MockProvider` source is the canonical reference.
+ *   For Cohere / on-prem / fine-tuned models, implement the
+ *   `LLMProvider` interface (see `LLMProvider` exported from the main
+ *   barrel) — `complete()` is required, `stream()` is optional. The
+ *   `MockProvider` source is the canonical reference.
  */
 export { MockProvider, mock, type MockProviderOptions, type MockReply, type LatencyMs, } from './adapters/llm/MockProvider.js';
 export { anthropic, AnthropicProvider, type AnthropicProviderOptions, } from './adapters/llm/AnthropicProvider.js';
-export { openai, OpenAIProvider, ollama, azureOpenai, type OpenAIProviderOptions, type AzureOpenAIProviderOptions, } from './adapters/llm/OpenAIProvider.js';
+export { openai, OpenAIProvider, azureOpenai, type OpenAIProviderOptions, type AzureOpenAIProviderOptions, } from './adapters/llm/OpenAIProvider.js';
+export { ollama, OllamaProvider, OllamaUnavailableError, type OllamaProviderOptions, type ThinkLevel, } from './adapters/llm/OllamaProvider.js';
 export { bedrock, BedrockProvider, type BedrockProviderOptions, } from './adapters/llm/BedrockProvider.js';
 export { browserAnthropic, BrowserAnthropicProvider, type BrowserAnthropicProviderOptions, } from './adapters/llm/BrowserAnthropicProvider.js';
 export { browserOpenai, BrowserOpenAIProvider, type BrowserOpenAIProviderOptions, browserAzureOpenai, BrowserAzureOpenAIProvider, type BrowserAzureOpenAIProviderOptions, } from './adapters/llm/BrowserOpenAIProvider.js';

package/dist/esm/providers.js

@@ -14,18 +14,26 @@
  *
  * What's here today:
  *   • `mock` / `MockProvider` — deterministic + realistic-mode mock
+ *   • `ollama` / `OllamaProvider` — local models, free, no API key
  *   • `anthropic` / `AnthropicProvider` — real provider (Claude)
  *   • `openai` / `OpenAIProvider` — real provider (GPT)
+ *   • `bedrock`, `azureOpenai`, and the `browser*` variants
+ *
+ * The ladder these are FOR: `mock()` while you shape the logic →
+ * `ollama('<model>')` for a real model that costs nothing and needs no
+ * key → a paid API in production. The agent code above them does not
+ * change between the three; that is the whole point of the port.
  *
  * Bring your own (BYO):
- *   For Bedrock / Ollama / Cohere / on-prem / fine-tuned models,
- *   implement the `LLMProvider` interface (see `LLMProvider` exported
- *   from the main barrel) — `complete()` is required, `stream()` is
- *   optional. The `MockProvider` source is the canonical reference.
+ *   For Cohere / on-prem / fine-tuned models, implement the
+ *   `LLMProvider` interface (see `LLMProvider` exported from the main
+ *   barrel) — `complete()` is required, `stream()` is optional. The
+ *   `MockProvider` source is the canonical reference.
  */
 export { MockProvider, mock, } from './adapters/llm/MockProvider.js';
 export { anthropic, AnthropicProvider, } from './adapters/llm/AnthropicProvider.js';
-export { openai, OpenAIProvider, ollama, azureOpenai, } from './adapters/llm/OpenAIProvider.js';
+export { openai, OpenAIProvider, azureOpenai, } from './adapters/llm/OpenAIProvider.js';
+export { ollama, OllamaProvider, OllamaUnavailableError, } from './adapters/llm/OllamaProvider.js';
 export { bedrock, BedrockProvider, } from './adapters/llm/BedrockProvider.js';
 export { browserAnthropic, BrowserAnthropicProvider, } from './adapters/llm/BrowserAnthropicProvider.js';
 export { browserOpenai, BrowserOpenAIProvider, browserAzureOpenai, BrowserAzureOpenAIProvider, } from './adapters/llm/BrowserOpenAIProvider.js';

package/dist/esm/providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,GAIL,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,GAElB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,MAAM,EACN,WAAW,GAGZ,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,GAEhB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAEzB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,EAErB,kBAAkB,EAClB,0BAA0B,GAE3B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,GAGf,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EACL,YAAY,EACZ,IAAI,GAIL,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,SAAS,EACT,iBAAiB,GAElB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,MAAM,EACN,cAAc,EACd,WAAW,GAGZ,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,MAAM,EACN,cAAc,EACd,sBAAsB,GAGvB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,OAAO,EACP,eAAe,GAEhB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GAEzB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,qBAAqB,EAErB,kBAAkB,EAClB,0BAA0B,GAE3B,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,cAAc,GAGf,MAAM,kCAAkC,CAAC"}

package/dist/esm/thinking/OllamaThinkingHandler.d.ts

@@ -0,0 +1,60 @@
+/**
+ * OllamaThinkingHandler — normalizes a local reasoning model's thinking
+ * into the framework's `ThinkingBlock[]` contract.
+ *
+ * Local reasoning models (deepseek-r1, qwen3, gpt-oss, …) reason in the
+ * open, and where that reasoning LANDS depends on how they were asked:
+ *
+ *   1. ASKED (`ollama('qwen3', { think: true })`, or the agent's
+ *      `.thinking({ budget })`) — Ollama lifts the reasoning out of the
+ *      answer into `message.thinking`. The adapter forwards it as
+ *      `{ kind: 'field', thinking }`. This is the good path.
+ *
+ *   2. NOT ASKED — the same model writes `<think>…</think>` straight into
+ *      the answer text. The adapter recognizes the shape and forwards the
+ *      whole answer as `{ kind: 'inline', content }`.
+ *
+ * **The library recognizes the inline shape; it never rewrites the
+ * answer.** Blocks produced from case 2 describe text that is STILL
+ * present, verbatim, in `LLMResponse.content` — because silently editing
+ * a model's answer is a meaning change, and that is the application's
+ * decision to make, not this library's. If you want the reasoning out of
+ * the answer, ask for it: turn `think` on, and the model stops putting it
+ * there.
+ *
+ * **No signature** — nothing on this wire is signed, so there is no
+ * round-trip integrity invariant (unlike Anthropic). `signature` stays
+ * undefined.
+ *
+ * **No `summary` flag** — this is raw reasoning, not a structured summary
+ * (unlike OpenAI's `reasoning_summary`).
+ *
+ * **`parseChunk`** — the adapter already emits `LLMChunk.thinkingDelta`
+ * directly while streaming (Ollama sends `message.thinking` deltas frame
+ * by frame), so the framework does not need this to see live reasoning.
+ * It is implemented anyway for consumers driving the handler themselves.
+ */
+import type { ThinkingHandler } from './types.js';
+/**
+ * What `OllamaProvider` puts on `LLMResponse.rawThinking`.
+ *
+ * Tagged rather than a bare string so the handler never has to GUESS which
+ * of the two situations it is looking at — and so a consumer reading the
+ * raw value can tell whether the reasoning is also sitting in the answer.
+ */
+export type OllamaRawThinking = {
+    readonly kind: 'field';
+    readonly thinking: string;
+} | {
+    readonly kind: 'inline';
+    readonly content: string;
+};
+/**
+ * Pull the reasoning out of text that carries `<think>` tags.
+ *
+ * All tag PARSING lives here, in the handler — the adapter only notices
+ * that a `<think` substring is present and tags the payload accordingly.
+ * Exported so a consumer driving normalization by hand can reuse it.
+ */
+export declare function extractInlineThinking(text: string): readonly string[];
+export declare const ollamaThinkingHandler: ThinkingHandler;

package/dist/esm/thinking/OllamaThinkingHandler.js

@@ -0,0 +1,107 @@
+/**
+ * OllamaThinkingHandler — normalizes a local reasoning model's thinking
+ * into the framework's `ThinkingBlock[]` contract.
+ *
+ * Local reasoning models (deepseek-r1, qwen3, gpt-oss, …) reason in the
+ * open, and where that reasoning LANDS depends on how they were asked:
+ *
+ *   1. ASKED (`ollama('qwen3', { think: true })`, or the agent's
+ *      `.thinking({ budget })`) — Ollama lifts the reasoning out of the
+ *      answer into `message.thinking`. The adapter forwards it as
+ *      `{ kind: 'field', thinking }`. This is the good path.
+ *
+ *   2. NOT ASKED — the same model writes `<think>…</think>` straight into
+ *      the answer text. The adapter recognizes the shape and forwards the
+ *      whole answer as `{ kind: 'inline', content }`.
+ *
+ * **The library recognizes the inline shape; it never rewrites the
+ * answer.** Blocks produced from case 2 describe text that is STILL
+ * present, verbatim, in `LLMResponse.content` — because silently editing
+ * a model's answer is a meaning change, and that is the application's
+ * decision to make, not this library's. If you want the reasoning out of
+ * the answer, ask for it: turn `think` on, and the model stops putting it
+ * there.
+ *
+ * **No signature** — nothing on this wire is signed, so there is no
+ * round-trip integrity invariant (unlike Anthropic). `signature` stays
+ * undefined.
+ *
+ * **No `summary` flag** — this is raw reasoning, not a structured summary
+ * (unlike OpenAI's `reasoning_summary`).
+ *
+ * **`parseChunk`** — the adapter already emits `LLMChunk.thinkingDelta`
+ * directly while streaming (Ollama sends `message.thinking` deltas frame
+ * by frame), so the framework does not need this to see live reasoning.
+ * It is implemented anyway for consumers driving the handler themselves.
+ */
+/** `<think>…</think>`, including an unclosed one from a truncated answer. */
+const THINK_TAG = /<think>([\s\S]*?)(?:<\/think>|$)/gi;
+/**
+ * Pull the reasoning out of text that carries `<think>` tags.
+ *
+ * All tag PARSING lives here, in the handler — the adapter only notices
+ * that a `<think` substring is present and tags the payload accordingly.
+ * Exported so a consumer driving normalization by hand can reuse it.
+ */
+export function extractInlineThinking(text) {
+    if (!text.includes('<think'))
+        return [];
+    const out = [];
+    // `matchAll` needs the /g flag and a fresh lastIndex per call.
+    THINK_TAG.lastIndex = 0;
+    for (const match of text.matchAll(THINK_TAG)) {
+        const inner = (match[1] ?? '').trim();
+        if (inner.length > 0)
+            out.push(inner);
+    }
+    return out;
+}
+function isRawThinking(raw) {
+    return typeof raw === 'object' && raw !== null && 'kind' in raw;
+}
+export const ollamaThinkingHandler = {
+    id: 'ollama',
+    providerNames: ['ollama'],
+    normalize(raw) {
+        if (raw === undefined || raw === null)
+            return [];
+        // Bare string — a hand-fed value, or a consumer-authored adapter that
+        // passes `message.thinking` straight through. Treat it as reasoning,
+        // but still honor tags if they are in there.
+        if (typeof raw === 'string')
+            return blocksFromText(raw);
+        if (isRawThinking(raw)) {
+            if (raw.kind === 'field') {
+                return typeof raw.thinking === 'string' ? blocksFromText(raw.thinking) : [];
+            }
+            if (raw.kind === 'inline') {
+                if (typeof raw.content !== 'string')
+                    return [];
+                return extractInlineThinking(raw.content).map(toBlock);
+            }
+        }
+        // Unknown shape — empty rather than throw. The framework catches throws
+        // and emits parse_failed; graceful empty is the right answer for a
+        // wire that may grow fields we have not seen yet.
+        return [];
+    },
+    parseChunk(chunk) {
+        if (typeof chunk !== 'object' || chunk === null)
+            return {};
+        const message = chunk.message;
+        const thinking = message?.thinking;
+        return typeof thinking === 'string' && thinking.length > 0 ? { thinkingDelta: thinking } : {};
+    },
+};
+/** Text → blocks. Tagged text yields one block per tag; plain text one block. */
+function blocksFromText(text) {
+    const tagged = extractInlineThinking(text);
+    if (tagged.length > 0)
+        return tagged.map(toBlock);
+    const trimmed = text.trim();
+    return trimmed.length > 0 ? [toBlock(trimmed)] : [];
+}
+function toBlock(content) {
+    return { type: 'thinking', content };
+}
+//# sourceMappingURL=OllamaThinkingHandler.js.map