@kodelyth/matrix 2026.5.42 → 2026.6.2

package/src/matrix/monitor/status.ts

@@ -1,120 +0,0 @@
-import type { ChannelAccountSnapshot } from "klaw/plugin-sdk/channel-contract";
-import {
-  createConnectedChannelStatusPatch,
-  createTransportActivityStatusPatch,
-} from "klaw/plugin-sdk/gateway-runtime";
-import { formatMatrixErrorMessage } from "../errors.js";
-import {
-  isMatrixDisconnectedSyncState,
-  isMatrixReadySyncState,
-  type MatrixSyncState,
-} from "../sync-state.js";
-
-type MatrixMonitorStatusSink = (patch: ChannelAccountSnapshot) => void;
-
-function cloneLastDisconnect(
-  value: ChannelAccountSnapshot["lastDisconnect"],
-): ChannelAccountSnapshot["lastDisconnect"] {
-  if (!value || typeof value === "string") {
-    return value ?? null;
-  }
-  return { ...value };
-}
-
-function formatSyncError(error: unknown): string | null {
-  if (!error) {
-    return null;
-  }
-  if (error instanceof Error) {
-    return error.message || error.name || "unknown";
-  }
-  return formatMatrixErrorMessage(error);
-}
-
-export type MatrixMonitorStatusController = ReturnType<typeof createMatrixMonitorStatusController>;
-
-export function createMatrixMonitorStatusController(params: {
-  accountId: string;
-  baseUrl?: string;
-  statusSink?: MatrixMonitorStatusSink;
-}) {
-  const status: ChannelAccountSnapshot = {
-    accountId: params.accountId,
-    ...(params.baseUrl ? { baseUrl: params.baseUrl } : {}),
-    connected: false,
-    lastConnectedAt: null,
-    lastDisconnect: null,
-    lastError: null,
-    healthState: "starting",
-  };
-
-  const emit = () => {
-    params.statusSink?.({
-      ...status,
-      lastDisconnect: cloneLastDisconnect(status.lastDisconnect),
-    });
-  };
-
-  const noteConnected = (at = Date.now(), options?: { transportActivity?: boolean }) => {
-    if (status.connected === true) {
-      status.lastEventAt = at;
-    } else {
-      Object.assign(status, createConnectedChannelStatusPatch(at));
-    }
-    if (options?.transportActivity) {
-      Object.assign(status, createTransportActivityStatusPatch(at));
-    }
-    status.lastError = null;
-    status.lastDisconnect = null;
-    status.healthState = "healthy";
-    emit();
-  };
-
-  const noteDisconnected = (params: { state: MatrixSyncState; at?: number; error?: unknown }) => {
-    const at = params.at ?? Date.now();
-    const error = formatSyncError(params.error);
-    status.connected = false;
-    status.lastEventAt = at;
-    status.lastDisconnect = {
-      at,
-      ...(error ? { error } : {}),
-    };
-    status.lastError = error;
-    status.healthState = params.state.toLowerCase();
-    emit();
-  };
-
-  emit();
-
-  return {
-    noteSyncState(state: MatrixSyncState, error?: unknown, at = Date.now()) {
-      if (isMatrixReadySyncState(state)) {
-        // matrix-js-sdk emits SYNCING after each successful /sync response.
-        // PREPARED can be cache-backed and CATCHUP is a lifecycle bridge, so
-        // neither should refresh transport liveness.
-        noteConnected(at, { transportActivity: state === "SYNCING" });
-        return;
-      }
-      if (isMatrixDisconnectedSyncState(state)) {
-        noteDisconnected({ state, at, error });
-        return;
-      }
-      // Unknown future SDK states inherit the current connectivity bit until the
-      // SDK classifies them as ready or disconnected. Avoid guessing here.
-      status.lastEventAt = at;
-      status.healthState = state.toLowerCase();
-      emit();
-    },
-    noteUnexpectedError(error: unknown, at = Date.now()) {
-      noteDisconnected({ state: "ERROR", at, error });
-    },
-    markStopped(at = Date.now()) {
-      status.connected = false;
-      status.lastEventAt = at;
-      if (status.healthState !== "error") {
-        status.healthState = "stopped";
-      }
-      emit();
-    },
-  };
-}

package/src/matrix/monitor/sync-lifecycle.ts

@@ -1,91 +0,0 @@
-import type { MatrixClient } from "../sdk.js";
-import { isMatrixTerminalSyncState, type MatrixSyncState } from "../sync-state.js";
-import type { MatrixMonitorStatusController } from "./status.js";
-
-function formatSyncLifecycleError(state: MatrixSyncState, error?: unknown): Error {
-  if (error instanceof Error) {
-    return error;
-  }
-  const message = typeof error === "string" && error.trim() ? error.trim() : undefined;
-  if (state === "STOPPED") {
-    return new Error(message ?? "Matrix sync stopped unexpectedly");
-  }
-  if (state === "ERROR") {
-    return new Error(message ?? "Matrix sync entered ERROR unexpectedly");
-  }
-  return new Error(message ?? `Matrix sync entered ${state} unexpectedly`);
-}
-
-export function createMatrixMonitorSyncLifecycle(params: {
-  client: MatrixClient;
-  statusController: MatrixMonitorStatusController;
-  isStopping?: () => boolean;
-}) {
-  let fatalError: Error | null = null;
-  let resolveFatalWait: (() => void) | null = null;
-  let rejectFatalWait: ((error: Error) => void) | null = null;
-
-  const settleFatal = (error: Error) => {
-    if (fatalError) {
-      return;
-    }
-    fatalError = error;
-    rejectFatalWait?.(error);
-    resolveFatalWait = null;
-    rejectFatalWait = null;
-  };
-
-  const onSyncState = (state: MatrixSyncState, _prevState: string | null, error?: unknown) => {
-    if (isMatrixTerminalSyncState(state) && !params.isStopping?.()) {
-      const fatalError = formatSyncLifecycleError(state, error);
-      params.statusController.noteUnexpectedError(fatalError);
-      settleFatal(fatalError);
-      return;
-    }
-    // Fatal sync failures are sticky for telemetry; later SDK state churn during
-    // cleanup or reconnect should not overwrite the first recorded error.
-    if (fatalError) {
-      return;
-    }
-    // Operator-initiated shutdown can still emit transient sync states before
-    // the final STOPPED. Ignore that churn so intentional stops do not look
-    // like runtime failures.
-    if (params.isStopping?.() && !isMatrixTerminalSyncState(state)) {
-      return;
-    }
-    params.statusController.noteSyncState(state, error);
-  };
-
-  const onUnexpectedError = (error: Error) => {
-    if (params.isStopping?.()) {
-      return;
-    }
-    params.statusController.noteUnexpectedError(error);
-    settleFatal(error);
-  };
-
-  params.client.on("sync.state", onSyncState);
-  params.client.on("sync.unexpected_error", onUnexpectedError);
-
-  return {
-    async waitForFatalStop(): Promise<void> {
-      if (fatalError) {
-        throw fatalError;
-      }
-      if (resolveFatalWait || rejectFatalWait) {
-        throw new Error("Matrix fatal-stop wait already in progress");
-      }
-      await new Promise<void>((resolve, reject) => {
-        resolveFatalWait = resolve;
-        rejectFatalWait = (error) => reject(error);
-      });
-    },
-    dispose() {
-      resolveFatalWait?.();
-      resolveFatalWait = null;
-      rejectFatalWait = null;
-      params.client.off("sync.state", onSyncState);
-      params.client.off("sync.unexpected_error", onUnexpectedError);
-    },
-  };
-}

package/src/matrix/monitor/task-runner.ts

@@ -1,38 +0,0 @@
-import type { RuntimeLogger } from "../../runtime-api.js";
-
-export function createMatrixMonitorTaskRunner(params: {
-  logger: RuntimeLogger;
-  logVerboseMessage: (message: string) => void;
-}) {
-  const inFlight = new Set<Promise<void>>();
-
-  const runDetachedTask = (label: string, task: () => Promise<void>): Promise<void> => {
-    let trackedTask!: Promise<void>;
-    trackedTask = Promise.resolve()
-      .then(task)
-      .catch((error) => {
-        const message = String(error);
-        params.logVerboseMessage(`matrix: ${label} failed (${message})`);
-        params.logger.warn("matrix background task failed", {
-          task: label,
-          error: message,
-        });
-      })
-      .finally(() => {
-        inFlight.delete(trackedTask);
-      });
-    inFlight.add(trackedTask);
-    return trackedTask;
-  };
-
-  const waitForIdle = async (): Promise<void> => {
-    while (inFlight.size > 0) {
-      await Promise.allSettled(Array.from(inFlight));
-    }
-  };
-
-  return {
-    runDetachedTask,
-    waitForIdle,
-  };
-}

package/src/matrix/monitor/test-events.ts

@@ -1,21 +0,0 @@
-import type { MatrixRawEvent } from "./types.js";
-
-export function createPollStartEvent(eventId: string): MatrixRawEvent {
-  return {
-    event_id: eventId,
-    sender: "@alice:example.org",
-    type: "m.poll.start",
-    origin_server_ts: Date.now(),
-    content: {
-      "m.poll.start": {
-        question: { "m.text": "Lunch?" },
-        kind: "m.poll.disclosed",
-        max_selections: 1,
-        answers: [
-          { id: "a1", "m.text": "Pizza" },
-          { id: "a2", "m.text": "Sushi" },
-        ],
-      },
-    },
-  };
-}

package/src/matrix/monitor/thread-context.ts

@@ -1,108 +0,0 @@
-import type { MatrixClient } from "../sdk.js";
-import { summarizeMatrixMessageContextEvent, trimMatrixMaybeString } from "./context-summary.js";
-import type { MatrixRawEvent } from "./types.js";
-
-const MAX_TRACKED_THREAD_STARTERS = 256;
-const MAX_THREAD_STARTER_BODY_LENGTH = 500;
-
-type MatrixThreadContext = {
-  threadStarterBody?: string;
-  senderId?: string;
-  senderLabel?: string;
-  summary?: string;
-};
-
-function truncateThreadStarterBody(value: string): string {
-  if (value.length <= MAX_THREAD_STARTER_BODY_LENGTH) {
-    return value;
-  }
-  return `${value.slice(0, MAX_THREAD_STARTER_BODY_LENGTH - 3)}...`;
-}
-
-export function summarizeMatrixThreadStarterEvent(event: MatrixRawEvent): string | undefined {
-  const body = summarizeMatrixMessageContextEvent(event);
-  if (body) {
-    return truncateThreadStarterBody(body);
-  }
-  const content = event.content as { msgtype?: unknown };
-  const msgtype = trimMatrixMaybeString(content.msgtype);
-  if (msgtype) {
-    return `Matrix ${msgtype} message`;
-  }
-  const eventType = trimMatrixMaybeString(event.type);
-  return eventType ? `Matrix ${eventType} event` : undefined;
-}
-
-function formatMatrixThreadStarterBody(params: {
-  threadRootId: string;
-  senderName?: string;
-  senderId?: string;
-  summary?: string;
-}): string {
-  const senderLabel = params.senderName ?? params.senderId ?? "unknown sender";
-  const lines = [`Matrix thread root ${params.threadRootId} from ${senderLabel}:`];
-  if (params.summary) {
-    lines.push(params.summary);
-  }
-  return lines.join("\n");
-}
-
-export function createMatrixThreadContextResolver(params: {
-  client: MatrixClient;
-  getMemberDisplayName: (roomId: string, userId: string) => Promise<string>;
-  logVerboseMessage: (message: string) => void;
-}) {
-  const cache = new Map<string, MatrixThreadContext>();
-
-  const remember = (key: string, value: MatrixThreadContext): MatrixThreadContext => {
-    cache.set(key, value);
-    if (cache.size > MAX_TRACKED_THREAD_STARTERS) {
-      const oldest = cache.keys().next().value;
-      if (typeof oldest === "string") {
-        cache.delete(oldest);
-      }
-    }
-    return value;
-  };
-
-  return async (input: { roomId: string; threadRootId: string }): Promise<MatrixThreadContext> => {
-    const cacheKey = `${input.roomId}:${input.threadRootId}`;
-    const cached = cache.get(cacheKey);
-    if (cached) {
-      return cached;
-    }
-
-    const rootEvent = await params.client
-      .getEvent(input.roomId, input.threadRootId)
-      .catch((err) => {
-        params.logVerboseMessage(
-          `matrix: failed resolving thread root room=${input.roomId} id=${input.threadRootId}: ${String(err)}`,
-        );
-        return null;
-      });
-    if (!rootEvent) {
-      return {
-        threadStarterBody: `Matrix thread root ${input.threadRootId}`,
-      };
-    }
-
-    const rawEvent = rootEvent as MatrixRawEvent;
-    const senderId = trimMatrixMaybeString(rawEvent.sender);
-    const senderName =
-      senderId &&
-      (await params.getMemberDisplayName(input.roomId, senderId).catch(() => undefined));
-    const senderLabel = senderName ?? senderId;
-    const summary = summarizeMatrixThreadStarterEvent(rawEvent);
-    return remember(cacheKey, {
-      threadStarterBody: formatMatrixThreadStarterBody({
-        threadRootId: input.threadRootId,
-        senderId,
-        senderName,
-        summary,
-      }),
-      senderId,
-      senderLabel,
-      summary,
-    });
-  };
-}

package/src/matrix/monitor/threads.ts

@@ -1,85 +0,0 @@
-import { resolveThreadSessionKeys } from "klaw/plugin-sdk/routing";
-import type { MatrixRawEvent, RoomMessageEventContent } from "./types.js";
-import { RelationType } from "./types.js";
-
-type MatrixThreadReplies = "off" | "inbound" | "always";
-
-type MatrixThreadRouting = {
-  threadId?: string;
-};
-
-export function resolveMatrixThreadSessionKeys(params: {
-  baseSessionKey: string;
-  threadId?: string | null;
-  parentSessionKey?: string;
-  useSuffix?: boolean;
-}): { sessionKey: string; parentSessionKey?: string } {
-  return resolveThreadSessionKeys({
-    ...params,
-    // Matrix event IDs are opaque and case-sensitive; keep the exact thread root.
-    normalizeThreadId: (threadId) => threadId,
-  });
-}
-
-function resolveMatrixRelatedReplyToEventId(relates: unknown): string | undefined {
-  if (!relates || typeof relates !== "object") {
-    return undefined;
-  }
-  if (
-    "m.in_reply_to" in relates &&
-    typeof relates["m.in_reply_to"] === "object" &&
-    relates["m.in_reply_to"] &&
-    "event_id" in relates["m.in_reply_to"] &&
-    typeof relates["m.in_reply_to"].event_id === "string"
-  ) {
-    return relates["m.in_reply_to"].event_id;
-  }
-  return undefined;
-}
-
-export function resolveMatrixThreadRouting(params: {
-  isDirectMessage: boolean;
-  threadReplies: MatrixThreadReplies;
-  dmThreadReplies?: MatrixThreadReplies;
-  messageId: string;
-  threadRootId?: string;
-}): MatrixThreadRouting {
-  const effectiveThreadReplies =
-    params.isDirectMessage && params.dmThreadReplies !== undefined
-      ? params.dmThreadReplies
-      : params.threadReplies;
-  const messageId = params.messageId.trim();
-  const threadRootId = params.threadRootId?.trim();
-  const inboundThreadId = threadRootId && threadRootId !== messageId ? threadRootId : undefined;
-  const threadId =
-    effectiveThreadReplies === "off"
-      ? undefined
-      : effectiveThreadReplies === "inbound"
-        ? inboundThreadId
-        : (inboundThreadId ?? (messageId || undefined));
-
-  return {
-    threadId,
-  };
-}
-
-export function resolveMatrixThreadRootId(params: {
-  event: MatrixRawEvent;
-  content: RoomMessageEventContent;
-}): string | undefined {
-  const relates = params.content["m.relates_to"];
-  if (!relates || typeof relates !== "object") {
-    return undefined;
-  }
-  if ("rel_type" in relates && relates.rel_type === RelationType.Thread) {
-    if ("event_id" in relates && typeof relates.event_id === "string") {
-      return relates.event_id;
-    }
-    return resolveMatrixRelatedReplyToEventId(relates);
-  }
-  return undefined;
-}
-
-export function resolveMatrixReplyToEventId(content: RoomMessageEventContent): string | undefined {
-  return resolveMatrixRelatedReplyToEventId(content["m.relates_to"]);
-}

package/src/matrix/monitor/types.ts

@@ -1,30 +0,0 @@
-import { MATRIX_REACTION_EVENT_TYPE } from "../reaction-common.js";
-import type { EncryptedFile, MessageEventContent } from "../sdk.js";
-export type { MatrixRawEvent } from "../sdk.js";
-
-export const EventType = {
-  RoomMessage: "m.room.message",
-  RoomMessageEncrypted: "m.room.encrypted",
-  RoomMember: "m.room.member",
-  Location: "m.location",
-  Reaction: MATRIX_REACTION_EVENT_TYPE,
-} as const;
-
-export const RelationType = {
-  Replace: "m.replace",
-  Thread: "m.thread",
-} as const;
-
-export type RoomMessageEventContent = MessageEventContent & {
-  url?: string;
-  file?: EncryptedFile;
-  info?: {
-    mimetype?: string;
-    size?: number;
-  };
-  "m.relates_to"?: {
-    rel_type?: string;
-    event_id?: string;
-    "m.in_reply_to"?: { event_id?: string };
-  };
-};