@archipelagolab/lobi 1.0.0

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

@@ -0,0 +1,289 @@
+import { describe, expect, it, vi } from "vitest";
+import { setMatrixRuntime } from "../../runtime.js";
+import type { MatrixClient } from "../sdk.js";
+import * as sendModule from "../send.js";
+import { editMatrixMessage, readMatrixMessages } from "./messages.js";
+
+function installMatrixActionTestRuntime(): void {
+  setMatrixRuntime({
+    config: {
+      loadConfig: () => ({}),
+    },
+    channel: {
+      text: {
+        resolveMarkdownTableMode: () => "code",
+        convertMarkdownTables: (text: string) => text,
+      },
+    },
+  } as unknown as import("../../runtime-api.js").PluginRuntime);
+}
+
+function createPollResponseEvent(): Record<string, unknown> {
+  return {
+    event_id: "$vote",
+    sender: "@bob:example.org",
+    type: "m.poll.response",
+    origin_server_ts: 20,
+    content: {
+      "m.poll.response": { answers: ["a1"] },
+      "m.relates_to": { rel_type: "m.reference", event_id: "$poll" },
+    },
+  };
+}
+
+function createPollStartEvent(params?: {
+  answers?: Array<Record<string, unknown>>;
+  includeDisclosedKind?: boolean;
+  maxSelections?: number;
+}): Record<string, unknown> {
+  return {
+    event_id: "$poll",
+    sender: "@alice:example.org",
+    type: "m.poll.start",
+    origin_server_ts: 1,
+    content: {
+      "m.poll.start": {
+        question: { "m.text": "Favorite fruit?" },
+        ...(params?.includeDisclosedKind ? { kind: "m.poll.disclosed" } : {}),
+        ...(params?.maxSelections !== undefined ? { max_selections: params.maxSelections } : {}),
+        answers: params?.answers ?? [{ id: "a1", "m.text": "Apple" }],
+      },
+    },
+  };
+}
+
+function createMessagesClient(params: {
+  chunk: Array<Record<string, unknown>>;
+  hydratedChunk?: Array<Record<string, unknown>>;
+  pollRoot?: Record<string, unknown>;
+  pollRelations?: Array<Record<string, unknown>>;
+}) {
+  const doRequest = vi.fn(async () => ({
+    chunk: params.chunk,
+    start: "start-token",
+    end: "end-token",
+  }));
+  const hydrateEvents = vi.fn(
+    async (_roomId: string, _events: Array<Record<string, unknown>>) =>
+      (params.hydratedChunk ?? params.chunk) as unknown,
+  );
+  const getEvent = vi.fn(async () => params.pollRoot ?? null);
+  const getRelations = vi.fn(async () => ({
+    events: params.pollRelations ?? [],
+    nextBatch: null,
+    prevBatch: null,
+  }));
+
+  return {
+    client: {
+      doRequest,
+      hydrateEvents,
+      getEvent,
+      getRelations,
+      stop: vi.fn(),
+    } as unknown as MatrixClient,
+    doRequest,
+    hydrateEvents,
+    getEvent,
+    getRelations,
+  };
+}
+
+describe("matrix message actions", () => {
+  it("forwards timeoutMs to the shared Matrix edit helper", async () => {
+    const editSpy = vi.spyOn(sendModule, "editMessageMatrix").mockResolvedValue("evt-edit");
+
+    try {
+      const result = await editMatrixMessage("!room:example.org", "$original", "hello", {
+        timeoutMs: 12_345,
+      });
+
+      expect(result).toEqual({ eventId: "evt-edit" });
+      expect(editSpy).toHaveBeenCalledWith("!room:example.org", "$original", "hello", {
+        cfg: undefined,
+        accountId: undefined,
+        client: undefined,
+        timeoutMs: 12_345,
+      });
+    } finally {
+      editSpy.mockRestore();
+    }
+  });
+
+  it("routes edits through the shared Matrix edit helper so mentions are preserved", async () => {
+    installMatrixActionTestRuntime();
+    const sendMessage = vi.fn().mockResolvedValue("evt-edit");
+    const client = {
+      getEvent: vi.fn().mockResolvedValue({
+        content: {
+          body: "hello @alice:example.org",
+          "m.mentions": { user_ids: ["@alice:example.org"] },
+        },
+      }),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue([]),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      sendMessage,
+      prepareForOneOff: vi.fn(async () => undefined),
+      start: vi.fn(async () => undefined),
+      stop: vi.fn(() => undefined),
+      stopAndPersist: vi.fn(async () => undefined),
+    } as unknown as MatrixClient;
+
+    const result = await editMatrixMessage(
+      "!room:example.org",
+      "$original",
+      "hello @alice:example.org and @bob:example.org",
+      { client },
+    );
+
+    expect(result).toEqual({ eventId: "evt-edit" });
+    expect(sendMessage).toHaveBeenCalledWith(
+      "!room:example.org",
+      expect.objectContaining({
+        "m.mentions": { user_ids: ["@bob:example.org"] },
+        "m.new_content": expect.objectContaining({
+          "m.mentions": { user_ids: ["@alice:example.org", "@bob:example.org"] },
+        }),
+      }),
+    );
+  });
+
+  it("does not re-notify legacy mentions when action edits target pre-m.mentions messages", async () => {
+    installMatrixActionTestRuntime();
+    const sendMessage = vi.fn().mockResolvedValue("evt-edit");
+    const client = {
+      getEvent: vi.fn().mockResolvedValue({
+        content: {
+          body: "hello @alice:example.org",
+        },
+      }),
+      getJoinedRoomMembers: vi.fn().mockResolvedValue([]),
+      getUserId: vi.fn().mockResolvedValue("@bot:example.org"),
+      sendMessage,
+      prepareForOneOff: vi.fn(async () => undefined),
+      start: vi.fn(async () => undefined),
+      stop: vi.fn(() => undefined),
+      stopAndPersist: vi.fn(async () => undefined),
+    } as unknown as MatrixClient;
+
+    const result = await editMatrixMessage(
+      "!room:example.org",
+      "$original",
+      "hello again @alice:example.org",
+      { client },
+    );
+
+    expect(result).toEqual({ eventId: "evt-edit" });
+    expect(sendMessage).toHaveBeenCalledWith(
+      "!room:example.org",
+      expect.objectContaining({
+        "m.mentions": {},
+        "m.new_content": expect.objectContaining({
+          body: "hello again @alice:example.org",
+          "m.mentions": { user_ids: ["@alice:example.org"] },
+        }),
+      }),
+    );
+  });
+
+  it("includes poll snapshots when reading message history", async () => {
+    const { client, doRequest, getEvent, getRelations } = createMessagesClient({
+      chunk: [
+        createPollResponseEvent(),
+        {
+          event_id: "$msg",
+          sender: "@alice:example.org",
+          type: "m.room.message",
+          origin_server_ts: 10,
+          content: {
+            msgtype: "m.text",
+            body: "hello",
+          },
+        },
+      ],
+      pollRoot: createPollStartEvent({
+        includeDisclosedKind: true,
+        maxSelections: 1,
+        answers: [
+          { id: "a1", "m.text": "Apple" },
+          { id: "a2", "m.text": "Strawberry" },
+        ],
+      }),
+      pollRelations: [createPollResponseEvent()],
+    });
+
+    const result = await readMatrixMessages("room:!room:example.org", { client, limit: 2.9 });
+
+    expect(doRequest).toHaveBeenCalledWith(
+      "GET",
+      expect.stringContaining("/rooms/!room%3Aexample.org/messages"),
+      expect.objectContaining({ limit: 2 }),
+    );
+    expect(getEvent).toHaveBeenCalledWith("!room:example.org", "$poll");
+    expect(getRelations).toHaveBeenCalledWith(
+      "!room:example.org",
+      "$poll",
+      "m.reference",
+      undefined,
+      {
+        from: undefined,
+      },
+    );
+    expect(result.messages).toEqual([
+      expect.objectContaining({
+        eventId: "$poll",
+        body: expect.stringContaining("1. Apple (1 vote)"),
+        msgtype: "m.text",
+      }),
+      expect.objectContaining({
+        eventId: "$msg",
+        body: "hello",
+      }),
+    ]);
+  });
+
+  it("dedupes multiple poll events for the same poll within one read page", async () => {
+    const { client, getEvent } = createMessagesClient({
+      chunk: [createPollResponseEvent(), createPollStartEvent()],
+      pollRoot: createPollStartEvent(),
+      pollRelations: [],
+    });
+
+    const result = await readMatrixMessages("room:!room:example.org", { client });
+
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0]).toEqual(
+      expect.objectContaining({
+        eventId: "$poll",
+        body: expect.stringContaining("[Poll]"),
+      }),
+    );
+    expect(getEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it("uses hydrated history events so encrypted poll entries can be read", async () => {
+    const { client, hydrateEvents } = createMessagesClient({
+      chunk: [
+        {
+          event_id: "$enc",
+          sender: "@bob:example.org",
+          type: "m.room.encrypted",
+          origin_server_ts: 20,
+          content: {},
+        },
+      ],
+      hydratedChunk: [createPollResponseEvent()],
+      pollRoot: createPollStartEvent(),
+      pollRelations: [],
+    });
+
+    const result = await readMatrixMessages("room:!room:example.org", { client });
+
+    expect(hydrateEvents).toHaveBeenCalledWith(
+      "!room:example.org",
+      expect.arrayContaining([expect.objectContaining({ event_id: "$enc" })]),
+    );
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0]?.eventId).toBe("$poll");
+  });
+});

package/src/matrix/actions/messages.ts

@@ -0,0 +1,123 @@
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { fetchMatrixPollMessageSummary, resolveMatrixPollRootEventId } from "../poll-summary.js";
+import { isPollEventType } from "../poll-types.js";
+import { editMessageMatrix, sendMessageMatrix } from "../send.js";
+import { withResolvedRoomAction } from "./client.js";
+import { resolveMatrixActionLimit } from "./limits.js";
+import { summarizeMatrixRawEvent } from "./summary.js";
+import {
+  EventType,
+  type MatrixActionClientOpts,
+  type MatrixMessageSummary,
+  type MatrixRawEvent,
+} from "./types.js";
+
+export async function sendMatrixMessage(
+  to: string,
+  content: string | undefined,
+  opts: MatrixActionClientOpts & {
+    mediaUrl?: string;
+    replyToId?: string;
+    threadId?: string;
+    audioAsVoice?: boolean;
+  } = {},
+) {
+  return await sendMessageMatrix(to, content, {
+    cfg: opts.cfg,
+    mediaUrl: opts.mediaUrl,
+    mediaLocalRoots: opts.mediaLocalRoots,
+    replyToId: opts.replyToId,
+    threadId: opts.threadId,
+    audioAsVoice: opts.audioAsVoice,
+    accountId: opts.accountId ?? undefined,
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function editMatrixMessage(
+  roomId: string,
+  messageId: string,
+  content: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  const trimmed = content.trim();
+  if (!trimmed) {
+    throw new Error("Matrix edit requires content");
+  }
+  const eventId = await editMessageMatrix(roomId, messageId, trimmed, {
+    cfg: opts.cfg,
+    accountId: opts.accountId ?? undefined,
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+  });
+  return { eventId: eventId || null };
+}
+
+export async function deleteMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { reason?: string } = {},
+) {
+  await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    await client.redactEvent(resolvedRoom, messageId, opts.reason);
+  });
+}
+
+export async function readMatrixMessages(
+  roomId: string,
+  opts: MatrixActionClientOpts & {
+    limit?: number;
+    before?: string;
+    after?: string;
+  } = {},
+): Promise<{
+  messages: MatrixMessageSummary[];
+  nextBatch?: string | null;
+  prevBatch?: string | null;
+}> {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const limit = resolveMatrixActionLimit(opts.limit, 20);
+    const token = normalizeOptionalString(opts.before) ?? normalizeOptionalString(opts.after);
+    const dir = opts.after ? "f" : "b";
+    // Room history is queried via the low-level endpoint for compatibility.
+    const res = (await client.doRequest(
+      "GET",
+      `/_lobi/client/v3/rooms/${encodeURIComponent(resolvedRoom)}/messages`,
+      {
+        dir,
+        limit,
+        from: token,
+      },
+    )) as { chunk: MatrixRawEvent[]; start?: string; end?: string };
+    const hydratedChunk = await client.hydrateEvents(resolvedRoom, res.chunk);
+    const seenPollRoots = new Set<string>();
+    const messages: MatrixMessageSummary[] = [];
+    for (const event of hydratedChunk) {
+      if (event.unsigned?.redacted_because) {
+        continue;
+      }
+      if (event.type === EventType.RoomMessage) {
+        messages.push(summarizeMatrixRawEvent(event));
+        continue;
+      }
+      if (!isPollEventType(event.type)) {
+        continue;
+      }
+      const pollRootId = resolveMatrixPollRootEventId(event);
+      if (!pollRootId || seenPollRoots.has(pollRootId)) {
+        continue;
+      }
+      seenPollRoots.add(pollRootId);
+      const pollSummary = await fetchMatrixPollMessageSummary(client, resolvedRoom, event);
+      if (pollSummary) {
+        messages.push(pollSummary);
+      }
+    }
+    return {
+      messages,
+      nextBatch: res.end ?? null,
+      prevBatch: res.start ?? null,
+    };
+  });
+}

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

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from "vitest";
+import type { MatrixClient } from "../sdk.js";
+import { listMatrixPins, pinMatrixMessage, unpinMatrixMessage } from "./pins.js";
+
+function createPinsClient(seedPinned: string[], knownBodies: Record<string, string> = {}) {
+  let pinned = [...seedPinned];
+  const getRoomStateEvent = vi.fn(async () => ({ pinned: [...pinned] }));
+  const sendStateEvent = vi.fn(
+    async (_roomId: string, _type: string, _key: string, payload: unknown) => {
+      pinned = [...((payload as { pinned: string[] }).pinned ?? [])];
+    },
+  );
+  const getEvent = vi.fn(async (_roomId: string, eventId: string) => {
+    const body = knownBodies[eventId];
+    if (!body) {
+      throw new Error("missing");
+    }
+    return {
+      event_id: eventId,
+      sender: "@alice:example.org",
+      type: "m.room.message",
+      origin_server_ts: 123,
+      content: { msgtype: "m.text", body },
+    };
+  });
+
+  return {
+    client: {
+      getRoomStateEvent,
+      sendStateEvent,
+      getEvent,
+      stop: vi.fn(),
+    } as unknown as MatrixClient,
+    getPinned: () => pinned,
+    sendStateEvent,
+  };
+}
+
+describe("matrix pins actions", () => {
+  it("pins a message once even when asked twice", async () => {
+    const { client, getPinned, sendStateEvent } = createPinsClient(["$a"]);
+
+    const first = await pinMatrixMessage("!room:example.org", "$b", { client });
+    const second = await pinMatrixMessage("!room:example.org", "$b", { client });
+
+    expect(first.pinned).toEqual(["$a", "$b"]);
+    expect(second.pinned).toEqual(["$a", "$b"]);
+    expect(getPinned()).toEqual(["$a", "$b"]);
+    expect(sendStateEvent).toHaveBeenCalledTimes(2);
+  });
+
+  it("unpinds only the selected message id", async () => {
+    const { client, getPinned } = createPinsClient(["$a", "$b", "$c"]);
+
+    const result = await unpinMatrixMessage("!room:example.org", "$b", { client });
+
+    expect(result.pinned).toEqual(["$a", "$c"]);
+    expect(getPinned()).toEqual(["$a", "$c"]);
+  });
+
+  it("lists pinned ids and summarizes only resolvable events", async () => {
+    const { client } = createPinsClient(["$a", "$missing"], { $a: "hello" });
+
+    const result = await listMatrixPins("!room:example.org", { client });
+
+    expect(result.pinned).toEqual(["$a", "$missing"]);
+    expect(result.events).toEqual([
+      expect.objectContaining({
+        eventId: "$a",
+        body: "hello",
+      }),
+    ]);
+  });
+});

package/src/matrix/actions/pins.ts

@@ -0,0 +1,64 @@
+import { withResolvedRoomAction } from "./client.js";
+import { fetchEventSummary, readPinnedEvents } from "./summary.js";
+import {
+  EventType,
+  type MatrixActionClientOpts,
+  type MatrixMessageSummary,
+  type RoomPinnedEventsEventContent,
+} from "./types.js";
+
+async function updateMatrixPins(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts,
+  update: (current: string[]) => string[],
+): Promise<{ pinned: string[] }> {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const current = await readPinnedEvents(client, resolvedRoom);
+    const next = update(current);
+    const payload: RoomPinnedEventsEventContent = { pinned: next };
+    await client.sendStateEvent(resolvedRoom, EventType.RoomPinnedEvents, "", payload);
+    return { pinned: next };
+  });
+}
+
+export async function pinMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[] }> {
+  return await updateMatrixPins(roomId, messageId, opts, (current) =>
+    current.includes(messageId) ? current : [...current, messageId],
+  );
+}
+
+export async function unpinMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[] }> {
+  return await updateMatrixPins(roomId, messageId, opts, (current) =>
+    current.filter((id) => id !== messageId),
+  );
+}
+
+export async function listMatrixPins(
+  roomId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[]; events: MatrixMessageSummary[] }> {
+  return await withResolvedRoomAction(roomId, opts, async (client, resolvedRoom) => {
+    const pinned = await readPinnedEvents(client, resolvedRoom);
+    const events = (
+      await Promise.all(
+        pinned.map(async (eventId) => {
+          try {
+            return await fetchEventSummary(client, resolvedRoom, eventId);
+          } catch {
+            return null;
+          }
+        }),
+      )
+    ).filter((event): event is MatrixMessageSummary => Boolean(event));
+    return { pinned, events };
+  });
+}

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

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+import type { MatrixClient } from "../sdk.js";
+import { voteMatrixPoll } from "./polls.js";
+
+function createPollClient(pollContent?: Record<string, unknown>) {
+  const getEvent = vi.fn(async () => ({
+    type: "m.poll.start",
+    content: pollContent ?? {
+      "m.poll.start": {
+        question: { "m.text": "Favorite fruit?" },
+        max_selections: 1,
+        answers: [
+          { id: "apple", "m.text": "Apple" },
+          { id: "berry", "m.text": "Berry" },
+        ],
+      },
+    },
+  }));
+  const sendEvent = vi.fn(async () => "$vote1");
+
+  return {
+    client: {
+      getEvent,
+      sendEvent,
+      stop: vi.fn(),
+    } as unknown as MatrixClient,
+    getEvent,
+    sendEvent,
+  };
+}
+
+describe("matrix poll actions", () => {
+  it("votes by option index against the resolved room id", async () => {
+    const { client, getEvent, sendEvent } = createPollClient();
+
+    const result = await voteMatrixPoll("room:!room:example.org", "$poll", {
+      client,
+      optionIndex: 2,
+    });
+
+    expect(getEvent).toHaveBeenCalledWith("!room:example.org", "$poll");
+    expect(sendEvent).toHaveBeenCalledWith(
+      "!room:example.org",
+      "m.poll.response",
+      expect.objectContaining({
+        "m.poll.response": { answers: ["berry"] },
+      }),
+    );
+    expect(result).toEqual({
+      eventId: "$vote1",
+      roomId: "!room:example.org",
+      pollId: "$poll",
+      answerIds: ["berry"],
+      labels: ["Berry"],
+      maxSelections: 1,
+    });
+  });
+
+  it("rejects option indexes that are outside the poll range", async () => {
+    const { client, sendEvent } = createPollClient();
+
+    await expect(
+      voteMatrixPoll("room:!room:example.org", "$poll", {
+        client,
+        optionIndex: 3,
+      }),
+    ).rejects.toThrow("out of range");
+
+    expect(sendEvent).not.toHaveBeenCalled();
+  });
+});