[codex] Structure Codex app-server request errors

[juliusmarminge]

Summary

• attach method, operation, and true causes to app-server payload and handler errors
• summarize schema failures with issue count, issue kinds, and maximum path depth while retaining the exact SchemaError cause
• classify unexpected no-schema payloads by safe payload kind instead of serializing raw values
• keep decode-failure logs to safe operation, method, and schema summaries without copying causes or raw wire values
• centralize request-error transformations on CodexAppServerRequestError and keep messages stable
• cover decode, encode, notification, handler, identifier, and termination cause chains with focused tests

Validation

• vp test run packages/effect-codex-app-server/src/client.test.ts packages/effect-codex-app-server/src/_internal/shared.test.ts packages/effect-codex-app-server/src/protocol.test.ts apps/server/src/provider/Layers/CodexSessionRuntime.test.ts (26 tests)
• vp check (0 errors; 20 pre-existing warnings)
• vp run typecheck

---

Note

Medium Risk
Touches JSON-RPC error shapes and termination behavior across the Codex client and server runtime; callers that matched on old detail strings or expected a transport error on stream end may need updates, though the change mainly reduces accidental secret leakage in logs.

Overview
Restructures Codex app-server error handling so failures are classified by operation (wire encode/decode, payload decode/encode, handler, transport, identifier generation) instead of ad hoc detail strings.

CodexAppServerRequestError gains method, operation, schema summaries (issueCount, issueKinds, maximumPathDepth), and a retained SchemaError cause; unexpected payloads on methods with no schema are reported via payload kind only. CodexAppServerProtocolParseError and transport errors use the same pattern, with new CodexAppServerIdentifierGenerationError (purpose-tagged UUID failures) and CodexAppServerInputStreamEndedError (clean stdin end, no synthetic cause). normalizeToRequestError is removed in favor of fromAppServerError / static factories.

Protocol and shared layers route decode/encode/handler failures through those factories; decode-failure logs emit safe operation/schema summaries without copying causes or wire bodies. CodexSessionRuntime maps turn/start schema failures via fromSchemaError, tags UUID generation by purpose, and logs full resume errors as cause objects.

Focused tests cover secret non-leakage, handler cause chains, protocol logging, and Effect-based openCodexThread cases.

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

Note

Structure Codex app-server request errors with typed operations, diagnostics, and dedicated error classes

• Replaces free-form detail strings in CodexAppServerProtocolParseError, CodexAppServerTransportError, and CodexAppServerRequestError with typed operation enums and structured schema diagnostics (issue count, kinds, path depth).
• Adds CodexAppServerIdentifierGenerationError (with purpose) and CodexAppServerInputStreamEndedError as dedicated error types, replacing generic transport errors for these cases.
• Updates decodeOptionalPayload, encodeOptionalPayload, runHandler, and protocol wire encode/decode functions in shared.ts and protocol.ts to emit the new structured errors.
• Decode failure logs now include operation, method, and diagnostic fields, and explicitly omit cause and raw payloads to avoid secret leakage.
• Behavioral Change: error messages and shapes across protocol, transport, and request error types are now standardized; any code matching on detail strings or message text will break.

^{Macroscope summarized 306576f.}

[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: fb24ec5a-161a-4ba9-a8ba-619402a1ca42

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/audit-codex-app-server-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactoring of error handling to use structured error types with typed operation fields and diagnostic metadata instead of free-form string details. Changes are mechanical with no business logic impact, limited to error classification and message formatting.

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

Dismissing prior approval to re-evaluate dcb2646

[macroscopeapp]

One convention finding on the new protocol-parse operation discriminator. Otherwise the error refactor aligns well with the conventions: structured attributes, messages derived from those attributes (not from cause), real causes preserved, and the multi-value operation on CodexAppServerRequestError is purely diagnostic.

^{Posted via Macroscope — Effect Service Conventions}

Dismissing prior approval to re-evaluate 5cecba9

Dismissing prior approval to re-evaluate f8c426f

Dismissing prior approval to re-evaluate 798661f

Dismissing prior approval to re-evaluate 7a27805

Dismissing prior approval to re-evaluate 0d26774

Dismissing prior approval to re-evaluate 7821d64

Dismissing prior approval to re-evaluate 306576f