@fifthrevision/axle 0.25.4 → 0.26.0

package/dist/{accumulator-yYlD8Bfm.d.ts → accumulator-BQ_1i4qv.d.ts}

@@ -773,6 +773,33 @@ interface ContentPartCitation {
   providerMetadata?: Record<string, unknown>;
 }
 //#endregion
+//#region src/messages/compaction.d.ts
+/**
+ * Record of one applied compaction: when it happened. Inspection only —
+ * records carry no message content and cannot reconstruct the pre-compaction
+ * conversation.
+ *
+ * @experimental Compaction is under active design and may change in any release.
+ */
+interface CompactionRecord {
+  /** Stable record id. Shared with the compaction turn. */
+  id: string;
+  /** ISO timestamp for when the compaction ran. */
+  at: string;
+}
+/**
+ * Validate that a compacted conversation is structurally well-formed.
+ *
+ * The messages must stand alone: every tool call must be answered by the
+ * tool message(s) immediately following it — providers reject conversations
+ * that interleave other messages between a call and its result — and every
+ * tool result must answer a preceding call.
+ *
+ * @experimental Compaction is under active design and may change in any release.
+ * @throws AxleError with code `COMPACTION_INVALID_MESSAGES`
+ */
+declare function validateCompactedMessages(messages: AxleMessage[]): void;
+//#endregion
 //#region src/turns/types.d.ts
 /**
  * Lifecycle state for a renderable turn.
@@ -863,7 +890,7 @@ interface Turn<TAnnotation extends Annotation = Annotation> {
 /**
  * Any renderable part within a turn.
  */
-type TurnPart<TAnnotation extends Annotation = Annotation> = TextPart<TAnnotation> | CitationPart<TAnnotation> | FilePart<TAnnotation> | ThinkingPart<TAnnotation> | ActionPart<TAnnotation>;
+type TurnPart<TAnnotation extends Annotation = Annotation> = TextPart<TAnnotation> | CitationPart<TAnnotation> | FilePart<TAnnotation> | ThinkingPart<TAnnotation> | ActionPart<TAnnotation> | CompactionPart<TAnnotation>;
 /**
  * Assistant or user text content.
  */
@@ -938,6 +965,28 @@ interface ThinkingPart<TAnnotation extends Annotation = Annotation> {
   /** Optional timing metadata. */
   timing?: TimingInfo;
 }
+/**
+ * Part marking a compaction of the model-facing conversation.
+ *
+ * Compaction renders as an agent turn containing this single part. The turn's
+ * `status` carries the lifecycle: `"streaming"` while the compaction callback
+ * runs, `"complete"` once applied, `"error"` on failure. Skipped compactions
+ * are removed from the turns, not settled.
+ *
+ * @experimental Compaction is under active design and may change in any release.
+ */
+interface CompactionPart<TAnnotation extends Annotation = Annotation> {
+  /** Stable part id. Shared with the compaction record. */
+  id: string;
+  /** Part discriminator. */
+  type: "compaction";
+  /** The applied record, present once the compaction completes. */
+  record?: CompactionRecord;
+  /** Annotations attached to this part. */
+  annotations?: TAnnotation[];
+  /** Optional timing metadata. */
+  timing?: TimingInfo;
+}
 /**
  * Shared fields for tool, subagent, and provider-managed actions.
  *
@@ -1056,6 +1105,16 @@ type TurnEvent<TAnnotation extends Annotation = Annotation> = {
   status: TurnStatus;
   usage: Stats;
   timing?: TimingInfo;
+} | {
+  type: "compaction:start";
+  id: string;
+  timing?: TimingInfo;
+} | {
+  type: "compaction:end";
+  id: string;
+  outcome: "complete" | "skipped" | "error";
+  record?: CompactionRecord;
+  timing?: TimingInfo;
 } | {
   type: "part:start";
   turnId: string;
@@ -1222,6 +1281,7 @@ declare class TurnAccumulator<TAnnotation extends Annotation = Annotation, THost
   constructor(init?: TurnAccumulatorState<TAnnotation>);
   get state(): TurnAccumulatorState<TAnnotation>;
   apply(event: AccumulatableEvent<TAnnotation, THostEvent>): TurnAccumulatorResult<TAnnotation, THostEvent>;
+  private applyTurnEvent;
   private replaceState;
   private replaceTurns;
   private updateTurn;
@@ -1231,4 +1291,4 @@ declare class TurnAccumulator<TAnnotation extends Annotation = Annotation, THost
   private handled;
 }
 //#endregion
-export { AxleStopReason as $, TurnPart as A, TokenUsage as At, ContentPart as B, SubagentAction as C, Span as Ct, ToolAction as D, SpanResult as Dt, TimingInfo as E, SpanOptions as Et, AxleToolCallResult as F, ContentPartThinking as G, ContentPartFile as H, AxleUserMessage as I, MessageMetadata as J, ContentPartToolCall as K, Citation as L, AxleAssistantMessage as M, TraceWriter as Mt, AxleMessage as N, Turn as O, SpanStatus as Ot, AxleToolCallMessage as P, AxleModelRequestOptions as Q, CitationOutputSpan as R, ProviderToolAction as S, LLMResult as St, ThinkingPart as T, SpanEvent as Tt, ContentPartProviderTool as U, ContentPartCitation as V, ContentPartText as W, ToolResultPart as X, ThinkingContinuity as Y, AIProvider as Z, Annotation as _, TokenStats as _t, UnknownEvent as a, ResolvedProviderTool as at, CitationPart as b, LLMRequest as bt, ToolContext as c, FileInfo as ct, ToolRegistry as d, FileResolveFormat as dt, ContextUsage as et, AnnotationEvent as f, FileResolveRequest as ft, ActionResult as g, Stats as gt, ActionPart as h, loadFileContent as ht, TurnAccumulatorState as i, ProviderOptions as it, TurnStatus as j, ToolResult as jt, TurnMetadata as k, SpanType as kt, ToolDefinition as l, FileKind as lt, TurnEvent as m, ResolvedFileSource as mt, TurnAccumulator as n, ModelResult as nt, ExecutableTool as o, ToolChoice as ot, AnnotationTarget as p, FileResolver as pt, DocumentLocator as q, TurnAccumulatorResult as r, ProviderClientOptions as rt, ProviderTool as s, DeferredFileInfo as st, AccumulatableEvent as t, ModelError as tt, ToolProgressChunk as u, FileProviderId as ut, AnnotationPlacement as v, UsageEntry as vt, TextPart as w, SpanData as wt, FilePart as x, LLMResponse as xt, AnnotationStatus as y, EventLevel as yt, CitationSource as z };
+export { ToolResultPart as $, TurnMetadata as A, SpanResult as At, Citation as B, ProviderToolAction as C, LLMRequest as Ct, TimingInfo as D, SpanData as Dt, ThinkingPart as E, Span as Et, AxleAssistantMessage as F, TraceWriter as Ft, ContentPartFile as G, CitationSource as H, AxleMessage as I, ContentPartThinking as J, ContentPartProviderTool as K, AxleToolCallMessage as L, TurnStatus as M, SpanType as Mt, CompactionRecord as N, TokenUsage as Nt, ToolAction as O, SpanEvent as Ot, validateCompactedMessages as P, ToolResult as Pt, ThinkingContinuity as Q, AxleToolCallResult as R, FilePart as S, EventLevel as St, TextPart as T, LLMResult as Tt, ContentPart as U, CitationOutputSpan as V, ContentPartCitation as W, DocumentLocator as X, ContentPartToolCall as Y, MessageMetadata as Z, Annotation as _, ResolvedFileSource as _t, UnknownEvent as a, ModelResult as at, CitationPart as b, TokenStats as bt, ToolContext as c, ResolvedProviderTool as ct, ToolRegistry as d, FileInfo as dt, AIProvider as et, AnnotationEvent as f, FileKind as ft, ActionResult as g, FileResolver as gt, ActionPart as h, FileResolveRequest as ht, TurnAccumulatorState as i, ModelError as it, TurnPart as j, SpanStatus as jt, Turn as k, SpanOptions as kt, ToolDefinition as l, ToolChoice as lt, TurnEvent as m, FileResolveFormat as mt, TurnAccumulator as n, AxleStopReason as nt, ExecutableTool as o, ProviderClientOptions as ot, AnnotationTarget as p, FileProviderId as pt, ContentPartText as q, TurnAccumulatorResult as r, ContextUsage as rt, ProviderTool as s, ProviderOptions as st, AccumulatableEvent as t, AxleModelRequestOptions as tt, ToolProgressChunk as u, DeferredFileInfo as ut, AnnotationPlacement as v, loadFileContent as vt, SubagentAction as w, LLMResponse as wt, CompactionPart as x, UsageEntry as xt, AnnotationStatus as y, Stats as yt, AxleUserMessage as z };

package/dist/accumulator-jZHrnyOF.js

@@ -0,0 +1 @@
+const e=new Set(Object.keys({"session:restore":!0,"turn:user":!0,"turn:start":!0,"turn:end":!0,"compaction:start":!0,"compaction:end":!0,"part:start":!0,"text:delta":!0,"text:citation":!0,"thinking:delta":!0,"thinking:summary-delta":!0,"thinking:update":!0,"part:end":!0,"action:args-delta":!0,"action:running":!0,"action:progress":!0,"action:complete":!0,"action:error":!0,"action:child-event":!0,"annotation:start":!0,"annotation:update":!0,"annotation:end":!0,error:!0}));function t(t){return e.has(t.type)}var n=class e{_state;constructor(e){this._state={turns:e?.turns??[],sessionAnnotations:e?.sessionAnnotations}}get state(){return this._state}apply(e){return t(e)?this.applyTurnEvent(e):{handled:!1,state:this._state,event:e}}applyTurnEvent(t){switch(t.type){case`session:restore`:return this.replaceState({turns:t.turns??[],sessionAnnotations:t.sessionAnnotations},t);case`turn:user`:return this.replaceTurns([...this._state.turns,t.turn],t);case`turn:start`:{let e={id:t.turnId,owner:`agent`,parts:[],status:`streaming`,...t.timing?{timing:t.timing}:{}};return this.replaceTurns([...this._state.turns,e],t)}case`compaction:start`:{let e={id:t.id,owner:`agent`,parts:[{id:t.id,type:`compaction`}],status:`streaming`,...t.timing?{timing:t.timing}:{}};return this.replaceTurns([...this._state.turns,e],t)}case`compaction:end`:{if(t.outcome===`skipped`){let e=this._state.turns.filter(e=>e.id!==t.id);return e.length===this._state.turns.length?this.handled(t):this.replaceTurns(e,t)}let e=t.outcome===`complete`?`complete`:`error`,n=!1,r=this._state.turns.map(r=>r.id===t.id?(n=!0,{...r,status:e,parts:r.parts.map(e=>e.type===`compaction`&&t.record?{...e,record:t.record}:e),timing:t.timing??r.timing}):r);return n?this.replaceTurns(r,t):this.handled(t)}case`part:start`:return this.updateTurn(t.turnId,t,e=>({...e,parts:[...e.parts,t.part]}));case`text:delta`:return this.updatePart(t.turnId,t.partId,t,e=>e.type===`text`?{...e,text:e.text+t.delta}:e);case`text:citation`:return this.updatePart(t.turnId,t.partId,t,e=>e.type===`text`?{...e,citations:[...e.citations??[],t.citation]}:e);case`thinking:delta`:return this.updatePart(t.turnId,t.partId,t,e=>e.type===`thinking`?{...e,text:(e.text??``)+t.delta}:e);case`thinking:summary-delta`:return this.updatePart(t.turnId,t.partId,t,e=>e.type===`thinking`?{...e,summary:(e.summary??``)+t.delta}:e);case`thinking:update`:return this.updatePart(t.turnId,t.partId,t,e=>e.type===`thinking`?{...e,...t.redacted===void 0?{}:{redacted:t.redacted},...t.continuity?{continuity:t.continuity}:{},...t.providerMetadata?{providerMetadata:t.providerMetadata}:{}}:e);case`part:end`:return this.updatePart(t.turnId,t.partId,t,e=>({...e,timing:t.timing??e.timing}));case`action:args-delta`:return this.updatePart(t.turnId,t.partId,t,e=>e.type!==`action`||e.kind!==`tool`?e:{...e,detail:{...e.detail,pendingArgs:t.accumulated}});case`action:running`:return this.updatePart(t.turnId,t.partId,t,e=>{if(e.type!==`action`)return e;if(e.kind===`tool`){let{pendingArgs:n,...r}=e.detail;return{...e,status:`running`,detail:t.parameters?{...r,parameters:t.parameters}:r}}return{...e,status:`running`}});case`action:progress`:return this.updatePart(t.turnId,t.partId,t,e=>{if(e.type!==`action`)return e;let n=e.detail.result,r=n?.type===`in-progress`?n.content:``;return{...e,detail:{...e.detail,result:{type:`in-progress`,content:r+t.chunk}}}});case`action:complete`:return this.updatePart(t.turnId,t.partId,t,e=>e.type===`action`?{...e,status:`complete`,detail:{...e.detail,result:t.result},timing:t.timing??e.timing}:e);case`action:error`:return this.updatePart(t.turnId,t.partId,t,e=>e.type===`action`?{...e,status:`error`,detail:{...e.detail,result:{type:`error`,error:t.error}},timing:t.timing??e.timing}:e);case`turn:end`:return this.updateTurn(t.turnId,t,e=>({...e,status:t.status,usage:t.usage,timing:t.timing??e.timing}));case`annotation:start`:return this.addAnnotation(t);case`annotation:update`:return this.replaceAnnotation(t,!1);case`annotation:end`:return this.replaceAnnotation(t,!0);case`error`:return this.handled(t);case`action:child-event`:return this.updatePart(t.turnId,t.partId,t,n=>{if(n.type!==`action`||n.kind!==`agent`)return n;let r=new e({turns:n.detail.children}).apply(t.event);return{...n,detail:{...n.detail,children:r.state.turns}}});default:return this.handled(t)}}replaceState(e,t){return this._state=e,this.handled(t)}replaceTurns(e,t){return this.replaceState({...this._state,turns:e},t)}updateTurn(e,t,n){let r=!1,i=this._state.turns.map(t=>{if(t.id!==e)return t;let i=n(t);return i===t?t:(r=!0,i)});return r?this.replaceTurns(i,t):this.handled(t)}updatePart(e,t,n,r){return this.updateTurn(e,n,e=>{let n=!1,i=e.parts.map(e=>{if(e.id!==t)return e;let i=r(e);return i===e?e:(n=!0,i)});return n?{...e,parts:i}:e})}addAnnotation(e){let t=e.target,n=r(e.annotation);return n?t.type===`session`?this.replaceState({...this._state,sessionAnnotations:[...this._state.sessionAnnotations??[],n]},e):t.type===`turn`?this.updateTurn(t.turnId,e,e=>({...e,annotations:[...e.annotations??[],n]})):this.updatePart(t.turnId,t.partId,e,e=>({...e,annotations:[...e.annotations??[],n]})):this.handled(e)}replaceAnnotation(e,t){let n=e.target,a=r(e.annotation,t);if(!a)return this.handled(e);if(n.type===`session`){let t=i(this._state.sessionAnnotations,a);return t?this.replaceState({...this._state,sessionAnnotations:t},e):this.handled(e)}return n.type===`turn`?this.updateTurn(n.turnId,e,e=>{let t=i(e.annotations,a);return t?{...e,annotations:t}:e}):this.updatePart(n.turnId,n.partId,e,e=>{let t=i(e.annotations,a);return t?{...e,annotations:t}:e})}handled(e){return{handled:!0,state:this._state,event:e}}};function r(e,t=!1){if(!e)return;let n=t?e.status??`complete`:e.status,r={...e,placement:e.placement??`after`};return n?{...r,status:n}:r}function i(e,t){if(!e)return;let n=!1,r=e.map(e=>e.id===t.id?(n=!0,t):e);return n?r:void 0}export{n as t};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as AxleStopReason, A as TurnPart, At as TokenUsage, B as ContentPart, C as SubagentAction, Ct as Span, D as ToolAction, Dt as SpanResult, Et as SpanOptions, F as AxleToolCallResult, G as ContentPartThinking, H as ContentPartFile, I as AxleUserMessage, J as MessageMetadata, K as ContentPartToolCall, L as Citation, M as AxleAssistantMessage, Mt as TraceWriter, N as AxleMessage, O as Turn, Ot as SpanStatus, P as AxleToolCallMessage, Q as AxleModelRequestOptions, R as CitationOutputSpan, S as ProviderToolAction, St as LLMResult, T as ThinkingPart, Tt as SpanEvent, U as ContentPartProviderTool, V as ContentPartCitation, W as ContentPartText, X as ToolResultPart, Y as ThinkingContinuity, Z as AIProvider, _ as Annotation, _t as TokenStats, at as ResolvedProviderTool, b as CitationPart, bt as LLMRequest, c as ToolContext, ct as FileInfo, d as ToolRegistry, dt as FileResolveFormat, et as ContextUsage, f as AnnotationEvent, ft as FileResolveRequest, g as ActionResult, gt as Stats, h as ActionPart, ht as loadFileContent, i as TurnAccumulatorState, it as ProviderOptions, j as TurnStatus, jt as ToolResult, k as TurnMetadata, kt as SpanType, l as ToolDefinition, lt as FileKind, m as TurnEvent, mt as ResolvedFileSource, n as TurnAccumulator, nt as ModelResult, o as ExecutableTool, ot as ToolChoice, p as AnnotationTarget, pt as FileResolver, q as DocumentLocator, r as TurnAccumulatorResult, rt as ProviderClientOptions, s as ProviderTool, st as DeferredFileInfo, t as AccumulatableEvent, tt as ModelError, u as ToolProgressChunk, ut as FileProviderId, v as AnnotationPlacement, vt as UsageEntry, w as TextPart, wt as SpanData, x as FilePart, xt as LLMResponse, y as AnnotationStatus, yt as EventLevel, z as CitationSource } from "./accumulator-yYlD8Bfm.js";
+import { $ as ToolResultPart, A as TurnMetadata, At as SpanResult, B as Citation, C as ProviderToolAction, Ct as LLMRequest, Dt as SpanData, E as ThinkingPart, Et as Span, F as AxleAssistantMessage, Ft as TraceWriter, G as ContentPartFile, H as CitationSource, I as AxleMessage, J as ContentPartThinking, K as ContentPartProviderTool, L as AxleToolCallMessage, M as TurnStatus, Mt as SpanType, N as CompactionRecord, Nt as TokenUsage, O as ToolAction, Ot as SpanEvent, P as validateCompactedMessages, Pt as ToolResult, Q as ThinkingContinuity, R as AxleToolCallResult, S as FilePart, St as EventLevel, T as TextPart, Tt as LLMResult, U as ContentPart, V as CitationOutputSpan, W as ContentPartCitation, X as DocumentLocator, Y as ContentPartToolCall, Z as MessageMetadata, _ as Annotation, _t as ResolvedFileSource, at as ModelResult, b as CitationPart, bt as TokenStats, c as ToolContext, ct as ResolvedProviderTool, d as ToolRegistry, dt as FileInfo, et as AIProvider, f as AnnotationEvent, ft as FileKind, g as ActionResult, gt as FileResolver, h as ActionPart, ht as FileResolveRequest, i as TurnAccumulatorState, it as ModelError, j as TurnPart, jt as SpanStatus, k as Turn, kt as SpanOptions, l as ToolDefinition, lt as ToolChoice, m as TurnEvent, mt as FileResolveFormat, n as TurnAccumulator, nt as AxleStopReason, o as ExecutableTool, ot as ProviderClientOptions, p as AnnotationTarget, pt as FileProviderId, q as ContentPartText, r as TurnAccumulatorResult, rt as ContextUsage, s as ProviderTool, st as ProviderOptions, t as AccumulatableEvent, tt as AxleModelRequestOptions, u as ToolProgressChunk, ut as DeferredFileInfo, v as AnnotationPlacement, vt as loadFileContent, w as SubagentAction, wt as LLMResponse, x as CompactionPart, xt as UsageEntry, y as AnnotationStatus, yt as Stats, z as AxleUserMessage } from "./accumulator-BQ_1i4qv.js";
 import * as z$2 from "zod";
 import { ZodObject, z } from "zod";
 
@@ -142,32 +142,72 @@ declare class Instruct<TSchema extends OutputSchema | undefined = undefined> {
 //#endregion
 //#region src/core/agent/history.d.ts
 /**
- * In-memory conversation and presentation history for an agent.
+ * Complete state for constructing a `History`. Reconstructing from a saved
+ * session goes through the constructor — there is no field-by-field mutation.
+ */
+interface HistoryInit<TAnnotation extends Annotation = Annotation> {
+  turns?: Turn<TAnnotation>[];
+  messages?: AxleMessage[];
+  archive?: AxleMessage[];
+  compactions?: CompactionRecord[];
+  sessionAnnotations?: TAnnotation[];
+}
+/**
+ * In-memory conversation and presentation state for an agent.
+ *
+ * All state is private; reads return copies and writes go through
+ * use-case-specific methods:
  *
- * `log` is the canonical model-facing message history. `turns` and
- * `sessionAnnotations` are renderable presentation state for consumers.
+ * - `messages` — the active, model-facing conversation. Requests are built
+ *   from it; compaction replaces it.
+ * - `archive` — every message ever appended, in order, untouched by
+ *   compaction. The chronological record, for inspection only.
+ * - `turns` — the renderable session turns: user/agent entries and compaction entries.
+ *   Forever-accumulating; consumers decide how to render or prune it.
+ * - `compactions` — receipts for each applied compaction.
+ * - `sessionAnnotations` — session-level render annotations.
  *
  * @typeParam TAnnotation - Annotation union supported by the host renderer.
  */
 declare class History<TAnnotation extends Annotation = Annotation> {
   private _turns;
-  private _log;
+  private _messages;
+  private _archive;
+  private _compactions;
   private _sessionAnnotations;
-  constructor(init?: {
-    turns?: Turn<TAnnotation>[];
-    log?: AxleMessage[];
-    sessionAnnotations?: TAnnotation[];
-  });
+  constructor(init?: HistoryInit<TAnnotation>);
   get turns(): Turn<TAnnotation>[];
-  get log(): AxleMessage[];
+  get messages(): AxleMessage[];
+  get archive(): AxleMessage[];
+  get compactions(): CompactionRecord[];
   get sessionAnnotations(): TAnnotation[];
-  addTurn(turn: Turn<TAnnotation>): void;
-  replaceTurns(turns: Turn<TAnnotation>[]): void;
-  replaceLog(messages: AxleMessage[]): void;
-  replaceSessionAnnotations(annotations?: TAnnotation[]): void;
-  appendToLog(messages: AxleMessage | AxleMessage[]): void;
-  latestTurn(): Turn<TAnnotation> | undefined;
-  toString(): string;
+  /**
+   * Append conversation messages. Every appended message goes to both the
+   * active conversation and the archive, so the archive is always the
+   * complete chronological record regardless of compaction.
+   *
+   * @internal The Agent is History's only writer. Direct writes bypass the
+   * work queue and the event fold, desynchronizing engine state.
+   */
+  append(messages: AxleMessage | AxleMessage[]): void;
+  /**
+   * Replace the renderable turn state wholesale. Used to sync the
+   * accumulated state after applying a turn event.
+   *
+   * @internal The Agent is History's only writer. External writes are
+   * overwritten by the agent's accumulator on the next event.
+   */
+  replaceTurns(turns: Turn<TAnnotation>[], sessionAnnotations: TAnnotation[]): void;
+  /**
+   * Apply a compaction: the new state replaces the active conversation and
+   * the record is kept. The archive is untouched — it already holds
+   * everything ever appended. The corresponding compaction turn arrives
+   * through the event fold, not here.
+   *
+   * @internal The Agent is History's only writer; use `agent.compact()`.
+   * @experimental Compaction is under active design and may change in any release.
+   */
+  compact(messages: AxleMessage[], record: CompactionRecord): void;
 }
 //#endregion
 //#region src/memory/types.d.ts
@@ -340,6 +380,13 @@ type GenerateResult<TResponse = AxleAssistantMessage> = {
   messages: AxleMessage[];
   final: AxleAssistantMessage;
   usage?: Stats;
+  /**
+   * Present when a configured limit ended the tool loop at a request
+   * boundary. The conversation is well-formed and continuable;
+   * `final.finishReason` keeps the provider's own reason for the last
+   * message (typically `FunctionCall` — the model wanted to continue).
+   */
+  stopped?: "max-iterations" | "token-limit";
 } | {
   ok: false;
   response?: undefined;
@@ -347,6 +394,12 @@ type GenerateResult<TResponse = AxleAssistantMessage> = {
   messages: AxleMessage[];
   error: GenerateError;
   usage?: Stats;
+  /**
+   * Present on a `parse` error when a loop limit ended an Instruct call
+   * before the model produced parseable output. The conversation is still
+   * well-formed and continuable.
+   */
+  stopped?: "max-iterations" | "token-limit";
 };
 type StreamResult<TResponse = AxleAssistantMessage> = GenerateResult<TResponse>;
 //#endregion
@@ -355,16 +408,6 @@ interface Handle<T> {
   cancel(reason?: unknown): void;
   readonly final: Promise<T>;
 }
-/**
- * Creates a cancellable, queued async handle.
- * Waits for `queue` before running `work`, merges an optional external signal
- * with an internal abort controller, and returns the handle + settled promise
- * for queue chaining.
- */
-declare function createHandle<T>(queue: Promise<void>, work: (signal: AbortSignal) => Promise<T>, externalSignal?: AbortSignal): {
-  handle: Handle<T>;
-  settled: Promise<void>;
-};
 //#endregion
 //#region src/core/agent/types.d.ts
 /**
@@ -505,7 +548,7 @@ type AgentDefinitionResolver = (definition: AgentDefinition) => MaybePromise<Res
  * renderable turn state. It intentionally does not include executable runtime
  * objects such as providers, tools, MCP clients, memory implementations, file
  * resolvers, or tracers. Recreate those from host-owned configuration, then
- * call `agent.restore(session)`.
+ * construct a new agent with the session: `new Agent(config, session)`.
  *
  * @typeParam TAnnotation - Annotation union supported by the host renderer.
  */
@@ -514,8 +557,12 @@ interface AgentSession<TAnnotation extends Annotation = Annotation> {
   version: 1;
   /** Stable conversation/session id. */
   sessionId: string;
-  /** Canonical model-facing message history used for continuation. */
+  /** Active model-facing conversation used for continuation. */
   messages: AxleMessage[];
+  /** Complete chronological record of every appended message, untouched by compaction. May be empty; absent in pre-compaction snapshots. */
+  archive?: AxleMessage[];
+  /** Compaction records, in order. Empty when no compaction has run; absent in pre-compaction snapshots. */
+  compactions?: CompactionRecord[];
   /** Renderable turn state for exact UI restoration. */
   turns?: Turn<TAnnotation>[];
   /** Session-level annotations for generic renderer state. */
@@ -545,6 +592,22 @@ interface AgentErrorResult {
 }
 type AgentHandle<T = string> = Handle<AgentResult<T> | AgentErrorResult>;
 type TurnEventCallback = (event: TurnEvent) => void;
+/**
+ * Caller-supplied compaction policy and strategy.
+ *
+ * The callback owns the decision: return `null` for "not now" (cheap — the
+ * usage estimate is local), or the complete new active conversation. The
+ * engine owns validation, record stamping, state processing, and event
+ * emission.
+ *
+ * @experimental Compaction is under active design and may change in any release.
+ */
+type CompactionCallback = (state: {
+  messages: AxleMessage[];
+}, context: {
+  usage: ContextUsage;
+  signal?: AbortSignal;
+}) => MaybePromise<AxleMessage[] | null>;
 interface SendMessageOptions extends AxleModelRequestOptions {
   fileResolver?: FileResolver;
   /**
@@ -571,7 +634,9 @@ declare class Agent {
   private spanParent?;
   private ownedTracer?;
   private eventCallbacks;
-  private sendQueue;
+  private compactionCallback?;
+  private workQueue;
+  private accumulator;
   /**
    * Create an agent from runtime config and, optionally, restore saved session state.
    *
@@ -584,25 +649,63 @@ declare class Agent {
   hasTools(): boolean;
   on(callback: TurnEventCallback): () => void;
   context(): ContextUsage;
+  private estimateContext;
   /**
-   * Capture the serializable session state for later continuation.
+   * Register the compaction callback: the policy and strategy for shrinking
+   * the active conversation. One callback per agent; registering again
+   * replaces it.
+   */
+  onCompaction(callback: CompactionCallback): void;
+  /**
+   * Run the registered compaction callback against the active conversation.
+   *
+   * Compaction is optional: with no callback registered this is a no-op that
+   * resolves `null`. Otherwise the call is enqueued behind in-flight sends so
+   * compaction never races a turn. The callback may return `null` to skip;
+   * cancellation also resolves `null`. Errors propagate — a manual compact
+   * was explicitly requested.
    *
-   * The returned object contains message history and renderable turn state, but
-   * not executable configuration such as providers, tools, MCP clients, memory,
-   * or tracers.
+   * Do not await this from inside a running send (a tool's `execute`,
+   * `onToolCall`, or a compaction callback): the send holds the queue, so the
+   * nested call deadlocks.
    */
-  snapshot(): AgentSession;
+  compact(options?: {
+    signal?: AbortSignal;
+  }): Promise<CompactionRecord | null>;
   /**
-   * Replace the agent's continuation and render state from a saved session.
+   * Capture the serializable session state for later continuation.
    *
-   * Restore does not change runtime configuration. The current provider, model,
-   * tools, MCP clients, memory, and other constructor-supplied objects remain in
-   * effect.
+   * Enqueued behind in-flight sends and compactions, so the capture is
+   * always at rest — a snapshot never contains a streaming or running turn.
+   * The returned object contains message history and renderable turn state,
+   * but not executable configuration such as providers, tools, MCP clients,
+   * memory, or tracers.
+   *
+   * Do not await this from inside a running send (a tool's `execute`,
+   * `onToolCall`, or a compaction callback): the send holds the queue, so the
+   * nested call deadlocks.
    */
-  restore(session: AgentSession): void;
+  snapshot(): Promise<AgentSession>;
   send(message: string | Instruct<undefined>, options?: SendMessageOptions): AgentHandle<string>;
   send<TSchema extends OutputSchema>(instruct: Instruct<TSchema>, options?: SendMessageOptions): AgentHandle<ParsedSchema<TSchema>>;
+  /**
+   * Enqueue work behind everything already queued on this agent. Sends and
+   * compactions share one queue, so they never overlap.
+   *
+   * The work is exposed as two promises: `final` carries the outcome to the
+   * caller; `workQueue` carries only sequencing, with the outcome stripped —
+   * a rejected `final` in the queue would poison the chain and block all
+   * later work. Cancelled work still runs in order, but with an
+   * already-aborted signal.
+   */
+  private queue;
   private resolveMcpTools;
+  /**
+   * The single write path for renderable turn state: every event folds
+   * through the agent-lifetime accumulator, History mirrors the result, and
+   * subscribers are notified. Engine-internal state and consumer-folded
+   * state agree by construction because they run the same fold.
+   */
   private emitEvent;
   private toToolDefinitions;
   private run;
@@ -679,6 +782,8 @@ declare function anthropic(apiKey: string, options?: ProviderClientOptions): AIP
 //#region src/providers/anthropic/index.d.ts
 declare const Anthropic: {
   readonly Models: {
+    readonly CLAUDE_SONNET_5: "claude-sonnet-5";
+    readonly CLAUDE_FABLE_5: "claude-fable-5";
     readonly CLAUDE_OPUS_4_8: "claude-opus-4-8";
     readonly CLAUDE_OPUS_4_7: "claude-opus-4-7";
     readonly CLAUDE_SONNET_4_6: "claude-sonnet-4-6";
@@ -728,6 +833,8 @@ declare function gemini(apiKey: string, options?: ProviderClientOptions): AIProv
 //#region src/providers/gemini/index.d.ts
 declare const Gemini: {
   readonly Models: {
+    readonly GEMINI_3_5_PRO: "gemini-3.5-pro";
+    readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
     readonly GEMINI_3_1_PRO_PREVIEW: "gemini-3.1-pro-preview";
     readonly GEMINI_3_1_PRO: "gemini-3.1-pro-preview";
     readonly GEMINI_3_1_PRO_PREVIEW_CUSTOMTOOLS: "gemini-3.1-pro-preview-customtools";
@@ -737,7 +844,6 @@ declare const Gemini: {
     readonly GEMINI_3_PRO: "gemini-3-pro-preview";
     readonly GEMINI_3_FLASH_PREVIEW: "gemini-3-flash-preview";
     readonly GEMINI_3_FLASH: "gemini-3-flash-preview";
-    readonly GEMINI_3_5_FLASH: "gemini-3.5-flash";
     readonly GEMINI_2_5_PRO: "gemini-2.5-pro";
     readonly GEMINI_2_5_FLASH: "gemini-2.5-flash";
     readonly GEMINI_2_5_FLASH_LITE: "gemini-2.5-flash-lite";
@@ -763,6 +869,13 @@ interface GenerateParams extends AxleModelRequestOptions {
   registry?: ToolRegistry;
   onToolCall?: ToolCallCallback;
   maxIterations?: number;
+  /**
+   * Context budget for the tool loop, in tokens. Checked at each request
+   * boundary against the previous model call's reported usage (effective
+   * input + output); when crossed, the loop returns `stopped: "token-limit"`
+   * with everything accumulated so far.
+   */
+  maxContextTokens?: number;
   span?: Span;
   fileResolver?: FileResolver;
 }
@@ -804,87 +917,71 @@ type StreamEvent = {
   message: AxleToolCallMessage;
 } | {
   type: "text:start";
-  index: number;
 } | {
   type: "text:delta";
-  index: number;
   delta: string;
   accumulated: string;
 } | {
   type: "text:citation";
-  index: number;
   citation: Citation;
   citations: Citation[];
 } | {
   type: "text:end";
-  index: number;
   final: string;
 } | {
   type: "citation";
-  index: number;
   citations: Citation[];
   providerMetadata?: Record<string, unknown>;
 } | {
   type: "thinking:start";
-  index: number;
   redacted?: boolean;
   continuity?: ThinkingContinuity;
   providerMetadata?: Record<string, unknown>;
 } | {
   type: "thinking:delta";
-  index: number;
   delta: string;
   accumulated: string;
 } | {
   type: "thinking:summary-delta";
-  index: number;
   delta: string;
   accumulated: string;
 } | {
   type: "thinking:update";
-  index: number;
   redacted?: boolean;
   continuity?: ThinkingContinuity;
   providerMetadata?: Record<string, unknown>;
 } | {
   type: "thinking:end";
-  index: number;
   final: string;
 } | {
   type: "tool:request";
-  index: number;
   id: string;
   name: string;
   kind?: "tool" | "agent";
 } | {
   type: "tool:args-delta";
-  index: number;
   id: string;
   name: string;
   delta: string;
   accumulated: string;
 } | {
   type: "tool:exec-start";
-  index: number;
   id: string;
   name: string;
   parameters: Record<string, unknown>;
 } | {
   type: "tool:exec-delta";
-  index: number;
   id: string;
   name: string;
   chunk: ToolProgressChunk;
 } | {
   type: "tool:exec-complete";
-  index: number;
   id: string;
   name: string;
   result: ToolCallResult;
   usage?: Stats;
 } | {
   type: "tool:exec-error";
-  index: number;
   id: string;
   name: string;
   error: {
@@ -894,12 +991,10 @@ type StreamEvent = {
   usage?: Stats;
 } | {
   type: "provider-tool:start";
-  index: number;
   id: string;
   name: string;
 } | {
   type: "provider-tool:complete";
-  index: number;
   id: string;
   name: string;
   output?: unknown;
@@ -918,6 +1013,14 @@ interface StreamParams extends AxleModelRequestOptions {
   registry?: ToolRegistry;
   onToolCall?: ToolCallCallback;
   maxIterations?: number;
+  /**
+   * Context budget for the tool loop, in tokens. Checked after each turn's
+   * tools are answered, against that turn's reported usage (effective input
+   * + output); when crossed, the loop returns `stopped: "token-limit"` with
+   * everything accumulated so far. The caller decides what to do — e.g.
+   * compact the conversation and start a new stream.
+   */
+  maxContextTokens?: number;
   span?: Span;
   fileResolver?: FileResolver;
 }
@@ -1137,4 +1240,4 @@ declare function createStats(): Stats;
 declare function addStats(total: Stats, usage?: Stats): void;
 declare function mergeStats(...usages: Array<Stats | undefined>): Stats;
 //#endregion
-export { type AIProvider, type AccumulatableEvent, type ActionPart, type ActionResult, Agent, type AgentConfig, type AgentDefinition, type AgentDefinitionRequestOptions, type AgentDefinitionResolver, type AgentErrorResult, type AgentHandle, type AgentMemory, type AgentResult, type AgentSession, type Annotation, type AnnotationEvent, type AnnotationPlacement, type AnnotationStatus, type AnnotationTarget, Anthropic, AxleAbortError, AxleAgentAbortError, type AxleAssistantMessage, type AxleConfiguration, AxleError, type AxleMessage, type AxleModelRequestOptions, AxleStopReason, type AxleToolCallMessage, type AxleToolCallResult, AxleToolFatalError, type AxleUserMessage, type BraveWebSearchOptions, type ChatCompletionsOptions, type ChatCompletionsVendor, type Citation, type CitationOutputSpan, type CitationPart, type CitationSource, type ContentPart, type ContentPartCitation, type ContentPartFile, type ContentPartProviderTool, type ContentPartText, type ContentPartThinking, type ContentPartToolCall, type ContextUsage, type CreateAgentToolOptions, type DeferredFileInfo, type DocumentLocator, type EventLevel, type ExecutableTool, type FileInfo, type FileKind, type FilePart, type FileProviderId, type FileResolveFormat, type FileResolveRequest, type FileResolver, type FileStore, Gemini, type GenerateInstructParams, type GenerateInstructResult, type GenerateParams, type Handle, History, Instruct, type InstructContextSection, type InstructInputs, type InstructOptions, type InstructResponse, InstructVariableError, type InstructVarsMode, type LLMRequest, type LLMResponse, type LLMResult, type LogEntry, type LogFn, LogWriter, MCP, type MCPConfig, type MCPHttpConfig, type MCPStdioConfig, type MaybePromise, type MemoryContext, type MessageMetadata, type ObservabilityOptions, OpenAI, type OutputSchema, type ParallelToolResult, type ParallelizeOptions, type ParsedSchema, type ProviderClientOptions, type ProviderDefinition, type ProviderOptions, type ProviderTool, type ProviderToolAction, type ProviderToolDefinitionRef, type RecallResult, type ResolvedAgentDefinition, type ResolvedFileSource, type SavedAgent, type SendMessageOptions, SimpleWriter, type SimpleWriterOptions, type Span, type SpanData, type SpanEvent, type SpanOptions, type SpanResult, type SpanStatus, type SpanType, type Stats, type StreamEvent, type StreamEventCallback, type StreamHandle, type StreamInstructHandle, type StreamInstructParams, type StreamInstructResult, type StreamParams, type StreamResult, type SubagentAction, TaskError, type TextPart, type ThinkingContinuity, type ThinkingPart, type TokenStats, type TokenUsage, type ToolAction, type ToolChoice, type ToolContext, type ToolDefinition, type ToolDefinitionRef, type ToolProgressChunk, ToolRegistry, type ToolResult, type ToolResultPart, type TraceWriter, Tracer, type TracerOptions, type Turn, TurnAccumulator, type TurnAccumulatorResult, type TurnAccumulatorState, type TurnEvent, TurnEventBuilder, type TurnEventCallback, type TurnMetadata, type TurnPart, type TurnStatus, type UsageEntry, type WebSearchBackend, type WebSearchBackendContext, type WebSearchRequest, type WebSearchResponse, type WebSearchResult, addStats, anthropic, braveWebSearch, chatCompletions, configureAxle, createAgentConfig, createAgentTool, createHandle, createStats, estimateContextUsage, gemini, generate, generateTurn, loadFileContent, mergeStats, openai, parallelize, parseResponse, stream };
+export { type AIProvider, type AccumulatableEvent, type ActionPart, type ActionResult, Agent, type AgentConfig, type AgentDefinition, type AgentDefinitionRequestOptions, type AgentDefinitionResolver, type AgentErrorResult, type AgentHandle, type AgentMemory, type AgentResult, type AgentSession, type Annotation, type AnnotationEvent, type AnnotationPlacement, type AnnotationStatus, type AnnotationTarget, Anthropic, AxleAbortError, AxleAgentAbortError, type AxleAssistantMessage, type AxleConfiguration, AxleError, type AxleMessage, type AxleModelRequestOptions, AxleStopReason, type AxleToolCallMessage, type AxleToolCallResult, AxleToolFatalError, type AxleUserMessage, type BraveWebSearchOptions, type ChatCompletionsOptions, type ChatCompletionsVendor, type Citation, type CitationOutputSpan, type CitationPart, type CitationSource, type CompactionCallback, type CompactionPart, type CompactionRecord, type ContentPart, type ContentPartCitation, type ContentPartFile, type ContentPartProviderTool, type ContentPartText, type ContentPartThinking, type ContentPartToolCall, type ContextUsage, type CreateAgentToolOptions, type DeferredFileInfo, type DocumentLocator, type EventLevel, type ExecutableTool, type FileInfo, type FileKind, type FilePart, type FileProviderId, type FileResolveFormat, type FileResolveRequest, type FileResolver, type FileStore, Gemini, type GenerateInstructParams, type GenerateInstructResult, type GenerateParams, type Handle, History, Instruct, type InstructContextSection, type InstructInputs, type InstructOptions, type InstructResponse, InstructVariableError, type InstructVarsMode, type LLMRequest, type LLMResponse, type LLMResult, type LogEntry, type LogFn, LogWriter, MCP, type MCPConfig, type MCPHttpConfig, type MCPStdioConfig, type MaybePromise, type MemoryContext, type MessageMetadata, type ObservabilityOptions, OpenAI, type OutputSchema, type ParallelToolResult, type ParallelizeOptions, type ParsedSchema, type ProviderClientOptions, type ProviderDefinition, type ProviderOptions, type ProviderTool, type ProviderToolAction, type ProviderToolDefinitionRef, type RecallResult, type ResolvedAgentDefinition, type ResolvedFileSource, type SavedAgent, type SendMessageOptions, SimpleWriter, type SimpleWriterOptions, type Span, type SpanData, type SpanEvent, type SpanOptions, type SpanResult, type SpanStatus, type SpanType, type Stats, type StreamEvent, type StreamEventCallback, type StreamHandle, type StreamInstructHandle, type StreamInstructParams, type StreamInstructResult, type StreamParams, type StreamResult, type SubagentAction, TaskError, type TextPart, type ThinkingContinuity, type ThinkingPart, type TokenStats, type TokenUsage, type ToolAction, type ToolChoice, type ToolContext, type ToolDefinition, type ToolDefinitionRef, type ToolProgressChunk, ToolRegistry, type ToolResult, type ToolResultPart, type TraceWriter, Tracer, type TracerOptions, type Turn, TurnAccumulator, type TurnAccumulatorResult, type TurnAccumulatorState, type TurnEvent, TurnEventBuilder, type TurnEventCallback, type TurnMetadata, type TurnPart, type TurnStatus, type UsageEntry, type WebSearchBackend, type WebSearchBackendContext, type WebSearchRequest, type WebSearchResponse, type WebSearchResult, addStats, anthropic, braveWebSearch, chatCompletions, configureAxle, createAgentConfig, createAgentTool, createStats, estimateContextUsage, gemini, generate, generateTurn, loadFileContent, mergeStats, openai, parallelize, parseResponse, stream, validateCompactedMessages };