[codex] Structure relay environment connector errors

[juliusmarminge]

Summary

• attach user, endpoint, device, operation, and request-stage context to connector failures
• preserve the real JWT/schema verification failure as the invalid-response cause
• replace boolean response validation with constrained diagnostic reasons while keeping one generic service error

Validation

• vp test infra/relay/src/environments/EnvironmentConnector.test.ts --no-cache
• vp check
• vp run typecheck
• vpr typecheck

Overlap audit

• no active service/error-refactor PR overlaps these files; feat(relay): enforce resource limits #2925 is an unrelated broad feature branch

---

Note

Medium Risk
Changes authentication-adjacent connect/mint error shapes and observability; consumers matching on old fields or message strings must update, but wire protocol behavior is largely unchanged aside from richer failures.

Overview
Relay EnvironmentConnector mint/health failures now expose structured tagged errors instead of sparse booleans and raw endpoint strings.

EnvironmentMintRequestFailed, EnvironmentMintResponseInvalid, and EnvironmentMintRequestTimedOut gain userId, optional deviceId, request stage or validation reason, and redacted httpBaseUrl fields (length, protocol, hostname) via getUrlDiagnostics and fromEndpoint helpers. JWT verification paths return discriminated outcomes so invalid responses carry reasons like proof_verification_failed and optional underlying cause; request failures are attributed to stages such as send_request.

Telemetry and logs for managed-endpoint resolution and health warnings record the same redacted URL diagnostics rather than full URLs, reducing credential/path leakage in traces and serialized errors.

Tests assert secret redaction in errors and span attributes and assert structured failure shapes for proof mismatch, HTTP 500, and timeouts.

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

Note

Structure relay environment connector errors with redacted URL diagnostics and typed reasons

• Adds userId, deviceId, stage, and redacted httpBaseUrl diagnostics (input length, protocol, hostname) to EnvironmentMintRequestFailed, EnvironmentMintRequestTimedOut, and EnvironmentMintResponseInvalid error classes in EnvironmentConnector.ts.
• Replaces raw endpoint URLs in span attributes and logs with structured diagnostic fields via new urlDiagnosticSpanAttributes and httpBaseUrlDiagnosticFields helpers.
• Reworks verifyWithEnvironmentKeys, verifyEnvironmentResponse, and verifyEnvironmentHealthResponse to return discriminated results with structured reason codes and optional causes instead of booleans or Option values.
• Adds static fromEndpoint constructors to all three error classes to enforce consistent redaction at construction sites.
• Behavioral Change: error messages now include stage/reason context; span attributes record URL diagnostics rather than raw URLs; callers of the verification utilities receive structured reasons instead of booleans.

^{Macroscope summarized 86ee1b0.}

[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: 4adec5e7-b736-499b-b03a-31f64c5b3316

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/relay-environment-mint-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR adds structured diagnostic fields to error classes and redacts sensitive URL components (credentials, paths, query params) from logs and telemetry. The underlying verification and connection logic remains unchanged - the refactoring improves error messages without altering behavior.

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

Dismissing prior approval to re-evaluate de7427d

Dismissing prior approval to re-evaluate 86ee1b0