@archipelagolab/lobi 1.0.0

package/src/matrix/client.ts

@@ -0,0 +1,23 @@
+export type { MatrixAuth } from "./client/types.js";
+export { isBunRuntime } from "./client/runtime.js";
+export { getLobiScopedEnvVarNames as getMatrixScopedEnvVarNames } from "../env-vars.js";
+export {
+  backfillMatrixAuthDeviceIdAfterStartup,
+  hasReadyMatrixEnvAuth,
+  resolveMatrixEnvAuthReadiness,
+  resolveMatrixConfigForAccount,
+  resolveScopedMatrixEnvConfig,
+  resolveMatrixAuth,
+  resolveMatrixAuthContext,
+  resolveValidatedMatrixHomeserverUrl,
+  validateMatrixHomeserverUrl,
+} from "./client/config.js";
+export { createMatrixClient } from "./client/create-client.js";
+export {
+  acquireSharedMatrixClient,
+  removeSharedClientInstance,
+  releaseSharedClientInstance,
+  resolveSharedMatrixClient,
+  stopSharedClientForAccount,
+  stopSharedClientInstance,
+} from "./client/shared.js";

package/src/matrix/config-paths.ts

@@ -0,0 +1,31 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type { CoreConfig } from "../types.js";
+
+export function shouldStoreMatrixAccountAtTopLevel(cfg: CoreConfig, accountId: string): boolean {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  if (normalizedAccountId !== DEFAULT_ACCOUNT_ID) {
+    return false;
+  }
+  const accounts = cfg.channels?.lobi?.accounts;
+  return !accounts || Object.keys(accounts).length === 0;
+}
+
+export function resolveMatrixConfigPath(cfg: CoreConfig, accountId: string): string {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  if (shouldStoreMatrixAccountAtTopLevel(cfg, normalizedAccountId)) {
+    return "channels.lobi";
+  }
+  return `channels.lobi.accounts.${normalizedAccountId}`;
+}
+
+export function resolveMatrixConfigFieldPath(
+  cfg: CoreConfig,
+  accountId: string,
+  fieldPath: string,
+): string {
+  const suffix = fieldPath.trim().replace(/^\.+/, "");
+  if (!suffix) {
+    return resolveMatrixConfigPath(cfg, accountId);
+  }
+  return `${resolveMatrixConfigPath(cfg, accountId)}.${suffix}`;
+}

package/src/matrix/config-update.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "vitest";
+import type { CoreConfig } from "../types.js";
+import { resolveMatrixConfigFieldPath, updateMatrixAccountConfig } from "./config-update.js";
+
+describe("updateMatrixAccountConfig", () => {
+  it("resolves account-aware Matrix config field paths", () => {
+    expect(resolveMatrixConfigFieldPath({} as CoreConfig, "default", "dm.policy")).toBe(
+      "channels.lobi.dm.policy",
+    );
+
+    const cfg = {
+      channels: {
+        matrix: {
+          accounts: {
+            ops: {},
+          },
+        },
+      },
+    } as CoreConfig;
+
+    expect(resolveMatrixConfigFieldPath(cfg, "ops", ".dm.allowFrom")).toBe(
+      "channels.lobi.accounts.ops.dm.allowFrom",
+    );
+  });
+
+  it("supports explicit null clears and boolean false values", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accounts: {
+            default: {
+              homeserver: "https://matrix.example.org",
+              userId: "@bot:example.org",
+              accessToken: "old-token", // pragma: allowlist secret
+              password: "old-password", // pragma: allowlist secret
+              encryption: true,
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const updated = updateMatrixAccountConfig(cfg, "default", {
+      accessToken: "new-token",
+      password: null,
+      userId: null,
+      encryption: false,
+    });
+
+    expect(updated.channels?.["matrix"]?.accounts?.default).toMatchObject({
+      accessToken: "new-token",
+      encryption: false,
+    });
+    expect(updated.channels?.["matrix"]?.accounts?.default?.password).toBeUndefined();
+    expect(updated.channels?.["matrix"]?.accounts?.default?.userId).toBeUndefined();
+  });
+
+  it("preserves SecretRef auth inputs when updating config", () => {
+    const updated = updateMatrixAccountConfig({} as CoreConfig, "default", {
+      accessToken: { source: "env", provider: "default", id: "LOBI_ACCESS_TOKEN" },
+      password: { source: "env", provider: "default", id: "LOBI_PASSWORD" },
+    });
+
+    expect(updated.channels?.matrix?.accessToken).toEqual({
+      source: "env",
+      provider: "default",
+      id: "LOBI_ACCESS_TOKEN",
+    });
+    expect(updated.channels?.matrix?.password).toEqual({
+      source: "env",
+      provider: "default",
+      id: "LOBI_PASSWORD",
+    });
+  });
+
+  it("stores and clears Matrix allowBots, allowPrivateNetwork, and proxy settings", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accounts: {
+            default: {
+              allowBots: true,
+              network: {
+                dangerouslyAllowPrivateNetwork: true,
+              },
+              proxy: "http://127.0.0.1:7890",
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const updated = updateMatrixAccountConfig(cfg, "default", {
+      allowBots: "mentions",
+      allowPrivateNetwork: null,
+      proxy: null,
+    });
+
+    expect(updated.channels?.["matrix"]?.accounts?.default).toMatchObject({
+      allowBots: "mentions",
+    });
+    expect(updated.channels?.["matrix"]?.accounts?.default?.network).toBeUndefined();
+    expect(updated.channels?.["matrix"]?.accounts?.default?.proxy).toBeUndefined();
+  });
+
+  it("stores and clears Matrix invite auto-join settings", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accounts: {
+            default: {
+              autoJoin: "allowlist",
+              autoJoinAllowlist: ["#ops:example.org"],
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const allowlistUpdated = updateMatrixAccountConfig(cfg, "default", {
+      autoJoin: "allowlist",
+      autoJoinAllowlist: ["!ops-room:example.org", "#ops:example.org"],
+    });
+    expect(allowlistUpdated.channels?.matrix?.accounts?.default).toMatchObject({
+      autoJoin: "allowlist",
+      autoJoinAllowlist: ["!ops-room:example.org", "#ops:example.org"],
+    });
+
+    const offUpdated = updateMatrixAccountConfig(cfg, "default", {
+      autoJoin: "off",
+      autoJoinAllowlist: null,
+    });
+    expect(offUpdated.channels?.matrix?.accounts?.default?.autoJoin).toBe("off");
+    expect(offUpdated.channels?.matrix?.accounts?.default?.autoJoinAllowlist).toBeUndefined();
+
+    const alwaysUpdated = updateMatrixAccountConfig(cfg, "default", {
+      autoJoin: "always",
+      autoJoinAllowlist: null,
+    });
+    expect(alwaysUpdated.channels?.matrix?.accounts?.default?.autoJoin).toBe("always");
+    expect(alwaysUpdated.channels?.matrix?.accounts?.default?.autoJoinAllowlist).toBeUndefined();
+  });
+
+  it("normalizes account id and defaults account enabled=true", () => {
+    const updated = updateMatrixAccountConfig({} as CoreConfig, "Main Bot", {
+      name: "Main Bot",
+      homeserver: "https://matrix.example.org",
+    });
+
+    expect(updated.channels?.["matrix"]?.accounts?.["main-bot"]).toMatchObject({
+      name: "Main Bot",
+      homeserver: "https://matrix.example.org",
+      enabled: true,
+    });
+  });
+
+  it("updates nested access config for named accounts without touching top-level defaults", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          dm: {
+            policy: "pairing",
+          },
+          groups: {
+            "!default:example.org": { enabled: true },
+          },
+          accounts: {
+            ops: {
+              homeserver: "https://matrix.ops.example.org",
+              accessToken: "ops-token",
+              dm: {
+                enabled: true,
+                policy: "pairing",
+              },
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const updated = updateMatrixAccountConfig(cfg, "ops", {
+      dm: {
+        policy: "allowlist",
+        allowFrom: ["@alice:example.org"],
+      },
+      groupPolicy: "allowlist",
+      groups: {
+        "!ops-room:example.org": { enabled: true },
+      },
+      rooms: null,
+    });
+
+    expect(updated.channels?.["matrix"]?.dm?.policy).toBe("pairing");
+    expect(updated.channels?.["matrix"]?.groups).toEqual({
+      "!default:example.org": { enabled: true },
+    });
+    expect(updated.channels?.["matrix"]?.accounts?.ops).toMatchObject({
+      dm: {
+        enabled: true,
+        policy: "allowlist",
+        allowFrom: ["@alice:example.org"],
+      },
+      groupPolicy: "allowlist",
+      groups: {
+        "!ops-room:example.org": { enabled: true },
+      },
+    });
+    expect(updated.channels?.["matrix"]?.accounts?.ops?.rooms).toBeUndefined();
+  });
+
+  it("reuses and canonicalizes non-normalized account entries when updating", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accounts: {
+            Ops: {
+              homeserver: "https://matrix.ops.example.org",
+              accessToken: "ops-token",
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const updated = updateMatrixAccountConfig(cfg, "ops", {
+      deviceName: "Ops Bot",
+    });
+
+    expect(updated.channels?.["matrix"]?.accounts?.Ops).toBeUndefined();
+    expect(updated.channels?.["matrix"]?.accounts?.ops).toMatchObject({
+      homeserver: "https://matrix.ops.example.org",
+      accessToken: "ops-token",
+      deviceName: "Ops Bot",
+      enabled: true,
+    });
+  });
+});

package/src/matrix/config-update.ts

@@ -0,0 +1,291 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { coerceSecretRef } from "openclaw/plugin-sdk/config-runtime";
+import { normalizeSecretInputString } from "openclaw/plugin-sdk/setup";
+import type { CoreConfig, MatrixConfig } from "../types.js";
+import { findMatrixAccountConfig } from "./account-config.js";
+import {
+  resolveMatrixConfigFieldPath,
+  resolveMatrixConfigPath,
+  shouldStoreMatrixAccountAtTopLevel,
+} from "./config-paths.js";
+
+export {
+  resolveMatrixConfigFieldPath,
+  resolveMatrixConfigPath,
+  shouldStoreMatrixAccountAtTopLevel,
+} from "./config-paths.js";
+
+export type MatrixAccountPatch = {
+  name?: string | null;
+  enabled?: boolean;
+  homeserver?: string | null;
+  allowPrivateNetwork?: boolean | null;
+  proxy?: string | null;
+  userId?: string | null;
+  accessToken?: MatrixConfig["accessToken"] | null;
+  password?: MatrixConfig["password"] | null;
+  deviceId?: string | null;
+  deviceName?: string | null;
+  avatarUrl?: string | null;
+  encryption?: boolean | null;
+  initialSyncLimit?: number | null;
+  allowBots?: MatrixConfig["allowBots"] | null;
+  autoJoin?: MatrixConfig["autoJoin"] | null;
+  autoJoinAllowlist?: MatrixConfig["autoJoinAllowlist"] | null;
+  dm?: MatrixConfig["dm"] | null;
+  groupPolicy?: MatrixConfig["groupPolicy"] | null;
+  groupAllowFrom?: MatrixConfig["groupAllowFrom"] | null;
+  groups?: MatrixConfig["groups"] | null;
+  rooms?: MatrixConfig["rooms"] | null;
+};
+
+function applyNullableStringField(
+  target: Record<string, unknown>,
+  key: keyof MatrixAccountPatch,
+  value: string | null | undefined,
+): void {
+  if (value === undefined) {
+    return;
+  }
+  if (value === null) {
+    delete target[key];
+    return;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    delete target[key];
+    return;
+  }
+  target[key] = trimmed;
+}
+
+function applyNullableSecretInputField(
+  target: Record<string, unknown>,
+  key: "accessToken" | "password",
+  value: MatrixConfig["accessToken"] | null | undefined,
+  defaults?: NonNullable<CoreConfig["secrets"]>["defaults"],
+): void {
+  if (value === undefined) {
+    return;
+  }
+  if (value === null) {
+    delete target[key];
+    return;
+  }
+  if (typeof value === "string") {
+    const normalized = normalizeSecretInputString(value);
+    if (normalized) {
+      target[key] = normalized;
+    } else {
+      delete target[key];
+    }
+    return;
+  }
+
+  const ref = coerceSecretRef(value, defaults);
+  if (!ref) {
+    throw new Error(`Invalid Matrix ${key} SecretInput.`);
+  }
+  target[key] = ref;
+}
+
+function cloneMatrixDmConfig(dm: MatrixConfig["dm"]): MatrixConfig["dm"] {
+  if (!dm) {
+    return dm;
+  }
+  return {
+    ...dm,
+    ...(dm.allowFrom ? { allowFrom: [...dm.allowFrom] } : {}),
+  };
+}
+
+function cloneMatrixRoomMap(rooms: MatrixConfig["groups"]): MatrixConfig["groups"] {
+  if (!rooms) {
+    return rooms;
+  }
+  return Object.fromEntries(
+    Object.entries(rooms).map(([roomId, roomCfg]) => [roomId, roomCfg ? { ...roomCfg } : roomCfg]),
+  );
+}
+
+function applyNullableArrayField(
+  target: Record<string, unknown>,
+  key: keyof MatrixAccountPatch,
+  value: Array<string | number> | null | undefined,
+): void {
+  if (value === undefined) {
+    return;
+  }
+  if (value === null) {
+    delete target[key];
+    return;
+  }
+  target[key] = [...value];
+}
+
+export function updateMatrixAccountConfig(
+  cfg: CoreConfig,
+  accountId: string,
+  patch: MatrixAccountPatch,
+): CoreConfig {
+  const matrix = cfg.channels?.matrix ?? {};
+  const normalizedAccountId = normalizeAccountId(accountId);
+  const existingAccount = (findMatrixAccountConfig(cfg, normalizedAccountId) ??
+    (normalizedAccountId === DEFAULT_ACCOUNT_ID ? matrix : {})) as MatrixConfig;
+  const nextAccount: Record<string, unknown> = { ...existingAccount };
+
+  if (patch.name !== undefined) {
+    if (patch.name === null) {
+      delete nextAccount.name;
+    } else {
+      const trimmed = patch.name.trim();
+      if (trimmed) {
+        nextAccount.name = trimmed;
+      } else {
+        delete nextAccount.name;
+      }
+    }
+  }
+  if (typeof patch.enabled === "boolean") {
+    nextAccount.enabled = patch.enabled;
+  } else if (typeof nextAccount.enabled !== "boolean") {
+    nextAccount.enabled = true;
+  }
+
+  applyNullableStringField(nextAccount, "homeserver", patch.homeserver);
+  applyNullableStringField(nextAccount, "proxy", patch.proxy);
+  applyNullableStringField(nextAccount, "userId", patch.userId);
+  applyNullableSecretInputField(
+    nextAccount,
+    "accessToken",
+    patch.accessToken,
+    cfg.secrets?.defaults,
+  );
+  applyNullableSecretInputField(nextAccount, "password", patch.password, cfg.secrets?.defaults);
+  applyNullableStringField(nextAccount, "deviceId", patch.deviceId);
+  applyNullableStringField(nextAccount, "deviceName", patch.deviceName);
+  applyNullableStringField(nextAccount, "avatarUrl", patch.avatarUrl);
+
+  if (patch.allowPrivateNetwork !== undefined) {
+    const nextNetwork =
+      nextAccount.network && typeof nextAccount.network === "object"
+        ? { ...(nextAccount.network as Record<string, unknown>) }
+        : {};
+    if (patch.allowPrivateNetwork === null) {
+      delete nextNetwork.dangerouslyAllowPrivateNetwork;
+    } else {
+      nextNetwork.dangerouslyAllowPrivateNetwork = patch.allowPrivateNetwork;
+    }
+    if (Object.keys(nextNetwork).length > 0) {
+      nextAccount.network = nextNetwork;
+    } else {
+      delete nextAccount.network;
+    }
+  }
+
+  if (patch.initialSyncLimit !== undefined) {
+    if (patch.initialSyncLimit === null) {
+      delete nextAccount.initialSyncLimit;
+    } else {
+      nextAccount.initialSyncLimit = Math.max(0, Math.floor(patch.initialSyncLimit));
+    }
+  }
+
+  if (patch.encryption !== undefined) {
+    if (patch.encryption === null) {
+      delete nextAccount.encryption;
+    } else {
+      nextAccount.encryption = patch.encryption;
+    }
+  }
+  if (patch.allowBots !== undefined) {
+    if (patch.allowBots === null) {
+      delete nextAccount.allowBots;
+    } else {
+      nextAccount.allowBots = patch.allowBots;
+    }
+  }
+  if (patch.autoJoin !== undefined) {
+    if (patch.autoJoin === null) {
+      delete nextAccount.autoJoin;
+    } else {
+      nextAccount.autoJoin = patch.autoJoin;
+    }
+  }
+  applyNullableArrayField(nextAccount, "autoJoinAllowlist", patch.autoJoinAllowlist);
+  if (patch.dm !== undefined) {
+    if (patch.dm === null) {
+      delete nextAccount.dm;
+    } else {
+      nextAccount.dm = cloneMatrixDmConfig({
+        ...(nextAccount.dm as MatrixConfig["dm"] | undefined),
+        ...patch.dm,
+      });
+    }
+  }
+  if (patch.groupPolicy !== undefined) {
+    if (patch.groupPolicy === null) {
+      delete nextAccount.groupPolicy;
+    } else {
+      nextAccount.groupPolicy = patch.groupPolicy;
+    }
+  }
+  applyNullableArrayField(nextAccount, "groupAllowFrom", patch.groupAllowFrom);
+  if (patch.groups !== undefined) {
+    if (patch.groups === null) {
+      delete nextAccount.groups;
+    } else {
+      nextAccount.groups = cloneMatrixRoomMap(patch.groups);
+    }
+  }
+  if (patch.rooms !== undefined) {
+    if (patch.rooms === null) {
+      delete nextAccount.rooms;
+    } else {
+      nextAccount.rooms = cloneMatrixRoomMap(patch.rooms);
+    }
+  }
+
+  const nextAccounts = Object.fromEntries(
+    Object.entries(matrix.accounts ?? {}).filter(
+      ([rawAccountId]) =>
+        rawAccountId === normalizedAccountId ||
+        normalizeAccountId(rawAccountId) !== normalizedAccountId,
+    ),
+  );
+
+  if (shouldStoreMatrixAccountAtTopLevel(cfg, normalizedAccountId)) {
+    const { accounts: _ignoredAccounts, defaultAccount } = matrix;
+    const {
+      accounts: _ignoredNextAccounts,
+      defaultAccount: _ignoredNextDefaultAccount,
+      ...topLevelAccount
+    } = nextAccount;
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        matrix: {
+          ...(defaultAccount ? { defaultAccount } : {}),
+          enabled: true,
+          ...topLevelAccount,
+        },
+      },
+    };
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      matrix: {
+        ...matrix,
+        enabled: true,
+        accounts: {
+          ...nextAccounts,
+          [normalizedAccountId]: nextAccount as MatrixConfig,
+        },
+      },
+    },
+  };
+}