[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

Medium Risk
Changes error shape and retry behavior for queued mobile sends when the environment is disconnected; RPC clients must handle the new error fields, but scope is limited to client-runtime and mobile outbox.

Overview
EnvironmentRpcUnavailableError is now a tagged schema error with environmentId, environmentLabel, and optional method instead of a free-form message; the user-facing text is computed from those fields. Unary request and stream runStream pass the RPC tag into session resolution so disconnected calls report which method was attempted. isEnvironmentRpcUnavailableError is exported for callers.

Mobile thread outbox treats this error as retriable alongside existing transport/transient connection failures, with a focused unit test.

Connection error tests are trimmed to redacted URL diagnostics for remote auth fetch/undeclared status (managed-relay mapping tests removed from this file). Durable subscription transport-loss logging drops Cause.pretty in favor of errorTag / reasonCount metadata.

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

Note

Structure client RPC unavailable errors with environment label and method context

• EnvironmentRpcUnavailableError in client.ts gains environmentLabel and optional method fields, with a computed message getter combining both.
• Adds isEnvironmentRpcUnavailableError type guard for reliable error detection by callers.
• currentSession, request, and runStream now pass the method name into EnvironmentRpcUnavailableError so errors identify the specific RPC call that failed.
• shouldRetryThreadOutboxDelivery in thread-outbox-model.ts now returns true for EnvironmentRpcUnavailableError, treating disconnected environments as retryable.
• Transport failure logging in subscribe replaces Cause.pretty(cause) with structured errorTag and reasonCount fields.

^{Macroscope summarized 0c5fe3c.}

[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: 575f52bf-7130-4418-bf75-69243182ca9e

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.}

[macroscopeapp]

Approvability

Verdict: Approved

Straightforward error handling improvement that restructures EnvironmentRpcUnavailableError with explicit fields and adds retry logic for this error type. Changes are self-contained, covered by tests, and low risk.

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

Dismissing prior approval to re-evaluate 7ab7e1b

Dismissing prior approval to re-evaluate 05f1e8c

Dismissing prior approval to re-evaluate 05f1e8c

Dismissing prior approval to re-evaluate 0c5fe3c