@archipelagolab/lobi 1.0.0

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

@@ -0,0 +1,224 @@
+import { EventEmitter } from "node:events";
+import { describe, expect, it, vi } from "vitest";
+import { createMatrixMonitorStatusController } from "./status.js";
+import { createMatrixMonitorSyncLifecycle } from "./sync-lifecycle.js";
+
+function createClientEmitter() {
+  return new EventEmitter() as unknown as {
+    on: (event: string, listener: (...args: unknown[]) => void) => unknown;
+    off: (event: string, listener: (...args: unknown[]) => void) => unknown;
+    emit: (event: string, ...args: unknown[]) => boolean;
+  };
+}
+
+describe("createMatrixMonitorSyncLifecycle", () => {
+  it("rejects the channel wait on unexpected sync errors", async () => {
+    const client = createClientEmitter();
+    const setStatus = vi.fn();
+    const lifecycle = createMatrixMonitorSyncLifecycle({
+      client: client as never,
+      statusController: createMatrixMonitorStatusController({
+        accountId: "default",
+        statusSink: setStatus,
+      }),
+    });
+
+    const waitPromise = lifecycle.waitForFatalStop();
+    client.emit("sync.unexpected_error", new Error("sync exploded"));
+
+    await expect(waitPromise).rejects.toThrow("sync exploded");
+    expect(setStatus).toHaveBeenCalledWith(
+      expect.objectContaining({
+        accountId: "default",
+        healthState: "error",
+        lastError: "sync exploded",
+      }),
+    );
+  });
+
+  it("ignores STOPPED emitted during intentional shutdown", async () => {
+    const client = createClientEmitter();
+    const setStatus = vi.fn();
+    let stopping = false;
+    const lifecycle = createMatrixMonitorSyncLifecycle({
+      client: client as never,
+      statusController: createMatrixMonitorStatusController({
+        accountId: "default",
+        statusSink: setStatus,
+      }),
+      isStopping: () => stopping,
+    });
+
+    const waitPromise = lifecycle.waitForFatalStop();
+    stopping = true;
+    client.emit("sync.state", "STOPPED", "SYNCING", undefined);
+    lifecycle.dispose();
+
+    await expect(waitPromise).resolves.toBeUndefined();
+    expect(setStatus).toHaveBeenCalledWith(
+      expect.objectContaining({
+        accountId: "default",
+        healthState: "stopped",
+      }),
+    );
+  });
+
+  it("marks unexpected STOPPED sync as an error state", async () => {
+    const client = createClientEmitter();
+    const setStatus = vi.fn();
+    const lifecycle = createMatrixMonitorSyncLifecycle({
+      client: client as never,
+      statusController: createMatrixMonitorStatusController({
+        accountId: "default",
+        statusSink: setStatus,
+      }),
+    });
+
+    const waitPromise = lifecycle.waitForFatalStop();
+    client.emit("sync.state", "STOPPED", "SYNCING", undefined);
+
+    await expect(waitPromise).rejects.toThrow("Matrix sync stopped unexpectedly");
+    expect(setStatus).toHaveBeenCalledWith(
+      expect.objectContaining({
+        accountId: "default",
+        healthState: "error",
+        lastError: "Matrix sync stopped unexpectedly",
+      }),
+    );
+  });
+
+  it("ignores unexpected sync errors emitted during intentional shutdown", async () => {
+    const client = createClientEmitter();
+    const setStatus = vi.fn();
+    let stopping = false;
+    const lifecycle = createMatrixMonitorSyncLifecycle({
+      client: client as never,
+      statusController: createMatrixMonitorStatusController({
+        accountId: "default",
+        statusSink: setStatus,
+      }),
+      isStopping: () => stopping,
+    });
+
+    const waitPromise = lifecycle.waitForFatalStop();
+    stopping = true;
+    client.emit("sync.unexpected_error", new Error("shutdown noise"));
+    lifecycle.dispose();
+
+    await expect(waitPromise).resolves.toBeUndefined();
+    expect(setStatus).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        accountId: "default",
+        healthState: "error",
+      }),
+    );
+  });
+
+  it("ignores non-terminal sync states emitted during intentional shutdown", async () => {
+    const client = createClientEmitter();
+    const setStatus = vi.fn();
+    let stopping = false;
+    const statusController = createMatrixMonitorStatusController({
+      accountId: "default",
+      statusSink: setStatus,
+    });
+    const lifecycle = createMatrixMonitorSyncLifecycle({
+      client: client as never,
+      statusController,
+      isStopping: () => stopping,
+    });
+
+    const waitPromise = lifecycle.waitForFatalStop();
+    stopping = true;
+    client.emit("sync.state", "ERROR", "RECONNECTING", new Error("shutdown noise"));
+    lifecycle.dispose();
+    statusController.markStopped();
+
+    await expect(waitPromise).resolves.toBeUndefined();
+    expect(setStatus).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        accountId: "default",
+        healthState: "stopped",
+        lastError: null,
+      }),
+    );
+  });
+
+  it("does not downgrade a fatal error to stopped during shutdown", async () => {
+    const client = createClientEmitter();
+    const setStatus = vi.fn();
+    let stopping = false;
+    const statusController = createMatrixMonitorStatusController({
+      accountId: "default",
+      statusSink: setStatus,
+    });
+    const lifecycle = createMatrixMonitorSyncLifecycle({
+      client: client as never,
+      statusController,
+      isStopping: () => stopping,
+    });
+
+    const waitPromise = lifecycle.waitForFatalStop();
+    client.emit("sync.unexpected_error", new Error("sync exploded"));
+    await expect(waitPromise).rejects.toThrow("sync exploded");
+
+    stopping = true;
+    client.emit("sync.state", "STOPPED", "SYNCING", undefined);
+    lifecycle.dispose();
+    statusController.markStopped();
+
+    expect(setStatus).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        accountId: "default",
+        healthState: "error",
+        lastError: "sync exploded",
+      }),
+    );
+  });
+
+  it("ignores follow-up sync states after a fatal sync error", async () => {
+    const client = createClientEmitter();
+    const setStatus = vi.fn();
+    const lifecycle = createMatrixMonitorSyncLifecycle({
+      client: client as never,
+      statusController: createMatrixMonitorStatusController({
+        accountId: "default",
+        statusSink: setStatus,
+      }),
+    });
+
+    const waitPromise = lifecycle.waitForFatalStop();
+    client.emit("sync.unexpected_error", new Error("sync exploded"));
+    await expect(waitPromise).rejects.toThrow("sync exploded");
+
+    client.emit("sync.state", "RECONNECTING", "SYNCING", new Error("late reconnect"));
+    lifecycle.dispose();
+
+    expect(setStatus).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        accountId: "default",
+        healthState: "error",
+        lastError: "sync exploded",
+      }),
+    );
+  });
+
+  it("rejects a second concurrent fatal-stop waiter", async () => {
+    const client = createClientEmitter();
+    const lifecycle = createMatrixMonitorSyncLifecycle({
+      client: client as never,
+      statusController: createMatrixMonitorStatusController({
+        accountId: "default",
+      }),
+    });
+
+    const firstWait = lifecycle.waitForFatalStop();
+
+    await expect(lifecycle.waitForFatalStop()).rejects.toThrow(
+      "Matrix fatal-stop wait already in progress",
+    );
+
+    lifecycle.dispose();
+    await expect(firstWait).resolves.toBeUndefined();
+  });
+});

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/thread-context.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createMatrixThreadContextResolver,
+  summarizeMatrixThreadStarterEvent,
+} from "./thread-context.js";
+import type { MatrixRawEvent } from "./types.js";
+
+describe("matrix thread context", () => {
+  it("summarizes thread starter events from body text", () => {
+    expect(
+      summarizeMatrixThreadStarterEvent({
+        event_id: "$root",
+        sender: "@alice:example.org",
+        type: "m.room.message",
+        origin_server_ts: Date.now(),
+        content: {
+          msgtype: "m.text",
+          body: " Thread starter body ",
+        },
+      } as MatrixRawEvent),
+    ).toBe("Thread starter body");
+  });
+
+  it("marks media-only thread starter events instead of returning bare filenames", () => {
+    expect(
+      summarizeMatrixThreadStarterEvent({
+        event_id: "$root",
+        sender: "@alice:example.org",
+        type: "m.room.message",
+        origin_server_ts: Date.now(),
+        content: {
+          msgtype: "m.image",
+          body: "photo.jpg",
+        },
+      } as MatrixRawEvent),
+    ).toBe("[matrix image attachment]");
+  });
+
+  it("resolves and caches thread starter context", async () => {
+    const getEvent = vi.fn(async () => ({
+      event_id: "$root",
+      sender: "@alice:example.org",
+      type: "m.room.message",
+      origin_server_ts: Date.now(),
+      content: {
+        msgtype: "m.text",
+        body: "Root topic",
+      },
+    }));
+    const getMemberDisplayName = vi.fn(async () => "Alice");
+    const resolveThreadContext = createMatrixThreadContextResolver({
+      client: {
+        getEvent,
+      } as never,
+      getMemberDisplayName,
+      logVerboseMessage: () => {},
+    });
+
+    await expect(
+      resolveThreadContext({
+        roomId: "!room:example.org",
+        threadRootId: "$root",
+      }),
+    ).resolves.toEqual({
+      threadStarterBody: "Matrix thread root $root from Alice:\nRoot topic",
+      senderId: "@alice:example.org",
+      senderLabel: "Alice",
+      summary: "Root topic",
+    });
+
+    await resolveThreadContext({
+      roomId: "!room:example.org",
+      threadRootId: "$root",
+    });
+
+    expect(getEvent).toHaveBeenCalledTimes(1);
+    expect(getMemberDisplayName).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not cache thread starter fetch failures", async () => {
+    const getEvent = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("temporary failure"))
+      .mockResolvedValueOnce({
+        event_id: "$root",
+        sender: "@alice:example.org",
+        type: "m.room.message",
+        origin_server_ts: Date.now(),
+        content: {
+          msgtype: "m.text",
+          body: "Recovered topic",
+        },
+      });
+    const getMemberDisplayName = vi.fn(async () => "Alice");
+    const resolveThreadContext = createMatrixThreadContextResolver({
+      client: {
+        getEvent,
+      } as never,
+      getMemberDisplayName,
+      logVerboseMessage: () => {},
+    });
+
+    await expect(
+      resolveThreadContext({
+        roomId: "!room:example.org",
+        threadRootId: "$root",
+      }),
+    ).resolves.toEqual({
+      threadStarterBody: "Matrix thread root $root",
+    });
+
+    await expect(
+      resolveThreadContext({
+        roomId: "!room:example.org",
+        threadRootId: "$root",
+      }),
+    ).resolves.toEqual({
+      threadStarterBody: "Matrix thread root $root from Alice:\nRecovered topic",
+      senderId: "@alice:example.org",
+      senderLabel: "Alice",
+      summary: "Recovered topic",
+    });
+
+    expect(getEvent).toHaveBeenCalledTimes(2);
+    expect(getMemberDisplayName).toHaveBeenCalledTimes(1);
+  });
+
+  it("summarizes poll start thread roots from poll content", () => {
+    expect(
+      summarizeMatrixThreadStarterEvent({
+        event_id: "$root",
+        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" },
+            ],
+          },
+        },
+      } as MatrixRawEvent),
+    ).toBe("[Poll]\nLunch?\n\n1. Pizza\n2. 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.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { resolveMatrixThreadRouting } from "./threads.js";
+
+describe("resolveMatrixThreadRouting", () => {
+  it("keeps sessions flat when threadReplies is off", () => {
+    expect(
+      resolveMatrixThreadRouting({
+        isDirectMessage: false,
+        threadReplies: "off",
+        messageId: "$reply1",
+        threadRootId: "$root",
+      }),
+    ).toEqual({
+      threadId: undefined,
+    });
+  });
+
+  it("uses the inbound thread root when replies arrive inside an existing thread", () => {
+    expect(
+      resolveMatrixThreadRouting({
+        isDirectMessage: false,
+        threadReplies: "inbound",
+        messageId: "$reply1",
+        threadRootId: "$root",
+      }),
+    ).toEqual({
+      threadId: "$root",
+    });
+  });
+
+  it("keeps top-level inbound messages flat when threadReplies is inbound", () => {
+    expect(
+      resolveMatrixThreadRouting({
+        isDirectMessage: false,
+        threadReplies: "inbound",
+        messageId: "$root",
+      }),
+    ).toEqual({
+      threadId: undefined,
+    });
+  });
+
+  it("uses the triggering message as the thread id when threadReplies is always", () => {
+    expect(
+      resolveMatrixThreadRouting({
+        isDirectMessage: false,
+        threadReplies: "always",
+        messageId: "$root",
+      }),
+    ).toEqual({
+      threadId: "$root",
+    });
+  });
+
+  it("lets dm.threadReplies override room threading behavior", () => {
+    expect(
+      resolveMatrixThreadRouting({
+        isDirectMessage: true,
+        threadReplies: "always",
+        dmThreadReplies: "off",
+        messageId: "$reply1",
+        threadRootId: "$root",
+      }),
+    ).toEqual({
+      threadId: undefined,
+    });
+  });
+});