@aragon-agent/core 0.2.13 → 0.2.15

package/CHANGELOG.md

@@ -9,6 +9,67 @@ were written.
 
 ### Added
 
+- **Tail relief — the last rung of the compaction ladder.** `relieveTail` joins
+  the root barrel with `TailReliefOptions` and `TailReliefResult` (85 → 86
+  runtime exports), and `compaction_end` gains an optional `tailRelief` field.
+
+  Every existing rung operates on the HEAD of a history. When the RETAINED tail
+  is what does not fit — a few turns carrying several 100 KB tool results — each
+  of them reports success or "nothing to drop" while the conversation stays
+  un-sendable. `relieveTail` clips oversized `tool_result` bodies in place,
+  oldest first, and stops as soon as the projection is under budget.
+
+  It is **structure-preserving by construction**: no message is removed, no
+  `toolCallId` is touched, no role changes, so a history that passed
+  `validateHistory` before still passes after. That is what makes it safe to run
+  on an already-spliced history, and it is why relief clips rather than drops.
+  Every clip is announced in the text the model reads, at the exact place the
+  data was removed, through a `marker` callback the host supplies — this package
+  owns no glyphs.
+
+  `compaction_end.tailRelief` is optional, so a subscriber that does not know
+  about it is unaffected.
+
+- **Context compaction — one injected port, and the engine refuses a bad
+  splice.** `AgentConfig.contextManager?: ContextManager` is called at every turn
+  boundary (after the steering drain, before `turn_start`). When it says so, the
+  engine hands it a **copy** of the history, adopts whatever comes back — and
+  validates it first.
+
+  `findSafeCutIndices`, `planCompaction` and `validateHistory` join the root
+  barrel, along with `CHARS_PER_TOKEN`, which was module-private (81 → 85 runtime
+  exports). Two new `AgentEvent` members, `compaction_start` and
+  `compaction_end`, carry the story; a consumer with a `default` branch is
+  unaffected.
+
+  **The mechanism is here; the policy is the host's.** This package holds a
+  `ModelRef` and never a `ModelInfo`, so the threshold, the summarizer, the
+  prompt and the failure ladder are all decisions on the other side of the port.
+
+  Four properties are load-bearing and each is asserted by a test:
+
+  - **Off is free.** With no `contextManager` the checkpoint is one `if` against
+    an absent field — no promise allocation, no events, no behaviour change.
+  - **The engine validates and may refuse.** An orphan `tool_result`, an unclosed
+    `tool_call`, an empty array or a history that grew is not adopted; the run
+    continues on the original and `compaction_end` reports
+    `invalid_history: <reason>`. An orphan `tool_result` is an unrecoverable 400
+    on Anthropic, so a host bug must not be able to produce one.
+  - **The call cannot hang the run.** `compaction_start` pauses the idle
+    watchdog, so the engine races `compact()` against the run's signal **and** a
+    120 s ceiling of its own, and emits `compaction_end` from a `finally` — which
+    is what resumes the watchdog. A non-settling promise, an ignored signal or a
+    malformed return value each degrade to "compaction did not happen".
+  - **The host gets a copy.** `ctx.messages` is a shallow copy, so a host that
+    splices it in place cannot corrupt engine state before the gate sees it.
+
+  **`compaction` is now a legitimate word in the engine**, which makes RT-4's
+  original claim ("no history-trimming API exists") false by design. That guard
+  now asserts the narrower and more useful thing: history shrinks in exactly one
+  place, and that place goes through `validateHistory`. The skill digest's
+  `force=true` escape hatch — added for a *truncated* earlier copy — covers a
+  *compacted-away* one unchanged, and is pinned by a test.
+
 - **`llm/retry.ts` — retry with exponential backoff, ON BY DEFAULT.**
   `RETRY_LIMITS`, `DEFAULT_RETRY_POLICY`, `isRetryableError`,
   `computeBackoffDelay`, `parseRetryAfterMs` and `withRetry` are exported from the

package/dist/engine/agent-loop.d.ts

@@ -12,6 +12,7 @@ import type { ToolRegistry } from '../tools/registry.js';
 import type { AgentEvent } from '../types.js';
 import type { MessageManager } from './message-manager.js';
 import type { MessageQueueManager } from './steering.js';
+import type { ContextManager } from './context-manager.js';
 import type { CodeActSandbox } from '../sandbox/types.js';
 export type { CodeActSandbox };
 export type { ExecuteResult as CodeActResult } from '../sandbox/types.js';
@@ -35,12 +36,46 @@ export interface AgentLoopContext {
     /** Maximum output tokens per LLM call. `undefined` = use provider default. */
     maxTokens?: number;
     signal: AbortSignal;
+    /**
+     * Optional context-compaction port (context-auto-compaction §3.2).
+     *
+     * `undefined` MEANS THE ENGINE NEVER COMPACTS, and every code path is
+     * byte-identical to a pre-feature build: the checkpoint below is one `if`
+     * against a field that is genuinely absent, not a live object whose predicate
+     * says no (AC-1).
+     */
+    contextManager?: ContextManager;
     timeouts: {
         llmCallTimeout: number;
         toolTimeout: number;
         codeTimeout: number;
+        /**
+         * The engine's ceiling on ONE `compact()` call. Defaults to
+         * `COMPACTION_HARD_TIMEOUT_MS`.
+         *
+         * OVERRIDABLE ONLY SO AC-10a IS TESTABLE IN UNDER TWO MINUTES. It is NOT a
+         * host policy knob: the whole point of the ceiling is that it does not depend
+         * on the host being correct, so raising it in production re-opens exactly the
+         * hang it exists to bound (P1-3 / R-13).
+         */
+        compactionHardTimeout?: number;
     };
 }
+/**
+ * A CEILING, NOT A POLICY (P1-3). It must sit STRICTLY ABOVE the largest wall
+ * clock a well-behaved host can legitimately spend, or it starts firing on
+ * correct hosts and the failure ladder's rungs stop being reachable. The CLI's
+ * worst legal case is two `callTimeoutMs` calls back to back (45 s + 45 s = 90 s)
+ * plus the digest render, so 90 s would be exactly the boundary — this is 120 s,
+ * leaving 30 s of slack.
+ *
+ * It is deliberately longer than `DEFAULT_IDLE_TIMEOUT` (60 s): `compaction_start`
+ * PAUSES the watchdog, so across this call this is the only clock running. An
+ * `await` with no ceiling here would be strictly worse than the pre-feature
+ * behaviour — a host that returns a non-settling promise would hang the run AND
+ * there would be nothing left to notice.
+ */
+export declare const COMPACTION_HARD_TIMEOUT_MS = 120000;
 /**
  * Run the Agent loop until completion, steering exhaustion, or abort.
  *

package/dist/engine/agent-loop.js

@@ -5,6 +5,205 @@
  * cycle, with steering/follow-up checkpoints and optional CodeAct code
  * block detection and execution.
  */
+import { validateHistory } from './compaction.js';
+import { estimatePromptTokens } from '../llm/output-limits.js';
+// ---------------------------------------------------------------------------
+// Compaction checkpoint (context-auto-compaction §3.3)
+// ---------------------------------------------------------------------------
+/**
+ * A CEILING, NOT A POLICY (P1-3). It must sit STRICTLY ABOVE the largest wall
+ * clock a well-behaved host can legitimately spend, or it starts firing on
+ * correct hosts and the failure ladder's rungs stop being reachable. The CLI's
+ * worst legal case is two `callTimeoutMs` calls back to back (45 s + 45 s = 90 s)
+ * plus the digest render, so 90 s would be exactly the boundary — this is 120 s,
+ * leaving 30 s of slack.
+ *
+ * It is deliberately longer than `DEFAULT_IDLE_TIMEOUT` (60 s): `compaction_start`
+ * PAUSES the watchdog, so across this call this is the only clock running. An
+ * `await` with no ceiling here would be strictly worse than the pre-feature
+ * behaviour — a host that returns a non-settling promise would hang the run AND
+ * there would be nothing left to notice.
+ */
+export const COMPACTION_HARD_TIMEOUT_MS = 120_000;
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Coerce whatever the host resolved with into a `CompactionOutcome`.
+ *
+ * THE TYPE IS NOT THE GUARANTEE (implementation finding IF-2). `ContextManager`
+ * is an interface a host implements in its own package, so at this boundary the
+ * value is untyped at runtime: a stub, a mock, a host that forgot a `return`, or
+ * a `Promise<void>` all arrive here as `undefined`. Reading `.action` off that
+ * throws OUTSIDE the inner `catch` — after `compaction_end` has been emitted from
+ * the `finally`, so the watchdog is correctly resumed, but the throw still
+ * escapes `runCompaction` and kills the run.
+ *
+ * That is exactly the failure §3.3 step 4 says must not happen: "a host that
+ * breaks its own contract must degrade to 'compaction did not happen', never to
+ * 'the run died'". The inner `catch` covers a REJECTED promise; this covers a
+ * promise that resolves with the wrong thing, which is the commoner mistake.
+ */
+function normalizeOutcome(value) {
+    const outcome = value;
+    if (!outcome || typeof outcome !== 'object') {
+        return { action: 'keep', reason: 'manager_bad_outcome' };
+    }
+    if (outcome.action === 'replace') {
+        if (!Array.isArray(outcome.messages)) {
+            return { action: 'keep', reason: 'manager_bad_outcome' };
+        }
+        return outcome;
+    }
+    if (outcome.action === 'keep')
+        return outcome;
+    return { action: 'keep', reason: 'manager_bad_outcome' };
+}
+/**
+ * Race the host's promise against the run's signal and a hard ceiling.
+ *
+ * RESOLVES rather than rejects on both loss conditions, so the two ladder rungs
+ * stay distinguishable in the event and in the log. The losing promise is left
+ * to settle on its own; its result is dropped, and it cannot reach `restore`
+ * because `applied` is decided by the caller.
+ */
+async function raceCompaction(work, signal, timeoutMs) {
+    if (signal.aborted)
+        return { action: 'keep', reason: 'aborted' };
+    let timer;
+    let onAbort;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve({ action: 'keep', reason: 'manager_timeout' }), timeoutMs);
+            }),
+            new Promise((resolve) => {
+                onAbort = () => resolve({ action: 'keep', reason: 'aborted' });
+                signal.addEventListener('abort', onAbort, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onAbort)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
+/**
+ * One compaction checkpoint. Returns whether a new history was ADOPTED.
+ *
+ * Five steps, and step 5 is the whole reason the engine is involved at all
+ * (D-4): the host proposes, the engine validates, and an invalid history is
+ * refused rather than adopted.
+ */
+async function runCompaction(ctx, params) {
+    const cm = ctx.contextManager;
+    if (!cm)
+        return false; // 1. off: zero cost, zero allocation
+    const probe = {
+        messageCount: ctx.messageManager.length,
+        trigger: params.trigger,
+        turnIndex: params.turnIndex,
+        ...(params.lastUsage ? { lastUsage: params.lastUsage } : {}),
+    };
+    let wanted = false;
+    try {
+        wanted = cm.shouldCompact(probe); // 2. sync gate
+    }
+    catch (err) {
+        // A throwing predicate is a host bug, and it must not take the run down.
+        ctx.emit({ type: 'compaction_start', trigger: params.trigger, messageCount: probe.messageCount });
+        ctx.emit({
+            type: 'compaction_end',
+            applied: false,
+            mode: 'none',
+            reason: `manager_threw: ${errText(err)}`,
+            messagesBefore: probe.messageCount,
+            messagesAfter: probe.messageCount,
+            droppedMessages: 0,
+            estimatedTokensBefore: 0,
+            estimatedTokensAfter: 0,
+            durationMs: 0,
+        });
+        return false;
+    }
+    if (!wanted)
+        return false;
+    // A SHALLOW COPY, NOT THE LIVE ARRAY (P1-2). `getAll()` hands back the internal
+    // array; `as Message[]` would launder away the only thing stopping a host from
+    // mutating engine state in place, before step 5 can see it.
+    const before = [...ctx.messageManager.getAll()];
+    const estimatedTokensBefore = estimatePromptTokens(before, ctx.systemPrompt);
+    // 3. Pauses the watchdog (`Agent.applyWatchdogPolicy`), applied BEFORE the
+    //    listeners so a subscriber that throws cannot leave the run armed.
+    ctx.emit({ type: 'compaction_start', trigger: params.trigger, messageCount: before.length });
+    const started = Date.now();
+    let applied = false;
+    let mode = 'none';
+    let reason;
+    let summary;
+    let after = before;
+    try {
+        let outcome;
+        try {
+            // 4. BOUNDED AND RACED, because step 3 just switched the idle detector off.
+            //    NORMALIZED, because the interface is not enforced at this boundary.
+            outcome = normalizeOutcome(await raceCompaction(cm.compact({
+                ...probe,
+                messages: before,
+                systemPrompt: ctx.systemPrompt,
+                model: ctx.model,
+                signal: ctx.signal,
+            }), ctx.signal, params.hardTimeoutMs ?? ctx.timeouts.compactionHardTimeout ?? COMPACTION_HARD_TIMEOUT_MS));
+        }
+        catch (err) {
+            outcome = { action: 'keep', reason: `manager_threw: ${errText(err)}` };
+        }
+        if (outcome.action === 'keep') {
+            reason = outcome.reason;
+        }
+        else {
+            // 5. THE STRUCTURAL GATE. Positional `previousLength` keeps the `grew`
+            //    rung live.
+            const check = validateHistory(outcome.messages, { previousLength: before.length });
+            if (check.ok) {
+                ctx.messageManager.restore(outcome.messages);
+                after = outcome.messages;
+                applied = true;
+                mode = outcome.mode;
+                summary = outcome.summary;
+                reason = outcome.reason;
+            }
+            else {
+                reason = `invalid_history: ${check.reason}`;
+            }
+        }
+    }
+    finally {
+        // IN A `finally`. `compaction_end` is what RESUMES the watchdog, so it must
+        // be emitted on every exit from this function — including a `throw` that
+        // escapes the two guards above. A compaction that failed to emit its `end`
+        // leaves the run permanently deaf.
+        ctx.emit({
+            type: 'compaction_end',
+            applied,
+            mode,
+            ...(reason !== undefined ? { reason } : {}),
+            messagesBefore: before.length,
+            messagesAfter: after.length,
+            droppedMessages: Math.max(0, before.length - after.length),
+            estimatedTokensBefore,
+            estimatedTokensAfter: applied
+                ? estimatePromptTokens(after, ctx.systemPrompt)
+                : estimatedTokensBefore,
+            ...(summary !== undefined ? { summary } : {}),
+            durationMs: Date.now() - started,
+        });
+    }
+    return applied;
+}
 // ---------------------------------------------------------------------------
 // CodeAct regex for extracting ```execute-js blocks
 // ---------------------------------------------------------------------------
@@ -52,6 +251,16 @@ function getToolCalls(message) {
  * for emitting `agent_end` in its own finally block.
  */
 export async function runAgentLoop(ctx) {
+    // ----- Compaction bookkeeping (context-auto-compaction §3.3) --------------
+    //
+    // ALL THREE ARE HOISTED ABOVE THE `while`, and only two of them are ever reset
+    // inside it — after a stream COMPLETES, never at the top of the loop.
+    /** Authoritative usage of the most recently completed turn (P1-1). */
+    let lastUsage;
+    /** 1-based, ONE PER ITERATION — guard 1's cooldown unit (P2-1). */
+    let turnIndex = 0;
+    /** NOT RESET AT THE TOP OF THE LOOP (P0-1). See the note at `turn_end`. */
+    let overflowRecovered = false;
     while (!ctx.signal.aborted) {
         // ----- Steering checkpoint (before LLM call) -----
         if (ctx.messageQueueManager.hasSteering()) {
@@ -62,6 +271,21 @@ export async function runAgentLoop(ctx) {
             }
             // Continue to LLM call with injected steering messages.
         }
+        turnIndex += 1;
+        // ----- Context pressure checkpoint (context-auto-compaction §3.3) -----
+        //
+        // PLACEMENT IS LOAD-BEARING IN THREE WAYS.
+        //   1. AFTER the steering drain, so a message the user just steered in is
+        //      part of the history being measured and is inside the retained tail by
+        //      construction (it is the newest message).
+        //   2. BEFORE `turn_start`, so the UI reads compaction as a phase of its own
+        //      rather than as a stall inside a turn.
+        //   3. INSIDE the `while`, not before it. A run that starts under the
+        //      threshold and crosses it at turn 12 is the normal case, and it is the
+        //      case an `agent_end`-based design cannot serve at all (D-1).
+        await runCompaction(ctx, { trigger: 'pressure', lastUsage, turnIndex });
+        if (ctx.signal.aborted)
+            break;
         // ----- Turn start -----
         ctx.emit({ type: 'turn_start' });
         // ----- Build LLM request -----
@@ -86,18 +310,43 @@ export async function runAgentLoop(ctx) {
             thinkingLevel: ctx.thinkingLevel,
             maxTokens: ctx.maxTokens,
         });
-        for await (const event of stream) {
+        try {
+            for await (const event of stream) {
+                if (ctx.signal.aborted)
+                    break;
+                // Forward every stream event to subscribers.
+                ctx.emit({ type: 'message_update', streamEvent: event });
+                if (event.type === 'done') {
+                    assistantMessage = event.message;
+                    usage = event.usage;
+                }
+                else if (event.type === 'error') {
+                    throw event.error;
+                }
+            }
+        }
+        catch (err) {
+            // ----- Reactive compaction (context-auto-compaction §3.5) -----
+            //
+            // The static context window is a GUESS for anything the table has not seen
+            // (`buildRuntimeModel` returns 128 000 for every unknown model), so a proxy
+            // in front of a 32 k model refuses the request before the proactive trigger
+            // could ever fire. One recovery turns that from a dead run into a re-send.
+            //
+            // STRUCTURAL CHECK, NOT `instanceof LLMError`: the error may have crossed a
+            // module boundary or been rebuilt, and an identity check on the class is the
+            // version of this test that fails in production and passes in the unit test
+            // (`retry.ts::isRetryableError` records the same reasoning).
+            const errorType = err?.errorType;
+            if (errorType !== 'context_overflow' || overflowRecovered || !ctx.contextManager)
+                throw err;
+            overflowRecovered = true;
+            const recovered = await runCompaction(ctx, { trigger: 'overflow', lastUsage, turnIndex });
+            if (!recovered)
+                throw err;
             if (ctx.signal.aborted)
                 break;
-            // Forward every stream event to subscribers.
-            ctx.emit({ type: 'message_update', streamEvent: event });
-            if (event.type === 'done') {
-                assistantMessage = event.message;
-                usage = event.usage;
-            }
-            else if (event.type === 'error') {
-                throw event.error;
-            }
+            continue; // re-send this turn against the compacted history
         }
         if (ctx.signal.aborted)
             break;
@@ -107,6 +356,24 @@ export async function runAgentLoop(ctx) {
         }
         // ----- Turn end -----
         ctx.emit({ type: 'turn_end', message: assistantMessage, usage });
+        // THE TWO LINES THE COMPACTION PROBE DEPENDS ON, and both are cleared HERE
+        // rather than at the top of the loop.
+        //
+        // Without the first, `lastUsage` is forever `undefined`, every trigger runs
+        // on the crude estimate, and the status bar and the trigger diverge — the
+        // exact defect the shared `occupiedTokens` exists to close, reintroduced
+        // silently (P1-1).
+        //
+        // Without the second — or with it moved to the top of the `while` — the
+        // one-shot overflow guard would not exist at all: §3.5's recovery ends in
+        // `continue`, which re-enters the loop, so a top-of-loop reset would clear
+        // the flag on the way back in and a session whose tail alone cannot fit
+        // would compact on every pass (P0-1). Clearing it after a stream COMPLETES
+        // is the correct expression of the intent: the flag means "this turn has
+        // already spent its one overflow recovery", and a turn that never produced a
+        // `done` event has not finished.
+        lastUsage = usage;
+        overflowRecovered = false;
         ctx.messageManager.push(assistantMessage);
         // ----- Process tool calls -----
         const toolCalls = getToolCalls(assistantMessage);

package/dist/engine/agent.d.ts

@@ -10,6 +10,7 @@ import type { ProviderRegistry } from '../llm/providers/index.js';
 import type { AgentTool } from '../tools/types.js';
 import type { AgentEventListener } from '../types.js';
 import type { CodeActSandbox, ModelRef } from './agent-loop.js';
+import type { ContextManager } from './context-manager.js';
 export interface AgentConfig {
     /** The initial system prompt. */
     systemPrompt: string;
@@ -27,6 +28,16 @@ export interface AgentConfig {
     sandbox?: CodeActSandbox;
     /** Maximum output tokens per LLM call. `undefined` = use provider default. */
     maxTokens?: number;
+    /**
+     * Optional context manager (context-auto-compaction §4.1).
+     *
+     * `undefined` means the engine NEVER compacts and every code path is
+     * byte-identical to a pre-feature build. THERE IS NO SETTER, deliberately: a
+     * host implementation reads its own config live through closures (the idiom
+     * `FastWiring` already uses), so the object handed in here can stay stable for
+     * the `Agent`'s whole lifetime while the policy behind it changes mid-session.
+     */
+    contextManager?: ContextManager;
     /** Timeout configuration. */
     timeouts?: {
         /** Single LLM call timeout (ms). Default: 300_000 (5 min). */
@@ -37,6 +48,15 @@ export interface AgentConfig {
         toolTimeout?: number;
         /** Code execution timeout (ms). Default: 30_000 (30 s). */
         codeTimeout?: number;
+        /**
+         * Ceiling on ONE `ContextManager.compact()` call (ms). Default: 120_000.
+         *
+         * EXPOSED ONLY SO AC-10a IS TESTABLE IN UNDER TWO MINUTES. It is not a host
+         * policy knob — the whole point of the ceiling is that it does not depend on
+         * the host being correct, and `compaction_start` pauses the idle watchdog, so
+         * across the call this is the only clock running (P1-3 / R-13).
+         */
+        compactionHardTimeout?: number;
         /**
          * Per-tool ceilings keyed by tool name, overriding `toolTimeout`.
          *
@@ -73,11 +93,13 @@ export declare class Agent {
     private readonly providerRegistry;
     private readonly getApiKeyFn;
     private readonly sandbox?;
+    private readonly contextManager?;
     private maxTokens;
     private readonly llmCallTimeout;
     private readonly idleTimeout;
     private readonly toolTimeout;
     private readonly codeTimeout;
+    private readonly compactionHardTimeout;
     private abortController;
     private running;
     private idlePromiseResolvers;
@@ -132,8 +154,23 @@ export declare class Agent {
      */
     private emit;
     /**
-     * Suspend the idle watchdog across a retry backoff, and resume it when the
-     * next attempt goes out (llm-api-retry-backoff §4.6).
+     * Suspend the idle watchdog across a wait the ENGINE ITSELF scheduled, and
+     * resume it when work moves again.
+     *
+     * TWO PAIRS, ONE POLICY (context-auto-compaction §3.3). Retry backoff was the
+     * first (llm-api-retry-backoff §4.6); context compaction is the second, and it
+     * is the reason this method lost the `Retry` in its name. Both are cases where
+     * the run is provably waiting on purpose and the watchdog cannot tell that
+     * apart from a wedged network call.
+     *
+     * `compaction_end` IS EMITTED FROM A `finally` IN `runCompaction`, on every
+     * exit path including a throw, precisely so this `resume()` is unconditional.
+     * A compaction whose `end` never arrived would leave the watchdog paused for
+     * the rest of the run, with nothing anywhere reporting it (P1-3 / R-13).
+     *
+     * Both halves are idempotent, and `runLoopWithLifecycle`'s `finally` calls
+     * `watchdog.stop()`, which clears `paused` — that is what bounds an abort
+     * landing mid-wait.
      *
      * `withRetry` waits up to `maxDelayMs` between attempts and emits nothing while
      * it does. That is indistinguishable from a wedged network call to the
@@ -147,7 +184,7 @@ export declare class Agent {
      * clears `paused` for exactly this reason. DO NOT "simplify" that line out of
      * `stop()`.
      */
-    private applyRetryWatchdogPolicy;
+    private applyWatchdogPolicy;
     /**
      * Synchronize the ToolRegistry with the provided tool array.
      * Removes tools no longer present and adds new ones.

package/dist/engine/agent.js

@@ -37,6 +37,7 @@ export class Agent {
     providerRegistry;
     getApiKeyFn;
     sandbox;
+    contextManager;
     // --- LLM generation parameters ---
     maxTokens;
     // --- Timeouts ---
@@ -44,6 +45,7 @@ export class Agent {
     idleTimeout;
     toolTimeout;
     codeTimeout;
+    compactionHardTimeout;
     // --- Runtime state ---
     abortController = null;
     running = false;
@@ -56,12 +58,14 @@ export class Agent {
         this.providerRegistry = config.providerRegistry;
         this.getApiKeyFn = config.getApiKey;
         this.sandbox = config.sandbox;
+        this.contextManager = config.contextManager;
         this.maxTokens = config.maxTokens;
         // Timeouts
         this.llmCallTimeout = config.timeouts?.llmCallTimeout ?? DEFAULT_LLM_CALL_TIMEOUT;
         this.idleTimeout = config.timeouts?.idleTimeout ?? DEFAULT_IDLE_TIMEOUT;
         this.toolTimeout = config.timeouts?.toolTimeout ?? DEFAULT_TOOL_TIMEOUT;
         this.codeTimeout = config.timeouts?.codeTimeout ?? DEFAULT_CODE_TIMEOUT;
+        this.compactionHardTimeout = config.timeouts?.compactionHardTimeout;
         // Register initial tools
         this.syncToolRegistry(config.tools);
         // Tool executor
@@ -222,7 +226,7 @@ export class Agent {
         // policy still has to have been applied — otherwise a bad subscriber leaves
         // the watchdog armed across a 30-second backoff and the run is aborted for
         // being "idle" while it is provably waiting on purpose.
-        this.applyRetryWatchdogPolicy(event);
+        this.applyWatchdogPolicy(event);
         for (const listener of this.listeners) {
             try {
                 listener(event);
@@ -234,8 +238,23 @@ export class Agent {
         this.watchdog.kick();
     }
     /**
-     * Suspend the idle watchdog across a retry backoff, and resume it when the
-     * next attempt goes out (llm-api-retry-backoff §4.6).
+     * Suspend the idle watchdog across a wait the ENGINE ITSELF scheduled, and
+     * resume it when work moves again.
+     *
+     * TWO PAIRS, ONE POLICY (context-auto-compaction §3.3). Retry backoff was the
+     * first (llm-api-retry-backoff §4.6); context compaction is the second, and it
+     * is the reason this method lost the `Retry` in its name. Both are cases where
+     * the run is provably waiting on purpose and the watchdog cannot tell that
+     * apart from a wedged network call.
+     *
+     * `compaction_end` IS EMITTED FROM A `finally` IN `runCompaction`, on every
+     * exit path including a throw, precisely so this `resume()` is unconditional.
+     * A compaction whose `end` never arrived would leave the watchdog paused for
+     * the rest of the run, with nothing anywhere reporting it (P1-3 / R-13).
+     *
+     * Both halves are idempotent, and `runLoopWithLifecycle`'s `finally` calls
+     * `watchdog.stop()`, which clears `paused` — that is what bounds an abort
+     * landing mid-wait.
      *
      * `withRetry` waits up to `maxDelayMs` between attempts and emits nothing while
      * it does. That is indistinguishable from a wedged network call to the
@@ -249,7 +268,15 @@ export class Agent {
      * clears `paused` for exactly this reason. DO NOT "simplify" that line out of
      * `stop()`.
      */
-    applyRetryWatchdogPolicy(event) {
+    applyWatchdogPolicy(event) {
+        if (event.type === 'compaction_start') {
+            this.watchdog.pause();
+            return;
+        }
+        if (event.type === 'compaction_end') {
+            this.watchdog.resume();
+            return;
+        }
         if (event.type !== 'message_update')
             return;
         const t = event.streamEvent.type;
@@ -303,11 +330,19 @@ export class Agent {
                 systemPrompt: this.systemPrompt,
                 thinkingLevel: this.thinkingLevel,
                 maxTokens: this.maxTokens,
+                // SPREAD, never `contextManager: this.contextManager`. With no manager the
+                // loop context has no such key, so `if (!ctx.contextManager)` tests a field
+                // that is genuinely absent rather than a property holding `undefined` —
+                // which is what makes the byte-identity claim in AC-1 provable.
+                ...(this.contextManager ? { contextManager: this.contextManager } : {}),
                 signal: this.abortController.signal,
                 timeouts: {
                     llmCallTimeout: this.llmCallTimeout,
                     toolTimeout: this.toolTimeout,
                     codeTimeout: this.codeTimeout,
+                    ...(this.compactionHardTimeout !== undefined
+                        ? { compactionHardTimeout: this.compactionHardTimeout }
+                        : {}),
                 },
             });
         }

package/dist/engine/compaction.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Pure compaction mechanics (context-auto-compaction §3.6.1 / §3.6.2 / §5.3).
+ *
+ * NO I/O, NO CLOCK, NO PROVIDER KNOWLEDGE, NO `node:*` IMPORT. This module is
+ * the engine's whole contribution to compaction: where a history may safely be
+ * cut, which cut to take, and — the one that matters — whether a history the
+ * host handed back is structurally sendable at all.
+ *
+ * WHY THE ENGINE OWNS VALIDATION AND NOTHING ELSE (D-4). A compacted history
+ * that strands a `tool_result` without its `tool_call` is an immediate HTTP 400
+ * on Anthropic: `convertMessages` emits one `user` message carrying a
+ * `tool_use_id` per `tool_result`, and the API rejects a `tool_use_id` with no
+ * `tool_use` before it. That failure is not recoverable by the host and must not
+ * be recoverable BY POLICY — so the engine refuses to adopt an invalid history
+ * and continues with the original. A host bug becomes "compaction did not
+ * happen" rather than "the session is now permanently un-sendable" (R-2).
+ */
+import type { Message } from '../llm/types.js';
+export interface CompactionPlan {
+    /** Head is `[0, cutIndex)`; tail is `[cutIndex, end)`. */
+    cutIndex: number;
+    droppedMessages: number;
+    retainedTurns: number;
+}
+export type HistoryCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'empty' | 'orphan_tool_result' | 'unclosed_tool_call' | 'grew';
+};
+/**
+ * Every index at which the history may be split without stranding a tool call.
+ *
+ * `i` is SAFE iff, walking from 0, the set of open tool calls is empty at the
+ * boundary before `i` AND `messages[i]` is not a `tool_result`.
+ *
+ * A SET-BASED WALK RATHER THAN A ROLE-PATTERN RULE, and that is deliberate: the
+ * history is not always the clean `user -> assistant -> tool_result*` shape the
+ * loop produces. Steering interruption pushes synthesized `tool_result`s for the
+ * REMAINING calls in a batch, CodeAct injects a bare `user` message, and
+ * `/resume` restores whatever a file contained. A rule that encodes the happy
+ * path is a rule that produces an invalid splice on the one history that got
+ * interesting.
+ */
+export declare function findSafeCutIndices(messages: readonly Message[]): number[];
+export interface PlanCompactionOptions {
+    keepRecentTurns: number;
+    /**
+     * Messages at the head that are ALREADY structurally preserved by the host
+     * (the goal anchor, and a prior `<compacted_context>` block right after it).
+     *
+     * THIS PARAMETER IS WHAT MAKES REPEATED COMPACTION TERMINATE CLEANLY (P1-9 /
+     * D-21). Without it the condition would have to be "the best cut is 0 or 1",
+     * which encodes an assumption about what messages 0 and 1 ARE — and after one
+     * compaction they are the anchor and the summary block, so a second pass would
+     * re-summarize a summary with no new material, produce a smaller and lossier
+     * record, and report success.
+     *
+     * The HOST counts it (it is the host that knows what an `<original_task>`
+     * message is) and passes the number; core stays free of any knowledge of the
+     * block format, which is the §1.2 boundary. Hard-coding `1` here, or teaching
+     * this module the tag, are both ways of putting host knowledge in the engine
+     * to save a parameter.
+     */
+    protectedPrefix?: number;
+}
+/**
+ * The largest safe cut that still leaves at least `keepRecentTurns` complete
+ * turns in the tail, or `null` when there is nothing worth dropping.
+ *
+ * `null` — rather than a zero-length head — is what lets §3.8 turn "the recent
+ * turns alone exceed the threshold" into a bounded, loud outcome instead of a
+ * retry loop against a paid API.
+ */
+export declare function planCompaction(messages: readonly Message[], opts: PlanCompactionOptions): CompactionPlan | null;
+export interface ValidateHistoryOptions {
+    /**
+     * The length of the history being REPLACED. Supplied positionally by the loop
+     * so the `grew` rung is live: a compaction that returns more messages than it
+     * was given is not a correctness failure, but it is always a bug, and adopting
+     * it would let a broken compactor amplify the very problem it exists to solve.
+     */
+    previousLength?: number;
+}
+/**
+ * THE GATE (§3.3 step 5). One walk, the same open-set as `findSafeCutIndices`.
+ *
+ * Also exported for the host's IDLE `/compact` path (§4.4 / D-25), which cannot
+ * reach the loop's gate because there is no loop — and D-4 declares that gate
+ * unbypassable.
+ */
+export declare function validateHistory(messages: readonly Message[], opts?: ValidateHistoryOptions): HistoryCheck;
+export interface TailReliefOptions {
+    /** Index the tail starts at; nothing before it is touched. */
+    from: number;
+    /** Clip each oversized `tool_result` body to this many characters. */
+    clipChars: number;
+    /** Stop as soon as the estimate falls below this. */
+    targetTokens: number;
+    /** System prompt, so the estimate is measured the same way everywhere. */
+    systemPrompt: string;
+    /** Appended where text was removed. The host supplies it; core has no glyphs. */
+    marker: (removed: number) => string;
+}
+export interface TailReliefResult {
+    messages: Message[];
+    clippedMessages: number;
+    charsRemoved: number;
+}
+/**
+ * Clip oversized `tool_result` bodies inside a retained tail until the whole
+ * history is projected under `targetTokens` — the last rung of the ladder
+ * (context-auto-compaction-hardening §3.3).
+ *
+ * WHY THIS EXISTS. Every other rung operates on the HEAD: summarize it, retry
+ * the summarization, drop it without a summary. When the TAIL is what does not
+ * fit — `keepRecentTurns` turns carrying several 100 KB tool results — each of
+ * those rungs reports success or `nothing_to_drop` while the history stays
+ * un-sendable, and the run dies with no rung left.
+ *
+ * FOUR RULES, EACH LOAD-BEARING:
+ *
+ *  1. ONLY `tool_result` BODIES ARE ELIGIBLE. Not `user` messages (the anchor
+ *     and the user's own instructions are the last things to damage), not
+ *     `assistant` messages (clipping the model's own reasoning mid-tail produces
+ *     a history that contradicts itself). The size argument is the bound: a tool
+ *     result is capped at 100 KB EACH with several per turn, while an assistant
+ *     message is capped by the turn's `maxOutputTokens`. The tail is blown by
+ *     results, not by calls.
+ *  2. OLDEST FIRST. The newest tool result is the one the next request is most
+ *     likely to be about, so the walk starts at `from` and stops the moment the
+ *     projection is under budget.
+ *  3. STRUCTURE IS NEVER CHANGED. No message is removed, no `toolCallId` is
+ *     touched, no role changes — so `validateHistory` cannot fail on a relieved
+ *     history that was valid before. That is what makes this safe to run AFTER a
+ *     splice, and it is the reason relief CLIPS rather than DROPS.
+ *  4. EVERY CLIP IS ANNOUNCED IN THE TEXT THE MODEL READS, at the exact place
+ *     the data was removed. A model that sees the marker knows the output is
+ *     partial and can re-run the tool; a model handed a silently truncated file
+ *     does not.
+ *
+ * PURE, AND IT DOES NOT MUTATE ITS INPUT. Untouched messages keep their identity
+ * in the returned array, which is what lets a caller assert "nothing before
+ * `from` changed" by reference rather than by deep equality.
+ */
+export declare function relieveTail(messages: readonly Message[], opts: TailReliefOptions): TailReliefResult;

package/dist/engine/compaction.js

@@ -0,0 +1,226 @@
+/**
+ * Pure compaction mechanics (context-auto-compaction §3.6.1 / §3.6.2 / §5.3).
+ *
+ * NO I/O, NO CLOCK, NO PROVIDER KNOWLEDGE, NO `node:*` IMPORT. This module is
+ * the engine's whole contribution to compaction: where a history may safely be
+ * cut, which cut to take, and — the one that matters — whether a history the
+ * host handed back is structurally sendable at all.
+ *
+ * WHY THE ENGINE OWNS VALIDATION AND NOTHING ELSE (D-4). A compacted history
+ * that strands a `tool_result` without its `tool_call` is an immediate HTTP 400
+ * on Anthropic: `convertMessages` emits one `user` message carrying a
+ * `tool_use_id` per `tool_result`, and the API rejects a `tool_use_id` with no
+ * `tool_use` before it. That failure is not recoverable by the host and must not
+ * be recoverable BY POLICY — so the engine refuses to adopt an invalid history
+ * and continues with the original. A host bug becomes "compaction did not
+ * happen" rather than "the session is now permanently un-sendable" (R-2).
+ */
+import { estimatePromptTokens } from '../llm/output-limits.js';
+/**
+ * Every index at which the history may be split without stranding a tool call.
+ *
+ * `i` is SAFE iff, walking from 0, the set of open tool calls is empty at the
+ * boundary before `i` AND `messages[i]` is not a `tool_result`.
+ *
+ * A SET-BASED WALK RATHER THAN A ROLE-PATTERN RULE, and that is deliberate: the
+ * history is not always the clean `user -> assistant -> tool_result*` shape the
+ * loop produces. Steering interruption pushes synthesized `tool_result`s for the
+ * REMAINING calls in a batch, CodeAct injects a bare `user` message, and
+ * `/resume` restores whatever a file contained. A rule that encodes the happy
+ * path is a rule that produces an invalid splice on the one history that got
+ * interesting.
+ */
+export function findSafeCutIndices(messages) {
+    const safe = [];
+    const open = new Set();
+    for (let i = 0; i < messages.length; i += 1) {
+        const m = messages[i];
+        if (open.size === 0 && m.role !== 'tool_result')
+            safe.push(i);
+        if (m.role === 'assistant') {
+            for (const b of m.content)
+                if (b.type === 'tool_call')
+                    open.add(b.toolCallId);
+        }
+        else if (m.role === 'tool_result') {
+            open.delete(m.toolCallId);
+        }
+    }
+    if (open.size === 0)
+        safe.push(messages.length);
+    return safe;
+}
+/** A "turn" is a `user`-role message; `tool_result` is a separate role here. */
+function countTurns(messages, from) {
+    let turns = 0;
+    for (let i = from; i < messages.length; i += 1) {
+        if (messages[i].role === 'user')
+            turns += 1;
+    }
+    return turns;
+}
+/**
+ * The largest safe cut that still leaves at least `keepRecentTurns` complete
+ * turns in the tail, or `null` when there is nothing worth dropping.
+ *
+ * `null` — rather than a zero-length head — is what lets §3.8 turn "the recent
+ * turns alone exceed the threshold" into a bounded, loud outcome instead of a
+ * retry loop against a paid API.
+ */
+export function planCompaction(messages, opts) {
+    const keep = Math.max(1, Math.floor(opts.keepRecentTurns));
+    const protectedPrefix = Math.max(0, Math.floor(opts.protectedPrefix ?? 0));
+    const safe = findSafeCutIndices(messages);
+    for (let i = safe.length - 1; i >= 0; i -= 1) {
+        const cutIndex = safe[i];
+        // The tail must still be a conversation, not an empty suffix.
+        if (cutIndex >= messages.length)
+            continue;
+        const retainedTurns = countTurns(messages, cutIndex);
+        if (retainedTurns < keep)
+            continue;
+        if (cutIndex <= protectedPrefix)
+            return null;
+        return {
+            cutIndex,
+            droppedMessages: cutIndex - protectedPrefix,
+            retainedTurns,
+        };
+    }
+    return null;
+}
+/**
+ * THE GATE (§3.3 step 5). One walk, the same open-set as `findSafeCutIndices`.
+ *
+ * Also exported for the host's IDLE `/compact` path (§4.4 / D-25), which cannot
+ * reach the loop's gate because there is no loop — and D-4 declares that gate
+ * unbypassable.
+ */
+export function validateHistory(messages, opts = {}) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return { ok: false, reason: 'empty' };
+    if (opts.previousLength !== undefined && messages.length > opts.previousLength) {
+        return { ok: false, reason: 'grew' };
+    }
+    const open = new Set();
+    for (const m of messages) {
+        if (m.role === 'assistant') {
+            for (const b of m.content)
+                if (b.type === 'tool_call')
+                    open.add(b.toolCallId);
+        }
+        else if (m.role === 'tool_result') {
+            if (!open.has(m.toolCallId))
+                return { ok: false, reason: 'orphan_tool_result' };
+            open.delete(m.toolCallId);
+        }
+    }
+    if (open.size > 0)
+        return { ok: false, reason: 'unclosed_tool_call' };
+    return { ok: true };
+}
+/**
+ * Clip oversized `tool_result` bodies inside a retained tail until the whole
+ * history is projected under `targetTokens` — the last rung of the ladder
+ * (context-auto-compaction-hardening §3.3).
+ *
+ * WHY THIS EXISTS. Every other rung operates on the HEAD: summarize it, retry
+ * the summarization, drop it without a summary. When the TAIL is what does not
+ * fit — `keepRecentTurns` turns carrying several 100 KB tool results — each of
+ * those rungs reports success or `nothing_to_drop` while the history stays
+ * un-sendable, and the run dies with no rung left.
+ *
+ * FOUR RULES, EACH LOAD-BEARING:
+ *
+ *  1. ONLY `tool_result` BODIES ARE ELIGIBLE. Not `user` messages (the anchor
+ *     and the user's own instructions are the last things to damage), not
+ *     `assistant` messages (clipping the model's own reasoning mid-tail produces
+ *     a history that contradicts itself). The size argument is the bound: a tool
+ *     result is capped at 100 KB EACH with several per turn, while an assistant
+ *     message is capped by the turn's `maxOutputTokens`. The tail is blown by
+ *     results, not by calls.
+ *  2. OLDEST FIRST. The newest tool result is the one the next request is most
+ *     likely to be about, so the walk starts at `from` and stops the moment the
+ *     projection is under budget.
+ *  3. STRUCTURE IS NEVER CHANGED. No message is removed, no `toolCallId` is
+ *     touched, no role changes — so `validateHistory` cannot fail on a relieved
+ *     history that was valid before. That is what makes this safe to run AFTER a
+ *     splice, and it is the reason relief CLIPS rather than DROPS.
+ *  4. EVERY CLIP IS ANNOUNCED IN THE TEXT THE MODEL READS, at the exact place
+ *     the data was removed. A model that sees the marker knows the output is
+ *     partial and can re-run the tool; a model handed a silently truncated file
+ *     does not.
+ *
+ * PURE, AND IT DOES NOT MUTATE ITS INPUT. Untouched messages keep their identity
+ * in the returned array, which is what lets a caller assert "nothing before
+ * `from` changed" by reference rather than by deep equality.
+ */
+export function relieveTail(messages, opts) {
+    const out = [...messages];
+    const from = Math.max(0, Math.floor(opts.from));
+    const clipChars = Math.max(0, Math.floor(opts.clipChars));
+    let clippedMessages = 0;
+    let charsRemoved = 0;
+    // RE-ESTIMATED AFTER EVERY CLIP rather than decremented, and the cost is not
+    // the reason to worry about it: the array this walks is one retained tail, not
+    // a session. `estimatePromptTokens` rounds, so a hand-rolled running total
+    // would drift from the number the caller's budget check uses — and the whole
+    // point of this function is to land under THAT number.
+    let projected = estimatePromptTokens(out, opts.systemPrompt);
+    for (let i = from; i < out.length; i += 1) {
+        if (projected <= opts.targetTokens)
+            break;
+        const message = out[i];
+        if (message.role !== 'tool_result')
+            continue;
+        const clipped = clipToolResultContent(message.content, clipChars, opts.marker);
+        if (clipped === null)
+            continue;
+        out[i] = { ...message, content: clipped.content };
+        clippedMessages += 1;
+        charsRemoved += clipped.removed;
+        projected = estimatePromptTokens(out, opts.systemPrompt);
+    }
+    return { messages: out, clippedMessages, charsRemoved };
+}
+/**
+ * One `tool_result` body, clipped — or `null` when there was nothing to remove.
+ *
+ * A PART ARRAY IS CLIPPED LONGEST-FIRST, and only its `text` parts. `image`
+ * parts are left alone: the estimator charges them a flat rate that has nothing
+ * to do with their length, so clipping one removes characters without removing
+ * tokens, and re-encoding an image is a different feature.
+ */
+function clipToolResultContent(content, clipChars, marker) {
+    if (typeof content === 'string') {
+        if (content.length <= clipChars)
+            return null;
+        const removed = content.length - clipChars;
+        return { content: content.slice(0, clipChars) + marker(removed), removed };
+    }
+    if (!Array.isArray(content))
+        return null;
+    const order = content
+        .map((part, index) => ({ index, length: part.type === 'text' ? part.text.length : -1 }))
+        .filter((entry) => entry.length > clipChars)
+        .sort((a, b) => b.length - a.length);
+    if (order.length === 0)
+        return null;
+    const parts = [...content];
+    let total = parts.reduce((sum, p) => sum + (p.type === 'text' ? p.text.length : 0), 0);
+    let removed = 0;
+    for (const entry of order) {
+        if (total <= clipChars)
+            break;
+        const part = parts[entry.index];
+        if (part.type !== 'text')
+            continue;
+        const cut = part.text.length - clipChars;
+        parts[entry.index] = { type: 'text', text: part.text.slice(0, clipChars) + marker(cut) };
+        removed += cut;
+        total -= cut;
+    }
+    if (removed === 0)
+        return null;
+    return { content: parts, removed };
+}

package/dist/engine/context-manager.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The injected context-management port (context-auto-compaction §3.2).
+ *
+ * TYPES ONLY, ZERO LOGIC, and the only imports are erased type imports from
+ * `llm/types.js` and `agent-loop.js`. The engine does not know what a context
+ * window IS — `Agent` holds a `ModelRef`, never a `ModelInfo` — and it must not
+ * learn, because `ModelRegistry` lives one layer up and
+ * `no-host-coupling.test.ts` rule 2 forbids this package from reaching for a
+ * host. So the engine gains ONE port it calls at a turn boundary, and every
+ * decision behind it — the threshold, which model summarizes, what the summary
+ * asks for, what happens on failure — is made on the host's side of it (D-2).
+ */
+import type { Message, TokenUsage } from '../llm/types.js';
+import type { ModelRef } from './agent-loop.js';
+/** Why compaction is being considered right now. */
+export type CompactionTrigger = 'pressure' | 'overflow';
+/** What the engine can cheaply tell the host at a turn boundary. */
+export interface CompactionProbe {
+    readonly messageCount: number;
+    /**
+     * Authoritative usage of the most recently COMPLETED turn, or `undefined`
+     * before the first one (a fresh run, or the first turn after `/resume`).
+     *
+     * THE HOST MUST HANDLE `undefined` (§3.4.2). It is not an edge case: the most
+     * dangerous single moment in this feature's life is the first request of a
+     * resumed 180 k-token session, where there is no usage to read and the naive
+     * answer is "0 %".
+     */
+    readonly lastUsage?: TokenUsage;
+    /** 1-based index of the turn that is about to be sent. */
+    readonly turnIndex: number;
+    readonly trigger: CompactionTrigger;
+}
+export interface CompactionContext extends CompactionProbe {
+    /**
+     * A SHALLOW COPY of the engine's history, never the live array (P1-2).
+     *
+     * `MessageManager.getAll()` returns the internal array itself (the "readonly
+     * view" in its doc comment is a TYPE, not a copy). Passing that across the
+     * port would let a host that sorts, splices or truncates it corrupt engine
+     * state in place, BEFORE the structural gate at §3.3 step 5 can look at it —
+     * which would defeat the one job the engine has in this feature. One array
+     * allocation per compaction, i.e. at most `maxPerRun` per run, buys the whole
+     * guarantee.
+     */
+    readonly messages: readonly Message[];
+    readonly systemPrompt: string;
+    readonly model: ModelRef;
+    /**
+     * The run's signal. The host MUST forward it into its own LLM call.
+     *
+     * The engine does not TRUST that it does: `runCompaction` races this promise
+     * against the signal and against a hard ceiling (§3.3), because the watchdog
+     * is paused across the call and a non-settling promise would otherwise hang
+     * the run with the idle detector switched off (P1-3).
+     */
+    readonly signal: AbortSignal;
+}
+export type CompactionOutcome = {
+    action: 'keep';
+    reason: string;
+} | {
+    action: 'replace';
+    messages: Message[];
+    mode: 'summarized' | 'truncated';
+    /** For the event; the engine does not interpret it. */
+    summary?: string;
+    reason?: string;
+};
+export interface ContextManager {
+    /**
+     * SYNCHRONOUS, CHEAP, SIDE-EFFECT FREE. Called once per turn, before the LLM
+     * request is built.
+     *
+     * IT IS SYNCHRONOUS SO THAT "OFF" AND "BELOW THRESHOLD" COST NOTHING (D-3).
+     * A single async port would put an `await` — a microtask tick and a promise
+     * allocation — on every turn of every run for a decision that is `false` more
+     * than 99 % of the time, and would make it impossible to state that a session
+     * below the threshold is byte-identical to a pre-feature build.
+     */
+    shouldCompact(probe: CompactionProbe): boolean;
+    /**
+     * Only called when `shouldCompact` returned `true`.
+     *
+     * MUST NOT THROW. The engine wraps the call defensively anyway (§3.3 step 4),
+     * because a host that breaks its own contract must degrade to "compaction did
+     * not happen", never to "the run died" — but a throwing implementation is a
+     * bug on the host side and is reported as one through `compaction_end.reason`.
+     */
+    compact(ctx: CompactionContext): Promise<CompactionOutcome>;
+}

package/dist/engine/context-manager.js

@@ -0,0 +1,13 @@
+/**
+ * The injected context-management port (context-auto-compaction §3.2).
+ *
+ * TYPES ONLY, ZERO LOGIC, and the only imports are erased type imports from
+ * `llm/types.js` and `agent-loop.js`. The engine does not know what a context
+ * window IS — `Agent` holds a `ModelRef`, never a `ModelInfo` — and it must not
+ * learn, because `ModelRegistry` lives one layer up and
+ * `no-host-coupling.test.ts` rule 2 forbids this package from reaching for a
+ * host. So the engine gains ONE port it calls at a turn boundary, and every
+ * decision behind it — the threshold, which model summarizes, what the summary
+ * asks for, what happens on failure — is made on the host's side of it (D-2).
+ */
+export {};

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { ContentPart, TextContentPart, ImageContentPart, ContentBlock, Text
 export { THINKING_BUDGET } from './llm/types.js';
 export type { LLMProvider, LLMRequest, LLMErrorType, } from './llm/provider.js';
 export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js';
-export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, } from './llm/output-limits.js';
+export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, CHARS_PER_TOKEN, } from './llm/output-limits.js';
 export type { OutputLimitInput, OutputLimitResolution, CeilingSource, } from './llm/output-limits.js';
 export { classifyOutputLimitFailure, sendWithOutputLimitRecovery, learnTokenField, getLearnedTokenField, clearLearnedTokenFields, } from './llm/output-limit-recovery.js';
 export { RETRY_LIMITS, DEFAULT_RETRY_POLICY, isRetryableError, computeBackoffDelay, parseRetryAfterMs, withRetry, } from './llm/retry.js';
@@ -41,7 +41,7 @@ export { createSkillFindTool } from './skills/skill-find-tool.js';
 export { computeToolPolicy, evaluateToolCall } from './skills/tool-policy.js';
 export { SKILL_CATALOG_MAX_BYTES, SKILL_BODY_MAX_BYTES, SKILL_RESULT_MAX_BYTES, ALWAYS_SKILLS_MAX_BYTES, SKILL_MD_MAX_BYTES, SKILL_DESC_LINE_MAX, SKILL_FILES_MAX, SKILL_FIND_MAX_BYTES, SKILL_NAME_PATTERN, } from './skills/constants.js';
 export type { SkillScope, SkillActivation, SkillFrontmatter, SkillRecord, SkillFileRef, SkillHost, SkillManifest, SkillValidationIssue, SkillCatalogOptions, SkillBodyOptions, SkillFindOptions, SkillIntegrity, SkillUsageStat, SkillUsageMap, SkillInvocationOptions, SkillPlatform, SkillPolicyView, SkillToolPolicyMode, ToolPolicyDecision, ToolPolicyInput, ToolPolicySource, ToolPolicyVerdict, } from './skills/types.js';
-export type { AgentEvent, AgentEventListener, AgentStartEvent, AgentEndEvent, TurnStartEvent, TurnEndEvent, MessageUpdateEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, CodeExecutionStartEvent, CodeExecutionEndEvent, } from './types.js';
+export type { AgentEvent, AgentEventListener, AgentStartEvent, AgentEndEvent, TurnStartEvent, TurnEndEvent, MessageUpdateEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, CodeExecutionStartEvent, CodeExecutionEndEvent, CompactionStartEvent, CompactionEndEvent, } from './types.js';
 export { Agent } from './engine/agent.js';
 export type { AgentConfig, AgentState } from './engine/agent.js';
 export type { ModelRef } from './engine/agent-loop.js';
@@ -49,5 +49,8 @@ export type { CodeActSandbox, CodeActResult } from './engine/agent-loop.js';
 export { MessageManager } from './engine/message-manager.js';
 export { MessageQueueManager } from './engine/steering.js';
 export { IdleWatchdog } from './engine/watchdog.js';
+export { findSafeCutIndices, planCompaction, relieveTail, validateHistory, } from './engine/compaction.js';
+export type { CompactionPlan, HistoryCheck, PlanCompactionOptions, TailReliefOptions, TailReliefResult, ValidateHistoryOptions, } from './engine/compaction.js';
+export type { ContextManager, CompactionProbe, CompactionContext, CompactionOutcome, CompactionTrigger, } from './engine/context-manager.js';
 export type { SandboxConfig, ExecuteOptions, ExecuteResult, ConsoleEntry, SandboxToolCall, } from './sandbox/types.js';
 export { Agent as AragonAgent } from './engine/agent.js';

package/dist/index.js

@@ -11,7 +11,11 @@ export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js'
 // Output-token limits — the authority for "how many tokens may this model
 // produce". Every adapter resolves through here; nothing else spells 64000.
 // ---------------------------------------------------------------------------
-export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, } from './llm/output-limits.js';
+export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, 
+// Promoted from module-private for the compaction digest's budget arithmetic
+// (context-auto-compaction P2-3): two chars-per-token constants that must agree
+// and nothing checking that they do is how a budget and an estimate drift.
+CHARS_PER_TOKEN, } from './llm/output-limits.js';
 export { classifyOutputLimitFailure, sendWithOutputLimitRecovery, learnTokenField, getLearnedTokenField, clearLearnedTokenFields, } from './llm/output-limit-recovery.js';
 // ---------------------------------------------------------------------------
 // Retry & exponential backoff — the authority for "a provider call failed, now
@@ -71,6 +75,19 @@ export { Agent } from './engine/agent.js';
 export { MessageManager } from './engine/message-manager.js';
 export { MessageQueueManager } from './engine/steering.js';
 export { IdleWatchdog } from './engine/watchdog.js';
+// ---------------------------------------------------------------------------
+// Context compaction (context-auto-compaction §4.1)
+//
+// THREE PURE FUNCTIONS AND FIVE TYPES. The mechanism is here; the policy — the
+// threshold, the summarizer, the prompt, the failure ladder — belongs to the
+// host, because this package has no `ModelInfo` and must not learn one (D-2).
+//
+// `validateHistory` is public for a specific reason: a host that splices while
+// the agent is IDLE cannot reach the loop's own gate, and D-4 declares that gate
+// unbypassable. Exporting it is what makes honouring D-4 on the manual path cost
+// three lines instead of a second implementation.
+// ---------------------------------------------------------------------------
+export { findSafeCutIndices, planCompaction, relieveTail, validateHistory, } from './engine/compaction.js';
 // Sandbox exports are NOT re-exported here — isolated-vm is incompatible with Electron's V8.
 // Import directly from './sandbox/*.js' when needed (lazy loading only).
 // ---------------------------------------------------------------------------

package/dist/llm/output-limits.d.ts

@@ -96,6 +96,16 @@ export interface OutputLimitResolution {
  * `0` or a negative.
  */
 export declare function resolveOutputTokens(input: OutputLimitInput): OutputLimitResolution;
+/**
+ * Average characters per token across the model families this package speaks to.
+ *
+ * EXPORTED (context-auto-compaction P2-3). It was module-private, which would
+ * have forced the CLI's compaction digest to grow a second copy for its budget
+ * arithmetic — two chars-per-token constants that must agree and nothing
+ * checking that they do is exactly how a digest budget and an occupancy estimate
+ * drift apart. No behaviour change here.
+ */
+export declare const CHARS_PER_TOKEN = 4;
 /**
  * Deliberately crude: ~4 chars/token plus per-message framing. Used ONLY to keep
  * `max_tokens + prompt <= context` on OpenAI, where being 20 % wrong is absorbed

package/dist/llm/output-limits.js

@@ -222,8 +222,16 @@ export function resolveOutputTokens(input) {
 // ---------------------------------------------------------------------------
 // Prompt estimation
 // ---------------------------------------------------------------------------
-/** Average characters per token across the model families this package speaks to. */
-const CHARS_PER_TOKEN = 4;
+/**
+ * Average characters per token across the model families this package speaks to.
+ *
+ * EXPORTED (context-auto-compaction P2-3). It was module-private, which would
+ * have forced the CLI's compaction digest to grow a second copy for its budget
+ * arithmetic — two chars-per-token constants that must agree and nothing
+ * checking that they do is exactly how a digest budget and an occupancy estimate
+ * drift apart. No behaviour change here.
+ */
+export const CHARS_PER_TOKEN = 4;
 /** Role markers, separators and tool-call scaffolding, per message. */
 const PER_MESSAGE_OVERHEAD_TOKENS = 4;
 function partLength(content) {

package/dist/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { AssistantMessage, Message, StreamEvent, TokenUsage } from './llm/types.js';
 import type { ToolResult } from './tools/types.js';
+import type { CompactionTrigger } from './engine/context-manager.js';
 export interface AgentStartEvent {
     type: 'agent_start';
 }
@@ -50,7 +51,62 @@ export interface CodeExecutionEndEvent {
     error?: string;
     duration: number;
 }
+/**
+ * Context compaction is about to run (context-auto-compaction §5.1).
+ *
+ * IT PAUSES THE IDLE WATCHDOG (`agent.ts::applyWatchdogPolicy`), because a
+ * summarization is a normal LLM call and can exceed `DEFAULT_IDLE_TIMEOUT`.
+ */
+export interface CompactionStartEvent {
+    type: 'compaction_start';
+    trigger: CompactionTrigger;
+    messageCount: number;
+}
+/**
+ * Context compaction finished, applied or not (context-auto-compaction §5.1).
+ *
+ * EMITTED FROM A `finally`, ON EVERY EXIT PATH. It is what RESUMES the watchdog,
+ * so a compaction that failed to emit its `end` would leave the run permanently
+ * deaf (P1-3).
+ */
+export interface CompactionEndEvent {
+    type: 'compaction_end';
+    applied: boolean;
+    mode: 'summarized' | 'truncated' | 'none';
+    /** Set whenever `applied` is false, and on any degraded splice. */
+    reason?: string;
+    messagesBefore: number;
+    messagesAfter: number;
+    droppedMessages: number;
+    /**
+     * Core's own `estimatePromptTokens`, BOTH SIDES — comparable by construction.
+     *
+     * A "before" from provider usage and an "after" from an estimate are two
+     * different units, and the card's headline claim ("118k -> 23k") would be
+     * comparing a measurement to a guess (§5.1).
+     */
+    estimatedTokensBefore: number;
+    estimatedTokensAfter: number;
+    /** The summary body, so the host needs no second channel to render its card. */
+    summary?: string;
+    /**
+     * Set only when the host clipped oversized `tool_result` bodies inside the
+     * RETAINED tail because the tail alone did not fit
+     * (context-auto-compaction-hardening §3.3.4 / W2).
+     *
+     * OPTIONAL, SO NO EXISTING SUBSCRIBER CHANGES. It is here rather than on
+     * `CompactionOutcome` because the engine has no use for the distinction — it
+     * validates and adopts a history like any other — while `aragon exec`'s JSON
+     * stream and the headless stderr line report a bounded, announced data loss
+     * the user is entitled to know about.
+     */
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    durationMs: number;
+}
 /** Union of all events emitted by the Agent engine. */
-export type AgentEvent = AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageUpdateEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | CodeExecutionStartEvent | CodeExecutionEndEvent;
+export type AgentEvent = AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageUpdateEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | CodeExecutionStartEvent | CodeExecutionEndEvent | CompactionStartEvent | CompactionEndEvent;
 /** Callback signature for Agent event listeners. */
 export type AgentEventListener = (event: AgentEvent) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/core",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "AragonAgent core engine — LLM provider adapters, streaming, tool registry/execution, steering, idle watchdog, and an optional isolated-vm sandbox.",
   "license": "MIT",
   "author": "AragonAgent contributors",