fix(web-shared): hydrate FatalError/RetryableError and Error subclasses in o11y (vercel#1942)

* fix(web-shared): hydrate FatalError/RetryableError and Error subclasses in o11y

The web o11y reviver set was missing entries for the recently-added
serialization types (FatalError, RetryableError, the built-in Error
subclasses, AggregateError, DOMException), causing devalue.unflatten to
throw "Unknown type X" and the UI to surface "Failed to load resource
details" whenever a step or run failed with one of these error types.

Adds the missing revivers to getWebRevivers() and a regression test that
round-trips real values through the runtime's dehydrateStepError back
through the web reviver set.

* fix(web-shared): address review feedback on error revivers

- Pass `cause` through ErrorOptions to the subclass constructor instead of
  assigning afterwards, matching `getCommonRevivers` in core. This gives
  the resulting `cause` property the same engine-set, non-enumerable
  semantics as a freshly thrown Error in the consumer realm.
- Guard `RetryableError.retryAfter` against missing/undefined values from
  older runtime payloads — without it, `new Date(undefined)` produces an
  Invalid Date rather than the property being absent. Add a defensive
  test that drives the reviver directly with a payload missing the field.

Author: TooTallNate

.changeset/web-shared-error-family-revivers.md

@@ -0,0 +1,5 @@
+---
+"@workflow/web-shared": patch
+---
+
+Fix "Unknown type FatalError" / "Failed to load resource details" in the o11y UI by adding the missing reviver entries (`FatalError`, `RetryableError`, the built-in `Error` subclasses, `AggregateError`, and `DOMException`) to `getWebRevivers()` so it stays in sync with the runtime reducer set.

packages/web-shared/package.json

@@ -71,6 +71,7 @@
     "@types/node": "catalog:",
     "@types/react": "19",
     "@types/react-dom": "19",
+    "@workflow/errors": "workspace:*",
     "@workflow/tsconfig": "workspace:*",
     "ai": "catalog:",
     "typescript": "catalog:",

packages/web-shared/src/lib/hydration.ts

@@ -58,12 +58,60 @@ function base64ToArrayBuffer(base64: string): ArrayBuffer {
 // Web revivers (browser-safe, no Buffer dependency)
 // ---------------------------------------------------------------------------
 
+/**
+ * Build a reviver for one of the built-in `Error` subclasses (e.g.
+ * `TypeError`, `RangeError`). The constructor for the named subclass is
+ * resolved off `globalThis` at call time so the produced instance has the
+ * correct prototype chain in the consumer realm. Falls back to a generic
+ * `Error` (with `name` set) if the global isn't available, which keeps the
+ * o11y UI rendering even on exotic browsers.
+ *
+ * `cause` is passed through `ErrorOptions` to the constructor when present,
+ * matching `getCommonRevivers` in `@workflow/core` so the resulting `cause`
+ * property has the same semantics (non-enumerable, set by the engine) as a
+ * freshly thrown Error in the consumer realm. The `'cause' in value` check
+ * preserves the distinction between "no cause" and "cause is undefined".
+ */
+function makeWebErrorSubclassReviver(
+  name:
+    | 'EvalError'
+    | 'RangeError'
+    | 'ReferenceError'
+    | 'SyntaxError'
+    | 'TypeError'
+    | 'URIError'
+) {
+  return (value: { message: string; stack?: string; cause?: unknown }) => {
+    const opts = 'cause' in value ? { cause: value.cause } : undefined;
+    const Ctor = (globalThis as Record<string, any>)[name] as
+      | ErrorConstructor
+      | undefined;
+    let error: Error;
+    if (typeof Ctor === 'function') {
+      error = new Ctor(value.message, opts);
+    } else {
+      // Fallback path: no built-in subclass available (exotic env). Construct
+      // a plain Error with the right `name` and copy `cause` manually since
+      // the base Error constructor is what we actually called.
+      error = Object.assign(new Error(value.message, opts), { name });
+    }
+    if (value.stack !== undefined) error.stack = value.stack;
+    return error;
+  };
+}
+
 /**
  * Get the web-specific revivers for hydrating serialized data.
  *
  * Uses `atob()` for base64 decoding (no Node.js Buffer dependency).
  * All types are revived as real instances (Date, Map, Set, URL,
  * URLSearchParams, Headers, Error, etc.).
+ *
+ * NOTE: this set must mirror the keys in `SerializableSpecial` (see
+ * `@workflow/core/serialization/types`). Any reducer key added on the
+ * serialization side that isn't covered here will cause `devalue.unflatten`
+ * to throw `Unknown type X`, which `hydrateResourceIO` swallows and
+ * surfaces as a "Failed to load resource details" banner in the o11y UI.
  */
 export function getWebRevivers(): Revivers {
   function reviveArrayBuffer(value: string): ArrayBuffer {
@@ -83,10 +131,93 @@ export function getWebRevivers(): Revivers {
     BigUint64Array: (value: string) =>
       new BigUint64Array(reviveArrayBuffer(value)),
     Date: (value) => new Date(value),
+
+    // Error family. The reducer side (see
+    // `packages/core/src/serialization/reducers/common.ts`) emits a tagged
+    // entry for each built-in Error subclass plus the workflow-specific
+    // `FatalError` / `RetryableError` and `AggregateError`. Without
+    // matching revivers here, `devalue.unflatten` throws "Unknown type X"
+    // — which surfaces in the web o11y UI as "Failed to load resource
+    // details: Unknown type FatalError".
     Error: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts);
+      error.name = value.name;
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    EvalError: makeWebErrorSubclassReviver('EvalError'),
+    RangeError: makeWebErrorSubclassReviver('RangeError'),
+    ReferenceError: makeWebErrorSubclassReviver('ReferenceError'),
+    SyntaxError: makeWebErrorSubclassReviver('SyntaxError'),
+    TypeError: makeWebErrorSubclassReviver('TypeError'),
+    URIError: makeWebErrorSubclassReviver('URIError'),
+    AggregateError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const Ctor = (
+        globalThis as { AggregateError?: AggregateErrorConstructor }
+      ).AggregateError;
+      const error =
+        typeof Ctor === 'function'
+          ? new Ctor(value.errors, value.message, opts)
+          : Object.assign(new Error(value.message, opts), {
+              name: 'AggregateError',
+              errors: value.errors,
+            });
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    // `FatalError` and `RetryableError` are not built-in browser globals,
+    // so we can't resolve a constructor from globalThis. The web o11y UI
+    // doesn't need `instanceof FatalError` to pass (no user code runs
+    // here) — it just needs `name`, `message`, `stack`, and any extra
+    // enumerable fields to render. Construct a plain `Error` with `name`
+    // set; ObjectInspector reads `constructor.name` for the displayed
+    // class label, but we don't have the real class, so we emit a tagged
+    // Error whose `name` field carries the class identity. This matches
+    // how the existing base `Error` reviver presents unknown subclasses.
+    FatalError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts);
+      error.name = 'FatalError';
+      if (value.stack !== undefined) error.stack = value.stack;
+      return error;
+    },
+    RetryableError: (value) => {
+      const opts = 'cause' in value ? { cause: value.cause } : undefined;
+      const error = new Error(value.message, opts) as Error & {
+        retryAfter?: Date;
+      };
+      error.name = 'RetryableError';
+      if (value.stack !== undefined) error.stack = value.stack;
+      // `retryAfter` is serialized as an epoch ms number (see the runtime
+      // RetryableError reducer for the rationale around realm-safety).
+      // Rehydrate as a Date so o11y consumers can render it directly.
+      // Guard against payloads from older runtime versions that predate
+      // the field — without this check, `new Date(undefined)` would
+      // produce an Invalid Date rather than omitting the property.
+      if (value.retryAfter != null) {
+        error.retryAfter = new Date(value.retryAfter);
+      }
+      return error;
+    },
+    DOMException: (value) => {
+      // Modern browsers and Node 18+ expose `DOMException` on globalThis.
+      // `AbortController.abort()` with no argument synthesizes one as the
+      // signal's reason, so this is a common payload for any aborted step.
+      const G = globalThis as { DOMException?: typeof DOMException };
+      if (typeof G.DOMException === 'function') {
+        const e = new G.DOMException(value.message, value.name);
+        if (value.stack !== undefined) e.stack = value.stack;
+        if ('cause' in value) (e as { cause?: unknown }).cause = value.cause;
+        return e;
+      }
       const error = new Error(value.message);
       error.name = value.name;
-      error.stack = value.stack;
+      if (value.stack !== undefined) error.stack = value.stack;
+      if ('cause' in value) {
+        (error as Error & { cause?: unknown }).cause = value.cause;
+      }
       return error;
     },
     Float32Array: (value: string) => new Float32Array(reviveArrayBuffer(value)),

packages/web-shared/test/hydration.test.ts

@@ -0,0 +1,123 @@
+import { dehydrateStepError } from '@workflow/core/serialization';
+import { hydrateData } from '@workflow/core/serialization-format';
+import { FatalError, RetryableError } from '@workflow/errors';
+import { describe, expect, it } from 'vitest';
+import { getWebRevivers } from '../src/lib/hydration.js';
+
+/**
+ * The web reviver set must mirror every key in `SerializableSpecial` (see
+ * `packages/core/src/serialization/types.ts`). When the runtime reducer set
+ * adds a new tagged type — historically `FatalError`, `RetryableError`,
+ * the built-in `Error` subclasses, `DOMException`, etc. — the web set must
+ * grow in lockstep. Otherwise `devalue.unflatten` throws `"Unknown type X"`,
+ * which `hydrateResourceIO` swallows and surfaces as a "Failed to load
+ * resource details" banner in the o11y UI.
+ *
+ * These tests round-trip real values through the runtime's
+ * `dehydrateStepError` (the production code path that produces the wire
+ * bytes for `step_failed.error` etc.) and then through the web reviver
+ * set, so they catch divergence on either side.
+ */
+
+const REVIVERS = getWebRevivers();
+
+/** Run a real value through the production wire path with no encryption. */
+async function roundTrip<T>(value: unknown): Promise<T> {
+  const wire = await dehydrateStepError(value, 'run_test', undefined);
+  return hydrateData(wire, REVIVERS) as T;
+}
+
+describe('getWebRevivers — error family', () => {
+  it('hydrates a base Error', async () => {
+    const original = new Error('boom', { cause: 'because' });
+    const revived = await roundTrip<Error & { cause?: unknown }>(original);
+    expect(revived).toBeInstanceOf(Error);
+    expect(revived.name).toBe('Error');
+    expect(revived.message).toBe('boom');
+    expect(revived.cause).toBe('because');
+  });
+
+  // biome-ignore format: visual alignment
+  const subclasses = [
+    ['EvalError',      EvalError],
+    ['RangeError',     RangeError],
+    ['ReferenceError', ReferenceError],
+    ['SyntaxError',    SyntaxError],
+    ['TypeError',      TypeError],
+    ['URIError',       URIError],
+  ] as const;
+
+  it.each(subclasses)('hydrates %s as a real instance', async (name, Ctor) => {
+    const revived = await roundTrip<Error>(new Ctor('boom'));
+    expect(revived).toBeInstanceOf(Ctor);
+    expect(revived.name).toBe(name);
+    expect(revived.message).toBe('boom');
+  });
+
+  it('hydrates an AggregateError with its `errors` array intact', async () => {
+    const original = new AggregateError(
+      [new Error('a'), new Error('b')],
+      'all failed'
+    );
+    const revived = await roundTrip<AggregateError>(original);
+    expect(revived).toBeInstanceOf(AggregateError);
+    expect(revived.message).toBe('all failed');
+    expect(revived.errors).toHaveLength(2);
+    expect((revived.errors[0] as Error).message).toBe('a');
+    expect((revived.errors[1] as Error).message).toBe('b');
+  });
+
+  it('hydrates a DOMException with name preserved', async () => {
+    // `DOMException` is the value seen by web o11y when
+    // `AbortController.abort()` is called with no argument and that
+    // signal.reason crosses a step boundary — the same code path that
+    // surfaced "Unknown type FatalError" before the symmetric web revivers
+    // landed.
+    const revived = await roundTrip<Error>(
+      new DOMException('aborted', 'AbortError')
+    );
+    expect(revived.message).toBe('aborted');
+    expect(revived.name).toBe('AbortError');
+  });
+
+  it('hydrates a FatalError with name="FatalError"', async () => {
+    // Regression test for the screenshot bug: "Unknown type FatalError"
+    // surfaced from devalue.unflatten when the symmetric web reviver was
+    // missing. Round-trips a real `FatalError` through the runtime wire
+    // path so any divergence between the reducer and reviver is caught.
+    const revived = await roundTrip<Error>(new FatalError('cannot retry'));
+    expect(revived).toBeInstanceOf(Error);
+    expect(revived.name).toBe('FatalError');
+    expect(revived.message).toBe('cannot retry');
+  });
+
+  it('hydrates a RetryableError with retryAfter as a Date', async () => {
+    const retryAt = new Date('2025-01-01T00:00:00.000Z');
+    const revived = await roundTrip<Error & { retryAfter: Date }>(
+      new RetryableError('try again', { retryAfter: retryAt })
+    );
+    expect(revived.name).toBe('RetryableError');
+    expect(revived.message).toBe('try again');
+    // `retryAfter` is wire-encoded as an epoch ms number for realm-safety
+    // (see the runtime RetryableError reducer); the web reviver must
+    // rehydrate it back into a Date.
+    expect(revived.retryAfter).toBeInstanceOf(Date);
+    expect(revived.retryAfter.toISOString()).toBe(retryAt.toISOString());
+  });
+
+  it('omits retryAfter when missing from the payload (older runtime)', () => {
+    // Defensive path: a payload produced by an older runtime that predates
+    // the `retryAfter` field would be missing it. The reviver must not
+    // produce `new Date(undefined)` (an Invalid Date) — the field should
+    // simply be absent from the resulting Error.
+    const retryableReviver = (REVIVERS as Record<string, (v: any) => unknown>)
+      .RetryableError;
+    const revived = retryableReviver({
+      message: 'try again',
+      stack: 'RetryableError: try again',
+    }) as Error & { retryAfter?: Date };
+    expect(revived.name).toBe('RetryableError');
+    expect(revived.message).toBe('try again');
+    expect(revived.retryAfter).toBeUndefined();
+  });
+});