[codex] structure desktop preview failures

[juliusmarminge]

Summary

• replace generic preview and Playwright failures with structured Schema error unions
• keep real boundary causes while making validation, state, and automation failures cause-free and directly discriminable
• attach bundle, tab, WebContents, and artifact context where available and remove constructor-only error wrappers
• add focused regressions for validation metadata, preserved causes, artifact safety, and control interruption

Validation

• vp test apps/desktop/src/preview/PlaywrightInjectedRuntime.test.ts apps/desktop/src/preview/Manager.test.ts
• vp check
• vp run typecheck

---

Note

Medium Risk
Large refactor across preview automation, CDP control, and artifact I/O error paths; behavior should be equivalent but any caller that matched on nested cause or generic tags needs to use the new union and type guards.

Overview
Desktop preview and Playwright injection now surface structured Effect Schema tagged errors instead of a single generic wrapper and ad-hoc Error objects with name/detail.

Preview manager: The old PreviewManagerError + automationError / fail() pattern is replaced by a union of specific classes (tab/webview missing, artifact path outside directory, image load, recording conflict, DevTools/debugger conflicts, automation evaluation/selector/target/viewport/timeout/interrupted, etc.). Low-level failures use PreviewOperationError with operation plus optional tabId, webContentsId, and artifactPath, while keeping the real cause only at that boundary. Automation action timelines pull user-facing detail via PreviewOperationError.toTimelineMessage, separate from each error’s structured message. Helpers attempt / attemptPromise / encodeJson now take a PreviewOperationContext instead of a bare operation string.

Playwright runtime: The monolithic PlaywrightInjectedRuntimeError is split into tagged errors (package resolve, bundle read, marker/terminator missing, evaluation, validation, options encode). extractPlaywrightInjectedRuntimeSource is exported and tested for cause-free vs cause-bearing cases.

Tests assert _tag, context fields, and that domain errors are not wrapped in an extra cause.

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

Note

Replace generic preview errors with structured, tagged error classes in desktop preview

• Introduces a family of tagged error classes in Manager.ts (e.g. PreviewOperationError, PreviewAutomationControlInterruptedError, PreviewArtifactImageLoadError) that carry structured metadata like operation, tabId, webContentsId, and artifactPath instead of wrapping generic Error objects.
• Similarly refactors PlaywrightInjectedRuntime.ts to replace a single PlaywrightInjectedRuntimeError with specific typed errors (PlaywrightSourceMarkerNotFoundError, PlaywrightSourceEvaluationError, PlaywrightSourceValidationError, etc.).
• PreviewOperationError.message excludes the underlying cause; the cause is accessible separately via toTimelineMessage.
• Tests in Manager.test.ts and PlaywrightInjectedRuntime.test.ts are updated to assert the new structured error shapes.
• Behavioral Change: all PreviewManager and Playwright runtime failure paths now emit typed errors with specific metadata rather than generic errors, which may affect any existing error handling that inspects error.cause or checks instanceof Error without checking the error name.

^{Macroscope summarized 2431a34.}

[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: ea9c4de1-e579-4176-a827-04ed4ba88679

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/desktop-preview-structured-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: Timeline omits nested failure messages
  • Restored cause-unwrapping logic in finalizeControlAction so that when a PreviewOperationError occurs, the timeline records the underlying error.cause.message instead of the generic wrapper message.

Or push these changes by commenting:

@cursor push 012e32aa35

Preview (012e32aa35)

diff --git a/apps/desktop/src/preview/Manager.ts b/apps/desktop/src/preview/Manager.ts
--- a/apps/desktop/src/preview/Manager.ts
+++ b/apps/desktop/src/preview/Manager.ts
@@ -851,11 +851,13 @@
       } else {
         const error = Option.getOrNull(Cause.findErrorOption(exit.cause));
         const interrupted = isPreviewAutomationControlInterruptedError(error);
+        const underlying =
+          isPreviewOperationError(error) && error.cause instanceof Error ? error.cause : error;
         yield* replaceAction(tabId, {
           ...actionEvent,
           status: interrupted ? "interrupted" : "failed",
           completedAt,
-          error: error instanceof Error ? error.message : String(error),
+          error: underlying instanceof Error ? underlying.message : String(underlying),
         });
       }
       const tabs = yield* SynchronizedRef.get(tabsRef);
@@ -2520,6 +2522,7 @@
 export type PreviewManagerError = typeof PreviewManagerError.Type;
 
 export const isPreviewManagerError = Schema.is(PreviewManagerError);
+export const isPreviewOperationError = Schema.is(PreviewOperationError);
 export const isPreviewAutomationControlInterruptedError = Schema.is(
   PreviewAutomationControlInterruptedError,
 );

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

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling to use structured, typed error classes instead of generic Error objects. The runtime behavior is unchanged; only error construction and message formatting improved. Tests updated accordingly.

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

Dismissing prior approval to re-evaluate 6168586

Dismissing prior approval to re-evaluate 2431a34