fix(telemetry): surface AI sidecar and DOMException failure reasons in Sentry (#612)

AI sidecar failures reached Sentry as 'Error: Error': the scrubber type-onlys plain Errors and the tool wrappers threw them from result.error. The bridge now exports toSidecarError(), wrapping the sidecar reason in a SafeError (memory-allocation text classifies as operational, the rest as bug); all 14 wrappers use it, plus the dispatcher crash/stdin/spawn rejection paths and parseStdoutJson. toBgRemovalError from #535 delegates to the shared helper.

On the web side, DOMExceptions report their specific name via err.name, so the NATIVE_ERRORS allowlist dropped the whole family's browser-authored messages. It now carries the full WebIDL DOMException name table; messages still pass through url/path redaction.

Bridge-mocking test files switched to importOriginal passthrough mocks.

packages/ai/src/background-removal-animated.ts

@@ -1,7 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export type GifBgFormat = "webp" | "gif" | "apng";
 
@@ -103,7 +108,7 @@ export async function removeBackgroundAnimated(
     const result = parseStdoutJson(stdout);
     if (!result.success) {
       if (result.error === "canceled") throw new AnimatedRemovalCanceledError();
-      throw new Error((result.error as string) || "Animated background removal failed");
+      throw toSidecarError(result.error, "Animated background removal failed");
     }
     const buffer = await readFile(outputPath);
     return { buffer, format, contentType: FORMAT_CONTENT_TYPE[format], ext: FORMAT_EXT[format] };

packages/ai/src/background-removal.ts

@@ -2,9 +2,13 @@ import { randomUUID } from "node:crypto";
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { isSafeMessageError, SafeError } from "@snapotter/shared";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface RemoveBackgroundOptions {
   model?: string;
@@ -29,18 +33,8 @@ export function isMemoryAllocError(err: unknown): boolean {
   );
 }
 
-/**
- * Wrap a background-removal failure in a SafeError so its message survives the
- * API's Sentry scrubber, which otherwise reduces a plain Error to "Error:
- * Error". The specific sidecar reason is kept as the message (callers and the
- * existing tests rely on it, matching the ai-bridge behavior); an empty reason
- * falls back to a constant. Errors we already author (the bridge's SafeError
- * timeout/OOM) pass through unchanged so their kind is not masked.
- */
 function toBgRemovalError(reason: unknown): Error {
-  if (isSafeMessageError(reason)) return reason;
-  const message = reason instanceof Error ? reason.message : String(reason ?? "");
-  return new SafeError(message || "Background removal failed", { kind: "bug" });
+  return toSidecarError(reason, "Background removal failed");
 }
 
 export async function removeBackground(
@@ -104,7 +98,7 @@ async function runAndParse(
     );
     const result = parseStdoutJson(stdout);
     if (!result.success) {
-      throw new Error(result.error || "Background removal failed");
+      throw toBgRemovalError(result.error || "Background removal failed");
     }
     return readFile(outputPath);
   } catch (err) {

packages/ai/src/bridge.ts

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { context, propagation, SpanStatusCode, trace } from "@opentelemetry/api";
-import { SafeError } from "@snapotter/shared";
+import { isSafeMessageError, SafeError } from "@snapotter/shared";
 import { missingBundleForScript } from "./feature-gate.js";
 import { acquireVenvRead, tryAcquireVenvRead } from "./venv-lock.js";
 
@@ -113,6 +113,24 @@ function pythonExitError(code: number | null, signal: string | null, extracted:
   });
 }
 
+/**
+ * Wrap a sidecar-reported failure (a `{success: false, error}` payload or a
+ * thrown reason) in a SafeError so its message survives the API's Sentry
+ * scrubber, which reduces a plain Error to "Error: Error" (NODE-24, NODE-2N,
+ * NODE-1R). The specific sidecar reason is kept as the message, matching
+ * pythonExitError; an empty reason falls back to the tool's constant message.
+ * Memory-allocation reasons classify as operational (the deployment's
+ * hardware), everything else as a bug. Errors we already author (the bridge's
+ * SafeError timeout/OOM) pass through unchanged so their kind is not masked.
+ */
+export function toSidecarError(reason: unknown, fallback: string): Error {
+  if (isSafeMessageError(reason)) return reason;
+  const message = reason instanceof Error ? reason.message : String(reason ?? "");
+  return new SafeError(message || fallback, {
+    kind: OOM_EXIT_TEXT.test(message) ? "operational" : "bug",
+  });
+}
+
 function extractPythonError(error: unknown): string {
   if (error && typeof error === "object") {
     const pErr = error as {
@@ -245,11 +263,17 @@ export class PythonDispatcher {
     );
   }
 
-  /** Reject and drop the pending requests written to one child generation. */
-  private rejectPendingForGeneration(generation: number, message: string): void {
+  /**
+   * Reject and drop the pending requests written to one child generation.
+   * Always rejects with a SafeError: these rejections reach tool wrappers and
+   * (when the per-request retry cannot save them) Sentry, where a plain Error
+   * is scrubbed to "Error: Error". run()'s crash-retry matches on the exact
+   * message, so callers must keep the two dispatcher-crash messages verbatim.
+   */
+  private rejectPendingForGeneration(generation: number, error: Error): void {
     for (const [id, req] of this.pending.entries()) {
       if (req.generation !== generation) continue;
-      req.reject(new Error(message));
+      req.reject(error);
       this.pending.delete(id);
     }
   }
@@ -270,7 +294,13 @@ export class PythonDispatcher {
           console.error(
             `[bridge] Dispatcher stdin pipe broken (${err.code}), rejecting pending requests`,
           );
-          this.rejectPendingForGeneration(gen, "Python dispatcher stdin closed unexpectedly");
+          this.rejectPendingForGeneration(
+            gen,
+            new SafeError("Python dispatcher stdin closed unexpectedly", {
+              kind: "operational",
+              code: "dispatcher-stdin-closed",
+            }),
+          );
           // An intentional shutdown() ends stdin then SIGTERMs the child,
           // which can surface here as an EPIPE/ERR_STREAM_DESTROYED. That is
           // not a crash: counting it would let repeated legitimate restarts
@@ -387,7 +417,13 @@ export class PythonDispatcher {
           // marks the child stopped before killing it); mirrors "close".
           this.recordCrash();
         }
-        this.rejectPendingForGeneration(gen, extractPythonError(err));
+        this.rejectPendingForGeneration(
+          gen,
+          new SafeError(extractPythonError(err) || "Python dispatcher process error", {
+            kind: "operational",
+            code: err.code ?? "dispatcher-error",
+          }),
+        );
         if (this.child === proc) {
           this.child = null;
           this.childReady = false;
@@ -395,7 +431,13 @@ export class PythonDispatcher {
       });
 
       proc.on("close", (code) => {
-        this.rejectPendingForGeneration(gen, "Python dispatcher exited unexpectedly");
+        this.rejectPendingForGeneration(
+          gen,
+          new SafeError("Python dispatcher exited unexpectedly", {
+            kind: "operational",
+            code: "dispatcher-exit",
+          }),
+        );
         if (code !== 0 && !this.stoppedChildren.has(proc)) {
           this.recordCrash();
         }
@@ -488,7 +530,12 @@ export class PythonDispatcher {
       } catch {
         this.pending.delete(id);
         clearTimeout(timer);
-        rejectPromise(new Error("Python dispatcher stdin closed unexpectedly"));
+        rejectPromise(
+          new SafeError("Python dispatcher stdin closed unexpectedly", {
+            kind: "operational",
+            code: "dispatcher-stdin-closed",
+          }),
+        );
       }
     });
   }
@@ -509,7 +556,12 @@ export class PythonDispatcher {
     // when the dispatcher is down (e.g. right after a model repair). Reject
     // with the same message the dispatcher path surfaces.
     if (missingBundleForScript(scriptName)) {
-      return Promise.reject(new Error("feature_not_installed"));
+      return Promise.reject(
+        new SafeError("feature_not_installed", {
+          kind: "operational",
+          code: "feature_not_installed",
+        }),
+      );
     }
     const scriptPath = resolve(PYTHON_DIR, scriptName);
     const timeout =
@@ -566,7 +618,12 @@ export class PythonDispatcher {
           if (err.code === "ENOENT" && !isFallback) {
             trySpawn("python3", true);
           } else {
-            rejectPromise(new Error(extractPythonError(err)));
+            rejectPromise(
+              new SafeError(extractPythonError(err) || "Failed to start Python process", {
+                kind: "operational",
+                code: err.code ?? "spawn-error",
+              }),
+            );
           }
         });
 
@@ -807,7 +864,11 @@ export function runPythonWithProgress(
 // biome-ignore lint/suspicious/noExplicitAny: matches JSON.parse return type
 export function parseStdoutJson(stdout: string): any {
   const matched = stdout.match(/\{[\s\S]*\}$/);
-  if (!matched) throw new Error("No JSON response from Python script");
+  if (!matched) {
+    // SafeError so the broken-contract reason reaches Sentry instead of the
+    // scrubber's type-only "Error: Error" fallback.
+    throw new SafeError("No JSON response from Python script", { kind: "bug", code: "no-json" });
+  }
   return JSON.parse(matched[0]);
 }
 

packages/ai/src/colorization.ts

@@ -1,7 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface ColorizeOptions {
   intensity?: number;
@@ -34,7 +39,7 @@ export async function colorize(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Colorization failed");
+    throw toSidecarError(result.error, "Colorization failed");
   }
 
   const actualOutputPath = result.output_path || outputPath;

packages/ai/src/face-detection.ts

@@ -2,7 +2,12 @@ import { readFile, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface BlurFacesOptions {
   blurRadius?: number;
@@ -50,7 +55,7 @@ export async function blurFaces(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Face detection failed");
+    throw toSidecarError(result.error, "Face detection failed");
   }
 
   const buffer = await readFile(outputPath);
@@ -79,7 +84,7 @@ export async function detectFaces(
 
     const result = parseStdoutJson(stdout);
     if (!result.success) {
-      throw new Error(result.error || "Face detection failed");
+      throw toSidecarError(result.error, "Face detection failed");
     }
 
     return {

packages/ai/src/face-enhancement.ts

@@ -1,7 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface EnhanceFacesOptions {
   model?: "auto" | "gfpgan" | "codeformer";
@@ -36,7 +41,7 @@ export async function enhanceFaces(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Face enhancement failed");
+    throw toSidecarError(result.error, "Face enhancement failed");
   }
 
   const buffer = await readFile(outputPath);

packages/ai/src/face-landmarks.ts

@@ -2,7 +2,12 @@ import { unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface FaceLandmarkPoint {
   x: number;
@@ -44,7 +49,7 @@ export async function detectFaceLandmarks(
 
     const result = parseStdoutJson(stdout);
     if (!result.success) {
-      throw new Error(result.error || "Face landmark detection failed");
+      throw toSidecarError(result.error, "Face landmark detection failed");
     }
 
     return {

packages/ai/src/inpainting.ts

@@ -1,7 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 /**
  * Inpainting backend. "fast" is the always-available LaMa ONNX path
@@ -35,7 +40,7 @@ export async function inpaint(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Inpainting failed");
+    throw toSidecarError(result.error, "Inpainting failed");
   }
 
   return readFile(outputPath);

packages/ai/src/noise-removal.ts

@@ -1,7 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface NoiseRemovalOptions {
   tier?: string;
@@ -44,7 +49,7 @@ export async function noiseRemoval(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Noise removal failed");
+    throw toSidecarError(result.error, "Noise removal failed");
   }
 
   const actualOutputPath = result.output_path || outputPath;

packages/ai/src/ocr.ts

@@ -1,6 +1,6 @@
 import { dirname, join } from "node:path";
 import sharp from "sharp";
-import type { ProgressCallback } from "./bridge.js";
+import { type ProgressCallback, toSidecarError } from "./bridge.js";
 import { runOcrRuntime } from "./ocr-runtime-dispatcher.js";
 import { runAdaptiveTesseract, type TesseractLanguage } from "./tesseract.js";
 import { preparePdfOcrPages, runTesseractPdf } from "./tesseract-pdf.js";
@@ -71,7 +71,7 @@ function parseAccurateResult(resultValue: unknown, quality: OcrQuality): OcrResu
   }
   const result = resultValue as Record<string, unknown>;
   if (result.success !== true) {
-    throw new Error((result.error as string | undefined) || "OCR failed");
+    throw toSidecarError(result.error, "OCR failed");
   }
 
   const metadataValid =

packages/ai/src/outpainting.ts

@@ -1,7 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface OutpaintOptions {
   extendTop: number;
@@ -39,7 +44,7 @@ export async function outpaint(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Outpainting failed");
+    throw toSidecarError(result.error, "Outpainting failed");
   }
 
   return readFile(outputPath);

packages/ai/src/red-eye-removal.ts

@@ -1,7 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface RedEyeRemovalOptions {
   sensitivity?: number;
@@ -38,7 +43,7 @@ export async function removeRedEye(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Red eye removal failed");
+    throw toSidecarError(result.error, "Red eye removal failed");
   }
 
   const actualOutputPath = result.output_path || outputPath;

packages/ai/src/restoration.ts

@@ -1,7 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import sharp from "sharp";
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 export interface RestorePhotoOptions {
   scratchRemoval?: boolean;
@@ -43,7 +48,7 @@ export async function restorePhoto(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Photo restoration failed");
+    throw toSidecarError(result.error, "Photo restoration failed");
   }
 
   const actualOutputPath = result.output_path || outputPath;

packages/ai/src/transcription.ts

@@ -1,4 +1,9 @@
-import { type ProgressCallback, parseStdoutJson, runPythonWithProgress } from "./bridge.js";
+import {
+  type ProgressCallback,
+  parseStdoutJson,
+  runPythonWithProgress,
+  toSidecarError,
+} from "./bridge.js";
 
 /**
  * A single timed segment of transcribed speech.
@@ -38,7 +43,7 @@ export async function transcribeAudio(
 
   const result = parseStdoutJson(stdout);
   if (result.error) {
-    throw new Error(result.error);
+    throw toSidecarError(result.error, "Transcription failed");
   }
 
   // Map python segment keys {start, end, text} to {startS, endS, text}.

packages/ai/src/upscaling.ts

@@ -6,6 +6,7 @@ import {
   type ProgressCallback,
   parseStdoutJson,
   runPythonWithProgress,
+  toSidecarError,
 } from "./bridge.js";
 
 export interface UpscaleOptions {
@@ -53,7 +54,7 @@ export async function upscale(
 
   const result = parseStdoutJson(stdout);
   if (!result.success) {
-    throw new Error(result.error || "Upscaling failed");
+    throw toSidecarError(result.error, "Upscaling failed");
   }
 
   // Python may write to a different path when the output format changes