@archipelagolab/lobi 1.0.0

package/src/matrix/draft-stream.test.ts

@@ -0,0 +1,406 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PluginRuntime } from "../runtime-api.js";
+
+const loadConfigMock = vi.fn(() => ({}));
+const resolveTextChunkLimitMock = vi.fn<
+  (cfg: unknown, channel: unknown, accountId?: unknown) => number
+>(() => 4000);
+const resolveChunkModeMock = vi.fn<(cfg: unknown, channel: unknown, accountId?: unknown) => string>(
+  () => "length",
+);
+const chunkMarkdownTextWithModeMock = vi.fn((text: string) => (text ? [text] : []));
+const convertMarkdownTablesMock = vi.fn((text: string) => text);
+const runtimeStub = {
+  config: { loadConfig: () => loadConfigMock() },
+  channel: {
+    text: {
+      resolveTextChunkLimit: (cfg: unknown, channel: unknown, accountId?: unknown) =>
+        resolveTextChunkLimitMock(cfg, channel, accountId),
+      resolveChunkMode: (cfg: unknown, channel: unknown, accountId?: unknown) =>
+        resolveChunkModeMock(cfg, channel, accountId),
+      chunkMarkdownText: (text: string) => (text ? [text] : []),
+      chunkMarkdownTextWithMode: (text: string) => chunkMarkdownTextWithModeMock(text),
+      resolveMarkdownTableMode: () => "code",
+      convertMarkdownTables: (text: string) => convertMarkdownTablesMock(text),
+    },
+  },
+} as unknown as PluginRuntime;
+
+let createMatrixDraftStream: typeof import("./draft-stream.js").createMatrixDraftStream;
+
+const sendMessageMock = vi.fn();
+const sendEventMock = vi.fn();
+const joinedRoomsMock = vi.fn().mockResolvedValue([]);
+
+function createMockClient() {
+  sendMessageMock.mockReset().mockResolvedValue("$evt1");
+  sendEventMock.mockReset().mockResolvedValue("$evt2");
+  joinedRoomsMock.mockReset().mockResolvedValue(["!room:test"]);
+  return {
+    sendMessage: sendMessageMock,
+    sendEvent: sendEventMock,
+    getJoinedRooms: joinedRoomsMock,
+    prepareForOneOff: vi.fn().mockResolvedValue(undefined),
+    start: vi.fn().mockResolvedValue(undefined),
+  } as unknown as import("./sdk.js").MatrixClient;
+}
+
+beforeAll(async () => {
+  const runtimeModule = await import("../runtime.js");
+  runtimeModule.setMatrixRuntime(runtimeStub);
+  ({ createMatrixDraftStream } = await import("./draft-stream.js"));
+});
+
+describe("createMatrixDraftStream", () => {
+  let client: ReturnType<typeof createMockClient>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    client = createMockClient();
+    resolveTextChunkLimitMock.mockReset().mockReturnValue(4000);
+    resolveChunkModeMock.mockReset().mockReturnValue("length");
+    chunkMarkdownTextWithModeMock
+      .mockReset()
+      .mockImplementation((text: string) => (text ? [text] : []));
+    convertMarkdownTablesMock.mockReset().mockImplementation((text: string) => text);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("sends a normal text preview on first partial update", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+    });
+
+    stream.update("Hello");
+    await stream.flush();
+
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+    expect(sendMessageMock.mock.calls[0]?.[1]).toMatchObject({
+      msgtype: "m.text",
+    });
+    expect(stream.eventId()).toBe("$evt1");
+  });
+
+  it("sends quiet preview notices when quiet mode is enabled", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      mode: "quiet",
+    });
+
+    stream.update("Hello");
+    await stream.flush();
+
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+    expect(sendMessageMock.mock.calls[0]?.[1]).toMatchObject({
+      msgtype: "m.notice",
+    });
+    expect(sendMessageMock.mock.calls[0]?.[1]).not.toHaveProperty("m.mentions");
+  });
+
+  it("edits the message on subsequent quiet updates", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      mode: "quiet",
+    });
+
+    stream.update("Hello");
+    await stream.flush();
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+
+    // Advance past throttle window so the next update fires immediately.
+    vi.advanceTimersByTime(1000);
+
+    stream.update("Hello world");
+    await stream.flush();
+
+    // First call = initial send, second call = edit (both go through sendMessage)
+    expect(sendMessageMock).toHaveBeenCalledTimes(2);
+    expect(sendMessageMock.mock.calls[1]?.[1]).toMatchObject({
+      msgtype: "m.notice",
+      "m.new_content": { msgtype: "m.notice" },
+    });
+  });
+
+  it("coalesces rapid quiet updates within throttle window", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      mode: "quiet",
+    });
+
+    stream.update("A");
+    stream.update("AB");
+    stream.update("ABC");
+    await stream.flush();
+
+    // First update fires immediately (fresh throttle window), then AB/ABC
+    // coalesce into a single edit with the latest text.
+    expect(sendMessageMock).toHaveBeenCalledTimes(2);
+    expect(sendMessageMock.mock.calls[0][1]).toMatchObject({ body: "A" });
+    // Edit uses "* <text>" prefix per Matrix m.replace spec.
+    expect(sendMessageMock.mock.calls[1][1]).toMatchObject({ body: "* ABC" });
+    expect(sendMessageMock.mock.calls[0][1]).toMatchObject({ msgtype: "m.notice" });
+    expect(sendMessageMock.mock.calls[1][1]).toMatchObject({
+      msgtype: "m.notice",
+      "m.new_content": { msgtype: "m.notice" },
+    });
+  });
+
+  it("skips no-op updates", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+    });
+
+    stream.update("Hello");
+    await stream.flush();
+    const callCount = sendMessageMock.mock.calls.length;
+
+    vi.advanceTimersByTime(1000);
+
+    // Same text again — should not send
+    stream.update("Hello");
+    await stream.flush();
+    expect(sendMessageMock).toHaveBeenCalledTimes(callCount);
+  });
+
+  it("ignores updates after stop", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+    });
+
+    stream.update("Hello");
+    await stream.stop();
+    const callCount = sendMessageMock.mock.calls.length;
+
+    stream.update("Ignored");
+    await stream.flush();
+    expect(sendMessageMock).toHaveBeenCalledTimes(callCount);
+  });
+
+  it("stop returns the event ID", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+    });
+
+    stream.update("Hello");
+    const eventId = await stream.stop();
+    expect(eventId).toBe("$evt1");
+  });
+
+  it("stop does not finalize live drafts on its own", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      mode: "partial",
+    });
+
+    stream.update("Hello");
+    await stream.stop();
+
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+    expect(sendMessageMock.mock.calls[0]?.[1]).toHaveProperty("org.matrix.msc4357.live");
+  });
+
+  it("finalizeLive clears the live marker at most once", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      mode: "partial",
+    });
+
+    stream.update("Hello");
+    await stream.stop();
+
+    await stream.finalizeLive();
+    await stream.finalizeLive();
+
+    expect(sendMessageMock).toHaveBeenCalledTimes(2);
+    expect(sendMessageMock.mock.calls[1]?.[1]).not.toHaveProperty("org.matrix.msc4357.live");
+  });
+
+  it("marks live finalize failures for normal final delivery fallback", async () => {
+    sendMessageMock.mockResolvedValueOnce("$evt1").mockRejectedValueOnce(new Error("rate limited"));
+
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      mode: "partial",
+    });
+
+    stream.update("Hello");
+    await stream.stop();
+
+    await expect(stream.finalizeLive()).resolves.toBe(false);
+    expect(stream.mustDeliverFinalNormally()).toBe(true);
+  });
+
+  it("reset allows reuse for next block", async () => {
+    sendMessageMock.mockResolvedValueOnce("$first").mockResolvedValueOnce("$second");
+
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      mode: "quiet",
+    });
+
+    stream.update("Block 1");
+    await stream.stop();
+    expect(stream.eventId()).toBe("$first");
+
+    stream.reset();
+    expect(stream.eventId()).toBeUndefined();
+
+    stream.update("Block 2");
+    await stream.stop();
+    expect(stream.eventId()).toBe("$second");
+  });
+
+  it("stops retrying after send failure", async () => {
+    sendMessageMock.mockRejectedValueOnce(new Error("network error"));
+
+    const log = vi.fn();
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      log,
+    });
+
+    stream.update("Hello");
+    await stream.flush();
+
+    // Should have logged the failure
+    expect(log).toHaveBeenCalledWith(expect.stringContaining("send/edit failed"));
+
+    vi.advanceTimersByTime(1000);
+
+    // Further updates should not attempt sends (stream is stopped)
+    stream.update("More text");
+    await stream.flush();
+
+    // Only the initial failed attempt
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+    expect(stream.eventId()).toBeUndefined();
+  });
+
+  it("skips empty/whitespace text", async () => {
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+    });
+
+    stream.update("   ");
+    await stream.flush();
+
+    expect(sendMessageMock).not.toHaveBeenCalled();
+  });
+
+  it("stops on edit failure mid-stream", async () => {
+    sendMessageMock
+      .mockResolvedValueOnce("$evt1") // initial send succeeds
+      .mockRejectedValueOnce(new Error("rate limited")); // edit fails
+
+    const log = vi.fn();
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      log,
+    });
+
+    stream.update("Hello");
+    await stream.flush();
+    expect(stream.eventId()).toBe("$evt1");
+
+    vi.advanceTimersByTime(1000);
+
+    stream.update("Hello world");
+    await stream.flush();
+    expect(log).toHaveBeenCalledWith(expect.stringContaining("send/edit failed"));
+
+    vi.advanceTimersByTime(1000);
+
+    // Stream should be stopped — further updates are ignored
+    stream.update("More text");
+    await stream.flush();
+    expect(sendMessageMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("bypasses newline chunking for the draft preview message", async () => {
+    resolveChunkModeMock.mockReturnValue("newline");
+    chunkMarkdownTextWithModeMock.mockImplementation((text: string) => text.split("\n"));
+
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+    });
+
+    stream.update("line 1\nline 2");
+    await stream.flush();
+
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+    expect(sendMessageMock.mock.calls[0]?.[1]).toMatchObject({ body: "line 1\nline 2" });
+  });
+
+  it("falls back to normal delivery when preview text exceeds one Matrix event", async () => {
+    const log = vi.fn();
+    resolveTextChunkLimitMock.mockReturnValue(5);
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      log,
+    });
+
+    stream.update("123456");
+    await stream.flush();
+
+    expect(sendMessageMock).not.toHaveBeenCalled();
+    expect(stream.eventId()).toBeUndefined();
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining("preview exceeded single-event limit"),
+    );
+  });
+
+  it("uses converted Matrix text when checking the single-event preview limit", async () => {
+    const log = vi.fn();
+    resolveTextChunkLimitMock.mockReturnValue(5);
+    convertMarkdownTablesMock.mockImplementation(() => "123456");
+    const stream = createMatrixDraftStream({
+      roomId: "!room:test",
+      client,
+      cfg: {} as import("../types.js").CoreConfig,
+      log,
+    });
+
+    stream.update("1234");
+    await stream.flush();
+
+    expect(sendMessageMock).not.toHaveBeenCalled();
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining("preview exceeded single-event limit"),
+    );
+  });
+});

package/src/matrix/draft-stream.ts

@@ -0,0 +1,216 @@
+import { createDraftStreamLoop } from "openclaw/plugin-sdk/channel-lifecycle";
+import type { CoreConfig } from "../types.js";
+import type { MatrixClient } from "./sdk.js";
+import { editMessageMatrix, prepareMatrixSingleText, sendSingleTextMessageMatrix } from "./send.js";
+import { MsgType } from "./send/types.js";
+
+const DEFAULT_THROTTLE_MS = 1000;
+type MatrixDraftPreviewMode = "partial" | "quiet";
+
+function resolveDraftPreviewOptions(mode: MatrixDraftPreviewMode): {
+  msgtype: typeof MsgType.Text | typeof MsgType.Notice;
+  includeMentions?: boolean;
+} {
+  if (mode === "quiet") {
+    return {
+      msgtype: MsgType.Notice,
+      includeMentions: false,
+    };
+  }
+  return {
+    msgtype: MsgType.Text,
+  };
+}
+
+export type MatrixDraftStream = {
+  /** Update the draft with the latest accumulated text for the current block. */
+  update: (text: string) => void;
+  /** Ensure the last pending update has been sent. */
+  flush: () => Promise<void>;
+  /** Flush and mark this block as done. Returns the event ID if a message was sent. */
+  stop: () => Promise<string | undefined>;
+  /** Clear the MSC4357 live marker in place when the draft is kept as final text. */
+  finalizeLive: () => Promise<boolean>;
+  /** Reset state for the next text block (after tool calls). */
+  reset: () => void;
+  /** The event ID of the current draft message, if any. */
+  eventId: () => string | undefined;
+  /** True when the provided text matches the last rendered draft payload. */
+  matchesPreparedText: (text: string) => boolean;
+  /** True when preview streaming must fall back to normal final delivery. */
+  mustDeliverFinalNormally: () => boolean;
+};
+
+export function createMatrixDraftStream(params: {
+  roomId: string;
+  client: MatrixClient;
+  cfg: CoreConfig;
+  mode?: MatrixDraftPreviewMode;
+  threadId?: string;
+  replyToId?: string;
+  /** When true, reset() restores the original replyToId instead of clearing it. */
+  preserveReplyId?: boolean;
+  accountId?: string;
+  log?: (message: string) => void;
+}): MatrixDraftStream {
+  const { roomId, client, cfg, threadId, accountId, log } = params;
+  const preview = resolveDraftPreviewOptions(params.mode ?? "partial");
+  // MSC4357 live markers are only useful for "partial" mode where users see
+  // the draft evolve. "quiet" mode uses m.notice for background previews
+  // where a streaming animation would be unexpected.
+  const useLive = params.mode !== "quiet";
+
+  let currentEventId: string | undefined;
+  let lastSentText = "";
+  let stopped = false;
+  let sendFailed = false;
+  let finalizeInPlaceBlocked = false;
+  let liveFinalized = false;
+  let replyToId = params.replyToId;
+
+  const sendOrEdit = async (text: string): Promise<boolean> => {
+    const trimmed = text.trimEnd();
+    if (!trimmed) {
+      return false;
+    }
+    const preparedText = prepareMatrixSingleText(trimmed, { cfg, accountId });
+    if (!preparedText.fitsInSingleEvent) {
+      finalizeInPlaceBlocked = true;
+      if (!currentEventId) {
+        sendFailed = true;
+      }
+      stopped = true;
+      log?.(
+        `draft-stream: preview exceeded single-event limit (${preparedText.convertedText.length} > ${preparedText.singleEventLimit})`,
+      );
+      return false;
+    }
+    if (sendFailed) {
+      return false;
+    }
+    if (preparedText.trimmedText === lastSentText) {
+      return true;
+    }
+    try {
+      if (!currentEventId) {
+        const result = await sendSingleTextMessageMatrix(roomId, preparedText.trimmedText, {
+          client,
+          cfg,
+          replyToId,
+          threadId,
+          accountId,
+          msgtype: preview.msgtype,
+          includeMentions: preview.includeMentions,
+          live: useLive,
+        });
+        currentEventId = result.messageId;
+        lastSentText = preparedText.trimmedText;
+        log?.(`draft-stream: created message ${currentEventId}${useLive ? " (MSC4357 live)" : ""}`);
+      } else {
+        await editMessageMatrix(roomId, currentEventId, preparedText.trimmedText, {
+          client,
+          cfg,
+          threadId,
+          accountId,
+          msgtype: preview.msgtype,
+          includeMentions: preview.includeMentions,
+          live: useLive,
+        });
+        lastSentText = preparedText.trimmedText;
+      }
+      return true;
+    } catch (err) {
+      log?.(`draft-stream: send/edit failed: ${String(err)}`);
+      const isPreviewLimitError =
+        err instanceof Error && err.message.startsWith("Matrix single-message text exceeds limit");
+      if (isPreviewLimitError) {
+        finalizeInPlaceBlocked = true;
+      }
+      if (!currentEventId) {
+        sendFailed = true;
+      }
+      stopped = true;
+      return false;
+    }
+  };
+
+  const loop = createDraftStreamLoop({
+    throttleMs: DEFAULT_THROTTLE_MS,
+    isStopped: () => stopped,
+    sendOrEditStreamMessage: sendOrEdit,
+  });
+
+  log?.(`draft-stream: ready (throttleMs=${DEFAULT_THROTTLE_MS})`);
+
+  const finalizeLive = async (): Promise<boolean> => {
+    // Send a final edit without the MSC4357 live marker to signal that
+    // the stream is complete. Supporting clients will stop the streaming
+    // animation and display the final content.
+    if (useLive && !liveFinalized && currentEventId && lastSentText) {
+      liveFinalized = true;
+      try {
+        await editMessageMatrix(roomId, currentEventId, lastSentText, {
+          client,
+          cfg,
+          threadId,
+          accountId,
+          msgtype: preview.msgtype,
+          includeMentions: preview.includeMentions,
+          live: false,
+        });
+        log?.(`draft-stream: finalized ${currentEventId} (MSC4357 stream ended)`);
+        return true;
+      } catch (err) {
+        log?.(`draft-stream: finalize edit failed: ${String(err)}`);
+        // If the finalize edit fails, the live marker remains on the last
+        // successful edit. Flag the stream so callers can fall back to
+        // normal final delivery or redaction instead of leaving the message
+        // stuck in a "still streaming" state for MSC4357 clients.
+        finalizeInPlaceBlocked = true;
+        return false;
+      }
+    }
+    return true;
+  };
+
+  const stop = async (): Promise<string | undefined> => {
+    // Flush before marking stopped so the loop can drain pending text.
+    await loop.flush();
+    stopped = true;
+    return currentEventId;
+  };
+
+  const reset = (): void => {
+    // Clear reply context unless preserveReplyId is set (replyToMode "all"),
+    // in which case subsequent blocks should keep replying to the original.
+    replyToId = params.preserveReplyId ? params.replyToId : undefined;
+    currentEventId = undefined;
+    lastSentText = "";
+    stopped = false;
+    sendFailed = false;
+    finalizeInPlaceBlocked = false;
+    liveFinalized = false;
+    loop.resetPending();
+    loop.resetThrottleWindow();
+  };
+
+  return {
+    update: (text: string) => {
+      if (stopped) {
+        return;
+      }
+      loop.update(text);
+    },
+    flush: loop.flush,
+    stop,
+    finalizeLive,
+    reset,
+    eventId: () => currentEventId,
+    matchesPreparedText: (text: string) =>
+      prepareMatrixSingleText(text, {
+        cfg,
+        accountId,
+      }).trimmedText === lastSentText,
+    mustDeliverFinalNormally: () => sendFailed || finalizeInPlaceBlocked,
+  };
+}

package/src/matrix/encryption-guidance.ts

@@ -0,0 +1,27 @@
+import { normalizeOptionalAccountId } from "openclaw/plugin-sdk/account-id";
+import { resolveMatrixDefaultOrOnlyAccountId } from "../account-selection.js";
+import type { CoreConfig } from "../types.js";
+import { resolveMatrixConfigFieldPath } from "./config-paths.js";
+
+export function resolveMatrixEncryptionConfigPath(
+  cfg: CoreConfig,
+  accountId?: string | null,
+): string {
+  const effectiveAccountId =
+    normalizeOptionalAccountId(accountId) ?? resolveMatrixDefaultOrOnlyAccountId(cfg);
+  return resolveMatrixConfigFieldPath(cfg, effectiveAccountId, "encryption");
+}
+
+export function formatMatrixEncryptionUnavailableError(
+  cfg: CoreConfig,
+  accountId?: string | null,
+): string {
+  return `Matrix encryption is not available (enable ${resolveMatrixEncryptionConfigPath(cfg, accountId)}=true)`;
+}
+
+export function formatMatrixEncryptedEventDisabledWarning(
+  cfg: CoreConfig,
+  accountId?: string | null,
+): string {
+  return `matrix: encrypted event received without encryption enabled; set ${resolveMatrixEncryptionConfigPath(cfg, accountId)}=true and verify the device to decrypt`;
+}

package/src/matrix/errors.ts

@@ -0,0 +1,21 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+
+export function formatMatrixErrorMessage(err: unknown): string {
+  return formatErrorMessage(err);
+}
+
+export function formatMatrixErrorReason(err: unknown): string {
+  return normalizeLowercaseStringOrEmpty(formatMatrixErrorMessage(err));
+}
+
+export function isMatrixNotFoundError(err: unknown): boolean {
+  const errObj = err as { statusCode?: number; body?: { errcode?: string } };
+  if (errObj?.statusCode === 404 || errObj?.body?.errcode === "M_NOT_FOUND") {
+    return true;
+  }
+  const message = formatMatrixErrorReason(err);
+  return (
+    message.includes("m_not_found") || message.includes("[404]") || message.includes("not found")
+  );
+}