[codex] Structure client RPC unavailable errors

[juliusmarminge]

Summary

• replace freeform disconnected RPC messages with environment ID, environment label, and requested method fields
• derive the stable user-facing message from those fields
• use exact catchTags semantics for expected missing-registration cleanup paths
• add focused coverage for disconnected unary RPC context

Validation

• vp test packages/client-runtime/src/rpc/client.test.ts packages/client-runtime/src/connection/registry.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck

Stack

• based on [codex] Structure connection persistence failures #3255, which is based on [codex] Preserve client connection error causes #3242

---

Note

Low Risk
Localized error-shape and Effect catch API changes in client-runtime RPC and registry; no auth or persistence changes.

Overview
EnvironmentRpcUnavailableError no longer carries a freeform message. It now exposes environmentId, environmentLabel, and an optional method, with the user-facing text built from those fields (including the RPC method when unary/stream calls fail).

Disconnected unary and stream-command RPC paths pass the requested method into session resolution so failures are attributable to a specific call. Registry cleanup paths switch from catchTag to catchTags for expected EnvironmentNotRegisteredError handling during start, relay removal, and retry.

Adds a test that a disconnected unary request returns the structured error and expected message.

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

Note

Structure EnvironmentRpcUnavailableError to include environment label and RPC method

• EnvironmentRpcUnavailableError now carries environmentId, environmentLabel, and an optional method field instead of a static message string.
• The error's message getter dynamically formats as "{environmentLabel} is not connected", appending " for RPC method {method}" when a method is present.
• EnvironmentRpc.currentSession, request, and runStream in client.ts now pass the RPC tag through so disconnection errors include the failing method name.
• A new test in client.test.ts asserts the error shape and formatted message for disconnected environments.
• Behavioral Change: callers catching EnvironmentRpcUnavailableError will see a different error shape — message is no longer a schema field and environmentLabel/method are new fields.

^{Macroscope summarized c840111.}

[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: 2ed190f3-f10b-4e68-a7d1-f107fa0c39d3

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/client-rpc-error-context

---

_{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: RPC disconnect breaks transport matching
  • Changed the regex pattern from /\bis not connected\.$/i (end-of-string anchored) to /\bis not connected\b/i (word-boundary only) so it matches both the original message and the new method-suffixed format.

Or push these changes by commenting:

@cursor push dbd63952d5

Preview (dbd63952d5)

diff --git a/packages/client-runtime/src/errors/transport.test.ts b/packages/client-runtime/src/errors/transport.test.ts
--- a/packages/client-runtime/src/errors/transport.test.ts
+++ b/packages/client-runtime/src/errors/transport.test.ts
@@ -27,6 +27,11 @@
       ),
     ).toBe(true);
     expect(isTransportConnectionErrorMessage("Test environment is not connected.")).toBe(true);
+    expect(
+      isTransportConnectionErrorMessage(
+        "Test environment is not connected for RPC method sendMessage.",
+      ),
+    ).toBe(true);
     expect(isTransportConnectionErrorMessage("ClientProtocolError: socket closed")).toBe(true);
   });
 

diff --git a/packages/client-runtime/src/errors/transport.ts b/packages/client-runtime/src/errors/transport.ts
--- a/packages/client-runtime/src/errors/transport.ts
+++ b/packages/client-runtime/src/errors/transport.ts
@@ -3,7 +3,7 @@
   /\bSocketOpenError\b/i,
   /\bSocket is not connected\b/i,
   /Unable to connect to the T3 server WebSocket\./i,
-  /\bis not connected\.$/i,
+  /\bis not connected\b/i,
   /\bdisconnected\.$/i,
   /\bcould not establish a WebSocket connection\.$/i,
   /\bClientProtocolError\b/i,

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

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

[cursor]

RPC disconnect breaks transport matching

Medium Severity

The EnvironmentRpcUnavailableError message now includes the RPC method, which breaks isTransportConnectionErrorMessage's heuristic for identifying transport connection issues. This causes mobile outbox messages to be incorrectly classified as non-retryable, potentially leading to dropped messages.

 

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

[macroscopeapp]

Approvability

Verdict: Needs human review

An unresolved review comment identifies that the new error message format may break isTransportConnectionErrorMessage matching logic, potentially causing mobile outbox messages to be incorrectly classified as non-retryable. This potential bug warrants human review.

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