@gakr-gakr/matrix 0.1.0

package/src/matrix/monitor/status.ts

@@ -0,0 +1,120 @@
+import type { ChannelAccountSnapshot } from "autobot/plugin-sdk/channel-contract";
+import {
+  createConnectedChannelStatusPatch,
+  createTransportActivityStatusPatch,
+} from "autobot/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

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

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

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

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

@@ -0,0 +1,85 @@
+import { resolveThreadSessionKeys } from "autobot/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

@@ -0,0 +1,30 @@
+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 };
+  };
+};