@archipelagolab/lobi 1.0.0

package/src/matrix/monitor/events.ts

@@ -0,0 +1,213 @@
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import type { PluginRuntime, RuntimeLogger } from "../../runtime-api.js";
+import type { CoreConfig } from "../../types.js";
+import type { MatrixAuth } from "../client.js";
+import { formatMatrixEncryptedEventDisabledWarning } from "../encryption-guidance.js";
+import type { MatrixClient } from "../sdk.js";
+import type { MatrixRawEvent } from "./types.js";
+import { EventType } from "./types.js";
+import { createMatrixVerificationEventRouter } from "./verification-events.js";
+
+function formatMatrixSelfDecryptionHint(accountId: string): string {
+  return (
+    "matrix: failed to decrypt a message from this same Matrix user. " +
+    "This usually means another Matrix device did not share the room key, or another OpenClaw runtime is using the same account. " +
+    `Check 'openclaw matrix verify status --verbose --account ${accountId}' and 'openclaw matrix devices list --account ${accountId}'.`
+  );
+}
+
+async function resolveMatrixSelfUserId(
+  client: MatrixClient,
+  logVerboseMessage: (message: string) => void,
+): Promise<string | null> {
+  if (typeof client.getUserId !== "function") {
+    return null;
+  }
+  try {
+    return (await client.getUserId()) ?? null;
+  } catch (err) {
+    logVerboseMessage(`matrix: failed resolving self user id for decrypt warning: ${String(err)}`);
+    return null;
+  }
+}
+
+export function registerMatrixMonitorEvents(params: {
+  cfg: CoreConfig;
+  client: MatrixClient;
+  auth: MatrixAuth;
+  allowFrom: string[];
+  dmEnabled: boolean;
+  dmPolicy: "open" | "pairing" | "allowlist" | "disabled";
+  readStoreAllowFrom: () => Promise<string[]>;
+  directTracker?: {
+    invalidateRoom: (roomId: string) => void;
+    rememberInvite?: (roomId: string, remoteUserId: string) => void;
+  };
+  logVerboseMessage: (message: string) => void;
+  warnedEncryptedRooms: Set<string>;
+  warnedCryptoMissingRooms: Set<string>;
+  logger: RuntimeLogger;
+  formatNativeDependencyHint: PluginRuntime["system"]["formatNativeDependencyHint"];
+  onRoomMessage: (roomId: string, event: MatrixRawEvent) => void | Promise<void>;
+  runDetachedTask?: (label: string, task: () => Promise<void>) => Promise<void>;
+}): void {
+  const {
+    cfg,
+    client,
+    auth,
+    allowFrom,
+    dmEnabled,
+    dmPolicy,
+    readStoreAllowFrom,
+    directTracker,
+    logVerboseMessage,
+    warnedEncryptedRooms,
+    warnedCryptoMissingRooms,
+    logger,
+    formatNativeDependencyHint,
+    onRoomMessage,
+    runDetachedTask,
+  } = params;
+  const { routeVerificationEvent, routeVerificationSummary } = createMatrixVerificationEventRouter({
+    client,
+    allowFrom,
+    dmEnabled,
+    dmPolicy,
+    readStoreAllowFrom,
+    logVerboseMessage,
+  });
+
+  const runMonitorTask = (label: string, task: () => Promise<void>) => {
+    if (runDetachedTask) {
+      return runDetachedTask(label, task);
+    }
+    return Promise.resolve()
+      .then(task)
+      .catch((error) => {
+        logVerboseMessage(`matrix: ${label} failed (${String(error)})`);
+      });
+  };
+
+  client.on("room.message", (roomId: string, event: MatrixRawEvent) => {
+    if (routeVerificationEvent(roomId, event)) {
+      return;
+    }
+    void runMonitorTask(
+      `room message handler room=${roomId} id=${event.event_id ?? "unknown"}`,
+      async () => {
+        await onRoomMessage(roomId, event);
+      },
+    );
+  });
+
+  client.on("room.encrypted_event", (roomId: string, event: MatrixRawEvent) => {
+    const eventId = event?.event_id ?? "unknown";
+    const eventType = event?.type ?? "unknown";
+    logVerboseMessage(`matrix: encrypted event room=${roomId} type=${eventType} id=${eventId}`);
+  });
+
+  client.on("room.decrypted_event", (roomId: string, event: MatrixRawEvent) => {
+    const eventId = event?.event_id ?? "unknown";
+    const eventType = event?.type ?? "unknown";
+    logVerboseMessage(`matrix: decrypted event room=${roomId} type=${eventType} id=${eventId}`);
+  });
+
+  client.on(
+    "room.failed_decryption",
+    async (roomId: string, event: MatrixRawEvent, error: Error) => {
+      const selfUserId = await resolveMatrixSelfUserId(client, logVerboseMessage);
+      const sender = typeof event.sender === "string" ? event.sender : null;
+      const senderMatchesOwnUser = Boolean(selfUserId && sender && selfUserId === sender);
+      logger.warn("Failed to decrypt message", {
+        roomId,
+        eventId: event.event_id,
+        sender,
+        senderMatchesOwnUser,
+        error: error.message,
+      });
+      if (senderMatchesOwnUser) {
+        logger.warn(formatMatrixSelfDecryptionHint(auth.accountId), {
+          roomId,
+          eventId: event.event_id,
+          sender,
+        });
+      }
+      logVerboseMessage(
+        `matrix: failed decrypt room=${roomId} id=${event.event_id ?? "unknown"} error=${error.message}`,
+      );
+    },
+  );
+
+  client.on("verification.summary", (summary) => {
+    void runMonitorTask("verification summary handler", async () => {
+      await routeVerificationSummary(summary);
+    });
+  });
+
+  client.on("room.invite", (roomId: string, event: MatrixRawEvent) => {
+    directTracker?.invalidateRoom(roomId);
+    const eventId = event?.event_id ?? "unknown";
+    const sender = event?.sender ?? "unknown";
+    const invitee = normalizeOptionalString(event?.state_key) ?? "";
+    const senderIsInvitee =
+      Boolean(invitee) && (normalizeOptionalString(event?.sender) ?? "") === invitee;
+    const isDirect = (event?.content as { is_direct?: boolean } | undefined)?.is_direct === true;
+    const rememberedSender = normalizeOptionalString(event?.sender);
+    if (rememberedSender && !senderIsInvitee) {
+      directTracker?.rememberInvite?.(roomId, rememberedSender);
+    }
+    logVerboseMessage(
+      `matrix: invite room=${roomId} sender=${sender} direct=${String(isDirect)} id=${eventId}`,
+    );
+  });
+
+  client.on("room.join", (roomId: string, event: MatrixRawEvent) => {
+    directTracker?.invalidateRoom(roomId);
+    const eventId = event?.event_id ?? "unknown";
+    logVerboseMessage(`matrix: join room=${roomId} id=${eventId}`);
+  });
+
+  client.on("room.event", (roomId: string, event: MatrixRawEvent) => {
+    const eventType = event?.type ?? "unknown";
+    if (eventType === EventType.RoomMessageEncrypted) {
+      logVerboseMessage(
+        `matrix: encrypted raw event room=${roomId} id=${event?.event_id ?? "unknown"}`,
+      );
+      if (auth.encryption !== true && !warnedEncryptedRooms.has(roomId)) {
+        warnedEncryptedRooms.add(roomId);
+        const warning = formatMatrixEncryptedEventDisabledWarning(cfg, auth.accountId);
+        logger.warn(warning, { roomId });
+      }
+      if (auth.encryption === true && !client.crypto && !warnedCryptoMissingRooms.has(roomId)) {
+        warnedCryptoMissingRooms.add(roomId);
+        const hint = formatNativeDependencyHint({
+          packageName: "@matrix-org/matrix-sdk-crypto-nodejs",
+          manager: "pnpm",
+          downloadCommand: "node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js",
+        });
+        const warning = `matrix: encryption enabled but crypto is unavailable; ${hint}`;
+        logger.warn(warning, { roomId });
+      }
+      return;
+    }
+    if (eventType === EventType.RoomMember) {
+      directTracker?.invalidateRoom(roomId);
+      const membership = (event?.content as { membership?: string } | undefined)?.membership;
+      const stateKey = (event as { state_key?: string }).state_key ?? "";
+      logVerboseMessage(
+        `matrix: member event room=${roomId} stateKey=${stateKey} membership=${membership ?? "unknown"}`,
+      );
+    }
+    if (eventType === EventType.Reaction) {
+      void runMonitorTask(
+        `reaction handler room=${roomId} id=${event.event_id ?? "unknown"}`,
+        async () => {
+          await onRoomMessage(roomId, event);
+        },
+      );
+      return;
+    }
+
+    routeVerificationEvent(roomId, event);
+  });
+}

package/src/matrix/monitor/handler.body-for-agent.test.ts

@@ -0,0 +1,396 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { installMatrixMonitorTestRuntime } from "../../test-runtime.js";
+import type { MatrixClient } from "../sdk.js";
+import {
+  createMatrixHandlerTestHarness,
+  createMatrixTextMessageEvent,
+} from "./handler.test-helpers.js";
+import type { MatrixRawEvent } from "./types.js";
+
+describe("createMatrixRoomMessageHandler inbound body formatting", () => {
+  type MatrixHandlerHarness = ReturnType<typeof createMatrixHandlerTestHarness>;
+  type FinalizedReplyContext = {
+    ReplyToBody?: string;
+    ReplyToSender?: string;
+    ThreadStarterBody?: string;
+  };
+
+  function createQuotedReplyVisibilityHarness(contextVisibility: "allowlist" | "allowlist_quote") {
+    return createMatrixHandlerTestHarness({
+      client: {
+        getEvent: async () =>
+          createMatrixTextMessageEvent({
+            eventId: "$quoted",
+            sender: "@mallory:example.org",
+            body: "Quoted payload",
+          }),
+      },
+      isDirectMessage: false,
+      cfg: {
+        channels: {
+          matrix: {
+            contextVisibility,
+          },
+        },
+      },
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["@alice:example.org"],
+      roomsConfig: { "*": {} },
+      replyToMode: "all",
+      getMemberDisplayName: async (_roomId, userId) =>
+        userId === "@alice:example.org" ? "Alice" : "Mallory",
+    });
+  }
+
+  async function sendQuotedReply(handler: MatrixHandlerHarness["handler"]) {
+    await handler(
+      "!room:example.org",
+      createMatrixTextMessageEvent({
+        eventId: "$reply1",
+        sender: "@alice:example.org",
+        body: "@room follow up",
+        relatesTo: {
+          "m.in_reply_to": { event_id: "$quoted" },
+        },
+        mentions: { room: true },
+      }),
+    );
+  }
+
+  function latestFinalizedReplyContext(
+    finalizeInboundContext: MatrixHandlerHarness["finalizeInboundContext"],
+  ) {
+    return vi.mocked(finalizeInboundContext).mock.calls.at(-1)?.[0] as FinalizedReplyContext;
+  }
+
+  beforeEach(() => {
+    installMatrixMonitorTestRuntime({
+      matchesMentionPatterns: () => false,
+      saveMediaBuffer: vi.fn(),
+    });
+  });
+
+  it("records thread metadata for group thread messages", async () => {
+    const { handler, finalizeInboundContext, recordInboundSession } =
+      createMatrixHandlerTestHarness({
+        client: {
+          getEvent: async () =>
+            createMatrixTextMessageEvent({
+              eventId: "$thread-root",
+              sender: "@alice:example.org",
+              body: "Root topic",
+            }),
+        },
+        isDirectMessage: false,
+        getMemberDisplayName: async (_roomId, userId) =>
+          userId === "@alice:example.org" ? "Alice" : "sender",
+      });
+
+    await handler(
+      "!room:example.org",
+      createMatrixTextMessageEvent({
+        eventId: "$reply1",
+        body: "@room follow up",
+        relatesTo: {
+          rel_type: "m.thread",
+          event_id: "$thread-root",
+          "m.in_reply_to": { event_id: "$thread-root" },
+        },
+        mentions: { room: true },
+      }),
+    );
+
+    expect(finalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        MessageThreadId: "$thread-root",
+        ThreadStarterBody: "Matrix thread root $thread-root from Alice:\nRoot topic",
+      }),
+    );
+    // Thread messages get thread-scoped session keys (thread isolation feature).
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionKey: "agent:ops:main:thread:$thread-root",
+      }),
+    );
+  });
+
+  it("starts the thread-scoped session from the triggering message when threadReplies is always", async () => {
+    const { handler, finalizeInboundContext, recordInboundSession } =
+      createMatrixHandlerTestHarness({
+        isDirectMessage: false,
+        threadReplies: "always",
+      });
+
+    await handler(
+      "!room:example.org",
+      createMatrixTextMessageEvent({
+        eventId: "$thread-root",
+        body: "@room start thread",
+        mentions: { room: true },
+      }),
+    );
+
+    expect(finalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        MessageThreadId: "$thread-root",
+        ReplyToId: undefined,
+      }),
+    );
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionKey: "agent:ops:main:thread:$thread-root",
+      }),
+    );
+  });
+
+  it("records formatted poll results for inbound poll response events", async () => {
+    const { handler, finalizeInboundContext, recordInboundSession } =
+      createMatrixHandlerTestHarness({
+        client: {
+          getEvent: async () => ({
+            event_id: "$poll",
+            sender: "@bot:example.org",
+            type: "m.poll.start",
+            origin_server_ts: 1,
+            content: {
+              "m.poll.start": {
+                question: { "m.text": "Lunch?" },
+                kind: "m.poll.disclosed",
+                max_selections: 1,
+                answers: [
+                  { id: "a1", "m.text": "Pizza" },
+                  { id: "a2", "m.text": "Sushi" },
+                ],
+              },
+            },
+          }),
+          getRelations: async () => ({
+            events: [
+              {
+                type: "m.poll.response",
+                event_id: "$vote1",
+                sender: "@user:example.org",
+                origin_server_ts: 2,
+                content: {
+                  "m.poll.response": { answers: ["a1"] },
+                  "m.relates_to": { rel_type: "m.reference", event_id: "$poll" },
+                },
+              },
+            ],
+            nextBatch: null,
+            prevBatch: null,
+          }),
+        } as unknown as Partial<MatrixClient>,
+        isDirectMessage: true,
+        getMemberDisplayName: async (_roomId, userId) =>
+          userId === "@bot:example.org" ? "Bot" : "sender",
+      });
+
+    await handler("!room:example.org", {
+      type: "m.poll.response",
+      sender: "@user:example.org",
+      event_id: "$vote1",
+      origin_server_ts: 2,
+      content: {
+        "m.poll.response": { answers: ["a1"] },
+        "m.relates_to": { rel_type: "m.reference", event_id: "$poll" },
+      },
+    } as MatrixRawEvent);
+
+    expect(finalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        RawBody: expect.stringMatching(/1\. Pizza \(1 vote\)[\s\S]*Total voters: 1/),
+      }),
+    );
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        sessionKey: "agent:ops:main",
+      }),
+    );
+  });
+
+  it("records reply context for quoted poll start events inside always-threaded replies", async () => {
+    const { handler, finalizeInboundContext } = createMatrixHandlerTestHarness({
+      client: {
+        getEvent: async (_roomId: string, eventId: string) => {
+          if (eventId === "$thread-root") {
+            return createMatrixTextMessageEvent({
+              eventId: "$thread-root",
+              sender: "@bob:example.org",
+              body: "Root topic",
+            });
+          }
+
+          return {
+            event_id: "$poll",
+            sender: "@alice:example.org",
+            type: "m.poll.start",
+            origin_server_ts: 1,
+            content: {
+              "m.poll.start": {
+                question: { "m.text": "Lunch?" },
+                kind: "m.poll.disclosed",
+                max_selections: 1,
+                answers: [
+                  { id: "a1", "m.text": "Pizza" },
+                  { id: "a2", "m.text": "Sushi" },
+                ],
+              },
+            },
+          } satisfies MatrixRawEvent;
+        },
+      } as unknown as Partial<MatrixClient>,
+      isDirectMessage: false,
+      threadReplies: "always",
+      getMemberDisplayName: async (_roomId, userId) => {
+        if (userId === "@alice:example.org") {
+          return "Alice";
+        }
+        if (userId === "@bob:example.org") {
+          return "Bob";
+        }
+        return "sender";
+      },
+    });
+
+    await handler(
+      "!room:example.org",
+      createMatrixTextMessageEvent({
+        eventId: "$reply1",
+        body: "@room follow up",
+        relatesTo: {
+          rel_type: "m.thread",
+          event_id: "$thread-root",
+          "m.in_reply_to": { event_id: "$poll" },
+        },
+        mentions: { room: true },
+      }),
+    );
+
+    expect(finalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        MessageThreadId: "$thread-root",
+        ReplyToId: undefined,
+        ReplyToSender: "Alice",
+        ReplyToBody: "[Poll]\nLunch?\n\n1. Pizza\n2. Sushi",
+        ThreadStarterBody: "Matrix thread root $thread-root from Bob:\nRoot topic",
+      }),
+    );
+  });
+
+  it("reuses the fetched thread root when reply context points at the same event", async () => {
+    const getEvent = vi.fn(async () =>
+      createMatrixTextMessageEvent({
+        eventId: "$thread-root",
+        sender: "@alice:example.org",
+        body: "Root topic",
+      }),
+    );
+    const getMemberDisplayName = vi.fn(async (_roomId: string, userId: string) =>
+      userId === "@alice:example.org" ? "Alice" : "sender",
+    );
+    const { handler, finalizeInboundContext } = createMatrixHandlerTestHarness({
+      client: { getEvent },
+      isDirectMessage: false,
+      threadReplies: "always",
+      getMemberDisplayName,
+    });
+
+    await handler(
+      "!room:example.org",
+      createMatrixTextMessageEvent({
+        eventId: "$reply1",
+        body: "@room follow up",
+        relatesTo: {
+          rel_type: "m.thread",
+          event_id: "$thread-root",
+          "m.in_reply_to": { event_id: "$thread-root" },
+        },
+        mentions: { room: true },
+      }),
+    );
+
+    expect(finalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        MessageThreadId: "$thread-root",
+        ReplyToId: undefined,
+        ReplyToSender: "Alice",
+        ReplyToBody: "Root topic",
+        ThreadStarterBody: "Matrix thread root $thread-root from Alice:\nRoot topic",
+      }),
+    );
+    expect(getEvent).toHaveBeenCalledTimes(1);
+    expect(getMemberDisplayName).toHaveBeenCalledTimes(2);
+  });
+
+  it("drops thread and reply context fetched from non-allowlisted room senders", async () => {
+    const { handler, finalizeInboundContext } = createMatrixHandlerTestHarness({
+      client: {
+        getEvent: async () =>
+          createMatrixTextMessageEvent({
+            eventId: "$thread-root",
+            sender: "@mallory:example.org",
+            body: "Malicious root topic",
+          }),
+      },
+      isDirectMessage: false,
+      cfg: {
+        channels: {
+          matrix: {
+            contextVisibility: "allowlist",
+          },
+        },
+      },
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["@alice:example.org"],
+      roomsConfig: { "*": {} },
+      getMemberDisplayName: async (_roomId, userId) =>
+        userId === "@alice:example.org" ? "Alice" : "Mallory",
+    });
+
+    await handler(
+      "!room:example.org",
+      createMatrixTextMessageEvent({
+        eventId: "$reply1",
+        sender: "@alice:example.org",
+        body: "@room follow up",
+        relatesTo: {
+          rel_type: "m.thread",
+          event_id: "$thread-root",
+          "m.in_reply_to": { event_id: "$thread-root" },
+        },
+        mentions: { room: true },
+      }),
+    );
+
+    const finalized = vi.mocked(finalizeInboundContext).mock.calls.at(-1)?.[0] as {
+      ReplyToBody?: string;
+      ReplyToSender?: string;
+      ThreadStarterBody?: string;
+    };
+    expect(finalized.ThreadStarterBody).toBeUndefined();
+    expect(finalized.ReplyToBody).toBeUndefined();
+    expect(finalized.ReplyToSender).toBeUndefined();
+  });
+
+  it("drops quoted reply context fetched from non-allowlisted room senders", async () => {
+    const { handler, finalizeInboundContext } = createQuotedReplyVisibilityHarness("allowlist");
+
+    await sendQuotedReply(handler);
+
+    const finalized = latestFinalizedReplyContext(finalizeInboundContext);
+    expect(finalized.ReplyToBody).toBeUndefined();
+    expect(finalized.ReplyToSender).toBeUndefined();
+  });
+
+  it("keeps quoted reply context in allowlist_quote mode", async () => {
+    const { handler, finalizeInboundContext } =
+      createQuotedReplyVisibilityHarness("allowlist_quote");
+
+    await sendQuotedReply(handler);
+
+    const finalized = latestFinalizedReplyContext(finalizeInboundContext);
+    expect(finalized.ReplyToBody).toBe("Quoted payload");
+    expect(finalized.ReplyToSender).toBe("Mallory");
+  });
+});