feat(tui): add /compact command with optional summarizer instructions

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -187,7 +187,7 @@ The agent maintains an optional **`manage_tasks`** list (create/update via the h
 
 #### Context compaction (the compaction governor)
 
-When a cycle's input tokens cross a threshold, the director compacts the inference-facing history (the full run is always retained in the context store). The threshold is **model-aware** — roughly 60% of the active model's real context window — so small-window models compact early enough to avoid provider context-overflow while large-window models do not compact prematurely. The compacted prefix is **append-only across passes**: the existing compacted user turn stays byte-identical; new folds become later summary turns with a harness-inserted assistant spacer (identified by reserved `model: "harness"`, plus a visible sentinel; persisted `[compaction]` tokens without a producer still freeze) between them so the prompt head can remain in the provider KV cache. Model-emitted copies of the spacer are not frozen. Spacer-only model replies are incomplete: ChatDirector nudges, then falls through loop-protection, workflow-idle, and open-task rails rather than empty-settling with work still open. The governor covers four cases:
+When a cycle's input tokens cross a threshold, the director compacts the inference-facing history (the full run is always retained in the context store). The threshold is **model-aware** — roughly 60% of the active model's real context window — so small-window models compact early enough to avoid provider context-overflow while large-window models do not compact prematurely. The compacted prefix is **append-only across passes**: the existing compacted user turn stays byte-identical; new folds become later summary turns with a harness-inserted assistant spacer (identified by reserved `model: "harness"`, plus a visible sentinel; persisted `[compaction]` tokens without a producer still freeze) between them so the prompt head can remain in the provider KV cache. Model-emitted copies of the spacer are not frozen. Spacer-only model replies are incomplete: ChatDirector nudges, then falls through loop-protection, workflow-idle, and open-task rails rather than empty-settling with work still open. The governor covers five cases:
 
 - **Threshold at a tool pause** — Once over threshold, the follow-up `infer` after a tool batch is swapped for a `compact` cycle, and inference resumes via a host continuation message. After a compact that remains over the high watermark, the governor uses **growth hysteresis** (wait for usage to grow by ~10% of the window) instead of re-arming on every cycle; dropping under 60% is not required.
 - **Idle (end-of-turn)** — An interactive turn can end with a reply and then sit idle with no tool batch to intercept; the governor requests a continuation at that pause and compacts when it arrives. An operator message that races the continuation still compacts first, then re-enters inference to answer it.
@@ -204,6 +204,7 @@ When a cycle's input tokens cross a threshold, the director compacts the inferen
 
 The `ollama` table key is the bare provider segment; the harness stamps slash-form on `sourceId` (`ollama/default` / `ollama/<instance>`), with `provider: openai-compatible` (`buildOpenAISource`) and a bare model (`llama3` / `qwen3`). Idle-recompress disable matches via `isOllamaProviderId` on that `sourceId` (`src/provider/ollama.ts`), not by looking up slash-form as a table key.
 
+- **Operator `/compact`** — A first-class slash command folds now without waiting for the occupancy governor. Optional trailing instructions go to the summarizer (empty uses the default structured fold) and are stored on the compact record so later auto-folds still see them. An in-flight turn uses the same pair-safe compact-then-continue hop as threshold compact; an idle compact shows the fold and does not start a new turn.
 - **Overflow recovery** — A `context_overflow` inference error would otherwise become a terminal error reply; the governor compacts and retries instead, bounded so a history the compactor cannot shrink does not loop forever. Overflow ignores hysteresis for the compact itself.
 
 The TTL window is measured from the last `inference.done` (every inference rewrites the provider's prefix cache) with one fire per window per compact of any kind, and it never fires with a tool batch outstanding — stall pings can arrive mid-work. The consecutive-compact cap shared with the threshold path still bounds compact→infer→compact. Prompt-caching the summary call itself is an explicit non-goal: the fold carries no cache options.

docs/IMPLEMENTATION.md

@@ -138,7 +138,7 @@ src/
     commands/
       registry.ts         Extensible slash-command registry
       built-in.ts         /help, /model, /settings, /permissions, /plugins,
-                          /clear, /new, /mcp (connect providers from /model),
+                          /clear, /new, /compact, /mcp (connect providers from /model),
                           /yolo
   tui/
     shell.ts              Transcript, header, status line, prompt, overlays

docs/PRODUCT.md

@@ -105,7 +105,7 @@ the file path and parse details.
 
 ## Slash Commands (TUI)
 
-The TUI has an extensible slash-command framework. Built-ins include `/help` (shortcut + command overlay), `/model` (models-only picker for connected accounts; **Alt+A** or `/connect` adds a provider), `/settings`, `/permissions`, `/plugins`, `/clear`, `/new`, `/mcp` (enable, disable, or remove servers), and `/yolo` (persists as the user-global skip-permissions default; `--dangerously-skip-permissions` still forces this process; secret-guard and authz still apply; `/yolo [on|off|toggle]`, bare `/yolo` toggles), plus a `/<name>` command per available workflow. When a session starts with the persisted default already on, the TUI shows a startup notice ("Permission prompts are disabled by your saved default…") so the silent machine-wide default is never invisible; `corbits exec` prints the equivalent warning to stderr. Plugins can register additional commands.
+The TUI has an extensible slash-command framework. Built-ins include `/help` (shortcut + command overlay), `/model` (models-only picker for connected accounts; **Alt+A** or `/connect` adds a provider), `/settings`, `/permissions`, `/plugins`, `/clear`, `/new`, `/compact` (fold conversation context now, optional trailing instructions to the summarizer; does not wait for the 60% occupancy governor; idle success shows the fold and does not start a new turn), `/mcp` (enable, disable, or remove servers), and `/yolo` (persists as the user-global skip-permissions default; `--dangerously-skip-permissions` still forces this process; secret-guard and authz still apply; `/yolo [on|off|toggle]`, bare `/yolo` toggles), plus a `/<name>` command per available workflow. When a session starts with the persisted default already on, the TUI shows a startup notice ("Permission prompts are disabled by your saved default…") so the silent machine-wide default is never invisible; `corbits exec` prints the equivalent warning to stderr. Plugins can register additional commands.
 
 **Default skills** exist out of the gate as first-party slash **actions**, not director names: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/scribe`, `/interview`, `/ast-grep`, `/lexicon`. Each one is a how-to playbook — the slash sends the skill body to the primary, which follows the steps. Skills do not assign identity or route the fleet; that stays on director system prompts. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request-review` is worktree checkout plus a surface pass, loading `/review` for quality rules only; `/scribe` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` is the per-commit review/build/critique loop — it does not steal planning from `/plan`. Substantial Builder work consumes a counsel / `/plan` plan first; tiny parent-DIY stays plan-optional. `/plan` authors an eng change plan (files, AC, non-goals, risks, ordered steps) and does not implement. `/create-issue` remains the tracker command: Linear MCP when available; otherwise it `ask_operator`s for the platform (GitHub etc.) and persists `Preferred issue tracker` in `.corbits/MEMORY.md` (GitHub via `gh issue create`). `/lexicon` owns director-prompt drift and size against the agents repo at a pinned commit. There is no first-party dispatch skill — Skywalker orchestrates natively. `git-rebase`, `linear-issue-workflow`, `style`, `philosophy`, `native-integration`, `typescript`, `ponytail`, and `opsh` stay `use_skill` only (`user-invocable: false`). Bake-only bars such as `idiot-proof` and `native-runtime` are not slashes and are not listed for `use_skill`. Draper and emil are not slashes; they remain closed directors via `spawn_agent(agent=…)`. There is no catch-all worker. Slash names are also available to the model via `skill_search` (descriptions) then `use_skill` (body). Disable the catalog in `/plugins` (`corbits-skills`) if you want them gone.
 

src/agent/compaction.test.ts

@@ -8,6 +8,7 @@ import type {
 } from "@intx/types/runtime";
 import {
   COMPACTION_CONTINUATION_EVENT,
+  OPERATOR_COMPACT_REASON,
   createCompactionGovernor,
 } from "./compaction.js";
 import {
@@ -785,6 +786,74 @@ describe("compaction governor", () => {
     ]);
     expect(continuations).toBe(1);
   });
+
+  test("manual compact bypasses the occupancy governor on an idle session", () => {
+    const governor = createCompactionGovernor(undefined);
+    governor.noteInferenceDone(inferenceDone(1000), tenTurns);
+
+    expect(governor.requestManual("keep the auth discussion")).toBe("kick");
+    expect(governor.extraInstructions).toBe("keep the auth discussion");
+    expect(governor.requestManual("")).toBe("armed");
+    expect(governor.extraInstructions).toBe("keep the auth discussion");
+
+    const actions = governor.interceptIdleContinuation(
+      emptyMessage(),
+      capabilities,
+    );
+    expect(
+      actions?.some(
+        (a) =>
+          a.type === "compact" &&
+          "reason" in a &&
+          a.reason === OPERATOR_COMPACT_REASON,
+      ),
+    ).toBe(true);
+    expect(governor.resumeAfterCompact(emptyMessage())).toBe("meter");
+    expect(governor.resumeAfterCompact(emptyMessage())).toBeNull();
+  });
+
+  test("manual compact during a tool pause continues the in-flight turn", () => {
+    const governor = createCompactionGovernor(() => undefined);
+    governor.noteInferenceDone(inferenceDone(1000), tenTurns);
+
+    expect(governor.requestManual("", { inFlight: true })).toBe("armed");
+    const actions = governor.interceptActions(
+      toolDone(),
+      inferAction,
+      capabilities,
+    );
+    expect(
+      actions?.some(
+        (a) =>
+          a.type === "compact" &&
+          "reason" in a &&
+          a.reason === OPERATOR_COMPACT_REASON,
+      ),
+    ).toBe(true);
+    expect(actions?.some((a) => a.type === "infer")).toBe(false);
+    expect(governor.resumeAfterCompact(emptyMessage())).toBe("infer");
+  });
+
+  test("manual compact no-ops below the compactor floor", () => {
+    const governor = createCompactionGovernor(undefined);
+    governor.noteInferenceDone(inferenceDone(overThreshold), threeTurns);
+    expect(governor.requestManual("focus on tests")).toBe("noop");
+    expect(governor.extraInstructions).toBeUndefined();
+    expect(
+      governor.interceptIdleContinuation(emptyMessage(), capabilities),
+    ).toBeNull();
+  });
+
+  test("manual compact hydrates from restored turns without a prior decide", () => {
+    const governor = createCompactionGovernor(undefined);
+    expect(governor.compactTurnCount).toBe(0);
+    expect(governor.requestManual("keep the auth discussion")).toBe("noop");
+    expect(
+      governor.requestManual("keep the auth discussion", { turns: tenTurns }),
+    ).toBe("kick");
+    expect(governor.compactTurnCount).toBe(10);
+    expect(governor.extraInstructions).toBe("keep the auth discussion");
+  });
 });
 
 describe("provider-aware idle recompress (CL-8745)", () => {

src/agent/compaction.ts

@@ -54,6 +54,19 @@ export type CompactionGovernor = ReturnType<typeof createCompactionGovernor>;
 // requestContinuation closure delivered. Subscribers that only care about
 // provider/connector traffic must ignore this event.
 export const COMPACTION_CONTINUATION_EVENT = "custom.compaction.continue";
+/** Compact reason for `/compact` (and later operator-triggered folds). */
+export const OPERATOR_COMPACT_REASON = "operator-request";
+const THRESHOLD_COMPACT_REASON = "context-threshold";
+
+/** How `/compact` armed the shared pipeline. */
+export type ManualCompactArming = "kick" | "armed" | "noop";
+
+/** Options for an operator-triggered compact. */
+export type ManualCompactOptions = {
+  inFlight?: boolean;
+  /** Live or restored turns; used to arm after resume before the first decide. */
+  turns?: readonly ConversationTurn[];
+};
 
 /** Build the continuation re-entry action for a compacted governor cycle. */
 export function compactionContinuationAction(
@@ -70,6 +83,11 @@ export function createCompactionGovernor(
 ) {
   let pending = false;
   let idlePending = false;
+  let manualPending = false;
+  // Sticky operator instructions from `/compact …`. Empty `/compact` still
+  // uses the default structured fold; a non-empty argument is kept for later
+  // auto-folds and written into the compact record.
+  let extraInstructions: string | undefined;
   let postCompactInfer = false;
   // Idle empty compact needs a post-compact decide cycle to adopt the shrunk
   // turns for the meter, but must not start a new inference (there is no
@@ -157,6 +175,16 @@ export function createCompactionGovernor(
     noteCompactIssued();
   }
 
+  function compactReason(operator: boolean): string {
+    return operator ? OPERATOR_COMPACT_REASON : THRESHOLD_COMPACT_REASON;
+  }
+
+  function clearManualArming(): void {
+    manualPending = false;
+    idlePending = false;
+    pending = false;
+  }
+
   // Continuation re-entry for a compact-bearing return. The legacy subagent
   // path still holds a host closure and drives its stall-ping loop through
   // it; the chat path holds none and gets an emit action the host answers
@@ -246,16 +274,22 @@ export function createCompactionGovernor(
   ): ReactorAction[] | null {
     if (event.type !== "tool.done") return null;
     if (outstandingToolCalls > 0) outstandingToolCalls -= 1;
-    if (!pending && !(usingEstimate && isOverThreshold(estimate.tokens)))
+    const operator = manualPending;
+    if (
+      !operator &&
+      !pending &&
+      !(usingEstimate && isOverThreshold(estimate.tokens))
+    )
       return null;
     if (!actions.some((a) => a.type === "infer")) return null;
-    if (atThresholdCompactCap()) return null;
-    pending = false;
+    if (!operator && atThresholdCompactCap()) return null;
+    clearManualArming();
     postCompactInfer = true;
-    issueThresholdCompact();
+    if (operator) noteCompactIssued();
+    else issueThresholdCompact();
     return [
       ...actions.filter((a) => a.type !== "infer"),
-      capabilities.compact(COMPACTOR_NAME, "context-threshold"),
+      capabilities.compact(COMPACTOR_NAME, compactReason(operator)),
       ...continuationActions(capabilities),
     ];
   }
@@ -276,8 +310,10 @@ export function createCompactionGovernor(
     event: ReactorInboundEvent,
     actions: ReactorAction[],
   ): boolean {
-    if (!pending || idlePending) return false;
-    if (atThresholdCompactCap()) return false;
+    if (idlePending) return false;
+    const operator = manualPending;
+    if (!operator && !pending) return false;
+    if (!operator && atThresholdCompactCap()) return false;
     if (!onTurnBoundary(event)) return false;
     if (isSpacerEchoTerminal(event, actions)) return false;
     const terminal =
@@ -352,26 +388,35 @@ export function createCompactionGovernor(
   ): ReactorAction[] | null {
     if (event.type !== "message.received") return null;
     if (idlePending) {
-      if (atThresholdCompactCap()) {
+      const operator = manualPending;
+      if (!operator && atThresholdCompactCap()) {
         idlePending = false;
         return null;
       }
-      idlePending = false;
-      pending = false;
+      clearManualArming();
+      const content = inboundText(event);
       // The reactor delivers no event after compact, so always request a
       // continuation to re-enter decide against the shrunk turns:
       // - raced operator content → re-infer to answer it
       // - empty synthetic continuation → meter-only sync (no infer)
-      return issueIdleFold(
-        inboundText(event),
-        capabilities,
-        "context-threshold",
-      );
+      if (operator) {
+        if (content.length > 0) postCompactInfer = true;
+        else postCompactMeter = true;
+        noteCompactIssued();
+        return [
+          capabilities.compact(COMPACTOR_NAME, OPERATOR_COMPACT_REASON),
+          ...continuationActions(capabilities),
+        ];
+      }
+      return issueIdleFold(content, capabilities, THRESHOLD_COMPACT_REASON);
     }
     // Unarmed idle re-entry past the provider TTL: same fold, same
     // keep-recent tail, same cap — but a "cache-ttl-recompress" reason so the
     // fold is attributable. No arming: every live re-entry re-checks the
     // window, so a sub-agent stall ping or operator message is the trigger.
+    // In-flight `/compact` (manualPending without idlePending) waits on
+    // interceptActions; do not steal that hop with a TTL fold.
+    if (manualPending) return null;
     if (!isTtlRecompressDue(now())) return null;
     return issueIdleFold(
       inboundText(event),
@@ -443,6 +488,28 @@ export function createCompactionGovernor(
     return postCompactInfer || postCompactMeter;
   }
 
+  // `/compact` bypasses the occupancy governor. Same pair-safe compact pipeline
+  // as auto-compact: in-flight turns wait for interceptActions / noteIdleTurn;
+  // idle sessions arm an empty continuation so the host can kick decide().
+  function requestManual(
+    instructions: string,
+    options?: ManualCompactOptions,
+  ): ManualCompactArming {
+    if (options?.turns !== undefined) syncFromTurns(options.turns);
+    if (turnCount <= MIN_TURNS_TO_COMPACT) return "noop";
+    const trimmed = instructions.trim();
+    if (trimmed.length > 0) extraInstructions = trimmed;
+    manualPending = true;
+    if (options?.inFlight === true) return "armed";
+    if (idlePending) return "armed";
+    idlePending = true;
+    if (requestContinuation !== undefined) {
+      requestContinuation();
+      return "armed";
+    }
+    return "kick";
+  }
+
   return {
     get estimatedTokens(): number {
       return estimate.tokens;
@@ -453,6 +520,13 @@ export function createCompactionGovernor(
     get usingEstimate(): boolean {
       return usingEstimate;
     },
+    get extraInstructions(): string | undefined {
+      return extraInstructions;
+    },
+    get compactTurnCount(): number {
+      return turnCount;
+    },
+    requestManual,
     syncFromTurns,
     noteInferenceDone,
     notePostCompact,