feat: LLM-27711 Codex /compact command

Author: NikolaiSviridov

src/CodexAcpClient.ts

@@ -415,6 +415,12 @@ export class CodexAcpClient {
         });
     }
 
+    async compactSession(sessionId: string): Promise<TurnCompletedNotification> {
+        const turnCompleted = this.codexClient.awaitTurnCompleted(sessionId);
+        await this.codexClient.threadCompactStart({ threadId: sessionId });
+        return await turnCompleted;
+    }
+
     async listSkills(params?: SkillsListParams): Promise<SkillsListResponse> {
         return this.codexClient.listSkills(params ?? {});
     }

src/CodexAcpServer.ts

@@ -15,6 +15,7 @@ import type {
     ReasoningEffortOption,
     Thread,
     ThreadItem,
+    TurnCompletedNotification,
     UserInput
 } from "./app-server/v2";
 import type {RateLimitsMap} from "./RateLimitsMap";
@@ -742,13 +743,20 @@ export class CodexAcpServer implements acp.Agent {
                 approvalHandler,
                 elicitationHandler);
 
-            if (await this.availableCommands.tryHandle(params.prompt, sessionState)) {
+            const commandResult = await this.availableCommands.tryHandle(params.prompt, sessionState);
+            if (commandResult) {
                 logger.log("Prompt handled by a command");
-                return {
-                    stopReason: "end_turn",
-                    usage: this.buildPromptUsage(sessionState.lastTokenUsage),
-                    _meta: this.buildQuotaMeta(sessionState),
-                };
+                if (commandResult !== true) {
+                    const interruptedResponse = await this.createInterruptedResponseIfNeeded(params.sessionId, commandResult, sessionState);
+                    if (interruptedResponse) {
+                        return interruptedResponse;
+                    }
+                }
+                const error = eventHandler.getFailure();
+                if (error) {
+                    throw error;
+                }
+                return this.createPromptResponse("end_turn", sessionState);
             }
 
             const modelId = ModelId.fromString(sessionState.currentModelId);
@@ -771,22 +779,9 @@ export class CodexAcpServer implements acp.Agent {
                 () => this.codexAcpClient.sendPrompt(params, agentMode, modelId, disableSummary, sessionState.cwd));
 
             // Check if turn was interrupted (cancelled)
-            if (turnCompleted.turn.status === "interrupted") {
-                await this.connection.sessionUpdate({
-                    sessionId: params.sessionId,
-                    update: {
-                        sessionUpdate: "agent_message_chunk",
-                        content: {
-                            type: "text",
-                            text: "*Conversation interrupted*"
-                        }
-                    }
-                });
-                return {
-                    stopReason: "cancelled",
-                    usage: this.buildPromptUsage(sessionState.lastTokenUsage),
-                    _meta: this.buildQuotaMeta(sessionState),
-                };
+            const interruptedResponse = await this.createInterruptedResponseIfNeeded(params.sessionId, turnCompleted, sessionState);
+            if (interruptedResponse) {
+                return interruptedResponse;
             }
 
             const error = eventHandler.getFailure()
@@ -795,11 +790,7 @@ export class CodexAcpServer implements acp.Agent {
                 throw error;
             }
 
-            return {
-                stopReason: "end_turn",
-                usage: this.buildPromptUsage(sessionState.lastTokenUsage),
-                _meta: this.buildQuotaMeta(sessionState),
-            };
+            return this.createPromptResponse("end_turn", sessionState);
         } catch (err) {
             logger.error(`Prompt for session ${params.sessionId} failed`, err);
             throw err;
@@ -835,6 +826,35 @@ export class CodexAcpServer implements acp.Agent {
         return toPromptUsage(lastTokenUsage);
     }
 
+    private async createInterruptedResponseIfNeeded(
+        sessionId: string,
+        turnCompleted: TurnCompletedNotification,
+        sessionState: SessionState
+    ): Promise<acp.PromptResponse | null> {
+        if (turnCompleted.turn.status !== "interrupted") {
+            return null;
+        }
+        await this.connection.sessionUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "agent_message_chunk",
+                content: {
+                    type: "text",
+                    text: "*Conversation interrupted*"
+                }
+            }
+        });
+        return this.createPromptResponse("cancelled", sessionState);
+    }
+
+    private createPromptResponse(stopReason: acp.PromptResponse["stopReason"], sessionState: SessionState): acp.PromptResponse {
+        return {
+            stopReason,
+            usage: this.buildPromptUsage(sessionState.lastTokenUsage),
+            _meta: this.buildQuotaMeta(sessionState),
+        };
+    }
+
     private async runWithProcessCheck<T>(operation: () => Promise<T>): Promise<T> {
         try {
             return await operation();

src/CodexAppServerClient.ts

@@ -26,6 +26,8 @@ import type {
     SkillsListResponse,
     ThreadLoadedListParams,
     ThreadLoadedListResponse,
+    ThreadCompactStartParams,
+    ThreadCompactStartResponse,
     ThreadListParams,
     ThreadListResponse,
     ThreadReadParams,
@@ -205,6 +207,10 @@ export class CodexAppServerClient {
         return await this.sendRequest({ method: "thread/read", params: params });
     }
 
+    async threadCompactStart(params: ThreadCompactStartParams): Promise<ThreadCompactStartResponse> {
+        return await this.sendRequest({ method: "thread/compact/start", params });
+    }
+
     async listMcpServerStatus(params: ListMcpServerStatusParams): Promise<ListMcpServerStatusResponse> {
         return await this.sendRequest({ method: "mcpServerStatus/list", params });
     }

src/CodexCommands.ts

@@ -3,6 +3,7 @@ import type {AgentSideConnection, AvailableCommand} from "@agentclientprotocol/s
 import {ACPSessionConnection} from "./ACPSessionConnection";
 import type {CodexAcpClient} from "./CodexAcpClient";
 import type {RateLimitSnapshot, SkillsListEntry} from "./app-server/v2";
+import type {TurnCompletedNotification} from "./app-server/v2";
 import type {SessionState} from "./CodexAcpServer";
 import type {RateLimitsMap} from "./RateLimitsMap";
 import type {TokenCount} from "./TokenCount";
@@ -41,7 +42,7 @@ export class CodexCommands {
         }
     }
 
-    async tryHandle(prompt: acp.ContentBlock[], sessionState: SessionState): Promise<boolean> {
+    async tryHandle(prompt: acp.ContentBlock[], sessionState: SessionState): Promise<CommandHandlingResult | false> {
         const command = this.parseCommand(prompt);
         if (command) {
             return this.handleCommand(command, sessionState);
@@ -91,6 +92,11 @@ export class CodexCommands {
                 description: "Display session configuration and token usage.",
                 input: null
             },
+            {
+                name: "compact",
+                description: "Compact conversation history to reduce context usage.",
+                input: null
+            },
             {
                 name: "logout",
                 description: "Sign out of Codex. This option is available when you are logged in via ChatGPT.",
@@ -119,10 +125,12 @@ export class CodexCommands {
         };
     }
 
-    async handleCommand(command: ParsedCommand, sessionState: SessionState): Promise<boolean> {
+    async handleCommand(command: ParsedCommand, sessionState: SessionState): Promise<CommandHandlingResult> {
         const sessionId = sessionState.sessionId;
 
         switch (command.name) {
+            case "compact":
+                return await this.runWithProcessCheck(() => this.codexAcpClient.compactSession(sessionId));
             case "status": {
                 const session = new ACPSessionConnection(this.connection, sessionId);
                 const message = this.buildStatusMessage(sessionState);
@@ -355,3 +363,4 @@ export class CodexCommands {
 }
 
 type ParsedCommand = { name: string; input: string | null };
+type CommandHandlingResult = true | TurnCompletedNotification;

src/CodexEventHandler.ts

@@ -227,6 +227,14 @@ export class CodexEventHandler {
                 return await createMcpToolCallUpdate(event.item);
             case "dynamicToolCall":
                 return await createDynamicToolCallUpdate(event.item);
+            case "contextCompaction":
+                return {
+                    sessionUpdate: "tool_call",
+                    toolCallId: event.item.id,
+                    kind: "other",
+                    title: "Compacting context",
+                    status: "in_progress",
+                };
             case "collabAgentToolCall":
             case "userMessage":
             case "hookPrompt":
@@ -237,7 +245,6 @@ export class CodexEventHandler {
             case "imageGeneration":
             case "enteredReviewMode":
             case "exitedReviewMode":
-            case "contextCompaction":
             case "plan":
                 return null;
         }
@@ -272,6 +279,12 @@ export class CodexEventHandler {
                         text: summary
                     }
                 }
+            case "contextCompaction":
+                return {
+                    sessionUpdate: "tool_call_update",
+                    toolCallId: event.item.id,
+                    status: "completed",
+                };
             case "collabAgentToolCall":
             case "userMessage":
             case "hookPrompt":
@@ -281,7 +294,6 @@ export class CodexEventHandler {
             case "imageGeneration":
             case "enteredReviewMode":
             case "exitedReviewMode":
-            case "contextCompaction":
             case "plan":
                 return null;
         }