@archipelagolab/lobi 1.0.0

package/src/matrix/monitor/handler.media-failure.test.ts

@@ -0,0 +1,267 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { installMatrixMonitorTestRuntime } from "../../test-runtime.js";
+import { MatrixMediaSizeLimitError } from "../media-errors.js";
+import {
+  createMatrixHandlerTestHarness,
+  createMatrixRoomMessageEvent,
+} from "./handler.test-helpers.js";
+
+const { downloadMatrixMediaMock } = vi.hoisted(() => ({
+  downloadMatrixMediaMock: vi.fn(),
+}));
+
+vi.mock("./media.js", async () => {
+  const actual = await vi.importActual<typeof import("./media.js")>("./media.js");
+  return {
+    ...actual,
+    downloadMatrixMedia: (...args: unknown[]) => downloadMatrixMediaMock(...args),
+  };
+});
+
+function createMediaFailureHarness() {
+  const logger = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  };
+  const runtime = {
+    error: vi.fn(),
+  };
+  const harness = createMatrixHandlerTestHarness({
+    logger: logger as never,
+    runtime: runtime as never,
+    shouldHandleTextCommands: () => true,
+    resolveMarkdownTableMode: () => "code",
+    resolveAgentRoute: () => ({
+      agentId: "main",
+      accountId: "ops",
+      sessionKey: "agent:main:matrix:channel:!room:example.org",
+      mainSessionKey: "agent:main:main",
+      channel: "matrix",
+      matchedBy: "binding.account",
+    }),
+    resolveStorePath: () => "/tmp/openclaw-test-session.json",
+    readSessionUpdatedAt: () => 123,
+    getRoomInfo: async () => ({
+      name: "Media Room",
+      canonicalAlias: "#media:example.org",
+      altAliases: [],
+    }),
+    getMemberDisplayName: async () => "Gum",
+    startupMs: Date.now() - 120_000,
+    startupGraceMs: 60_000,
+    textLimit: 4000,
+    mediaMaxBytes: 5 * 1024 * 1024,
+    replyToMode: "first",
+  });
+
+  return {
+    ...harness,
+    logger,
+    runtime,
+  };
+}
+
+function createImageEvent(content: Record<string, unknown>) {
+  return createMatrixRoomMessageEvent({
+    eventId: "$event1",
+    sender: "@gum:matrix.example.org",
+    content: {
+      ...content,
+      "m.mentions": { user_ids: ["@bot:matrix.example.org"] },
+    } as never,
+  });
+}
+
+describe("createMatrixRoomMessageHandler media failures", () => {
+  beforeEach(() => {
+    downloadMatrixMediaMock.mockReset();
+    installMatrixMonitorTestRuntime();
+  });
+
+  it("forwards the Matrix event body as originalFilename for media downloads", async () => {
+    downloadMatrixMediaMock.mockResolvedValue({
+      path: "/tmp/inbound/Screenshot-2026-03-27---uuid.png",
+      contentType: "image/png",
+      placeholder: "[matrix media]",
+    });
+    const { handler } = createMediaFailureHarness();
+
+    await handler(
+      "!room:example.org",
+      createImageEvent({
+        msgtype: "m.image",
+        body: " Screenshot 2026-03-27.png ",
+        url: "mxc://example/image",
+      }),
+    );
+
+    expect(downloadMatrixMediaMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mxcUrl: "mxc://example/image",
+        maxBytes: 5 * 1024 * 1024,
+        originalFilename: "Screenshot 2026-03-27.png",
+      }),
+    );
+  });
+
+  it("prefers content.filename over body text when deriving originalFilename", async () => {
+    downloadMatrixMediaMock.mockResolvedValue({
+      path: "/tmp/inbound/Screenshot-2026-03-27---uuid.png",
+      contentType: "image/png",
+      placeholder: "[matrix media]",
+    });
+    const { handler } = createMediaFailureHarness();
+
+    await handler(
+      "!room:example.org",
+      createImageEvent({
+        msgtype: "m.image",
+        body: "can you review this screenshot?",
+        filename: "Screenshot 2026-03-27.png",
+        url: "mxc://example/image",
+      }),
+    );
+
+    expect(downloadMatrixMediaMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        originalFilename: "Screenshot 2026-03-27.png",
+      }),
+    );
+  });
+
+  it("replaces bare image filenames with an unavailable marker when unencrypted download fails", async () => {
+    downloadMatrixMediaMock.mockRejectedValue(new Error("download failed"));
+    const { handler, recordInboundSession, logger, runtime } = createMediaFailureHarness();
+
+    await handler(
+      "!room:example.org",
+      createImageEvent({
+        msgtype: "m.image",
+        body: "image.png",
+        url: "mxc://example/image",
+      }),
+    );
+
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          RawBody: "[matrix image attachment unavailable]",
+          CommandBody: "[matrix image attachment unavailable]",
+          MediaPath: undefined,
+        }),
+      }),
+    );
+    expect(logger.warn).toHaveBeenCalledWith(
+      "matrix media download failed",
+      expect.objectContaining({
+        eventId: "$event1",
+        msgtype: "m.image",
+        encrypted: false,
+      }),
+    );
+    expect(runtime.error).not.toHaveBeenCalled();
+  });
+
+  it("replaces bare image filenames with an unavailable marker when encrypted download fails", async () => {
+    downloadMatrixMediaMock.mockRejectedValue(new Error("decrypt failed"));
+    const { handler, recordInboundSession } = createMediaFailureHarness();
+
+    await handler(
+      "!room:example.org",
+      createImageEvent({
+        msgtype: "m.image",
+        body: "photo.jpg",
+        file: {
+          url: "mxc://example/encrypted",
+          key: { kty: "oct", key_ops: ["encrypt"], alg: "A256CTR", k: "secret", ext: true },
+          iv: "iv",
+          hashes: { sha256: "hash" },
+          v: "v2",
+        },
+      }),
+    );
+
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          RawBody: "[matrix image attachment unavailable]",
+          CommandBody: "[matrix image attachment unavailable]",
+          MediaPath: undefined,
+        }),
+      }),
+    );
+  });
+
+  it("preserves a real caption while marking the attachment unavailable", async () => {
+    downloadMatrixMediaMock.mockRejectedValue(new Error("download failed"));
+    const { handler, recordInboundSession } = createMediaFailureHarness();
+
+    await handler(
+      "!room:example.org",
+      createImageEvent({
+        msgtype: "m.image",
+        body: "can you see this image?",
+        filename: "image.png",
+        url: "mxc://example/image",
+      }),
+    );
+
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          RawBody: "can you see this image?\n\n[matrix image attachment unavailable]",
+          CommandBody: "can you see this image?\n\n[matrix image attachment unavailable]",
+        }),
+      }),
+    );
+  });
+
+  it("shows a too-large marker when the download is rejected due to size limit", async () => {
+    downloadMatrixMediaMock.mockRejectedValue(new MatrixMediaSizeLimitError());
+    const { handler, recordInboundSession } = createMediaFailureHarness();
+
+    await handler(
+      "!room:example.org",
+      createImageEvent({
+        msgtype: "m.image",
+        body: "big-photo.jpg",
+        url: "mxc://example/big-image",
+      }),
+    );
+
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          RawBody: "[matrix image attachment too large]",
+          CommandBody: "[matrix image attachment too large]",
+          MediaPath: undefined,
+        }),
+      }),
+    );
+  });
+
+  it("preserves a real caption while marking the attachment too large on size limit error", async () => {
+    downloadMatrixMediaMock.mockRejectedValue(new MatrixMediaSizeLimitError());
+    const { handler, recordInboundSession } = createMediaFailureHarness();
+
+    await handler(
+      "!room:example.org",
+      createImageEvent({
+        msgtype: "m.image",
+        body: "check this out",
+        filename: "large-photo.jpg",
+        url: "mxc://example/big-image",
+      }),
+    );
+
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          RawBody: "check this out\n\n[matrix image attachment too large]",
+          CommandBody: "check this out\n\n[matrix image attachment too large]",
+        }),
+      }),
+    );
+  });
+});

package/src/matrix/monitor/handler.test-helpers.ts

@@ -0,0 +1,308 @@
+import { vi } from "vitest";
+import type { RuntimeEnv, RuntimeLogger } from "../../runtime-api.js";
+import type { MatrixRoomConfig, MatrixStreamingMode, ReplyToMode } from "../../types.js";
+import type { MatrixClient } from "../sdk.js";
+import { createMatrixRoomMessageHandler, type MatrixMonitorHandlerParams } from "./handler.js";
+import { EventType, type MatrixRawEvent, type RoomMessageEventContent } from "./types.js";
+
+const DEFAULT_ROUTE = {
+  agentId: "ops",
+  channel: "matrix",
+  accountId: "ops",
+  sessionKey: "agent:ops:main",
+  mainSessionKey: "agent:ops:main",
+  matchedBy: "binding.account" as const,
+};
+
+type MatrixHandlerTestHarnessOptions = {
+  accountId?: string;
+  cfg?: unknown;
+  client?: Partial<MatrixClient>;
+  runtime?: RuntimeEnv;
+  logger?: RuntimeLogger;
+  logVerboseMessage?: (message: string) => void;
+  allowFrom?: string[];
+  groupAllowFrom?: string[];
+  roomsConfig?: Record<string, MatrixRoomConfig>;
+  accountAllowBots?: boolean | "mentions";
+  configuredBotUserIds?: Set<string>;
+  mentionRegexes?: RegExp[];
+  groupPolicy?: "open" | "allowlist" | "disabled";
+  replyToMode?: ReplyToMode;
+  threadReplies?: "off" | "inbound" | "always";
+  dmThreadReplies?: "off" | "inbound" | "always";
+  dmSessionScope?: "per-user" | "per-room";
+  streaming?: MatrixStreamingMode;
+  blockStreamingEnabled?: boolean;
+  dmEnabled?: boolean;
+  dmPolicy?: "pairing" | "allowlist" | "open" | "disabled";
+  textLimit?: number;
+  mediaMaxBytes?: number;
+  startupMs?: number;
+  startupGraceMs?: number;
+  dropPreStartupMessages?: boolean;
+  needsRoomAliasesForConfig?: boolean;
+  isDirectMessage?: boolean;
+  historyLimit?: number;
+  readAllowFromStore?: MatrixMonitorHandlerParams["core"]["channel"]["pairing"]["readAllowFromStore"];
+  upsertPairingRequest?: MatrixMonitorHandlerParams["core"]["channel"]["pairing"]["upsertPairingRequest"];
+  buildPairingReply?: () => string;
+  shouldHandleTextCommands?: () => boolean;
+  hasControlCommand?: () => boolean;
+  resolveMarkdownTableMode?: () => string;
+  resolveAgentRoute?: () => typeof DEFAULT_ROUTE;
+  resolveStorePath?: () => string;
+  readSessionUpdatedAt?: () => number | undefined;
+  recordInboundSession?: (...args: unknown[]) => Promise<void>;
+  resolveEnvelopeFormatOptions?: () => Record<string, never>;
+  formatAgentEnvelope?: ({ body }: { body: string }) => string;
+  finalizeInboundContext?: (ctx: unknown) => unknown;
+  createReplyDispatcherWithTyping?: (params?: {
+    onError?: (err: unknown, info: { kind: "tool" | "block" | "final" }) => void;
+  }) => {
+    dispatcher: Record<string, unknown>;
+    replyOptions: Record<string, unknown>;
+    markDispatchIdle: () => void;
+    markRunComplete: () => void;
+  };
+  resolveHumanDelayConfig?: () => undefined;
+  dispatchReplyFromConfig?: () => Promise<{
+    queuedFinal: boolean;
+    counts: { final: number; block: number; tool: number };
+  }>;
+  withReplyDispatcher?: <T>(params: {
+    dispatcher: {
+      markComplete?: () => void;
+      waitForIdle?: () => Promise<void>;
+    };
+    run: () => Promise<T>;
+    onSettled?: () => void | Promise<void>;
+  }) => Promise<T>;
+  inboundDeduper?: MatrixMonitorHandlerParams["inboundDeduper"];
+  shouldAckReaction?: () => boolean;
+  enqueueSystemEvent?: (...args: unknown[]) => void;
+  getRoomInfo?: MatrixMonitorHandlerParams["getRoomInfo"];
+  getMemberDisplayName?: MatrixMonitorHandlerParams["getMemberDisplayName"];
+};
+
+type MatrixHandlerTestHarness = {
+  dispatchReplyFromConfig: () => Promise<{
+    queuedFinal: boolean;
+    counts: { final: number; block: number; tool: number };
+  }>;
+  enqueueSystemEvent: (...args: unknown[]) => void;
+  finalizeInboundContext: (ctx: unknown) => unknown;
+  handler: ReturnType<typeof createMatrixRoomMessageHandler>;
+  readAllowFromStore: MatrixMonitorHandlerParams["core"]["channel"]["pairing"]["readAllowFromStore"];
+  recordInboundSession: (...args: unknown[]) => Promise<void>;
+  resolveAgentRoute: () => typeof DEFAULT_ROUTE;
+  upsertPairingRequest: MatrixMonitorHandlerParams["core"]["channel"]["pairing"]["upsertPairingRequest"];
+};
+
+export function createMatrixHandlerTestHarness(
+  options: MatrixHandlerTestHarnessOptions = {},
+): MatrixHandlerTestHarness {
+  const readAllowFromStore = options.readAllowFromStore ?? vi.fn(async () => [] as string[]);
+  const upsertPairingRequest =
+    options.upsertPairingRequest ?? vi.fn(async () => ({ code: "ABCDEFGH", created: false }));
+  const resolveAgentRoute = options.resolveAgentRoute ?? vi.fn(() => DEFAULT_ROUTE);
+  const recordInboundSession = options.recordInboundSession ?? vi.fn(async () => {});
+  const finalizeInboundContext = options.finalizeInboundContext ?? vi.fn((ctx) => ctx);
+  const dispatchReplyFromConfig =
+    options.dispatchReplyFromConfig ??
+    (async () => ({
+      queuedFinal: false,
+      counts: { final: 0, block: 0, tool: 0 },
+    }));
+  const enqueueSystemEvent = options.enqueueSystemEvent ?? vi.fn();
+
+  const handler = createMatrixRoomMessageHandler({
+    client: {
+      getUserId: async () => "@bot:example.org",
+      getEvent: async () => ({ sender: "@bot:example.org" }),
+      ...options.client,
+    } as never,
+    core: {
+      channel: {
+        pairing: {
+          readAllowFromStore,
+          upsertPairingRequest,
+          buildPairingReply: options.buildPairingReply ?? (() => "pairing"),
+        },
+        commands: {
+          shouldHandleTextCommands: options.shouldHandleTextCommands ?? (() => false),
+        },
+        text: {
+          hasControlCommand: options.hasControlCommand ?? (() => false),
+          resolveMarkdownTableMode: options.resolveMarkdownTableMode ?? (() => "preserve"),
+        },
+        routing: {
+          resolveAgentRoute,
+        },
+        mentions: {
+          buildMentionRegexes: () => options.mentionRegexes ?? [],
+        },
+        session: {
+          resolveStorePath: options.resolveStorePath ?? (() => "/tmp/session-store"),
+          readSessionUpdatedAt: options.readSessionUpdatedAt ?? (() => undefined),
+          recordInboundSession,
+        },
+        reply: {
+          resolveEnvelopeFormatOptions: options.resolveEnvelopeFormatOptions ?? (() => ({})),
+          formatAgentEnvelope:
+            options.formatAgentEnvelope ?? (({ body }: { body: string }) => body),
+          finalizeInboundContext,
+          createReplyDispatcherWithTyping:
+            options.createReplyDispatcherWithTyping ??
+            (() => ({
+              dispatcher: {},
+              replyOptions: {},
+              markDispatchIdle: () => {},
+              markRunComplete: () => {},
+            })),
+          resolveHumanDelayConfig: options.resolveHumanDelayConfig ?? (() => undefined),
+          dispatchReplyFromConfig,
+          withReplyDispatcher:
+            options.withReplyDispatcher ??
+            (async <T>(params: {
+              dispatcher: {
+                markComplete?: () => void;
+                waitForIdle?: () => Promise<void>;
+              };
+              run: () => Promise<T>;
+              onSettled?: () => void | Promise<void>;
+            }) => {
+              const { dispatcher, run, onSettled } = params;
+              try {
+                return await run();
+              } finally {
+                dispatcher.markComplete?.();
+                try {
+                  await dispatcher.waitForIdle?.();
+                } finally {
+                  await onSettled?.();
+                }
+              }
+            }),
+        },
+        reactions: {
+          shouldAckReaction: options.shouldAckReaction ?? (() => false),
+        },
+      },
+      system: {
+        enqueueSystemEvent,
+      },
+    } as never,
+    cfg: (options.cfg ?? {}) as never,
+    accountId: options.accountId ?? "ops",
+    runtime:
+      options.runtime ??
+      ({
+        error: () => {},
+      } as RuntimeEnv),
+    logger:
+      options.logger ??
+      ({
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+      } as RuntimeLogger),
+    logVerboseMessage: options.logVerboseMessage ?? (() => {}),
+    allowFrom: options.allowFrom ?? [],
+    groupAllowFrom: options.groupAllowFrom ?? [],
+    roomsConfig: options.roomsConfig,
+    accountAllowBots: options.accountAllowBots,
+    configuredBotUserIds: options.configuredBotUserIds,
+    groupPolicy: options.groupPolicy ?? "open",
+    replyToMode: options.replyToMode ?? "off",
+    threadReplies: options.threadReplies ?? "inbound",
+    dmThreadReplies: options.dmThreadReplies,
+    dmSessionScope: options.dmSessionScope,
+    streaming: options.streaming ?? "off",
+    blockStreamingEnabled: options.blockStreamingEnabled ?? false,
+    dmEnabled: options.dmEnabled ?? true,
+    dmPolicy: options.dmPolicy ?? "open",
+    textLimit: options.textLimit ?? 8_000,
+    mediaMaxBytes: options.mediaMaxBytes ?? 10_000_000,
+    startupMs: options.startupMs ?? 0,
+    startupGraceMs: options.startupGraceMs ?? 0,
+    dropPreStartupMessages: options.dropPreStartupMessages ?? true,
+    inboundDeduper: options.inboundDeduper,
+    directTracker: {
+      isDirectMessage: async () => options.isDirectMessage ?? true,
+    },
+    getRoomInfo: options.getRoomInfo ?? (async () => ({ altAliases: [] })),
+    getMemberDisplayName: options.getMemberDisplayName ?? (async () => "sender"),
+    needsRoomAliasesForConfig: options.needsRoomAliasesForConfig ?? false,
+    historyLimit: options.historyLimit ?? 0,
+  });
+
+  return {
+    dispatchReplyFromConfig,
+    enqueueSystemEvent,
+    finalizeInboundContext,
+    handler,
+    readAllowFromStore,
+    recordInboundSession,
+    resolveAgentRoute,
+    upsertPairingRequest,
+  };
+}
+
+export function createMatrixTextMessageEvent(params: {
+  eventId: string;
+  sender?: string;
+  body: string;
+  originServerTs?: number;
+  relatesTo?: RoomMessageEventContent["m.relates_to"];
+  mentions?: RoomMessageEventContent["m.mentions"];
+}): MatrixRawEvent {
+  return createMatrixRoomMessageEvent({
+    eventId: params.eventId,
+    sender: params.sender,
+    originServerTs: params.originServerTs,
+    content: {
+      msgtype: "m.text",
+      body: params.body,
+      ...(params.relatesTo ? { "m.relates_to": params.relatesTo } : {}),
+      ...(params.mentions ? { "m.mentions": params.mentions } : {}),
+    },
+  });
+}
+
+export function createMatrixRoomMessageEvent(params: {
+  eventId: string;
+  sender?: string;
+  originServerTs?: number;
+  content: RoomMessageEventContent;
+}): MatrixRawEvent {
+  return {
+    type: EventType.RoomMessage,
+    sender: params.sender ?? "@user:example.org",
+    event_id: params.eventId,
+    origin_server_ts: params.originServerTs ?? Date.now(),
+    content: params.content,
+  } as MatrixRawEvent;
+}
+
+export function createMatrixReactionEvent(params: {
+  eventId: string;
+  targetEventId: string;
+  key: string;
+  sender?: string;
+  originServerTs?: number;
+}): MatrixRawEvent {
+  return {
+    type: EventType.Reaction,
+    sender: params.sender ?? "@user:example.org",
+    event_id: params.eventId,
+    origin_server_ts: params.originServerTs ?? Date.now(),
+    content: {
+      "m.relates_to": {
+        rel_type: "m.annotation",
+        event_id: params.targetEventId,
+        key: params.key,
+      },
+    },
+  } as MatrixRawEvent;
+}