@archipelagolab/lobi 1.0.0

package/src/matrix/deps.ts

@@ -0,0 +1,225 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import type { RuntimeEnv } from "../runtime-api.js";
+
+const REQUIRED_MATRIX_PACKAGES = [
+  "@archipelagolab/lobi-js-sdk",
+  "@matrix-org/matrix-sdk-crypto-nodejs",
+  "@matrix-org/matrix-sdk-crypto-wasm",
+];
+
+type MatrixCryptoRuntimeDeps = {
+  requireFn?: (id: string) => unknown;
+  runCommand?: (params: {
+    argv: string[];
+    cwd: string;
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+  }) => Promise<CommandResult>;
+  resolveFn?: (id: string) => string;
+  nodeExecutable?: string;
+  log?: (message: string) => void;
+};
+
+function resolveMissingMatrixPackages(): string[] {
+  try {
+    const req = createRequire(import.meta.url);
+    return REQUIRED_MATRIX_PACKAGES.filter((pkg) => {
+      try {
+        req.resolve(pkg);
+        return false;
+      } catch {
+        return true;
+      }
+    });
+  } catch {
+    return [...REQUIRED_MATRIX_PACKAGES];
+  }
+}
+
+export function isMatrixSdkAvailable(): boolean {
+  return resolveMissingMatrixPackages().length === 0;
+}
+
+function resolvePluginRoot(): string {
+  const currentDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(currentDir, "..", "..");
+}
+
+type CommandResult = {
+  code: number;
+  stdout: string;
+  stderr: string;
+};
+
+async function runFixedCommandWithTimeout(params: {
+  argv: string[];
+  cwd: string;
+  timeoutMs: number;
+  env?: NodeJS.ProcessEnv;
+}): Promise<CommandResult> {
+  return await new Promise((resolve) => {
+    const [command, ...args] = params.argv;
+    if (!command) {
+      resolve({
+        code: 1,
+        stdout: "",
+        stderr: "command is required",
+      });
+      return;
+    }
+
+    const proc = spawn(command, args, {
+      cwd: params.cwd,
+      env: { ...process.env, ...params.env },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timer: NodeJS.Timeout | null = null;
+
+    const finalize = (result: CommandResult) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      resolve(result);
+    };
+
+    proc.stdout?.on("data", (chunk: Buffer | string) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr?.on("data", (chunk: Buffer | string) => {
+      stderr += chunk.toString();
+    });
+
+    timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      finalize({
+        code: 124,
+        stdout,
+        stderr: stderr || `command timed out after ${params.timeoutMs}ms`,
+      });
+    }, params.timeoutMs);
+
+    proc.on("error", (err) => {
+      finalize({
+        code: 1,
+        stdout,
+        stderr: err.message,
+      });
+    });
+
+    proc.on("close", (code) => {
+      finalize({
+        code: code ?? 1,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+function defaultRequireFn(id: string): unknown {
+  return createRequire(import.meta.url)(id);
+}
+
+function defaultResolveFn(id: string): string {
+  return createRequire(import.meta.url).resolve(id);
+}
+
+function isMissingMatrixCryptoRuntimeError(error: unknown): boolean {
+  const message = formatErrorMessage(error);
+  return (
+    message.includes("@matrix-org/matrix-sdk-crypto-nodejs-") ||
+    message.includes("matrix-sdk-crypto-nodejs") ||
+    message.includes("download-lib.js")
+  );
+}
+
+export async function ensureMatrixCryptoRuntime(
+  params: MatrixCryptoRuntimeDeps = {},
+): Promise<void> {
+  const requireFn = params.requireFn ?? defaultRequireFn;
+  try {
+    requireFn("@matrix-org/matrix-sdk-crypto-nodejs");
+    return;
+  } catch (err) {
+    if (!isMissingMatrixCryptoRuntimeError(err)) {
+      throw err;
+    }
+  }
+
+  const resolveFn = params.resolveFn ?? defaultResolveFn;
+  const scriptPath = resolveFn("@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js");
+  params.log?.("matrix: bootstrapping native crypto runtime");
+  const runCommand = params.runCommand ?? runFixedCommandWithTimeout;
+  const nodeExecutable = params.nodeExecutable ?? process.execPath;
+  const result = await runCommand({
+    argv: [nodeExecutable, scriptPath],
+    cwd: path.dirname(scriptPath),
+    timeoutMs: 300_000,
+    env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+  });
+  if (result.code !== 0) {
+    throw new Error(
+      result.stderr.trim() || result.stdout.trim() || "Matrix crypto runtime bootstrap failed.",
+    );
+  }
+
+  requireFn("@matrix-org/matrix-sdk-crypto-nodejs");
+}
+
+export async function ensureMatrixSdkInstalled(params: {
+  runtime: RuntimeEnv;
+  confirm?: (message: string) => Promise<boolean>;
+}): Promise<void> {
+  if (isMatrixSdkAvailable()) {
+    return;
+  }
+  const confirm = params.confirm;
+  if (confirm) {
+    const ok = await confirm(
+      "Matrix requires @archipelagolab/lobi-js-sdk, @matrix-org/matrix-sdk-crypto-nodejs, and @matrix-org/matrix-sdk-crypto-wasm. Install now?",
+    );
+    if (!ok) {
+      throw new Error(
+        "Matrix requires @archipelagolab/lobi-js-sdk, @matrix-org/matrix-sdk-crypto-nodejs, and @matrix-org/matrix-sdk-crypto-wasm (install dependencies first).",
+      );
+    }
+  }
+
+  const root = resolvePluginRoot();
+  const command = fs.existsSync(path.join(root, "pnpm-lock.yaml"))
+    ? ["pnpm", "install"]
+    : ["npm", "install", "--omit=dev", "--silent"];
+  params.runtime.log?.(`matrix: installing dependencies via ${command[0]} (${root})…`);
+  const result = await runFixedCommandWithTimeout({
+    argv: command,
+    cwd: root,
+    timeoutMs: 300_000,
+    env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },
+  });
+  if (result.code !== 0) {
+    throw new Error(
+      result.stderr.trim() || result.stdout.trim() || "Matrix dependency install failed.",
+    );
+  }
+  if (!isMatrixSdkAvailable()) {
+    const missing = resolveMissingMatrixPackages();
+    throw new Error(
+      missing.length > 0
+        ? `Matrix dependency install completed but required packages are still missing: ${missing.join(", ")}`
+        : "Matrix dependency install completed but Matrix dependencies are still missing.",
+    );
+  }
+}

package/src/matrix/device-health.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { isOpenClawManagedMatrixDevice, summarizeMatrixDeviceHealth } from "./device-health.js";
+
+describe("matrix device health", () => {
+  it("detects OpenClaw-managed device names", () => {
+    expect(isOpenClawManagedMatrixDevice("OpenClaw Gateway")).toBe(true);
+    expect(isOpenClawManagedMatrixDevice("OpenClaw Debug")).toBe(true);
+    expect(isOpenClawManagedMatrixDevice("Element iPhone")).toBe(false);
+    expect(isOpenClawManagedMatrixDevice(null)).toBe(false);
+  });
+
+  it("summarizes stale OpenClaw-managed devices separately from the current device", () => {
+    const summary = summarizeMatrixDeviceHealth([
+      {
+        deviceId: "du314Zpw3A",
+        displayName: "OpenClaw Gateway",
+        current: true,
+      },
+      {
+        deviceId: "BritdXC6iL",
+        displayName: "OpenClaw Gateway",
+        current: false,
+      },
+      {
+        deviceId: "G6NJU9cTgs",
+        displayName: "OpenClaw Debug",
+        current: false,
+      },
+      {
+        deviceId: "phone123",
+        displayName: "Element iPhone",
+        current: false,
+      },
+    ]);
+
+    expect(summary.currentDeviceId).toBe("du314Zpw3A");
+    expect(summary.currentOpenClawDevices).toEqual([
+      expect.objectContaining({ deviceId: "du314Zpw3A" }),
+    ]);
+    expect(summary.staleOpenClawDevices).toEqual([
+      expect.objectContaining({ deviceId: "BritdXC6iL" }),
+      expect.objectContaining({ deviceId: "G6NJU9cTgs" }),
+    ]);
+  });
+});

package/src/matrix/device-health.ts

@@ -0,0 +1,31 @@
+export type MatrixManagedDeviceInfo = {
+  deviceId: string;
+  displayName: string | null;
+  current: boolean;
+};
+
+export type MatrixDeviceHealthSummary = {
+  currentDeviceId: string | null;
+  staleOpenClawDevices: MatrixManagedDeviceInfo[];
+  currentOpenClawDevices: MatrixManagedDeviceInfo[];
+};
+
+const OPENCLAW_DEVICE_NAME_PREFIX = "OpenClaw ";
+
+export function isOpenClawManagedMatrixDevice(displayName: string | null | undefined): boolean {
+  return displayName?.startsWith(OPENCLAW_DEVICE_NAME_PREFIX) === true;
+}
+
+export function summarizeMatrixDeviceHealth(
+  devices: MatrixManagedDeviceInfo[],
+): MatrixDeviceHealthSummary {
+  const currentDeviceId = devices.find((device) => device.current)?.deviceId ?? null;
+  const openClawDevices = devices.filter((device) =>
+    isOpenClawManagedMatrixDevice(device.displayName),
+  );
+  return {
+    currentDeviceId,
+    staleOpenClawDevices: openClawDevices.filter((device) => !device.current),
+    currentOpenClawDevices: openClawDevices.filter((device) => device.current),
+  };
+}

package/src/matrix/direct-management.test.ts

@@ -0,0 +1,350 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  inspectMatrixDirectRooms,
+  persistMatrixDirectRoomMapping,
+  promoteMatrixDirectRoomCandidate,
+  repairMatrixDirectRooms,
+} from "./direct-management.js";
+import type { MatrixClient } from "./sdk.js";
+import { EventType } from "./send/types.js";
+
+function createClient(overrides: Partial<MatrixClient> = {}): MatrixClient {
+  return {
+    getUserId: vi.fn(async () => "@bot:example.org"),
+    getAccountData: vi.fn(async () => undefined),
+    getJoinedRooms: vi.fn(async () => [] as string[]),
+    getJoinedRoomMembers: vi.fn(async () => [] as string[]),
+    getRoomStateEvent: vi.fn(async () => ({})),
+    setAccountData: vi.fn(async () => undefined),
+    createDirectRoom: vi.fn(async () => "!created:example.org"),
+    ...overrides,
+  } as unknown as MatrixClient;
+}
+
+describe("inspectMatrixDirectRooms", () => {
+  it("prefers strict mapped rooms over discovered rooms", async () => {
+    const client = createClient({
+      getAccountData: vi.fn(async () => ({
+        "@alice:example.org": ["!dm:example.org", "!shared:example.org"],
+      })),
+      getJoinedRooms: vi.fn(async () => ["!dm:example.org", "!shared:example.org"]),
+      getJoinedRoomMembers: vi.fn(async (roomId: string) =>
+        roomId === "!dm:example.org"
+          ? ["@bot:example.org", "@alice:example.org"]
+          : ["@bot:example.org", "@alice:example.org", "@mallory:example.org"],
+      ),
+    });
+
+    const result = await inspectMatrixDirectRooms({
+      client,
+      remoteUserId: "@alice:example.org",
+    });
+
+    expect(result.activeRoomId).toBe("!dm:example.org");
+    expect(result.mappedRooms).toEqual([
+      expect.objectContaining({ roomId: "!dm:example.org", strict: true }),
+      expect.objectContaining({ roomId: "!shared:example.org", strict: false }),
+    ]);
+  });
+
+  it("falls back to discovered strict joined rooms when m.direct is stale", async () => {
+    const client = createClient({
+      getAccountData: vi.fn(async () => ({
+        "@alice:example.org": ["!stale:example.org"],
+      })),
+      getJoinedRooms: vi.fn(async () => ["!stale:example.org", "!fresh:example.org"]),
+      getJoinedRoomMembers: vi.fn(async (roomId: string) =>
+        roomId === "!fresh:example.org"
+          ? ["@bot:example.org", "@alice:example.org"]
+          : ["@bot:example.org", "@alice:example.org", "@mallory:example.org"],
+      ),
+    });
+
+    const result = await inspectMatrixDirectRooms({
+      client,
+      remoteUserId: "@alice:example.org",
+    });
+
+    expect(result.activeRoomId).toBe("!fresh:example.org");
+    expect(result.discoveredStrictRoomIds).toEqual(["!fresh:example.org"]);
+  });
+
+  it("prefers discovered rooms marked direct in local member state over plain strict rooms", async () => {
+    const client = createClient({
+      getJoinedRooms: vi.fn(async () => ["!fallback:example.org", "!explicit:example.org"]),
+      getJoinedRoomMembers: vi.fn(async () => ["@bot:example.org", "@alice:example.org"]),
+      getRoomStateEvent: vi.fn(async (roomId: string, _eventType: string, userId: string) =>
+        roomId === "!explicit:example.org" && userId === "@bot:example.org"
+          ? { is_direct: true }
+          : {},
+      ),
+    });
+
+    const result = await inspectMatrixDirectRooms({
+      client,
+      remoteUserId: "@alice:example.org",
+    });
+
+    expect(result.activeRoomId).toBe("!explicit:example.org");
+    expect(result.discoveredStrictRoomIds).toEqual([
+      "!fallback:example.org",
+      "!explicit:example.org",
+    ]);
+  });
+
+  it("ignores remote member-state direct flags when ranking discovered rooms", async () => {
+    const client = createClient({
+      getJoinedRooms: vi.fn(async () => ["!fallback:example.org", "!remote-marked:example.org"]),
+      getJoinedRoomMembers: vi.fn(async () => ["@bot:example.org", "@alice:example.org"]),
+      getRoomStateEvent: vi.fn(async (roomId: string, _eventType: string, userId: string) =>
+        roomId === "!remote-marked:example.org" && userId === "@alice:example.org"
+          ? { is_direct: true }
+          : {},
+      ),
+    });
+
+    const result = await inspectMatrixDirectRooms({
+      client,
+      remoteUserId: "@alice:example.org",
+    });
+
+    expect(result.activeRoomId).toBe("!fallback:example.org");
+  });
+
+  it("does not treat discovered rooms with local is_direct false as active DMs", async () => {
+    const client = createClient({
+      getJoinedRooms: vi.fn(async () => ["!blocked:example.org"]),
+      getJoinedRoomMembers: vi.fn(async () => ["@bot:example.org", "@alice:example.org"]),
+      getRoomStateEvent: vi.fn(async (_roomId: string, _eventType: string, userId: string) => ({
+        is_direct: userId === "@bot:example.org" ? false : undefined,
+      })),
+    });
+
+    const result = await inspectMatrixDirectRooms({
+      client,
+      remoteUserId: "@alice:example.org",
+    });
+
+    expect(result.activeRoomId).toBeNull();
+    expect(result.discoveredStrictRoomIds).toEqual([]);
+  });
+});
+
+describe("repairMatrixDirectRooms", () => {
+  it("repoints m.direct to an existing strict joined room", async () => {
+    const setAccountData = vi.fn(async () => undefined);
+    const client = createClient({
+      getAccountData: vi.fn(async () => ({
+        "@alice:example.org": ["!stale:example.org"],
+      })),
+      getJoinedRooms: vi.fn(async () => ["!stale:example.org", "!fresh:example.org"]),
+      getJoinedRoomMembers: vi.fn(async (roomId: string) =>
+        roomId === "!fresh:example.org"
+          ? ["@bot:example.org", "@alice:example.org"]
+          : ["@bot:example.org", "@alice:example.org", "@mallory:example.org"],
+      ),
+      setAccountData,
+    });
+
+    const result = await repairMatrixDirectRooms({
+      client,
+      remoteUserId: "@alice:example.org",
+      encrypted: true,
+    });
+
+    expect(result.activeRoomId).toBe("!fresh:example.org");
+    expect(result.createdRoomId).toBeNull();
+    expect(setAccountData).toHaveBeenCalledWith(
+      EventType.Direct,
+      expect.objectContaining({
+        "@alice:example.org": ["!fresh:example.org", "!stale:example.org"],
+      }),
+    );
+  });
+
+  it("creates a fresh direct room when no healthy DM exists", async () => {
+    const createDirectRoom = vi.fn(async () => "!created:example.org");
+    const setAccountData = vi.fn(async () => undefined);
+    const client = createClient({
+      getJoinedRooms: vi.fn(async () => ["!shared:example.org"]),
+      getJoinedRoomMembers: vi.fn(async () => [
+        "@bot:example.org",
+        "@alice:example.org",
+        "@mallory:example.org",
+      ]),
+      createDirectRoom,
+      setAccountData,
+    });
+
+    const result = await repairMatrixDirectRooms({
+      client,
+      remoteUserId: "@alice:example.org",
+      encrypted: true,
+    });
+
+    expect(createDirectRoom).toHaveBeenCalledWith("@alice:example.org", { encrypted: true });
+    expect(result.createdRoomId).toBe("!created:example.org");
+    expect(setAccountData).toHaveBeenCalledWith(
+      EventType.Direct,
+      expect.objectContaining({
+        "@alice:example.org": ["!created:example.org"],
+      }),
+    );
+  });
+
+  it("rejects unqualified Matrix user ids", async () => {
+    const client = createClient();
+
+    await expect(
+      repairMatrixDirectRooms({
+        client,
+        remoteUserId: "alice",
+      }),
+    ).rejects.toThrow('Matrix user IDs must be fully qualified (got "alice")');
+  });
+});
+
+describe("promoteMatrixDirectRoomCandidate", () => {
+  it("classifies a strict room as direct and repairs m.direct", async () => {
+    const setAccountData = vi.fn(async () => undefined);
+    const client = createClient({
+      getJoinedRoomMembers: vi.fn(async () => ["@bot:example.org", "@alice:example.org"]),
+      setAccountData,
+    });
+
+    const result = await promoteMatrixDirectRoomCandidate({
+      client,
+      remoteUserId: "@alice:example.org",
+      roomId: "!fresh:example.org",
+    });
+
+    expect(result).toEqual({
+      classifyAsDirect: true,
+      repaired: true,
+      roomId: "!fresh:example.org",
+      reason: "promoted",
+    });
+    expect(setAccountData).toHaveBeenCalledWith(
+      EventType.Direct,
+      expect.objectContaining({
+        "@alice:example.org": ["!fresh:example.org"],
+      }),
+    );
+  });
+
+  it("does not classify rooms with local is_direct false as direct", async () => {
+    const setAccountData = vi.fn(async () => undefined);
+    const client = createClient({
+      getJoinedRoomMembers: vi.fn(async () => ["@bot:example.org", "@alice:example.org"]),
+      getRoomStateEvent: vi.fn(async (_roomId: string, _eventType: string, stateKey: string) =>
+        stateKey === "@bot:example.org" ? { is_direct: false } : {},
+      ),
+      setAccountData,
+    });
+
+    const result = await promoteMatrixDirectRoomCandidate({
+      client,
+      remoteUserId: "@alice:example.org",
+      roomId: "!blocked:example.org",
+    });
+
+    expect(result).toEqual({
+      classifyAsDirect: false,
+      repaired: false,
+      reason: "local-explicit-false",
+    });
+    expect(setAccountData).not.toHaveBeenCalled();
+  });
+
+  it("returns already-mapped without rewriting account data", async () => {
+    const setAccountData = vi.fn(async () => undefined);
+    const client = createClient({
+      getAccountData: vi.fn(async () => ({
+        "@alice:example.org": ["!mapped:example.org", "!older:example.org"],
+      })),
+      getJoinedRoomMembers: vi.fn(async () => ["@bot:example.org", "@alice:example.org"]),
+      setAccountData,
+    });
+
+    const result = await promoteMatrixDirectRoomCandidate({
+      client,
+      remoteUserId: "@alice:example.org",
+      roomId: "!mapped:example.org",
+    });
+
+    expect(result).toEqual({
+      classifyAsDirect: true,
+      repaired: false,
+      roomId: "!mapped:example.org",
+      reason: "already-mapped",
+    });
+    expect(setAccountData).not.toHaveBeenCalled();
+  });
+
+  it("still classifies the room as direct when repair fails", async () => {
+    const client = createClient({
+      getJoinedRoomMembers: vi.fn(async () => ["@bot:example.org", "@alice:example.org"]),
+      setAccountData: vi.fn(async () => {
+        throw new Error("account data unavailable");
+      }),
+    });
+
+    const result = await promoteMatrixDirectRoomCandidate({
+      client,
+      remoteUserId: "@alice:example.org",
+      roomId: "!fresh:example.org",
+    });
+
+    expect(result).toEqual({
+      classifyAsDirect: true,
+      repaired: false,
+      roomId: "!fresh:example.org",
+      reason: "repair-failed",
+    });
+  });
+
+  it("serializes concurrent m.direct writes so distinct mappings are not lost", async () => {
+    let directContent: Record<string, string[]> = {};
+    let releaseFirstWrite!: () => void;
+    const firstWriteStarted = new Promise<void>((resolve) => {
+      releaseFirstWrite = () => {
+        resolve();
+      };
+    });
+    let writeCount = 0;
+    const setAccountData = vi.fn(async (_eventType: string, content: Record<string, string[]>) => {
+      writeCount += 1;
+      if (writeCount === 1) {
+        await firstWriteStarted;
+      }
+      directContent = { ...content };
+    });
+    const client = createClient({
+      getAccountData: vi.fn(async () => ({ ...directContent })),
+      setAccountData,
+    });
+
+    const firstWrite = persistMatrixDirectRoomMapping({
+      client,
+      remoteUserId: "@alice:example.org",
+      roomId: "!alice:example.org",
+    });
+    await vi.waitFor(() => {
+      expect(setAccountData).toHaveBeenCalledTimes(1);
+    });
+
+    const secondWrite = persistMatrixDirectRoomMapping({
+      client,
+      remoteUserId: "@bob:example.org",
+      roomId: "!bob:example.org",
+    });
+
+    releaseFirstWrite();
+    await expect(Promise.all([firstWrite, secondWrite])).resolves.toEqual([true, true]);
+
+    expect(directContent).toEqual({
+      "@alice:example.org": ["!alice:example.org"],
+      "@bob:example.org": ["!bob:example.org"],
+    });
+  });
+});