[codex] Structure remote pairing input errors

[juliusmarminge]

Summary

• replace raw remote-pairing input errors with distinct schema error classes
• retain URL parsing causes and classify backend URL source
• attach safe host context to missing token/code failures without exposing credentials

Validation

• vp test packages/shared/src/remote.test.ts
• vp check
• vp run typecheck
• vpr typecheck

---

Note

Low Risk
Localized validation refactor in shared remote pairing; user-facing messages are unchanged and success paths are the same, though error instances are no longer plain Error.

Overview
Replaces generic Error throws in resolveRemotePairingTarget and normalizeRemoteBaseUrl with Effect Schema tagged error classes for missing/invalid pairing URLs, backend URLs, tokens, and pairing codes, plus a RemotePairingTargetError union.

Invalid URL parsing now wraps the original TypeError as cause, and backend URL failures record source (direct-host vs hosted-pairing-host). Missing token/code errors include a normalized host (e.g. no credentials from messy host strings). Tests assert the new error types and preserved causes.

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

Note

Replace generic errors with structured tagged error classes in remote pairing input validation

• Introduces five new TaggedErrorClass types in remote.ts: RemoteBackendUrlMissingError, RemoteBackendUrlInvalidError, RemotePairingUrlInvalidError, RemotePairingTokenMissingError, and RemotePairingCodeMissingError.
• RemoteBackendUrlInvalidError carries a source field ('direct-host' | 'hosted-pairing-host') to identify the origin of the invalid input; all error classes with a cause preserve the original TypeError.
• normalizeRemoteBaseUrl and resolveRemotePairingTarget now throw these structured errors instead of generic Error instances, with structured metadata (host, source, cause) attached.
• Behavioral Change: callers catching errors from these functions must now handle tagged error types rather than plain Error objects.

^{Macroscope summarized f32b4ed.}

[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: e928fb49-cba0-42f3-bf1a-6612f76d0842

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/remote-pairing-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: Raw host exposes pairing credentials
  • Moved normalizeRemoteBaseUrl() before the pairing code check so RemotePairingCodeMissingError receives the parsed URL's .host property (hostname+port only) instead of the raw input string, preventing credential leakage.

Or push these changes by commenting:

@cursor push 56371127e7

Preview (56371127e7)

diff --git a/packages/shared/src/remote.ts b/packages/shared/src/remote.ts
--- a/packages/shared/src/remote.ts
+++ b/packages/shared/src/remote.ts
@@ -213,11 +213,10 @@
   if (!host) {
     throw new RemoteBackendUrlMissingError();
   }
+  const normalizedHost = normalizeRemoteBaseUrl(host, "direct-host");
   if (!pairingCode) {
-    throw new RemotePairingCodeMissingError({ host });
+    throw new RemotePairingCodeMissingError({ host: normalizedHost.host });
   }
-
-  const normalizedHost = normalizeRemoteBaseUrl(host, "direct-host");
   return {
     credential: pairingCode,
     httpBaseUrl: toHttpBaseUrl(normalizedHost),

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

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

[macroscopeapp]

Approvability

Verdict: Approved

Refactors error handling to use structured error classes instead of generic Error instances. The error conditions and messages are unchanged; only type information is added. Includes tests for the new error types.

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

Dismissing prior approval to re-evaluate f32b4ed