[codex] Structure OpenCode text generation failures

[juliusmarminge]

OpenCode text generation handled session creation, prompt requests, provider-declared failures, and empty output inside one tryPromise. Semantic failures were converted into raw Error values, so the public TextGenerationError retained only a string and an artificial stack frame. Transport failures were also indistinguishable by phase.

This change introduces phase-specific Schema tagged errors for session requests, missing session payloads, prompt requests, provider-declared prompt failures, and empty output. They retain safe correlation fields such as the text-generation operation, cwd, session id, provider/model ids, and response part counts without retaining prompt or output bodies. SDK request failures keep the exact thrown cause; response-shape failures intentionally have no manufactured cause.

The SDK work is split into Effect operations and the known internal tags are mapped to the existing public TextGenerationError with catchTags. Existing user-facing details for missing payloads, provider-declared failures, and empty output remain unchanged.

Validation:

• vp test apps/server/src/textGeneration/OpenCodeTextGeneration.test.ts (9 tests)
• vp check (passes; repository has 20 pre-existing warnings)
• vp run typecheck

---

Note

Medium Risk
Changes error propagation on a shared text-generation path used for commit messages and related flows; behavior is intended to stay the same at the API surface but failure typing and cause chains differ internally.

Overview
OpenCode text generation no longer wraps session create, prompt, and response handling in one tryPromise that turned semantic failures into generic Errors. The SDK path is split into Effect steps that fail with phase-specific tagged errors (SessionRequest, SessionPayload, PromptRequest, PromptResponse, EmptyOutput), carrying safe correlation fields (operation, cwd, session id, provider/model, part counts) and preserving the real SDK throw only for transport failures.

Those tags are mapped to the existing public TextGenerationError via catchTags, keeping the same user-facing detail strings for missing payloads, provider errors, and empty output. Provider-side failures are parsed with getOpenCodePromptFailure ({ name?, message }) instead of a single string helper.

Tests extend the runtime mock for session/prompt failures and assert structured error.cause tags and fields across each failure mode.

^{Reviewed by Cursor Bugbot for commit 5ab986c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Structure OpenCode text generation failures as typed errors with contextual detail

• Introduces six tagged error classes in OpenCodeTextGeneration.ts covering session creation failure, missing session payload, prompt request failure, provider-surfaced errors, and empty/malformed output.
• Refactors makeOpenCodeTextGeneration.runOpenCodeJson to map each failure point to its typed error, then re-wrap as TextGenerationError with a specific detail string and the typed error preserved as cause.
• Replaces getOpenCodePromptErrorMessage with getOpenCodePromptFailure, which extracts both an optional provider error name and a message from the error shape.
• Adds a stricter isOpenCodeTextPart type-guard so malformed response parts are silently dropped rather than processed.
• Expands tests in OpenCodeTextGeneration.test.ts to assert on error.cause structure for each new failure path.

^{Macroscope summarized 5ab986c.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c88c990a-7d70-46e4-a0fe-65425142c1f1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-opencode-text-generation-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Empty output path throws
  • Added null/non-object guards (!!part && typeof part === "object" && "in" checks) to the textPartCount filter, matching the same safety checks used in getOpenCodeTextResponse.

Or push these changes by commenting:

@cursor push c43021fed4

Preview (c43021fed4)

diff --git a/apps/server/src/textGeneration/OpenCodeTextGeneration.ts b/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
--- a/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
+++ b/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
@@ -442,7 +442,13 @@
             ...promptContext,
             responsePartCount: responseParts.length,
             textPartCount: responseParts.filter(
-              (part) => part.type === "text" && typeof part.text === "string",
+              (part) =>
+                !!part &&
+                typeof part === "object" &&
+                "type" in part &&
+                part.type === "text" &&
+                "text" in part &&
+                typeof part.text === "string",
             ).length,
           });
         }

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 6dafd93. Configure here.}

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors internal error handling to use structured typed errors for better debugging context. The external behavior (TextGenerationError) is preserved, and the changes are well-tested and self-contained with no runtime behavior changes.

^{You can customize Macroscope's approvability policy. Learn more.}