@archipelagolab/lobi 1.0.0

package/src/matrix/send/targets.test.ts

@@ -0,0 +1,254 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { MatrixClient } from "../sdk.js";
+import { EventType } from "./types.js";
+
+const { resolveMatrixRoomId, normalizeThreadId } = await import("./targets.js");
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("resolveMatrixRoomId", () => {
+  it("uses m.direct when available", async () => {
+    const userId = "@user:example.org";
+    const client = {
+      getAccountData: vi.fn().mockResolvedValue({
+        [userId]: ["!room:example.org"],
+      }),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi.fn(),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot:example.org", userId]),
+      setAccountData: vi.fn(),
+    } as unknown as MatrixClient;
+
+    const roomId = await resolveMatrixRoomId(client, userId);
+
+    expect(roomId).toBe("!room:example.org");
+    expect(client.getJoinedRooms).not.toHaveBeenCalled();
+    expect(client.setAccountData).not.toHaveBeenCalled();
+  });
+
+  it("falls back to joined rooms and persists m.direct", async () => {
+    const userId = "@fallback:example.org";
+    const roomId = "!room:example.org";
+    const setAccountData = vi.fn().mockResolvedValue(undefined);
+    const client = {
+      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi.fn().mockResolvedValue([roomId]),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot:example.org", userId]),
+      setAccountData,
+    } as unknown as MatrixClient;
+
+    const resolved = await resolveMatrixRoomId(client, userId);
+
+    expect(resolved).toBe(roomId);
+    expect(setAccountData).toHaveBeenCalledWith(
+      EventType.Direct,
+      expect.objectContaining({ [userId]: [roomId] }),
+    );
+  });
+
+  it("prefers joined rooms marked direct in local member state over plain strict rooms", async () => {
+    const userId = "@fallback:example.org";
+    const client = {
+      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi.fn().mockResolvedValue(["!fallback:example.org", "!explicit:example.org"]),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot:example.org", userId]),
+      getRoomStateEvent: vi
+        .fn()
+        .mockImplementation(async (roomId: string, _eventType: string, stateKey: string) =>
+          roomId === "!explicit:example.org" && stateKey === "@bot:example.org"
+            ? { is_direct: true }
+            : {},
+        ),
+      setAccountData: vi.fn().mockResolvedValue(undefined),
+    } as unknown as MatrixClient;
+
+    const resolved = await resolveMatrixRoomId(client, userId);
+
+    expect(resolved).toBe("!explicit:example.org");
+    expect(client.setAccountData).toHaveBeenCalledWith(
+      EventType.Direct,
+      expect.objectContaining({ [userId]: ["!explicit:example.org"] }),
+    );
+  });
+
+  it("ignores remote member-state direct flags when resolving a direct room", async () => {
+    const userId = "@fallback:example.org";
+    const client = {
+      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi
+        .fn()
+        .mockResolvedValue(["!fallback:example.org", "!remote-marked:example.org"]),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot:example.org", userId]),
+      getRoomStateEvent: vi
+        .fn()
+        .mockImplementation(async (roomId: string, _eventType: string, stateKey: string) =>
+          roomId === "!remote-marked:example.org" && stateKey === userId ? { is_direct: true } : {},
+        ),
+      setAccountData: vi.fn().mockResolvedValue(undefined),
+    } as unknown as MatrixClient;
+
+    const resolved = await resolveMatrixRoomId(client, userId);
+
+    expect(resolved).toBe("!fallback:example.org");
+    expect(client.setAccountData).toHaveBeenCalledWith(
+      EventType.Direct,
+      expect.objectContaining({ [userId]: ["!fallback:example.org"] }),
+    );
+  });
+
+  it("continues when a room member lookup fails", async () => {
+    const userId = "@continue:example.org";
+    const roomId = "!good:example.org";
+    const setAccountData = vi.fn().mockResolvedValue(undefined);
+    const getJoinedRoomMembers = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("boom"))
+      .mockResolvedValueOnce(["@bot:example.org", userId]);
+    const client = {
+      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi.fn().mockResolvedValue(["!bad:example.org", roomId]),
+      getJoinedRoomMembers,
+      setAccountData,
+    } as unknown as MatrixClient;
+
+    const resolved = await resolveMatrixRoomId(client, userId);
+
+    expect(resolved).toBe(roomId);
+    expect(setAccountData).toHaveBeenCalled();
+  });
+
+  it("does not fall back to larger shared rooms for direct-user sends", async () => {
+    const userId = "@group:example.org";
+    const roomId = "!group:example.org";
+    const client = {
+      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi.fn().mockResolvedValue([roomId]),
+      getJoinedRoomMembers: vi
+        .fn()
+        .mockResolvedValue(["@bot:example.org", userId, "@extra:example.org"]),
+      setAccountData: vi.fn().mockResolvedValue(undefined),
+    } as unknown as MatrixClient;
+
+    await expect(resolveMatrixRoomId(client, userId)).rejects.toThrow(
+      `No direct room found for ${userId} (m.direct missing)`,
+    );
+    expect(client.setAccountData).not.toHaveBeenCalled();
+  });
+
+  it("accepts nested Matrix user target prefixes", async () => {
+    const userId = "@prefixed:example.org";
+    const roomId = "!prefixed-room:example.org";
+    const client = {
+      getAccountData: vi.fn().mockResolvedValue({
+        [userId]: [roomId],
+      }),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi.fn(),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot:example.org", userId]),
+      setAccountData: vi.fn(),
+      resolveRoom: vi.fn(),
+    } as unknown as MatrixClient;
+
+    const resolved = await resolveMatrixRoomId(client, `matrix:user:${userId}`);
+
+    expect(resolved).toBe(roomId);
+    expect(client.resolveRoom).not.toHaveBeenCalled();
+  });
+
+  it("scopes direct-room cache per Matrix client", async () => {
+    const userId = "@shared:example.org";
+    const clientA = {
+      getAccountData: vi.fn().mockResolvedValue({
+        [userId]: ["!room-a:example.org"],
+      }),
+      getUserId: vi.fn().mockResolvedValue("@bot-a:example.org"),
+      getJoinedRooms: vi.fn(),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot-a:example.org", userId]),
+      setAccountData: vi.fn(),
+      resolveRoom: vi.fn(),
+    } as unknown as MatrixClient;
+    const clientB = {
+      getAccountData: vi.fn().mockResolvedValue({
+        [userId]: ["!room-b:example.org"],
+      }),
+      getUserId: vi.fn().mockResolvedValue("@bot-b:example.org"),
+      getJoinedRooms: vi.fn(),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot-b:example.org", userId]),
+      setAccountData: vi.fn(),
+      resolveRoom: vi.fn(),
+    } as unknown as MatrixClient;
+
+    await expect(resolveMatrixRoomId(clientA, userId)).resolves.toBe("!room-a:example.org");
+    await expect(resolveMatrixRoomId(clientB, userId)).resolves.toBe("!room-b:example.org");
+
+    expect(clientA.getAccountData).toHaveBeenCalledTimes(1);
+    expect(clientB.getAccountData).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores m.direct entries that point at shared rooms", async () => {
+    const userId = "@shared:example.org";
+    const client = {
+      getAccountData: vi.fn().mockResolvedValue({
+        [userId]: ["!shared-room:example.org", "!dm-room:example.org"],
+      }),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi.fn(),
+      getJoinedRoomMembers: vi
+        .fn()
+        .mockResolvedValueOnce(["@bot:example.org", userId, "@extra:example.org"])
+        .mockResolvedValueOnce(["@bot:example.org", userId]),
+      setAccountData: vi.fn(),
+      resolveRoom: vi.fn(),
+    } as unknown as MatrixClient;
+
+    await expect(resolveMatrixRoomId(client, userId)).resolves.toBe("!dm-room:example.org");
+  });
+
+  it("revalidates cached direct rooms before reuse when membership changes", async () => {
+    const userId = "@shared:example.org";
+    const directRooms = ["!dm-room-1:example.org"];
+    const membersByRoom = new Map<string, string[]>([
+      ["!dm-room-1:example.org", ["@bot:example.org", userId]],
+      ["!dm-room-2:example.org", ["@bot:example.org", userId]],
+    ]);
+    const client = {
+      getAccountData: vi.fn().mockImplementation(async () => ({
+        [userId]: [...directRooms],
+      })),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      getJoinedRooms: vi
+        .fn()
+        .mockResolvedValue(["!dm-room-1:example.org", "!dm-room-2:example.org"]),
+      getJoinedRoomMembers: vi
+        .fn()
+        .mockImplementation(async (roomId: string) => membersByRoom.get(roomId) ?? []),
+      setAccountData: vi.fn(),
+      resolveRoom: vi.fn(),
+    } as unknown as MatrixClient;
+
+    await expect(resolveMatrixRoomId(client, userId)).resolves.toBe("!dm-room-1:example.org");
+
+    directRooms.splice(0, directRooms.length, "!dm-room-1:example.org", "!dm-room-2:example.org");
+    membersByRoom.set("!dm-room-1:example.org", [
+      "@bot:example.org",
+      userId,
+      "@mallory:example.org",
+    ]);
+
+    await expect(resolveMatrixRoomId(client, userId)).resolves.toBe("!dm-room-2:example.org");
+  });
+});
+
+describe("normalizeThreadId", () => {
+  it("returns null for empty thread ids", () => {
+    expect(normalizeThreadId("   ")).toBeNull();
+    expect(normalizeThreadId("$thread")).toBe("$thread");
+  });
+});

package/src/matrix/send/targets.ts

@@ -0,0 +1,104 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalStringifiedId,
+} from "openclaw/plugin-sdk/text-runtime";
+import { inspectMatrixDirectRooms, persistMatrixDirectRoomMapping } from "../direct-management.js";
+import { isStrictDirectRoom } from "../direct-room.js";
+import type { MatrixClient } from "../sdk.js";
+import { isMatrixQualifiedUserId, normalizeMatrixResolvableTarget } from "../target-ids.js";
+
+function normalizeTarget(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("Matrix target is required (room:<id> or #alias)");
+  }
+  return trimmed;
+}
+
+export function normalizeThreadId(raw?: string | number | null): string | null {
+  return normalizeOptionalStringifiedId(raw) ?? null;
+}
+
+// Size-capped to prevent unbounded growth (#4948)
+const MAX_DIRECT_ROOM_CACHE_SIZE = 1024;
+const directRoomCacheByClient = new WeakMap<MatrixClient, Map<string, string>>();
+
+function resolveDirectRoomCache(client: MatrixClient): Map<string, string> {
+  const existing = directRoomCacheByClient.get(client);
+  if (existing) {
+    return existing;
+  }
+  const created = new Map<string, string>();
+  directRoomCacheByClient.set(client, created);
+  return created;
+}
+
+function setDirectRoomCached(client: MatrixClient, key: string, value: string): void {
+  const directRoomCache = resolveDirectRoomCache(client);
+  directRoomCache.set(key, value);
+  if (directRoomCache.size > MAX_DIRECT_ROOM_CACHE_SIZE) {
+    const oldest = directRoomCache.keys().next().value;
+    if (oldest !== undefined) {
+      directRoomCache.delete(oldest);
+    }
+  }
+}
+
+async function resolveDirectRoomId(client: MatrixClient, userId: string): Promise<string> {
+  const trimmed = userId.trim();
+  if (!isMatrixQualifiedUserId(trimmed)) {
+    throw new Error(`Matrix user IDs must be fully qualified (got "${trimmed}")`);
+  }
+  const selfUserId = (await client.getUserId().catch(() => null))?.trim() || null;
+
+  const directRoomCache = resolveDirectRoomCache(client);
+  const cached = directRoomCache.get(trimmed);
+  if (
+    cached &&
+    (await isStrictDirectRoom({ client, roomId: cached, remoteUserId: trimmed, selfUserId }))
+  ) {
+    return cached;
+  }
+  if (cached) {
+    directRoomCache.delete(trimmed);
+  }
+
+  const inspection = await inspectMatrixDirectRooms({
+    client,
+    remoteUserId: trimmed,
+  });
+  if (inspection.activeRoomId) {
+    setDirectRoomCached(client, trimmed, inspection.activeRoomId);
+    if (inspection.mappedRoomIds[0] !== inspection.activeRoomId) {
+      await persistMatrixDirectRoomMapping({
+        client,
+        remoteUserId: trimmed,
+        roomId: inspection.activeRoomId,
+      }).catch(() => {
+        // Ignore persistence errors when send resolution has already found a usable room.
+      });
+    }
+    return inspection.activeRoomId;
+  }
+
+  throw new Error(`No direct room found for ${trimmed} (m.direct missing)`);
+}
+
+export async function resolveMatrixRoomId(client: MatrixClient, raw: string): Promise<string> {
+  const target = normalizeMatrixResolvableTarget(normalizeTarget(raw));
+  const lowered = normalizeLowercaseStringOrEmpty(target);
+  if (lowered.startsWith("user:")) {
+    return await resolveDirectRoomId(client, target.slice("user:".length));
+  }
+  if (isMatrixQualifiedUserId(target)) {
+    return await resolveDirectRoomId(client, target);
+  }
+  if (target.startsWith("#")) {
+    const resolved = await client.resolveRoom(target);
+    if (!resolved) {
+      throw new Error(`Matrix alias ${target} could not be resolved`);
+    }
+    return resolved;
+  }
+  return target;
+}

package/src/matrix/send/types.ts

@@ -0,0 +1,134 @@
+import type { CoreConfig } from "../../types.js";
+import {
+  MATRIX_ANNOTATION_RELATION_TYPE,
+  MATRIX_REACTION_EVENT_TYPE,
+  type MatrixReactionEventContent,
+} from "../reaction-common.js";
+import type {
+  DimensionalFileInfo,
+  EncryptedFile,
+  FileWithThumbnailInfo,
+  MessageEventContent,
+  TextualMessageEventContent,
+  TimedFileInfo,
+  VideoFileInfo,
+} from "../sdk.js";
+
+// Message types
+export const MsgType = {
+  Text: "m.text",
+  Image: "m.image",
+  Audio: "m.audio",
+  Video: "m.video",
+  File: "m.file",
+  Notice: "m.notice",
+} as const;
+
+// Relation types
+export const RelationType = {
+  Annotation: MATRIX_ANNOTATION_RELATION_TYPE,
+  Replace: "m.replace",
+  Thread: "m.thread",
+} as const;
+
+// Event types
+export const EventType = {
+  Direct: "m.direct",
+  Reaction: MATRIX_REACTION_EVENT_TYPE,
+  RoomMessage: "m.room.message",
+} as const;
+
+export const MATRIX_OPENCLAW_FINALIZED_PREVIEW_KEY = "com.openclaw.finalized_preview" as const;
+
+export type MatrixDirectAccountData = Record<string, string[]>;
+
+export type MatrixReplyRelation = {
+  "m.in_reply_to": { event_id: string };
+};
+
+export type MatrixThreadRelation = {
+  rel_type: typeof RelationType.Thread;
+  event_id: string;
+  is_falling_back?: boolean;
+  "m.in_reply_to"?: { event_id: string };
+};
+
+export type MatrixRelation = MatrixReplyRelation | MatrixThreadRelation;
+
+export type MatrixReplyMeta = {
+  "m.relates_to"?: MatrixRelation;
+};
+
+export type MatrixMediaInfo =
+  | FileWithThumbnailInfo
+  | DimensionalFileInfo
+  | TimedFileInfo
+  | VideoFileInfo;
+
+export type MatrixTextContent = TextualMessageEventContent & MatrixReplyMeta;
+
+export type MatrixMediaContent = MessageEventContent &
+  MatrixReplyMeta & {
+    info?: MatrixMediaInfo;
+    url?: string;
+    file?: EncryptedFile;
+    filename?: string;
+    "org.matrix.msc3245.voice"?: Record<string, never>;
+    "org.matrix.msc1767.audio"?: { duration: number };
+  };
+
+export type MatrixOutboundContent = MatrixTextContent | MatrixMediaContent;
+
+export type ReactionEventContent = MatrixReactionEventContent;
+
+export type MatrixSendResult = {
+  messageId: string;
+  roomId: string;
+  primaryMessageId?: string;
+  messageIds?: string[];
+};
+
+export type MatrixSendOpts = {
+  client?: import("../sdk.js").MatrixClient;
+  cfg?: CoreConfig;
+  mediaUrl?: string;
+  mediaAccess?: {
+    localRoots?: readonly string[];
+    readFile?: (filePath: string) => Promise<Buffer>;
+  };
+  mediaLocalRoots?: readonly string[];
+  mediaReadFile?: (filePath: string) => Promise<Buffer>;
+  accountId?: string;
+  replyToId?: string;
+  threadId?: string | number | null;
+  timeoutMs?: number;
+  /** Send audio as voice message instead of audio file. Defaults to false. */
+  audioAsVoice?: boolean;
+};
+
+export type MatrixMediaMsgType =
+  | typeof MsgType.Image
+  | typeof MsgType.Audio
+  | typeof MsgType.Video
+  | typeof MsgType.File;
+
+export type MatrixTextMsgType = typeof MsgType.Text | typeof MsgType.Notice;
+
+export type MediaKind = "image" | "audio" | "video" | "document" | "unknown";
+
+export type MatrixFormattedContent = MessageEventContent & {
+  format?: string;
+  formatted_body?: string;
+};
+
+export type MatrixExtraContentFields = Record<string, unknown>;
+
+/**
+ * MSC4357 live marker key.
+ * When present on event content, signals that the message is still being
+ * streamed (e.g. an LLM generating a response). Supporting clients render
+ * the message with a streaming animation until an edit without this marker
+ * arrives, indicating the stream is complete.
+ * @see https://github.com/matrix-org/matrix-spec-proposals/pull/4357
+ */
+export const MSC4357_LIVE_KEY = "org.matrix.msc4357.live" as const;