feat(autoloop): auto-compact on context-budget threshold

Closes the last design-doc deferred item (§7.1). Each agent gets a /compact
dispatched when its contextPercent crosses the per-role threshold (Planner
80%, Coder 70%, Reviewer 70%) — uses Claude Code's built-in /compact slash
command with an agent-specific preservation hint, so session id is kept and
no manual memory-file dance is needed.

Implementation:
  - dispatcher.maybeCompact(agent, name) in src/autoloop/dispatcher.ts —
    reads getStatus(name).stats.contextPercent, fires compactSession()
    when over threshold, 30s cooldown to prevent back-to-back fires
  - per-agent compactSummaryFor() builds the /compact <hint> text:
    Planner keeps plan/goal/user decisions; Coder keeps codebase
    familiarity + attempted patches; Reviewer keeps fakery patterns +
    recent metrics
  - called at the end of deliverToPlanner / deliverToCoder /
    deliverToReviewer (both happy path and clarification path for Coder,
    both verdict and no-verdict path for Reviewer)
  - new 'compact' SSE event on /autoloop/<id>/events, plumbed via
    embedded-server's existing SSE relay
  - ClaudeAgentDispatcherConfig.compactThresholds for per-run override

Dashboard: renders compact events inline in the relevant pane as
'[auto-compact <pct>% ≥ <threshold>% — /compact dispatched]' system entries.

501/501 tests pass; build/lint/format clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Enderfga

CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.3] - 2026-05-10
+
+### Added — auto-compact on context-budget threshold
+
+Each agent session is monitored after every turn via `getStats().contextPercent`.
+When it crosses the per-agent threshold the dispatcher dispatches `/compact`
+with an agent-specific summary hint:
+
+| Agent | Default threshold | What `/compact` is told to preserve |
+|---|---|---|
+| Planner | 80% | current plan / goal, decisions with the user, what's been tried + rejected, user prefs, iter verdicts |
+| Coder | 70% | codebase familiarity, attempted patches, current working state, plan + goal |
+| Reviewer | 70% | fakery patterns caught, recent metrics, structural rules from goal.json |
+
+Per-run override via `compactThresholds: { planner?, coder?, reviewer? }` on
+the dispatcher config. 30-second cooldown prevents back-to-back compactions.
+
+Surfaces as a new `compact` SSE event on `/autoloop/<id>/events` (alongside
+`planner_reply` / `coder_reply` / `reviewer_reply`); the embedded dashboard
+renders it as an inline `[auto-compact 82% ≥ 80% — /compact dispatched]`
+system entry in the relevant pane.
+
+Closes the last design-doc deferred item (auto-compact, design doc §7.1).
+Manual `autoloop_reset_agent` still available for nuclear reset.
+
 ## [3.5.2] - 2026-05-10
 
 ### Fixed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enderfga/claw-orchestrator",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "description": "Claw Orchestrator — run Claude Code, Codex, Gemini, Cursor Agent, OpenCode and custom coding CLIs as one unified runtime for claw-style agent systems. Runs standalone, with first-class OpenClaw plugin support. Persistent sessions, multi-agent council, tool orchestration.",
   "type": "module",
   "main": "./dist/src/index.js",

src/autoloop/dispatcher.ts

@@ -56,6 +56,16 @@ export interface ClaudeAgentDispatcherConfig {
   /** Per-message wall-clock cap. Default 10 min. */
   sendTimeoutMs?: number;
   logger?: Logger;
+  /**
+   * Auto-compact thresholds (percent of context window). When the agent's
+   * `contextPercent` (from getStats) climbs above its threshold after a
+   * turn, the dispatcher dispatches `/compact <agent-specific summary>` to
+   * that agent. Defaults: Planner 80%, Coder 70%, Reviewer 70%.
+   *
+   * Per the design doc §7: each agent's context is precious; don't let it
+   * silently fill until the API rejects.
+   */
+  compactThresholds?: { planner?: number; coder?: number; reviewer?: number };
   /**
    * Push-policy ref that S3's update_push_policy mutates. Caller (SessionManager)
    * passes its own policy object so changes are visible to the runner.
@@ -228,6 +238,71 @@ export class ClaudeAgentDispatcher extends EventEmitter implements AgentDispatch
     }
   }
 
+  // ─── Auto-compact ────────────────────────────────────────────────────────
+  //
+  // After each agent turn we check getStats().contextPercent. When it crosses
+  // the per-agent threshold we send `/compact <hint>` to ask Claude Code to
+  // drop chunks of history while preserving what each role needs to keep
+  // working. /compact preserves the session id — no reset, no memory-file
+  // dance, no reprime — so this is cheap.
+  //
+  // We track lastCompactAt per agent to avoid re-firing within 30 s in case
+  // the immediate post-compact stats haven't refreshed yet.
+
+  private lastCompactAt: Partial<Record<'planner' | 'coder' | 'reviewer', number>> = {};
+
+  private compactSummaryFor(agent: 'planner' | 'coder' | 'reviewer'): string {
+    if (agent === 'planner') {
+      return [
+        'Preserve: current plan.md state and goal.json criteria; what the user has asked',
+        "for and approved; what directions have been tried and rejected; the user's style",
+        'preferences for this run; iter-by-iter Reviewer verdicts. Drop: verbose tool',
+        'output, intermediate file dumps, redundant context.',
+      ].join(' ');
+    }
+    if (agent === 'coder') {
+      return [
+        'Preserve: codebase familiarity (what files do what), what patches you have already',
+        'tried and why they failed, what is currently working, the current plan and goal.',
+        'Drop: full file dumps, verbose stack traces, intermediate eval output beyond the',
+        'last few iters.',
+      ].join(' ');
+    }
+    return [
+      'Preserve: patterns of fakery you have caught (in reviewer_memory.md), recent metric',
+      'history, structural rules from goal.json, your accumulating model of what cheating',
+      'looks like in this codebase. Drop: full diff dumps from older iters, verbose audit',
+      'transcripts beyond the last few iters.',
+    ].join(' ');
+  }
+
+  private async maybeCompact(agent: 'planner' | 'coder' | 'reviewer', name: string): Promise<void> {
+    const cfg = this.config.compactThresholds ?? {};
+    const threshold =
+      agent === 'planner' ? (cfg.planner ?? 80) : agent === 'coder' ? (cfg.coder ?? 70) : (cfg.reviewer ?? 70);
+    let pct: number | undefined;
+    try {
+      const stats = this.config.manager.getStatus(name).stats;
+      pct = stats.contextPercent;
+    } catch {
+      // Session might be gone (terminate races); silent skip.
+      return;
+    }
+    if (pct == null || pct < threshold) return;
+    const last = this.lastCompactAt[agent] ?? 0;
+    if (Date.now() - last < 30_000) return;
+    this.lastCompactAt[agent] = Date.now();
+    this.logger.info?.(
+      `[autoloop/${this.config.runId}] ${agent} context ${pct.toFixed(0)}% ≥ ${threshold}% — auto-compact`,
+    );
+    this.emit('compact', { agent, percent: pct, threshold });
+    try {
+      await this.config.manager.compactSession(name, this.compactSummaryFor(agent));
+    } catch (err) {
+      this.logger.warn?.(`[autoloop/${this.config.runId}] compact ${agent} failed: ${(err as Error).message}`);
+    }
+  }
+
   // ─── Planner-specific ────────────────────────────────────────────────────
 
   private async ensurePlanner(): Promise<void> {
@@ -318,6 +393,8 @@ export class ClaudeAgentDispatcher extends EventEmitter implements AgentDispatch
 
     // Emit cleaned reply (without raw JSON blocks) for the chat tool to surface.
     if (parsed.cleaned_reply) this.emit('planner_reply', parsed.cleaned_reply);
+    // Auto-compact after each Planner turn if context is filling up.
+    await this.maybeCompact('planner', this.plannerName);
     return handlerResult.emitted_messages;
   }
 
@@ -393,6 +470,7 @@ export class ClaudeAgentDispatcher extends EventEmitter implements AgentDispatch
     if (!ic) {
       // No iter_complete emitted — could be a clarification request, or the
       // Coder bailed. Return a directive_ack so Planner sees it next turn.
+      await this.maybeCompact('coder', this.coderName);
       return [
         Msg.directiveAck(env.iter, {
           understood: false,
@@ -424,6 +502,7 @@ export class ClaudeAgentDispatcher extends EventEmitter implements AgentDispatch
     const commitMsg = `autoloop/iter-${env.iter}: ${ic.summary}`.slice(0, 200);
     await this.runGit(['git', 'commit', '-m', commitMsg]);
 
+    await this.maybeCompact('coder', this.coderName);
     return [
       Msg.iterArtifacts(env.iter, {
         diff: diffOut.out,
@@ -522,10 +601,12 @@ export class ClaudeAgentDispatcher extends EventEmitter implements AgentDispatch
         metric: null,
         audit_notes: verdict.payload.audit_notes,
       });
+      await this.maybeCompact('reviewer', this.reviewerName);
       return [verdict];
     }
 
     this.persistVerdict(env.payload.iter, rc);
+    await this.maybeCompact('reviewer', this.reviewerName);
     return [Msg.reviewVerdict(env.payload.iter, rc)];
   }
 

src/dashboard/index.html

@@ -629,6 +629,24 @@ <h2 id="sidebarTitle">Runs</h2>
           });
           paintPlanner();
         });
+        es.addEventListener('compact', (e) => {
+          const data = JSON.parse(e.data);
+          const entry = {
+            who: 'system',
+            text: `[auto-compact ${data.percent.toFixed(0)}% ≥ ${data.threshold}% — /compact dispatched]`,
+            ts: new Date().toISOString(),
+          };
+          if (data.agent === 'planner') {
+            state.autoloop.plannerLog.push(entry);
+            paintPlanner();
+          } else if (data.agent === 'coder') {
+            state.autoloop.coderLog.push(entry);
+            paintCoder();
+          } else if (data.agent === 'reviewer') {
+            state.autoloop.reviewerLog.push(entry);
+            paintReviewer();
+          }
+        });
       }
 
       function paintAutoloopState() {

src/embedded-server.ts

@@ -576,6 +576,7 @@ export class EmbeddedServer {
         const onPlannerReply = (text: unknown): void => send('planner_reply', { text });
         const onCoderReply = (text: unknown): void => send('coder_reply', { text });
         const onReviewerReply = (text: unknown): void => send('reviewer_reply', { text });
+        const onCompact = (e: unknown): void => send('compact', e);
         const cleanup = (): void => {
           ctx.runner.off('message', onMessage);
           ctx.runner.off('state', onState);
@@ -585,6 +586,7 @@ export class EmbeddedServer {
           ctx.dispatcher.off('planner_reply', onPlannerReply);
           ctx.dispatcher.off('coder_reply', onCoderReply);
           ctx.dispatcher.off('reviewer_reply', onReviewerReply);
+          ctx.dispatcher.off('compact', onCompact);
           try {
             res.end();
           } catch {
@@ -599,6 +601,7 @@ export class EmbeddedServer {
         ctx.dispatcher.on('planner_reply', onPlannerReply);
         ctx.dispatcher.on('coder_reply', onCoderReply);
         ctx.dispatcher.on('reviewer_reply', onReviewerReply);
+        ctx.dispatcher.on('compact', onCompact);
         res.on('close', cleanup);
         return;
       }