Handle goal commands without continuation turns

Author: benbrandt

src/CodexAcpClient.ts

@@ -327,7 +327,7 @@ export class CodexAcpClient {
         sessionId: string,
         objective: string,
         onTurnStarted?: (turnId: string) => void,
-    ): Promise<TurnCompletedNotification> {
+    ): Promise<TurnCompletedNotification | null> {
         return await this.codexClient.runGoalSet({
             threadId: sessionId,
             objective,
@@ -345,7 +345,7 @@ export class CodexAcpClient {
     async resumeGoal(
         sessionId: string,
         onTurnStarted?: (turnId: string) => void,
-    ): Promise<TurnCompletedNotification> {
+    ): Promise<TurnCompletedNotification | null> {
         return await this.codexClient.runGoalSet({
             threadId: sessionId,
             status: "active",

src/CodexAppServerClient.ts

@@ -105,6 +105,8 @@ const McpServerElicitationRequest = new RequestType<
     void
 >('mcpServer/elicitation/request');
 
+const GOAL_TURN_START_GRACE_MS = 1_000;
+
 /**
  * A type-safe client over the Codex App Server's JSON-RPC API.
  * Maps each request to its expected response and exposes clear, typed methods for supported JSON-RPC operations.
@@ -268,14 +270,18 @@ export class CodexAppServerClient {
         }
     }
 
-    async runGoalSet(params: ThreadGoalSetParams, onTurnStarted?: (turnId: string) => void): Promise<TurnCompletedNotification> {
+    async runGoalSet(
+        params: ThreadGoalSetParams,
+        onTurnStarted?: (turnId: string) => void,
+        turnStartGraceMs = GOAL_TURN_START_GRACE_MS,
+    ): Promise<TurnCompletedNotification | null> {
         const capturedCompletions: Array<TurnCompletedNotification> = [];
         const releaseCompletionCapture = this.captureTurnCompletions(params.threadId, (event) => {
             capturedCompletions.push(event);
         });
         let goalTurnId: string | null = null;
-        let resolveGoalTurnStarted: () => void = () => {};
-        const goalTurnStarted = new Promise<void>((resolve) => {
+        let resolveGoalTurnStarted: (turnId: string) => void = () => {};
+        const goalTurnStarted = new Promise<string>((resolve) => {
             resolveGoalTurnStarted = resolve;
         });
         const releaseRoutingCapture = this.captureTurnRoutings(params.threadId, (turnId) => {
@@ -284,17 +290,14 @@ export class CodexAppServerClient {
             }
             goalTurnId = turnId;
             onTurnStarted?.(turnId);
-            resolveGoalTurnStarted();
+            resolveGoalTurnStarted(turnId);
         });
 
         try {
             await this.threadGoalSet(params);
-            if (goalTurnId === null) {
-                await goalTurnStarted;
-            }
-            const turnId = goalTurnId;
+            const turnId = goalTurnId ?? await this.waitForGoalTurnStarted(goalTurnStarted, turnStartGraceMs);
             if (turnId === null) {
-                throw new Error("Goal command did not start a turn");
+                return null;
             }
             const earlyCompletion = capturedCompletions.find(event => event.turn.id === turnId);
             releaseCompletionCapture();
@@ -309,6 +312,20 @@ export class CodexAppServerClient {
         }
     }
 
+    private async waitForGoalTurnStarted(goalTurnStarted: Promise<string>, timeoutMs: number): Promise<string | null> {
+        let timeout: ReturnType<typeof setTimeout> | null = null;
+        const timeoutPromise = new Promise<null>((resolve) => {
+            timeout = setTimeout(() => resolve(null), timeoutMs);
+        });
+        try {
+            return await Promise.race([goalTurnStarted, timeoutPromise]);
+        } finally {
+            if (timeout !== null) {
+                clearTimeout(timeout);
+            }
+        }
+    }
+
     async runCompact(params: ThreadCompactStartParams): Promise<CompactionCompletedNotification> {
         const compactionCompleted = this.awaitCompactionCompleted(params.threadId);
         await this.threadCompactStart(params);

src/CodexCommands.ts

@@ -272,15 +272,12 @@ export class CodexCommands {
                 await this.runWithProcessCheck(() => this.codexAcpClient.setGoalStatus(sessionId, "paused"));
                 return { handled: true };
             case "resume":
-                return {
-                    handled: true,
-                    turnCompleted: await this.runWithProcessCheck(() => this.codexAcpClient.resumeGoal(
-                        sessionId,
-                        (turnId) => {
-                            sessionState.currentTurnId = turnId;
-                        },
-                    )),
-                };
+                return this.createGoalCommandResult(await this.runWithProcessCheck(() => this.codexAcpClient.resumeGoal(
+                    sessionId,
+                    (turnId) => {
+                        sessionState.currentTurnId = turnId;
+                    },
+                )));
             case "clear":
                 await this.runWithProcessCheck(() => this.codexAcpClient.clearGoal(sessionId));
                 return { handled: true };
@@ -298,15 +295,22 @@ export class CodexCommands {
             return { handled: true };
         }
 
+        return this.createGoalCommandResult(await this.runWithProcessCheck(() => this.codexAcpClient.setGoal(
+            sessionId,
+            argument,
+            (turnId) => {
+                sessionState.currentTurnId = turnId;
+            },
+        )));
+    }
+
+    private createGoalCommandResult(turnCompleted: TurnCompletedNotification | null): CommandHandleResult {
+        if (turnCompleted === null) {
+            return { handled: true };
+        }
         return {
             handled: true,
-            turnCompleted: await this.runWithProcessCheck(() => this.codexAcpClient.setGoal(
-                sessionId,
-                argument,
-                (turnId) => {
-                    sessionState.currentTurnId = turnId;
-                },
-            )),
+            turnCompleted,
         };
     }
 

src/__tests__/CodexACPAgent/CodexAcpClient.test.ts

@@ -1299,6 +1299,47 @@ describe('ACP server test', { timeout: 40_000 }, () => {
         expect(promptResolved).toBe(true);
     });
 
+    it('does not hang when goal set starts no continuation turn', async () => {
+        const mockFixture = createCodexMockTestFixture();
+        const codexAppServerClient = mockFixture.getCodexAppServerClient();
+        const threadGoalSetSpy = vi.spyOn(codexAppServerClient, "threadGoalSet")
+            .mockResolvedValue({ goal: createThreadGoal() });
+        const awaitTurnCompletedSpy = vi.spyOn(codexAppServerClient, "awaitTurnCompleted");
+
+        const result = await codexAppServerClient.runGoalSet({
+            threadId: "session-id",
+            objective: "Ship the migration and keep tests green",
+            status: "active",
+        }, undefined, 0);
+
+        expect(result).toBeNull();
+        expect(threadGoalSetSpy).toHaveBeenCalledWith({
+            threadId: "session-id",
+            objective: "Ship the migration and keep tests green",
+            status: "active",
+        });
+        expect(awaitTurnCompletedSpy).not.toHaveBeenCalled();
+    });
+
+    it('completes goal slash command when app server starts no continuation turn', async () => {
+        const { mockFixture, turnStartSpy } = setupPromptFixture();
+        const goalRunSpy = vi.spyOn(mockFixture.getCodexAppServerClient(), "runGoalSet")
+            .mockResolvedValue(null);
+
+        const response = await mockFixture.getCodexAcpAgent().prompt({
+            sessionId: "session-id",
+            prompt: [{ type: "text", text: "/goal Ship the migration and keep tests green" }],
+        });
+
+        expect(response.stopReason).toBe("end_turn");
+        expect(goalRunSpy).toHaveBeenCalledWith({
+            threadId: "session-id",
+            objective: "Ship the migration and keep tests green",
+            status: "active",
+        }, expect.any(Function));
+        expect(turnStartSpy).not.toHaveBeenCalled();
+    });
+
     it('reports missing goal slash command input', async () => {
         const { mockFixture } = setupPromptFixture();
         const goalSetSpy = vi.spyOn(mockFixture.getCodexAppServerClient(), "threadGoalSet")