@ultimat3/ai 29.4.0 → 30.1.0

package/src/agent-checkpoint.ts

@@ -0,0 +1,44 @@
+// Single responsibility: `onCheckpoint` — a signed handle for the run so far, handed to the app
+// after a turn's tool results (or its correction) land and before the next turn is bought, so a
+// worker that dies mid-run leaves something to `.continue()` from. Sealed only when the hook is
+// declared: a run without it pays nothing and is byte-identical.
+
+import type { Span } from '@ultimat3/core';
+import type { AgentCheckpoint, TranscriptBinding } from './agent-continue';
+import { sealTranscript } from './agent-continue';
+import type { AgentRunUsage } from './agent-usage';
+import type { AiMessage } from './provider';
+
+/** What one checkpoint is cut from: the transcript after turn `turn`, and the run's total. */
+export interface CheckpointState {
+  readonly turn: number;
+  readonly messages: readonly AiMessage[];
+  readonly run: AgentRunUsage;
+  /** Compactions so far, continuations included — signed, like a finished handle's. */
+  readonly compacted: number;
+}
+
+export type Checkpointer = (state: CheckpointState) => Promise<void>;
+
+/**
+ * `undefined` without a hook — the loop then seals nothing. Awaited, and a throw fails the run, as
+ * `onTurn`'s does: a checkpoint that silently stopped reads exactly like one that works.
+ */
+export function checkpointer<A>(
+  hook: ((event: AgentCheckpoint, args: A) => void | Promise<void>) | undefined,
+  args: A,
+  binding: TranscriptBinding,
+  span: Span,
+): Checkpointer | undefined {
+  if (hook === undefined) return undefined;
+  return async ({ turn, messages, run, compacted }) => {
+    const transcript = sealTranscript(binding, {
+      messages,
+      turns: turn,
+      usage: run.usage,
+      ...(compacted > 0 ? { compacted } : {}),
+    });
+    span.addEvent('agent.checkpoint', { 'agent.checkpoint.turn': turn });
+    await hook({ turn, transcript, run }, args);
+  };
+}

package/src/agent-compact-def.ts

@@ -60,6 +60,17 @@ export interface AgentCompaction {
   readonly compactions: number;
   /** The model that was asked for the summary. */
   readonly model: ModelId;
+  /**
+   * How the turns reached the summary call: `'messages'`, the run's own request up to the cut
+   * (it reads the cached prefix), or `'text'` when those did not fit the writer — re-sent as text,
+   * oldest tool results clipped to their first and last 1,000 characters, then left out. Absent
+   * when no call was built.
+   */
+  readonly summaryInput?: 'messages' | 'text';
+  /** On `'text'`: turns, oldest first, whose tool results were clipped or left out. */
+  readonly clipped?: number;
+  /** On `'text'`: of those, the turns whose tool results were left out entirely. */
+  readonly omitted?: number;
   /** The summary call's usage and cost; absent when no call was made. Already in the run's total. */
   readonly usage?: TokenUsage;
   readonly cost?: Money;

package/src/agent-compact-measure.ts

@@ -0,0 +1,38 @@
+// Single responsibility: what one run has MEASURED about its prompt size — the ratio of the tokens
+// a provider reported for a turn to the four-characters-a-token estimate of that request. Dense JSON
+// and non-Latin text run at one to two characters a token, so the estimate alone let a run walk past
+// the window it was meant to compact before.
+
+import type { TokenUsage } from './provider';
+
+/** One run's measurement. Starts at 1 (the estimate as is); never below it, never signed into a handle. */
+export interface PromptMeasure {
+  /** Read a turn's reported input against the request that produced it. */
+  observe(usage: TokenUsage, estimate: number): void;
+  /** The provider refused `estimate` as over `room`: the real figure is at least `room + 1`. */
+  overflowed(estimate: number, room: number): void;
+  /** `estimate` as the provider would count it, on what this run has seen so far. */
+  scale(estimate: number): number;
+}
+
+/** The prompt half a provider reports: every input token, read from the cache or not. */
+export const reportedInput = (usage: TokenUsage): number =>
+  usage.inputTokens + usage.cacheReadTokens + usage.cacheWriteTokens;
+
+export function promptMeasure(): PromptMeasure {
+  let ratio = 1;
+  return {
+    observe(usage, estimate) {
+      const reported = reportedInput(usage);
+      // A provider reporting nothing (a cache hit, a wire with no usage) says nothing: the last
+      // measurement stands. Below 1 is ignored — the estimate may stay pessimistic.
+      if (reported <= 0 || estimate <= 0) return;
+      ratio = Math.max(1, reported / estimate);
+    },
+    overflowed(estimate, room) {
+      if (estimate <= 0) return;
+      ratio = Math.max(ratio, (room + 1) / estimate);
+    },
+    scale: (estimate) => Math.ceil(estimate * ratio),
+  };
+}

package/src/agent-compact-request.ts

@@ -0,0 +1,100 @@
+// Single responsibility: the ONE request a compaction's summary call sends. The run's own request
+// up to the cut, plus the instruction, when that fits the writer — it reads the cached prefix.
+// Otherwise the same tools, system and first message, then the turns to summarise as TEXT,
+// shortened oldest first (./agent-compact-text) — never a second call, never a dropped turn.
+
+import { shortestFit } from './agent-compact-text';
+import type { ModelId } from './models';
+import type { AiContentBlock, AiMessage, GenerateRequest } from './provider';
+
+/** How a compacted first message's summary block starts — the marker a later compaction reads. */
+export const COMPACTED_MARK = '[compacted:';
+
+/** What the summary call is asked, appended to the last message it is sent. */
+export const SUMMARY_INSTRUCTION = `${COMPACTED_MARK} instruction] This conversation is about to be shortened to fit the context window: everything after the task in the first message, any earlier summary included, will be replaced by the summary you write now. Summarise it for yourself — what you did, every tool you called and what it returned (keep exact ids, numbers, names and quotes you will still need), what you concluded, and what remains to do. Do not call any tool. Reply with the summary as plain text only.`;
+
+/** Opens the text form's transcript block: what it is, and that it may have been shortened. */
+export const TRANSCRIPT_NOTE = `${COMPACTED_MARK} transcript] The turns after the task, oldest first, as text: they did not fit as messages. The oldest tool results may be clipped (their start and end kept) or left out — say so in the summary where it matters.`;
+
+/** The turns before the cut, split off the first message and the kept ones. */
+export interface SummarySplit {
+  /** The first user message: the rendered prompt, and any earlier summary. */
+  readonly head: AiMessage;
+  /** Whole turns — an assistant message and the user message answering it — oldest first. */
+  readonly older: readonly AiMessage[];
+}
+
+/** How the summarised turns reached the summary call. */
+export type SummaryInput =
+  | { readonly form: 'messages' }
+  | { readonly form: 'text'; readonly clipped: number; readonly omitted: number };
+
+export interface SummaryCall {
+  readonly request: GenerateRequest;
+  readonly input: SummaryInput;
+}
+
+/**
+ * The summary call for `split`: as messages when `fits` takes them, else as text shortened until
+ * it does. `undefined` when even every tool result left out does not fit.
+ */
+export function summaryCall(
+  base: GenerateRequest,
+  writer: ModelId,
+  maxTokens: number,
+  split: SummarySplit,
+  fits: (request: GenerateRequest) => boolean,
+): SummaryCall | undefined {
+  const asMessages = writerRequest(base, writer, maxTokens, withInstruction(split));
+  if (fits(asMessages)) return { request: asMessages, input: { form: 'messages' } };
+  const asText = (transcript: string): GenerateRequest =>
+    writerRequest(base, writer, maxTokens, textForm(split.head, transcript));
+  const fit = shortestFit(pairsOf(split.older), (text) => fits(asText(text)));
+  if (fit === undefined) return undefined;
+  const { clipped, omitted } = fit;
+  return { request: asText(fit.text), input: { form: 'text', clipped, omitted } };
+}
+
+/**
+ * The run's own tools, system and cache hint, so the provider reads the prefix the run wrote. A
+ * different summary model takes none of the run model's reasoning controls: one it lacks would be
+ * `X_AI_REQUEST_INVALID`.
+ */
+function writerRequest(
+  base: GenerateRequest,
+  writer: ModelId,
+  maxTokens: number,
+  messages: readonly AiMessage[],
+): GenerateRequest {
+  if (writer === base.model) return { ...base, messages, maxTokens };
+  const { effort: _effort, thinking: _thinking, ...rest } = base;
+  return { ...rest, model: writer, messages, maxTokens };
+}
+
+/** Roles must alternate, and the older turns end on a user message: the instruction joins it. */
+function withInstruction(split: SummarySplit): readonly AiMessage[] {
+  const messages = [split.head, ...split.older];
+  const last = messages.at(-1) ?? split.head;
+  return [...messages.slice(0, -1), { role: 'user', content: [...blocksOf(last), instruction()] }];
+}
+
+/** The first message as it was sent — its bytes, its cache — then the transcript, then the ask. */
+function textForm(head: AiMessage, transcript: string): readonly AiMessage[] {
+  const block = { type: 'text' as const, text: `${TRANSCRIPT_NOTE}\n\n${transcript}` };
+  return [{ role: 'user', content: [...blocksOf(head), block, instruction()] }];
+}
+
+const instruction = (): AiContentBlock => ({ type: 'text', text: SUMMARY_INSTRUCTION });
+
+/** The older turns, two messages each: the cut is between turns, so they pair exactly. */
+function pairsOf(older: readonly AiMessage[]): readonly (readonly AiMessage[])[] {
+  const pairs: AiMessage[][] = [];
+  for (let i = 0; i < older.length; i += 2) pairs.push(older.slice(i, i + 2));
+  return pairs;
+}
+
+export function blocksOf(message: AiMessage): readonly AiContentBlock[] {
+  return typeof message.content === 'string'
+    ? [{ type: 'text', text: message.content }]
+    : message.content;
+}

package/src/agent-compact-text.ts

@@ -0,0 +1,95 @@
+// Single responsibility: the turns to summarise as TEXT, shortened oldest first until they fit —
+// the summary call's input when the run's own messages up to the cut do not. Tool results are
+// clipped to their start and end, then left out; a turn itself is never dropped. Where the design
+// came from: `docs/history/ai.md`.
+
+import type { AiContentBlock, AiMessage } from './provider';
+
+/** The characters of one tool result a clipped turn keeps: half from its start, half from its end. */
+export const SUMMARY_CLIP_CHARS = 2_000;
+
+/** One turn's render at each shortening: whole, its tool results clipped, its tool results left out. */
+type Renders = readonly [whole: string, clipped: string, omitted: string];
+
+/** The transcript that fit, and how far it was shortened to. */
+export interface TextTranscript {
+  readonly text: string;
+  /** Turns, oldest first, whose tool results were clipped or left out. */
+  readonly clipped: number;
+  /** ...of those, the turns whose tool results were left out entirely. */
+  readonly omitted: number;
+}
+
+/**
+ * `value` cut to `max` characters, the first and last halves kept — the end of a tool result is
+ * where its error, its count or its last row is. By code point, so no surrogate pair is split.
+ * Never longer than `value`: a cut that would add more marker than it removes is not made.
+ */
+export function clipText(value: string, max: number = SUMMARY_CLIP_CHARS): string {
+  if (value.length <= max) return value;
+  const chars = Array.from(value);
+  const half = Math.floor(max / 2);
+  const left = chars.length - 2 * half;
+  if (left <= 0) return value;
+  const clipped = `${chars.slice(0, half).join('')}\n[… ${left} characters left out …]\n${chars.slice(-half).join('')}`;
+  return clipped.length < value.length ? clipped : value;
+}
+
+/**
+ * The least shortening of `turns` (each an assistant message and the user message answering it)
+ * that `fits`: every turn reaches a level before any turn reaches the next, oldest first.
+ * `undefined` when even every tool result left out does not fit.
+ */
+export function shortestFit(
+  turns: readonly (readonly AiMessage[])[],
+  fits: (text: string) => boolean,
+): TextTranscript | undefined {
+  const renders = turns.map(rendersOf);
+  const n = renders.length;
+  // Shortening `s` (0..2n): turns before `s` clipped, turns before `s - n` left out. Each step
+  // only ever shortens one turn, so the size falls with `s` and the least `s` that fits is found
+  // by bisection — a handful of estimates, never one per turn.
+  const at = (s: number): string =>
+    renders.map((render, i) => render[(i < s ? 1 : 0) + (i < s - n ? 1 : 0)]).join('\n\n');
+  if (!fits(at(2 * n))) return undefined;
+  let low = 0;
+  let high = 2 * n;
+  while (low < high) {
+    const mid = Math.floor((low + high) / 2);
+    if (fits(at(mid))) high = mid;
+    else low = mid + 1;
+  }
+  return { text: at(low), clipped: Math.min(low, n), omitted: Math.max(0, low - n) };
+}
+
+function rendersOf(turn: readonly AiMessage[]): Renders {
+  const whole = render(turn, 0);
+  // A level is never longer than the one before it, so the bisection above stays sound.
+  const clipped = shorter(render(turn, 1), whole);
+  return [whole, clipped, shorter(render(turn, 2), clipped)];
+}
+
+const shorter = (a: string, b: string): string => (a.length < b.length ? a : b);
+
+const render = (turn: readonly AiMessage[], level: 0 | 1 | 2): string =>
+  turn
+    .flatMap((message) => blocksOf(message).map((block) => line(message.role, block, level)))
+    .filter((text) => text !== '')
+    .join('\n');
+
+function line(role: AiMessage['role'], block: AiContentBlock, level: 0 | 1 | 2): string {
+  if (block.type === 'text') return block.text === '' ? '' : `[${role}]: ${block.text}`;
+  if (block.type === 'tool_use') {
+    const input = JSON.stringify(block.input) ?? '';
+    return `[tool call ${block.name} #${block.id}]: ${level === 2 ? clipText(input) : input}`;
+  }
+  if (block.type === 'tool_result') {
+    const label = `${block.is_error === true ? 'tool error' : 'tool result'} #${block.tool_use_id}`;
+    if (level === 2) return `[${label} left out: ${block.content.length} characters]`;
+    return `[${label}]: ${level === 1 ? clipText(block.content) : block.content}`;
+  }
+  return `[${block.type} left out]`;
+}
+
+const blocksOf = (message: AiMessage): readonly AiContentBlock[] =>
+  typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : message.content;

package/src/agent-compact.ts

@@ -8,25 +8,27 @@
 // change, once, and the next turn writes the new, shorter prefix.
 //
 // Never a truncation: a summary that cannot be had leaves the transcript whole, and a whole
-// transcript that does not fit is `X_AGENT_CONTEXT_EXHAUSTED` before it is sent.
+// transcript that does not fit is `X_AGENT_CONTEXT_EXHAUSTED` before it is sent. Only the summary
+// call's INPUT is ever shortened (./agent-compact-request), when the turns do not fit it whole. The trigger reads
+// the estimate scaled by what the provider REPORTED (./agent-compact-measure); a provider that
+// refuses a request anyway (`X_AI_CONTEXT_OVERFLOW`) gets one forced compaction, then that code.
 
 import type { Ctx, Span } from '@ultimat3/core';
 import { stringField, throwIfAborted } from '@ultimat3/core';
 import type { AgentCompaction, CompactPlan } from './agent-compact-def';
+import { promptMeasure } from './agent-compact-measure';
+import type { SummaryInput, SummarySplit } from './agent-compact-request';
+import { blocksOf, COMPACTED_MARK, summaryCall } from './agent-compact-request';
 import { AgentContextExhaustedError } from './agent-errors';
 import type { RunDeadline } from './agent-guards';
 import type { Gateway } from './gateway';
 import type { ModelId } from './models';
 import { modelSpec } from './models';
-import type { AiContentBlock, AiMessage, GenerateRequest, GenerateResult } from './provider';
+import type { AiMessage, GenerateRequest, GenerateResult, TokenUsage } from './provider';
 import { estimateInputTokens, estimateTextTokens, isTruncated } from './provider';
 import { runMeter } from './run-meter';
 
-/** How a compacted first message's summary block starts — the marker a later compaction reads. */
-export const COMPACTED_MARK = '[compacted:';
-
-/** What the summary call is asked, appended to the last message it is sent. */
-export const SUMMARY_INSTRUCTION = `${COMPACTED_MARK} instruction] This conversation is about to be shortened to fit the context window: everything after the task in the first message, any earlier summary included, will be replaced by the summary you write now. Summarise it for yourself — what you did, every tool you called and what it returned (keep exact ids, numbers, names and quotes you will still need), what you concluded, and what remains to do. Do not call any tool. Reply with the summary as plain text only.`;
+export { COMPACTED_MARK, SUMMARY_INSTRUCTION } from './agent-compact-request';
 
 /** The run's own stops: thrown as themselves from the summary call, never read as its failure. */
 const RUN_STOPS: ReadonlySet<string> = new Set([
@@ -55,6 +57,17 @@ export interface CompactorInput {
 export interface Compactor {
   /** The messages the next turn sends: as given, compacted, or refused. */
   fit(messages: readonly AiMessage[], turn: number): Promise<readonly AiMessage[]>;
+  /** A turn answered: its reported input corrects every later estimate of this run. */
+  observe(usage: TokenUsage, request: GenerateRequest): void;
+  /**
+   * The provider refused `messages` as over the window (`refusal` is what it said): compact
+   * regardless of the trigger, or throw `X_AGENT_CONTEXT_EXHAUSTED`. Never returns them as given.
+   */
+  force(
+    messages: readonly AiMessage[],
+    turn: number,
+    refusal: string,
+  ): Promise<readonly AiMessage[]>;
   /** Compactions so far, continuations included — what the handle's `compacted` carries. */
   count(): number;
 }
@@ -84,6 +97,9 @@ export function compactor(input: CompactorInput): Compactor {
   // itself: each attempt is a billed call, and one that just failed is tried again only when the
   // run can no longer go on without it — never once per turn while it still fits.
   let trigger = plan.at * limit;
+  // Reported over estimated, per run: a continuation's first turn estimates plainly.
+  const measure = promptMeasure();
+  const measured = (request: GenerateRequest): number => measure.scale(promptTokens(request));
 
   const report = async (event: AgentCompaction): Promise<void> => {
     span.addEvent('agent.compact', {
@@ -95,20 +111,31 @@ export function compactor(input: CompactorInput): Compactor {
       'agent.compact.summarised_turns': event.summarised,
       'agent.compact.kept_turns': event.kept,
       ...(event.reason === undefined ? {} : { 'agent.compact.reason': event.reason }),
+      ...(event.summaryInput === undefined
+        ? {}
+        : {
+            'agent.compact.summary_input': event.summaryInput,
+            'agent.compact.clipped_turns': event.clipped ?? 0,
+            'agent.compact.omitted_turns': event.omitted ?? 0,
+          }),
       ...(event.cost === undefined ? {} : { 'llm.cost.minor': event.cost.minor }),
     });
     await input.onCompact?.(event);
   };
 
-  const fit = async (
+  /** `refusal` set: forced by a provider's overflow, so a failure can never go on whole. */
+  const attempt = async (
     messages: readonly AiMessage[],
     turn: number,
+    refusal: string | undefined,
   ): Promise<readonly AiMessage[]> => {
-    const before = promptTokens({ ...base, messages });
-    if (before <= trigger) return messages;
+    const before = measured({ ...base, messages });
+    if (refusal === undefined && before <= trigger) return messages;
     const facts = { turn, before, limit, model: writer };
     const split = splitTurns(messages, plan.keepTurns);
     const kept = split === undefined ? Math.floor(messages.length / 2) : plan.keepTurns;
+    // How the turns reached the summary call, once one is built — reported on either outcome.
+    let shape: SummaryInput | undefined;
     const failed = async (
       reason: string,
       summarised: number,
@@ -122,18 +149,20 @@ export function compactor(input: CompactorInput): Compactor {
         summarised,
         kept,
         compactions: count,
+        ...inputFacts(shape),
         ...(call === undefined ? {} : { usage: call.usage, cost: call.cost }),
       });
       // Still fits: the run goes on whole. Compaction is how a run stays under the window, never
       // a condition of running — the turns that fit are not refused for a summary that failed.
       trigger = limit;
-      if (before <= limit) return messages;
+      if (refusal === undefined && before <= limit) return messages;
       throw new AgentContextExhaustedError({
         agent: input.agent,
         model,
         estimate: before,
         limit,
         reason,
+        ...(refusal === undefined ? {} : { refused: refusal }),
       });
     };
 
@@ -141,10 +170,22 @@ export function compactor(input: CompactorInput): Compactor {
       return failed(`there is no turn older than the last ${plan.keepTurns} to summarise`, 0);
     }
     const summarised = split.older.length / 2;
-    const request = summaryRequest(base, writer, plan.maxSummaryTokens, split);
-    if (promptTokens(request) > roomOf(writer, plan.maxSummaryTokens)) {
-      return failed(`the turns to summarise do not fit model "${writer}" either`, summarised);
+    const room = roomOf(writer, plan.maxSummaryTokens);
+    const call = summaryCall(
+      base,
+      writer,
+      plan.maxSummaryTokens,
+      split,
+      (r) => measured(r) <= room,
+    );
+    if (call === undefined) {
+      return failed(
+        `the turns to summarise do not fit model "${writer}" even as text with every tool result left out`,
+        summarised,
+      );
     }
+    const { request } = call;
+    shape = call.input;
     throwIfAborted(input.ctx);
     input.deadline.check();
     input.assertCost(request);
@@ -172,7 +213,7 @@ export function compactor(input: CompactorInput): Compactor {
     }
     if (summary === '') return failed('the summary call answered no text', summarised, result);
     const compacted = [compactedHead(split.head, summarised, summary), ...split.kept];
-    const after = promptTokens({ ...base, messages: compacted });
+    const after = measured({ ...base, messages: compacted });
     if (after >= before) {
       return failed('the summary was no shorter than the turns it replaced', summarised, result);
     }
@@ -188,20 +229,26 @@ export function compactor(input: CompactorInput): Compactor {
       summarised,
       kept,
       compactions: count,
+      ...inputFacts(shape),
       usage: result.usage,
       cost: result.cost,
     });
     return compacted;
   };
 
-  return { fit, count: () => count };
+  return {
+    fit: (messages, turn) => attempt(messages, turn, undefined),
+    observe: (usage, request) => measure.observe(usage, promptTokens(request)),
+    force: (messages, turn, refusal) => {
+      // The provider counted more than the room: every estimate from here on is at least that.
+      measure.overflowed(promptTokens({ ...base, messages }), limit);
+      return attempt(messages, turn, refusal);
+    },
+    count: () => count,
+  };
 }
 
-interface Split {
-  /** The first user message: the rendered prompt, and any earlier summary. */
-  readonly head: AiMessage;
-  /** Whole turns — an assistant message and the user message answering it — oldest first. */
-  readonly older: readonly AiMessage[];
+interface Split extends SummarySplit {
   /** The last `keepTurns` turns, verbatim. */
   readonly kept: readonly AiMessage[];
 }
@@ -220,31 +267,6 @@ function splitTurns(messages: readonly AiMessage[], keepTurns: number): Split |
   return { head, older: messages.slice(1, cut), kept: messages.slice(cut) };
 }
 
-/**
- * The run's own request up to the cut, plus the instruction — the same tools, system and cache
- * hint, so the provider reads the prefix an earlier turn wrote. A different summary model takes
- * none of the run model's reasoning controls: one it lacks would be `X_AI_REQUEST_INVALID`.
- */
-function summaryRequest(
-  base: GenerateRequest,
-  writer: ModelId,
-  maxTokens: number,
-  split: Split,
-): GenerateRequest {
-  const messages = withInstruction([split.head, ...split.older]);
-  if (writer === base.model) return { ...base, messages, maxTokens };
-  const { effort: _effort, thinking: _thinking, ...rest } = base;
-  return { ...rest, model: writer, messages, maxTokens };
-}
-
-/** Roles must alternate, and the older turns end on a user message: the instruction joins it. */
-function withInstruction(messages: readonly AiMessage[]): readonly AiMessage[] {
-  const last = messages.at(-1);
-  const text = { type: 'text' as const, text: SUMMARY_INSTRUCTION };
-  if (last === undefined) return [{ role: 'user', content: SUMMARY_INSTRUCTION }];
-  return [...messages.slice(0, -1), { role: 'user', content: [...blocksOf(last), text] }];
-}
-
 /**
  * The first message, rebuilt: the prompt as it was sent (an earlier summary dropped — the new one
  * covers it), then the summary, marked. The model reads it as its own notes, said to be so.
@@ -257,8 +279,11 @@ function compactedHead(head: AiMessage, turns: number, summary: string): AiMessa
   return { role: 'user', content: [...prompt, { type: 'text', text: note }] };
 }
 
-function blocksOf(message: AiMessage): readonly AiContentBlock[] {
-  return typeof message.content === 'string'
-    ? [{ type: 'text', text: message.content }]
-    : message.content;
+/** The event's facts about the summary call's input: its form, and how far text was shortened. */
+function inputFacts(
+  shape: SummaryInput | undefined,
+): Pick<AgentCompaction, 'summaryInput' | 'clipped' | 'omitted'> {
+  if (shape === undefined) return {};
+  if (shape.form === 'messages') return { summaryInput: 'messages' };
+  return { summaryInput: 'text', clipped: shape.clipped, omitted: shape.omitted };
 }

package/src/agent-continue.ts

@@ -20,6 +20,7 @@ import {
   canonicalJson,
   currentSigningSecret,
   fingerprint,
+  hmac,
   isProduction,
   isUltimateError,
   usesDevCursorSecret,
@@ -83,6 +84,19 @@ export interface TranscriptBinding {
   readonly org: string | null;
 }
 
+/**
+ * `onCheckpoint`'s event: the run so far as a handle, after turn `turn`'s tool results or its
+ * correction landed and before turn `turn + 1` is bought. The same signed, bound shape a finished
+ * run returns, so `.continue(input, { transcript, user })` resumes from it and the screen refuses
+ * an edited or cross-tenant copy as it refuses any other.
+ */
+export interface AgentCheckpoint {
+  readonly turn: number;
+  readonly transcript: AgentTranscript;
+  /** The run's total so far, continuations included. */
+  readonly run: AgentRunUsage;
+}
+
 /** What `.run()` and `.continue()` resolve to: the validated answer and the handle to go on from. */
 export interface AgentRun<TOutput> {
   readonly output: TOutput;
@@ -218,9 +232,7 @@ const toolsMark = (names: readonly string[]): string => fingerprint([...names].s
 
 function signatureOf(fields: Omit<AgentTranscript, 'sig'>): string {
   // The framework's one signing secret (`ULTIMATE_CURSOR_SECRET`), under this file's own label.
-  return new Bun.CryptoHasher('sha256', currentSigningSecret())
-    .update(`${PURPOSE}\n${canonicalJson(fields)}`)
-    .digest('hex');
+  return hmac('sha256', currentSigningSecret(), `${PURPOSE}\n${canonicalJson(fields)}`, 'hex');
 }
 
 /** A handle for `state`, bound and signed. The one place a transcript is written. */

package/src/agent-def.ts

@@ -6,6 +6,7 @@ import type { Ctx } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { AgentCompaction, AgentCompactOption } from './agent-compact-def';
+import type { AgentCheckpoint } from './agent-continue';
 import type { AgentSystem } from './agent-system';
 import type { AgentRunUsage } from './agent-usage';
 import type { LlmBudget } from './llm';
@@ -173,6 +174,14 @@ export interface AgentDef<
    * throw fails the run. Also an `agent.compact` span event.
    */
   onCompact?(event: AgentCompaction): void | Promise<void>;
+  /**
+   * Called after each turn whose tool results (or correction) landed, before the next turn is
+   * bought — never after the answer, which `.run()` returns. Its `transcript` is a signed handle:
+   * store it, and a worker that died resumes with `.continue(input, { transcript, user })` instead
+   * of re-buying every turn. Awaited; a throw fails the run. Sealed only when declared. `args` is
+   * the run's own input and context, as `vars()` gets them: where the handle goes is the app's row.
+   */
+  onCheckpoint?(event: AgentCheckpoint, args: AgentVarsArgs<TInput>): void | Promise<void>;
 }
 
 /** One completed model turn, as an observer sees it. Facts only — no transcript, no actor. */

package/src/agent-errors.ts

@@ -1,6 +1,6 @@
 // The X_AGENT_* codes an UNATTENDED run needs, and the one a continuation's handle is refused by, apart from ./errors only because one file has
 // one job and that catalogue is at its ceiling — the split `hive-errors.ts` made. The codes, their
-// titles and the single `registerErrorCodes` call stay in ./errors.
+// titles and the single `registerErrorCodes` call stay in ./error-codes.
 
 import { UltimateError } from '@ultimat3/core';
 
@@ -101,10 +101,19 @@ export class AgentContextExhaustedError extends UltimateError {
     limit: number;
     /** Why compaction did not bring it under. */
     reason: string;
+    /**
+     * What the provider said when it refused the request as over the window
+     * (`X_AI_CONTEXT_OVERFLOW`): the run was SENT, and the refusal is the measurement.
+     */
+    refused?: string;
   }) {
+    const size =
+      input.refused === undefined
+        ? `next request is estimated at ${input.estimate} prompt tokens, over the ${input.limit} model "${input.model}" has room for (contextWindow less maxTokens)`
+        : `request was refused by the provider as over model "${input.model}"'s context window (${input.refused}); ${input.limit} tokens is its room (contextWindow less maxTokens)`;
     super({
       code: 'X_AGENT_CONTEXT_EXHAUSTED',
-      cause: `agent "${input.agent}"'s next request is estimated at ${input.estimate} prompt tokens, over the ${input.limit} model "${input.model}" has room for (contextWindow less maxTokens), and compaction could not bring it under: ${input.reason}`,
+      cause: `agent "${input.agent}"'s ${size}, and compaction could not bring it under: ${input.reason}`,
       fix: 'compact: { at: 0.6, keepTurns: 2 }   # on the agent — compact earlier and keep fewer turns verbatim; or lower maxToolResultChars, or run on a model whose registerModel row has a larger contextWindow',
       meta: {
         agent: input.agent,
@@ -112,6 +121,7 @@ export class AgentContextExhaustedError extends UltimateError {
         estimate: input.estimate,
         limit: input.limit,
         reason: input.reason,
+        ...(input.refused === undefined ? {} : { refused: input.refused }),
       },
     });
   }

package/src/agent-facts.ts

@@ -83,6 +83,14 @@ export function describeAgents(): readonly AgentFact[] {
     .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 
+/**
+ * One agent's facts, named yet or not — how `defineEval({ agent })` learns the prompt it measures.
+ * `undefined` for an action `agent()` did not build, and for a `named()` twin (see above).
+ */
+export function agentFactsOf(target: AnyAction): Omit<AgentFact, 'name'> | undefined {
+  return registry.get(target)?.();
+}
+
 /** Test-only reset. A module-level registry otherwise leaks between test files. */
 export function resetAgents(): void {
   registry.clear();