@archipelagolab/lobi 1.0.0

package/src/matrix/actions/summary.ts

@@ -0,0 +1,88 @@
+import { isMatrixNotFoundError } from "../errors.js";
+import { resolveMatrixMessageAttachment, resolveMatrixMessageBody } from "../media-text.js";
+import { fetchMatrixPollMessageSummary } from "../poll-summary.js";
+import type { MatrixClient } from "../sdk.js";
+import {
+  EventType,
+  type MatrixMessageSummary,
+  type MatrixRawEvent,
+  type RoomMessageEventContent,
+  type RoomPinnedEventsEventContent,
+} from "./types.js";
+
+export function summarizeMatrixRawEvent(event: MatrixRawEvent): MatrixMessageSummary {
+  const content = event.content as RoomMessageEventContent;
+  const relates = content["m.relates_to"];
+  let relType: string | undefined;
+  let eventId: string | undefined;
+  if (relates) {
+    if ("rel_type" in relates) {
+      relType = relates.rel_type;
+      eventId = relates.event_id;
+    } else if ("m.in_reply_to" in relates) {
+      eventId = relates["m.in_reply_to"]?.event_id;
+    }
+  }
+  const relatesTo =
+    relType || eventId
+      ? {
+          relType,
+          eventId,
+        }
+      : undefined;
+  return {
+    eventId: event.event_id,
+    sender: event.sender,
+    body: resolveMatrixMessageBody({
+      body: content.body,
+      filename: content.filename,
+      msgtype: content.msgtype,
+    }),
+    msgtype: content.msgtype,
+    attachment: resolveMatrixMessageAttachment({
+      body: content.body,
+      filename: content.filename,
+      msgtype: content.msgtype,
+    }),
+    timestamp: event.origin_server_ts,
+    relatesTo,
+  };
+}
+
+export async function readPinnedEvents(client: MatrixClient, roomId: string): Promise<string[]> {
+  try {
+    const content = (await client.getRoomStateEvent(
+      roomId,
+      EventType.RoomPinnedEvents,
+      "",
+    )) as RoomPinnedEventsEventContent;
+    const pinned = content.pinned;
+    return pinned.filter((id) => id.trim().length > 0);
+  } catch (err: unknown) {
+    if (isMatrixNotFoundError(err)) {
+      return [];
+    }
+    throw err;
+  }
+}
+
+export async function fetchEventSummary(
+  client: MatrixClient,
+  roomId: string,
+  eventId: string,
+): Promise<MatrixMessageSummary | null> {
+  try {
+    const raw = (await client.getEvent(roomId, eventId)) as unknown as MatrixRawEvent;
+    if (raw.unsigned?.redacted_because) {
+      return null;
+    }
+    const pollSummary = await fetchMatrixPollMessageSummary(client, roomId, raw);
+    if (pollSummary) {
+      return pollSummary;
+    }
+    return summarizeMatrixRawEvent(raw);
+  } catch {
+    // Event not found, redacted, or inaccessible - return null
+    return null;
+  }
+}

package/src/matrix/actions/types.ts

@@ -0,0 +1,82 @@
+import type { CoreConfig } from "../../types.js";
+import {
+  MATRIX_ANNOTATION_RELATION_TYPE,
+  MATRIX_REACTION_EVENT_TYPE,
+  type MatrixReactionEventContent,
+} from "../reaction-common.js";
+import type { MatrixClient, MessageEventContent } from "../sdk.js";
+export type { MatrixRawEvent } from "../sdk.js";
+export type { MatrixReactionSummary } from "../reaction-common.js";
+
+export const MsgType = {
+  Text: "m.text",
+} as const;
+
+export const RelationType = {
+  Replace: "m.replace",
+  Annotation: MATRIX_ANNOTATION_RELATION_TYPE,
+} as const;
+
+export const EventType = {
+  RoomMessage: "m.room.message",
+  RoomPinnedEvents: "m.room.pinned_events",
+  RoomTopic: "m.room.topic",
+  Reaction: MATRIX_REACTION_EVENT_TYPE,
+} as const;
+
+export type RoomMessageEventContent = MessageEventContent & {
+  msgtype: string;
+  body: string;
+  "m.new_content"?: RoomMessageEventContent;
+  "m.relates_to"?: {
+    rel_type?: string;
+    event_id?: string;
+    "m.in_reply_to"?: { event_id?: string };
+  };
+};
+
+export type ReactionEventContent = MatrixReactionEventContent;
+
+export type RoomPinnedEventsEventContent = {
+  pinned: string[];
+};
+
+export type RoomTopicEventContent = {
+  topic?: string;
+};
+
+export type MatrixActionClientOpts = {
+  client?: MatrixClient;
+  cfg?: CoreConfig;
+  mediaLocalRoots?: readonly string[];
+  timeoutMs?: number;
+  accountId?: string | null;
+  readiness?: "none" | "prepared" | "started";
+};
+
+export type MatrixMessageSummary = {
+  eventId?: string;
+  sender?: string;
+  body?: string;
+  msgtype?: string;
+  attachment?: MatrixMessageAttachmentSummary;
+  timestamp?: number;
+  relatesTo?: {
+    relType?: string;
+    eventId?: string;
+    key?: string;
+  };
+};
+
+export type MatrixMessageAttachmentKind = "audio" | "file" | "image" | "sticker" | "video";
+
+export type MatrixMessageAttachmentSummary = {
+  kind: MatrixMessageAttachmentKind;
+  caption?: string;
+  filename?: string;
+};
+
+export type MatrixActionClient = {
+  client: MatrixClient;
+  stopOnDone: boolean;
+};

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

@@ -0,0 +1,105 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const withStartedActionClientMock = vi.fn();
+const loadConfigMock = vi.fn(() => ({
+  channels: {
+    matrix: {},
+  },
+}));
+
+vi.mock("../../runtime.js", () => ({
+  getMatrixRuntime: () => ({
+    config: {
+      loadConfig: loadConfigMock,
+    },
+  }),
+}));
+
+vi.mock("./client.js", () => ({
+  withStartedActionClient: (...args: unknown[]) => withStartedActionClientMock(...args),
+}));
+
+let listMatrixVerifications: typeof import("./verification.js").listMatrixVerifications;
+
+describe("matrix verification actions", () => {
+  beforeAll(async () => {
+    ({ listMatrixVerifications } = await import("./verification.js"));
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    loadConfigMock.mockReturnValue({
+      channels: {
+        matrix: {},
+      },
+    });
+  });
+
+  it("points encryption guidance at the selected Matrix account", async () => {
+    loadConfigMock.mockReturnValue({
+      channels: {
+        matrix: {
+          accounts: {
+            ops: {
+              encryption: false,
+            },
+          },
+        },
+      },
+    });
+    withStartedActionClientMock.mockImplementation(async (_opts, run) => {
+      return await run({ crypto: null });
+    });
+
+    await expect(listMatrixVerifications({ accountId: "ops" })).rejects.toThrow(
+      "Matrix encryption is not available (enable channels.lobi.accounts.ops.encryption=true)",
+    );
+  });
+
+  it("uses the resolved default Matrix account when accountId is omitted", async () => {
+    loadConfigMock.mockReturnValue({
+      channels: {
+        matrix: {
+          defaultAccount: "ops",
+          accounts: {
+            ops: {
+              encryption: false,
+            },
+          },
+        },
+      },
+    });
+    withStartedActionClientMock.mockImplementation(async (_opts, run) => {
+      return await run({ crypto: null });
+    });
+
+    await expect(listMatrixVerifications()).rejects.toThrow(
+      "Matrix encryption is not available (enable channels.lobi.accounts.ops.encryption=true)",
+    );
+  });
+
+  it("uses explicit cfg instead of runtime config when crypto is unavailable", async () => {
+    const explicitCfg = {
+      channels: {
+        matrix: {
+          accounts: {
+            ops: {
+              encryption: false,
+            },
+          },
+        },
+      },
+    };
+    loadConfigMock.mockImplementation(() => {
+      throw new Error("verification actions should not reload runtime config when cfg is provided");
+    });
+    withStartedActionClientMock.mockImplementation(async (_opts, run) => {
+      return await run({ crypto: null });
+    });
+
+    await expect(listMatrixVerifications({ cfg: explicitCfg, accountId: "ops" })).rejects.toThrow(
+      "Matrix encryption is not available (enable channels.lobi.accounts.ops.encryption=true)",
+    );
+    expect(loadConfigMock).not.toHaveBeenCalled();
+  });
+});

package/src/matrix/actions/verification.ts

@@ -0,0 +1,237 @@
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { getMatrixRuntime } from "../../runtime.js";
+import type { CoreConfig } from "../../types.js";
+import { formatMatrixEncryptionUnavailableError } from "../encryption-guidance.js";
+import { withStartedActionClient } from "./client.js";
+import type { MatrixActionClientOpts } from "./types.js";
+
+function requireCrypto(
+  client: import("../sdk.js").MatrixClient,
+  opts: MatrixActionClientOpts,
+): NonNullable<import("../sdk.js").MatrixClient["crypto"]> {
+  if (!client.crypto) {
+    const cfg = opts.cfg ?? (getMatrixRuntime().config.loadConfig() as CoreConfig);
+    throw new Error(formatMatrixEncryptionUnavailableError(cfg, opts.accountId));
+  }
+  return client.crypto;
+}
+
+function resolveVerificationId(input: string): string {
+  const normalized = input.trim();
+  if (!normalized) {
+    throw new Error("Matrix verification request id is required");
+  }
+  return normalized;
+}
+
+export async function listMatrixVerifications(opts: MatrixActionClientOpts = {}) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.listVerifications();
+  });
+}
+
+export async function requestMatrixVerification(
+  params: MatrixActionClientOpts & {
+    ownUser?: boolean;
+    userId?: string;
+    deviceId?: string;
+    roomId?: string;
+  } = {},
+) {
+  return await withStartedActionClient(params, async (client) => {
+    const crypto = requireCrypto(client, params);
+    const ownUser = params.ownUser ?? (!params.userId && !params.deviceId && !params.roomId);
+    return await crypto.requestVerification({
+      ownUser,
+      userId: normalizeOptionalString(params.userId),
+      deviceId: normalizeOptionalString(params.deviceId),
+      roomId: normalizeOptionalString(params.roomId),
+    });
+  });
+}
+
+export async function acceptMatrixVerification(
+  requestId: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.acceptVerification(resolveVerificationId(requestId));
+  });
+}
+
+export async function cancelMatrixVerification(
+  requestId: string,
+  opts: MatrixActionClientOpts & { reason?: string; code?: string } = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.cancelVerification(resolveVerificationId(requestId), {
+      reason: normalizeOptionalString(opts.reason),
+      code: normalizeOptionalString(opts.code),
+    });
+  });
+}
+
+export async function startMatrixVerification(
+  requestId: string,
+  opts: MatrixActionClientOpts & { method?: "sas" } = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.startVerification(resolveVerificationId(requestId), opts.method ?? "sas");
+  });
+}
+
+export async function generateMatrixVerificationQr(
+  requestId: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.generateVerificationQr(resolveVerificationId(requestId));
+  });
+}
+
+export async function scanMatrixVerificationQr(
+  requestId: string,
+  qrDataBase64: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    const payload = qrDataBase64.trim();
+    if (!payload) {
+      throw new Error("Matrix QR data is required");
+    }
+    return await crypto.scanVerificationQr(resolveVerificationId(requestId), payload);
+  });
+}
+
+export async function getMatrixVerificationSas(
+  requestId: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.getVerificationSas(resolveVerificationId(requestId));
+  });
+}
+
+export async function confirmMatrixVerificationSas(
+  requestId: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.confirmVerificationSas(resolveVerificationId(requestId));
+  });
+}
+
+export async function mismatchMatrixVerificationSas(
+  requestId: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.mismatchVerificationSas(resolveVerificationId(requestId));
+  });
+}
+
+export async function confirmMatrixVerificationReciprocateQr(
+  requestId: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    return await crypto.confirmVerificationReciprocateQr(resolveVerificationId(requestId));
+  });
+}
+
+export async function getMatrixEncryptionStatus(
+  opts: MatrixActionClientOpts & { includeRecoveryKey?: boolean } = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const crypto = requireCrypto(client, opts);
+    const recoveryKey = await crypto.getRecoveryKey();
+    return {
+      encryptionEnabled: true,
+      recoveryKeyStored: Boolean(recoveryKey),
+      recoveryKeyCreatedAt: recoveryKey?.createdAt ?? null,
+      ...(opts.includeRecoveryKey ? { recoveryKey: recoveryKey?.encodedPrivateKey ?? null } : {}),
+      pendingVerifications: (await crypto.listVerifications()).length,
+    };
+  });
+}
+
+export async function getMatrixVerificationStatus(
+  opts: MatrixActionClientOpts & { includeRecoveryKey?: boolean } = {},
+) {
+  return await withStartedActionClient(opts, async (client) => {
+    const status = await client.getOwnDeviceVerificationStatus();
+    const payload = {
+      ...status,
+      pendingVerifications: client.crypto ? (await client.crypto.listVerifications()).length : 0,
+    };
+    if (!opts.includeRecoveryKey) {
+      return payload;
+    }
+    const recoveryKey = client.crypto ? await client.crypto.getRecoveryKey() : null;
+    return {
+      ...payload,
+      recoveryKey: recoveryKey?.encodedPrivateKey ?? null,
+    };
+  });
+}
+
+export async function getMatrixRoomKeyBackupStatus(opts: MatrixActionClientOpts = {}) {
+  return await withStartedActionClient(
+    opts,
+    async (client) => await client.getRoomKeyBackupStatus(),
+  );
+}
+
+export async function verifyMatrixRecoveryKey(
+  recoveryKey: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  return await withStartedActionClient(
+    opts,
+    async (client) => await client.verifyWithRecoveryKey(recoveryKey),
+  );
+}
+
+export async function restoreMatrixRoomKeyBackup(
+  opts: MatrixActionClientOpts & {
+    recoveryKey?: string;
+  } = {},
+) {
+  return await withStartedActionClient(
+    opts,
+    async (client) =>
+      await client.restoreRoomKeyBackup({
+        recoveryKey: normalizeOptionalString(opts.recoveryKey),
+      }),
+  );
+}
+
+export async function resetMatrixRoomKeyBackup(opts: MatrixActionClientOpts = {}) {
+  return await withStartedActionClient(opts, async (client) => await client.resetRoomKeyBackup());
+}
+
+export async function bootstrapMatrixVerification(
+  opts: MatrixActionClientOpts & {
+    recoveryKey?: string;
+    forceResetCrossSigning?: boolean;
+  } = {},
+) {
+  return await withStartedActionClient(
+    opts,
+    async (client) =>
+      await client.bootstrapOwnDeviceVerification({
+        recoveryKey: normalizeOptionalString(opts.recoveryKey),
+        forceResetCrossSigning: opts.forceResetCrossSigning === true,
+      }),
+  );
+}

package/src/matrix/actions.ts

@@ -0,0 +1,37 @@
+export type {
+  MatrixActionClientOpts,
+  MatrixMessageSummary,
+  MatrixReactionSummary,
+} from "./actions/types.js";
+export {
+  sendMatrixMessage,
+  editMatrixMessage,
+  deleteMatrixMessage,
+  readMatrixMessages,
+} from "./actions/messages.js";
+export { voteMatrixPoll } from "./actions/polls.js";
+export { listMatrixReactions, removeMatrixReactions } from "./actions/reactions.js";
+export { pinMatrixMessage, unpinMatrixMessage, listMatrixPins } from "./actions/pins.js";
+export { getMatrixMemberInfo, getMatrixRoomInfo } from "./actions/room.js";
+export { updateMatrixOwnProfile } from "./actions/profile.js";
+export {
+  bootstrapMatrixVerification,
+  acceptMatrixVerification,
+  cancelMatrixVerification,
+  confirmMatrixVerificationReciprocateQr,
+  confirmMatrixVerificationSas,
+  generateMatrixVerificationQr,
+  getMatrixEncryptionStatus,
+  getMatrixRoomKeyBackupStatus,
+  getMatrixVerificationStatus,
+  getMatrixVerificationSas,
+  listMatrixVerifications,
+  mismatchMatrixVerificationSas,
+  requestMatrixVerification,
+  resetMatrixRoomKeyBackup,
+  restoreMatrixRoomKeyBackup,
+  scanMatrixVerificationQr,
+  startMatrixVerification,
+  verifyMatrixRecoveryKey,
+} from "./actions/verification.js";
+export { reactMatrixMessage } from "./send.js";

package/src/matrix/active-client.ts

@@ -0,0 +1,26 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import type { MatrixClient } from "./sdk.js";
+
+const activeClients = new Map<string, MatrixClient>();
+
+function resolveAccountKey(accountId?: string | null): string {
+  const normalized = normalizeAccountId(accountId);
+  return normalized || DEFAULT_ACCOUNT_ID;
+}
+
+export function setActiveMatrixClient(
+  client: MatrixClient | null,
+  accountId?: string | null,
+): void {
+  const key = resolveAccountKey(accountId);
+  if (!client) {
+    activeClients.delete(key);
+    return;
+  }
+  activeClients.set(key, client);
+}
+
+export function getActiveMatrixClient(accountId?: string | null): MatrixClient | null {
+  const key = resolveAccountKey(accountId);
+  return activeClients.get(key) ?? null;
+}

package/src/matrix/async-lock.ts

@@ -0,0 +1,18 @@
+export type AsyncLock = <T>(fn: () => Promise<T>) => Promise<T>;
+
+export function createAsyncLock(): AsyncLock {
+  let lock: Promise<void> = Promise.resolve();
+  return async function withLock<T>(fn: () => Promise<T>): Promise<T> {
+    const previous = lock;
+    let release: (() => void) | undefined;
+    lock = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      return await fn();
+    } finally {
+      release?.();
+    }
+  };
+}