@cursor/july 0.1.1

package/src/internal/cursor-relay-core.ts

@@ -0,0 +1,444 @@
+/**
+ * Shared engine for the Cursor pull relays (`--cursor-events` for GitHub SCM
+ * events, and the automatic Slack relay for `cursorAccount` channels). Both
+ * long-poll a per-principal Cursor backend stream with a durable client-owned
+ * offset and a heartbeat registration; only the subscribe/poll paths, the
+ * registration body/response, and the per-event dispatch differ. Those vary
+ * as data or closures on a {@link RelayAdapter}, so this engine is written
+ * once and tested through each provider's relay.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const OFFSET_SNAPSHOT_VERSION = 1 as const;
+const DEFAULT_POLL_WAIT_MS = 25_000;
+const DEFAULT_POLL_LIMIT = 100;
+const DEFAULT_REGISTER_INTERVAL_MS = 5 * 60 * 1000;
+const CONSUMER_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+const DEFAULT_IDLE_POLL_DELAY_MS = 250;
+const MIN_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+const AUTH_FAILURE_BACKOFF_MS = 60_000;
+
+interface OffsetSnapshot {
+  version: typeof OFFSET_SNAPSHOT_VERSION;
+  offset: string;
+  updatedAt: string;
+}
+
+/** Durable offset snapshot under `<stateDir>/offset.json`. */
+export class RelayOffsetStore {
+  constructor(private readonly stateDir: string) {}
+
+  private get filePath(): string {
+    return join(this.stateDir, "offset.json");
+  }
+
+  async load(): Promise<string | undefined> {
+    try {
+      const raw = await readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(raw) as Partial<OffsetSnapshot>;
+      if (
+        parsed.version === OFFSET_SNAPSHOT_VERSION &&
+        typeof parsed.offset === "string"
+      ) {
+        return parsed.offset;
+      }
+      return undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async save(offset: string): Promise<void> {
+    await mkdir(this.stateDir, { recursive: true });
+    const snapshot: OffsetSnapshot = {
+      version: OFFSET_SNAPSHOT_VERSION,
+      offset,
+      updatedAt: new Date().toISOString(),
+    };
+    // Write-then-rename so a crash mid-write never corrupts the snapshot.
+    const tmpPath = `${this.filePath}.tmp`;
+    await writeFile(tmpPath, JSON.stringify(snapshot, null, 2), "utf8");
+    await rename(tmpPath, this.filePath);
+  }
+}
+
+/** Compare stream offsets (`<ms>-<seq>`). */
+export function compareStreamOffsets(a: string, b: string): number {
+  const [aMs, aSeq] = splitOffset(a);
+  const [bMs, bSeq] = splitOffset(b);
+  if (aMs !== bMs) return aMs < bMs ? -1 : 1;
+  if (aSeq !== bSeq) return aSeq < bSeq ? -1 : 1;
+  return 0;
+}
+
+function splitOffset(offset: string): [number, number] {
+  const dash = offset.indexOf("-");
+  const ms = Number(dash === -1 ? offset : offset.slice(0, dash));
+  const seq = dash === -1 ? 0 : Number(offset.slice(dash + 1));
+  return [Number.isFinite(ms) ? ms : 0, Number.isFinite(seq) ? seq : 0];
+}
+
+export function describeRelayError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+interface PollResponse<TEvent> {
+  events: TEvent[];
+  nextOffset: string;
+  gapDetected: boolean;
+}
+
+/**
+ * Provider-specific behavior for {@link CursorRelayCore}. Everything else —
+ * consumer-id persistence, registration-gated lifecycle, heartbeat, the
+ * anchor/poll/dedupe/offset loop, and backoff — is shared.
+ */
+export interface RelayAdapter<TEvent extends { offset: string }> {
+  /** Log fragment, e.g. `cursor-events` → `[agent-serve] cursor-events: …`. */
+  readonly logPrefix: string;
+  /** Subscription registration path, e.g. `/v0/scm-events/subscriptions`. */
+  readonly subscribePath: string;
+  /** Base long-poll path, e.g. `/v0/scm-events`. */
+  readonly pollPath: string;
+  /** The registration request body for this consumer id. */
+  buildRegistrationBody(consumerId: string): unknown;
+  /**
+   * Apply the (ok) registration response: update the accepted-scope filter
+   * and return the human-readable outcome lines to log. The core logs them
+   * only when they change, so returning stable lines keeps the heartbeat
+   * quiet.
+   */
+  applyRegistrationResponse(json: unknown): string[];
+  /**
+   * Whether an event from the shared principal stream belongs to THIS
+   * consumer (repo/agent + kind filter). Non-matching events still advance
+   * the offset but are not dispatched.
+   */
+  shouldDispatch(event: TEvent): boolean;
+  /** Handle one matching event. Failures are logged, not retried. */
+  dispatch(event: TEvent): Promise<void>;
+}
+
+export interface CursorRelayCoreOptions<TEvent extends { offset: string }> {
+  baseUrl: string;
+  apiKey: string;
+  stateDir: string;
+  adapter: RelayAdapter<TEvent>;
+  logger: (line: string) => void;
+  /** Test seam. Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Test seam: override long-poll wait (default 25s). */
+  pollWaitMs?: number;
+}
+
+export class CursorRelayCore<TEvent extends { offset: string }> {
+  private running = false;
+  private abort: AbortController | undefined;
+  private registerTimer: NodeJS.Timeout | undefined;
+  private consumePromise: Promise<void> | undefined;
+  private readonly offsetStore: RelayOffsetStore;
+  private readonly fetchImpl: typeof fetch;
+  private consumerId = "";
+  /** undefined until the first registration, so a clean first success logs. */
+  private lastRegistrationLog: string | undefined;
+
+  constructor(private readonly options: CursorRelayCoreOptions<TEvent>) {
+    this.offsetStore = new RelayOffsetStore(options.stateDir);
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.abort = new AbortController();
+    this.consumePromise = this.run();
+  }
+
+  /**
+   * Registration-gated lifecycle: no anchor and no consumption until one
+   * registration succeeded — anchoring "now" while unsubscribed would
+   * silently miss every delivery in between.
+   */
+  private async run(): Promise<void> {
+    await this.resolveConsumerId();
+    const registered = await this.registerUntilSuccess();
+    if (!registered) return;
+    this.registerTimer = setInterval(() => {
+      void this.registerOnce();
+    }, DEFAULT_REGISTER_INTERVAL_MS);
+    this.registerTimer.unref?.();
+    await this.consumeLoop();
+  }
+
+  /**
+   * Durable consumer identity for this state root (memoized), so this host's
+   * registrations never clobber a sibling consumer's on the same key and
+   * survive restarts. Public so callers can bind transports with it before
+   * `start()` (the Slack relay proxies outbound calls under this id).
+   */
+  async resolveConsumerId(): Promise<string> {
+    if (this.consumerId !== "") {
+      return this.consumerId;
+    }
+    const filePath = join(this.options.stateDir, "consumer-id");
+    try {
+      const existing = (await readFile(filePath, "utf8")).trim();
+      if (CONSUMER_ID_PATTERN.test(existing)) {
+        this.consumerId = existing;
+        return existing;
+      }
+    } catch {
+      // Missing or unreadable: mint below.
+    }
+    const minted = randomUUID();
+    try {
+      await mkdir(this.options.stateDir, { recursive: true });
+      const tmpPath = `${filePath}.tmp`;
+      await writeFile(tmpPath, `${minted}\n`, "utf8");
+      await rename(tmpPath, filePath);
+    } catch (error) {
+      this.log(
+        `could not persist consumer id (${describeRelayError(error)}); using an ephemeral one for this run`
+      );
+    }
+    this.consumerId = minted;
+    return minted;
+  }
+
+  async stop(): Promise<void> {
+    if (!this.running) return;
+    this.running = false;
+    if (this.registerTimer !== undefined) {
+      clearInterval(this.registerTimer);
+      this.registerTimer = undefined;
+    }
+    this.abort?.abort();
+    // Bounded wait: server close must never hang on a poll that ignores the
+    // abort (offsets are saved as events are processed, so cutting the loop
+    // loose loses nothing).
+    await Promise.race([
+      this.consumePromise?.catch(() => {}),
+      new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, 2_000);
+        timer.unref?.();
+      }),
+    ]);
+  }
+
+  private log(line: string): void {
+    this.options.logger(
+      `[agent-serve] ${this.options.adapter.logPrefix}: ${line}`
+    );
+  }
+
+  private async request(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<Response> {
+    const url = `${this.options.baseUrl.replace(/\/+$/, "")}${path}`;
+    return this.fetchImpl(url, {
+      method,
+      headers: {
+        authorization: `Bearer ${this.options.apiKey}`,
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      ...(this.abort === undefined ? {} : { signal: this.abort.signal }),
+    });
+  }
+
+  /** Retry registration with backoff until it succeeds or the relay stops. */
+  private async registerUntilSuccess(): Promise<boolean> {
+    let backoffMs = MIN_BACKOFF_MS;
+    while (this.running) {
+      if (await this.registerOnce()) {
+        return true;
+      }
+      await this.sleep(backoffMs);
+      backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+    }
+    return false;
+  }
+
+  /**
+   * Register (or refresh) via the adapter. Returns true when the server
+   * accepted the registration (individual scopes may still have failed
+   * validation — the adapter logs those).
+   */
+  private async registerOnce(): Promise<boolean> {
+    if (!this.running) return false;
+    try {
+      const response = await this.request(
+        "PUT",
+        this.options.adapter.subscribePath,
+        this.options.adapter.buildRegistrationBody(this.consumerId)
+      );
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        this.logRegistrationOutcome([
+          `registration failed: ${response.status} ${text.slice(0, 300)}`,
+        ]);
+        return false;
+      }
+      const json = (await response.json()) as unknown;
+      this.logRegistrationOutcome(
+        this.options.adapter.applyRegistrationResponse(json)
+      );
+      return true;
+    } catch (error) {
+      if (this.isAbort(error)) return false;
+      this.logRegistrationOutcome([
+        `registration error: ${describeRelayError(error)}`,
+      ]);
+      return false;
+    }
+  }
+
+  /** Log registration outcome lines only when they change (heartbeat-quiet). */
+  private logRegistrationOutcome(lines: string[]): void {
+    const key = lines.join("\n");
+    if (key === this.lastRegistrationLog) return;
+    this.lastRegistrationLog = key;
+    for (const line of lines) {
+      this.log(line);
+    }
+  }
+
+  private async consumeLoop(): Promise<void> {
+    let backoffMs = MIN_BACKOFF_MS;
+    let offset = await this.offsetStore.load();
+    let announcedGap = false;
+
+    while (this.running) {
+      try {
+        if (offset === undefined) {
+          // First run: anchor at "now" so the agent does not replay (and
+          // react to) the retained backlog of old events.
+          const anchorResponse = await this.request(
+            "GET",
+            `${this.options.adapter.pollPath}?after=%24&limit=1`
+          );
+          if (!anchorResponse.ok) {
+            backoffMs = await this.backoffAfterHttpFailure(
+              anchorResponse,
+              backoffMs
+            );
+            continue;
+          }
+          const anchor = (await anchorResponse.json()) as PollResponse<TEvent>;
+          offset = anchor.nextOffset;
+          await this.offsetStore.save(offset);
+          this.log(`anchored at offset "${offset}"`);
+          backoffMs = MIN_BACKOFF_MS;
+          continue;
+        }
+
+        const query = new URLSearchParams({
+          after: offset,
+          limit: String(DEFAULT_POLL_LIMIT),
+          waitMs: String(this.options.pollWaitMs ?? DEFAULT_POLL_WAIT_MS),
+        });
+        const response = await this.request(
+          "GET",
+          `${this.options.adapter.pollPath}?${query.toString()}`
+        );
+        if (!response.ok) {
+          backoffMs = await this.backoffAfterHttpFailure(response, backoffMs);
+          continue;
+        }
+        const poll = (await response.json()) as PollResponse<TEvent>;
+        backoffMs = MIN_BACKOFF_MS;
+
+        if (poll.gapDetected && !announcedGap) {
+          announcedGap = true;
+          this.log(
+            "gap detected: events may have been trimmed while this host was offline; resuming from the oldest retained event"
+          );
+        }
+        if (poll.events.length > 0) {
+          announcedGap = false;
+        }
+
+        for (const event of poll.events) {
+          if (!this.running) break;
+          // At-least-once dedupe: never re-dispatch at or before the last
+          // processed offset (reads are exclusive-after, so this only fires
+          // on replay after a crash between dispatch and save).
+          if (compareStreamOffsets(event.offset, offset) <= 0) continue;
+          if (this.options.adapter.shouldDispatch(event)) {
+            try {
+              await this.options.adapter.dispatch(event);
+            } catch (error) {
+              this.log(
+                `dispatch failed at offset ${event.offset}: ${describeRelayError(error)}`
+              );
+            }
+          }
+          offset = event.offset;
+        }
+        if (
+          poll.nextOffset !== "" &&
+          compareStreamOffsets(poll.nextOffset, offset) > 0
+        ) {
+          offset = poll.nextOffset;
+        }
+        if (poll.events.length > 0) {
+          await this.offsetStore.save(offset);
+        } else {
+          await this.sleep(DEFAULT_IDLE_POLL_DELAY_MS);
+        }
+      } catch (error) {
+        if (this.isAbort(error)) return;
+        this.log(`poll error: ${describeRelayError(error)}`);
+        await this.sleep(backoffMs);
+        backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+      }
+    }
+  }
+
+  /** Log the failure, sleep, and return the backoff for the NEXT failure. */
+  private async backoffAfterHttpFailure(
+    response: Response,
+    backoffMs: number
+  ): Promise<number> {
+    const isAuthFailure = response.status === 401 || response.status === 403;
+    const sleepMs = isAuthFailure ? AUTH_FAILURE_BACKOFF_MS : backoffMs;
+    const text = await response.text().catch(() => "");
+    this.log(
+      `poll failed: ${response.status} ${text.slice(0, 300)} (retrying in ${Math.round(sleepMs / 1000)}s)`
+    );
+    await this.sleep(sleepMs);
+    return isAuthFailure
+      ? AUTH_FAILURE_BACKOFF_MS
+      : Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      const signal = this.abort?.signal;
+      if (signal?.aborted === true) {
+        resolve();
+        return;
+      }
+      const finish = (): void => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", finish);
+        resolve();
+      };
+      const timer = setTimeout(finish, ms);
+      timer.unref?.();
+      signal?.addEventListener("abort", finish, { once: true });
+    });
+  }
+
+  private isAbort(error: unknown): boolean {
+    return (
+      !this.running || (error instanceof Error && error.name === "AbortError")
+    );
+  }
+}

package/src/internal/cursor-slack-relay.ts

@@ -0,0 +1,242 @@
+/**
+ * Pulls `/v0/slack-events` into agent-serve: register the mounted
+ * cursor-account Slack agents (name + icon) with the Cursor backend, then
+ * long-poll routed events with a durable offset under
+ * `<stateDir>/offset.json` and dispatch each to the agent it addresses.
+ * Outbound Slack Web API calls are proxied through `POST /v0/slack-events/api`
+ * via a per-agent {@link SlackApiTransport} binding.
+ *
+ * Same lifecycle rules as the SCM relay (`cursor-event-relay.ts`):
+ * registration-gated consumption, heartbeat re-registration, durable
+ * consumer id, at-least-once dispatch with client-owned offsets.
+ */
+
+import type { CursorSlackEnvelope } from "../channels/slack/cursor-account.js";
+import {
+  CursorRelayCore,
+  describeRelayError,
+  type RelayAdapter,
+} from "./cursor-relay-core.js";
+
+/** One agent this host registers over the Cursor Slack connection. */
+export interface CursorSlackAgentRegistration {
+  name: string;
+  iconUrl?: string;
+  iconEmoji?: string;
+}
+
+interface RegistrationResponse {
+  workspaces?: Array<{
+    slackTeamId: string;
+    isSubscribed: boolean;
+    detail?: string;
+  }>;
+  agents?: Array<{ name: string; isSubscribed: boolean; detail?: string }>;
+  expiresAt?: string;
+}
+
+/** One relayed event as delivered to {@link CursorSlackRelayOptions.dispatch}. */
+export type CursorSlackRelayEvent = CursorSlackEnvelope & { offset: string };
+
+export interface CursorSlackRelayOptions {
+  baseUrl: string;
+  apiKey: string;
+  agents: readonly CursorSlackAgentRegistration[];
+  stateDir: string;
+  /**
+   * Called for each event addressed to this consumer's agents; failures are
+   * logged, not retried.
+   */
+  dispatch: (envelope: CursorSlackRelayEvent) => Promise<void>;
+  logger: (line: string) => void;
+  /** Test seam. Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Test seam: override long-poll wait (default 25s). */
+  pollWaitMs?: number;
+}
+
+/** Human-readable log fragment for one relayed Slack event. */
+export function formatCursorSlackEventLog(envelope: {
+  eventName: string;
+  agentName: string;
+  matchedBy: string;
+  channelId: string;
+  threadTs: string;
+  receivedAtMs: number;
+  eventId?: string;
+}): string {
+  const received = new Date(envelope.receivedAtMs).toISOString();
+  return `${envelope.eventName} → ${envelope.agentName} (${envelope.matchedBy}) in ${envelope.channelId}/${envelope.threadTs} received=${received} (${envelope.eventId ?? "no event id"})`;
+}
+
+/**
+ * Build the backend proxy caller one agent's {@link SlackApiTransport}
+ * binds to. Returns Slack-shaped `{ ok: false, error }` bodies on transport
+ * failures so channel soft-fail paths behave exactly like direct Web API
+ * callers.
+ */
+export function createCursorSlackApiCaller(args: {
+  baseUrl: string;
+  apiKey: string;
+  agentName: string;
+  consumerId: string;
+  fetchImpl?: typeof fetch;
+  logger?: (line: string) => void;
+}): (
+  method: string,
+  callArgs: Record<string, unknown>
+) => Promise<Record<string, unknown>> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const url = `${args.baseUrl.replace(/\/+$/, "")}/v0/slack-events/api`;
+  return async (method, callArgs) => {
+    try {
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${args.apiKey}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          method,
+          arguments: callArgs,
+          agentName: args.agentName,
+          consumerId: args.consumerId,
+        }),
+      });
+      const body = (await response.json().catch(() => undefined)) as
+        | Record<string, unknown>
+        | undefined;
+      if (body !== undefined && typeof body === "object") {
+        if (!response.ok && body.ok === undefined) {
+          const error =
+            typeof body.error === "string"
+              ? body.error
+              : `cursor_backend_http_${response.status}`;
+          return { ok: false, error };
+        }
+        return body;
+      }
+      return {
+        ok: false,
+        error: `cursor_backend_http_${response.status}`,
+      };
+    } catch (error) {
+      args.logger?.(
+        `[agent-serve] cursor-slack: ${method} proxy call failed: ${describeRelayError(error)}`
+      );
+      return { ok: false, error: "cursor_backend_unreachable" };
+    }
+  };
+}
+
+/**
+ * Cursor Slack relay: a thin {@link CursorRelayCore} adapter. Keeps the same
+ * `new CursorSlackRelay(options)` surface with `.resolveConsumerId()`,
+ * `.start()`, and `.stop()` (the server binds outbound transports with the
+ * resolved consumer id before starting).
+ */
+export class CursorSlackRelay {
+  private readonly core: CursorRelayCore<CursorSlackRelayEvent>;
+  /**
+   * Agent names (lowercased) the server confirmed for THIS consumer. The
+   * stream is shared with sibling consumers of the same principal, so only
+   * events for these agents (and this consumer id) may dispatch.
+   */
+  private subscribedAgents = new Set<string>();
+  private consumerId = "";
+
+  constructor(private readonly options: CursorSlackRelayOptions) {
+    const adapter: RelayAdapter<CursorSlackRelayEvent> = {
+      logPrefix: "cursor-slack",
+      subscribePath: "/v0/slack-events/subscriptions",
+      pollPath: "/v0/slack-events",
+      buildRegistrationBody: (consumerId) => {
+        this.consumerId = consumerId;
+        return {
+          consumerId,
+          // Optional fields may be undefined — JSON.stringify drops them
+          // from the registration body.
+          agents: this.options.agents.map((agent) => ({
+            name: agent.name,
+            iconUrl: agent.iconUrl,
+            iconEmoji: agent.iconEmoji,
+          })),
+        };
+      },
+      applyRegistrationResponse: (json) => {
+        const result = json as RegistrationResponse;
+        const agentStatuses = result.agents ?? [];
+        this.subscribedAgents = new Set(
+          agentStatuses
+            .filter((status) => status.isSubscribed)
+            .map((status) => status.name.toLowerCase())
+        );
+        const failures = [
+          ...(result.workspaces ?? [])
+            .filter((workspace) => !workspace.isSubscribed)
+            .map(
+              (workspace) =>
+                `workspace ${workspace.slackTeamId}: ${workspace.detail ?? "not subscribed"}`
+            ),
+          ...agentStatuses
+            .filter((status) => !status.isSubscribed)
+            .map(
+              (status) => `agent ${status.name}: ${status.detail ?? "rejected"}`
+            ),
+        ];
+        if (failures.length > 0) {
+          return failures;
+        }
+        const workspaceIds = (result.workspaces ?? [])
+          .filter((workspace) => workspace.isSubscribed)
+          .map((workspace) => workspace.slackTeamId);
+        return [
+          `registered ${[...this.subscribedAgents].join(", ")} on Slack workspace ${workspaceIds.join(", ")}`,
+        ];
+      },
+      shouldDispatch: (event) => this.shouldDispatch(event),
+      dispatch: (event) => this.options.dispatch(event),
+    };
+    this.core = new CursorRelayCore<CursorSlackRelayEvent>({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      stateDir: options.stateDir,
+      adapter,
+      logger: options.logger,
+      ...(options.fetchImpl === undefined
+        ? {}
+        : { fetchImpl: options.fetchImpl }),
+      ...(options.pollWaitMs === undefined
+        ? {}
+        : { pollWaitMs: options.pollWaitMs }),
+    });
+  }
+
+  /**
+   * Resolve the durable consumer id before starting, so transports can bind
+   * with it. Also used by tests.
+   */
+  async resolveConsumerId(): Promise<string> {
+    this.consumerId = await this.core.resolveConsumerId();
+    return this.consumerId;
+  }
+
+  /**
+   * Whether a relayed event belongs to THIS consumer: the backend stamps
+   * each envelope with the registering consumer id and agent.
+   */
+  private shouldDispatch(event: CursorSlackRelayEvent): boolean {
+    if (event.consumerId !== this.consumerId) {
+      return false;
+    }
+    return this.subscribedAgents.has(event.agentName.toLowerCase());
+  }
+
+  start(): void {
+    this.core.start();
+  }
+
+  async stop(): Promise<void> {
+    await this.core.stop();
+  }
+}

package/src/internal/describe-error.ts

@@ -0,0 +1,4 @@
+/** Stable string for logging / HTTP error bodies. */
+export function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}