@aragon-agent/core 0.2.14 → 0.2.16

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 }
+                        : {}),
                 },
             });
         }