Implement session compaction feature with ACP integration

- Added `session/compact` method to compact the durable CrewCoder session in place, returning a summary.
- Updated ACP adapter to advertise the new compaction method and handle requests.
- Introduced `compactDurableSession` function to manage session compaction logic, including hooks for extension support.
- Enhanced event handling to differentiate between automatic and manual compaction, including summary body in notifications.
- Created tests for session compaction, including scenarios for previewing compaction and applying edited summaries.
- Refactored existing code to support the new compaction functionality and ensure compatibility with the ACP protocol.

Author: CjLogic

crewcoder-agent/AGENTS.md

@@ -539,7 +539,8 @@ summary:       LLM-generated via the active model client, deterministic fallback
                 retained recent messages are authoritative for completion status and must be visible to
                 the summarizer so completed work is not revived as an open thread
 events:        reuses session_compacted + SessionCompaction[] (no event-stream/schema changes)
-manual:        crewcoder session compact <id>; TUI /compact, /compact on|off|status
+manual:        crewcoder session compact <id>; TUI /compact, /compact on|off|status;
+                ACP session/compact (idle durable rewrite; advertised on initialize._meta)
 ```
 
 Do not change `currentContextTokens` to use cumulative `totalTokens` as the primary metric — the
@@ -919,6 +920,12 @@ ACP extension: CrewCode calls it after new/load, including with `[]` to revoke s
 CrewCoder validates roots on the agent host, persists them in session metadata, and authorizes file
 tools through `ToolContext.externalDirectories`; never replace this with a process-global allowlist
 or an environment variable. See `docs/EXTERNAL_DIRECTORIES.md`.
+`session/compact` is the other host-owned session extension: it compacts the durable session in
+place (same rewrite as `crewcoder session compact`), returns the summary, and emits
+`_crewcoder/compaction_update` with `automatic: false`. Advertise it on
+`initialize._meta["crewcoder/sessionCompact"]`. Do not let CrewCode fall back to local
+summary-reset when this method exists. Refuse compact during an in-flight `session/prompt`.
+Automatic live compaction still omits the summary body on the update channel.
 
 When a client advertises `clientCapabilities.fs`, `read`/`write`/`edit` route text I/O
 through `fs/read_text_file`/`fs/write_text_file` instead of `node:fs`, which is how

crewcoder-agent/docs/ACP_ADAPTER.md

@@ -60,12 +60,14 @@ see "Deliberate deviations" below.
 | `session/set_model` | Switches provider/model. Routed through `extMethod` |
 | `session/set_approval_mode` | Switches the active session approval/sandbox mode without respawning CrewCoder |
 | `session/set_external_directories` | Replaces and persists the session's explicitly granted filesystem roots |
+| `session/compact` | Compacts the durable CrewCoder session in place and returns the summary |
 | `authenticate` | No-op; credentials are managed by `crewcoder auth` |
 
 Capabilities are reported **honestly**: `loadSession: true`,
 `promptCapabilities.image: false`. CrewCoder takes images as on-disk paths, not
 inline base64, so advertising the ACP image block would invite a request it cannot
-serve.
+serve. Manual compact is advertised on `initialize._meta["crewcoder/sessionCompact"]`,
+not as a standard ACP session capability.
 
 ## Deliberate deviations from the 1.x schema
 
@@ -100,6 +102,30 @@ dangerous-command tripwire should keep CrewCoder in `review` and auto-resolve or
 permission requests instead; setting `full-access` makes Codex unrestricted and prevents that
 host from inspecting provider-native commands before execution.
 
+`session/compact` is the host compact-button path. It is an additive extension method
+routed through `extMethod`, same as `session/set_model`. `initialize._meta["crewcoder/sessionCompact"]`
+advertises `{ method: "session/compact", preview: true, editedSummary: true }` so CrewCode can
+stop local summary-reset and compact CrewCoder's durable session instead.
+
+Request: `{ sessionId, preview?, summary? }`. `preview: true` generates the summary without
+saving. A non-empty `summary` installs that text as the compacted background. The method
+refuses while `session/prompt` is running and refuses sessions that have not been persisted
+yet. It is the same rewrite as `crewcoder session compact`: older messages become a
+synthetic background summary, recent messages stay, native provider continuation is
+cleared, and `lastInputTokens` is reset.
+
+Response:
+
+```txt
+compacted, preview, edited, compactionId?, source?, fallbackReason?,
+originalMessageCount, retainedMessageCount, summary
+```
+
+Host-requested compact emits `_crewcoder/compaction_update` with `automatic: false`. The
+completed update **includes `summary`** so the client can replace its local history with
+CrewCoder's summary rather than inventing one. Automatic live compaction still omits the
+summary body on the update channel.
+
 `session/prompt` reports usage **twice**: `_meta["crewcoder/usage"]` (spec-correct,
 full `UsageSummary` including `contextWindow` and `lastInputTokens`) and a top-level
 `usage` mirror, which is where hermes-derived clients look.
@@ -130,10 +156,12 @@ overlay can render the current session list without reconstructing mutations.
 
 Compaction has no standard ACP lifecycle shape, so CrewCoder uses the additive
 `_crewcoder/compaction_update` session-update kind. It carries `status`,
-`automatic`, `percent`, `message`, and optional phase/count/id metadata. The
-compacted summary body stays in CrewCoder's durable session and is deliberately
-not broadcast to the client. CrewCode understands this extension; standard-only
-ACP clients safely ignore the unknown update kind.
+`automatic`, `percent`, `message`, and optional phase/count/id metadata. Automatic
+live compaction keeps the summary body in CrewCoder's durable session and does not
+put it on the update. Host-requested `session/compact` sets `automatic: false` and
+includes `summary` on both the RPC result and the completed update. CrewCode
+understands this extension; standard-only ACP clients safely ignore the unknown
+update kind.
 
 Everything else returns `undefined` and is dropped. CrewCoder's richer vocabulary —
 checkpoints, cost ledger, durable goals, compaction preview, token budget,

crewcoder-agent/docs/AUTO_COMPACTION.md

@@ -46,7 +46,10 @@ auto-compact. Claude's SDK-native auto-compaction is
 also enabled as defense in depth for its opaque resumed session. While running as an ACP agent,
 CrewCoder publishes its own compaction lifecycle on the additive
 `_crewcoder/compaction_update` session-update kind so capable hosts can show progress before the
-next usage snapshot arrives. Codex app-server durable threads
+next usage snapshot arrives. CrewCode's compact button must call ACP `session/compact`
+(advertised on `initialize._meta["crewcoder/sessionCompact"]`); that rewrites the durable
+session the same way `crewcoder session compact` does and returns the summary. Do not
+leave host compact as a local transcript summary-reset. Codex app-server durable threads
 avoid repeatedly uploading full context across restarts, but they do not change the
 model's context-window limit; see
 [`CODEX_TRANSPORT.md`](./CODEX_TRANSPORT.md).
@@ -154,6 +157,10 @@ detached in a `finally` so it never keeps the process alive.
 
 ### Idle — saved-session command
 
+ACP clients use the same idle path over `session/compact` instead of the CLI. The method
+accepts `{ sessionId, preview?, summary? }`, refuses while a prompt is in flight, and
+returns the installed summary so the host can update its local transcript.
+
 When no run is active, the TUI shells out to the backend, which atomically replaces the saved
 session history and clears native provider continuation before the next resume:
 

crewcoder-agent/docs/SESSION_COMPACTION_PROGRESS_EVENTS.md

@@ -36,9 +36,12 @@ Fields:
 `status: "started"`, failures to `"failed"`, and `session_compacted` to
 `"completed"`. A skipped no-op closes an already-open progress indicator with a
 completed lifecycle status while preserving the explicit skip message and phase.
-The payload is marked `automatic: true` because ACP currently exposes no native
-manual-compaction request; host-triggered manual compaction remains host-owned.
-The summary body is not sent over this notification channel.
+Token-triggered live compaction marks the payload `automatic: true` and omits the
+summary body. Host-requested `session/compact` marks it `automatic: false` and
+includes `summary` on the completed update plus the RPC result, so CrewCode can
+replace local history with CrewCoder's durable compact instead of a host-side
+summary-reset. ACP still has no standard compact method; this is the namespaced
+CrewCoder extension advertised on `initialize._meta["crewcoder/sessionCompact"]`.
 
 Standard-only ACP clients may ignore the unknown namespaced update. CrewCode
 parses it into its provider-neutral compaction meter and therefore does not infer

crewcoder-agent/src/acp/acp-agent.ts

@@ -27,6 +27,7 @@ import {
 } from "@agentclientprotocol/sdk";
 import { runAgentLoop, type AgentLoopResult } from "../core/agent-loop.js";
 import { runAgentLoopContinue } from "../core/agent-loop-continue.js";
+import { compactDurableSession } from "../core/compact-session.js";
 import { createSessionId } from "../core/session-store.js";
 import { setSessionExternalDirectories, validateExternalDirectories } from "../core/external-directories.js";
 import { loadSession as loadSessionRecord } from "../core/session-loader.js";
@@ -36,7 +37,7 @@ import { DEFAULT_AGENT_MODE } from "../core/mode-router.js";
 import type { AgentEvent } from "../core/events.js";
 import type { ApprovalMode } from "../core/approval.js";
 import type { AgentMode } from "../core/types.js";
-import type { ModelQuestion } from "../core/model-client.js";
+import { HeuristicModelClient, type ModelQuestion } from "../core/model-client.js";
 import type { ApprovalControlDecision } from "../core/stdin-control.js";
 import { ProviderModelClient } from "../providers/provider-model-client.js";
 import { listBuiltinProviderModels, resolveModel } from "../providers/model-registry.js";
@@ -81,6 +82,22 @@ type AcpSession = {
 type AcpModelInfo = { modelId: string; name: string; description?: string };
 type AcpModelState = { availableModels: AcpModelInfo[]; currentModelId: string };
 
+/** Advertised on `initialize._meta` so CrewCode can call compact instead of local summary-reset. */
+export const CREWCODER_SESSION_COMPACT_META = {
+  method: "session/compact",
+  preview: true,
+  editedSummary: true
+} as const;
+
+const EXT_METHODS = new Set([
+  "session/set_model",
+  "session/set_reasoning_effort",
+  "session/set_approval_mode",
+  "session/set_external_directories",
+  "session/follow_up",
+  "session/compact"
+]);
+
 const PERMISSION_OPTIONS: PermissionOption[] = [
   { optionId: "allow_once", name: "Allow", kind: "allow_once" },
   { optionId: "allow_always", name: "Always allow", kind: "allow_always" },
@@ -120,7 +137,8 @@ export class CrewCoderAcpAgent implements Agent {
           embeddedContext: false
         }
       },
-      authMethods: []
+      authMethods: [],
+      _meta: { "crewcoder/sessionCompact": CREWCODER_SESSION_COMPACT_META }
     };
   }
 
@@ -179,10 +197,14 @@ export class CrewCoderAcpAgent implements Agent {
    * respawning CrewCoder.
    */
   async extMethod(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>> {
-    if (method !== "session/set_model" && method !== "session/set_reasoning_effort" && method !== "session/set_approval_mode" && method !== "session/set_external_directories" && method !== "session/follow_up") throw RequestError.methodNotFound(method);
+    if (!EXT_METHODS.has(method)) throw RequestError.methodNotFound(method);
     const sessionId = typeof params.sessionId === "string" ? params.sessionId : "";
     const session = this.session(sessionId);
 
+    if (method === "session/compact") {
+      return this.compactSession(session, params);
+    }
+
     if (method === "session/follow_up") {
       const message = typeof params.message === "string" ? params.message.trim() : "";
       if (!message) throw RequestError.invalidParams({ reason: "message is required" });
@@ -238,6 +260,51 @@ export class CrewCoderAcpAgent implements Agent {
     return {};
   }
 
+  private async compactSession(session: AcpSession, params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (session.abort) {
+      throw RequestError.invalidParams({ reason: "Cannot compact while a prompt is running. Wait for the current turn to finish." });
+    }
+    if (!session.started) {
+      throw RequestError.invalidParams({ reason: "session has no durable transcript yet" });
+    }
+    const preview = params.preview === true;
+    const summary = typeof params.summary === "string" ? params.summary : undefined;
+    const emit = async (event: AgentEvent): Promise<void> => {
+      const update = translateEvent(event);
+      if (update) await this.conn.sessionUpdate({ sessionId: session.sessionId, update: update as unknown as SessionUpdate });
+    };
+    try {
+      const result = await compactDurableSession({
+        sessionId: session.sessionId,
+        modelClient: this.modelClientFor(session),
+        cwd: session.cwd,
+        preview,
+        editedSummary: summary,
+        emit,
+        automatic: false
+      });
+      return {
+        compacted: result.compacted,
+        preview: result.preview,
+        edited: result.edited,
+        compactionId: result.compactionId,
+        source: result.source,
+        fallbackReason: result.fallbackReason,
+        originalMessageCount: result.originalMessageCount,
+        retainedMessageCount: result.retainedMessageCount,
+        summary: result.summary
+      };
+    } catch (error) {
+      throw RequestError.internalError({ message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  private modelClientFor(session: AcpSession): ProviderModelClient | HeuristicModelClient {
+    return this.options.heuristic
+      ? new HeuristicModelClient()
+      : new ProviderModelClient(session.providerId, session.cwd, session.model, undefined, session.reasoningEffort);
+  }
+
   async cancel(params: CancelNotification): Promise<void> {
     const session = this.sessions.get(params.sessionId);
     if (!session) return;

crewcoder-agent/src/acp/event-translator.ts

@@ -16,13 +16,15 @@ export type SessionUpdate = SessionNotification["update"];
 export interface CrewCoderCompactionUpdate {
   sessionUpdate: "_crewcoder/compaction_update";
   status: "started" | "completed" | "failed";
-  automatic: true;
+  automatic: boolean;
   phase?: "requested" | "summarizing" | "saving" | "skipped" | "failed";
   percent?: number;
   message: string;
   compactionId?: string;
   originalMessageCount?: number;
   retainedMessageCount?: number;
+  /** Present only for host-requested compact, so CrewCode can replace local history. */
+  summary?: string;
 }
 
 export type CrewCoderSessionUpdate = SessionUpdate | CrewCoderCompactionUpdate;
@@ -81,7 +83,7 @@ export function translateEvent(event: AgentEvent): CrewCoderSessionUpdate | unde
     return {
       sessionUpdate: "_crewcoder/compaction_update",
       status: event.phase === "failed" ? "failed" : event.phase === "skipped" ? "completed" : "started",
-      automatic: true,
+      automatic: event.automatic !== false,
       phase: event.phase,
       percent: event.percent,
       message: event.message,
@@ -91,15 +93,17 @@ export function translateEvent(event: AgentEvent): CrewCoderSessionUpdate | unde
   }
 
   if (event.type === "session_compacted") {
+    const automatic = event.automatic !== false;
     return {
       sessionUpdate: "_crewcoder/compaction_update",
       status: "completed",
-      automatic: true,
+      automatic,
       percent: 100,
       message: "Context compacted. Continuing with the retained recent messages and summary.",
       compactionId: event.compactionId,
       originalMessageCount: event.originalMessageCount,
-      retainedMessageCount: event.retainedMessageCount
+      retainedMessageCount: event.retainedMessageCount,
+      ...(automatic ? {} : { summary: event.summary })
     };
   }