@gakr-gakr/matrix 0.1.0

package/src/matrix/direct-management.ts

@@ -0,0 +1,349 @@
+import { KeyedAsyncQueue } from "autobot/plugin-sdk/keyed-async-queue";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { inspectMatrixDirectRoomEvidence } from "./direct-room.js";
+import type { MatrixClient } from "./sdk.js";
+import { EventType, type MatrixDirectAccountData } from "./send/types.js";
+import { isMatrixQualifiedUserId } from "./target-ids.js";
+
+export type MatrixDirectRoomCandidate = {
+  roomId: string;
+  joinedMembers: string[] | null;
+  strict: boolean;
+  explicit: boolean;
+  source: "account-data" | "joined";
+};
+
+export type MatrixDirectRoomInspection = {
+  selfUserId: string | null;
+  remoteUserId: string;
+  mappedRoomIds: string[];
+  mappedRooms: MatrixDirectRoomCandidate[];
+  discoveredStrictRoomIds: string[];
+  activeRoomId: string | null;
+};
+
+export type MatrixDirectRoomRepairResult = MatrixDirectRoomInspection & {
+  createdRoomId: string | null;
+  changed: boolean;
+  directContentBefore: MatrixDirectAccountData;
+  directContentAfter: MatrixDirectAccountData;
+};
+
+export type MatrixDirectRoomPromotionResult =
+  | {
+      classifyAsDirect: true;
+      repaired: boolean;
+      roomId: string;
+      reason: "promoted" | "already-mapped" | "repair-failed";
+    }
+  | {
+      classifyAsDirect: false;
+      repaired: false;
+      reason: "not-strict" | "local-explicit-false";
+    };
+
+type MatrixDirectRoomMappingWriteResult = {
+  changed: boolean;
+  directContentBefore: MatrixDirectAccountData;
+  directContentAfter: MatrixDirectAccountData;
+};
+
+const DIRECT_ACCOUNT_DATA_QUEUE_KEY = EventType.Direct;
+const directAccountDataWriteQueues = new WeakMap<MatrixClient, KeyedAsyncQueue>();
+
+async function readMatrixDirectAccountData(client: MatrixClient): Promise<MatrixDirectAccountData> {
+  try {
+    const direct = (await client.getAccountData(EventType.Direct)) as MatrixDirectAccountData;
+    return direct && typeof direct === "object" && !Array.isArray(direct) ? direct : {};
+  } catch {
+    return {};
+  }
+}
+
+function normalizeRemoteUserId(remoteUserId: string): string {
+  const normalized = normalizeOptionalString(remoteUserId) ?? "";
+  if (!isMatrixQualifiedUserId(normalized)) {
+    throw new Error(`Matrix user IDs must be fully qualified (got "${remoteUserId}")`);
+  }
+  return normalized;
+}
+
+function normalizeMappedRoomIds(direct: MatrixDirectAccountData, remoteUserId: string): string[] {
+  const current = direct[remoteUserId];
+  if (!Array.isArray(current)) {
+    return [];
+  }
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const value of current) {
+    const roomId = normalizeOptionalString(value) ?? "";
+    if (!roomId || seen.has(roomId)) {
+      continue;
+    }
+    seen.add(roomId);
+    normalized.push(roomId);
+  }
+  return normalized;
+}
+
+function normalizeRoomIdList(values: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const value of values) {
+    const roomId = value.trim();
+    if (!roomId || seen.has(roomId)) {
+      continue;
+    }
+    seen.add(roomId);
+    normalized.push(roomId);
+  }
+  return normalized;
+}
+
+function hasMatrixDirectRoomMappings(params: {
+  directContent: MatrixDirectAccountData;
+  remoteUserId: string;
+  roomIds: readonly string[];
+}): boolean {
+  const current = normalizeMappedRoomIds(params.directContent, params.remoteUserId);
+  const next = normalizeRoomIdList([...params.roomIds, ...current]);
+  return current.length === next.length && current.every((roomId, index) => roomId === next[index]);
+}
+
+function resolveDirectAccountDataWriteQueue(client: MatrixClient): KeyedAsyncQueue {
+  const existing = directAccountDataWriteQueues.get(client);
+  if (existing) {
+    return existing;
+  }
+  const created = new KeyedAsyncQueue();
+  directAccountDataWriteQueues.set(client, created);
+  return created;
+}
+
+async function writeMatrixDirectRoomMappings(params: {
+  client: MatrixClient;
+  remoteUserId: string;
+  roomIds: readonly string[];
+}): Promise<MatrixDirectRoomMappingWriteResult> {
+  return await resolveDirectAccountDataWriteQueue(params.client).enqueue(
+    DIRECT_ACCOUNT_DATA_QUEUE_KEY,
+    async () => {
+      const directContentBefore = await readMatrixDirectAccountData(params.client);
+      const directContentAfter = buildNextDirectContent({
+        directContent: directContentBefore,
+        remoteUserId: params.remoteUserId,
+        roomIds: params.roomIds,
+      });
+      const changed = !hasMatrixDirectRoomMappings({
+        directContent: directContentBefore,
+        remoteUserId: params.remoteUserId,
+        roomIds: params.roomIds,
+      });
+      if (changed) {
+        await params.client.setAccountData(EventType.Direct, directContentAfter);
+      }
+      return {
+        changed,
+        directContentBefore,
+        directContentAfter,
+      };
+    },
+  );
+}
+
+async function classifyDirectRoomCandidate(params: {
+  client: MatrixClient;
+  roomId: string;
+  remoteUserId: string;
+  selfUserId: string | null;
+  source: "account-data" | "joined";
+}): Promise<MatrixDirectRoomCandidate> {
+  const evidence = await inspectMatrixDirectRoomEvidence({
+    client: params.client,
+    roomId: params.roomId,
+    remoteUserId: params.remoteUserId,
+    selfUserId: params.selfUserId,
+  });
+  return {
+    roomId: params.roomId,
+    joinedMembers: evidence.joinedMembers,
+    strict:
+      evidence.strict && (params.source === "account-data" || evidence.memberStateFlag !== false),
+    explicit:
+      evidence.strict &&
+      (params.source === "account-data" || evidence.memberStateFlag !== false) &&
+      (params.source === "account-data" || evidence.viaMemberState),
+    source: params.source,
+  };
+}
+
+function buildNextDirectContent(params: {
+  directContent: MatrixDirectAccountData;
+  remoteUserId: string;
+  roomIds: readonly string[];
+}): MatrixDirectAccountData {
+  const current = normalizeMappedRoomIds(params.directContent, params.remoteUserId);
+  const nextRooms = normalizeRoomIdList([...params.roomIds, ...current]);
+  return {
+    ...params.directContent,
+    [params.remoteUserId]: nextRooms,
+  };
+}
+
+export async function persistMatrixDirectRoomMapping(params: {
+  client: MatrixClient;
+  remoteUserId: string;
+  roomId: string;
+}): Promise<boolean> {
+  const remoteUserId = normalizeRemoteUserId(params.remoteUserId);
+  return (
+    await writeMatrixDirectRoomMappings({
+      client: params.client,
+      remoteUserId,
+      roomIds: [params.roomId],
+    })
+  ).changed;
+}
+
+export async function promoteMatrixDirectRoomCandidate(params: {
+  client: MatrixClient;
+  remoteUserId: string;
+  roomId: string;
+  selfUserId?: string | null;
+}): Promise<MatrixDirectRoomPromotionResult> {
+  const remoteUserId = normalizeRemoteUserId(params.remoteUserId);
+  const evidence = await inspectMatrixDirectRoomEvidence({
+    client: params.client,
+    roomId: params.roomId,
+    remoteUserId,
+    selfUserId: params.selfUserId,
+  });
+  if (!evidence.strict) {
+    return {
+      classifyAsDirect: false,
+      repaired: false,
+      reason: "not-strict",
+    };
+  }
+  if (evidence.memberStateFlag === false) {
+    return {
+      classifyAsDirect: false,
+      repaired: false,
+      reason: "local-explicit-false",
+    };
+  }
+
+  try {
+    const repaired = await persistMatrixDirectRoomMapping({
+      client: params.client,
+      remoteUserId,
+      roomId: params.roomId,
+    });
+    return {
+      classifyAsDirect: true,
+      repaired,
+      roomId: params.roomId,
+      reason: repaired ? "promoted" : "already-mapped",
+    };
+  } catch {
+    return {
+      classifyAsDirect: true,
+      repaired: false,
+      roomId: params.roomId,
+      reason: "repair-failed",
+    };
+  }
+}
+
+export async function inspectMatrixDirectRooms(params: {
+  client: MatrixClient;
+  remoteUserId: string;
+}): Promise<MatrixDirectRoomInspection> {
+  const remoteUserId = normalizeRemoteUserId(params.remoteUserId);
+  const selfUserId =
+    normalizeOptionalString(await params.client.getUserId().catch(() => null)) ?? null;
+  const directContent = await readMatrixDirectAccountData(params.client);
+  const mappedRoomIds = normalizeMappedRoomIds(directContent, remoteUserId);
+  const mappedRooms = await Promise.all(
+    mappedRoomIds.map(
+      async (roomId) =>
+        await classifyDirectRoomCandidate({
+          client: params.client,
+          roomId,
+          remoteUserId,
+          selfUserId,
+          source: "account-data",
+        }),
+    ),
+  );
+  const mappedStrict = mappedRooms.find((room) => room.strict);
+
+  let joinedRooms: string[] = [];
+  if (typeof params.client.getJoinedRooms === "function") {
+    try {
+      const resolved = await params.client.getJoinedRooms();
+      joinedRooms = Array.isArray(resolved) ? resolved : [];
+    } catch {
+      joinedRooms = [];
+    }
+  }
+  const discoveredStrictRooms: MatrixDirectRoomCandidate[] = [];
+  for (const roomId of normalizeRoomIdList(joinedRooms)) {
+    if (mappedRoomIds.includes(roomId)) {
+      continue;
+    }
+    const candidate = await classifyDirectRoomCandidate({
+      client: params.client,
+      roomId,
+      remoteUserId,
+      selfUserId,
+      source: "joined",
+    });
+    if (candidate.strict) {
+      discoveredStrictRooms.push(candidate);
+    }
+  }
+  const discoveredStrictRoomIds = discoveredStrictRooms.map((room) => room.roomId);
+  const discoveredExplicit = discoveredStrictRooms.find((room) => room.explicit);
+
+  return {
+    selfUserId,
+    remoteUserId,
+    mappedRoomIds,
+    mappedRooms,
+    discoveredStrictRoomIds,
+    activeRoomId:
+      mappedStrict?.roomId ?? discoveredExplicit?.roomId ?? discoveredStrictRoomIds[0] ?? null,
+  };
+}
+
+export async function repairMatrixDirectRooms(params: {
+  client: MatrixClient;
+  remoteUserId: string;
+  encrypted?: boolean;
+}): Promise<MatrixDirectRoomRepairResult> {
+  const remoteUserId = normalizeRemoteUserId(params.remoteUserId);
+  const inspected = await inspectMatrixDirectRooms({
+    client: params.client,
+    remoteUserId,
+  });
+  const activeRoomId =
+    inspected.activeRoomId ??
+    (await params.client.createDirectRoom(remoteUserId, {
+      encrypted: params.encrypted === true,
+    }));
+  const createdRoomId = inspected.activeRoomId ? null : activeRoomId;
+  const mappingWrite = await writeMatrixDirectRoomMappings({
+    client: params.client,
+    remoteUserId,
+    roomIds: [activeRoomId, ...inspected.discoveredStrictRoomIds],
+  });
+  return {
+    ...inspected,
+    activeRoomId,
+    createdRoomId,
+    changed: mappingWrite.changed,
+    directContentBefore: mappingWrite.directContentBefore,
+    directContentAfter: mappingWrite.directContentAfter,
+  };
+}

package/src/matrix/direct-room.ts

@@ -0,0 +1,128 @@
+import type { MatrixClient } from "./sdk.js";
+
+function trimMaybeString(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function normalizeJoinedMatrixMembers(joinedMembers: unknown): string[] {
+  if (!Array.isArray(joinedMembers)) {
+    return [];
+  }
+  return joinedMembers
+    .map((entry) => trimMaybeString(entry))
+    .filter((entry): entry is string => Boolean(entry));
+}
+
+export function isStrictDirectMembership(params: {
+  selfUserId?: string | null;
+  remoteUserId?: string | null;
+  joinedMembers?: readonly string[] | null;
+}): boolean {
+  const selfUserId = trimMaybeString(params.selfUserId);
+  const remoteUserId = trimMaybeString(params.remoteUserId);
+  const joinedMembers = params.joinedMembers ?? [];
+  return Boolean(
+    selfUserId &&
+    remoteUserId &&
+    joinedMembers.length === 2 &&
+    joinedMembers.includes(selfUserId) &&
+    joinedMembers.includes(remoteUserId),
+  );
+}
+
+export async function readJoinedMatrixMembers(
+  client: MatrixClient,
+  roomId: string,
+): Promise<string[] | null> {
+  try {
+    return normalizeJoinedMatrixMembers(await client.getJoinedRoomMembers(roomId));
+  } catch {
+    return null;
+  }
+}
+
+export async function hasDirectMatrixMemberFlag(
+  client: MatrixClient,
+  roomId: string,
+  userId?: string | null,
+): Promise<boolean | null> {
+  const normalizedUserId = trimMaybeString(userId);
+  if (!normalizedUserId) {
+    return null;
+  }
+  try {
+    const state = await client.getRoomStateEvent(roomId, "m.room.member", normalizedUserId);
+    // Return true if is_direct is explicitly true, false if explicitly false, null if absent
+    if (state?.is_direct === true) {
+      return true;
+    }
+    if (state?.is_direct === false) {
+      return false;
+    }
+    // is_direct field is absent from the membership event
+    return null;
+  } catch {
+    // API/network error - treat as unavailable
+    return null;
+  }
+}
+
+export type MatrixDirectRoomEvidence = {
+  joinedMembers: string[] | null;
+  strict: boolean;
+  viaMemberState: boolean;
+  memberStateFlag: boolean | null;
+};
+
+export async function inspectMatrixDirectRoomEvidence(params: {
+  client: MatrixClient;
+  roomId: string;
+  remoteUserId: string;
+  selfUserId?: string | null;
+}): Promise<MatrixDirectRoomEvidence> {
+  const selfUserId =
+    params.selfUserId !== undefined
+      ? trimMaybeString(params.selfUserId)
+      : trimMaybeString(await params.client.getUserId().catch(() => null));
+  const joinedMembers = await readJoinedMatrixMembers(params.client, params.roomId);
+  const strict = isStrictDirectMembership({
+    selfUserId,
+    remoteUserId: params.remoteUserId,
+    joinedMembers,
+  });
+  if (!strict) {
+    return {
+      joinedMembers,
+      strict: false,
+      viaMemberState: false,
+      memberStateFlag: null,
+    };
+  }
+  const memberStateFlag = await hasDirectMatrixMemberFlag(params.client, params.roomId, selfUserId);
+  return {
+    joinedMembers,
+    strict,
+    viaMemberState: memberStateFlag === true,
+    memberStateFlag,
+  };
+}
+
+export async function isStrictDirectRoom(params: {
+  client: MatrixClient;
+  roomId: string;
+  remoteUserId: string;
+  selfUserId?: string | null;
+}): Promise<boolean> {
+  return (
+    await inspectMatrixDirectRoomEvidence({
+      client: params.client,
+      roomId: params.roomId,
+      remoteUserId: params.remoteUserId,
+      selfUserId: params.selfUserId,
+    })
+  ).strict;
+}

package/src/matrix/draft-stream.ts

@@ -0,0 +1,225 @@
+import { createDraftStreamLoop } from "autobot/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>;
+  /** Cancel pending draft updates without creating a new preview event. */
+  discardPending: () => Promise<void>;
+  /** 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 discardPending = async (): Promise<void> => {
+    stopped = true;
+    loop.stop();
+    await loop.waitForInFlight();
+  };
+
+  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,
+    discardPending,
+    finalizeLive,
+    reset,
+    eventId: () => currentEventId,
+    matchesPreparedText: (text: string) =>
+      prepareMatrixSingleText(text, {
+        cfg,
+        accountId,
+      }).trimmedText === lastSentText,
+    mustDeliverFinalNormally: () => sendFailed || finalizeInPlaceBlocked,
+  };
+}