@archipelagolab/lobi 1.0.0

package/src/matrix/accounts.ts

@@ -0,0 +1,194 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { hasConfiguredSecretInput } from "openclaw/plugin-sdk/secret-input";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import {
+  resolveConfiguredMatrixAccountIds,
+  resolveMatrixDefaultOrOnlyAccountId,
+} from "../account-selection.js";
+import { resolveMatrixAccountStringValues } from "../auth-precedence.js";
+import type { CoreConfig, MatrixConfig } from "../types.js";
+import {
+  findMatrixAccountConfig,
+  resolveMatrixAccountConfig,
+  resolveMatrixBaseConfig,
+} from "./account-config.js";
+import { resolveGlobalMatrixEnvConfig, resolveScopedMatrixEnvConfig } from "./client/env-auth.js";
+import { credentialsMatchConfig, loadMatrixCredentials } from "./credentials-read.js";
+
+export type ResolvedMatrixAccount = {
+  accountId: string;
+  enabled: boolean;
+  name?: string;
+  configured: boolean;
+  homeserver?: string;
+  userId?: string;
+  config: MatrixConfig;
+};
+
+function clean(value: unknown): string {
+  return normalizeOptionalString(value) ?? "";
+}
+
+function resolveMatrixAccountAuthView(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  env: NodeJS.ProcessEnv;
+}): {
+  homeserver: string;
+  userId: string;
+  accessToken?: string;
+  password?: string;
+} {
+  const normalizedAccountId = normalizeAccountId(params.accountId);
+  const matrix = resolveMatrixBaseConfig(params.cfg);
+  const account = findMatrixAccountConfig(params.cfg, normalizedAccountId) ?? {};
+  const resolvedStrings = resolveMatrixAccountStringValues({
+    accountId: normalizedAccountId,
+    account: {
+      homeserver: clean(account.homeserver),
+      userId: clean(account.userId),
+      accessToken: typeof account.accessToken === "string" ? clean(account.accessToken) : "",
+      password: typeof account.password === "string" ? clean(account.password) : "",
+      deviceId: clean(account.deviceId),
+      deviceName: clean(account.deviceName),
+    },
+    scopedEnv: resolveScopedMatrixEnvConfig(normalizedAccountId, params.env),
+    channel: {
+      homeserver: clean(matrix.homeserver),
+      userId: clean(matrix.userId),
+      accessToken: typeof matrix.accessToken === "string" ? clean(matrix.accessToken) : "",
+      password: typeof matrix.password === "string" ? clean(matrix.password) : "",
+      deviceId: clean(matrix.deviceId),
+      deviceName: clean(matrix.deviceName),
+    },
+    globalEnv: resolveGlobalMatrixEnvConfig(params.env),
+  });
+  return {
+    homeserver: resolvedStrings.homeserver,
+    userId: resolvedStrings.userId,
+    accessToken: resolvedStrings.accessToken || undefined,
+    password: resolvedStrings.password || undefined,
+  };
+}
+
+function resolveMatrixAccountUserId(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  env?: NodeJS.ProcessEnv;
+}): string | null {
+  const env = params.env ?? process.env;
+  const authView = resolveMatrixAccountAuthView({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    env,
+  });
+  const configuredUserId = authView.userId.trim();
+  if (configuredUserId) {
+    return configuredUserId;
+  }
+
+  const stored = loadMatrixCredentials(env, params.accountId);
+  if (!stored) {
+    return null;
+  }
+  if (authView.homeserver && stored.homeserver !== authView.homeserver) {
+    return null;
+  }
+  if (authView.accessToken && stored.accessToken !== authView.accessToken) {
+    return null;
+  }
+  return stored.userId.trim() || null;
+}
+
+export function listMatrixAccountIds(cfg: CoreConfig): string[] {
+  const ids = resolveConfiguredMatrixAccountIds(cfg, process.env);
+  return ids.length > 0 ? ids : [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultMatrixAccountId(cfg: CoreConfig): string {
+  return normalizeAccountId(resolveMatrixDefaultOrOnlyAccountId(cfg));
+}
+
+export function resolveConfiguredMatrixBotUserIds(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+  env?: NodeJS.ProcessEnv;
+}): Set<string> {
+  const env = params.env ?? process.env;
+  const currentAccountId = normalizeAccountId(params.accountId);
+  const accountIds = new Set(resolveConfiguredMatrixAccountIds(params.cfg, env));
+  if (resolveMatrixAccount({ cfg: params.cfg, accountId: DEFAULT_ACCOUNT_ID, env }).configured) {
+    accountIds.add(DEFAULT_ACCOUNT_ID);
+  }
+  const ids = new Set<string>();
+
+  for (const accountId of accountIds) {
+    if (normalizeAccountId(accountId) === currentAccountId) {
+      continue;
+    }
+    if (!resolveMatrixAccount({ cfg: params.cfg, accountId, env }).configured) {
+      continue;
+    }
+    const userId = resolveMatrixAccountUserId({
+      cfg: params.cfg,
+      accountId,
+      env,
+    });
+    if (userId) {
+      ids.add(userId);
+    }
+  }
+
+  return ids;
+}
+
+export function resolveMatrixAccount(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+  env?: NodeJS.ProcessEnv;
+}): ResolvedMatrixAccount {
+  const env = params.env ?? process.env;
+  const accountId = normalizeAccountId(
+    params.accountId ?? resolveDefaultMatrixAccountId(params.cfg),
+  );
+  const matrixBase = resolveMatrixBaseConfig(params.cfg);
+  const base = resolveMatrixAccountConfig({ cfg: params.cfg, accountId, env });
+  const explicitAuthConfig =
+    accountId === DEFAULT_ACCOUNT_ID
+      ? base
+      : (findMatrixAccountConfig(params.cfg, accountId) ?? {});
+  const enabled = base.enabled !== false && matrixBase.enabled !== false;
+
+  const authView = resolveMatrixAccountAuthView({
+    cfg: params.cfg,
+    accountId,
+    env,
+  });
+  const hasHomeserver = Boolean(authView.homeserver);
+  const hasUserId = Boolean(authView.userId);
+  const hasAccessToken =
+    Boolean(authView.accessToken) || hasConfiguredSecretInput(explicitAuthConfig.accessToken);
+  const hasPassword = Boolean(authView.password);
+  const hasPasswordAuth =
+    hasUserId && (hasPassword || hasConfiguredSecretInput(explicitAuthConfig.password));
+  const stored = loadMatrixCredentials(env, accountId);
+  const hasStored =
+    stored && authView.homeserver
+      ? credentialsMatchConfig(stored, {
+          homeserver: authView.homeserver,
+          userId: authView.userId || "",
+        })
+      : false;
+  const configured = hasHomeserver && (hasAccessToken || hasPasswordAuth || hasStored);
+  return {
+    accountId,
+    enabled,
+    name: normalizeOptionalString(base.name),
+    configured,
+    homeserver: authView.homeserver || undefined,
+    userId: authView.userId || undefined,
+    config: base,
+  };
+}
+
+export { resolveMatrixAccountConfig } from "./account-config.js";

package/src/matrix/actions/client.test.ts

@@ -0,0 +1,215 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createMockMatrixClient,
+  expectExplicitMatrixClientConfig,
+  expectOneOffSharedMatrixClient,
+  matrixClientResolverMocks,
+  primeMatrixClientResolverMocks,
+} from "../client-resolver.test-helpers.js";
+
+const resolveMatrixRoomIdMock = vi.fn();
+
+const {
+  loadConfigMock,
+  getMatrixRuntimeMock,
+  getActiveMatrixClientMock,
+  acquireSharedMatrixClientMock,
+  releaseSharedClientInstanceMock,
+  isBunRuntimeMock,
+  resolveMatrixAuthContextMock,
+} = matrixClientResolverMocks;
+
+vi.mock("../../runtime.js", () => ({
+  getMatrixRuntime: () => getMatrixRuntimeMock(),
+}));
+
+vi.mock("../active-client.js", () => ({
+  getActiveMatrixClient: getActiveMatrixClientMock,
+}));
+
+vi.mock("../client.js", () => ({
+  acquireSharedMatrixClient: acquireSharedMatrixClientMock,
+  isBunRuntime: () => isBunRuntimeMock(),
+  resolveMatrixAuthContext: resolveMatrixAuthContextMock,
+}));
+
+vi.mock("../client/shared.js", () => ({
+  releaseSharedClientInstance: (...args: unknown[]) => releaseSharedClientInstanceMock(...args),
+}));
+
+vi.mock("../send.js", () => ({
+  resolveMatrixRoomId: (...args: unknown[]) => resolveMatrixRoomIdMock(...args),
+}));
+
+let withResolvedActionClient: typeof import("./client.js").withResolvedActionClient;
+let withResolvedRoomAction: typeof import("./client.js").withResolvedRoomAction;
+let withStartedActionClient: typeof import("./client.js").withStartedActionClient;
+
+describe("action client helpers", () => {
+  beforeAll(async () => {
+    ({ withResolvedActionClient, withResolvedRoomAction, withStartedActionClient } =
+      await import("./client.js"));
+  });
+
+  beforeEach(() => {
+    primeMatrixClientResolverMocks();
+    resolveMatrixRoomIdMock
+      .mockReset()
+      .mockImplementation(async (_client, roomId: string) => roomId);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("stops one-off shared clients when no active monitor client is registered", async () => {
+    vi.stubEnv("OPENCLAW_GATEWAY_PORT", "18799");
+
+    const result = await withResolvedActionClient({ accountId: "default" }, async () => "ok");
+
+    await expectOneOffSharedMatrixClient();
+    expect(result).toBe("ok");
+  });
+
+  it("skips one-off room preparation when readiness is disabled", async () => {
+    await withResolvedActionClient({ accountId: "default", readiness: "none" }, async () => {});
+
+    const sharedClient = await acquireSharedMatrixClientMock.mock.results[0]?.value;
+    expect(sharedClient.prepareForOneOff).not.toHaveBeenCalled();
+    expect(sharedClient.start).not.toHaveBeenCalled();
+    expect(releaseSharedClientInstanceMock).toHaveBeenCalledWith(sharedClient, "stop");
+  });
+
+  it("starts one-off clients when started readiness is required", async () => {
+    await withStartedActionClient({ accountId: "default" }, async () => {});
+
+    const sharedClient = await acquireSharedMatrixClientMock.mock.results[0]?.value;
+    expect(sharedClient.start).toHaveBeenCalledTimes(1);
+    expect(sharedClient.prepareForOneOff).not.toHaveBeenCalled();
+    expect(releaseSharedClientInstanceMock).toHaveBeenCalledWith(sharedClient, "persist");
+  });
+
+  it("reuses active monitor client when available", async () => {
+    const activeClient = createMockMatrixClient();
+    getActiveMatrixClientMock.mockReturnValue(activeClient);
+
+    const result = await withResolvedActionClient({ accountId: "default" }, async (client) => {
+      expect(client).toBe(activeClient);
+      return "ok";
+    });
+
+    expect(result).toBe("ok");
+    expect(acquireSharedMatrixClientMock).not.toHaveBeenCalled();
+    expect(activeClient.stop).not.toHaveBeenCalled();
+  });
+
+  it("starts active clients when started readiness is required", async () => {
+    const activeClient = createMockMatrixClient();
+    getActiveMatrixClientMock.mockReturnValue(activeClient);
+
+    await withStartedActionClient({ accountId: "default" }, async (client) => {
+      expect(client).toBe(activeClient);
+    });
+
+    expect(activeClient.start).toHaveBeenCalledTimes(1);
+    expect(activeClient.prepareForOneOff).not.toHaveBeenCalled();
+    expect(activeClient.stop).not.toHaveBeenCalled();
+    expect(activeClient.stopAndPersist).not.toHaveBeenCalled();
+  });
+
+  it("uses the implicit resolved account id for active client lookup and storage", async () => {
+    loadConfigMock.mockReturnValue({
+      channels: {
+        matrix: {
+          accounts: {
+            ops: {
+              homeserver: "https://ops.example.org",
+              userId: "@ops:example.org",
+              accessToken: "ops-token",
+            },
+          },
+        },
+      },
+    });
+    resolveMatrixAuthContextMock.mockReturnValue({
+      cfg: loadConfigMock(),
+      env: process.env,
+      accountId: "ops",
+      resolved: {
+        homeserver: "https://ops.example.org",
+        userId: "@ops:example.org",
+        accessToken: "ops-token",
+        deviceId: "OPSDEVICE",
+        encryption: true,
+      },
+    });
+    await withResolvedActionClient({}, async () => {});
+
+    await expectOneOffSharedMatrixClient({
+      cfg: loadConfigMock(),
+      accountId: "ops",
+    });
+  });
+
+  it("uses explicit cfg instead of loading runtime config", async () => {
+    const explicitCfg = {
+      channels: {
+        matrix: {
+          defaultAccount: "ops",
+        },
+      },
+    };
+
+    await withResolvedActionClient({ cfg: explicitCfg, accountId: "ops" }, async () => {});
+
+    expectExplicitMatrixClientConfig({
+      cfg: explicitCfg,
+      accountId: "ops",
+    });
+  });
+
+  it("stops shared action clients after wrapped calls succeed", async () => {
+    const sharedClient = createMockMatrixClient();
+    acquireSharedMatrixClientMock.mockResolvedValue(sharedClient);
+
+    const result = await withResolvedActionClient({ accountId: "default" }, async (client) => {
+      expect(client).toBe(sharedClient);
+      return "ok";
+    });
+
+    expect(result).toBe("ok");
+    expect(releaseSharedClientInstanceMock).toHaveBeenCalledWith(sharedClient, "stop");
+  });
+
+  it("stops shared action clients when the wrapped call throws", async () => {
+    const sharedClient = createMockMatrixClient();
+    acquireSharedMatrixClientMock.mockResolvedValue(sharedClient);
+
+    await expect(
+      withResolvedActionClient({ accountId: "default" }, async () => {
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+
+    expect(releaseSharedClientInstanceMock).toHaveBeenCalledWith(sharedClient, "stop");
+  });
+
+  it("resolves room ids before running wrapped room actions", async () => {
+    const sharedClient = createMockMatrixClient();
+    acquireSharedMatrixClientMock.mockResolvedValue(sharedClient);
+    resolveMatrixRoomIdMock.mockResolvedValue("!room:example.org");
+
+    const result = await withResolvedRoomAction(
+      "room:#ops:example.org",
+      { accountId: "default" },
+      async (client, resolvedRoom) => {
+        expect(client).toBe(sharedClient);
+        return resolvedRoom;
+      },
+    );
+
+    expect(resolveMatrixRoomIdMock).toHaveBeenCalledWith(sharedClient, "room:#ops:example.org");
+    expect(result).toBe("!room:example.org");
+    expect(releaseSharedClientInstanceMock).toHaveBeenCalledWith(sharedClient, "stop");
+  });
+});

package/src/matrix/actions/client.ts

@@ -0,0 +1,31 @@
+import { withResolvedRuntimeMatrixClient } from "../client-bootstrap.js";
+import { resolveMatrixRoomId } from "../send.js";
+import type { MatrixActionClient, MatrixActionClientOpts } from "./types.js";
+
+type MatrixActionClientStopMode = "stop" | "persist";
+
+export async function withResolvedActionClient<T>(
+  opts: MatrixActionClientOpts,
+  run: (client: MatrixActionClient["client"]) => Promise<T>,
+  mode: MatrixActionClientStopMode = "stop",
+): Promise<T> {
+  return await withResolvedRuntimeMatrixClient(opts, run, mode);
+}
+
+export async function withStartedActionClient<T>(
+  opts: MatrixActionClientOpts,
+  run: (client: MatrixActionClient["client"]) => Promise<T>,
+): Promise<T> {
+  return await withResolvedActionClient({ ...opts, readiness: "started" }, run, "persist");
+}
+
+export async function withResolvedRoomAction<T>(
+  roomId: string,
+  opts: MatrixActionClientOpts,
+  run: (client: MatrixActionClient["client"], resolvedRoom: string) => Promise<T>,
+): Promise<T> {
+  return await withResolvedActionClient(opts, async (client) => {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    return await run(client, resolvedRoom);
+  });
+}

package/src/matrix/actions/devices.test.ts

@@ -0,0 +1,114 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const withStartedActionClientMock = vi.fn();
+
+vi.mock("./client.js", () => ({
+  withStartedActionClient: (...args: unknown[]) => withStartedActionClientMock(...args),
+}));
+
+const { listMatrixOwnDevices, pruneMatrixStaleGatewayDevices } = await import("./devices.js");
+
+describe("matrix device actions", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("lists own devices on a started client", async () => {
+    withStartedActionClientMock.mockImplementation(async (_opts, run) => {
+      return await run({
+        listOwnDevices: vi.fn(async () => [
+          {
+            deviceId: "A7hWrQ70ea",
+            displayName: "OpenClaw Gateway",
+            lastSeenIp: null,
+            lastSeenTs: null,
+            current: true,
+          },
+        ]),
+      });
+    });
+
+    const result = await listMatrixOwnDevices({ accountId: "poe" });
+
+    expect(withStartedActionClientMock).toHaveBeenCalledWith(
+      { accountId: "poe" },
+      expect.any(Function),
+    );
+    expect(result).toEqual([
+      expect.objectContaining({
+        deviceId: "A7hWrQ70ea",
+        current: true,
+      }),
+    ]);
+  });
+
+  it("prunes stale OpenClaw-managed devices but preserves the current device", async () => {
+    const deleteOwnDevices = vi.fn(async () => ({
+      currentDeviceId: "du314Zpw3A",
+      deletedDeviceIds: ["BritdXC6iL", "G6NJU9cTgs", "My3T0hkTE0"],
+      remainingDevices: [
+        {
+          deviceId: "du314Zpw3A",
+          displayName: "OpenClaw Gateway",
+          lastSeenIp: null,
+          lastSeenTs: null,
+          current: true,
+        },
+      ],
+    }));
+    withStartedActionClientMock.mockImplementation(async (_opts, run) => {
+      return await run({
+        listOwnDevices: vi.fn(async () => [
+          {
+            deviceId: "du314Zpw3A",
+            displayName: "OpenClaw Gateway",
+            lastSeenIp: null,
+            lastSeenTs: null,
+            current: true,
+          },
+          {
+            deviceId: "BritdXC6iL",
+            displayName: "OpenClaw Gateway",
+            lastSeenIp: null,
+            lastSeenTs: null,
+            current: false,
+          },
+          {
+            deviceId: "G6NJU9cTgs",
+            displayName: "OpenClaw Debug",
+            lastSeenIp: null,
+            lastSeenTs: null,
+            current: false,
+          },
+          {
+            deviceId: "My3T0hkTE0",
+            displayName: "OpenClaw Gateway",
+            lastSeenIp: null,
+            lastSeenTs: null,
+            current: false,
+          },
+          {
+            deviceId: "phone123",
+            displayName: "Element iPhone",
+            lastSeenIp: null,
+            lastSeenTs: null,
+            current: false,
+          },
+        ]),
+        deleteOwnDevices,
+      });
+    });
+
+    const result = await pruneMatrixStaleGatewayDevices({ accountId: "poe" });
+
+    expect(deleteOwnDevices).toHaveBeenCalledWith(["BritdXC6iL", "G6NJU9cTgs", "My3T0hkTE0"]);
+    expect(result.staleGatewayDeviceIds).toEqual(["BritdXC6iL", "G6NJU9cTgs", "My3T0hkTE0"]);
+    expect(result.deletedDeviceIds).toEqual(["BritdXC6iL", "G6NJU9cTgs", "My3T0hkTE0"]);
+    expect(result.remainingDevices).toEqual([
+      expect.objectContaining({
+        deviceId: "du314Zpw3A",
+        current: true,
+      }),
+    ]);
+  });
+});

package/src/matrix/actions/devices.ts

@@ -0,0 +1,34 @@
+import { summarizeMatrixDeviceHealth } from "../device-health.js";
+import { withStartedActionClient } from "./client.js";
+import type { MatrixActionClientOpts } from "./types.js";
+
+export async function listMatrixOwnDevices(opts: MatrixActionClientOpts = {}) {
+  return await withStartedActionClient(opts, async (client) => await client.listOwnDevices());
+}
+
+export async function pruneMatrixStaleGatewayDevices(opts: MatrixActionClientOpts = {}) {
+  return await withStartedActionClient(opts, async (client) => {
+    const devices = await client.listOwnDevices();
+    const health = summarizeMatrixDeviceHealth(devices);
+    const staleGatewayDeviceIds = health.staleOpenClawDevices.map((device) => device.deviceId);
+    const deleted =
+      staleGatewayDeviceIds.length > 0
+        ? await client.deleteOwnDevices(staleGatewayDeviceIds)
+        : {
+            currentDeviceId: devices.find((device) => device.current)?.deviceId ?? null,
+            deletedDeviceIds: [] as string[],
+            remainingDevices: devices,
+          };
+    return {
+      before: devices,
+      staleGatewayDeviceIds,
+      ...deleted,
+    };
+  });
+}
+
+export async function getMatrixDeviceHealth(opts: MatrixActionClientOpts = {}) {
+  return await withStartedActionClient(opts, async (client) =>
+    summarizeMatrixDeviceHealth(await client.listOwnDevices()),
+  );
+}

package/src/matrix/actions/limits.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { resolveMatrixActionLimit } from "./limits.js";
+
+describe("resolveMatrixActionLimit", () => {
+  it("uses fallback for non-finite values", () => {
+    expect(resolveMatrixActionLimit(undefined, 20)).toBe(20);
+    expect(resolveMatrixActionLimit(Number.NaN, 20)).toBe(20);
+  });
+
+  it("normalizes finite numbers to positive integers", () => {
+    expect(resolveMatrixActionLimit(7.9, 20)).toBe(7);
+    expect(resolveMatrixActionLimit(0, 20)).toBe(1);
+    expect(resolveMatrixActionLimit(-3, 20)).toBe(1);
+  });
+});

package/src/matrix/actions/limits.ts

@@ -0,0 +1,6 @@
+export function resolveMatrixActionLimit(raw: unknown, fallback: number): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    return fallback;
+  }
+  return Math.max(1, Math.floor(raw));
+}