@ultimat3/ai 27.13.2 → 27.14.0

package/CLAUDE.md

@@ -65,6 +65,7 @@ one adds, the other adds.
 | `prompt-cache.ts` | PROVIDER prompt caching: `SystemParts`, `PromptCacheHint`, `PROMPT_CACHE_RULES` (sources in its header) |
 | `prompt-cache-blocks.ts` | the Anthropic wire's marks (chat-completions': `openai-messages.ts`) |
 | `agent-per-run.ts` / `agent-run-limits.ts` | one run's `offerTools()`/`model()`/`limits()`, narrow only; `costPerRun` |
+| `agent-compact-def.ts` / `agent-compact.ts` | `compact`'s declaration and event; the trigger, the cut, the summary call |
 | `agent-continue.ts` / `agent-turn.ts` | `.run()` / `.continue()`, the transcript handle and its screen; one turn's report and refusals |
 | `agent-transcript.ts` | what one turn leaves in the transcript: the assistant replay, the tool results, the correction |
 | `agent-facts.ts` | `describeAgents()` — the agent registry, and the row a manifest WOULD publish (its consumer has to be `cli`, tier 5) |
@@ -245,6 +246,10 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
   cursor secret, own label) and bound to agent, model, tool names and `orgId`; screened before
   anything is loaded. `maxTurns`/`tokensPerRun` are cumulative — the remainder is the ceiling,
   NEVER a ledger debit. A failure seals an updated handle onto the error (`transcriptOf`).
+- **`compact` (default `'auto'`) acts BEFORE a turn, never after a 400**: the summary call is the
+  run's own request up to a cut BETWEEN turns (the cached prefix, same session), billed, not a turn;
+  system, tools, kept turns byte-identical; failed → whole, or `X_AGENT_CONTEXT_EXHAUSTED`, never
+  truncated ([why](../../docs/history/ai.md#auto-compaction-2026-10)).
 - **`hive()` is a fan-out action** (`PRIMITIVE_FACTORIES`): `HiveResult` is a SCHEMA from the
   member's `output`; three arms (`ok`/`failed`/`skipped`) and three counters; `members` in SPLIT
   order with `index`; the hive never names an actor; no hive budget code; a member's throw goes
@@ -277,16 +282,10 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
 
 ## Invariants — evals, retrieval, fix lines
 
-Full text of each rule: [`docs/history/ai.md`](../../docs/history/ai.md#evals-retrieval-fix-lines).
-
-- **No fix line may name `x ai`** (planned); an eval is selected with `x test eval --filter <name>`.
-- An eval gates on the DROP from its baseline, mean AND per case; every prompt is named by an eval
-  (`X_EVAL_MISSING`); `ULTIMATE_EVAL_RECORD=1` records (`x verify` with it: `X_EVAL_RECORDING`).
-- Retrieval is hybrid, no vector-only path; `chunk()` hard-wraps; `VectorStore.prune` is required.
-- **An unbound store read inside a request whose actor has an `orgId` is `X_VECTOR_UNSCOPED`**
-  (both stores, every read); `scope: UNSCOPED` is the named opt-in, an omitted scope is `UNBOUND`.
-- `postgresVectorStore()` is the only production vector path (the live suite never skips); tenant
-  and policy filters in SQL on every statement and BOTH fusion halves; `scoped()` only TIGHTENS.
+In brief ([full text](../../docs/history/ai.md#evals-retrieval-fix-lines)): no fix line names
+`x ai`; an eval gates on the DROP from its baseline, mean AND per case, and every prompt has one;
+retrieval is hybrid only; an unbound store read under an org actor is `X_VECTOR_UNSCOPED`;
+`postgresVectorStore()` filters tenant and policy in SQL on every statement; `scoped()` TIGHTENS.
 
 ## Commands
 

package/README.md

@@ -445,6 +445,7 @@ sub-agent in its own `tools` and the sub-agent runs under the same actor, throug
 | `budget.costPerRun` caps the run's **money**: before each turn, what the run cost so far (continuations and nested calls included) plus that turn's worst-case estimate | `costPerCall` bounds one call and nothing bounded their sum; refused pre-flight as `X_AI_BUDGET_EXCEEDED` (scope `costPerRun`), never truncated |
 | one run may **narrow** its declaration, never widen it: `offerTools()` a subset of `tools` (another name is `X_AGENT_TOOL_UNDECLARED`), `model` as a function (resolved through the registry, `X_AI_MODEL_UNKNOWN`), `limits()` lower ceilings (a higher one is `X_AI_REQUEST_INVALID`) | a stored permission rule or model tier needed one declared agent per combination; the declaration stays the blast radius, and the handle binds the run's model and offered subset — [Agents → Per-run picks](https://github.com/developerz-ai/ultimate/wiki/Agents#per-run-picks-offertools-model-limits) |
 | a tool result is truncated, and says so | the transcript IS the request, so an untruncated result is re-billed once per remaining turn |
+| a run nearing its model's context window is **compacted** before the turn that would not fit (`compact`, default `'auto'`) | the transcript IS the request, so a long loop grew until the provider answered a 400 after every turn of it was paid for — [below](#auto-compaction) |
 | **no semantic cache** | similar prompts do not have similar answers once the answer depends on what `lookupOrder` returned this second |
 
 ### What a call cost
@@ -455,6 +456,55 @@ sub-agent in its own `tools` and the sub-agent runs under the same actor, throug
 
 `agent()` returns an `AgentAction`: the action, plus `.run(input, opts)` → `{ output, transcript, turns, usage }` and `.continue(input, { transcript, user }, opts)`, which appends one user turn to a stored transcript and resumes the loop. The transcript is re-sent byte for byte (the provider's prompt cache reads it back; no tool re-runs); `maxTurns` and `budget.tokensPerRun` are cumulative; the handle is signed, bound to the agent, model, tools and tenant, and screened (`X_AGENT_TRANSCRIPT_INVALID`); a failed call leaves an updated one on the error (`transcriptOf(error)`), which is the one a job stores. Full contract: [Agents → Continuing a run](https://github.com/developerz-ai/ultimate/wiki/Agents#continuing-a-run-run--continue).
 
+### Auto-compaction
+
+```ts
+import { agent, definePrompt, t } from '@ultimat3/ai';
+import { can } from '@ultimat3/policy';
+
+export const researcher = agent({
+  input: t.object({ question: t.string }),
+  output: t.object({ answer: t.string }),
+  prompt: definePrompt<{ question: string }>({
+    id: 'research',
+    version: '1.0.0',
+    template: 'Research: {{question}}',
+  }),
+  vars: ({ input }) => ({ question: input.question }),
+  tools: [],
+  policy: can('kb:ask'),
+  compact: { at: 0.8, keepTurns: 4, maxSummaryTokens: 2_048 }, // 'auto' (default) | 'off' | { …, model }
+  onCompact: ({ turn, outcome, reason, before, after, limit, summarised, kept, cost }) => {
+    console.log(turn, outcome, reason, before, after, limit, summarised, kept, cost?.minor);
+  },
+});
+```
+
+Before each turn, the gateway's estimate of that turn's request is compared with the model row's
+`contextWindow` less `maxTokens`. Over `at` of it, ONE model call summarises every turn older than
+the last `keepTurns`; the summary joins the first user message (after the prompt, verbatim, marked
+`[compacted: …]`), the kept turns follow byte for byte, and the turn is sent.
+
+| Rule | Why |
+|---|---|
+| default **`'auto'`**; `'off'` never compacts and never checks | a summary changes what the model sees, but only above `at` of the window, where the alternative is a run lost to a 400 after every turn was paid for. Below it a run is byte-identical to `'off'` — requests and handle — and it is never silent: `onCompact`, the `agent.compact` span event, the handle's `compacted` |
+| triggered on the **estimate of the next request** — the gateway's prompt estimate plus the tool definitions — over `at` × (`contextWindow` − `maxTokens`), before the call | after a 400 there is no request left to fix; `maxTokens` is reserved because the completion shares the window |
+| the system prompt, its stable block and the tools are **never touched** | a provider cache is a prefix match over tools → system → messages: they are the part every turn and every run shares, so they are still read at the cache rate after a compaction. Only the messages are rewritten, once |
+| the summary call is the run's **own request** up to the cut, plus one instruction — same gateway, tools, system and `promptCache` hint | it reads the prefix the turn that ended at the cut already cached instead of paying for it again; on OpenRouter the same `x-session-id` routes it to the provider holding that cache (`compact.model` trades that read for a cheaper writer) |
+| the cut falls **between turns**: the prompt and the last `keepTurns` (4, at least 1) turns are verbatim | a turn is an assistant message and the user message answering every `tool_use` in it, so no call is ever separated from its result (a 400 on every provider); the model keeps its task as written and the results it just asked for |
+| it summarises what the model was **sent** — tool results already redacted and cut to `maxToolResultChars` | the summary call reads nothing the run's turns did not; a later compaction folds the earlier summary in rather than stacking another |
+| the summary call is **billed to the run**: the same ledger (`tokensPerRun`), `costPerRun` checked before it, `usage`, `onTurn`'s `run`, `meta.billed`; priced at its own model's rates | it is spend like any other; a budget refusal, a deadline or an abort is thrown as itself, never read as a failed compaction |
+| it is **not a turn** — `maxTurns` and `onTurn` count the loop alone | the turn ceiling bounds the loop's decisions, and a summary is not one |
+| a failed summary (no text, cut off at `maxSummaryTokens`, refused, unreachable, no shorter) leaves the run **whole while it fits**; over the room it is **`X_AGENT_CONTEXT_EXHAUSTED`**, before the request is sent, registered `terminal` | never a truncated transcript — a model reasoning over a run it can no longer see answers confidently and wrong; and the same input outgrows the window on every job attempt |
+| after a failed attempt the next waits until the request **no longer fits** | each attempt is a billed call: one that just failed is not bought again on every turn the run can still take whole |
+| the handle stores the **compacted** messages and a signed `compacted` count, absent at zero | `.continue()` resumes from exactly what was sent, a continuation compacts on its own turns, and a run that never compacted writes the handle it always did |
+
+| Limit | Detail |
+|---|---|
+| the estimate | ~4 characters a token, which is why `at` defaults below 1 |
+| `tools: []` on the chat-completions wire | only `respond` is offered, so it is forced, the summary call answers no text and the run falls back to whole |
+| per run | `compact` is the declaration's; `limits()` does not take it, `describeAgents()` does not publish it |
+
 ### Provider prompt caching
 
 Not the gateway's response cache and not `llm()`'s semantic one: this asks the **provider** to keep
@@ -971,6 +1021,7 @@ fail-closed `terminal` default.
 | `X_AGENT_TOOL_UNDECLARED` | an `agent()` run's `offerTools()` named a tool its declaration does not list |
 | `X_AGENT_TOOL_LOOP` | an `agent()` made the same tool calls and read the same results `maxRepeatedToolCalls` turns in a row |
 | `X_AGENT_DEADLINE` | an `agent()` outlived its declared `deadlineMs` |
+| `X_AGENT_CONTEXT_EXHAUSTED` | an `agent()`'s next request would not fit its model's context window, and compaction could not bring it under; refused before it is sent |
 | `X_EVAL_THRESHOLD` | an eval scored below its bar |
 | `X_VECTOR_DIM_MISMATCH` | a vector's length disagrees with the store |
 | `X_VECTOR_SCOPE_WIDENED` | a derived vector scope tried to leave the tenant it was bound to |
@@ -986,6 +1037,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
+| `AgentContextExhaustedError` | `X_AGENT_CONTEXT_EXHAUSTED` | `src/agent-errors.ts` |
 | `AgentDeadlineError` | `X_AGENT_DEADLINE` | `src/agent-errors.ts` |
 | `AgentMaxTurnsError` | `X_AGENT_MAX_TURNS` | `src/errors.ts` |
 | `AgentToolLoopError` | `X_AGENT_TOOL_LOOP` | `src/agent-errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "27.13.2",
+  "version": "27.14.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -32,15 +32,15 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "27.13.2",
-    "@ultimat3/cache": "27.13.2",
-    "@ultimat3/core": "27.13.2",
-    "@ultimat3/db": "27.13.2",
-    "@ultimat3/http": "27.13.2",
-    "@ultimat3/jobs": "27.13.2",
-    "@ultimat3/money": "27.13.2",
-    "@ultimat3/policy": "27.13.2",
-    "@ultimat3/schema": "27.13.2",
-    "@ultimat3/time": "27.13.2"
+    "@ultimat3/action": "27.14.0",
+    "@ultimat3/cache": "27.14.0",
+    "@ultimat3/core": "27.14.0",
+    "@ultimat3/db": "27.14.0",
+    "@ultimat3/http": "27.14.0",
+    "@ultimat3/jobs": "27.14.0",
+    "@ultimat3/money": "27.14.0",
+    "@ultimat3/policy": "27.14.0",
+    "@ultimat3/schema": "27.14.0",
+    "@ultimat3/time": "27.14.0"
   }
 }

package/src/agent-compact-def.ts

@@ -0,0 +1,104 @@
+// Single responsibility: what an `agent({ compact })` declaration says — the option, its defaults,
+// the screen it passes at declaration, and the one event a compaction reports. ./agent-compact
+// owns the run-time half that reads them.
+
+import { finiteCount } from '@ultimat3/core';
+import type { Money } from '@ultimat3/money';
+import { AiRequestInvalidError } from './errors';
+import type { ModelId } from './models';
+import type { TokenUsage } from './provider';
+
+/** The fraction of the model's input room (`contextWindow - maxTokens`) that triggers a compaction. */
+export const DEFAULT_COMPACT_AT = 0.8;
+
+/** The most recent turns sent verbatim after a compaction — one turn is one assistant message and the user message answering it. */
+export const DEFAULT_KEEP_TURNS = 4;
+
+/** The summary call's completion ceiling when the declaration names none (held under `maxTokens`). */
+export const DEFAULT_MAX_SUMMARY_TOKENS = 2_048;
+
+export interface AgentCompactRule {
+  /** Compact once the next request is estimated over this fraction of the input room. 0 < at <= 1. */
+  readonly at?: number;
+  /** Turns kept verbatim, the newest. At least 1: the model must read the tool results it just asked for. */
+  readonly keepTurns?: number;
+  /** The model that writes the summary. Default: the run's own — which also reads the cached prefix. */
+  readonly model?: ModelId;
+  /** The summary call's completion ceiling. Default `min(2,048, maxTokens)`. */
+  readonly maxSummaryTokens?: number;
+}
+
+/** `'auto'` (the default) is `{}` — every default above. `'off'` never compacts and never checks. */
+export type AgentCompactOption = 'auto' | 'off' | AgentCompactRule;
+
+/** A declaration's `compact`, screened, defaults applied — `undefined` for `'off'`. */
+export interface CompactPlan {
+  readonly at: number;
+  readonly keepTurns: number;
+  readonly model: ModelId | undefined;
+  readonly maxSummaryTokens: number;
+}
+
+/** One compaction attempt, as an observer sees it. Facts only — never the summary, never the transcript. */
+export interface AgentCompaction {
+  /** The turn the compaction was for: the request about to be sent. */
+  readonly turn: number;
+  readonly outcome: 'compacted' | 'failed';
+  /** On `failed`: why. The run then went on uncompacted, or stopped with `X_AGENT_CONTEXT_EXHAUSTED`. */
+  readonly reason?: string;
+  /** The next request's estimated prompt tokens before the compaction. */
+  readonly before: number;
+  /** ...and after it — `before` again when it failed. */
+  readonly after: number;
+  /** The input room: the model's `contextWindow` less `maxTokens`. */
+  readonly limit: number;
+  /** Turns folded into the summary (0 when none were old enough). */
+  readonly summarised: number;
+  /** Turns sent verbatim after it. */
+  readonly kept: number;
+  /** Which compaction of the run this was, continuations included — 1-based. Counts successes only. */
+  readonly compactions: number;
+  /** The model that was asked for the summary. */
+  readonly model: ModelId;
+  /** 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;
+}
+
+const SUBJECT = 'agent';
+
+/** At DECLARATION, like every other bound: an `agent()` runs at module scope, so a bad one fails the boot. */
+export function screenCompact(
+  option: AgentCompactOption | undefined,
+  maxTokens: number,
+): CompactPlan | undefined {
+  if (option === 'off') return undefined;
+  const rule: AgentCompactRule = option === undefined || option === 'auto' ? {} : option;
+  if (typeof rule !== 'object' || rule === null) {
+    throw new AiRequestInvalidError({
+      detail: `agent compact is ${String(option)}, which is not 'auto', 'off' or a rule`,
+      fix: "compact: 'auto'   # on the agent — or 'off', or { at: 0.8, keepTurns: 4 }",
+    });
+  }
+  const at = rule.at ?? DEFAULT_COMPACT_AT;
+  // `estimate > NaN * room` is false on every turn: compaction silently never runs.
+  if (!Number.isFinite(at) || at <= 0 || at > 1) {
+    throw new AiRequestInvalidError({
+      detail: `agent compact.at is ${at}; it is a fraction of the context window, above 0 and at most 1`,
+      fix: 'compact: { at: 0.8 }   # on the agent — compact once the next request is 80% of the room',
+    });
+  }
+  const keepTurns = finiteCount(
+    SUBJECT,
+    'compact.keepTurns',
+    rule.keepTurns ?? DEFAULT_KEEP_TURNS,
+    1,
+  );
+  const maxSummaryTokens = finiteCount(
+    SUBJECT,
+    'compact.maxSummaryTokens',
+    rule.maxSummaryTokens ?? Math.min(DEFAULT_MAX_SUMMARY_TOKENS, maxTokens),
+    1,
+  );
+  return { at, keepTurns, model: rule.model, maxSummaryTokens };
+}

package/src/agent-compact.ts

@@ -0,0 +1,264 @@
+// Single responsibility: auto-compaction for ONE `agent()` run — the trigger before each turn, the
+// cut between turns, the one summary call, and the transcript rebuilt around it.
+//
+// Shaped by the provider prompt cache (./prompt-cache): a cache is a prefix match, so everything
+// before the messages — the tools, the system prompt and its stable block — is sent byte for byte
+// as it was, and the summary call is the run's OWN request up to the cut plus one instruction, so
+// it reads the prefix an earlier turn wrote instead of paying for it again. Only the messages
+// 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.
+
+import type { Ctx, Span } from '@ultimat3/core';
+import { stringField, throwIfAborted } from '@ultimat3/core';
+import type { AgentCompaction, CompactPlan } from './agent-compact-def';
+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 { 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.`;
+
+/** The run's own stops: thrown as themselves from the summary call, never read as its failure. */
+const RUN_STOPS: ReadonlySet<string> = new Set([
+  'X_AI_BUDGET_EXCEEDED',
+  'X_AGENT_DEADLINE',
+  'X_ABORTED',
+]);
+
+export interface CompactorInput {
+  readonly agent: string;
+  readonly plan: CompactPlan;
+  /** The run's request with no messages: its model, system, tools and cache hint. */
+  readonly base: GenerateRequest;
+  readonly model: ModelId;
+  /** Compactions the handle being continued already holds. */
+  readonly prior: number;
+  readonly gateway: Gateway;
+  readonly deadline: RunDeadline;
+  readonly ctx: Ctx;
+  readonly span: Span;
+  readonly onCompact: ((event: AgentCompaction) => void | Promise<void>) | undefined;
+  /** `costPerRun` for the summary call, as for a turn: throws `X_AI_BUDGET_EXCEEDED` pre-flight. */
+  readonly assertCost: (request: GenerateRequest) => void;
+}
+
+export interface Compactor {
+  /** The messages the next turn sends: as given, compacted, or refused. */
+  fit(messages: readonly AiMessage[], turn: number): Promise<readonly AiMessage[]>;
+  /** Compactions so far, continuations included — what the handle's `compacted` carries. */
+  count(): number;
+}
+
+/**
+ * The prompt half of a request, as the gateway estimates it (`estimateInputTokens`), plus the tool
+ * definitions that estimate leaves out — every one of them is sent on every turn.
+ */
+export function promptTokens(request: GenerateRequest): number {
+  return estimateInputTokens(request) + estimateTextTokens(JSON.stringify(request.tools ?? []));
+}
+
+/** The input room of `model` for a completion ceiling of `maxTokens`. Never below one token. */
+export function roomOf(model: ModelId, maxTokens: number): number {
+  return Math.max(1, modelSpec(model).contextWindow - maxTokens);
+}
+
+export function compactor(input: CompactorInput): Compactor {
+  const { plan, base, model, span } = input;
+  const writer = plan.model ?? model;
+  // Before the first turn: an unregistered summary model is `X_AI_MODEL_UNKNOWN` at run start,
+  // not in the middle of the run whose transcript it was supposed to save.
+  modelSpec(writer);
+  const limit = roomOf(model, base.maxTokens);
+  let count = input.prior;
+  // The estimate a compaction is attempted above. After a FAILED attempt it rises to the room
+  // 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;
+
+  const report = async (event: AgentCompaction): Promise<void> => {
+    span.addEvent('agent.compact', {
+      'agent.compact.turn': event.turn,
+      'agent.compact.outcome': event.outcome,
+      'agent.compact.before_tokens': event.before,
+      'agent.compact.after_tokens': event.after,
+      'agent.compact.limit_tokens': event.limit,
+      'agent.compact.summarised_turns': event.summarised,
+      'agent.compact.kept_turns': event.kept,
+      ...(event.reason === undefined ? {} : { 'agent.compact.reason': event.reason }),
+      ...(event.cost === undefined ? {} : { 'llm.cost.minor': event.cost.minor }),
+    });
+    await input.onCompact?.(event);
+  };
+
+  const fit = async (
+    messages: readonly AiMessage[],
+    turn: number,
+  ): Promise<readonly AiMessage[]> => {
+    const before = promptTokens({ ...base, messages });
+    if (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;
+    const failed = async (
+      reason: string,
+      summarised: number,
+      call?: GenerateResult,
+    ): Promise<readonly AiMessage[]> => {
+      await report({
+        ...facts,
+        outcome: 'failed',
+        reason,
+        after: before,
+        summarised,
+        kept,
+        compactions: count,
+        ...(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;
+      throw new AgentContextExhaustedError({
+        agent: input.agent,
+        model,
+        estimate: before,
+        limit,
+        reason,
+      });
+    };
+
+    if (split === undefined) {
+      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);
+    }
+    throwIfAborted(input.ctx);
+    input.deadline.check();
+    input.assertCost(request);
+    let result: GenerateResult;
+    try {
+      // Its own meter, inside the run's: the bill reaches the run as a nested call's does — on the
+      // same ledger, in `tokensPerRun` and `costPerRun`, priced at the summary model's own rates.
+      result = await input.deadline.guard(runMeter().call(input.gateway.generate(request)));
+    } catch (error) {
+      throwIfAborted(input.ctx);
+      const code = stringField(error, 'code');
+      if (code !== undefined && RUN_STOPS.has(code)) throw error;
+      return failed(`the summary call failed${code === undefined ? '' : ` (${code})`}`, summarised);
+    }
+    const summary = result.text.trim();
+    if (result.stopReason === 'refusal') {
+      return failed('the summary call was refused', summarised, result);
+    }
+    if (isTruncated(result.stopReason)) {
+      return failed(
+        `the summary was cut off at maxSummaryTokens (${plan.maxSummaryTokens})`,
+        summarised,
+        result,
+      );
+    }
+    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 });
+    if (after >= before) {
+      return failed('the summary was no shorter than the turns it replaced', summarised, result);
+    }
+    if (after > limit) {
+      return failed('even compacted, the next request is over the window', summarised, result);
+    }
+    count += 1;
+    trigger = plan.at * limit;
+    await report({
+      ...facts,
+      outcome: 'compacted',
+      after,
+      summarised,
+      kept,
+      compactions: count,
+      usage: result.usage,
+      cost: result.cost,
+    });
+    return compacted;
+  };
+
+  return { fit, 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[];
+  /** The last `keepTurns` turns, verbatim. */
+  readonly kept: readonly AiMessage[];
+}
+
+/**
+ * The transcript cut BETWEEN turns, never inside one. A loop's messages are the prompt, then
+ * assistant/user pairs — each user message answering every `tool_use` of the assistant message
+ * before it — so a cut before an assistant message cannot separate a call from its result.
+ * `undefined` when no whole turn is older than the kept ones.
+ */
+function splitTurns(messages: readonly AiMessage[], keepTurns: number): Split | undefined {
+  const head = messages[0];
+  const cut = messages.length - 2 * keepTurns;
+  if (head === undefined || head.role !== 'user' || cut < 3) return undefined;
+  if (messages[cut]?.role !== 'assistant' || messages[cut - 1]?.role !== 'user') return undefined;
+  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.
+ */
+function compactedHead(head: AiMessage, turns: number, summary: string): AiMessage {
+  const prompt = blocksOf(head).filter(
+    (block) => !(block.type === 'text' && block.text.startsWith(COMPACTED_MARK)),
+  );
+  const note = `${COMPACTED_MARK} ${turns} earlier turn${turns === 1 ? '' : 's'} of this run were summarised to fit the context window. Your summary of everything after the task above:]\n\n${summary}`;
+  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;
+}

package/src/agent-continue.ts

@@ -64,6 +64,12 @@ export interface AgentTranscript {
   readonly turns: number;
   /** Usage across the run and every continuation — what `budget.tokensPerRun` counts. */
   readonly usage: TokenUsage;
+  /**
+   * Compactions applied so far, continuations included — present only once there was one, so a
+   * run that never compacted writes exactly the handle it always did. Its first message then holds
+   * the prompt and a `[compacted: …]` summary block (`./agent-compact`).
+   */
+  readonly compacted?: number;
   /** HMAC-SHA256 over the canonical JSON of every field above (`sealTranscript`). */
   readonly sig: string;
 }
@@ -220,7 +226,7 @@ function signatureOf(fields: Omit<AgentTranscript, 'sig'>): string {
 /** A handle for `state`, bound and signed. The one place a transcript is written. */
 export function sealTranscript(
   binding: TranscriptBinding,
-  state: Pick<AgentTranscript, 'messages' | 'turns' | 'usage'>,
+  state: Pick<AgentTranscript, 'messages' | 'turns' | 'usage' | 'compacted'>,
 ): AgentTranscript {
   const fields: Omit<AgentTranscript, 'sig'> = {
     v: TRANSCRIPT_VERSION,
@@ -231,6 +237,7 @@ export function sealTranscript(
     messages: state.messages,
     turns: state.turns,
     usage: state.usage,
+    ...(state.compacted === undefined || state.compacted < 1 ? {} : { compacted: state.compacted }),
   };
   return { ...fields, sig: signatureOf(fields) };
 }
@@ -320,6 +327,13 @@ export function screenTranscript(binding: TranscriptBinding, raw: unknown): Agen
     refuse('its turn count is not a whole number');
   }
   const usage = usageOf(handle['usage']) ?? refuse('its usage is not four token counts');
+  const compacted = handle['compacted'];
+  if (
+    compacted !== undefined &&
+    (typeof compacted !== 'number' || !Number.isInteger(compacted) || compacted < 1)
+  ) {
+    refuse('its compaction count is not a whole number above zero');
+  }
   const messages = Array.isArray(handle['messages']) ? handle['messages'] : refuse('no messages');
   if (messages.length < 1) refuse('it holds no message');
   const declared = new Set(binding.tools);
@@ -362,6 +376,7 @@ export function screenTranscript(binding: TranscriptBinding, raw: unknown): Agen
     messages: screened,
     turns: turns as number,
     usage,
+    ...(compacted === undefined ? {} : { compacted: compacted as number }),
     sig: sig as string,
   };
 }

package/src/agent-def.ts

@@ -5,6 +5,7 @@ import type { ActionMcp, ActionPolicy } from '@ultimat3/action';
 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 { AgentSystem } from './agent-system';
 import type { AgentRunUsage } from './agent-usage';
 import type { LlmBudget } from './llm';
@@ -87,6 +88,14 @@ export interface AgentDef<
    * what each wire is sent; a host that caches implicitly is sent nothing either way.
    */
   readonly promptCache?: PromptCacheOption<AgentVarsArgs<TInput>>;
+  /**
+   * Auto-compaction. Default `'auto'`: before a turn whose request the gateway estimates over
+   * `at` (0.8) of the model's `contextWindow` less `maxTokens`, ONE model call summarises the turns
+   * older than the last `keepTurns` (4) into the first user message; the system prompt, the tools
+   * and the kept turns are sent byte for byte as before. A request that still would not fit is
+   * `X_AGENT_CONTEXT_EXHAUSTED` before it is sent. `'off'` never compacts and never checks.
+   */
+  readonly compact?: AgentCompactOption;
   /**
    * What the model may call: an `action()` that is `mcp: { expose: true }` — the same predicate an
    * external MCP client is filtered by, so both are offered the same actions — or an
@@ -158,6 +167,12 @@ export interface AgentDef<
    * one turn deep by construction; this is per TURN.
    */
   onTurn?(event: AgentTurn): void | Promise<void>;
+  /**
+   * Called once per compaction ATTEMPT, before the turn it was for is sent — `outcome:
+   * 'compacted'` or `'failed'` with the reason. Same contract as `onTurn`: observation only, and a
+   * throw fails the run. Also an `agent.compact` span event.
+   */
+  onCompact?(event: AgentCompaction): void | Promise<void>;
 }
 
 /** One completed model turn, as an observer sees it. Facts only — no transcript, no actor. */

package/src/agent-errors.ts

@@ -84,3 +84,35 @@ export class AgentToolUndeclaredError extends UltimateError {
     });
   }
 }
+
+/**
+ * The next request would not fit the model's context window, and compaction could not make it
+ * fit. Refused BEFORE the request is sent: a provider answers an over-long request with a 400 (or
+ * a turn cut off at `model_context_window_exceeded`) after the whole transcript was paid for, and
+ * a transcript cut to fit is a model reasoning over a run it can no longer see.
+ */
+export class AgentContextExhaustedError extends UltimateError {
+  constructor(input: {
+    agent: string;
+    model: string;
+    /** The next request's estimated prompt tokens. */
+    estimate: number;
+    /** The model's `contextWindow` less `maxTokens`. */
+    limit: number;
+    /** Why compaction did not bring it under. */
+    reason: string;
+  }) {
+    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}`,
+      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,
+        model: input.model,
+        estimate: input.estimate,
+        limit: input.limit,
+        reason: input.reason,
+      },
+    });
+  }
+}

package/src/agent.ts

@@ -26,6 +26,10 @@ import type { Ctx } from '@ultimat3/core';
 import { throwIfAborted, withSpan } from '@ultimat3/core';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
+import type { Compactor } from './agent-compact';
+import { compactor } from './agent-compact';
+import type { CompactPlan } from './agent-compact-def';
+import { screenCompact } from './agent-compact-def';
 import type { AgentAction, TranscriptBinding } from './agent-continue';
 import {
   claimAgentSession,
@@ -65,6 +69,7 @@ import { ignoredSamplingAttribute, screenSampling } from './sampling';
 import type { LlmToolResult } from './tools';
 import { isOfferedTool, runLlmToolCall, toolLabel } from './tools';
 
+export type { AgentCompaction, AgentCompactOption, AgentCompactRule } from './agent-compact-def';
 export type {
   AgentBudget,
   AgentDef,
@@ -97,6 +102,7 @@ export function agent<
   // This declaration's identity for `.run()` / `.continue()` sessions (`claimAgentSession`).
   const owner = {};
   const sampling = screenSampling(SUBJECT, def);
+  const compact = screenCompact(def.compact, bounds.maxTokens);
   // Projected on FIRST RUN, memoised, for the reason above: `agent()` is evaluated at module
   // scope and a tool's name is stamped by `registerAction` at boot, so naming it here would make
   // the ordinary `export const publishPost = action(...)` beside it `X_ACTION_UNREGISTERED`.
@@ -115,7 +121,7 @@ export function agent<
         def,
         respond,
         await resolvePerRun(def, { ...declared, adapted: adapt() }, args),
-        { sampling, owner },
+        { sampling, owner, compact },
         args,
       ),
   });
@@ -149,7 +155,11 @@ async function run<
   respond: Respond,
   /** This run's picks — model, offered tools, ceilings — resolved from the declaration. */
   picked: PerRun,
-  fixed: { readonly sampling: Sampling; readonly owner: object },
+  fixed: {
+    readonly sampling: Sampling;
+    readonly owner: object;
+    readonly compact: CompactPlan | undefined;
+  },
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
@@ -237,6 +247,36 @@ async function run<
     // deadline, a truncated turn, the caller leaving — is thrown carrying what the run was billed.
     const meter = runMeter();
     const disclosure = { discloseErrors: def.discloseToolErrors !== false };
+    // Worst case: the run so far (continuations and nested calls included) plus this request,
+    // estimated as the gateway's own reservation will be — at the write rate only where a provider
+    // serving the model would mark it. Before every turn, and before a compaction's summary call.
+    const assertCost = (next: GenerateRequest): void => {
+      if (costPerRun === undefined) return;
+      const spent = runTotal(model, prior?.usage, meter.total(), meter.below()).costExact;
+      const marked = gateway.marksPromptCache?.(next.model ?? model) === true;
+      assertRunCost(costPerRun, spent, estimateCost(next, marked));
+    };
+    const compacting: Compactor | undefined =
+      fixed.compact === undefined
+        ? undefined
+        : compactor({
+            agent: name,
+            plan: fixed.compact,
+            base,
+            model,
+            prior: prior?.compacted ?? 0,
+            gateway,
+            deadline,
+            ctx: args.ctx,
+            span,
+            onCompact: def.onCompact?.bind(def),
+            assertCost,
+          });
+    // What the handle's `compacted` carries: a run with `compact: 'off'` keeps what it was handed.
+    const compacted = (): { compacted?: number } => {
+      const count = compacting?.count() ?? prior?.compacted ?? 0;
+      return count > 0 ? { compacted: count } : {};
+    };
     // Where a failure would resume from: the request in flight, and the turns answered so far.
     const at = { messages: [] as readonly AiMessage[], turns: prior?.turns ?? 0 };
     const loop = async (): Promise<InferOutput<TOutput>> => {
@@ -259,15 +299,12 @@ async function run<
         // budget, runs every remaining tool's side effects, and discards the answer.
         throwIfAborted(args.ctx);
         deadline.check();
+        // Before the request exists, never after a 400: a turn the window cannot take is
+        // compacted first, or refused (`X_AGENT_CONTEXT_EXHAUSTED`) without being sent.
+        if (compacting !== undefined) messages = await compacting.fit(messages, turn);
+        at.messages = messages;
         const request: GenerateRequest = { ...base, messages };
-        if (costPerRun !== undefined) {
-          // Worst case: the run so far (continuations and nested calls included) plus this turn,
-          // estimated as the gateway's own reservation will be — at the write rate only where a
-          // provider serving the model would mark the request.
-          const spent = runTotal(model, prior?.usage, meter.total(), meter.below()).costExact;
-          const marked = gateway.marksPromptCache?.(model) === true;
-          assertRunCost(costPerRun, spent, estimateCost(request, marked));
-        }
+        assertCost(request);
         const result = await deadline
           .guard(meter.call(gateway.generate(request)))
           .catch((error: unknown) => {
@@ -360,6 +397,7 @@ async function run<
                 messages: [...messages, assistantTurn(result)],
                 turns: turn,
                 usage: usage.usage,
+                ...compacted(),
               }),
               turns: turn,
               usage,
@@ -398,7 +436,7 @@ async function run<
           // — six truncated continuations billed six times against a ceiling that saw none of them.
           if (session !== undefined && at.messages.length > 0) {
             const { usage } = runTotal(model, prior?.usage, meter.billed());
-            withTranscript(failed, sealTranscript(binding, { ...at, usage }));
+            withTranscript(failed, sealTranscript(binding, { ...at, usage, ...compacted() }));
           }
           throw failed;
         })

package/src/errors-retry.ts

@@ -55,6 +55,9 @@ export const AI_ERROR_RETRY = {
   // A run whose `offerTools()` named an undeclared tool names it again on the next attempt: the
   // fix is the declaration or the app's own rule, never a retry.
   X_AGENT_TOOL_UNDECLARED: 'terminal',
+  // A run whose transcript outgrew the window outgrows it again: the attempt starts from the same
+  // input, takes the same turns and reaches the same size. The fix is `compact` or the model.
+  X_AGENT_CONTEXT_EXHAUSTED: 'terminal',
 } as const satisfies Readonly<Partial<Record<AiErrorCode, ErrorRetry>>>;
 
 // `Partial`, so the table may be a subset — but every key is still checked against the declared set,

package/src/errors.ts

@@ -36,6 +36,7 @@ export const AI_ERROR_CODES = [
   'X_AGENT_TRANSCRIPT_INVALID',
   'X_AI_PROVIDER_UNEXPECTED',
   'X_AGENT_TOOL_UNDECLARED',
+  'X_AGENT_CONTEXT_EXHAUSTED',
 ] as const;
 
 export type AiErrorCode = (typeof AI_ERROR_CODES)[number];
@@ -75,6 +76,7 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_AI_PROVIDER_UNEXPECTED:
     'a provider ended a turn with an unknown reason and an incomplete answer',
   X_AGENT_TOOL_UNDECLARED: 'an agent run offered a tool its declaration does not list',
+  X_AGENT_CONTEXT_EXHAUSTED: "an agent's next request would not fit its model's context window",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Unconditional and

package/src/index.ts

@@ -5,6 +5,7 @@
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 export { agent } from './agent';
+export type { AgentCompaction, AgentCompactOption, AgentCompactRule } from './agent-compact-def';
 export type {
   AgentAction,
   AgentContinuation,
@@ -26,6 +27,7 @@ export type {
   AgentVarsArgs,
 } from './agent-def';
 export {
+  AgentContextExhaustedError,
   AgentDeadlineError,
   AgentToolLoopError,
   AgentToolUndeclaredError,