fix: recover codex context overflow prompt errors

fuller-stack-dev · fuller-stack-dev · commit 52ea7e640e29 · 2026-05-22T17:25:19.000-06:00
diff --git a/src/agents/pi-embedded-helpers/errors.test.ts b/src/agents/pi-embedded-helpers/errors.test.ts
@@ -2,7 +2,7 @@ import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { describe, expect, it } from "vitest";
 import { MALFORMED_STREAMING_FRAGMENT_ERROR_MESSAGE } from "../../shared/assistant-error-format.js";
 import { makeAssistantMessageFixture } from "../test-helpers/assistant-message-fixtures.js";
-import { formatAssistantErrorText } from "./errors.js";
+import { formatAssistantErrorText, isLikelyContextOverflowError } from "./errors.js";
 
 describe("formatAssistantErrorText streaming JSON parse classification", () => {
   const makeAssistantError = (errorMessage: string): AssistantMessage =>
@@ -36,3 +36,13 @@ describe("formatAssistantErrorText streaming JSON parse classification", () => {
     );
   });
 });
+
+describe("isLikelyContextOverflowError", () => {
+  it("detects Codex promptError wording for a full context window", () => {
+    expect(
+      isLikelyContextOverflowError(
+        "Codex ran out of room in the model's context window. Start a new session or reset the conversation.",
+      ),
+    ).toBe(true);
+  });
+});
diff --git a/src/agents/pi-embedded-helpers/errors.ts b/src/agents/pi-embedded-helpers/errors.ts
@@ -107,6 +107,8 @@ export function isContextOverflowError(errorMessage?: string): boolean {
     lower.includes("context window") ||
     lower.includes("context length") ||
     lower.includes("maximum context length");
+  const hasContextWindowOutOfRoom =
+    hasContextWindow && (lower.includes("ran out of room") || lower.includes("ran out of space"));
   return (
     lower.includes("request_too_large") ||
     (lower.includes("invalid_argument") && lower.includes("maximum number of tokens")) ||
@@ -118,6 +120,7 @@ export function isContextOverflowError(errorMessage?: string): boolean {
     lower.includes("exceeds model context window") ||
     lower.includes("model token limit") ||
     (lower.includes("input exceeds") && lower.includes("maximum number of tokens")) ||
+    hasContextWindowOutOfRoom ||
     (hasRequestSizeExceeds && hasContextWindow) ||
     lower.includes("context overflow:") ||
     lower.includes("exceed context limit") ||
diff --git a/src/agents/pi-embedded-runner/run.overflow-compaction.harness.ts b/src/agents/pi-embedded-runner/run.overflow-compaction.harness.ts
@@ -182,6 +182,7 @@ export const mockedIsLikelyContextOverflowError = vi.fn((msg?: string) => {
   return (
     lower.includes("request_too_large") ||
     lower.includes("context window exceeded") ||
+    (lower.includes("context window") && lower.includes("ran out of room")) ||
     lower.includes("prompt is too long")
   );
 });
@@ -360,6 +361,7 @@ export function resetRunOverflowCompactionHarnessMocks(): void {
     return (
       lower.includes("request_too_large") ||
       lower.includes("context window exceeded") ||
+      (lower.includes("context window") && lower.includes("ran out of room")) ||
       lower.includes("prompt is too long")
     );
   });
diff --git a/src/agents/pi-embedded-runner/run.overflow-compaction.test.ts b/src/agents/pi-embedded-runner/run.overflow-compaction.test.ts
@@ -22,6 +22,7 @@ import {
   mockedEnsureAuthProfileStoreWithoutExternalProfiles,
   mockedGlobalHookRunner,
   mockedGetApiKeyForModel,
+  mockedIsLikelyContextOverflowError,
   mockedMarkAuthProfileSuccess,
   mockedPickFallbackThinkingLevel,
   mockedResolveAuthProfileOrder,
@@ -1511,6 +1512,39 @@ describe("runEmbeddedPiAgent overflow compaction trigger routing", () => {
     expect(result.meta.error).toBeUndefined();
   });
 
+  it("surfaces a visible blocked payload for Codex promptError overflow without assistant text", async () => {
+    const promptError = new Error(
+      "Codex ran out of room in the model's context window. Start a new session or reset the conversation.",
+    );
+    const terminalLifecycleMeta: Array<Record<string, unknown>> = [];
+    mockedRunEmbeddedAttempt.mockResolvedValueOnce(
+      makeAttemptResult({
+        promptError,
+        promptErrorSource: "prompt",
+        assistantTexts: [],
+        attemptUsage: { input: 0, output: 0, total: 0 },
+        setTerminalLifecycleMeta: (meta) => {
+          terminalLifecycleMeta.push(meta);
+        },
+      }),
+    );
+
+    const result = await runEmbeddedPiAgent(overflowBaseRunParams);
+
+    expect(mockedIsLikelyContextOverflowError).toHaveBeenCalledWith(promptError.message);
+    expect(mockedCompactDirect).toHaveBeenCalledTimes(1);
+    expect(result.payloads?.[0]).toMatchObject({
+      isError: true,
+      text: expect.stringContaining("Context overflow"),
+    });
+    expect(result.payloads?.[0]?.text).toContain("/reset");
+    expect(result.payloads?.[0]?.text).toContain("/new");
+    expect(result.meta.error?.kind).toBe("context_overflow");
+    expect(result.meta.livenessState).toBe("blocked");
+    expect(result.meta.finalAssistantVisibleText).toBe(result.payloads?.[0]?.text);
+    expect(terminalLifecycleMeta.at(-1)).toMatchObject({ livenessState: "blocked" });
+  });
+
   it("does not reset compaction attempt budget after successful tool-result truncation", async () => {
     const overflowError = queueOverflowAttemptWithOversizedToolOutput(
       mockedRunEmbeddedAttempt,
diff --git a/src/agents/pi-embedded-runner/run.ts b/src/agents/pi-embedded-runner/run.ts
@@ -2123,16 +2123,21 @@ export async function runEmbeddedPiAgent(
               );
             }
             const kind = isCompactionFailure ? "compaction_failure" : "context_overflow";
+            const overflowRecoveryText =
+              "Context overflow: prompt too large for the model. " +
+              "Try /reset (or /new) to start a fresh session, or use a larger-context model.";
+            log.warn(
+              `[context-overflow-recovery] exhausted provider overflow recovery for ${provider}/${modelId}; ` +
+                `livenessState=blocked suggestedAction=reset_or_new kind=${kind}`,
+            );
             attempt.setTerminalLifecycleMeta?.({
               replayInvalid: resolveReplayInvalidForAttempt(),
               livenessState: "blocked",
             });
             return {
               payloads: [
                 {
-                  text:
-                    "Context overflow: prompt too large for the model. " +
-                    "Try /reset (or /new) to start a fresh session, or use a larger-context model.",
+                  text: overflowRecoveryText,
                   isError: true,
                 },
               ],
@@ -2150,6 +2155,8 @@ export async function runEmbeddedPiAgent(
                   lastTurnTotal,
                 }),
                 systemPromptReport: attempt.systemPromptReport,
+                finalAssistantVisibleText: overflowRecoveryText,
+                finalAssistantRawText: overflowRecoveryText,
                 finalPromptText: attempt.finalPromptText,
                 replayInvalid: resolveReplayInvalidForAttempt(),
                 livenessState: "blocked",
