fix(investigation): reconcile Codex terminal output (#179)

* fix(investigation): reconcile Codex terminal output

* chore(release): rebuild ReviewRouter action

Author: 777genius

__tests__/unit/review-investigation/codex-app-server-protocol.test.ts

@@ -1238,7 +1238,22 @@ describe('CodexAppServerProtocolClient', () => {
     });
   });
 
-  it('rejects an unseen allowed terminal snapshot item as protocol drift', async () => {
+  it('reconciles an unseen non-effectful item from the terminal snapshot', async () => {
+    const fixture = await activeTurn();
+    const item = agentMessageItem(
+      'terminal-only',
+      'final_answer',
+      '{"ok":true}'
+    );
+    completeUsage(fixture.client);
+    completeTurn(fixture.client, [item]);
+
+    await expect(fixture.result).resolves.toMatchObject({
+      finalMessage: '{"ok":true}',
+    });
+  });
+
+  it('rejects an unseen MCP item from the terminal snapshot', async () => {
     const fixture = await activeTurn();
     fixture.client.receive(
       notification('turn/completed', {
@@ -1247,13 +1262,14 @@ describe('CodexAppServerProtocolClient', () => {
           id: turnId,
           status: 'completed',
           error: null,
-          items: [agentMessageItem('unseen', 'final_answer', '{"ok":true}')],
+          items: [mcpToolCallItem('terminal-only', successfulMcpOutcome())],
         },
       })
     );
 
     await expect(fixture.result).rejects.toMatchObject({
       failureClass: ReviewAgentFailureClass.StreamIncomplete,
+      message: 'review_agent_stream_incomplete_turn_completed',
     });
   });
 

__tests__/unit/review-investigation/review-agent-adapters.contract.test.ts

@@ -275,6 +275,28 @@ describe.each([
     });
   });
 
+  it('accepts exactly one schema-valid JSON payload surrounded by provider prose', async () => {
+    const { adapter, runner, request } = fixture(ReviewAgentProviderKind.Codex);
+    runner.rawCodexOutput = `Completed review.\n${JSON.stringify(turnOutput)}\nEnd of review.`;
+
+    await expect(adapter.executeTurn(request)).resolves.toMatchObject({
+      outputVersion: 2,
+      findings: turnOutput.findings,
+    });
+  });
+
+  it('rejects ambiguous provider prose containing multiple valid payloads', async () => {
+    const { adapter, runner, request } = fixture(ReviewAgentProviderKind.Codex);
+    runner.rawCodexOutput = `${JSON.stringify(turnOutput)}\n${JSON.stringify({
+      ...turnOutput,
+      findings: [],
+    })}`;
+
+    await expect(adapter.executeTurn(request)).rejects.toMatchObject({
+      failureClass: ReviewAgentFailureClass.SchemaInvalidOutput,
+    });
+  });
+
   it('fails malformed provider output as schema-invalid', async () => {
     const { adapter, runner, request } = fixture(providerKind);
     runner.output = { ...turnOutput, authoritativeClean: true };

dist/index.js

@@ -108598,10 +108598,16 @@ var CodexAppServerProtocolClient = class {
         const id = requireIdentifier2(item.id, "item_id");
         const type2 = requireNonEmptyString(item.type, "item_type");
         this.validateAllowedItem(item, "completed");
-        const observed = this.completedItems.get(id);
-        if (!observed || snapshotItemIds.has(id) || observed.type !== type2) {
+        if (snapshotItemIds.has(id)) {
           throw streamFailure2();
         }
+        const observed = this.completedItems.get(id);
+        if (!observed) {
+          this.reconcileTerminalNonEffectfulItem(item, id, type2);
+          snapshotItemIds.add(id);
+          continue;
+        }
+        if (observed.type !== type2) throw streamFailure2();
         if (type2 === "mcpToolCall" && (observed.server !== item.server || observed.tool !== item.tool)) {
           throw confinementFailure("mcp_tool_identity_changed");
         }
@@ -108614,6 +108620,14 @@ var CodexAppServerProtocolClient = class {
       }
     }
   }
+  reconcileTerminalNonEffectfulItem(item, id, type2) {
+    if (type2 === "mcpToolCall") throw streamFailure2();
+    const active = this.activeItems.get(id);
+    if (active && active.type !== type2) throw streamFailure2();
+    this.activeItems.delete(id);
+    this.completedItems.set(id, Object.freeze({ type: type2 }));
+    if (type2 === "agentMessage") this.captureFinalMessage(item);
+  }
   validateAllowedItem(item, lifecycle) {
     const type2 = requireNonEmptyString(item.type, "item_type");
     if (FORBIDDEN_ITEM_TYPES.has(type2)) {
@@ -109945,7 +109959,7 @@ var CodexReviewAgentAdapter = class extends StrictCliReviewAgent {
     });
     let output;
     try {
-      output = parseReviewAgentTurnOutput(parseFinalJson(result2.finalMessage));
+      output = parseFinalTurnOutput(result2.finalMessage);
     } catch (error2) {
       throw schemaFailure(error2);
     }
@@ -110014,29 +110028,56 @@ var CodexReviewAgentAdapter = class extends StrictCliReviewAgent {
     return Object.freeze(args);
   }
 };
-function parseFinalJson(message) {
+function parseFinalTurnOutput(message) {
   const trimmed = message.trim();
-  try {
-    return JSON.parse(trimmed);
-  } catch (error2) {
-    const extracted = extractSingleJsonPayload(trimmed);
-    if (extracted === null) throw error2;
-    return JSON.parse(extracted);
-  }
-}
-function extractSingleJsonPayload(message) {
-  const fenced = message.match(/^```(?:json)?\s*\n([\s\S]*?)\n```\s*$/iu);
-  if (fenced) {
-    const payload = fenced[1];
-    return typeof payload === "string" ? payload.trim() : null;
-  }
-  const start = message.indexOf("{");
-  const end = message.lastIndexOf("}");
-  if (start < 0 || end <= start) return null;
-  const prefix = message.slice(0, start).trim();
-  const suffix = message.slice(end + 1).trim();
-  if (prefix || suffix) return null;
-  return message.slice(start, end + 1);
+  const valid = /* @__PURE__ */ new Map();
+  for (const candidate of extractJsonPayloadCandidates(trimmed)) {
+    try {
+      const output = parseReviewAgentTurnOutput(JSON.parse(candidate));
+      valid.set(JSON.stringify(output), output);
+    } catch {
+    }
+  }
+  if (valid.size !== 1) throw new Error("review_agent_output_invalid");
+  return [...valid.values()][0];
+}
+function extractJsonPayloadCandidates(message) {
+  const candidates = /* @__PURE__ */ new Set();
+  if (message) candidates.add(message);
+  const fencedPattern = /```(?:json)?\s*\n([\s\S]*?)\n```/giu;
+  for (const match2 of message.matchAll(fencedPattern)) {
+    const payload = match2[1]?.trim();
+    if (payload) candidates.add(payload);
+  }
+  let start = -1;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < message.length; index += 1) {
+    const character = message[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"' && depth > 0) {
+      inString = true;
+      continue;
+    }
+    if (character === "{") {
+      if (depth === 0) start = index;
+      depth += 1;
+      continue;
+    }
+    if (character !== "}" || depth === 0) continue;
+    depth -= 1;
+    if (depth === 0 && start >= 0) {
+      candidates.add(message.slice(start, index + 1));
+      start = -1;
+    }
+  }
+  return Object.freeze([...candidates]);
 }
 function tomlString2(value) {
   return JSON.stringify(value);

dist/index.js.map

@@ -631,10 +631,16 @@ export class CodexAppServerProtocolClient {
         const id = requireIdentifier(item.id, 'item_id');
         const type = requireNonEmptyString(item.type, 'item_type');
         this.validateAllowedItem(item, 'completed');
-        const observed = this.completedItems.get(id);
-        if (!observed || snapshotItemIds.has(id) || observed.type !== type) {
+        if (snapshotItemIds.has(id)) {
           throw streamFailure();
         }
+        const observed = this.completedItems.get(id);
+        if (!observed) {
+          this.reconcileTerminalNonEffectfulItem(item, id, type);
+          snapshotItemIds.add(id);
+          continue;
+        }
+        if (observed.type !== type) throw streamFailure();
         if (
           type === 'mcpToolCall' &&
           (observed.server !== item.server || observed.tool !== item.tool)
@@ -654,6 +660,19 @@ export class CodexAppServerProtocolClient {
     }
   }
 
+  private reconcileTerminalNonEffectfulItem(
+    item: Record<string, unknown>,
+    id: string,
+    type: string
+  ): void {
+    if (type === 'mcpToolCall') throw streamFailure();
+    const active = this.activeItems.get(id);
+    if (active && active.type !== type) throw streamFailure();
+    this.activeItems.delete(id);
+    this.completedItems.set(id, Object.freeze({ type }));
+    if (type === 'agentMessage') this.captureFinalMessage(item);
+  }
+
   private validateAllowedItem(
     item: Record<string, unknown>,
     lifecycle: 'started' | 'completed'

src/review-investigation/infrastructure/codex-app-server-protocol.ts

@@ -11,6 +11,7 @@ import {
 import {
   buildReviewAgentTurnOutputSchema,
   parseReviewAgentTurnOutput,
+  type ReviewAgentTurnOutput,
   type ReviewTurnObservation,
 } from '../domain/turn-observation';
 import {
@@ -97,7 +98,7 @@ export class CodexReviewAgentAdapter extends StrictCliReviewAgent {
 
     let output;
     try {
-      output = parseReviewAgentTurnOutput(parseFinalJson(result.finalMessage));
+      output = parseFinalTurnOutput(result.finalMessage);
     } catch (error) {
       throw schemaFailure(error);
     }
@@ -171,31 +172,61 @@ export class CodexReviewAgentAdapter extends StrictCliReviewAgent {
   }
 }
 
-function parseFinalJson(message: string): unknown {
+function parseFinalTurnOutput(message: string): ReviewAgentTurnOutput {
   const trimmed = message.trim();
-  try {
-    return JSON.parse(trimmed);
-  } catch (error) {
-    const extracted = extractSingleJsonPayload(trimmed);
-    if (extracted === null) throw error;
-    return JSON.parse(extracted);
+  const valid = new Map<string, ReviewAgentTurnOutput>();
+  for (const candidate of extractJsonPayloadCandidates(trimmed)) {
+    try {
+      const output = parseReviewAgentTurnOutput(JSON.parse(candidate));
+      valid.set(JSON.stringify(output), output);
+    } catch {
+      // Provider prose and malformed JSON are ignored unless no unique
+      // schema-valid payload remains.
+    }
   }
+  if (valid.size !== 1) throw new Error('review_agent_output_invalid');
+  return [...valid.values()][0]!;
 }
 
-function extractSingleJsonPayload(message: string): string | null {
-  const fenced = message.match(/^```(?:json)?\s*\n([\s\S]*?)\n```\s*$/iu);
-  if (fenced) {
-    const payload = fenced[1];
-    return typeof payload === 'string' ? payload.trim() : null;
+function extractJsonPayloadCandidates(message: string): readonly string[] {
+  const candidates = new Set<string>();
+  if (message) candidates.add(message);
+
+  const fencedPattern = /```(?:json)?\s*\n([\s\S]*?)\n```/giu;
+  for (const match of message.matchAll(fencedPattern)) {
+    const payload = match[1]?.trim();
+    if (payload) candidates.add(payload);
   }
 
-  const start = message.indexOf('{');
-  const end = message.lastIndexOf('}');
-  if (start < 0 || end <= start) return null;
-  const prefix = message.slice(0, start).trim();
-  const suffix = message.slice(end + 1).trim();
-  if (prefix || suffix) return null;
-  return message.slice(start, end + 1);
+  let start = -1;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < message.length; index += 1) {
+    const character = message[index]!;
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === '\\') escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"' && depth > 0) {
+      inString = true;
+      continue;
+    }
+    if (character === '{') {
+      if (depth === 0) start = index;
+      depth += 1;
+      continue;
+    }
+    if (character !== '}' || depth === 0) continue;
+    depth -= 1;
+    if (depth === 0 && start >= 0) {
+      candidates.add(message.slice(start, index + 1));
+      start = -1;
+    }
+  }
+  return Object.freeze([...candidates]);
 }
 
 function tomlString(value: string): string {