@gakr-gakr/matrix 0.1.0

package/src/matrix/session-store-metadata.ts

@@ -0,0 +1,108 @@
+import { normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { resolveMatrixDirectUserId, resolveMatrixTargetIdentity } from "./target-ids.js";
+
+function trimMaybeString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function resolveMatrixRoomTargetId(value: unknown): string | undefined {
+  const trimmed = trimMaybeString(value);
+  if (!trimmed) {
+    return undefined;
+  }
+  const target = resolveMatrixTargetIdentity(trimmed);
+  return target?.kind === "room" && target.id.startsWith("!") ? target.id : undefined;
+}
+
+function resolveMatrixSessionAccountId(value: unknown): string | undefined {
+  const trimmed = trimMaybeString(value);
+  return trimmed ? normalizeAccountId(trimmed) : undefined;
+}
+
+function resolveMatrixStoredRoomId(params: {
+  deliveryTo?: unknown;
+  lastTo?: unknown;
+  originNativeChannelId?: unknown;
+  originTo?: unknown;
+}): string | undefined {
+  return (
+    resolveMatrixRoomTargetId(params.deliveryTo) ??
+    resolveMatrixRoomTargetId(params.lastTo) ??
+    resolveMatrixRoomTargetId(params.originNativeChannelId) ??
+    resolveMatrixRoomTargetId(params.originTo)
+  );
+}
+
+type MatrixStoredSessionEntryLike = {
+  deliveryContext?: {
+    channel?: unknown;
+    to?: unknown;
+    accountId?: unknown;
+  };
+  origin?: {
+    provider?: unknown;
+    from?: unknown;
+    to?: unknown;
+    nativeChannelId?: unknown;
+    nativeDirectUserId?: unknown;
+    accountId?: unknown;
+    chatType?: unknown;
+  };
+  lastChannel?: unknown;
+  lastTo?: unknown;
+  lastAccountId?: unknown;
+  chatType?: unknown;
+};
+
+export function resolveMatrixStoredSessionMeta(entry?: MatrixStoredSessionEntryLike): {
+  channel?: string;
+  accountId?: string;
+  roomId?: string;
+  directUserId?: string;
+} | null {
+  if (!entry) {
+    return null;
+  }
+  const channel =
+    trimMaybeString(entry.deliveryContext?.channel) ??
+    trimMaybeString(entry.lastChannel) ??
+    trimMaybeString(entry.origin?.provider);
+  const accountId =
+    resolveMatrixSessionAccountId(
+      entry.deliveryContext?.accountId ?? entry.lastAccountId ?? entry.origin?.accountId,
+    ) ?? undefined;
+  const roomId = resolveMatrixStoredRoomId({
+    deliveryTo: entry.deliveryContext?.to,
+    lastTo: entry.lastTo,
+    originNativeChannelId: entry.origin?.nativeChannelId,
+    originTo: entry.origin?.to,
+  });
+  const chatType =
+    trimMaybeString(entry.origin?.chatType) ?? trimMaybeString(entry.chatType) ?? undefined;
+  const directUserId =
+    chatType === "direct"
+      ? (trimMaybeString(entry.origin?.nativeDirectUserId) ??
+        resolveMatrixDirectUserId({
+          from: trimMaybeString(entry.origin?.from),
+          to:
+            (roomId ? `room:${roomId}` : undefined) ??
+            trimMaybeString(entry.deliveryContext?.to) ??
+            trimMaybeString(entry.lastTo) ??
+            trimMaybeString(entry.origin?.to),
+          chatType,
+        }))
+      : undefined;
+  if (!channel && !accountId && !roomId && !directUserId) {
+    return null;
+  }
+  return {
+    ...(channel ? { channel } : {}),
+    ...(accountId ? { accountId } : {}),
+    ...(roomId ? { roomId } : {}),
+    ...(directUserId ? { directUserId } : {}),
+  };
+}

package/src/matrix/startup-abort.ts

@@ -0,0 +1,44 @@
+export function createMatrixStartupAbortError(): Error {
+  const error = new Error("Matrix startup aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+export function throwIfMatrixStartupAborted(abortSignal?: AbortSignal): void {
+  if (abortSignal?.aborted === true) {
+    throw createMatrixStartupAbortError();
+  }
+}
+
+export function isMatrixStartupAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+export async function awaitMatrixStartupWithAbort<T>(
+  promise: Promise<T>,
+  abortSignal?: AbortSignal,
+): Promise<T> {
+  if (!abortSignal) {
+    return await promise;
+  }
+  if (abortSignal.aborted) {
+    throw createMatrixStartupAbortError();
+  }
+  return await new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      abortSignal.removeEventListener("abort", onAbort);
+      reject(createMatrixStartupAbortError());
+    };
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        abortSignal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        abortSignal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}

package/src/matrix/subagent-hooks.ts

@@ -0,0 +1,308 @@
+import { DEFAULT_ACCOUNT_ID } from "autobot/plugin-sdk/account-id";
+import {
+  getSessionBindingService,
+  type SessionBindingRecord,
+} from "autobot/plugin-sdk/conversation-binding-runtime";
+import {
+  formatThreadBindingDisabledError,
+  formatThreadBindingSpawnDisabledError,
+  resolveThreadBindingSpawnPolicy,
+} from "autobot/plugin-sdk/conversation-runtime";
+import type { AutoBotPluginApi } from "autobot/plugin-sdk/core";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { resolveMatrixTargetIdentity } from "./target-ids.js";
+import {
+  getMatrixThreadBindingManager,
+  listAllBindings,
+  listBindingsForAccount,
+  removeBindingRecord,
+  resolveBindingKey,
+} from "./thread-bindings-shared.js";
+
+type MatrixSubagentSpawningEvent = {
+  threadRequested: boolean;
+  requester?: {
+    channel?: string;
+    accountId?: string;
+    to?: string;
+    threadId?: string | number;
+  };
+  childSessionKey: string;
+  agentId: string;
+  label?: string;
+};
+
+type MatrixSubagentEndedEvent = {
+  targetSessionKey: string;
+  targetKind: string;
+  accountId?: string;
+  reason?: string;
+  sendFarewell?: boolean;
+};
+
+type MatrixSubagentDeliveryTargetEvent = {
+  childSessionKey: string;
+  requesterOrigin?: {
+    channel?: string;
+    accountId?: string;
+    to?: string;
+    threadId?: string | number;
+  };
+  expectsCompletionMessage: boolean;
+};
+
+type MatrixDeliveryOrigin = {
+  channel: "matrix";
+  accountId: string;
+  to: string;
+  threadId?: string;
+};
+
+type SpawningResult =
+  | {
+      status: "ok";
+      threadBindingReady?: boolean;
+      deliveryOrigin?: MatrixDeliveryOrigin;
+    }
+  | { status: "error"; error: string };
+
+type DeliveryTargetResult = {
+  origin: MatrixDeliveryOrigin;
+};
+
+function summarizeError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  return "error";
+}
+
+function resolveMatrixBindingThreadId(binding: SessionBindingRecord): string | undefined {
+  const { conversationId, parentConversationId } = binding.conversation;
+  return parentConversationId && parentConversationId !== conversationId
+    ? conversationId
+    : undefined;
+}
+
+function resolveMatrixBindingDeliveryOrigin(
+  binding: SessionBindingRecord,
+  fallbackAccountId: string,
+): MatrixDeliveryOrigin {
+  const boundRoomId =
+    binding.conversation.parentConversationId ?? binding.conversation.conversationId;
+  const threadId = resolveMatrixBindingThreadId(binding);
+  return {
+    channel: "matrix",
+    accountId: binding.conversation.accountId ?? fallbackAccountId,
+    to: `room:${boundRoomId}`,
+    ...(threadId ? { threadId } : {}),
+  };
+}
+
+export async function handleMatrixSubagentSpawning(
+  api: AutoBotPluginApi,
+  event: MatrixSubagentSpawningEvent,
+): Promise<SpawningResult | undefined> {
+  if (!event.threadRequested) {
+    return undefined;
+  }
+  const channel = event.requester?.channel?.trim().toLowerCase();
+  if (channel !== "matrix") {
+    return undefined;
+  }
+
+  // Normalize early so per-account config and manager lookup use the same id.
+  // Falls back to DEFAULT_ACCOUNT_ID so accounts.default.threadBindings.* is
+  // respected even when the requester omits accountId.
+  const accountId = normalizeOptionalString(event.requester?.accountId) || DEFAULT_ACCOUNT_ID;
+  const policy = resolveThreadBindingSpawnPolicy({
+    cfg: api.config,
+    channel: "matrix",
+    accountId,
+    kind: "subagent",
+  });
+
+  if (!policy.enabled) {
+    return {
+      status: "error",
+      error: formatThreadBindingDisabledError({
+        channel: policy.channel,
+        accountId: policy.accountId,
+        kind: "subagent",
+      }),
+    } satisfies SpawningResult;
+  }
+  if (!policy.spawnEnabled) {
+    return {
+      status: "error",
+      error: formatThreadBindingSpawnDisabledError({
+        channel: policy.channel,
+        accountId: policy.accountId,
+        kind: "subagent",
+      }),
+    };
+  }
+
+  // Resolve the raw Matrix room ID from the requester's `to` field
+  // (e.g. "room:!abc123:example.org" → "!abc123:example.org").
+  const rawTo = normalizeOptionalString(event.requester?.to) ?? "";
+  const matrixTarget = rawTo ? resolveMatrixTargetIdentity(rawTo) : null;
+  const roomId = matrixTarget?.kind === "room" ? matrixTarget.id : "";
+
+  if (!roomId) {
+    return {
+      status: "error",
+      error:
+        "Cannot create Matrix thread binding: no room target in spawn request (requester.to must be a Matrix room ID).",
+    };
+  }
+
+  const bindingService = getSessionBindingService();
+  const capabilities = bindingService.getCapabilities({ channel: "matrix", accountId });
+  if (!capabilities.adapterAvailable || !capabilities.bindSupported) {
+    return {
+      status: "error",
+      error: `No Matrix session binding adapter available for account "${accountId}". Is the Matrix channel running?`,
+    };
+  }
+  if (!capabilities.placements.includes("child")) {
+    return {
+      status: "error",
+      error: `Matrix session binding adapter for account "${accountId}" does not support child thread bindings.`,
+    };
+  }
+
+  try {
+    // placement="child" tells the Matrix SessionBindingAdapter to:
+    // 1. Send an intro message to the room, creating a new thread root event
+    // 2. Use the returned event ID as boundConversationId (the thread ID)
+    // 3. Register the binding record in the in-memory store and persist it
+    //
+    // We do NOT call setBindingRecord here — the adapter's bind() handles
+    // record creation, thread creation, and persistence atomically.
+    const binding = await bindingService.bind({
+      targetSessionKey: event.childSessionKey,
+      targetKind: "subagent",
+      conversation: {
+        channel: "matrix",
+        accountId,
+        conversationId: roomId,
+      },
+      placement: "child",
+      metadata: {
+        agentId: event.agentId?.trim() || undefined,
+        label: normalizeOptionalString(event.label) || undefined,
+        boundBy: "system",
+      },
+    });
+    return {
+      status: "ok",
+      threadBindingReady: true,
+      deliveryOrigin: resolveMatrixBindingDeliveryOrigin(binding, accountId),
+    } satisfies SpawningResult;
+  } catch (err) {
+    return {
+      status: "error",
+      error: `Matrix thread bind failed: ${summarizeError(err)}`,
+    };
+  }
+}
+
+export async function handleMatrixSubagentEnded(event: MatrixSubagentEndedEvent): Promise<void> {
+  const accountId = normalizeOptionalString(event.accountId) || undefined;
+  // Use the targeted account list when available; fall back to a full scan
+  // so bindings are cleaned up even when accountId is absent.
+  const candidates = accountId ? listBindingsForAccount(accountId) : listAllBindings();
+  const matching = candidates.filter(
+    (entry) => entry.targetSessionKey === event.targetSessionKey && entry.targetKind === "subagent",
+  );
+  const removedBindingKeys = new Set<string>();
+  if (event.sendFarewell) {
+    const bindingService = getSessionBindingService();
+    const reason = normalizeOptionalString(event.reason) || "subagent-ended";
+    for (const binding of matching) {
+      const bindingId = resolveBindingKey(binding);
+      const removed = await bindingService.unbind({ bindingId, reason });
+      if (removed.some((entry) => entry.bindingId === bindingId)) {
+        removedBindingKeys.add(bindingId);
+      }
+    }
+  }
+
+  const affectedAccountIds = new Set<string>();
+  for (const binding of matching) {
+    if (removedBindingKeys.has(resolveBindingKey(binding))) {
+      continue;
+    }
+    if (removeBindingRecord(binding)) {
+      affectedAccountIds.add(binding.accountId);
+    }
+  }
+  // Flush each affected account's manager so removals are persisted to disk.
+  for (const acctId of affectedAccountIds) {
+    const manager = getMatrixThreadBindingManager(acctId);
+    await manager?.persist();
+  }
+}
+
+export function handleMatrixSubagentDeliveryTarget(
+  event: MatrixSubagentDeliveryTargetEvent,
+): DeliveryTargetResult | undefined {
+  if (!event.expectsCompletionMessage) {
+    return undefined;
+  }
+  const requesterChannel = event.requesterOrigin?.channel?.trim().toLowerCase();
+  if (requesterChannel !== "matrix") {
+    return undefined;
+  }
+
+  const requesterAccountId = normalizeOptionalString(event.requesterOrigin?.accountId);
+  const requesterThreadId =
+    event.requesterOrigin?.threadId != null && event.requesterOrigin.threadId !== ""
+      ? String(event.requesterOrigin.threadId).trim()
+      : "";
+
+  // Search the targeted account when available; otherwise scan all accounts.
+  const candidates = requesterAccountId
+    ? listBindingsForAccount(requesterAccountId)
+    : listAllBindings();
+  const bindings = candidates.filter(
+    (entry) => entry.targetSessionKey === event.childSessionKey && entry.targetKind === "subagent",
+  );
+  if (bindings.length === 0) {
+    return undefined;
+  }
+
+  let binding: (typeof bindings)[number] | undefined;
+  if (requesterThreadId) {
+    binding = bindings.find(
+      (entry) =>
+        entry.conversationId === requesterThreadId &&
+        (!requesterAccountId || entry.accountId === requesterAccountId),
+    );
+  }
+  if (!binding && bindings.length === 1) {
+    binding = bindings[0];
+  }
+  if (!binding) {
+    return undefined;
+  }
+
+  const roomId = binding.parentConversationId ?? binding.conversationId;
+  const threadId =
+    binding.parentConversationId && binding.parentConversationId !== binding.conversationId
+      ? binding.conversationId
+      : undefined;
+
+  return {
+    origin: {
+      channel: "matrix",
+      accountId: binding.accountId,
+      to: `room:${roomId}`,
+      ...(threadId ? { threadId } : {}),
+    },
+  };
+}

package/src/matrix/sync-state.ts

@@ -0,0 +1,27 @@
+export type MatrixSyncState =
+  | "PREPARED"
+  | "SYNCING"
+  | "CATCHUP"
+  | "RECONNECTING"
+  | "ERROR"
+  | "STOPPED"
+  | (string & {});
+
+export function isMatrixReadySyncState(
+  state: MatrixSyncState | null | undefined,
+): state is "PREPARED" | "SYNCING" | "CATCHUP" {
+  return state === "PREPARED" || state === "SYNCING" || state === "CATCHUP";
+}
+
+export function isMatrixDisconnectedSyncState(
+  state: MatrixSyncState | null | undefined,
+): state is "RECONNECTING" | "ERROR" | "STOPPED" {
+  return state === "RECONNECTING" || state === "ERROR" || state === "STOPPED";
+}
+
+export function isMatrixTerminalSyncState(
+  state: MatrixSyncState | null | undefined,
+): state is "STOPPED" {
+  // matrix-js-sdk can recover from ERROR to PREPARED during initial sync.
+  return state === "STOPPED";
+}

package/src/matrix/target-ids.ts

@@ -0,0 +1,79 @@
+import { normalizeLowercaseStringOrEmpty } from "autobot/plugin-sdk/string-coerce-runtime";
+
+type MatrixTarget = { kind: "room"; id: string } | { kind: "user"; id: string };
+const MATRIX_PREFIX = "matrix:";
+const ROOM_PREFIX = "room:";
+const CHANNEL_PREFIX = "channel:";
+const USER_PREFIX = "user:";
+
+function stripKnownPrefixes(raw: string, prefixes: readonly string[]): string {
+  let normalized = raw.trim();
+  while (normalized) {
+    const lowered = normalizeLowercaseStringOrEmpty(normalized);
+    const matched = prefixes.find((prefix) => lowered.startsWith(prefix));
+    if (!matched) {
+      return normalized;
+    }
+    normalized = normalized.slice(matched.length).trim();
+  }
+  return normalized;
+}
+
+export function resolveMatrixTargetIdentity(raw: string): MatrixTarget | null {
+  const normalized = stripKnownPrefixes(raw, [MATRIX_PREFIX]);
+  if (!normalized) {
+    return null;
+  }
+  const lowered = normalizeLowercaseStringOrEmpty(normalized);
+  if (lowered.startsWith(USER_PREFIX)) {
+    const id = normalized.slice(USER_PREFIX.length).trim();
+    return id ? { kind: "user", id } : null;
+  }
+  if (lowered.startsWith(ROOM_PREFIX)) {
+    const id = normalized.slice(ROOM_PREFIX.length).trim();
+    return id ? { kind: "room", id } : null;
+  }
+  if (lowered.startsWith(CHANNEL_PREFIX)) {
+    const id = normalized.slice(CHANNEL_PREFIX.length).trim();
+    return id ? { kind: "room", id } : null;
+  }
+  if (isMatrixQualifiedUserId(normalized)) {
+    return { kind: "user", id: normalized };
+  }
+  return { kind: "room", id: normalized };
+}
+
+export function isMatrixQualifiedUserId(raw: string): boolean {
+  const trimmed = raw.trim();
+  return trimmed.startsWith("@") && trimmed.includes(":");
+}
+
+export function normalizeMatrixResolvableTarget(raw: string): string {
+  return stripKnownPrefixes(raw, [MATRIX_PREFIX, ROOM_PREFIX, CHANNEL_PREFIX]);
+}
+
+export function normalizeMatrixMessagingTarget(raw: string): string | undefined {
+  const normalized = stripKnownPrefixes(raw, [
+    MATRIX_PREFIX,
+    ROOM_PREFIX,
+    CHANNEL_PREFIX,
+    USER_PREFIX,
+  ]);
+  return normalized || undefined;
+}
+
+export function resolveMatrixDirectUserId(params: {
+  from?: string;
+  to?: string;
+  chatType?: string;
+}): string | undefined {
+  if (params.chatType !== "direct") {
+    return undefined;
+  }
+  const roomId = normalizeMatrixResolvableTarget(params.to ?? "");
+  if (!roomId.startsWith("!")) {
+    return undefined;
+  }
+  const userId = stripKnownPrefixes(params.from ?? "", [MATRIX_PREFIX, USER_PREFIX]);
+  return isMatrixQualifiedUserId(userId) ? userId : undefined;
+}