@archipelagolab/lobi 1.0.0

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

@@ -0,0 +1,174 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createMockMatrixClient,
+  expectExplicitMatrixClientConfig,
+  expectOneOffSharedMatrixClient,
+  matrixClientResolverMocks,
+  primeMatrixClientResolverMocks,
+} from "../client-resolver.test-helpers.js";
+
+const {
+  getMatrixRuntimeMock,
+  getActiveMatrixClientMock,
+  acquireSharedMatrixClientMock,
+  releaseSharedClientInstanceMock,
+  isBunRuntimeMock,
+  resolveMatrixAuthContextMock,
+} = matrixClientResolverMocks;
+
+vi.mock("../active-client.js", () => ({
+  getActiveMatrixClient: (...args: unknown[]) => getActiveMatrixClientMock(...args),
+}));
+
+vi.mock("../client.js", () => ({
+  acquireSharedMatrixClient: (...args: unknown[]) => acquireSharedMatrixClientMock(...args),
+  isBunRuntime: () => isBunRuntimeMock(),
+  resolveMatrixAuthContext: resolveMatrixAuthContextMock,
+}));
+
+vi.mock("../client/shared.js", () => ({
+  releaseSharedClientInstance: (...args: unknown[]) => releaseSharedClientInstanceMock(...args),
+}));
+
+vi.mock("../../runtime.js", () => ({
+  getMatrixRuntime: () => getMatrixRuntimeMock(),
+}));
+
+let withResolvedMatrixControlClient: typeof import("./client.js").withResolvedMatrixControlClient;
+let withResolvedMatrixSendClient: typeof import("./client.js").withResolvedMatrixSendClient;
+
+describe("matrix send client helpers", () => {
+  beforeAll(async () => {
+    ({ withResolvedMatrixControlClient, withResolvedMatrixSendClient } =
+      await import("./client.js"));
+  });
+
+  beforeEach(() => {
+    primeMatrixClientResolverMocks({
+      resolved: {},
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("stops one-off shared clients when no active monitor client is registered", async () => {
+    vi.stubEnv("OPENCLAW_GATEWAY_PORT", "18799");
+
+    const result = await withResolvedMatrixSendClient({ accountId: "default" }, async () => "ok");
+
+    await expectOneOffSharedMatrixClient({
+      prepareForOneOffCalls: 0,
+      startCalls: 1,
+      releaseMode: "persist",
+    });
+    expect(result).toBe("ok");
+  });
+
+  it("reuses active monitor client when available", async () => {
+    const activeClient = createMockMatrixClient();
+    getActiveMatrixClientMock.mockReturnValue(activeClient);
+
+    const result = await withResolvedMatrixSendClient({ accountId: "default" }, async (client) => {
+      expect(client).toBe(activeClient);
+      return "ok";
+    });
+
+    expect(result).toBe("ok");
+    expect(acquireSharedMatrixClientMock).not.toHaveBeenCalled();
+    expect(activeClient.start).toHaveBeenCalledTimes(1);
+    expect(activeClient.stop).not.toHaveBeenCalled();
+    expect(activeClient.stopAndPersist).not.toHaveBeenCalled();
+  });
+
+  it("uses the effective account id when auth resolution is implicit", async () => {
+    resolveMatrixAuthContextMock.mockReturnValue({
+      cfg: {},
+      env: process.env,
+      accountId: "ops",
+      resolved: {},
+    });
+    await withResolvedMatrixSendClient({}, async () => {});
+
+    await expectOneOffSharedMatrixClient({
+      accountId: "ops",
+      prepareForOneOffCalls: 0,
+      startCalls: 1,
+      releaseMode: "persist",
+    });
+  });
+
+  it("uses explicit cfg instead of loading runtime config", async () => {
+    const explicitCfg = {
+      channels: {
+        matrix: {
+          defaultAccount: "ops",
+        },
+      },
+    };
+
+    await withResolvedMatrixSendClient({ cfg: explicitCfg, accountId: "ops" }, async () => {});
+
+    expectExplicitMatrixClientConfig({
+      cfg: explicitCfg,
+      accountId: "ops",
+    });
+  });
+
+  it("stops shared matrix clients when wrapped sends fail", async () => {
+    const sharedClient = createMockMatrixClient();
+    acquireSharedMatrixClientMock.mockResolvedValue(sharedClient);
+
+    await expect(
+      withResolvedMatrixSendClient({ accountId: "default" }, async () => {
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+
+    expect(releaseSharedClientInstanceMock).toHaveBeenCalledWith(sharedClient, "persist");
+  });
+
+  it("starts one-off clients before outbound sends so encrypted rooms can reuse live crypto state", async () => {
+    const sharedClient = createMockMatrixClient();
+    acquireSharedMatrixClientMock.mockResolvedValue(sharedClient);
+
+    await withResolvedMatrixSendClient({ accountId: "default" }, async () => "ok");
+
+    expect(sharedClient.start).toHaveBeenCalledTimes(1);
+    expect(sharedClient.prepareForOneOff).not.toHaveBeenCalled();
+  });
+
+  it("keeps one-off control clients lightweight when no active monitor client is registered", async () => {
+    const result = await withResolvedMatrixControlClient(
+      { accountId: "default" },
+      async () => "ok",
+    );
+
+    await expectOneOffSharedMatrixClient({
+      prepareForOneOffCalls: 0,
+      startCalls: 0,
+      releaseMode: "stop",
+    });
+    expect(result).toBe("ok");
+  });
+
+  it("reuses active monitor clients for control operations without restarting them", async () => {
+    const activeClient = createMockMatrixClient();
+    getActiveMatrixClientMock.mockReturnValue(activeClient);
+
+    const result = await withResolvedMatrixControlClient(
+      { accountId: "default" },
+      async (client) => {
+        expect(client).toBe(activeClient);
+        return "ok";
+      },
+    );
+
+    expect(result).toBe("ok");
+    expect(acquireSharedMatrixClientMock).not.toHaveBeenCalled();
+    expect(activeClient.start).not.toHaveBeenCalled();
+    expect(activeClient.stop).not.toHaveBeenCalled();
+    expect(activeClient.stopAndPersist).not.toHaveBeenCalled();
+  });
+});

package/src/matrix/send/client.ts

@@ -0,0 +1,90 @@
+import { getMatrixRuntime } from "../../runtime.js";
+import type { CoreConfig } from "../../types.js";
+import { resolveMatrixAccountConfig } from "../account-config.js";
+import type { MatrixClient } from "../sdk.js";
+
+const getCore = () => getMatrixRuntime();
+
+type MatrixSendClientRuntime = Pick<
+  typeof import("../client-bootstrap.js"),
+  "withResolvedRuntimeMatrixClient"
+>;
+
+let matrixSendClientRuntimePromise: Promise<MatrixSendClientRuntime> | null = null;
+
+async function loadMatrixSendClientRuntime(): Promise<MatrixSendClientRuntime> {
+  matrixSendClientRuntimePromise ??= import("../client-bootstrap.js");
+  return await matrixSendClientRuntimePromise;
+}
+
+export function resolveMediaMaxBytes(
+  accountId?: string | null,
+  cfg?: CoreConfig,
+): number | undefined {
+  const resolvedCfg = cfg ?? (getCore().config.loadConfig() as CoreConfig);
+  const matrixCfg = resolveMatrixAccountConfig({ cfg: resolvedCfg, accountId });
+  const mediaMaxMb = typeof matrixCfg.mediaMaxMb === "number" ? matrixCfg.mediaMaxMb : undefined;
+  if (typeof mediaMaxMb === "number") {
+    return mediaMaxMb * 1024 * 1024;
+  }
+  return undefined;
+}
+
+export async function withResolvedMatrixSendClient<T>(
+  opts: {
+    client?: MatrixClient;
+    cfg?: CoreConfig;
+    timeoutMs?: number;
+    accountId?: string | null;
+  },
+  run: (client: MatrixClient) => Promise<T>,
+): Promise<T> {
+  return await withResolvedMatrixClient(
+    {
+      ...opts,
+      // One-off outbound sends still need a started client so room encryption
+      // state and live crypto sessions are available before sendMessage/sendEvent.
+      readiness: "started",
+    },
+    run,
+    // Started one-off send clients should flush sync/crypto state before CLI
+    // shutdown paths can tear down the process.
+    "persist",
+  );
+}
+
+export async function withResolvedMatrixControlClient<T>(
+  opts: {
+    client?: MatrixClient;
+    cfg?: CoreConfig;
+    timeoutMs?: number;
+    accountId?: string | null;
+  },
+  run: (client: MatrixClient) => Promise<T>,
+): Promise<T> {
+  return await withResolvedMatrixClient(
+    {
+      ...opts,
+      readiness: "none",
+    },
+    run,
+  );
+}
+
+async function withResolvedMatrixClient<T>(
+  opts: {
+    client?: MatrixClient;
+    cfg?: CoreConfig;
+    timeoutMs?: number;
+    accountId?: string | null;
+    readiness: "started" | "none";
+  },
+  run: (client: MatrixClient) => Promise<T>,
+  shutdownBehavior?: "persist",
+): Promise<T> {
+  if (opts.client) {
+    return await run(opts.client);
+  }
+  const { withResolvedRuntimeMatrixClient } = await loadMatrixSendClientRuntime();
+  return await withResolvedRuntimeMatrixClient(opts, run, shutdownBehavior);
+}

package/src/matrix/send/formatting.ts

@@ -0,0 +1,189 @@
+import { getMatrixRuntime } from "../../runtime.js";
+import {
+  markdownToMatrixHtml,
+  resolveMatrixMentionsInMarkdown,
+  renderMarkdownToMatrixHtmlWithMentions,
+  type MatrixMentions,
+} from "../format.js";
+import type { MatrixClient } from "../sdk.js";
+import {
+  MsgType,
+  RelationType,
+  type MatrixFormattedContent,
+  type MatrixMediaMsgType,
+  type MatrixRelation,
+  type MatrixReplyRelation,
+  type MatrixTextContent,
+  type MatrixTextMsgType,
+  type MatrixThreadRelation,
+} from "./types.js";
+
+const getCore = () => getMatrixRuntime();
+
+async function renderMatrixFormattedContent(params: {
+  client: MatrixClient;
+  markdown?: string | null;
+  includeMentions?: boolean;
+}): Promise<{ html?: string; mentions?: MatrixMentions }> {
+  const markdown = params.markdown ?? "";
+  if (params.includeMentions === false) {
+    const html = markdownToMatrixHtml(markdown).trimEnd();
+    return { html: html || undefined };
+  }
+  const { html, mentions } = await renderMarkdownToMatrixHtmlWithMentions({
+    markdown,
+    client: params.client,
+  });
+  return { html, mentions };
+}
+
+export function buildTextContent(
+  body: string,
+  relation?: MatrixRelation,
+  opts: {
+    msgtype?: MatrixTextMsgType;
+  } = {},
+): MatrixTextContent {
+  const msgtype = opts.msgtype ?? MsgType.Text;
+  return relation
+    ? {
+        msgtype,
+        body,
+        "m.relates_to": relation,
+      }
+    : {
+        msgtype,
+        body,
+      };
+}
+
+export async function enrichMatrixFormattedContent(params: {
+  client: MatrixClient;
+  content: MatrixFormattedContent;
+  markdown?: string | null;
+  includeMentions?: boolean;
+}): Promise<void> {
+  const { html, mentions } = await renderMatrixFormattedContent({
+    client: params.client,
+    markdown: params.markdown,
+    includeMentions: params.includeMentions,
+  });
+  if (mentions) {
+    params.content["m.mentions"] = mentions;
+  } else {
+    delete params.content["m.mentions"];
+  }
+  if (!html) {
+    delete params.content.format;
+    delete params.content.formatted_body;
+    return;
+  }
+  params.content.format = "org.matrix.custom.html";
+  params.content.formatted_body = html;
+}
+
+export async function resolveMatrixMentionsForBody(params: {
+  client: MatrixClient;
+  body: string;
+}): Promise<MatrixMentions> {
+  return await resolveMatrixMentionsInMarkdown({
+    markdown: params.body ?? "",
+    client: params.client,
+  });
+}
+
+function normalizeMentionUserIds(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+}
+
+export function extractMatrixMentions(
+  content: Record<string, unknown> | undefined,
+): MatrixMentions {
+  const rawMentions = content?.["m.mentions"];
+  if (!rawMentions || typeof rawMentions !== "object") {
+    return {};
+  }
+  const mentions = rawMentions as { room?: unknown; user_ids?: unknown };
+  const normalized: MatrixMentions = {};
+  const userIds = normalizeMentionUserIds(mentions.user_ids);
+  if (userIds.length > 0) {
+    normalized.user_ids = userIds;
+  }
+  if (mentions.room === true) {
+    normalized.room = true;
+  }
+  return normalized;
+}
+
+export function diffMatrixMentions(
+  current: MatrixMentions,
+  previous: MatrixMentions,
+): MatrixMentions {
+  const previousUserIds = new Set(previous.user_ids ?? []);
+  const newUserIds = (current.user_ids ?? []).filter((userId) => !previousUserIds.has(userId));
+  const delta: MatrixMentions = {};
+  if (newUserIds.length > 0) {
+    delta.user_ids = newUserIds;
+  }
+  if (current.room && !previous.room) {
+    delta.room = true;
+  }
+  return delta;
+}
+
+export function buildReplyRelation(replyToId?: string): MatrixReplyRelation | undefined {
+  const trimmed = replyToId?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  return { "m.in_reply_to": { event_id: trimmed } };
+}
+
+export function buildThreadRelation(threadId: string, replyToId?: string): MatrixThreadRelation {
+  const trimmed = threadId.trim();
+  return {
+    rel_type: RelationType.Thread,
+    event_id: trimmed,
+    is_falling_back: true,
+    "m.in_reply_to": { event_id: replyToId?.trim() || trimmed },
+  };
+}
+
+export function resolveMatrixMsgType(contentType?: string, _fileName?: string): MatrixMediaMsgType {
+  const kind = getCore().media.mediaKindFromMime(contentType ?? "");
+  switch (kind) {
+    case "image":
+      return MsgType.Image;
+    case "audio":
+      return MsgType.Audio;
+    case "video":
+      return MsgType.Video;
+    default:
+      return MsgType.File;
+  }
+}
+
+export function resolveMatrixVoiceDecision(opts: {
+  wantsVoice: boolean;
+  contentType?: string;
+  fileName?: string;
+}): { useVoice: boolean } {
+  if (!opts.wantsVoice) {
+    return { useVoice: false };
+  }
+  if (isMatrixVoiceCompatibleAudio(opts)) {
+    return { useVoice: true };
+  }
+  return { useVoice: false };
+}
+
+function isMatrixVoiceCompatibleAudio(opts: { contentType?: string; fileName?: string }): boolean {
+  // Matrix currently shares the core voice compatibility policy.
+  // Keep this wrapper as the seam if Matrix policy diverges later.
+  return getCore().media.isVoiceCompatibleAudio({
+    contentType: opts.contentType,
+    fileName: opts.fileName,
+  });
+}

package/src/matrix/send/media.ts

@@ -0,0 +1,244 @@
+import { parseBuffer, type IFileInfo } from "music-metadata";
+import { getMatrixRuntime } from "../../runtime.js";
+import type {
+  DimensionalFileInfo,
+  EncryptedFile,
+  FileWithThumbnailInfo,
+  MatrixClient,
+  TimedFileInfo,
+  VideoFileInfo,
+} from "../sdk.js";
+import {
+  type MatrixMediaContent,
+  type MatrixMediaInfo,
+  type MatrixMediaMsgType,
+  type MatrixRelation,
+  type MediaKind,
+} from "./types.js";
+
+const getCore = () => getMatrixRuntime();
+
+export function buildMatrixMediaInfo(params: {
+  size: number;
+  mimetype?: string;
+  durationMs?: number;
+  imageInfo?: DimensionalFileInfo;
+}): MatrixMediaInfo | undefined {
+  const base: FileWithThumbnailInfo = {};
+  if (Number.isFinite(params.size)) {
+    base.size = params.size;
+  }
+  if (params.mimetype) {
+    base.mimetype = params.mimetype;
+  }
+  if (params.imageInfo) {
+    const dimensional: DimensionalFileInfo = {
+      ...base,
+      ...params.imageInfo,
+    };
+    if (typeof params.durationMs === "number") {
+      const videoInfo: VideoFileInfo = {
+        ...dimensional,
+        duration: params.durationMs,
+      };
+      return videoInfo;
+    }
+    return dimensional;
+  }
+  if (typeof params.durationMs === "number") {
+    const timedInfo: TimedFileInfo = {
+      ...base,
+      duration: params.durationMs,
+    };
+    return timedInfo;
+  }
+  if (Object.keys(base).length === 0) {
+    return undefined;
+  }
+  return base;
+}
+
+export function buildMediaContent(params: {
+  msgtype: MatrixMediaMsgType;
+  body: string;
+  url?: string;
+  filename?: string;
+  mimetype?: string;
+  size: number;
+  relation?: MatrixRelation;
+  isVoice?: boolean;
+  durationMs?: number;
+  imageInfo?: DimensionalFileInfo;
+  file?: EncryptedFile;
+}): MatrixMediaContent {
+  const info = buildMatrixMediaInfo({
+    size: params.size,
+    mimetype: params.mimetype,
+    durationMs: params.durationMs,
+    imageInfo: params.imageInfo,
+  });
+  const base: MatrixMediaContent = {
+    msgtype: params.msgtype,
+    body: params.body,
+    filename: params.filename,
+    info: info ?? undefined,
+  };
+  // Encrypted media should only include the "file" payload, not top-level "url".
+  if (!params.file && params.url) {
+    base.url = params.url;
+  }
+  // For encrypted files, add the file object
+  if (params.file) {
+    base.file = params.file;
+  }
+  if (params.isVoice) {
+    base["org.matrix.msc3245.voice"] = {};
+    if (typeof params.durationMs === "number") {
+      base["org.matrix.msc1767.audio"] = {
+        duration: params.durationMs,
+      };
+    }
+  }
+  if (params.relation) {
+    base["m.relates_to"] = params.relation;
+  }
+  return base;
+}
+
+const THUMBNAIL_MAX_SIDE = 800;
+const THUMBNAIL_QUALITY = 80;
+
+export async function prepareImageInfo(params: {
+  buffer: Buffer;
+  client: MatrixClient;
+  encrypted?: boolean;
+}): Promise<DimensionalFileInfo | undefined> {
+  const meta = await getCore()
+    .media.getImageMetadata(params.buffer)
+    .catch(() => null);
+  if (!meta) {
+    return undefined;
+  }
+  const imageInfo: DimensionalFileInfo = { w: meta.width, h: meta.height };
+  const maxDim = Math.max(meta.width, meta.height);
+  if (maxDim > THUMBNAIL_MAX_SIDE) {
+    try {
+      const thumbBuffer = await getCore().media.resizeToJpeg({
+        buffer: params.buffer,
+        maxSide: THUMBNAIL_MAX_SIDE,
+        quality: THUMBNAIL_QUALITY,
+        withoutEnlargement: true,
+      });
+      const thumbMeta = await getCore()
+        .media.getImageMetadata(thumbBuffer)
+        .catch(() => null);
+      const result = await uploadMediaWithEncryption(params.client, thumbBuffer, {
+        contentType: "image/jpeg",
+        filename: "thumbnail.jpg",
+        encrypted: params.encrypted === true,
+      });
+      if (result.file) {
+        imageInfo.thumbnail_file = result.file;
+      } else {
+        imageInfo.thumbnail_url = result.url;
+      }
+      if (thumbMeta) {
+        imageInfo.thumbnail_info = {
+          w: thumbMeta.width,
+          h: thumbMeta.height,
+          mimetype: "image/jpeg",
+          size: thumbBuffer.byteLength,
+        };
+      }
+    } catch {
+      // Thumbnail generation failed, continue without it
+    }
+  }
+  return imageInfo;
+}
+
+export async function resolveMediaDurationMs(params: {
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+  kind: MediaKind;
+}): Promise<number | undefined> {
+  if (params.kind !== "audio" && params.kind !== "video") {
+    return undefined;
+  }
+  try {
+    const fileInfo: IFileInfo | string | undefined =
+      params.contentType || params.fileName
+        ? {
+            mimeType: params.contentType,
+            size: params.buffer.byteLength,
+            path: params.fileName,
+          }
+        : undefined;
+    const metadata = await parseBuffer(params.buffer, fileInfo, {
+      duration: true,
+      skipCovers: true,
+    });
+    const durationSeconds = metadata.format.duration;
+    if (typeof durationSeconds === "number" && Number.isFinite(durationSeconds)) {
+      return Math.max(0, Math.round(durationSeconds * 1000));
+    }
+  } catch {
+    // Duration is optional; ignore parse failures.
+  }
+  return undefined;
+}
+
+async function uploadFile(
+  client: MatrixClient,
+  file: Buffer,
+  params: {
+    contentType?: string;
+    filename?: string;
+  },
+): Promise<string> {
+  return await client.uploadContent(file, params.contentType, params.filename);
+}
+
+async function uploadMediaWithEncryption(
+  client: MatrixClient,
+  buffer: Buffer,
+  params: {
+    contentType?: string;
+    filename?: string;
+    encrypted: boolean;
+  },
+): Promise<{ url: string; file?: EncryptedFile }> {
+  if (params.encrypted && client.crypto) {
+    const encrypted = await client.crypto.encryptMedia(buffer);
+    const mxc = await client.uploadContent(encrypted.buffer, params.contentType, params.filename);
+    const file: EncryptedFile = { url: mxc, ...encrypted.file };
+    return {
+      url: mxc,
+      file,
+    };
+  }
+
+  const mxc = await uploadFile(client, buffer, params);
+  return { url: mxc };
+}
+
+/**
+ * Upload media with optional encryption for E2EE rooms.
+ */
+export async function uploadMediaMaybeEncrypted(
+  client: MatrixClient,
+  roomId: string,
+  buffer: Buffer,
+  params: {
+    contentType?: string;
+    filename?: string;
+  },
+): Promise<{ url: string; file?: EncryptedFile }> {
+  // Check if room is encrypted and crypto is available
+  const isEncrypted = Boolean(client.crypto && (await client.crypto.isRoomEncrypted(roomId)));
+  return await uploadMediaWithEncryption(client, buffer, {
+    ...params,
+    encrypted: isEncrypted,
+  });
+}