[codex] Structure project and filesystem RPC errors

[juliusmarminge]

Summary

Project search/list, workspace file read/write, and filesystem browse RPC failures previously collapsed rich server-side errors into message strings, often by interpolating an underlying cause. Clients and telemetry could not reliably correlate failures by operation or path, and platform details leaked into user-facing messages.

This change adds rolling-compatible structured diagnostics to the existing RPC error tags. New failures carry the request context, a closed failure classification, relevant normalized/resolved paths, file operations, and the exact underlying cause. Messages are derived from stable request attributes and no longer depend on cause text. Legacy message-only payloads still decode during rolling upgrades.

The server boundary now maps internal workspace error unions into those fields exhaustively. Focused contract and websocket tests cover stable messages, retained causes, structured fields, and legacy decoding.

Stacked on #3274 because it consumes the structured workspace filesystem errors introduced there.

Validation

• vp test packages/contracts/src/project.test.ts packages/contracts/src/filesystem.test.ts apps/server/src/server.test.ts (101 tests)
• vp check
• vp run typecheck

Sensitive-context follow-up\n- project-search RPC errors retain query length rather than the raw query\n- legacy message-only and legacy raw-query payloads continue decoding during rolling upgrades without retaining the query\n- server mappings preserve the exact underlying cause

---

Note

Medium Risk
Changes the RPC error wire format and user-visible messages for workspace operations; clients or telemetry that parsed legacy message strings may need updates, though structured fields improve safe handling.

Overview
Workspace project and filesystem browse RPC failures now return structured error payloads instead of long message strings built from underlying causes.

Contract error types gain typed failure discriminators plus request context (cwd, relativePath, queryLength instead of raw query, paths, operations, etc.). User-facing message strings are derived from that context and no longer echo cause text—so search queries, file contents, and platform details stay out of messages while cause is still attached for debugging. Message-only legacy payloads remain decodable for rolling upgrades.

The websocket layer maps internal workspace error unions into those fields exhaustively and drops the old compatibility string builders. Integration tests assert the new shape, including that sensitive search text never appears on the wire.

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

Note

Structure filesystem and project RPC errors with typed classes and contextual fields

• Introduces typed error classes (ProjectSearchEntriesError, ProjectListEntriesError, ProjectReadFileError, ProjectWriteFileError, FilesystemBrowseError) in project.ts and filesystem.ts with structured fields (cwd, relativePath, failure codes, etc.).
• Error messages are now derived from structured context rather than raw platform details, ensuring sensitive data (e.g., search queries) is never embedded in error strings.
• WS RPC handlers in ws.ts are updated to construct these typed errors using new mapping helpers (projectEntriesFailureContext, filesystemBrowseFailureContext, projectFileFailureContext).
• Legacy message-only error payloads can still be decoded without structured fields, preserving backward compatibility.
• Behavioral Change: all five RPC methods now fail with structured typed errors instead of unstructured string messages.

^{Macroscope summarized c447448.}

[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: 7f92dd0f-63e6-4802-8d00-b81e5a3065f7

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-project-rpc-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: Search failures omit normalizedCwd
  • Added normalizedCwd: error.cwd to the three search-index error branches (WorkspaceSearchIndexCreateFailed, WorkspaceSearchIndexScanTimedOut, WorkspaceSearchIndexSearchFailed) in projectEntriesFailureContext, matching how workspace-root errors already propagate the normalized path.

Or push these changes by commenting:

@cursor push 594471e8fd

Preview (594471e8fd)

diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -155,11 +155,23 @@
         normalizedCwd: error.normalizedWorkspaceRoot,
       };
     case "WorkspaceSearchIndexCreateFailed":
-      return { failure: "search_index_create_failed", detail: error.reason };
+      return {
+        failure: "search_index_create_failed",
+        normalizedCwd: error.cwd,
+        detail: error.reason,
+      };
     case "WorkspaceSearchIndexScanTimedOut":
-      return { failure: "search_index_scan_timed_out", timeout: error.timeout };
+      return {
+        failure: "search_index_scan_timed_out",
+        normalizedCwd: error.cwd,
+        timeout: error.timeout,
+      };
     case "WorkspaceSearchIndexSearchFailed":
-      return { failure: "search_index_search_failed", detail: error.reason };
+      return {
+        failure: "search_index_search_failed",
+        normalizedCwd: error.cwd,
+        detail: error.reason,
+      };
     default:
       return unexpectedCompatibilityError(error);
   }

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

^{Reviewed by Cursor Bugbot for commit 13e6969. Configure here.}

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors RPC error handling to use structured error types instead of string messages, without changing when errors occur or how operations behave. Backward compatibility is preserved for rolling upgrades, and tests cover both new structure and legacy decoding paths.

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

Dismissing prior approval to re-evaluate 7ae0764

Dismissing prior approval to re-evaluate c447448