@gakr-gakr/matrix 0.1.0

package/src/outbound.ts

@@ -0,0 +1,248 @@
+import {
+  renderMessagePresentationFallbackText,
+  type MessagePresentation,
+} from "autobot/plugin-sdk/interactive-runtime";
+import { createReplyToFanout } from "autobot/plugin-sdk/outbound-runtime";
+import { resolvePayloadMediaUrls } from "autobot/plugin-sdk/reply-payload";
+import type { ReplyPayload } from "autobot/plugin-sdk/reply-runtime";
+import { sendMessageMatrix, sendPollMatrix } from "./matrix/send.js";
+import type { MatrixExtraContentFields } from "./matrix/send/types.js";
+import {
+  chunkTextForOutbound,
+  resolveOutboundSendDep,
+  type ChannelOutboundAdapter,
+} from "./runtime-api.js";
+
+const MATRIX_AUTOBOT_PRESENTATION_KEY = "com.autobot.presentation" as const;
+const MATRIX_AUTOBOT_PRESENTATION_TYPE = "message.presentation" as const;
+const MATRIX_EMPTY_PRESENTATION_FALLBACK_TEXT = "---";
+
+type MatrixChannelData = {
+  extraContent?: MatrixExtraContentFields;
+};
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function resolveMatrixChannelData(payload: ReplyPayload): MatrixChannelData {
+  const raw = toRecord(payload.channelData)?.matrix;
+  return (toRecord(raw) as MatrixChannelData | undefined) ?? {};
+}
+
+function buildMatrixPresentationContent(presentation: MessagePresentation) {
+  return {
+    ...presentation,
+    version: 1,
+    type: MATRIX_AUTOBOT_PRESENTATION_TYPE,
+  };
+}
+
+function resolveMatrixPresentationContent(
+  payload: ReplyPayload,
+): Record<string, unknown> | undefined {
+  const extraContent = toRecord(resolveMatrixChannelData(payload).extraContent);
+  const presentation = toRecord(extraContent?.[MATRIX_AUTOBOT_PRESENTATION_KEY]);
+  if (
+    !presentation ||
+    presentation.version !== 1 ||
+    presentation.type !== MATRIX_AUTOBOT_PRESENTATION_TYPE
+  ) {
+    return undefined;
+  }
+  return presentation;
+}
+
+function renderMatrixPresentationPayload(params: {
+  payload: ReplyPayload;
+  presentation: MessagePresentation;
+}): ReplyPayload {
+  const matrixData = resolveMatrixChannelData(params.payload);
+  const fallbackText = renderMessagePresentationFallbackText({
+    text: params.payload.text,
+    presentation: params.presentation,
+    emptyFallback: MATRIX_EMPTY_PRESENTATION_FALLBACK_TEXT,
+  });
+  return {
+    ...params.payload,
+    text: fallbackText,
+    channelData: {
+      ...params.payload.channelData,
+      matrix: {
+        ...matrixData,
+        extraContent: {
+          [MATRIX_AUTOBOT_PRESENTATION_KEY]: buildMatrixPresentationContent(params.presentation),
+        },
+      },
+    },
+  };
+}
+
+function resolveMatrixPayloadText(payload: ReplyPayload): string {
+  const text = payload.text ?? "";
+  if (text.trim() || !resolveMatrixPresentationContent(payload)) {
+    return text;
+  }
+  return MATRIX_EMPTY_PRESENTATION_FALLBACK_TEXT;
+}
+
+function resolveMatrixExtraContent(payload: ReplyPayload): MatrixExtraContentFields | undefined {
+  const presentation = resolveMatrixPresentationContent(payload);
+  return presentation ? { [MATRIX_AUTOBOT_PRESENTATION_KEY]: presentation } : undefined;
+}
+
+export const matrixOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: chunkTextForOutbound,
+  chunkerMode: "markdown",
+  textChunkLimit: 4000,
+  presentationCapabilities: {
+    supported: true,
+    buttons: true,
+    selects: true,
+    context: true,
+    divider: true,
+    limits: {
+      text: {
+        markdownDialect: "markdown",
+        supportsEdit: true,
+      },
+    },
+  },
+  renderPresentation: ({ payload, presentation }) =>
+    renderMatrixPresentationPayload({ payload, presentation }),
+  sendPayload: async ({
+    cfg,
+    to,
+    payload,
+    mediaLocalRoots,
+    mediaReadFile,
+    mediaAccess,
+    deps,
+    replyToId,
+    replyToIdSource,
+    replyToMode,
+    threadId,
+    accountId,
+    audioAsVoice,
+  }) => {
+    const send =
+      resolveOutboundSendDep<typeof sendMessageMatrix>(deps, "matrix") ?? sendMessageMatrix;
+    const resolvedThreadId =
+      threadId !== undefined && threadId !== null ? String(threadId) : undefined;
+    const resolveReplyToId = createReplyToFanout({
+      ...(replyToId != null ? { replyToId } : {}),
+      ...(replyToIdSource !== undefined ? { replyToIdSource } : {}),
+      ...(replyToMode !== undefined ? { replyToMode } : {}),
+    });
+    const urls = resolvePayloadMediaUrls(payload);
+    const payloadText = resolveMatrixPayloadText(payload);
+    if (urls.length > 0) {
+      let lastResult: Awaited<ReturnType<typeof send>> | undefined;
+      for (let i = 0; i < urls.length; i++) {
+        const isFirst = i === 0;
+        lastResult = await send(to, isFirst ? payloadText : "", {
+          cfg,
+          mediaUrl: urls[i],
+          mediaAccess,
+          mediaLocalRoots,
+          mediaReadFile,
+          replyToId: resolveReplyToId(),
+          threadId: resolvedThreadId,
+          accountId: accountId ?? undefined,
+          audioAsVoice: payload.audioAsVoice ?? audioAsVoice,
+          extraContent: isFirst ? resolveMatrixExtraContent(payload) : undefined,
+        });
+      }
+      return {
+        channel: "matrix",
+        messageId: lastResult!.messageId,
+        roomId: lastResult!.roomId,
+      };
+    }
+    const result = await send(to, payloadText, {
+      cfg,
+      mediaUrl: payload.mediaUrl,
+      mediaAccess,
+      mediaLocalRoots,
+      mediaReadFile,
+      replyToId: resolveReplyToId(),
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+      audioAsVoice: payload.audioAsVoice ?? audioAsVoice,
+      extraContent: resolveMatrixExtraContent(payload),
+    });
+    return {
+      channel: "matrix",
+      messageId: result.messageId,
+      roomId: result.roomId,
+    };
+  },
+  sendText: async ({ cfg, to, text, deps, replyToId, threadId, accountId, audioAsVoice }) => {
+    const send =
+      resolveOutboundSendDep<typeof sendMessageMatrix>(deps, "matrix") ?? sendMessageMatrix;
+    const resolvedThreadId =
+      threadId !== undefined && threadId !== null ? String(threadId) : undefined;
+    const result = await send(to, text, {
+      cfg,
+      replyToId: replyToId ?? undefined,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+      audioAsVoice,
+    });
+    return {
+      channel: "matrix",
+      messageId: result.messageId,
+      roomId: result.roomId,
+    };
+  },
+  sendMedia: async ({
+    cfg,
+    to,
+    text,
+    mediaUrl,
+    mediaLocalRoots,
+    mediaReadFile,
+    deps,
+    replyToId,
+    threadId,
+    accountId,
+    audioAsVoice,
+  }) => {
+    const send =
+      resolveOutboundSendDep<typeof sendMessageMatrix>(deps, "matrix") ?? sendMessageMatrix;
+    const resolvedThreadId =
+      threadId !== undefined && threadId !== null ? String(threadId) : undefined;
+    const result = await send(to, text, {
+      cfg,
+      mediaUrl,
+      mediaLocalRoots,
+      mediaReadFile,
+      replyToId: replyToId ?? undefined,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+      audioAsVoice,
+    });
+    return {
+      channel: "matrix",
+      messageId: result.messageId,
+      roomId: result.roomId,
+    };
+  },
+  sendPoll: async ({ cfg, to, poll, threadId, accountId }) => {
+    const resolvedThreadId = threadId !== undefined && threadId !== null ? threadId : undefined;
+    const result = await sendPollMatrix(to, poll, {
+      cfg,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+    });
+    return {
+      channel: "matrix",
+      messageId: result.eventId,
+      roomId: result.roomId,
+      pollId: result.eventId,
+    };
+  },
+};

package/src/plugin-entry.runtime.js

@@ -0,0 +1,115 @@
+// Thin ESM wrapper so native dynamic import() resolves in source-checkout mode
+// while packaged dist builds resolve a distinct runtime entry that cannot loop
+// back into this wrapper through the stable root runtime alias.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const PLUGIN_ID = "matrix";
+const PLUGIN_ENTRY_RUNTIME_BASENAME = "plugin-entry.handlers.runtime";
+const NATIVE_RUNTIME_EXTENSIONS = [".js", ".mjs", ".cjs"];
+
+function readPackageJson(packageRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function normalizeLowercaseStringOrEmpty(value) {
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+
+function hasTrustedAutoBotRootIndicator(packageRoot, packageJson) {
+  const packageExports = packageJson?.exports ?? {};
+  if (!Object.prototype.hasOwnProperty.call(packageExports, "./plugin-sdk")) {
+    return false;
+  }
+  const hasCliEntryExport = Object.prototype.hasOwnProperty.call(packageExports, "./cli-entry");
+  const hasAutoBotBin =
+    (typeof packageJson?.bin === "string" &&
+      normalizeLowercaseStringOrEmpty(packageJson.bin).includes("autobot")) ||
+    (typeof packageJson?.bin === "object" &&
+      packageJson.bin !== null &&
+      typeof packageJson.bin.autobot === "string");
+  const hasAutoBotEntrypoint = fs.existsSync(path.join(packageRoot, "autobot.mjs"));
+  return hasCliEntryExport || hasAutoBotBin || hasAutoBotEntrypoint;
+}
+
+function findAutoBotPackageRoot(startDir) {
+  let cursor = path.resolve(startDir);
+  for (let i = 0; i < 12; i += 1) {
+    const pkg = readPackageJson(cursor);
+    if (pkg?.name === "autobot" && hasTrustedAutoBotRootIndicator(cursor, pkg)) {
+      return { packageRoot: cursor, packageJson: pkg };
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+  return null;
+}
+
+function resolveExistingFile(basePath, extensions) {
+  for (const ext of extensions) {
+    const candidate = `${basePath}${ext}`;
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function resolveBundledPluginRuntimeModulePath(moduleUrl, params) {
+  const modulePath = fileURLToPath(moduleUrl);
+  const moduleDir = path.dirname(modulePath);
+  const localCandidates = [
+    path.join(moduleDir, "..", params.runtimeBasename),
+    path.join(moduleDir, "extensions", params.pluginId, params.runtimeBasename),
+  ];
+
+  for (const candidate of localCandidates) {
+    const resolved = resolveExistingFile(candidate, NATIVE_RUNTIME_EXTENSIONS);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  const location = findAutoBotPackageRoot(moduleDir);
+  if (location) {
+    const { packageRoot } = location;
+    const packageCandidates = [
+      path.join(packageRoot, "extensions", params.pluginId, params.runtimeBasename),
+      path.join(packageRoot, "dist", "extensions", params.pluginId, params.runtimeBasename),
+    ];
+
+    for (const candidate of packageCandidates) {
+      const resolved = resolveExistingFile(candidate, NATIVE_RUNTIME_EXTENSIONS);
+      if (resolved) {
+        return resolved;
+      }
+    }
+  }
+
+  throw new Error(
+    `Cannot resolve ${params.pluginId} plugin runtime module ${params.runtimeBasename} from ${modulePath}`,
+  );
+}
+
+async function loadRuntimeModule(modulePath) {
+  return import(pathToFileURL(modulePath).href);
+}
+
+const mod = await loadRuntimeModule(
+  resolveBundledPluginRuntimeModulePath(import.meta.url, {
+    pluginId: PLUGIN_ID,
+    runtimeBasename: PLUGIN_ENTRY_RUNTIME_BASENAME,
+  }),
+);
+export const ensureMatrixCryptoRuntime = mod.ensureMatrixCryptoRuntime;
+export const handleVerifyRecoveryKey = mod.handleVerifyRecoveryKey;
+export const handleVerificationBootstrap = mod.handleVerificationBootstrap;
+export const handleVerificationStatus = mod.handleVerificationStatus;

package/src/plugin-entry.runtime.ts

@@ -0,0 +1,70 @@
+import type { GatewayRequestHandlerOptions } from "autobot/plugin-sdk/gateway-runtime";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { formatMatrixErrorMessage } from "./matrix/errors.js";
+
+type MatrixVerificationRuntime = typeof import("./matrix/actions/verification.js");
+
+let matrixVerificationRuntimePromise: Promise<MatrixVerificationRuntime> | undefined;
+
+function loadMatrixVerificationRuntime(): Promise<MatrixVerificationRuntime> {
+  matrixVerificationRuntimePromise ??= import("./matrix/actions/verification.js");
+  return matrixVerificationRuntimePromise;
+}
+
+function sendError(respond: (ok: boolean, payload?: unknown) => void, err: unknown) {
+  respond(false, { error: formatMatrixErrorMessage(err) });
+}
+
+export async function handleVerifyRecoveryKey({
+  params,
+  respond,
+}: GatewayRequestHandlerOptions): Promise<void> {
+  try {
+    const { verifyMatrixRecoveryKey } = await loadMatrixVerificationRuntime();
+    const key = normalizeOptionalString(params?.key);
+    if (!key) {
+      respond(false, { error: "key required" });
+      return;
+    }
+    const accountId = normalizeOptionalString(params?.accountId);
+    const result = await verifyMatrixRecoveryKey(key, { accountId });
+    respond(result.success, result);
+  } catch (err) {
+    sendError(respond, err);
+  }
+}
+
+export async function handleVerificationBootstrap({
+  params,
+  respond,
+}: GatewayRequestHandlerOptions): Promise<void> {
+  try {
+    const { bootstrapMatrixVerification } = await loadMatrixVerificationRuntime();
+    const accountId = normalizeOptionalString(params?.accountId);
+    const recoveryKey = typeof params?.recoveryKey === "string" ? params.recoveryKey : undefined;
+    const forceResetCrossSigning = params?.forceResetCrossSigning === true;
+    const result = await bootstrapMatrixVerification({
+      accountId,
+      recoveryKey,
+      forceResetCrossSigning,
+    });
+    respond(result.success, result);
+  } catch (err) {
+    sendError(respond, err);
+  }
+}
+
+export async function handleVerificationStatus({
+  params,
+  respond,
+}: GatewayRequestHandlerOptions): Promise<void> {
+  try {
+    const { getMatrixVerificationStatus } = await loadMatrixVerificationRuntime();
+    const accountId = normalizeOptionalString(params?.accountId);
+    const includeRecoveryKey = params?.includeRecoveryKey === true;
+    const status = await getMatrixVerificationStatus({ accountId, includeRecoveryKey });
+    respond(true, status);
+  } catch (err) {
+    sendError(respond, err);
+  }
+}

package/src/profile-update.ts

@@ -0,0 +1,71 @@
+import { normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { updateMatrixOwnProfile } from "./matrix/actions/profile.js";
+import { updateMatrixAccountConfig, resolveMatrixConfigPath } from "./matrix/config-update.js";
+import { getMatrixRuntime } from "./runtime.js";
+import type { CoreConfig } from "./types.js";
+
+export type MatrixProfileUpdateResult = {
+  accountId: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  profile: {
+    displayNameUpdated: boolean;
+    avatarUpdated: boolean;
+    resolvedAvatarUrl: string | null;
+    uploadedAvatarSource: "http" | "path" | null;
+    convertedAvatarFromHttp: boolean;
+  };
+  configPath: string;
+};
+
+export async function applyMatrixProfileUpdate(params: {
+  cfg?: CoreConfig;
+  account?: string;
+  displayName?: string;
+  avatarUrl?: string;
+  avatarPath?: string;
+  mediaLocalRoots?: readonly string[];
+}): Promise<MatrixProfileUpdateResult> {
+  const runtime = getMatrixRuntime();
+  const persistedCfg = runtime.config.current() as CoreConfig;
+  const accountId = normalizeAccountId(params.account);
+  const displayName = params.displayName?.trim() || null;
+  const avatarUrl = params.avatarUrl?.trim() || null;
+  const avatarPath = params.avatarPath?.trim() || null;
+  if (!displayName && !avatarUrl && !avatarPath) {
+    throw new Error("Provide name/displayName and/or avatarUrl/avatarPath.");
+  }
+
+  const synced = await updateMatrixOwnProfile({
+    cfg: params.cfg,
+    accountId,
+    displayName: displayName ?? undefined,
+    avatarUrl: avatarUrl ?? undefined,
+    avatarPath: avatarPath ?? undefined,
+    mediaLocalRoots: params.mediaLocalRoots,
+  });
+  const persistedAvatarUrl =
+    synced.uploadedAvatarSource && synced.resolvedAvatarUrl ? synced.resolvedAvatarUrl : avatarUrl;
+  const updated = updateMatrixAccountConfig(persistedCfg, accountId, {
+    name: displayName ?? undefined,
+    avatarUrl: persistedAvatarUrl ?? undefined,
+  });
+  await runtime.config.replaceConfigFile({
+    nextConfig: updated as never,
+    afterWrite: { mode: "auto" },
+  });
+
+  return {
+    accountId,
+    displayName,
+    avatarUrl: persistedAvatarUrl ?? null,
+    profile: {
+      displayNameUpdated: synced.displayNameUpdated,
+      avatarUpdated: synced.avatarUpdated,
+      resolvedAvatarUrl: synced.resolvedAvatarUrl,
+      uploadedAvatarSource: synced.uploadedAvatarSource,
+      convertedAvatarFromHttp: synced.convertedAvatarFromHttp,
+    },
+    configPath: resolveMatrixConfigPath(updated, accountId),
+  };
+}

package/src/record-shared.ts

@@ -0,0 +1,3 @@
+import { isRecord } from "autobot/plugin-sdk/string-coerce-runtime";
+
+export { isRecord };

package/src/resolve-targets.ts

@@ -0,0 +1,175 @@
+import { normalizeOptionalLowercaseString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
+import { isMatrixQualifiedUserId, normalizeMatrixMessagingTarget } from "./matrix/target-ids.js";
+import type {
+  ChannelDirectoryEntry,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  RuntimeEnv,
+} from "./runtime-api.js";
+
+function normalizeLookupQuery(query: string): string {
+  return normalizeOptionalLowercaseString(query) ?? "";
+}
+
+function findExactDirectoryMatches(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): ChannelDirectoryEntry[] {
+  const normalized = normalizeLookupQuery(query);
+  if (!normalized) {
+    return [];
+  }
+  return matches.filter((match) => {
+    const id = normalizeOptionalLowercaseString(match.id);
+    const name = normalizeOptionalLowercaseString(match.name);
+    const handle = normalizeOptionalLowercaseString(match.handle);
+    return normalized === id || normalized === name || normalized === handle;
+  });
+}
+
+function pickBestGroupMatch(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): { best?: ChannelDirectoryEntry; note?: string } {
+  if (matches.length === 0) {
+    return {};
+  }
+  const exact = findExactDirectoryMatches(matches, query);
+  if (exact.length > 1) {
+    return { best: exact[0], note: "multiple exact matches; chose first" };
+  }
+  if (exact.length === 1) {
+    return { best: exact[0] };
+  }
+  return {
+    best: matches[0],
+    note: matches.length > 1 ? "multiple matches; chose first" : undefined,
+  };
+}
+
+function pickBestUserMatch(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): ChannelDirectoryEntry | undefined {
+  if (matches.length === 0) {
+    return undefined;
+  }
+  const exact = findExactDirectoryMatches(matches, query);
+  if (exact.length === 1) {
+    return exact[0];
+  }
+  return undefined;
+}
+
+function describeUserMatchFailure(matches: ChannelDirectoryEntry[], query: string): string {
+  if (matches.length === 0) {
+    return "no matches";
+  }
+  const normalized = normalizeLookupQuery(query);
+  if (!normalized) {
+    return "empty input";
+  }
+  const exact = findExactDirectoryMatches(matches, normalized);
+  if (exact.length === 0) {
+    return "no exact match; use full Matrix ID";
+  }
+  if (exact.length > 1) {
+    return "multiple exact matches; use full Matrix ID";
+  }
+  return "no exact match; use full Matrix ID";
+}
+
+async function readCachedMatches(
+  cache: Map<string, ChannelDirectoryEntry[]>,
+  query: string,
+  lookup: (query: string) => Promise<ChannelDirectoryEntry[]>,
+): Promise<ChannelDirectoryEntry[]> {
+  const key = normalizeLookupQuery(query);
+  if (!key) {
+    return [];
+  }
+  const cached = cache.get(key);
+  if (cached) {
+    return cached;
+  }
+  const matches = await lookup(query.trim());
+  cache.set(key, matches);
+  return matches;
+}
+
+export async function resolveMatrixTargets(params: {
+  cfg: unknown;
+  accountId?: string | null;
+  inputs: string[];
+  kind: ChannelResolveKind;
+  runtime?: RuntimeEnv;
+}): Promise<ChannelResolveResult[]> {
+  const results: ChannelResolveResult[] = [];
+  const userLookupCache = new Map<string, ChannelDirectoryEntry[]>();
+  const groupLookupCache = new Map<string, ChannelDirectoryEntry[]>();
+
+  for (const input of params.inputs) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+      results.push({ input, resolved: false, note: "empty input" });
+      continue;
+    }
+    if (params.kind === "user") {
+      const normalizedTarget = normalizeMatrixMessagingTarget(trimmed);
+      if (normalizedTarget && isMatrixQualifiedUserId(normalizedTarget)) {
+        results.push({ input, resolved: true, id: normalizedTarget });
+        continue;
+      }
+      try {
+        const matches = await readCachedMatches(userLookupCache, trimmed, (query) =>
+          listMatrixDirectoryPeersLive({
+            cfg: params.cfg,
+            accountId: params.accountId,
+            query,
+            limit: 5,
+          }),
+        );
+        const best = pickBestUserMatch(matches, trimmed);
+        results.push({
+          input,
+          resolved: Boolean(best?.id),
+          id: best?.id,
+          name: best?.name,
+          note: best ? undefined : describeUserMatchFailure(matches, trimmed),
+        });
+      } catch (err) {
+        params.runtime?.error?.(`matrix resolve failed: ${String(err)}`);
+        results.push({ input, resolved: false, note: "lookup failed" });
+      }
+      continue;
+    }
+    const normalizedTarget = normalizeMatrixMessagingTarget(trimmed);
+    if (normalizedTarget?.startsWith("!")) {
+      results.push({ input, resolved: true, id: normalizedTarget });
+      continue;
+    }
+    try {
+      const matches = await readCachedMatches(groupLookupCache, trimmed, (query) =>
+        listMatrixDirectoryGroupsLive({
+          cfg: params.cfg,
+          accountId: params.accountId,
+          query,
+          limit: 5,
+        }),
+      );
+      const { best, note } = pickBestGroupMatch(matches, trimmed);
+      results.push({
+        input,
+        resolved: Boolean(best?.id),
+        id: best?.id,
+        name: best?.name,
+        note,
+      });
+    } catch (err) {
+      params.runtime?.error?.(`matrix resolve failed: ${String(err)}`);
+      results.push({ input, resolved: false, note: "lookup failed" });
+    }
+  }
+  return results;
+}

package/src/resolver.runtime.ts

@@ -0,0 +1,5 @@
+import { resolveMatrixTargets } from "./resolve-targets.js";
+
+export const matrixResolverRuntime = {
+  resolveMatrixTargets,
+};