@archipelagolab/lobi 1.0.0

package/src/startup-maintenance.test.ts

@@ -0,0 +1,227 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { withTempHome } from "../../../test/helpers/temp-home.js";
+
+const legacyCryptoInspectorAvailability = vi.hoisted(() => ({
+  available: true,
+}));
+
+vi.mock("./legacy-crypto-inspector-availability.js", () => ({
+  isMatrixLegacyCryptoInspectorAvailable: () => legacyCryptoInspectorAvailability.available,
+}));
+
+import { runMatrixStartupMaintenance } from "./startup-maintenance.js";
+import { resolveMatrixAccountStorageRoot } from "./storage-paths.js";
+
+async function seedLegacyMatrixState(home: string) {
+  const stateDir = path.join(home, ".openclaw");
+  await fs.mkdir(path.join(stateDir, "matrix"), { recursive: true });
+  await fs.writeFile(path.join(stateDir, "matrix", "bot-storage.json"), '{"legacy":true}');
+}
+
+function makeMatrixStartupConfig(includeCredentials = true) {
+  return {
+    channels: {
+      matrix: includeCredentials
+        ? {
+            homeserver: "https://matrix.example.org",
+            userId: "@bot:example.org",
+            accessToken: "tok-123",
+          }
+        : {
+            homeserver: "https://matrix.example.org",
+          },
+    },
+  } as const;
+}
+
+async function seedLegacyMatrixCrypto(home: string) {
+  const stateDir = path.join(home, ".openclaw");
+  const { rootDir } = resolveMatrixAccountStorageRoot({
+    stateDir,
+    homeserver: "https://matrix.example.org",
+    userId: "@bot:example.org",
+    accessToken: "tok-123",
+  });
+  await fs.mkdir(path.join(rootDir, "crypto"), { recursive: true });
+  await fs.writeFile(
+    path.join(rootDir, "crypto", "bot-sdk.json"),
+    JSON.stringify({ deviceId: "DEVICE123" }),
+    "utf8",
+  );
+}
+
+function createSuccessfulMatrixMigrationDeps() {
+  return {
+    maybeCreateMatrixMigrationSnapshot: vi.fn(async () => ({
+      created: true,
+      archivePath: "/tmp/snapshot.tar.gz",
+      markerPath: "/tmp/migration-snapshot.json",
+    })),
+    autoMigrateLegacyMatrixState: vi.fn(async () => ({
+      migrated: true,
+      changes: [],
+      warnings: [],
+    })),
+  };
+}
+
+describe("runMatrixStartupMaintenance", () => {
+  beforeEach(() => {
+    legacyCryptoInspectorAvailability.available = true;
+  });
+
+  it("creates a snapshot before actionable startup migration", async () => {
+    await withTempHome(async (home) => {
+      await seedLegacyMatrixState(home);
+      const deps = createSuccessfulMatrixMigrationDeps();
+      const autoPrepareLegacyMatrixCryptoMock = vi.fn(async () => ({
+        migrated: false,
+        changes: [],
+        warnings: [],
+      }));
+
+      await runMatrixStartupMaintenance({
+        cfg: makeMatrixStartupConfig(),
+        env: process.env,
+        deps: {
+          maybeCreateMatrixMigrationSnapshot: deps.maybeCreateMatrixMigrationSnapshot,
+          autoMigrateLegacyMatrixState: deps.autoMigrateLegacyMatrixState,
+          autoPrepareLegacyMatrixCrypto: autoPrepareLegacyMatrixCryptoMock,
+        },
+        log: {},
+      });
+
+      expect(deps.maybeCreateMatrixMigrationSnapshot).toHaveBeenCalledWith(
+        expect.objectContaining({ trigger: "gateway-startup" }),
+      );
+      expect(deps.autoMigrateLegacyMatrixState).toHaveBeenCalledOnce();
+      expect(autoPrepareLegacyMatrixCryptoMock).toHaveBeenCalledOnce();
+    });
+  });
+
+  it("skips snapshot creation when startup only has warning-only migration state", async () => {
+    await withTempHome(async (home) => {
+      await seedLegacyMatrixState(home);
+      const maybeCreateMatrixMigrationSnapshotMock = vi.fn();
+      const autoMigrateLegacyMatrixStateMock = vi.fn();
+      const autoPrepareLegacyMatrixCryptoMock = vi.fn();
+      const info = vi.fn();
+      const warn = vi.fn();
+
+      await runMatrixStartupMaintenance({
+        cfg: makeMatrixStartupConfig(false),
+        env: process.env,
+        deps: {
+          maybeCreateMatrixMigrationSnapshot: maybeCreateMatrixMigrationSnapshotMock as never,
+          autoMigrateLegacyMatrixState: autoMigrateLegacyMatrixStateMock as never,
+          autoPrepareLegacyMatrixCrypto: autoPrepareLegacyMatrixCryptoMock as never,
+        },
+        log: { info, warn },
+      });
+
+      expect(maybeCreateMatrixMigrationSnapshotMock).not.toHaveBeenCalled();
+      expect(autoMigrateLegacyMatrixStateMock).not.toHaveBeenCalled();
+      expect(autoPrepareLegacyMatrixCryptoMock).not.toHaveBeenCalled();
+      expect(info).toHaveBeenCalledWith(
+        "matrix: migration remains in a warning-only state; no pre-migration snapshot was needed yet",
+      );
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining("could not be resolved yet"));
+    });
+  });
+
+  it("logs the concrete unavailable-inspector warning when startup migration is warning-only", async () => {
+    legacyCryptoInspectorAvailability.available = false;
+
+    await withTempHome(async (home) => {
+      await seedLegacyMatrixCrypto(home);
+      const maybeCreateMatrixMigrationSnapshotMock = vi.fn();
+      const autoMigrateLegacyMatrixStateMock = vi.fn();
+      const autoPrepareLegacyMatrixCryptoMock = vi.fn();
+      const info = vi.fn();
+      const warn = vi.fn();
+
+      await runMatrixStartupMaintenance({
+        cfg: makeMatrixStartupConfig(),
+        env: process.env,
+        deps: {
+          maybeCreateMatrixMigrationSnapshot: maybeCreateMatrixMigrationSnapshotMock as never,
+          autoMigrateLegacyMatrixState: autoMigrateLegacyMatrixStateMock as never,
+          autoPrepareLegacyMatrixCrypto: autoPrepareLegacyMatrixCryptoMock as never,
+        },
+        log: { info, warn },
+      });
+
+      expect(maybeCreateMatrixMigrationSnapshotMock).not.toHaveBeenCalled();
+      expect(autoMigrateLegacyMatrixStateMock).not.toHaveBeenCalled();
+      expect(autoPrepareLegacyMatrixCryptoMock).not.toHaveBeenCalled();
+      expect(info).toHaveBeenCalledWith(
+        "matrix: migration remains in a warning-only state; no pre-migration snapshot was needed yet",
+      );
+      expect(warn).toHaveBeenCalledWith(
+        "matrix: legacy encrypted-state warnings:\n- Legacy Matrix encrypted state was detected, but the Matrix crypto inspector is unavailable.",
+      );
+    });
+  });
+
+  it("skips startup migration when snapshot creation fails", async () => {
+    await withTempHome(async (home) => {
+      await seedLegacyMatrixState(home);
+      const maybeCreateMatrixMigrationSnapshotMock = vi.fn(async () => {
+        throw new Error("backup failed");
+      });
+      const autoMigrateLegacyMatrixStateMock = vi.fn();
+      const autoPrepareLegacyMatrixCryptoMock = vi.fn();
+      const warn = vi.fn();
+
+      await runMatrixStartupMaintenance({
+        cfg: makeMatrixStartupConfig(),
+        env: process.env,
+        deps: {
+          maybeCreateMatrixMigrationSnapshot: maybeCreateMatrixMigrationSnapshotMock,
+          autoMigrateLegacyMatrixState: autoMigrateLegacyMatrixStateMock as never,
+          autoPrepareLegacyMatrixCrypto: autoPrepareLegacyMatrixCryptoMock as never,
+        },
+        log: { warn },
+      });
+
+      expect(autoMigrateLegacyMatrixStateMock).not.toHaveBeenCalled();
+      expect(autoPrepareLegacyMatrixCryptoMock).not.toHaveBeenCalled();
+      expect(warn).toHaveBeenCalledWith(
+        "gateway: failed creating a Matrix migration snapshot; skipping Matrix migration for now: Error: backup failed",
+      );
+    });
+  });
+
+  it("downgrades migration step failures to warnings so startup can continue", async () => {
+    await withTempHome(async (home) => {
+      await seedLegacyMatrixState(home);
+      const deps = createSuccessfulMatrixMigrationDeps();
+      const autoPrepareLegacyMatrixCryptoMock = vi.fn(async () => {
+        throw new Error("disk full");
+      });
+      const warn = vi.fn();
+
+      await expect(
+        runMatrixStartupMaintenance({
+          cfg: makeMatrixStartupConfig(),
+          env: process.env,
+          deps: {
+            maybeCreateMatrixMigrationSnapshot: deps.maybeCreateMatrixMigrationSnapshot,
+            autoMigrateLegacyMatrixState: deps.autoMigrateLegacyMatrixState,
+            autoPrepareLegacyMatrixCrypto: autoPrepareLegacyMatrixCryptoMock,
+          },
+          log: { warn },
+        }),
+      ).resolves.toBeUndefined();
+
+      expect(deps.maybeCreateMatrixMigrationSnapshot).toHaveBeenCalledOnce();
+      expect(deps.autoMigrateLegacyMatrixState).toHaveBeenCalledOnce();
+      expect(autoPrepareLegacyMatrixCryptoMock).toHaveBeenCalledOnce();
+      expect(warn).toHaveBeenCalledWith(
+        "gateway: legacy Matrix encrypted-state preparation failed during Matrix migration; continuing startup: Error: disk full",
+      );
+    });
+  });
+});

package/src/startup-maintenance.ts

@@ -0,0 +1,114 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
+import {
+  autoMigrateLegacyMatrixState,
+  autoPrepareLegacyMatrixCrypto,
+  maybeCreateMatrixMigrationSnapshot,
+  resolveMatrixMigrationStatus,
+  type MatrixMigrationStatus,
+} from "./matrix-migration.runtime.js";
+
+type MatrixStartupLogger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+function logWarningOnlyMatrixMigrationReasons(params: {
+  status: MatrixMigrationStatus;
+  log: MatrixStartupLogger;
+}): void {
+  if (params.status.legacyState && "warning" in params.status.legacyState) {
+    params.log.warn?.(`matrix: ${params.status.legacyState.warning}`);
+  }
+
+  if (params.status.legacyCrypto.warnings.length > 0) {
+    params.log.warn?.(
+      `matrix: legacy encrypted-state warnings:\n${params.status.legacyCrypto.warnings.map((entry) => `- ${entry}`).join("\n")}`,
+    );
+  }
+}
+
+async function runBestEffortMatrixMigrationStep(params: {
+  label: string;
+  log: MatrixStartupLogger;
+  logPrefix?: string;
+  run: () => Promise<unknown>;
+}): Promise<void> {
+  try {
+    await params.run();
+  } catch (err) {
+    params.log.warn?.(
+      `${params.logPrefix?.trim() || "gateway"}: ${params.label} failed during Matrix migration; continuing startup: ${String(err)}`,
+    );
+  }
+}
+
+export async function runMatrixStartupMaintenance(params: {
+  cfg: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+  log: MatrixStartupLogger;
+  trigger?: string;
+  logPrefix?: string;
+  deps?: {
+    maybeCreateMatrixMigrationSnapshot?: typeof maybeCreateMatrixMigrationSnapshot;
+    autoMigrateLegacyMatrixState?: typeof autoMigrateLegacyMatrixState;
+    autoPrepareLegacyMatrixCrypto?: typeof autoPrepareLegacyMatrixCrypto;
+  };
+}): Promise<void> {
+  const env = params.env ?? process.env;
+  const createSnapshot =
+    params.deps?.maybeCreateMatrixMigrationSnapshot ?? maybeCreateMatrixMigrationSnapshot;
+  const migrateLegacyState =
+    params.deps?.autoMigrateLegacyMatrixState ?? autoMigrateLegacyMatrixState;
+  const prepareLegacyCrypto =
+    params.deps?.autoPrepareLegacyMatrixCrypto ?? autoPrepareLegacyMatrixCrypto;
+  const trigger = params.trigger?.trim() || "gateway-startup";
+  const logPrefix = params.logPrefix?.trim() || "gateway";
+  const migrationStatus = resolveMatrixMigrationStatus({ cfg: params.cfg, env });
+
+  if (!migrationStatus.pending) {
+    return;
+  }
+  if (!migrationStatus.actionable) {
+    params.log.info?.(
+      "matrix: migration remains in a warning-only state; no pre-migration snapshot was needed yet",
+    );
+    logWarningOnlyMatrixMigrationReasons({ status: migrationStatus, log: params.log });
+    return;
+  }
+
+  try {
+    await createSnapshot({
+      trigger,
+      env,
+      log: params.log,
+    });
+  } catch (err) {
+    params.log.warn?.(
+      `${logPrefix}: failed creating a Matrix migration snapshot; skipping Matrix migration for now: ${String(err)}`,
+    );
+    return;
+  }
+
+  await runBestEffortMatrixMigrationStep({
+    label: "legacy Matrix state migration",
+    log: params.log,
+    logPrefix,
+    run: () =>
+      migrateLegacyState({
+        cfg: params.cfg,
+        env,
+        log: params.log,
+      }),
+  });
+  await runBestEffortMatrixMigrationStep({
+    label: "legacy Matrix encrypted-state preparation",
+    log: params.log,
+    logPrefix,
+    run: () =>
+      prepareLegacyCrypto({
+        cfg: params.cfg,
+        env,
+        log: params.log,
+      }),
+  });
+}

package/src/storage-paths.ts

@@ -0,0 +1,92 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+export function sanitizeMatrixPathSegment(value: string): string {
+  const cleaned = normalizeLowercaseStringOrEmpty(value)
+    .replace(/[^a-z0-9._-]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return cleaned || "unknown";
+}
+
+export function resolveMatrixHomeserverKey(homeserver: string): string {
+  try {
+    const url = new URL(homeserver);
+    if (url.host) {
+      return sanitizeMatrixPathSegment(url.host);
+    }
+  } catch {
+    // fall through
+  }
+  return sanitizeMatrixPathSegment(homeserver);
+}
+
+export function hashMatrixAccessToken(accessToken: string): string {
+  return crypto.createHash("sha256").update(accessToken).digest("hex").slice(0, 16);
+}
+
+export function resolveMatrixCredentialsFilename(accountId?: string | null): string {
+  const normalized = normalizeAccountId(accountId);
+  return normalized === DEFAULT_ACCOUNT_ID ? "credentials.json" : `credentials-${normalized}.json`;
+}
+
+export function resolveMatrixCredentialsDir(stateDir: string): string {
+  return path.join(stateDir, "credentials", "lobi");
+}
+
+export function resolveMatrixCredentialsPath(params: {
+  stateDir: string;
+  accountId?: string | null;
+}): string {
+  return path.join(
+    resolveMatrixCredentialsDir(params.stateDir),
+    resolveMatrixCredentialsFilename(params.accountId),
+  );
+}
+
+export function resolveMatrixLegacyFlatStoreRoot(stateDir: string): string {
+  return path.join(stateDir, "lobi");
+}
+
+export function resolveMatrixLegacyFlatStoragePaths(stateDir: string): {
+  rootDir: string;
+  storagePath: string;
+  cryptoPath: string;
+} {
+  const rootDir = resolveMatrixLegacyFlatStoreRoot(stateDir);
+  return {
+    rootDir,
+    storagePath: path.join(rootDir, "bot-storage.json"),
+    cryptoPath: path.join(rootDir, "crypto"),
+  };
+}
+
+export function resolveMatrixAccountStorageRoot(params: {
+  stateDir: string;
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  accountId?: string | null;
+}): {
+  rootDir: string;
+  accountKey: string;
+  tokenHash: string;
+} {
+  const accountKey = sanitizeMatrixPathSegment(params.accountId ?? DEFAULT_ACCOUNT_ID);
+  const userKey = sanitizeMatrixPathSegment(params.userId);
+  const serverKey = resolveMatrixHomeserverKey(params.homeserver);
+  const tokenHash = hashMatrixAccessToken(params.accessToken);
+  return {
+    rootDir: path.join(
+      params.stateDir,
+      "lobi",
+      "accounts",
+      accountKey,
+      `${serverKey}__${userKey}`,
+      tokenHash,
+    ),
+    accountKey,
+    tokenHash,
+  };
+}

package/src/test-helpers.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const MATRIX_TEST_HOMESERVER = "https://matrix.example.org";
+export const MATRIX_DEFAULT_USER_ID = "@bot:example.org";
+export const MATRIX_DEFAULT_ACCESS_TOKEN = "tok-123";
+export const MATRIX_DEFAULT_DEVICE_ID = "DEVICE123";
+export const MATRIX_OPS_ACCOUNT_ID = "ops";
+export const MATRIX_OPS_USER_ID = "@ops-bot:example.org";
+export const LOBI_OPS_ACCESS_TOKEN = "tok-ops";
+export const LOBI_OPS_DEVICE_ID = "DEVICEOPS";
+
+export function writeFile(filePath: string, value: string) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, value, "utf8");
+}
+
+export function writeMatrixCredentials(
+  stateDir: string,
+  params?: {
+    accountId?: string;
+    homeserver?: string;
+    userId?: string;
+    accessToken?: string;
+    deviceId?: string;
+  },
+) {
+  const accountId = params?.accountId ?? MATRIX_OPS_ACCOUNT_ID;
+  writeFile(
+    path.join(stateDir, "credentials", "matrix", `credentials-${accountId}.json`),
+    JSON.stringify(
+      {
+        homeserver: params?.homeserver ?? MATRIX_TEST_HOMESERVER,
+        userId: params?.userId ?? MATRIX_OPS_USER_ID,
+        accessToken: params?.accessToken ?? LOBI_OPS_ACCESS_TOKEN,
+        deviceId: params?.deviceId ?? LOBI_OPS_DEVICE_ID,
+      },
+      null,
+      2,
+    ),
+  );
+}

package/src/test-mocks.ts

@@ -0,0 +1,55 @@
+import type { Mock } from "vitest";
+import { vi } from "vitest";
+
+type MatrixBotSdkMockParams = {
+  matrixClient?: unknown;
+  simpleFsStorageProvider?: unknown;
+  rustSdkCryptoStorageProvider?: unknown;
+  includeVerboseLogService?: boolean;
+};
+
+type MatrixBotSdkMock = {
+  ConsoleLogger: new () => {
+    trace: Mock<() => void>;
+    debug: Mock<() => void>;
+    info: Mock<() => void>;
+    warn: Mock<() => void>;
+    error: Mock<() => void>;
+  };
+  MatrixClient: unknown;
+  LogService: {
+    setLogger: Mock<() => void>;
+    warn?: Mock<() => void>;
+    info?: Mock<() => void>;
+    debug?: Mock<() => void>;
+  };
+  SimpleFsStorageProvider: unknown;
+  RustSdkCryptoStorageProvider: unknown;
+};
+
+export function createMatrixBotSdkMock(params: MatrixBotSdkMockParams = {}): MatrixBotSdkMock {
+  return {
+    ConsoleLogger: class {
+      trace = vi.fn();
+      debug = vi.fn();
+      info = vi.fn();
+      warn = vi.fn();
+      error = vi.fn();
+    },
+    MatrixClient: params.matrixClient ?? function MatrixClient() {},
+    LogService: {
+      setLogger: vi.fn(),
+      ...(params.includeVerboseLogService
+        ? {
+            warn: vi.fn(),
+            info: vi.fn(),
+            debug: vi.fn(),
+          }
+        : {}),
+    },
+    SimpleFsStorageProvider:
+      params.simpleFsStorageProvider ?? function SimpleFsStorageProvider() {},
+    RustSdkCryptoStorageProvider:
+      params.rustSdkCryptoStorageProvider ?? function RustSdkCryptoStorageProvider() {},
+  };
+}

package/src/test-runtime.ts

@@ -0,0 +1,72 @@
+import {
+  implicitMentionKindWhen,
+  resolveInboundMentionDecision,
+} from "openclaw/plugin-sdk/channel-inbound";
+import { vi } from "vitest";
+import type { PluginRuntime } from "./runtime-api.js";
+import { setMatrixRuntime } from "./runtime.js";
+
+type MatrixTestRuntimeOptions = {
+  cfg?: Record<string, unknown>;
+  logging?: Partial<PluginRuntime["logging"]>;
+  channel?: Partial<PluginRuntime["channel"]>;
+  stateDir?: string;
+};
+
+export function installMatrixTestRuntime(options: MatrixTestRuntimeOptions = {}): void {
+  const defaultStateDirResolver: NonNullable<PluginRuntime["state"]>["resolveStateDir"] = (
+    _env,
+    homeDir,
+  ) => options.stateDir ?? (homeDir ?? (() => "/tmp"))();
+  const logging: PluginRuntime["logging"] | undefined = options.logging
+    ? ({
+        shouldLogVerbose: () => false,
+        getChildLogger: () => ({
+          info: () => {},
+          warn: () => {},
+          error: () => {},
+        }),
+        ...options.logging,
+      } as PluginRuntime["logging"])
+    : undefined;
+
+  setMatrixRuntime({
+    config: {
+      loadConfig: () => options.cfg ?? {},
+    },
+    ...(options.channel ? { channel: options.channel as PluginRuntime["channel"] } : {}),
+    ...(logging ? { logging } : {}),
+    state: {
+      resolveStateDir: defaultStateDirResolver,
+    },
+  } as PluginRuntime);
+}
+
+type MatrixMonitorTestRuntimeOptions = Pick<MatrixTestRuntimeOptions, "cfg" | "stateDir"> & {
+  matchesMentionPatterns?: (text: string, patterns: RegExp[]) => boolean;
+  saveMediaBuffer?: NonNullable<NonNullable<PluginRuntime["channel"]>["media"]>["saveMediaBuffer"];
+};
+
+export function installMatrixMonitorTestRuntime(
+  options: MatrixMonitorTestRuntimeOptions = {},
+): void {
+  installMatrixTestRuntime({
+    cfg: options.cfg,
+    stateDir: options.stateDir,
+    channel: {
+      mentions: {
+        buildMentionRegexes: () => [],
+        matchesMentionPatterns:
+          options.matchesMentionPatterns ??
+          ((text: string, patterns: RegExp[]) => patterns.some((pattern) => pattern.test(text))),
+        matchesMentionWithExplicit: () => false,
+        implicitMentionKindWhen,
+        resolveInboundMentionDecision,
+      },
+      media: {
+        fetchRemoteMedia: vi.fn(),
+        saveMediaBuffer: options.saveMediaBuffer ?? vi.fn(),
+      },
+    },
+  });
+}

package/src/test-support/monitor-route-test-support.ts

@@ -0,0 +1,8 @@
+export {
+  registerSessionBindingAdapter,
+  __testing,
+} from "../../../../src/infra/outbound/session-binding-service.js";
+export { setActivePluginRegistry } from "../../../../src/plugins/runtime.js";
+export { resolveAgentRoute } from "../../../../src/routing/resolve-route.js";
+export { createTestRegistry } from "../../../../src/test-utils/channel-plugins.js";
+export type { OpenClawConfig } from "../../../../src/config/config.js";

package/src/tool-actions.runtime.ts

@@ -0,0 +1 @@
+export { handleMatrixAction } from "./tool-actions.js";