badgerclaw 0.1.7 → 1.4.0

package/src/matrix/client/config.ts

@@ -0,0 +1,274 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/matrix";
+import { getMatrixRuntime } from "../../runtime.js";
+import {
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "../../secret-input.js";
+import type { CoreConfig } from "../../types.js";
+import { loadMatrixSdk } from "../sdk-runtime.js";
+import { ensureMatrixSdkLoggingConfigured } from "./logging.js";
+import type { MatrixAuth, MatrixResolvedConfig } from "./types.js";
+
+function clean(value: unknown, path: string): string {
+  return normalizeResolvedSecretInputString({ value, path }) ?? "";
+}
+
+/** Shallow-merge known nested config sub-objects so partial overrides inherit base values. */
+function deepMergeConfig<T extends Record<string, unknown>>(base: T, override: Partial<T>): T {
+  const merged = { ...base, ...override } as Record<string, unknown>;
+  // Merge known nested objects (dm, actions) so partial overrides keep base fields
+  for (const key of ["dm", "actions"] as const) {
+    const b = base[key];
+    const o = override[key];
+    if (typeof b === "object" && b !== null && typeof o === "object" && o !== null) {
+      merged[key] = { ...(b as Record<string, unknown>), ...(o as Record<string, unknown>) };
+    }
+  }
+  return merged as T;
+}
+
+/**
+ * Resolve Matrix config for a specific account, with fallback to top-level config.
+ * This supports both multi-account (channels.badgerclaw.accounts.*) and
+ * single-account (channels.badgerclaw.*) configurations.
+ */
+export function resolveMatrixConfigForAccount(
+  cfg: CoreConfig = getMatrixRuntime().config.loadConfig() as CoreConfig,
+  accountId?: string | null,
+  env: NodeJS.ProcessEnv = process.env,
+): MatrixResolvedConfig {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  const matrixBase = cfg.channels?.badgerclaw ?? {};
+  const accounts = cfg.channels?.badgerclaw?.accounts;
+
+  // Try to get account-specific config first (direct lookup, then case-insensitive fallback)
+  let accountConfig = accounts?.[normalizedAccountId];
+  if (!accountConfig && accounts) {
+    for (const key of Object.keys(accounts)) {
+      if (normalizeAccountId(key) === normalizedAccountId) {
+        accountConfig = accounts[key];
+        break;
+      }
+    }
+  }
+
+  // Deep merge: account-specific values override top-level values, preserving
+  // nested object inheritance (dm, actions, groups) so partial overrides work.
+  const matrix = accountConfig ? deepMergeConfig(matrixBase, accountConfig) : matrixBase;
+
+  const homeserver =
+    clean(matrix.homeserver, "channels.badgerclaw.homeserver") ||
+    clean(env.MATRIX_HOMESERVER, "MATRIX_HOMESERVER");
+  const userId =
+    clean(matrix.userId, "channels.badgerclaw.userId") || clean(env.MATRIX_USER_ID, "MATRIX_USER_ID");
+  const accessToken =
+    clean(matrix.accessToken, "channels.badgerclaw.accessToken") ||
+    clean(env.MATRIX_ACCESS_TOKEN, "MATRIX_ACCESS_TOKEN") ||
+    undefined;
+  const password =
+    clean(matrix.password, "channels.badgerclaw.password") ||
+    clean(env.MATRIX_PASSWORD, "MATRIX_PASSWORD") ||
+    undefined;
+  const deviceName =
+    clean(matrix.deviceName, "channels.badgerclaw.deviceName") ||
+    clean(env.MATRIX_DEVICE_NAME, "MATRIX_DEVICE_NAME") ||
+    undefined;
+  const initialSyncLimit =
+    typeof matrix.initialSyncLimit === "number"
+      ? Math.max(0, Math.floor(matrix.initialSyncLimit))
+      : undefined;
+  const encryption = matrix.encryption ?? false;
+  return {
+    homeserver,
+    userId,
+    accessToken,
+    password,
+    deviceName,
+    initialSyncLimit,
+    encryption,
+  };
+}
+
+/**
+ * Single-account function for backward compatibility - resolves default account config.
+ */
+export function resolveMatrixConfig(
+  cfg: CoreConfig = getMatrixRuntime().config.loadConfig() as CoreConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): MatrixResolvedConfig {
+  return resolveMatrixConfigForAccount(cfg, DEFAULT_ACCOUNT_ID, env);
+}
+
+/**
+ * Resolve the actual homeserver base URL via Matrix .well-known discovery.
+ * Falls back to the provided URL if discovery fails or returns no result.
+ * This ensures the bot always connects to the correct shard even when only
+ * the canonical domain (e.g. badger.signout.io) is configured.
+ */
+async function resolveHomeserverViaWellKnown(homeserver: string): Promise<string> {
+  try {
+    const url = new URL(homeserver);
+    const wellKnownUrl = `${url.protocol}//${url.host}/.well-known/matrix/client`;
+    const resp = await fetch(wellKnownUrl, { signal: AbortSignal.timeout(5000) });
+    if (resp.ok) {
+      const data = (await resp.json()) as Record<string, unknown>;
+      const baseUrl = (data?.["m.homeserver"] as Record<string, unknown>)?.["base_url"];
+      if (typeof baseUrl === "string" && baseUrl.startsWith("http")) {
+        // Strip trailing slash for consistency
+        return baseUrl.replace(/\/$/, "");
+      }
+    }
+  } catch {
+    // Discovery failed — use configured URL as-is
+  }
+  return homeserver;
+}
+
+export async function resolveMatrixAuth(params?: {
+  cfg?: CoreConfig;
+  env?: NodeJS.ProcessEnv;
+  accountId?: string | null;
+}): Promise<MatrixAuth> {
+  const cfg = params?.cfg ?? (getMatrixRuntime().config.loadConfig() as CoreConfig);
+  const env = params?.env ?? process.env;
+  const resolved = resolveMatrixConfigForAccount(cfg, params?.accountId, env);
+  if (!resolved.homeserver) {
+    throw new Error("BadgerClaw homeserver is required (matrix.homeserver)");
+  }
+
+  // Resolve the actual shard via .well-known so we always hit the right server
+  // even when the canonical domain (e.g. badger.signout.io) is configured.
+  resolved.homeserver = await resolveHomeserverViaWellKnown(resolved.homeserver);
+
+  const {
+    loadMatrixCredentials,
+    saveMatrixCredentials,
+    credentialsMatchConfig,
+    touchMatrixCredentials,
+  } = await import("../credentials.js");
+
+  const accountId = params?.accountId;
+  const cached = loadMatrixCredentials(env, accountId);
+  const cachedCredentials =
+    cached &&
+    credentialsMatchConfig(cached, {
+      homeserver: resolved.homeserver,
+      userId: resolved.userId || "",
+    })
+      ? cached
+      : null;
+
+  // If we have an access token, we can fetch userId via whoami if not provided
+  if (resolved.accessToken) {
+    let userId = resolved.userId;
+    if (!userId) {
+      // Fetch userId from access token via whoami
+      ensureMatrixSdkLoggingConfigured();
+      const { MatrixClient } = loadMatrixSdk();
+      const tempClient = new MatrixClient(resolved.homeserver, resolved.accessToken);
+      const whoami = await tempClient.getUserId();
+      userId = whoami;
+      // Save the credentials with the fetched userId
+      saveMatrixCredentials(
+        {
+          homeserver: resolved.homeserver,
+          userId,
+          accessToken: resolved.accessToken,
+        },
+        env,
+        accountId,
+      );
+    } else if (cachedCredentials && cachedCredentials.accessToken === resolved.accessToken) {
+      touchMatrixCredentials(env, accountId);
+    }
+    return {
+      homeserver: resolved.homeserver,
+      userId,
+      accessToken: resolved.accessToken,
+      deviceName: resolved.deviceName,
+      initialSyncLimit: resolved.initialSyncLimit,
+      encryption: resolved.encryption,
+    };
+  }
+
+  if (cachedCredentials) {
+    touchMatrixCredentials(env, accountId);
+    return {
+      homeserver: cachedCredentials.homeserver,
+      userId: cachedCredentials.userId,
+      accessToken: cachedCredentials.accessToken,
+      deviceName: resolved.deviceName,
+      initialSyncLimit: resolved.initialSyncLimit,
+      encryption: resolved.encryption,
+    };
+  }
+
+  if (!resolved.userId) {
+    throw new Error("BadgerClaw userId is required when no access token is configured (matrix.userId)");
+  }
+
+  if (!resolved.password) {
+    throw new Error(
+      "BadgerClaw password is required when no access token is configured (matrix.password)",
+    );
+  }
+
+  // Login with password using HTTP API.
+  const { response: loginResponse, release: releaseLoginResponse } = await fetchWithSsrFGuard({
+    url: `${resolved.homeserver}/_matrix/client/v3/login`,
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "m.login.password",
+        identifier: { type: "m.id.user", user: resolved.userId },
+        password: resolved.password,
+        initial_device_display_name: resolved.deviceName ?? "OpenClaw Gateway",
+      }),
+    },
+    auditContext: "matrix.login",
+  });
+  const login = await (async () => {
+    try {
+      if (!loginResponse.ok) {
+        const errorText = await loginResponse.text();
+        throw new Error(`BadgerClaw login failed: ${errorText}`);
+      }
+      return (await loginResponse.json()) as {
+        access_token?: string;
+        user_id?: string;
+        device_id?: string;
+      };
+    } finally {
+      await releaseLoginResponse();
+    }
+  })();
+
+  const accessToken = login.access_token?.trim();
+  if (!accessToken) {
+    throw new Error("BadgerClaw login did not return an access token");
+  }
+
+  const auth: MatrixAuth = {
+    homeserver: resolved.homeserver,
+    userId: login.user_id ?? resolved.userId,
+    accessToken,
+    deviceName: resolved.deviceName,
+    initialSyncLimit: resolved.initialSyncLimit,
+    encryption: resolved.encryption,
+  };
+
+  saveMatrixCredentials(
+    {
+      homeserver: auth.homeserver,
+      userId: auth.userId,
+      accessToken: auth.accessToken,
+      deviceId: login.device_id,
+    },
+    env,
+    accountId,
+  );
+
+  return auth;
+}

package/src/matrix/client/create-client.ts

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import type {
+  IStorageProvider,
+  ICryptoStorageProvider,
+  MatrixClient,
+} from "@vector-im/matrix-bot-sdk";
+import { loadMatrixSdk } from "../sdk-runtime.js";
+import { ensureMatrixSdkLoggingConfigured } from "./logging.js";
+import {
+  maybeMigrateLegacyStorage,
+  resolveMatrixStoragePaths,
+  writeStorageMeta,
+} from "./storage.js";
+
+function sanitizeUserIdList(input: unknown, label: string): string[] {
+  const LogService = loadMatrixSdk().LogService;
+  if (input == null) {
+    return [];
+  }
+  if (!Array.isArray(input)) {
+    LogService.warn(
+      "MatrixClientLite",
+      `Expected ${label} list to be an array, got ${typeof input}`,
+    );
+    return [];
+  }
+  const filtered = input.filter(
+    (entry): entry is string => typeof entry === "string" && entry.trim().length > 0,
+  );
+  if (filtered.length !== input.length) {
+    LogService.warn(
+      "MatrixClientLite",
+      `Dropping ${input.length - filtered.length} invalid ${label} entries from sync payload`,
+    );
+  }
+  return filtered;
+}
+
+export async function createMatrixClient(params: {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  encryption?: boolean;
+  localTimeoutMs?: number;
+  accountId?: string | null;
+}): Promise<MatrixClient> {
+  const { MatrixClient, SimpleFsStorageProvider, RustSdkCryptoStorageProvider, LogService } =
+    loadMatrixSdk();
+  ensureMatrixSdkLoggingConfigured();
+  const env = process.env;
+
+  // Create storage provider
+  const storagePaths = resolveMatrixStoragePaths({
+    homeserver: params.homeserver,
+    userId: params.userId,
+    accessToken: params.accessToken,
+    accountId: params.accountId,
+    env,
+  });
+  maybeMigrateLegacyStorage({ storagePaths, env });
+  fs.mkdirSync(storagePaths.rootDir, { recursive: true });
+  const storage: IStorageProvider = new SimpleFsStorageProvider(storagePaths.storagePath);
+
+  // Create crypto storage if encryption is enabled
+  let cryptoStorage: ICryptoStorageProvider | undefined;
+  if (params.encryption) {
+    fs.mkdirSync(storagePaths.cryptoPath, { recursive: true });
+
+    try {
+      const { StoreType } = await import("@matrix-org/matrix-sdk-crypto-nodejs");
+      cryptoStorage = new RustSdkCryptoStorageProvider(storagePaths.cryptoPath, StoreType.Sqlite);
+    } catch (err) {
+      LogService.warn(
+        "MatrixClientLite",
+        "Failed to initialize crypto storage, E2EE disabled:",
+        err,
+      );
+    }
+  }
+
+  writeStorageMeta({
+    storagePaths,
+    homeserver: params.homeserver,
+    userId: params.userId,
+    accountId: params.accountId,
+  });
+
+  const client = new MatrixClient(params.homeserver, params.accessToken, storage, cryptoStorage);
+
+  if (client.crypto) {
+    const originalUpdateSyncData = client.crypto.updateSyncData.bind(client.crypto);
+    client.crypto.updateSyncData = async (
+      toDeviceMessages,
+      otkCounts,
+      unusedFallbackKeyAlgs,
+      changedDeviceLists,
+      leftDeviceLists,
+    ) => {
+      const safeChanged = sanitizeUserIdList(changedDeviceLists, "changed device list");
+      const safeLeft = sanitizeUserIdList(leftDeviceLists, "left device list");
+      try {
+        return await originalUpdateSyncData(
+          toDeviceMessages,
+          otkCounts,
+          unusedFallbackKeyAlgs,
+          safeChanged,
+          safeLeft,
+        );
+      } catch (err) {
+        const message = typeof err === "string" ? err : err instanceof Error ? err.message : "";
+        if (message.includes("Expect value to be String")) {
+          LogService.warn(
+            "MatrixClientLite",
+            "Ignoring malformed device list entries during crypto sync",
+            message,
+          );
+          return;
+        }
+        throw err;
+      }
+    };
+  }
+
+  return client;
+}

package/src/matrix/client/logging.ts

@@ -0,0 +1,46 @@
+import { loadMatrixSdk } from "../sdk-runtime.js";
+
+let matrixSdkLoggingConfigured = false;
+let matrixSdkBaseLogger:
+  | {
+      trace: (module: string, ...messageOrObject: unknown[]) => void;
+      debug: (module: string, ...messageOrObject: unknown[]) => void;
+      info: (module: string, ...messageOrObject: unknown[]) => void;
+      warn: (module: string, ...messageOrObject: unknown[]) => void;
+      error: (module: string, ...messageOrObject: unknown[]) => void;
+    }
+  | undefined;
+
+function shouldSuppressMatrixHttpNotFound(module: string, messageOrObject: unknown[]): boolean {
+  if (module !== "MatrixHttpClient") {
+    return false;
+  }
+  return messageOrObject.some((entry) => {
+    if (!entry || typeof entry !== "object") {
+      return false;
+    }
+    return (entry as { errcode?: string }).errcode === "M_NOT_FOUND";
+  });
+}
+
+export function ensureMatrixSdkLoggingConfigured(): void {
+  if (matrixSdkLoggingConfigured) {
+    return;
+  }
+  const { ConsoleLogger, LogService } = loadMatrixSdk();
+  matrixSdkBaseLogger = new ConsoleLogger();
+  matrixSdkLoggingConfigured = true;
+
+  LogService.setLogger({
+    trace: (module, ...messageOrObject) => matrixSdkBaseLogger?.trace(module, ...messageOrObject),
+    debug: (module, ...messageOrObject) => matrixSdkBaseLogger?.debug(module, ...messageOrObject),
+    info: (module, ...messageOrObject) => matrixSdkBaseLogger?.info(module, ...messageOrObject),
+    warn: (module, ...messageOrObject) => matrixSdkBaseLogger?.warn(module, ...messageOrObject),
+    error: (module, ...messageOrObject) => {
+      if (shouldSuppressMatrixHttpNotFound(module, messageOrObject)) {
+        return;
+      }
+      matrixSdkBaseLogger?.error(module, ...messageOrObject);
+    },
+  });
+}

package/src/matrix/client/runtime.ts

@@ -0,0 +1,4 @@
+export function isBunRuntime(): boolean {
+  const versions = process.versions as { bun?: string };
+  return typeof versions.bun === "string";
+}

package/src/matrix/client/shared.ts

@@ -0,0 +1,223 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type { CoreConfig } from "../../types.js";
+import { getMatrixLogService } from "../sdk-runtime.js";
+import { setupKeyBackup } from "./backup.js";
+import { resolveMatrixAuth } from "./config.js";
+import { createMatrixClient } from "./create-client.js";
+import { startMatrixClientWithGrace } from "./startup.js";
+import { DEFAULT_ACCOUNT_KEY } from "./storage.js";
+import type { MatrixAuth } from "./types.js";
+
+type SharedMatrixClientState = {
+  client: MatrixClient;
+  key: string;
+  started: boolean;
+  cryptoReady: boolean;
+};
+
+// Support multiple accounts with separate clients
+const sharedClientStates = new Map<string, SharedMatrixClientState>();
+const sharedClientPromises = new Map<string, Promise<SharedMatrixClientState>>();
+const sharedClientStartPromises = new Map<string, Promise<void>>();
+
+function buildSharedClientKey(auth: MatrixAuth, accountId?: string | null): string {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  return [
+    auth.homeserver,
+    auth.userId,
+    auth.accessToken,
+    auth.encryption ? "e2ee" : "plain",
+    normalizedAccountId || DEFAULT_ACCOUNT_KEY,
+  ].join("|");
+}
+
+async function createSharedMatrixClient(params: {
+  auth: MatrixAuth;
+  timeoutMs?: number;
+  accountId?: string | null;
+}): Promise<SharedMatrixClientState> {
+  const client = await createMatrixClient({
+    homeserver: params.auth.homeserver,
+    userId: params.auth.userId,
+    accessToken: params.auth.accessToken,
+    encryption: params.auth.encryption,
+    localTimeoutMs: params.timeoutMs,
+    accountId: params.accountId,
+  });
+  return {
+    client,
+    key: buildSharedClientKey(params.auth, params.accountId),
+    started: false,
+    cryptoReady: false,
+  };
+}
+
+async function ensureSharedClientStarted(params: {
+  state: SharedMatrixClientState;
+  timeoutMs?: number;
+  initialSyncLimit?: number;
+  encryption?: boolean;
+}): Promise<void> {
+  if (params.state.started) {
+    return;
+  }
+  const key = params.state.key;
+  const existingStartPromise = sharedClientStartPromises.get(key);
+  if (existingStartPromise) {
+    await existingStartPromise;
+    return;
+  }
+  const startPromise = (async () => {
+    const client = params.state.client;
+
+    // Initialize crypto if enabled
+    if (params.encryption && !params.state.cryptoReady) {
+      try {
+        const joinedRooms = await client.getJoinedRooms();
+        if (client.crypto) {
+          await (client.crypto as { prepare: (rooms?: string[]) => Promise<void> }).prepare(
+            joinedRooms,
+          );
+          params.state.cryptoReady = true;
+          await setupKeyBackup(client);
+        }
+      } catch (err) {
+        const LogService = getMatrixLogService();
+        LogService.warn("MatrixClientLite", "Failed to prepare crypto:", err);
+      }
+    }
+
+    await startMatrixClientWithGrace({
+      client,
+      onError: (err: unknown) => {
+        params.state.started = false;
+        const LogService = getMatrixLogService();
+        const message = err instanceof Error ? err.message : String(err);
+        // OTK conflict means the server has stale keys for this device.
+        // Log clearly so the user knows to re-pair.
+        if (message.includes("One time key") && message.includes("already exists")) {
+          LogService.error(
+            "MatrixClientLite",
+            "E2EE key conflict detected — the bot's encryption session is stale.",
+            "Run: /bot pair <botname> in BadgerClaw and reconnect with 'openclaw badgerclaw connect <code>'",
+          );
+        } else {
+          LogService.error("MatrixClientLite", "client.start() error:", err);
+        }
+      },
+    });
+    params.state.started = true;
+  })();
+  sharedClientStartPromises.set(key, startPromise);
+  try {
+    await startPromise;
+  } finally {
+    sharedClientStartPromises.delete(key);
+  }
+}
+
+export async function resolveSharedMatrixClient(
+  params: {
+    cfg?: CoreConfig;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    auth?: MatrixAuth;
+    startClient?: boolean;
+    accountId?: string | null;
+  } = {},
+): Promise<MatrixClient> {
+  const accountId = normalizeAccountId(params.accountId);
+  const auth =
+    params.auth ?? (await resolveMatrixAuth({ cfg: params.cfg, env: params.env, accountId }));
+  const key = buildSharedClientKey(auth, accountId);
+  const shouldStart = params.startClient !== false;
+
+  // Check if we already have a client for this key
+  const existingState = sharedClientStates.get(key);
+  if (existingState) {
+    if (shouldStart) {
+      await ensureSharedClientStarted({
+        state: existingState,
+        timeoutMs: params.timeoutMs,
+        initialSyncLimit: auth.initialSyncLimit,
+        encryption: auth.encryption,
+      });
+    }
+    return existingState.client;
+  }
+
+  // Check if there's a pending creation for this key
+  const existingPromise = sharedClientPromises.get(key);
+  if (existingPromise) {
+    const pending = await existingPromise;
+    if (shouldStart) {
+      await ensureSharedClientStarted({
+        state: pending,
+        timeoutMs: params.timeoutMs,
+        initialSyncLimit: auth.initialSyncLimit,
+        encryption: auth.encryption,
+      });
+    }
+    return pending.client;
+  }
+
+  // Create a new client for this account
+  const createPromise = createSharedMatrixClient({
+    auth,
+    timeoutMs: params.timeoutMs,
+    accountId,
+  });
+  sharedClientPromises.set(key, createPromise);
+  try {
+    const created = await createPromise;
+    sharedClientStates.set(key, created);
+    if (shouldStart) {
+      await ensureSharedClientStarted({
+        state: created,
+        timeoutMs: params.timeoutMs,
+        initialSyncLimit: auth.initialSyncLimit,
+        encryption: auth.encryption,
+      });
+    }
+    return created.client;
+  } finally {
+    sharedClientPromises.delete(key);
+  }
+}
+
+export async function waitForMatrixSync(_params: {
+  client: MatrixClient;
+  timeoutMs?: number;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  // @vector-im/matrix-bot-sdk handles sync internally in start()
+  // This is kept for API compatibility but is essentially a no-op now
+}
+
+export function stopSharedClient(key?: string): void {
+  if (key) {
+    // Stop a specific client
+    const state = sharedClientStates.get(key);
+    if (state) {
+      state.client.stop();
+      sharedClientStates.delete(key);
+    }
+  } else {
+    // Stop all clients (backward compatible behavior)
+    for (const state of sharedClientStates.values()) {
+      state.client.stop();
+    }
+    sharedClientStates.clear();
+  }
+}
+
+/**
+ * Stop the shared client for a specific account.
+ * Use this instead of stopSharedClient() when shutting down a single account
+ * to avoid stopping all accounts.
+ */
+export function stopSharedClientForAccount(auth: MatrixAuth, accountId?: string | null): void {
+  const key = buildSharedClientKey(auth, normalizeAccountId(accountId));
+  stopSharedClient(key);
+}

package/src/matrix/client/startup.ts

@@ -0,0 +1,29 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+
+export const MATRIX_CLIENT_STARTUP_GRACE_MS = 2000;
+
+export async function startMatrixClientWithGrace(params: {
+  client: Pick<MatrixClient, "start">;
+  graceMs?: number;
+  onError?: (err: unknown) => void;
+}): Promise<void> {
+  const graceMs = params.graceMs ?? MATRIX_CLIENT_STARTUP_GRACE_MS;
+  let startFailed = false;
+  let startError: unknown = undefined;
+  let startPromise: Promise<unknown>;
+  try {
+    startPromise = params.client.start();
+  } catch (err) {
+    params.onError?.(err);
+    throw err;
+  }
+  void startPromise.catch((err: unknown) => {
+    startFailed = true;
+    startError = err;
+    params.onError?.(err);
+  });
+  await new Promise((resolve) => setTimeout(resolve, graceMs));
+  if (startFailed) {
+    throw startError;
+  }
+}