@gakr-gakr/matrix 0.1.0

package/src/resolver.ts

@@ -0,0 +1,21 @@
+import type { ChannelPlugin } from "autobot/plugin-sdk/channel-core";
+import { createLazyRuntimeNamedExport } from "autobot/plugin-sdk/lazy-runtime";
+import type { ResolvedMatrixAccount } from "./matrix/accounts.js";
+
+const loadMatrixChannelRuntime = createLazyRuntimeNamedExport(
+  () => import("./resolver.runtime.js"),
+  "matrixResolverRuntime",
+);
+
+type MatrixResolver = NonNullable<ChannelPlugin<ResolvedMatrixAccount>["resolver"]>;
+
+export const matrixResolverAdapter: MatrixResolver = {
+  resolveTargets: async ({ cfg, accountId, inputs, kind, runtime }) =>
+    (await loadMatrixChannelRuntime()).resolveMatrixTargets({
+      cfg,
+      accountId,
+      inputs,
+      kind,
+      runtime,
+    }),
+};

package/src/runtime-api.ts

@@ -0,0 +1,106 @@
+export {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  normalizeOptionalAccountId,
+} from "autobot/plugin-sdk/account-id";
+export {
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringArrayParam,
+  readStringParam,
+  ToolAuthorizationError,
+} from "autobot/plugin-sdk/channel-actions";
+export { buildChannelConfigSchema } from "autobot/plugin-sdk/channel-config-primitives";
+export type { ChannelPlugin } from "autobot/plugin-sdk/channel-core";
+export type {
+  BaseProbeResult,
+  ChannelDirectoryEntry,
+  ChannelGroupContext,
+  ChannelMessageActionAdapter,
+  ChannelMessageActionContext,
+  ChannelMessageActionName,
+  ChannelMessageToolDiscovery,
+  ChannelOutboundAdapter,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  ChannelToolSend,
+} from "autobot/plugin-sdk/channel-contract";
+export {
+  formatLocationText,
+  toLocationContext,
+  type NormalizedLocation,
+} from "autobot/plugin-sdk/channel-location";
+export { logInboundDrop, logTypingFailure } from "autobot/plugin-sdk/channel-logging";
+export { resolveAckReaction } from "autobot/plugin-sdk/channel-feedback";
+export type { ChannelSetupInput } from "autobot/plugin-sdk/setup";
+export type {
+  AutoBotConfig,
+  ContextVisibilityMode,
+  DmPolicy,
+  GroupPolicy,
+} from "autobot/plugin-sdk/config-contracts";
+export type { GroupToolPolicyConfig } from "autobot/plugin-sdk/config-contracts";
+export type { WizardPrompter } from "autobot/plugin-sdk/setup";
+export type { SecretInput } from "autobot/plugin-sdk/secret-input";
+export {
+  GROUP_POLICY_BLOCKED_LABEL,
+  resolveAllowlistProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
+  warnMissingProviderGroupPolicyFallbackOnce,
+} from "autobot/plugin-sdk/runtime-group-policy";
+export {
+  addWildcardAllowFrom,
+  formatDocsLink,
+  hasConfiguredSecretInput,
+  mergeAllowFromEntries,
+  moveSingleAccountChannelSectionToDefaultAccount,
+  promptAccountId,
+  promptChannelAccessConfig,
+  splitSetupEntries,
+} from "autobot/plugin-sdk/setup";
+export type { RuntimeEnv } from "autobot/plugin-sdk/runtime";
+export {
+  assertHttpUrlTargetsPrivateNetwork,
+  closeDispatcher,
+  createPinnedDispatcher,
+  isPrivateOrLoopbackHost,
+  resolvePinnedHostnameWithPolicy,
+  ssrfPolicyFromDangerouslyAllowPrivateNetwork,
+  ssrfPolicyFromAllowPrivateNetwork,
+  type LookupFn,
+  type SsrFPolicy,
+} from "autobot/plugin-sdk/ssrf-runtime";
+export { dispatchReplyFromConfigWithSettledDispatcher } from "autobot/plugin-sdk/inbound-reply-dispatch";
+export {
+  ensureConfiguredAcpBindingReady,
+  resolveConfiguredAcpBindingRecord,
+} from "autobot/plugin-sdk/acp-binding-runtime";
+export {
+  buildProbeChannelStatusSummary,
+  collectStatusIssuesFromLastError,
+  PAIRING_APPROVED_MESSAGE,
+} from "autobot/plugin-sdk/channel-status";
+export {
+  getSessionBindingService,
+  resolveThreadBindingIdleTimeoutMsForChannel,
+  resolveThreadBindingMaxAgeMsForChannel,
+} from "autobot/plugin-sdk/conversation-runtime";
+export { resolveOutboundSendDep } from "autobot/plugin-sdk/outbound-send-deps";
+export { resolveAgentIdFromSessionKey } from "autobot/plugin-sdk/routing";
+export { chunkTextForOutbound } from "autobot/plugin-sdk/text-chunking";
+export { createChannelMessageReplyPipeline } from "autobot/plugin-sdk/channel-message";
+export { loadOutboundMediaFromUrl } from "autobot/plugin-sdk/outbound-media";
+export { normalizePollInput, type PollInput } from "autobot/plugin-sdk/poll-runtime";
+export { writeJsonFileAtomically } from "autobot/plugin-sdk/json-store";
+export {
+  buildChannelKeyCandidates,
+  resolveChannelEntryMatch,
+} from "autobot/plugin-sdk/channel-targets";
+export { buildTimeoutAbortSignal } from "./matrix/sdk/timeout-abort-signal.js";
+export { formatZonedTimestamp } from "autobot/plugin-sdk/time-runtime";
+export type { PluginRuntime, RuntimeLogger } from "autobot/plugin-sdk/plugin-runtime";
+export type { ReplyPayload } from "autobot/plugin-sdk/reply-runtime";
+// resolveMatrixAccountStringValues already comes from the Matrix API barrel.
+// Re-exporting auth-precedence here makes TS source loaders define the export twice.

package/src/runtime.ts

@@ -0,0 +1,13 @@
+import { createPluginRuntimeStore } from "autobot/plugin-sdk/runtime-store";
+import type { PluginRuntime } from "./runtime-api.js";
+
+const {
+  setRuntime: setMatrixRuntime,
+  getRuntime: getMatrixRuntime,
+  tryGetRuntime: getOptionalMatrixRuntime,
+} = createPluginRuntimeStore<PluginRuntime>({
+  pluginId: "matrix",
+  errorMessage: "Matrix runtime not initialized",
+});
+
+export { getMatrixRuntime, getOptionalMatrixRuntime, setMatrixRuntime };

package/src/secret-contract.ts

@@ -0,0 +1,174 @@
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import {
+  collectSecretInputAssignment,
+  getChannelSurface,
+  hasConfiguredSecretInputValue,
+  hasOwnProperty,
+  normalizeSecretStringValue,
+  type ResolverContext,
+  type SecretDefaults,
+} from "autobot/plugin-sdk/channel-secret-basic-runtime";
+import { getMatrixScopedEnvVarNames } from "./env-vars.js";
+
+export const secretTargetRegistryEntries: import("autobot/plugin-sdk/channel-secret-basic-runtime").SecretTargetRegistryEntry[] =
+  [
+    {
+      id: "channels.matrix.accounts.*.accessToken",
+      targetType: "channels.matrix.accounts.*.accessToken",
+      configFile: "autobot.json",
+      pathPattern: "channels.matrix.accounts.*.accessToken",
+      secretShape: "secret_input",
+      expectedResolvedValue: "string",
+      includeInPlan: true,
+      includeInConfigure: true,
+      includeInAudit: true,
+    },
+    {
+      id: "channels.matrix.accounts.*.password",
+      targetType: "channels.matrix.accounts.*.password",
+      configFile: "autobot.json",
+      pathPattern: "channels.matrix.accounts.*.password",
+      secretShape: "secret_input",
+      expectedResolvedValue: "string",
+      includeInPlan: true,
+      includeInConfigure: true,
+      includeInAudit: true,
+    },
+    {
+      id: "channels.matrix.accessToken",
+      targetType: "channels.matrix.accessToken",
+      configFile: "autobot.json",
+      pathPattern: "channels.matrix.accessToken",
+      secretShape: "secret_input",
+      expectedResolvedValue: "string",
+      includeInPlan: true,
+      includeInConfigure: true,
+      includeInAudit: true,
+    },
+    {
+      id: "channels.matrix.password",
+      targetType: "channels.matrix.password",
+      configFile: "autobot.json",
+      pathPattern: "channels.matrix.password",
+      secretShape: "secret_input",
+      expectedResolvedValue: "string",
+      includeInPlan: true,
+      includeInConfigure: true,
+      includeInAudit: true,
+    },
+  ];
+
+export function collectRuntimeConfigAssignments(params: {
+  config: { channels?: Record<string, unknown> };
+  defaults?: SecretDefaults;
+  context: ResolverContext;
+}): void {
+  const resolved = getChannelSurface(params.config, "matrix");
+  if (!resolved) {
+    return;
+  }
+  const { channel: matrix, surface } = resolved;
+  const envAccessTokenConfigured =
+    normalizeSecretStringValue(params.context.env.MATRIX_ACCESS_TOKEN).length > 0;
+  const defaultScopedAccessTokenConfigured =
+    normalizeSecretStringValue(
+      params.context.env[getMatrixScopedEnvVarNames("default").accessToken],
+    ).length > 0;
+  const defaultAccountAccessTokenConfigured = surface.accounts.some(
+    ({ accountId, account }) =>
+      normalizeAccountId(accountId) === DEFAULT_ACCOUNT_ID &&
+      hasConfiguredSecretInputValue(account.accessToken, params.defaults),
+  );
+  const baseAccessTokenConfigured = hasConfiguredSecretInputValue(
+    matrix.accessToken,
+    params.defaults,
+  );
+  collectSecretInputAssignment({
+    value: matrix.accessToken,
+    path: "channels.matrix.accessToken",
+    expected: "string",
+    defaults: params.defaults,
+    context: params.context,
+    active: surface.channelEnabled,
+    inactiveReason: "Matrix channel is disabled.",
+    apply: (value) => {
+      matrix.accessToken = value;
+    },
+  });
+  collectSecretInputAssignment({
+    value: matrix.password,
+    path: "channels.matrix.password",
+    expected: "string",
+    defaults: params.defaults,
+    context: params.context,
+    active:
+      surface.channelEnabled &&
+      !(
+        baseAccessTokenConfigured ||
+        envAccessTokenConfigured ||
+        defaultScopedAccessTokenConfigured ||
+        defaultAccountAccessTokenConfigured
+      ),
+    inactiveReason:
+      "Matrix channel is disabled or access-token auth is configured for the default Matrix account.",
+    apply: (value) => {
+      matrix.password = value;
+    },
+  });
+  if (!surface.hasExplicitAccounts) {
+    return;
+  }
+  for (const { accountId, account, enabled } of surface.accounts) {
+    if (hasOwnProperty(account, "accessToken")) {
+      collectSecretInputAssignment({
+        value: account.accessToken,
+        path: `channels.matrix.accounts.${accountId}.accessToken`,
+        expected: "string",
+        defaults: params.defaults,
+        context: params.context,
+        active: enabled,
+        inactiveReason: "Matrix account is disabled.",
+        apply: (value) => {
+          account.accessToken = value;
+        },
+      });
+    }
+    if (!hasOwnProperty(account, "password")) {
+      continue;
+    }
+    const accountAccessTokenConfigured = hasConfiguredSecretInputValue(
+      account.accessToken,
+      params.defaults,
+    );
+    const scopedEnvAccessTokenConfigured =
+      normalizeSecretStringValue(
+        params.context.env[getMatrixScopedEnvVarNames(accountId).accessToken],
+      ).length > 0;
+    const inheritedDefaultAccountAccessTokenConfigured =
+      normalizeAccountId(accountId) === DEFAULT_ACCOUNT_ID &&
+      (baseAccessTokenConfigured || envAccessTokenConfigured);
+    collectSecretInputAssignment({
+      value: account.password,
+      path: `channels.matrix.accounts.${accountId}.password`,
+      expected: "string",
+      defaults: params.defaults,
+      context: params.context,
+      active:
+        enabled &&
+        !(
+          accountAccessTokenConfigured ||
+          scopedEnvAccessTokenConfigured ||
+          inheritedDefaultAccountAccessTokenConfigured
+        ),
+      inactiveReason: "Matrix account is disabled or this account has an accessToken configured.",
+      apply: (value) => {
+        account.password = value;
+      },
+    });
+  }
+}
+
+export const channelSecrets = {
+  secretTargetRegistryEntries,
+  collectRuntimeConfigAssignments,
+};

package/src/session-route.ts

@@ -0,0 +1,126 @@
+import { normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import {
+  buildChannelOutboundSessionRoute,
+  buildThreadAwareOutboundSessionRoute,
+  type ChannelOutboundSessionRouteParams,
+} from "autobot/plugin-sdk/channel-core";
+import { parseThreadSessionSuffix } from "autobot/plugin-sdk/routing";
+import {
+  loadSessionStore,
+  resolveSessionStoreEntry,
+  resolveStorePath,
+} from "autobot/plugin-sdk/session-store-runtime";
+import { resolveMatrixAccountConfig } from "./matrix/account-config.js";
+import { resolveDefaultMatrixAccountId } from "./matrix/accounts.js";
+import { resolveMatrixStoredSessionMeta } from "./matrix/session-store-metadata.js";
+import { resolveMatrixTargetIdentity } from "./matrix/target-ids.js";
+
+function resolveEffectiveMatrixAccountId(
+  params: Pick<ChannelOutboundSessionRouteParams, "cfg" | "accountId">,
+): string {
+  return normalizeAccountId(params.accountId ?? resolveDefaultMatrixAccountId(params.cfg));
+}
+
+function resolveMatrixDmSessionScope(params: {
+  cfg: ChannelOutboundSessionRouteParams["cfg"];
+  accountId: string;
+}): "per-user" | "per-room" {
+  return (
+    resolveMatrixAccountConfig({
+      cfg: params.cfg,
+      accountId: params.accountId,
+    }).dm?.sessionScope ?? "per-user"
+  );
+}
+
+function resolveMatrixCurrentDmRoomId(params: {
+  cfg: ChannelOutboundSessionRouteParams["cfg"];
+  agentId: string;
+  accountId: string;
+  currentSessionKey?: string;
+  targetUserId: string;
+}): string | undefined {
+  const sessionKey =
+    parseThreadSessionSuffix(params.currentSessionKey).baseSessionKey ??
+    params.currentSessionKey?.trim();
+  if (!sessionKey) {
+    return undefined;
+  }
+  try {
+    const storePath = resolveStorePath(params.cfg.session?.store, {
+      agentId: params.agentId,
+    });
+    const store = loadSessionStore(storePath);
+    const existing = resolveSessionStoreEntry({
+      store,
+      sessionKey,
+    }).existing;
+    const currentSession = resolveMatrixStoredSessionMeta(existing);
+    if (!currentSession) {
+      return undefined;
+    }
+    if (currentSession.accountId && currentSession.accountId !== params.accountId) {
+      return undefined;
+    }
+    if (!currentSession.directUserId || currentSession.directUserId !== params.targetUserId) {
+      return undefined;
+    }
+    return currentSession.roomId;
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveMatrixOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
+  const target =
+    resolveMatrixTargetIdentity(params.resolvedTarget?.to ?? params.target) ??
+    resolveMatrixTargetIdentity(params.target);
+  if (!target) {
+    return null;
+  }
+  const effectiveAccountId = resolveEffectiveMatrixAccountId(params);
+  const roomScopedDmId =
+    target.kind === "user" &&
+    resolveMatrixDmSessionScope({
+      cfg: params.cfg,
+      accountId: effectiveAccountId,
+    }) === "per-room"
+      ? resolveMatrixCurrentDmRoomId({
+          cfg: params.cfg,
+          agentId: params.agentId,
+          accountId: effectiveAccountId,
+          currentSessionKey: params.currentSessionKey,
+          targetUserId: target.id,
+        })
+      : undefined;
+  const peer =
+    roomScopedDmId !== undefined
+      ? { kind: "channel" as const, id: roomScopedDmId }
+      : {
+          kind: target.kind === "user" ? ("direct" as const) : ("channel" as const),
+          id: target.id,
+        };
+  const chatType = target.kind === "user" ? "direct" : "channel";
+  const from = target.kind === "user" ? `matrix:${target.id}` : `matrix:channel:${target.id}`;
+  const to = `room:${roomScopedDmId ?? target.id}`;
+
+  const baseRoute = buildChannelOutboundSessionRoute({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "matrix",
+    accountId: effectiveAccountId,
+    peer,
+    chatType,
+    from,
+    to,
+  });
+  return buildThreadAwareOutboundSessionRoute({
+    route: baseRoute,
+    replyToId: params.replyToId,
+    threadId: params.threadId,
+    currentSessionKey: params.currentSessionKey,
+    normalizeThreadId: (threadId) => threadId,
+    canRecoverCurrentThread: ({ route }) =>
+      route.peer.kind !== "direct" || (params.cfg.session?.dmScope ?? "main") !== "main",
+  });
+}

package/src/setup-bootstrap.ts

@@ -0,0 +1,102 @@
+import { hasExplicitMatrixAccountConfig } from "./matrix/account-config.js";
+import { resolveMatrixAccountConfig } from "./matrix/accounts.js";
+import { bootstrapMatrixVerification } from "./matrix/actions/verification.js";
+import { formatMatrixErrorMessage } from "./matrix/errors.js";
+import type { RuntimeEnv } from "./runtime-api.js";
+import type { CoreConfig } from "./types.js";
+
+export type MatrixSetupVerificationBootstrapResult = {
+  attempted: boolean;
+  success: boolean;
+  recoveryKeyCreatedAt: string | null;
+  backupVersion: string | null;
+  error?: string;
+};
+
+export async function maybeBootstrapNewEncryptedMatrixAccount(params: {
+  previousCfg: CoreConfig;
+  cfg: CoreConfig;
+  accountId: string;
+}): Promise<MatrixSetupVerificationBootstrapResult> {
+  const accountConfig = resolveMatrixAccountConfig({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  const previousAccountConfig = resolveMatrixAccountConfig({
+    cfg: params.previousCfg,
+    accountId: params.accountId,
+  });
+
+  if (
+    accountConfig.encryption !== true ||
+    (hasExplicitMatrixAccountConfig(params.previousCfg, params.accountId) &&
+      previousAccountConfig.encryption === true)
+  ) {
+    return {
+      attempted: false,
+      success: false,
+      recoveryKeyCreatedAt: null,
+      backupVersion: null,
+    };
+  }
+
+  try {
+    const bootstrap = await bootstrapMatrixVerification({
+      accountId: params.accountId,
+      cfg: params.cfg,
+    });
+    return {
+      attempted: true,
+      success: bootstrap.success,
+      recoveryKeyCreatedAt: bootstrap.verification.recoveryKeyCreatedAt,
+      backupVersion: bootstrap.verification.backupVersion,
+      ...(bootstrap.success
+        ? {}
+        : { error: bootstrap.error ?? "Matrix verification bootstrap failed" }),
+    };
+  } catch (err) {
+    return {
+      attempted: true,
+      success: false,
+      recoveryKeyCreatedAt: null,
+      backupVersion: null,
+      error: formatMatrixErrorMessage(err),
+    };
+  }
+}
+
+export async function runMatrixSetupBootstrapAfterConfigWrite(params: {
+  previousCfg: CoreConfig;
+  cfg: CoreConfig;
+  accountId: string;
+  runtime: RuntimeEnv;
+}): Promise<void> {
+  const nextAccountConfig = resolveMatrixAccountConfig({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  if (nextAccountConfig.encryption !== true) {
+    return;
+  }
+
+  const bootstrap = await maybeBootstrapNewEncryptedMatrixAccount({
+    previousCfg: params.previousCfg,
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  if (!bootstrap.attempted) {
+    return;
+  }
+  if (bootstrap.success) {
+    params.runtime.log(`Matrix verification bootstrap: complete for "${params.accountId}".`);
+    if (bootstrap.backupVersion) {
+      params.runtime.log(
+        `Matrix backup version for "${params.accountId}": ${bootstrap.backupVersion}`,
+      );
+    }
+    return;
+  }
+  params.runtime.error(
+    `Matrix verification bootstrap warning for "${params.accountId}": ${bootstrap.error ?? "unknown bootstrap failure"}`,
+  );
+}