[codex] Structure web local API failures

[juliusmarminge]

Summary

• replace generic local API failures with structured errors keyed by the unavailable operation
• preserve the exact desktop bridge rejection cause for external URL opens
• retain only safe URL diagnostics (hostname, protocol, and input length), excluding credentials, path/query/fragment payloads, and the raw URL
• cover credential and token redaction in the local API tests

Validation

• vp test apps/web/src/localApi.test.ts
• vp check
• vp run typecheck

Note

Replace generic errors with typed error classes in the web local API

• Introduces three typed error classes in localApi.ts: LocalBackendUnavailableError (with a specific operation name), LocalExternalUrlOpenError (with sanitized URL diagnostics), and LocalApiUnavailableError.
• Browser-facade backend operations (e.g. server.getConfig, shell.openInEditor) now reject with LocalBackendUnavailableError instead of a generic Error.
• shell.openExternal wraps the desktop bridge call and throws LocalExternalUrlOpenError on failure or a false return, including hostname, protocol, and URL length while omitting the raw URL.
• ensureLocalApi throws LocalApiUnavailableError instead of a generic Error('Local API not found').
• Behavioral Change: all callers that previously caught a generic Error must now handle the new tagged error types.

^{Macroscope summarized 70e9b69.}

---

Note

Medium Risk
Callers that matched plain Error messages or instanceof Error for local API failures must handle new tagged types; external URL error paths are security-sensitive but deliberately avoid leaking secrets.

Overview
Replaces generic Error throws in the web local API facade with Effect Schema tagged error classes: LocalBackendUnavailableError (per-operation literal), LocalExternalUrlOpenError (safe hostname/protocol/length + optional cause), and LocalApiUnavailableError from ensureLocalApi.

shell.openExternal on the desktop bridge now wraps rejections and “not opened” outcomes in LocalExternalUrlOpenError using shared getUrlDiagnostics (@t3tools/shared/urlDiagnostics), so errors and messages never carry the raw URL, credentials, or query tokens.

Adds redactDpopRequestTarget in shared DPoP utilities (scheme/host/port/path only) with tests; exports urlDiagnostics from @t3tools/shared. Local API tests assert structured backend-unavailable errors and credential/token redaction for external URL failures.

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

[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: 7fa8ac91-342c-405e-9bde-b9222c914ccd

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/web-local-api-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing plain Error objects with structured, typed error classes. The error conditions and code paths remain unchanged - only the error types and messages are improved. The URL diagnostics utility is explicitly designed to exclude sensitive data like credentials.

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

Dismissing prior approval to re-evaluate f80f32d

Dismissing prior approval to re-evaluate 8998eeb

Dismissing prior approval to re-evaluate 70e9b69

[juliusmarminge]

Summary

• replace generic local API failures with structured errors keyed by the unavailable operation
• preserve the exact desktop bridge rejection cause for external URL opens
• retain only safe URL diagnostics (hostname, protocol, and input length), excluding credentials, path/query/fragment payloads, and the raw URL
• cover credential and token redaction in the local API tests

Validation

• vp test apps/web/src/localApi.test.ts
• vp check
• vp run typecheck

Note

Replace generic errors with typed error classes in the web local API

• Introduces three typed error classes in localApi.ts: LocalBackendUnavailableError (with a specific operation name), LocalExternalUrlOpenError (with sanitized URL diagnostics), and LocalApiUnavailableError.
• Browser-facade backend operations (e.g. server.getConfig, shell.openInEditor) now reject with LocalBackendUnavailableError instead of a generic Error.
• shell.openExternal wraps the desktop bridge call and throws LocalExternalUrlOpenError on failure or a false return, including hostname, protocol, and URL length while omitting the raw URL.
• ensureLocalApi throws LocalApiUnavailableError instead of a generic Error('Local API not found').
• Behavioral Change: all callers that previously caught a generic Error must now handle the new tagged error types.

^{Macroscope summarized 70e9b69.}

---

Note

Medium Risk
Callers that matched plain Error messages or instanceof Error for local API failures must handle new tagged types; external URL error paths are security-sensitive but deliberately avoid leaking secrets.

Overview
Replaces generic Error throws in the web local API facade with Effect Schema tagged error classes: LocalBackendUnavailableError (per-operation literal), LocalExternalUrlOpenError (safe hostname/protocol/length + optional cause), and LocalApiUnavailableError from ensureLocalApi.

shell.openExternal on the desktop bridge now wraps rejections and “not opened” outcomes in LocalExternalUrlOpenError using shared getUrlDiagnostics (@t3tools/shared/urlDiagnostics), so errors and messages never carry the raw URL, credentials, or query tokens.

Adds redactDpopRequestTarget in shared DPoP utilities (scheme/host/port/path only) with tests; exports urlDiagnostics from @t3tools/shared. Local API tests assert structured backend-unavailable errors and credential/token redaction for external URL failures.

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

[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: 7fa8ac91-342c-405e-9bde-b9222c914ccd

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/web-local-api-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing plain Error objects with structured, typed error classes. The error conditions and code paths remain unchanged - only the error types and messages are improved. The URL diagnostics utility is explicitly designed to exclude sensitive data like credentials.

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

Dismissing prior approval to re-evaluate f80f32d

Dismissing prior approval to re-evaluate 8998eeb

Dismissing prior approval to re-evaluate 70e9b69

[juliusmarminge]

Summary

• replace generic local API failures with structured errors keyed by the unavailable operation
• preserve the exact desktop bridge rejection cause for external URL opens
• retain only safe URL diagnostics (hostname, protocol, and input length), excluding credentials, path/query/fragment payloads, and the raw URL
• cover credential and token redaction in the local API tests

Validation

• vp test apps/web/src/localApi.test.ts
• vp check
• vp run typecheck

Note

Replace generic errors with typed error classes in the web local API

• Introduces three typed error classes in localApi.ts: LocalBackendUnavailableError (with a specific operation name), LocalExternalUrlOpenError (with sanitized URL diagnostics), and LocalApiUnavailableError.
• Browser-facade backend operations (e.g. server.getConfig, shell.openInEditor) now reject with LocalBackendUnavailableError instead of a generic Error.
• shell.openExternal wraps the desktop bridge call and throws LocalExternalUrlOpenError on failure or a false return, including hostname, protocol, and URL length while omitting the raw URL.
• ensureLocalApi throws LocalApiUnavailableError instead of a generic Error('Local API not found').
• Behavioral Change: all callers that previously caught a generic Error must now handle the new tagged error types.

^{Macroscope summarized 70e9b69.}

---

Note

Medium Risk
Callers that matched plain Error messages or instanceof Error for local API failures must handle new tagged types; external URL error paths are security-sensitive but deliberately avoid leaking secrets.

Overview
Replaces generic Error throws in the web local API facade with Effect Schema tagged error classes: LocalBackendUnavailableError (per-operation literal), LocalExternalUrlOpenError (safe hostname/protocol/length + optional cause), and LocalApiUnavailableError from ensureLocalApi.

shell.openExternal on the desktop bridge now wraps rejections and “not opened” outcomes in LocalExternalUrlOpenError using shared getUrlDiagnostics (@t3tools/shared/urlDiagnostics), so errors and messages never carry the raw URL, credentials, or query tokens.

Adds redactDpopRequestTarget in shared DPoP utilities (scheme/host/port/path only) with tests; exports urlDiagnostics from @t3tools/shared. Local API tests assert structured backend-unavailable errors and credential/token redaction for external URL failures.

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

[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: 7fa8ac91-342c-405e-9bde-b9222c914ccd

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/web-local-api-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing plain Error objects with structured, typed error classes. The error conditions and code paths remain unchanged - only the error types and messages are improved. The URL diagnostics utility is explicitly designed to exclude sensitive data like credentials.

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

Dismissing prior approval to re-evaluate f80f32d

Dismissing prior approval to re-evaluate 8998eeb

Dismissing prior approval to re-evaluate 70e9b69

[juliusmarminge]

Summary

• replace generic local API failures with structured errors keyed by the unavailable operation
• preserve the exact desktop bridge rejection cause for external URL opens
• retain only safe URL diagnostics (hostname, protocol, and input length), excluding credentials, path/query/fragment payloads, and the raw URL
• cover credential and token redaction in the local API tests

Validation

• vp test apps/web/src/localApi.test.ts
• vp check
• vp run typecheck

Note

Replace generic errors with typed error classes in the web local API

• Introduces three typed error classes in localApi.ts: LocalBackendUnavailableError (with a specific operation name), LocalExternalUrlOpenError (with sanitized URL diagnostics), and LocalApiUnavailableError.
• Browser-facade backend operations (e.g. server.getConfig, shell.openInEditor) now reject with LocalBackendUnavailableError instead of a generic Error.
• shell.openExternal wraps the desktop bridge call and throws LocalExternalUrlOpenError on failure or a false return, including hostname, protocol, and URL length while omitting the raw URL.
• ensureLocalApi throws LocalApiUnavailableError instead of a generic Error('Local API not found').
• Behavioral Change: all callers that previously caught a generic Error must now handle the new tagged error types.

^{Macroscope summarized 70e9b69.}

---

Note

Medium Risk
Callers that matched plain Error messages or instanceof Error for local API failures must handle new tagged types; external URL error paths are security-sensitive but deliberately avoid leaking secrets.

Overview
Replaces generic Error throws in the web local API facade with Effect Schema tagged error classes: LocalBackendUnavailableError (per-operation literal), LocalExternalUrlOpenError (safe hostname/protocol/length + optional cause), and LocalApiUnavailableError from ensureLocalApi.

shell.openExternal on the desktop bridge now wraps rejections and “not opened” outcomes in LocalExternalUrlOpenError using shared getUrlDiagnostics (@t3tools/shared/urlDiagnostics), so errors and messages never carry the raw URL, credentials, or query tokens.

Adds redactDpopRequestTarget in shared DPoP utilities (scheme/host/port/path only) with tests; exports urlDiagnostics from @t3tools/shared. Local API tests assert structured backend-unavailable errors and credential/token redaction for external URL failures.

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

[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: 7fa8ac91-342c-405e-9bde-b9222c914ccd

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/web-local-api-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing plain Error objects with structured, typed error classes. The error conditions and code paths remain unchanged - only the error types and messages are improved. The URL diagnostics utility is explicitly designed to exclude sensitive data like credentials.

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

Dismissing prior approval to re-evaluate f80f32d

Dismissing prior approval to re-evaluate 8998eeb

Dismissing prior approval to re-evaluate 70e9b69

[juliusmarminge]

Summary

• replace generic local API failures with structured errors keyed by the unavailable operation
• preserve the exact desktop bridge rejection cause for external URL opens
• retain only safe URL diagnostics (hostname, protocol, and input length), excluding credentials, path/query/fragment payloads, and the raw URL
• cover credential and token redaction in the local API tests

Validation

• vp test apps/web/src/localApi.test.ts
• vp check
• vp run typecheck

Note

Replace generic errors with typed error classes in the web local API

• Introduces three typed error classes in localApi.ts: LocalBackendUnavailableError (with a specific operation name), LocalExternalUrlOpenError (with sanitized URL diagnostics), and LocalApiUnavailableError.
• Browser-facade backend operations (e.g. server.getConfig, shell.openInEditor) now reject with LocalBackendUnavailableError instead of a generic Error.
• shell.openExternal wraps the desktop bridge call and throws LocalExternalUrlOpenError on failure or a false return, including hostname, protocol, and URL length while omitting the raw URL.
• ensureLocalApi throws LocalApiUnavailableError instead of a generic Error('Local API not found').
• Behavioral Change: all callers that previously caught a generic Error must now handle the new tagged error types.

^{Macroscope summarized 70e9b69.}

---

Note

Medium Risk
Callers that matched plain Error messages or instanceof Error for local API failures must handle new tagged types; external URL error paths are security-sensitive but deliberately avoid leaking secrets.

Overview
Replaces generic Error throws in the web local API facade with Effect Schema tagged error classes: LocalBackendUnavailableError (per-operation literal), LocalExternalUrlOpenError (safe hostname/protocol/length + optional cause), and LocalApiUnavailableError from ensureLocalApi.

shell.openExternal on the desktop bridge now wraps rejections and “not opened” outcomes in LocalExternalUrlOpenError using shared getUrlDiagnostics (@t3tools/shared/urlDiagnostics), so errors and messages never carry the raw URL, credentials, or query tokens.

Adds redactDpopRequestTarget in shared DPoP utilities (scheme/host/port/path only) with tests; exports urlDiagnostics from @t3tools/shared. Local API tests assert structured backend-unavailable errors and credential/token redaction for external URL failures.

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

[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: 7fa8ac91-342c-405e-9bde-b9222c914ccd

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/web-local-api-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing plain Error objects with structured, typed error classes. The error conditions and code paths remain unchanged - only the error types and messages are improved. The URL diagnostics utility is explicitly designed to exclude sensitive data like credentials.

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

Dismissing prior approval to re-evaluate f80f32d

Dismissing prior approval to re-evaluate 8998eeb

Dismissing prior approval to re-evaluate 70e9b69

[juliusmarminge]

Summary

• replace generic local API failures with structured errors keyed by the unavailable operation
• preserve the exact desktop bridge rejection cause for external URL opens
• retain only safe URL diagnostics (hostname, protocol, and input length), excluding credentials, path/query/fragment payloads, and the raw URL
• cover credential and token redaction in the local API tests

Validation

• vp test apps/web/src/localApi.test.ts
• vp check
• vp run typecheck

Note

Replace generic errors with typed error classes in the web local API

• Introduces three typed error classes in localApi.ts: LocalBackendUnavailableError (with a specific operation name), LocalExternalUrlOpenError (with sanitized URL diagnostics), and LocalApiUnavailableError.
• Browser-facade backend operations (e.g. server.getConfig, shell.openInEditor) now reject with LocalBackendUnavailableError instead of a generic Error.
• shell.openExternal wraps the desktop bridge call and throws LocalExternalUrlOpenError on failure or a false return, including hostname, protocol, and URL length while omitting the raw URL.
• ensureLocalApi throws LocalApiUnavailableError instead of a generic Error('Local API not found').
• Behavioral Change: all callers that previously caught a generic Error must now handle the new tagged error types.

^{Macroscope summarized 70e9b69.}

---

Note

Medium Risk
Callers that matched plain Error messages or instanceof Error for local API failures must handle new tagged types; external URL error paths are security-sensitive but deliberately avoid leaking secrets.

Overview
Replaces generic Error throws in the web local API facade with Effect Schema tagged error classes: LocalBackendUnavailableError (per-operation literal), LocalExternalUrlOpenError (safe hostname/protocol/length + optional cause), and LocalApiUnavailableError from ensureLocalApi.

shell.openExternal on the desktop bridge now wraps rejections and “not opened” outcomes in LocalExternalUrlOpenError using shared getUrlDiagnostics (@t3tools/shared/urlDiagnostics), so errors and messages never carry the raw URL, credentials, or query tokens.

Adds redactDpopRequestTarget in shared DPoP utilities (scheme/host/port/path only) with tests; exports urlDiagnostics from @t3tools/shared. Local API tests assert structured backend-unavailable errors and credential/token redaction for external URL failures.

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

[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: 7fa8ac91-342c-405e-9bde-b9222c914ccd

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/web-local-api-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing plain Error objects with structured, typed error classes. The error conditions and code paths remain unchanged - only the error types and messages are improved. The URL diagnostics utility is explicitly designed to exclude sensitive data like credentials.

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

Dismissing prior approval to re-evaluate f80f32d

Dismissing prior approval to re-evaluate 8998eeb

Dismissing prior approval to re-evaluate 70e9b69

[juliusmarminge]

Summary

• replace generic local API failures with structured errors keyed by the unavailable operation
• preserve the exact desktop bridge rejection cause for external URL opens
• retain only safe URL diagnostics (hostname, protocol, and input length), excluding credentials, path/query/fragment payloads, and the raw URL
• cover credential and token redaction in the local API tests

Validation

• vp test apps/web/src/localApi.test.ts
• vp check
• vp run typecheck

Note

Replace generic errors with typed error classes in the web local API

• Introduces three typed error classes in localApi.ts: LocalBackendUnavailableError (with a specific operation name), LocalExternalUrlOpenError (with sanitized URL diagnostics), and LocalApiUnavailableError.
• Browser-facade backend operations (e.g. server.getConfig, shell.openInEditor) now reject with LocalBackendUnavailableError instead of a generic Error.
• shell.openExternal wraps the desktop bridge call and throws LocalExternalUrlOpenError on failure or a false return, including hostname, protocol, and URL length while omitting the raw URL.
• ensureLocalApi throws LocalApiUnavailableError instead of a generic Error('Local API not found').
• Behavioral Change: all callers that previously caught a generic Error must now handle the new tagged error types.

^{Macroscope summarized 70e9b69.}

---

Note

Medium Risk
Callers that matched plain Error messages or instanceof Error for local API failures must handle new tagged types; external URL error paths are security-sensitive but deliberately avoid leaking secrets.

Overview
Replaces generic Error throws in the web local API facade with Effect Schema tagged error classes: LocalBackendUnavailableError (per-operation literal), LocalExternalUrlOpenError (safe hostname/protocol/length + optional cause), and LocalApiUnavailableError from ensureLocalApi.

shell.openExternal on the desktop bridge now wraps rejections and “not opened” outcomes in LocalExternalUrlOpenError using shared getUrlDiagnostics (@t3tools/shared/urlDiagnostics), so errors and messages never carry the raw URL, credentials, or query tokens.

Adds redactDpopRequestTarget in shared DPoP utilities (scheme/host/port/path only) with tests; exports urlDiagnostics from @t3tools/shared. Local API tests assert structured backend-unavailable errors and credential/token redaction for external URL failures.

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

[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: 7fa8ac91-342c-405e-9bde-b9222c914ccd

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/web-local-api-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing plain Error objects with structured, typed error classes. The error conditions and code paths remain unchanged - only the error types and messages are improved. The URL diagnostics utility is explicitly designed to exclude sensitive data like credentials.

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

Dismissing prior approval to re-evaluate f80f32d

Dismissing prior approval to re-evaluate 8998eeb

Dismissing prior approval to re-evaluate 70e9b69

[juliusmarminge]

Summary

• replace generic local API failures with structured errors keyed by the unavailable operation
• preserve the exact desktop bridge rejection cause for external URL opens
• retain only safe URL diagnostics (hostname, protocol, and input length), excluding credentials, path/query/fragment payloads, and the raw URL
• cover credential and token redaction in the local API tests

Validation

• vp test apps/web/src/localApi.test.ts
• vp check
• vp run typecheck

Note

Replace generic errors with typed error classes in the web local API

• Introduces three typed error classes in localApi.ts: LocalBackendUnavailableError (with a specific operation name), LocalExternalUrlOpenError (with sanitized URL diagnostics), and LocalApiUnavailableError.
• Browser-facade backend operations (e.g. server.getConfig, shell.openInEditor) now reject with LocalBackendUnavailableError instead of a generic Error.
• shell.openExternal wraps the desktop bridge call and throws LocalExternalUrlOpenError on failure or a false return, including hostname, protocol, and URL length while omitting the raw URL.
• ensureLocalApi throws LocalApiUnavailableError instead of a generic Error('Local API not found').
• Behavioral Change: all callers that previously caught a generic Error must now handle the new tagged error types.

^{Macroscope summarized 70e9b69.}

---

Note

Medium Risk
Callers that matched plain Error messages or instanceof Error for local API failures must handle new tagged types; external URL error paths are security-sensitive but deliberately avoid leaking secrets.

Overview
Replaces generic Error throws in the web local API facade with Effect Schema tagged error classes: LocalBackendUnavailableError (per-operation literal), LocalExternalUrlOpenError (safe hostname/protocol/length + optional cause), and LocalApiUnavailableError from ensureLocalApi.

shell.openExternal on the desktop bridge now wraps rejections and “not opened” outcomes in LocalExternalUrlOpenError using shared getUrlDiagnostics (@t3tools/shared/urlDiagnostics), so errors and messages never carry the raw URL, credentials, or query tokens.

Adds redactDpopRequestTarget in shared DPoP utilities (scheme/host/port/path only) with tests; exports urlDiagnostics from @t3tools/shared. Local API tests assert structured backend-unavailable errors and credential/token redaction for external URL failures.

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

[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: 7fa8ac91-342c-405e-9bde-b9222c914ccd

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/web-local-api-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling by replacing plain Error objects with structured, typed error classes. The error conditions and code paths remain unchanged - only the error types and messages are improved. The URL diagnostics utility is explicitly designed to exclude sensitive data like credentials.

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

Dismissing prior approval to re-evaluate f80f32d

Dismissing prior approval to re-evaluate 8998eeb

Dismissing prior approval to re-evaluate 70e9b69