@peers-app/peers-ui 0.26.5 → 0.27.0

package/src/hooks/use-rows.test.tsx

@@ -0,0 +1,196 @@
+import type { IHostSubscribeOptions } from "@peers-app/peers-sdk";
+import { act, render, renderHook, screen, waitFor } from "@testing-library/react";
+import { type IRowsSource, useRows } from "./use-rows";
+
+interface IRow {
+  id: string;
+}
+
+/** A table whose reads are answered by the test, one at a time. */
+function fakeTable(answer: (filter: unknown) => IRow[] | Promise<IRow[]>) {
+  const listeners = new Set<{ handler: () => void; options?: IHostSubscribeOptions }>();
+  const reads: unknown[] = [];
+  const table: IRowsSource<IRow> = {
+    list: jest.fn(async (filter) => {
+      reads.push(filter);
+      return answer(filter);
+    }),
+    dataChanged: {
+      subscribe: (handler, options) => {
+        const listener = { handler: () => handler({}), options };
+        listeners.add(listener);
+        return { unsubscribe: () => listeners.delete(listener) };
+      },
+    },
+  };
+  return {
+    table,
+    reads,
+    listeners,
+    change: () => {
+      for (const listener of listeners) listener.handler();
+    },
+    reconnect: () => {
+      for (const listener of listeners) listener.options?.onReconnect?.();
+    },
+  };
+}
+
+function Rows({ table, filter }: { table: IRowsSource<IRow>; filter?: Partial<IRow> }) {
+  const { rows, loading, error } = useRows(table, filter);
+  return (
+    <div>
+      <span data-testid="rows">{rows.map((row) => row.id).join(",")}</span>
+      <span data-testid="loading">{String(loading)}</span>
+      <span data-testid="error">{error?.message ?? ""}</span>
+    </div>
+  );
+}
+
+const text = (id: string) => screen.getByTestId(id).textContent;
+
+describe("useRows", () => {
+  test("reads on mount and again when the table changes", async () => {
+    let rows = [{ id: "a" }];
+    const fake = fakeTable(() => rows);
+    render(<Rows table={fake.table} />);
+    expect(text("loading")).toBe("true");
+    await waitFor(() => expect(text("rows")).toBe("a"));
+    expect(text("loading")).toBe("false");
+
+    rows = [{ id: "a" }, { id: "b" }];
+    act(() => fake.change());
+    await waitFor(() => expect(text("rows")).toBe("a,b"));
+  });
+
+  test("changes during a read cause one more read, not one per change", async () => {
+    let release: (() => void) | undefined;
+    let n = 0;
+    const fake = fakeTable(
+      () =>
+        new Promise<IRow[]>((resolve) => {
+          const id = String(++n);
+          release = () => resolve([{ id }]);
+        }),
+    );
+    render(<Rows table={fake.table} />);
+    await waitFor(() => expect(fake.reads).toHaveLength(1));
+    act(() => {
+      fake.change();
+      fake.change();
+      fake.change();
+    });
+    await act(async () => release?.());
+    await waitFor(() => expect(fake.reads).toHaveLength(2));
+    await act(async () => release?.());
+    await waitFor(() => expect(text("rows")).toBe("2"));
+    expect(fake.reads).toHaveLength(2);
+  });
+
+  test("reads again after a reconnect", async () => {
+    let rows = [{ id: "a" }];
+    const fake = fakeTable(() => rows);
+    render(<Rows table={fake.table} />);
+    await waitFor(() => expect(text("rows")).toBe("a"));
+    rows = [{ id: "missed" }];
+    act(() => fake.reconnect());
+    await waitFor(() => expect(text("rows")).toBe("missed"));
+  });
+
+  test("reports a failed read and keeps the last rows", async () => {
+    let fail = false;
+    const fake = fakeTable(() => {
+      if (fail) throw new Error("host is down");
+      return [{ id: "a" }];
+    });
+    render(<Rows table={fake.table} />);
+    await waitFor(() => expect(text("rows")).toBe("a"));
+    fail = true;
+    act(() => fake.change());
+    await waitFor(() => expect(text("error")).toBe("host is down"));
+    expect(text("rows")).toBe("a");
+    fail = false;
+    act(() => fake.change());
+    await waitFor(() => expect(text("error")).toBe(""));
+  });
+
+  test("reads again when the filter changes, and unsubscribes on unmount", async () => {
+    const fake = fakeTable((filter) => [{ id: JSON.stringify(filter) }]);
+    const { rerender, unmount } = render(<Rows table={fake.table} filter={{ id: "x" }} />);
+    await waitFor(() => expect(text("rows")).toBe('{"id":"x"}'));
+    // An equal filter in a new object doesn't read again.
+    rerender(<Rows table={fake.table} filter={{ id: "x" }} />);
+    rerender(<Rows table={fake.table} filter={{ id: "y" }} />);
+    await waitFor(() => expect(text("rows")).toBe('{"id":"y"}'));
+    expect(fake.reads).toEqual([{ id: "x" }, { id: "y" }]);
+    expect(fake.listeners.size).toBe(1);
+    unmount();
+    expect(fake.listeners.size).toBe(0);
+  });
+
+  test("reads again once an asynchronous subscription is live", async () => {
+    let rows = [{ id: "before" }];
+    const fake = fakeTable(() => rows);
+    let release!: (live: boolean) => void;
+    const ready = new Promise<boolean>((resolve) => {
+      release = resolve;
+    });
+    const subscribe = fake.table.dataChanged.subscribe;
+    fake.table.dataChanged.subscribe = (handler, options) => ({
+      ...subscribe(handler, options),
+      ready,
+    });
+    render(<Rows table={fake.table} />);
+    await waitFor(() => expect(text("rows")).toBe("before"));
+    // No notification can be delivered while the remote subscription is still attaching.
+    rows = [{ id: "during setup" }];
+    await act(async () => release(true));
+    await waitFor(() => expect(text("rows")).toBe("during setup"));
+  });
+
+  test("a synchronous list failure can be retried", async () => {
+    const fake = fakeTable(() => [{ id: "recovered" }]);
+    const list = fake.table.list;
+    fake.table.list = jest.fn(() => {
+      throw new Error("offline");
+    });
+    render(<Rows table={fake.table} />);
+    await waitFor(() => expect(text("error")).toBe("offline"));
+    fake.table.list = list;
+    act(() => fake.change());
+    await waitFor(() => expect(text("rows")).toBe("recovered"));
+  });
+
+  test("reload retries a failed subscription", async () => {
+    const fake = fakeTable(() => [{ id: "recovered" }]);
+    const subscribe = fake.table.dataChanged.subscribe;
+    fake.table.dataChanged.subscribe = () => {
+      throw new Error("subscription unavailable");
+    };
+    const { result } = renderHook(() => useRows(fake.table));
+    await waitFor(() => expect(result.current.error?.message).toBe("subscription unavailable"));
+    fake.table.dataChanged.subscribe = subscribe;
+    await act(async () => result.current.reload());
+    expect(result.current.rows).toEqual([{ id: "recovered" }]);
+    expect(result.current.error).toBeUndefined();
+    expect(fake.listeners.size).toBe(1);
+  });
+
+  test("reload resolves once the rows are current", async () => {
+    let rows = [{ id: "a" }];
+    const fake = fakeTable(() => rows);
+    let reload: (() => Promise<void>) | undefined;
+    function Reloading() {
+      const result = useRows(fake.table);
+      reload = result.reload;
+      return <span data-testid="rows">{result.rows.map((row) => row.id).join(",")}</span>;
+    }
+    render(<Reloading />);
+    await waitFor(() => expect(text("rows")).toBe("a"));
+    rows = [{ id: "b" }];
+    await act(async () => {
+      await reload?.();
+    });
+    expect(text("rows")).toBe("b");
+  });
+});

package/src/hooks/use-rows.ts

@@ -0,0 +1,120 @@
+import type {
+  DataFilter,
+  IDataQueryParams,
+  IHostSubscribeOptions,
+  ISubscriptionResult,
+} from "@peers-app/peers-sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** A table `useRows` can read: a `hostContract` table, or anything with the same two members. */
+export interface IRowsSource<T extends Record<string, any>> {
+  /** Rows matching `filter`, with paging and sorting options. */
+  list(filter?: DataFilter<T>, options?: IDataQueryParams<T>): Promise<T[]>;
+  /**
+   * Changes to the rows. Optional `ready` acknowledges remote attachment; `onReconnect` runs
+   * once a replacement subscription is live, when changes may have been missed.
+   */
+  readonly dataChanged: {
+    subscribe(
+      handler: (event: unknown) => void,
+      options?: IHostSubscribeOptions,
+    ): ISubscriptionResult & { readonly ready?: Promise<boolean> };
+  };
+}
+
+/** What {@link useRows} returns. */
+export interface IUseRowsResult<T> {
+  /** The latest rows; empty until the first read. */
+  rows: T[];
+  /** True until a read settles after mounting or after the query changed. */
+  loading: boolean;
+  /** Why the latest read failed; cleared by the next one that succeeds. */
+  error: Error | undefined;
+  /** Read again now. Resolves when the rows are current. */
+  reload(): Promise<void>;
+}
+
+/**
+ * Rows from a contract table, kept current: read on mount, and read again whenever the table
+ * changes, once an asynchronous subscription is live, after a reconnect, or when `filter` or
+ * `options` change (compared as JSON). Changes
+ * that arrive during a read cause one more read, not one per change.
+ *
+ * ```tsx
+ * const { rows: headlines, error } = useRows(news.tables.Headlines, {}, { pageSize: 100 });
+ * ```
+ *
+ * @param table - A table from a `hostContract` client. Keep it stable (make the client once, at
+ *   module scope, as `hostContract` does): a new table reads and subscribes again.
+ * @param filter - Which rows (all when omitted).
+ * @param options - Paging and sorting.
+ */
+export function useRows<T extends Record<string, any>>(
+  table: IRowsSource<T>,
+  filter?: DataFilter<T>,
+  options?: IDataQueryParams<T>,
+): IUseRowsResult<T> {
+  const key = JSON.stringify([filter ?? {}, options ?? {}]);
+  const query = useRef({ filter, options });
+  query.current = { filter, options };
+  const [state, setState] = useState<{ rows: T[]; loading: boolean; error?: Error }>({
+    rows: [],
+    loading: true,
+  });
+  const reloadRef = useRef<() => Promise<void>>(async () => undefined);
+
+  // `key` stands for filter and options, which the reads take from `query`.
+  useEffect(() => {
+    let cancelled = false;
+    let again = false;
+    let reading: Promise<void> | undefined;
+    let subscription: ReturnType<IRowsSource<T>["dataChanged"]["subscribe"]> | undefined;
+    setState((previous) => (previous.loading ? previous : { ...previous, loading: true }));
+
+    const read = (): Promise<void> => {
+      again = true;
+      reading ??= Promise.resolve().then(async () => {
+        try {
+          while (again && !cancelled) {
+            again = false;
+            try {
+              if (!subscription) {
+                subscription = table.dataChanged.subscribe(readAgain, { onReconnect: readAgain });
+                // Read again after remote attachment, covering changes missed during setup
+                // without delaying the initial read's connection timeout.
+                void subscription.ready?.then((live) => {
+                  if (live && !cancelled) readAgain();
+                });
+              }
+              const rows = await table.list(query.current.filter, query.current.options);
+              if (!cancelled) {
+                setState({ rows: Array.isArray(rows) ? rows : [], loading: false });
+              }
+            } catch (cause) {
+              if (!cancelled) {
+                const error = cause instanceof Error ? cause : new Error(String(cause));
+                setState((previous) => ({ rows: previous.rows, loading: false, error }));
+              }
+            }
+          }
+        } finally {
+          reading = undefined;
+        }
+      });
+      return reading;
+    };
+    const readAgain = () => {
+      void read();
+    };
+
+    reloadRef.current = read;
+    readAgain();
+    return () => {
+      cancelled = true;
+      subscription?.unsubscribe();
+    };
+  }, [table, key]);
+
+  const reload = useCallback(() => reloadRef.current(), []);
+  return { rows: state.rows, loading: state.loading, error: state.error, reload };
+}

package/src/hooks/use-subscription.ts

@@ -0,0 +1,24 @@
+import type { ReadonlyObservable } from "@peers-app/peers-sdk";
+import { useEffect } from "react";
+
+/**
+ * Use this to register a handler for an observable in a functional component.
+ * The handler is called immediately (unless `doNotCallOnChangeDuringSetup`) and whenever the
+ * observable changes.
+ * @param subscribable The observable to subscribe to
+ * @param onChange The function to call with the new value when the observable changes
+ * @param doNotCallOnChangeDuringSetup Skip the immediate call.
+ */
+export function useSubscription<T>(
+  subscribable: ReadonlyObservable<T>,
+  onChange: (value: T) => void,
+  doNotCallOnChangeDuringSetup?: boolean,
+): void {
+  useEffect(() => {
+    if (!doNotCallOnChangeDuringSetup) {
+      onChange(subscribable());
+    }
+    const subscription = subscribable.subscribe(() => onChange(subscribable()));
+    return () => subscription.dispose();
+  }, [subscribable, onChange, doNotCallOnChangeDuringSetup]);
+}

package/src/hooks/use-tool.test.tsx

@@ -0,0 +1,225 @@
+import { act, renderHook } from "@testing-library/react";
+import { useTool } from "./use-tool";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("useTool", () => {
+  test("tracks a run from pending to its result", async () => {
+    const answer = deferred<{ count: number }>();
+    const tool = jest.fn((_input?: { feed?: string }) => answer.promise);
+    const { result } = renderHook(() => useTool(tool));
+    expect(result.current.pending).toBe(false);
+
+    let running!: Promise<{ count: number } | undefined>;
+    act(() => {
+      running = result.current.run({ feed: "bbc" });
+    });
+    expect(result.current.pending).toBe(true);
+    expect(tool).toHaveBeenCalledWith({ feed: "bbc" });
+
+    await act(async () => answer.resolve({ count: 3 }));
+    await expect(running).resolves.toEqual({ count: 3 });
+    expect(result.current).toMatchObject({ pending: false, result: { count: 3 } });
+    expect(result.current.error).toBeUndefined();
+
+    const typeChecks = () => {
+      // @ts-expect-error the input is the tool's
+      void result.current.run({ feed: 1 });
+      const count: number | undefined = result.current.result?.count;
+      void count;
+    };
+    void typeChecks;
+  });
+
+  test("a failed run sets error and resolves undefined instead of throwing", async () => {
+    const onError = jest.fn();
+    const { result } = renderHook(() =>
+      useTool(
+        async () => {
+          throw "offline";
+        },
+        { onError },
+      ),
+    );
+    let outcome: unknown = "unset";
+    await act(async () => {
+      outcome = await result.current.run();
+    });
+    expect(outcome).toBeUndefined();
+    expect(result.current.error?.message).toBe("offline");
+    expect(result.current.pending).toBe(false);
+    expect(onError).toHaveBeenCalledWith(expect.any(Error));
+  });
+
+  test("a new run clears the last error and result", async () => {
+    let fail = true;
+    const { result } = renderHook(() =>
+      useTool(async () => {
+        if (fail) throw new Error("nope");
+        return "ok";
+      }),
+    );
+    await act(async () => {
+      await result.current.run();
+    });
+    expect(result.current.error).toBeDefined();
+    fail = false;
+    const next = deferred<void>();
+    act(() => {
+      void result.current.run().then(() => next.resolve());
+    });
+    expect(result.current.error).toBeUndefined();
+    expect(result.current.pending).toBe(true);
+    await act(async () => next.promise);
+    expect(result.current.result).toBe("ok");
+  });
+
+  test("overlapping runs: the state follows the latest, each run resolves its own result", async () => {
+    const slow = deferred<string>();
+    const fast = deferred<string>();
+    const answers = [slow, fast];
+    const onSuccess = jest.fn();
+    const { result } = renderHook(() =>
+      useTool(() => (answers.shift() as ReturnType<typeof deferred<string>>).promise, {
+        onSuccess,
+      }),
+    );
+    let first!: Promise<string | undefined>;
+    let second!: Promise<string | undefined>;
+    act(() => {
+      first = result.current.run();
+      second = result.current.run();
+    });
+    await act(async () => fast.resolve("fast"));
+    await expect(second).resolves.toBe("fast");
+    expect(result.current).toMatchObject({ pending: false, result: "fast" });
+    await act(async () => slow.resolve("slow"));
+    await expect(first).resolves.toBe("slow");
+    expect(result.current.result).toBe("fast");
+    expect(onSuccess.mock.calls.map(([value]) => value)).toEqual(["fast", "slow"]);
+  });
+
+  test("reset clears state but lets the pending call and callback finish", async () => {
+    const answer = deferred<string>();
+    const onSuccess = jest.fn();
+    const { result } = renderHook(() => useTool(() => answer.promise, { onSuccess }));
+    act(() => {
+      void result.current.run();
+    });
+    act(() => result.current.reset());
+    expect(result.current.pending).toBe(false);
+    await act(async () => answer.resolve("late"));
+    expect(result.current.result).toBeUndefined();
+    expect(onSuccess).toHaveBeenCalledWith("late");
+  });
+
+  test("run is stable and calls the latest function and callbacks", async () => {
+    const onSuccess = jest.fn();
+    const { result, rerender } = renderHook(
+      ({ label }: { label: string }) =>
+        useTool(async () => label, { onSuccess: (value) => onSuccess(label, value) }),
+      { initialProps: { label: "first" } },
+    );
+    const run = result.current.run;
+    rerender({ label: "second" });
+    expect(result.current.run).toBe(run);
+    await act(async () => {
+      await run();
+    });
+    expect(result.current.result).toBe("second");
+    expect(onSuccess).toHaveBeenCalledWith("second", "second");
+  });
+
+  test("nothing updates after unmount", async () => {
+    const answer = deferred<string>();
+    const onSuccess = jest.fn();
+    const errors = jest.spyOn(console, "error").mockImplementation(() => {});
+    const { result, unmount } = renderHook(() => useTool(() => answer.promise, { onSuccess }));
+    let running!: Promise<string | undefined>;
+    act(() => {
+      running = result.current.run();
+    });
+    unmount();
+    answer.resolve("done");
+    await expect(running).resolves.toBe("done");
+    expect(onSuccess).not.toHaveBeenCalled();
+    expect(errors).not.toHaveBeenCalled();
+    errors.mockRestore();
+  });
+
+  test("callback failures do not change the call's outcome or reject run", async () => {
+    const errors = jest.spyOn(console, "error").mockImplementation(() => {});
+    const onError = jest.fn(() => {
+      throw new Error("error callback failed");
+    });
+    const { result, rerender } = renderHook(
+      ({ fail }: { fail: boolean }) =>
+        useTool(
+          async () => {
+            if (fail) throw new Error("tool failed");
+            return "saved";
+          },
+          {
+            onSuccess: () => {
+              throw new Error("success callback failed");
+            },
+            onError,
+          },
+        ),
+      { initialProps: { fail: false } },
+    );
+    await act(async () => {
+      await expect(result.current.run()).resolves.toBe("saved");
+    });
+    expect(result.current.result).toBe("saved");
+    expect(result.current.error).toBeUndefined();
+    expect(onError).not.toHaveBeenCalled();
+    rerender({ fail: true });
+    await act(async () => {
+      await expect(result.current.run()).resolves.toBeUndefined();
+    });
+    expect(result.current.error?.message).toBe("tool failed");
+    expect(errors).toHaveBeenCalledTimes(2);
+    errors.mockRestore();
+  });
+
+  test("observes rejected async callbacks and unprintable rejection values", async () => {
+    const errors = jest.spyOn(console, "error").mockImplementation(() => {});
+    const { result, rerender } = renderHook(
+      ({ fail }: { fail: boolean }) =>
+        useTool(
+          async () => {
+            if (fail) throw Object.create(null);
+            return "ok";
+          },
+          {
+            onSuccess: async () => {
+              throw new Error("async success callback");
+            },
+            onError: async () => {
+              throw new Error("async error callback");
+            },
+          },
+        ),
+      { initialProps: { fail: false } },
+    );
+    await act(async () => {
+      await expect(result.current.run()).resolves.toBe("ok");
+    });
+    rerender({ fail: true });
+    await act(async () => {
+      await expect(result.current.run()).resolves.toBeUndefined();
+    });
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(errors).toHaveBeenCalledTimes(2);
+    errors.mockRestore();
+  });
+});

package/src/hooks/use-tool.ts

@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** A call {@link useTool} can run: a contract tool, a table write, or any async function. */
+export type UseToolCall = (...args: any[]) => Promise<unknown>;
+
+/**
+ * Callbacks for {@link useTool}. The latest ones passed are used. Callback failures are
+ * logged; they do not change the call's result or error. Async callbacks are not awaited.
+ */
+export interface IUseToolOptions<T extends UseToolCall> {
+  /** After a run succeeds, with its result and arguments. Not called after unmount. */
+  onSuccess?: (result: Awaited<ReturnType<T>>, ...args: Parameters<T>) => void;
+  /** After a run fails, with its error and arguments. Not called after unmount. */
+  onError?: (error: Error, ...args: Parameters<T>) => void;
+}
+
+/** What {@link useTool} returns. */
+export interface IUseToolResult<T extends UseToolCall> {
+  /** Run the call. Resolves to its result, or `undefined` when it fails; it never rejects. */
+  run: (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>> | undefined>;
+  /** True while the latest run is in flight. */
+  pending: boolean;
+  /** Why the latest run failed. Cleared when a run starts. */
+  error: Error | undefined;
+  /** The latest run's result. Cleared when a run starts. */
+  result: Awaited<ReturnType<T>> | undefined;
+  /** Clear state and ignore pending state updates, without cancelling calls or their callbacks. */
+  reset: () => void;
+}
+
+interface IToolState<R> {
+  pending: boolean;
+  error?: Error;
+  result?: R;
+}
+
+/**
+ * Run a tool from a component and track it: `pending` while it runs, then `result` or `error`.
+ *
+ * ```tsx
+ * const refresh = useTool(news.tools.refresh);
+ * <button disabled={refresh.pending} onClick={() => refresh.run()}>Refresh</button>
+ * {refresh.error && <div>Couldn't refresh.</div>}
+ * ```
+ *
+ * Typed from the call, so `run` takes the tool's input and `result` is its output. It also
+ * takes table writes (`useTool(news.tables.Feeds.save)`) or any async function. `run` keeps
+ * the same identity across renders and calls the latest function passed. When runs overlap,
+ * the state follows the latest one. Nothing updates after unmount.
+ *
+ * @param call - The tool or async function to run.
+ * @param options - `onSuccess` and `onError` callbacks.
+ */
+export function useTool<T extends UseToolCall>(
+  call: T,
+  options: IUseToolOptions<T> = {},
+): IUseToolResult<T> {
+  type Result = Awaited<ReturnType<T>>;
+  const latest = useRef({ call, options });
+  latest.current = { call, options };
+  const runs = useRef(0);
+  const mounted = useRef(true);
+  const [state, setState] = useState<IToolState<Result>>({ pending: false });
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const run = useCallback(async (...args: Parameters<T>): Promise<Result | undefined> => {
+    const id = ++runs.current;
+    if (mounted.current) setState({ pending: true });
+    try {
+      const result = (await latest.current.call(...args)) as Result;
+      if (mounted.current) {
+        if (id === runs.current) setState({ pending: false, result });
+        notify(() => latest.current.options.onSuccess?.(result, ...args));
+      }
+      return result;
+    } catch (cause) {
+      const error = toolError(cause);
+      if (mounted.current) {
+        if (id === runs.current) setState({ pending: false, error });
+        notify(() => latest.current.options.onError?.(error, ...args));
+      }
+      return undefined;
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    runs.current++;
+    if (mounted.current) setState({ pending: false });
+  }, []);
+
+  return { run, reset, pending: state.pending, error: state.error, result: state.result };
+}
+
+function notify(callback: () => void): void {
+  const failed = (cause: unknown) => console.error("useTool callback failed", cause);
+  try {
+    void Promise.resolve(callback()).catch(failed);
+  } catch (cause) {
+    failed(cause);
+  }
+}
+
+function toolError(cause: unknown): Error {
+  try {
+    if (cause instanceof Error) return cause;
+    return new Error(String(cause));
+  } catch {
+    return new Error("Tool call failed");
+  }
+}