@kodelyth/matrix 2026.5.42 → 2026.6.1

package/src/matrix/direct-management.ts

@@ -1,349 +0,0 @@
-import { KeyedAsyncQueue } from "klaw/plugin-sdk/keyed-async-queue";
-import { normalizeOptionalString } from "klaw/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

@@ -1,128 +0,0 @@
-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

@@ -1,225 +0,0 @@
-import { createDraftStreamLoop } from "klaw/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,
-  };
-}