@archipelagolab/lobi 1.0.0

package/src/setup-config.ts

@@ -0,0 +1,222 @@
+import {
+  applyAccountNameToChannelSection,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeSecretInputString,
+  type ChannelSetupInput,
+} from "openclaw/plugin-sdk/setup";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { resolveMatrixEnvAuthReadiness } from "./matrix/client/env-auth.js";
+import { updateMatrixAccountConfig } from "./matrix/config-update.js";
+import { isSupportedMatrixAvatarSource } from "./matrix/profile.js";
+import {
+  matrixNamedAccountPromotionKeys,
+  resolveSingleAccountPromotionTarget,
+  matrixSingleAccountKeysToMove,
+} from "./setup-contract.js";
+import type { CoreConfig } from "./types.js";
+
+const channel = "matrix" as const;
+const COMMON_SINGLE_ACCOUNT_KEYS_TO_MOVE = new Set([
+  "name",
+  "enabled",
+  "httpPort",
+  "webhookPath",
+  "webhookUrl",
+  "webhookSecret",
+  "service",
+  "region",
+  "homeserver",
+  "userId",
+  "accessToken",
+  "password",
+  "deviceName",
+  "url",
+  "code",
+  "dmPolicy",
+  "allowFrom",
+  "groupPolicy",
+  "groupAllowFrom",
+  "defaultTo",
+]);
+const MATRIX_SINGLE_ACCOUNT_KEYS_TO_MOVE = new Set<string>(matrixSingleAccountKeysToMove);
+const MATRIX_NAMED_ACCOUNT_PROMOTION_KEYS = new Set<string>(matrixNamedAccountPromotionKeys);
+
+function cloneIfObject<T>(value: T): T {
+  if (value && typeof value === "object") {
+    return structuredClone(value);
+  }
+  return value;
+}
+
+function resolveSetupAvatarUrl(input: ChannelSetupInput): string | undefined {
+  const avatarUrl = input.avatarUrl;
+  if (typeof avatarUrl !== "string") {
+    return undefined;
+  }
+  const trimmed = avatarUrl.trim();
+  return trimmed || undefined;
+}
+
+function resolveExistingMatrixAccountKey(
+  accounts: Record<string, Record<string, unknown>>,
+  targetAccountId: string,
+): string {
+  const normalizedTargetAccountId = normalizeAccountId(targetAccountId);
+  return (
+    Object.keys(accounts).find(
+      (accountId) => normalizeAccountId(accountId) === normalizedTargetAccountId,
+    ) ?? targetAccountId
+  );
+}
+
+export function moveSingleMatrixAccountConfigToNamedAccount(cfg: CoreConfig): CoreConfig {
+  const channels = cfg.channels as Record<string, unknown> | undefined;
+  const baseConfig = channels?.[channel];
+  const base =
+    typeof baseConfig === "object" && baseConfig
+      ? (baseConfig as Record<string, unknown>)
+      : undefined;
+  if (!base) {
+    return cfg;
+  }
+
+  const accounts =
+    typeof base.accounts === "object" && base.accounts
+      ? (base.accounts as Record<string, Record<string, unknown>>)
+      : {};
+  const hasNamedAccounts = Object.keys(accounts).filter(Boolean).length > 0;
+  const keysToMove = Object.entries(base)
+    .filter(([key, value]) => {
+      if (key === "accounts" || key === "enabled" || value === undefined) {
+        return false;
+      }
+      if (
+        !COMMON_SINGLE_ACCOUNT_KEYS_TO_MOVE.has(key) &&
+        !MATRIX_SINGLE_ACCOUNT_KEYS_TO_MOVE.has(key)
+      ) {
+        return false;
+      }
+      if (hasNamedAccounts && !MATRIX_NAMED_ACCOUNT_PROMOTION_KEYS.has(key)) {
+        return false;
+      }
+      return true;
+    })
+    .map(([key]) => key);
+  if (keysToMove.length === 0) {
+    return cfg;
+  }
+
+  const targetAccountId = resolveSingleAccountPromotionTarget({ channel: base });
+  const resolvedTargetAccountId = resolveExistingMatrixAccountKey(accounts, targetAccountId);
+
+  const nextAccount: Record<string, unknown> = { ...accounts[resolvedTargetAccountId] };
+  for (const key of keysToMove) {
+    nextAccount[key] = cloneIfObject(base[key]);
+  }
+  const nextChannel = { ...base };
+  for (const key of keysToMove) {
+    delete nextChannel[key];
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      [channel]: {
+        ...nextChannel,
+        accounts: {
+          ...accounts,
+          [resolvedTargetAccountId]: nextAccount,
+        },
+      },
+    },
+  };
+}
+
+export function validateMatrixSetupInput(params: {
+  accountId: string;
+  input: ChannelSetupInput;
+}): string | null {
+  const avatarUrl = resolveSetupAvatarUrl(params.input);
+  if (avatarUrl && !isSupportedMatrixAvatarSource(avatarUrl)) {
+    return "Matrix avatar URL must be an mxc:// URI or an http(s) URL.";
+  }
+  if (params.input.useEnv) {
+    const envReadiness = resolveMatrixEnvAuthReadiness(params.accountId, process.env);
+    return envReadiness.ready ? null : envReadiness.missingMessage;
+  }
+  if (!params.input.homeserver?.trim()) {
+    return "Matrix requires --homeserver";
+  }
+  const accessToken = params.input.accessToken?.trim();
+  const password = normalizeSecretInputString(params.input.password);
+  const userId = params.input.userId?.trim();
+  if (!accessToken && !password) {
+    return "Matrix requires --access-token or --password";
+  }
+  if (!accessToken) {
+    if (!userId) {
+      return "Matrix requires --user-id when using --password";
+    }
+    if (!password) {
+      return "Matrix requires --password when using --user-id";
+    }
+  }
+  return null;
+}
+
+export function applyMatrixSetupAccountConfig(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  input: ChannelSetupInput;
+}): CoreConfig {
+  const normalizedAccountId = normalizeAccountId(params.accountId);
+  const migratedCfg =
+    normalizedAccountId !== DEFAULT_ACCOUNT_ID
+      ? moveSingleMatrixAccountConfigToNamedAccount(params.cfg)
+      : params.cfg;
+  const next = applyAccountNameToChannelSection({
+    cfg: migratedCfg,
+    channelKey: channel,
+    accountId: normalizedAccountId,
+    name: params.input.name,
+  }) as CoreConfig;
+  const avatarUrl = resolveSetupAvatarUrl(params.input);
+
+  if (params.input.useEnv) {
+    return updateMatrixAccountConfig(next, normalizedAccountId, {
+      enabled: true,
+      homeserver: null,
+      allowPrivateNetwork: null,
+      proxy: null,
+      userId: null,
+      accessToken: null,
+      password: null,
+      deviceId: null,
+      deviceName: null,
+      avatarUrl,
+    });
+  }
+
+  const accessToken = params.input.accessToken?.trim();
+  const password = normalizeSecretInputString(params.input.password);
+  const userId = params.input.userId?.trim();
+  return updateMatrixAccountConfig(next, normalizedAccountId, {
+    enabled: true,
+    homeserver: params.input.homeserver?.trim(),
+    allowPrivateNetwork:
+      typeof params.input.dangerouslyAllowPrivateNetwork === "boolean"
+        ? params.input.dangerouslyAllowPrivateNetwork
+        : typeof params.input.allowPrivateNetwork === "boolean"
+          ? params.input.allowPrivateNetwork
+          : undefined,
+    proxy: normalizeOptionalString(params.input.proxy),
+    userId: password && !userId ? null : userId,
+    accessToken: accessToken || (password ? null : undefined),
+    password: password || (accessToken ? null : undefined),
+    deviceName: params.input.deviceName?.trim(),
+    avatarUrl,
+    initialSyncLimit: params.input.initialSyncLimit,
+  });
+}

package/src/setup-contract.ts

@@ -0,0 +1,89 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/routing";
+
+export const matrixSingleAccountKeysToMove = [
+  "deviceId",
+  "avatarUrl",
+  "initialSyncLimit",
+  "encryption",
+  "allowlistOnly",
+  "allowBots",
+  "blockStreaming",
+  "replyToMode",
+  "threadReplies",
+  "textChunkLimit",
+  "chunkMode",
+  "responsePrefix",
+  "ackReaction",
+  "ackReactionScope",
+  "reactionNotifications",
+  "threadBindings",
+  "startupVerification",
+  "startupVerificationCooldownHours",
+  "mediaMaxMb",
+  "autoJoin",
+  "autoJoinAllowlist",
+  "dm",
+  "groups",
+  "rooms",
+  "actions",
+] as const;
+
+export const matrixNamedAccountPromotionKeys = [
+  // When named accounts already exist, only move auth/bootstrap fields into the
+  // promoted account. Shared delivery-policy fields stay at the top level.
+  "name",
+  "homeserver",
+  "userId",
+  "accessToken",
+  "password",
+  "deviceId",
+  "deviceName",
+  "avatarUrl",
+  "initialSyncLimit",
+  "encryption",
+] as const;
+
+export const singleAccountKeysToMove = [...matrixSingleAccountKeysToMove];
+export const namedAccountPromotionKeys = [...matrixNamedAccountPromotionKeys];
+
+export function resolveSingleAccountPromotionTarget(params: {
+  channel: Record<string, unknown>;
+}): string {
+  const accounts =
+    typeof params.channel.accounts === "object" && params.channel.accounts
+      ? (params.channel.accounts as Record<string, unknown>)
+      : {};
+  const normalizedDefaultAccount =
+    typeof params.channel.defaultAccount === "string" && params.channel.defaultAccount.trim()
+      ? normalizeAccountId(params.channel.defaultAccount)
+      : undefined;
+  const matchedAccountId = normalizedDefaultAccount
+    ? Object.entries(accounts).find(
+        ([accountId, value]) =>
+          accountId &&
+          value &&
+          typeof value === "object" &&
+          normalizeAccountId(accountId) === normalizedDefaultAccount,
+      )?.[0]
+    : undefined;
+  if (matchedAccountId) {
+    return matchedAccountId;
+  }
+  if (normalizedDefaultAccount) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  const namedAccounts = Object.entries(accounts).filter(
+    ([accountId, value]) => accountId && typeof value === "object" && value,
+  );
+  if (namedAccounts.length === 1) {
+    return namedAccounts[0][0];
+  }
+  if (
+    namedAccounts.length > 1 &&
+    accounts[DEFAULT_ACCOUNT_ID] &&
+    typeof accounts[DEFAULT_ACCOUNT_ID] === "object"
+  ) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  return DEFAULT_ACCOUNT_ID;
+}

package/src/setup-core.test.ts

@@ -0,0 +1,326 @@
+import { describe, expect, it } from "vitest";
+import { matrixSetupAdapter } from "./setup-core.js";
+import type { CoreConfig } from "./types.js";
+
+function applyOpsAccountConfig(cfg: CoreConfig): CoreConfig {
+  return matrixSetupAdapter.applyAccountConfig({
+    cfg,
+    accountId: "ops",
+    input: {
+      name: "Ops",
+      homeserver: "https://matrix.example.org",
+      accessToken: "ops-token",
+    },
+  }) as CoreConfig;
+}
+
+function expectPromotedDefaultAccount(next: CoreConfig): void {
+  expect(next.channels?.matrix?.accounts?.Default).toMatchObject({
+    enabled: true,
+    deviceName: "Legacy raw key",
+    homeserver: "https://matrix.example.org",
+    userId: "@default:example.org",
+    accessToken: "default-token",
+    avatarUrl: "mxc://example.org/default-avatar",
+  });
+  expect(next.channels?.matrix?.accounts?.default).toBeUndefined();
+}
+
+function expectOpsAccount(next: CoreConfig): void {
+  expect(next.channels?.matrix?.accounts?.ops).toMatchObject({
+    name: "Ops",
+    enabled: true,
+    homeserver: "https://matrix.example.org",
+    accessToken: "ops-token",
+  });
+}
+
+describe("matrixSetupAdapter", () => {
+  it("moves legacy default config before writing a named account", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          homeserver: "https://matrix.example.org",
+          userId: "@default:example.org",
+          accessToken: "default-token",
+          deviceName: "Default device",
+        },
+      },
+    } as CoreConfig;
+
+    const next = matrixSetupAdapter.applyAccountConfig({
+      cfg,
+      accountId: "ops",
+      input: {
+        name: "Ops",
+        homeserver: "https://matrix.example.org",
+        userId: "@ops:example.org",
+        accessToken: "ops-token",
+      },
+    }) as CoreConfig;
+
+    expect(next.channels?.matrix?.homeserver).toBeUndefined();
+    expect(next.channels?.matrix?.userId).toBeUndefined();
+    expect(next.channels?.matrix?.accessToken).toBeUndefined();
+    expect(next.channels?.matrix?.accounts?.default).toMatchObject({
+      homeserver: "https://matrix.example.org",
+      userId: "@default:example.org",
+      accessToken: "default-token",
+      deviceName: "Default device",
+    });
+    expect(next.channels?.matrix?.accounts?.ops).toMatchObject({
+      name: "Ops",
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      userId: "@ops:example.org",
+      accessToken: "ops-token",
+    });
+  });
+
+  it("reuses an existing raw default-account key during promotion", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          defaultAccount: "default",
+          homeserver: "https://matrix.example.org",
+          userId: "@default:example.org",
+          accessToken: "default-token",
+          avatarUrl: "mxc://example.org/default-avatar",
+          accounts: {
+            Default: {
+              enabled: true,
+              deviceName: "Legacy raw key",
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const next = applyOpsAccountConfig(cfg);
+
+    expectPromotedDefaultAccount(next);
+    expectOpsAccount(next);
+  });
+
+  it("reuses an existing raw default-like key during promotion when defaultAccount is unset", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          homeserver: "https://matrix.example.org",
+          userId: "@default:example.org",
+          accessToken: "default-token",
+          avatarUrl: "mxc://example.org/default-avatar",
+          accounts: {
+            Default: {
+              enabled: true,
+              deviceName: "Legacy raw key",
+            },
+            support: {
+              homeserver: "https://matrix.example.org",
+              accessToken: "support-token",
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const next = applyOpsAccountConfig(cfg);
+
+    expectPromotedDefaultAccount(next);
+    expect(next.channels?.matrix?.accounts?.support).toMatchObject({
+      homeserver: "https://matrix.example.org",
+      accessToken: "support-token",
+    });
+    expectOpsAccount(next);
+  });
+
+  it("clears stored auth fields when switching an account to env-backed auth", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accounts: {
+            ops: {
+              name: "Ops",
+              homeserver: "https://matrix.example.org",
+              proxy: "http://127.0.0.1:7890",
+              userId: "@ops:example.org",
+              accessToken: "ops-token",
+              password: "secret",
+              deviceId: "DEVICE",
+              deviceName: "Ops device",
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const next = matrixSetupAdapter.applyAccountConfig({
+      cfg,
+      accountId: "ops",
+      input: {
+        name: "Ops",
+        useEnv: true,
+      },
+    }) as CoreConfig;
+
+    expect(next.channels?.matrix?.accounts?.ops).toMatchObject({
+      name: "Ops",
+      enabled: true,
+    });
+    expect(next.channels?.matrix?.accounts?.ops?.homeserver).toBeUndefined();
+    expect(next.channels?.matrix?.accounts?.ops?.proxy).toBeUndefined();
+    expect(next.channels?.matrix?.accounts?.ops?.userId).toBeUndefined();
+    expect(next.channels?.matrix?.accounts?.ops?.accessToken).toBeUndefined();
+    expect(next.channels?.matrix?.accounts?.ops?.password).toBeUndefined();
+    expect(next.channels?.matrix?.accounts?.ops?.deviceId).toBeUndefined();
+    expect(next.channels?.matrix?.accounts?.ops?.deviceName).toBeUndefined();
+  });
+
+  it("keeps avatarUrl when switching an account to env-backed auth", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accounts: {
+            ops: {
+              name: "Ops",
+              homeserver: "https://matrix.example.org",
+              accessToken: "ops-token",
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const next = matrixSetupAdapter.applyAccountConfig({
+      cfg,
+      accountId: "ops",
+      input: {
+        name: "Ops",
+        useEnv: true,
+        avatarUrl: "  mxc://example.org/ops-avatar  ",
+      },
+    }) as CoreConfig;
+
+    expect(next.channels?.matrix?.accounts?.ops).toMatchObject({
+      name: "Ops",
+      enabled: true,
+      avatarUrl: "mxc://example.org/ops-avatar",
+    });
+    expect(next.channels?.matrix?.accounts?.ops?.homeserver).toBeUndefined();
+    expect(next.channels?.matrix?.accounts?.ops?.accessToken).toBeUndefined();
+  });
+
+  it("stores proxy in account setup updates", () => {
+    const next = matrixSetupAdapter.applyAccountConfig({
+      cfg: {} as CoreConfig,
+      accountId: "ops",
+      input: {
+        homeserver: "https://matrix.example.org",
+        accessToken: "ops-token",
+        proxy: "http://127.0.0.1:7890",
+      },
+    }) as CoreConfig;
+
+    expect(next.channels?.matrix?.accounts?.ops).toMatchObject({
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "ops-token",
+      proxy: "http://127.0.0.1:7890",
+    });
+  });
+
+  it("stores avatarUrl from setup input on the target account", () => {
+    const next = matrixSetupAdapter.applyAccountConfig({
+      cfg: {} as CoreConfig,
+      accountId: "ops",
+      input: {
+        homeserver: "https://matrix.example.org",
+        accessToken: "ops-token",
+        avatarUrl: "  mxc://example.org/ops-avatar  ",
+      },
+    }) as CoreConfig;
+
+    expect(next.channels?.matrix?.accounts?.ops).toMatchObject({
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      accessToken: "ops-token",
+      avatarUrl: "mxc://example.org/ops-avatar",
+    });
+  });
+
+  it("rejects unsupported avatar URL schemes during setup validation", () => {
+    const validationError = matrixSetupAdapter.validateInput?.({
+      cfg: {} as CoreConfig,
+      accountId: "ops",
+      input: {
+        homeserver: "https://matrix.example.org",
+        accessToken: "ops-token",
+        avatarUrl: "file:///tmp/avatar.png",
+      },
+    });
+
+    expect(validationError).toBe("Matrix avatar URL must be an mxc:// URI or an http(s) URL.");
+  });
+
+  it("stores canonical dangerous private-network opt-in from setup input", () => {
+    const next = matrixSetupAdapter.applyAccountConfig({
+      cfg: {} as CoreConfig,
+      accountId: "ops",
+      input: {
+        homeserver: "http://matrix.internal:8008",
+        accessToken: "ops-token",
+        dangerouslyAllowPrivateNetwork: true,
+      },
+    }) as CoreConfig;
+
+    expect(next.channels?.matrix?.accounts?.ops).toMatchObject({
+      enabled: true,
+      homeserver: "http://matrix.internal:8008",
+      accessToken: "ops-token",
+      network: {
+        dangerouslyAllowPrivateNetwork: true,
+      },
+    });
+  });
+
+  it("keeps top-level block streaming as a shared default when named accounts already exist", () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          homeserver: "https://matrix.example.org",
+          userId: "@default:example.org",
+          accessToken: "default-token",
+          blockStreaming: true,
+          accounts: {
+            support: {
+              homeserver: "https://matrix.example.org",
+              userId: "@support:example.org",
+              accessToken: "support-token",
+            },
+          },
+        },
+      },
+    } as CoreConfig;
+
+    const next = matrixSetupAdapter.applyAccountConfig({
+      cfg,
+      accountId: "ops",
+      input: {
+        name: "Ops",
+        homeserver: "https://matrix.example.org",
+        userId: "@ops:example.org",
+        accessToken: "ops-token",
+      },
+    }) as CoreConfig;
+
+    expect(next.channels?.matrix?.blockStreaming).toBe(true);
+    expect(next.channels?.matrix?.accounts?.ops).toMatchObject({
+      name: "Ops",
+      enabled: true,
+      homeserver: "https://matrix.example.org",
+      userId: "@ops:example.org",
+      accessToken: "ops-token",
+    });
+    expect(next.channels?.matrix?.accounts?.ops?.blockStreaming).toBeUndefined();
+  });
+});

package/src/setup-core.ts

@@ -0,0 +1,50 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  prepareScopedSetupConfig,
+  type ChannelSetupAdapter,
+} from "openclaw/plugin-sdk/setup";
+import { applyMatrixSetupAccountConfig, validateMatrixSetupInput } from "./setup-config.js";
+import type { CoreConfig } from "./types.js";
+
+const channel = "matrix" as const;
+
+function resolveMatrixSetupAccountId(params: { accountId?: string; name?: string }): string {
+  return normalizeAccountId(params.accountId?.trim() || params.name?.trim() || DEFAULT_ACCOUNT_ID);
+}
+
+export const matrixSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ accountId, input }) =>
+    resolveMatrixSetupAccountId({
+      accountId,
+      name: input?.name,
+    }),
+  resolveBindingAccountId: ({ accountId, agentId }) =>
+    resolveMatrixSetupAccountId({
+      accountId,
+      name: agentId,
+    }),
+  applyAccountName: ({ cfg, accountId, name }) =>
+    prepareScopedSetupConfig({
+      cfg: cfg as CoreConfig,
+      channelKey: channel,
+      accountId,
+      name,
+    }) as CoreConfig,
+  validateInput: ({ accountId, input }) => validateMatrixSetupInput({ accountId, input }),
+  applyAccountConfig: ({ cfg, accountId, input }) =>
+    applyMatrixSetupAccountConfig({
+      cfg: cfg as CoreConfig,
+      accountId,
+      input,
+    }),
+  afterAccountConfigWritten: async ({ previousCfg, cfg, accountId, runtime }) => {
+    const { runMatrixSetupBootstrapAfterConfigWrite } = await import("./setup-bootstrap.js");
+    await runMatrixSetupBootstrapAfterConfigWrite({
+      previousCfg: previousCfg as CoreConfig,
+      cfg: cfg as CoreConfig,
+      accountId,
+      runtime,
+    });
+  },
+};

package/src/setup-surface.ts

@@ -0,0 +1,4 @@
+export {
+  matrixOnboardingAdapter,
+  matrixOnboardingAdapter as matrixSetupWizard,
+} from "./onboarding.js";