@archipelagolab/lobi 1.0.0

package/src/matrix/direct-management.ts

@@ -0,0 +1,347 @@
+import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-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 hasPrimaryMatrixDirectRoomMapping(params: {
+  directContent: MatrixDirectAccountData;
+  remoteUserId: string;
+  roomId: string;
+}): boolean {
+  return normalizeMappedRoomIds(params.directContent, params.remoteUserId)[0] === params.roomId;
+}
+
+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 writeMatrixDirectRoomMapping(params: {
+  client: MatrixClient;
+  remoteUserId: string;
+  roomId: 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,
+        roomId: params.roomId,
+      });
+      const changed = !hasPrimaryMatrixDirectRoomMapping({
+        directContent: directContentBefore,
+        remoteUserId: params.remoteUserId,
+        roomId: params.roomId,
+      });
+      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;
+  roomId: string;
+}): MatrixDirectAccountData {
+  const current = normalizeMappedRoomIds(params.directContent, params.remoteUserId);
+  const nextRooms = normalizeRoomIdList([params.roomId, ...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 writeMatrixDirectRoomMapping({
+      client: params.client,
+      remoteUserId,
+      roomId: 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 (!mappedStrict && 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 writeMatrixDirectRoomMapping({
+    client: params.client,
+    remoteUserId,
+    roomId: activeRoomId,
+  });
+  return {
+    ...inspected,
+    activeRoomId,
+    createdRoomId,
+    changed: mappingWrite.changed,
+    directContentBefore: mappingWrite.directContentBefore,
+    directContentAfter: mappingWrite.directContentAfter,
+  };
+}

package/src/matrix/direct-room.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from "vitest";
+import { inspectMatrixDirectRoomEvidence } from "./direct-room.js";
+import type { MatrixClient } from "./sdk.js";
+
+function createClient(overrides: Partial<MatrixClient> = {}): MatrixClient {
+  return {
+    getUserId: vi.fn(async () => "@bot:example.org"),
+    getJoinedRoomMembers: vi.fn(async () => ["@bot:example.org", "@alice:example.org"]),
+    getRoomStateEvent: vi.fn(async () => ({})),
+    ...overrides,
+  } as unknown as MatrixClient;
+}
+
+describe("inspectMatrixDirectRoomEvidence", () => {
+  it("does not retry getUserId when callers explicitly pass a missing self user", async () => {
+    const getUserId = vi.fn(async () => "@bot:example.org");
+    const client = createClient({ getUserId });
+
+    const result = await inspectMatrixDirectRoomEvidence({
+      client,
+      roomId: "!dm:example.org",
+      remoteUserId: "@alice:example.org",
+      selfUserId: null,
+    });
+
+    expect(getUserId).not.toHaveBeenCalled();
+    expect(result.strict).toBe(false);
+  });
+
+  it("resolves selfUserId when callers leave it undefined", async () => {
+    const getUserId = vi.fn(async () => "@bot:example.org");
+    const client = createClient({ getUserId });
+
+    const result = await inspectMatrixDirectRoomEvidence({
+      client,
+      roomId: "!dm:example.org",
+      remoteUserId: "@alice:example.org",
+    });
+
+    expect(getUserId).toHaveBeenCalledTimes(1);
+    expect(result.strict).toBe(true);
+  });
+
+  it("records only the local member-state direct flag", async () => {
+    const client = createClient({
+      getRoomStateEvent: vi.fn(async (_roomId: string, _eventType: string, stateKey: string) =>
+        stateKey === "@bot:example.org" ? { is_direct: false } : { is_direct: true },
+      ),
+    });
+
+    const result = await inspectMatrixDirectRoomEvidence({
+      client,
+      roomId: "!dm:example.org",
+      remoteUserId: "@alice:example.org",
+    });
+
+    expect(result.strict).toBe(true);
+    expect(result.memberStateFlag).toBe(false);
+    expect(result.viaMemberState).toBe(false);
+  });
+});

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;
+}