@kodelyth/matrix 2026.5.42 → 2026.6.2

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

@@ -1,108 +0,0 @@
-import { normalizeAccountId } from "klaw/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

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

@@ -1,308 +0,0 @@
-import { DEFAULT_ACCOUNT_ID } from "klaw/plugin-sdk/account-id";
-import {
-  getSessionBindingService,
-  type SessionBindingRecord,
-} from "klaw/plugin-sdk/conversation-binding-runtime";
-import {
-  formatThreadBindingDisabledError,
-  formatThreadBindingSpawnDisabledError,
-  resolveThreadBindingSpawnPolicy,
-} from "klaw/plugin-sdk/conversation-runtime";
-import type { KlawPluginApi } from "klaw/plugin-sdk/core";
-import { normalizeOptionalString } from "klaw/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: KlawPluginApi,
-  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

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

@@ -1,79 +0,0 @@
-import { normalizeLowercaseStringOrEmpty } from "klaw/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;
-}