@gakr-gakr/discord 0.1.0

package/src/shared.ts

@@ -0,0 +1,197 @@
+import { describeAccountSnapshot } from "autobot/plugin-sdk/account-helpers";
+import { normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import { formatAllowFromLowercase } from "autobot/plugin-sdk/allow-from";
+import { adaptScopedAccountAccessor } from "autobot/plugin-sdk/channel-config-helpers";
+import { createScopedChannelConfigAdapter } from "autobot/plugin-sdk/channel-config-helpers";
+import type { ChannelDoctorAdapter } from "autobot/plugin-sdk/channel-contract";
+import { inspectDiscordAccount } from "./account-inspect.js";
+import {
+  isDiscordAccountEnabledForRuntime,
+  listDiscordAccountIds,
+  mergeDiscordAccountConfig,
+  resolveDefaultDiscordAccountId,
+  resolveDiscordAccount,
+  resolveDiscordAccountAllowFrom,
+  resolveDiscordAccountDisabledReason,
+  type ResolvedDiscordAccount,
+} from "./accounts.js";
+import {
+  getChatChannelMeta,
+  resolveConfiguredFromCredentialStatuses,
+  type ChannelPlugin,
+} from "./channel-api.js";
+import { DiscordChannelConfigSchema } from "./config-schema.js";
+import { normalizeCompatibilityConfig } from "./doctor-contract.js";
+import { DISCORD_LEGACY_CONFIG_RULES } from "./doctor-shared.js";
+import type { AutoBotConfig } from "./runtime-api.js";
+import {
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./secret-config-contract.js";
+import {
+  collectUnsupportedSecretRefConfigCandidates,
+  unsupportedSecretRefSurfacePatterns,
+} from "./security-contract.js";
+import { discordSecurityAdapter } from "./security.js";
+import { deriveLegacySessionChatType } from "./session-contract.js";
+
+const DISCORD_CHANNEL = "discord" as const;
+
+type DiscordDoctorModule = typeof import("./doctor.js");
+type DiscordConfigAccessorAccount = {
+  allowFrom: string[] | undefined;
+  defaultTo: string | undefined;
+};
+
+let discordDoctorModulePromise: Promise<DiscordDoctorModule> | undefined;
+
+async function loadDiscordDoctorModule(): Promise<DiscordDoctorModule> {
+  discordDoctorModulePromise ??= import("./doctor.js");
+  return await discordDoctorModulePromise;
+}
+
+const discordDoctor: ChannelDoctorAdapter = {
+  dmAllowFromMode: "topOnly",
+  groupModel: "route",
+  groupAllowFromFallbackToAllowFrom: false,
+  warnOnEmptyGroupSenderAllowlist: false,
+  legacyConfigRules: DISCORD_LEGACY_CONFIG_RULES,
+  normalizeCompatibilityConfig,
+  collectPreviewWarnings: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.collectPreviewWarnings?.(params) ?? [],
+  collectMutableAllowlistWarnings: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.collectMutableAllowlistWarnings?.(params) ?? [],
+  repairConfig: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.repairConfig?.(params) ?? {
+      config: params.cfg,
+      changes: [],
+    },
+};
+
+function resolveDiscordConfigAccessorAccount(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): DiscordConfigAccessorAccount {
+  const accountId = normalizeAccountId(
+    params.accountId ?? resolveDefaultDiscordAccountId(params.cfg),
+  );
+  const config = mergeDiscordAccountConfig(params.cfg, accountId);
+  return {
+    allowFrom: resolveDiscordAccountAllowFrom({ cfg: params.cfg, accountId }),
+    defaultTo: config.defaultTo,
+  };
+}
+
+export const discordConfigAdapter = createScopedChannelConfigAdapter<
+  ResolvedDiscordAccount,
+  DiscordConfigAccessorAccount
+>({
+  sectionKey: DISCORD_CHANNEL,
+  listAccountIds: listDiscordAccountIds,
+  resolveAccount: adaptScopedAccountAccessor(resolveDiscordAccount),
+  resolveAccessorAccount: resolveDiscordConfigAccessorAccount,
+  inspectAccount: adaptScopedAccountAccessor(inspectDiscordAccount),
+  defaultAccountId: resolveDefaultDiscordAccountId,
+  clearBaseFields: ["token", "name"],
+  resolveAllowFrom: (account) => account.allowFrom,
+  formatAllowFrom: (allowFrom) => formatAllowFromLowercase({ allowFrom }),
+  resolveDefaultTo: (account) => account.defaultTo,
+});
+
+export function createDiscordPluginBase(params: {
+  setup: NonNullable<ChannelPlugin<ResolvedDiscordAccount>["setup"]>;
+  setupWizard?: ChannelPlugin<ResolvedDiscordAccount>["setupWizard"];
+}): Pick<
+  ChannelPlugin<ResolvedDiscordAccount>,
+  | "id"
+  | "meta"
+  | "setupWizard"
+  | "capabilities"
+  | "commands"
+  | "doctor"
+  | "streaming"
+  | "reload"
+  | "configSchema"
+  | "config"
+  | "setup"
+  | "messaging"
+  | "security"
+  | "secrets"
+> {
+  return {
+    id: DISCORD_CHANNEL,
+    ...(params.setupWizard ? { setupWizard: params.setupWizard } : {}),
+    meta: { ...getChatChannelMeta(DISCORD_CHANNEL) },
+    capabilities: {
+      chatTypes: ["direct", "channel", "thread"],
+      polls: true,
+      reactions: true,
+      threads: true,
+      media: true,
+      tts: {
+        voice: {
+          synthesisTarget: "voice-note",
+        },
+      },
+      nativeCommands: true,
+    },
+    commands: {
+      nativeCommandsAutoEnabled: true,
+      nativeSkillsAutoEnabled: true,
+      resolveNativeCommandName: ({ commandKey, defaultName }) =>
+        commandKey === "tts" ? "voice" : defaultName,
+    },
+    doctor: discordDoctor,
+    streaming: {
+      blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+    },
+    reload: { configPrefixes: ["channels.discord"] },
+    configSchema: DiscordChannelConfigSchema,
+    config: {
+      ...discordConfigAdapter,
+      hasConfiguredState: ({ env }) =>
+        typeof env?.DISCORD_BOT_TOKEN === "string" && env.DISCORD_BOT_TOKEN.trim().length > 0,
+      isEnabled: (account, cfg) => isDiscordAccountEnabledForRuntime(account, cfg),
+      disabledReason: (account, cfg) => resolveDiscordAccountDisabledReason(account, cfg),
+      isConfigured: (account) =>
+        resolveConfiguredFromCredentialStatuses(account) ?? Boolean(account.token?.trim()),
+      describeAccount: (account) =>
+        describeAccountSnapshot({
+          account,
+          configured:
+            resolveConfiguredFromCredentialStatuses(account) ?? Boolean(account.token?.trim()),
+          extra: {
+            tokenSource: account.tokenSource,
+            tokenStatus: account.tokenStatus,
+          },
+        }),
+    },
+    messaging: {
+      deriveLegacySessionChatType,
+    },
+    security: discordSecurityAdapter,
+    secrets: {
+      secretTargetRegistryEntries,
+      unsupportedSecretRefSurfacePatterns,
+      collectUnsupportedSecretRefConfigCandidates,
+      collectRuntimeConfigAssignments,
+    },
+    setup: params.setup,
+  } as Pick<
+    ChannelPlugin<ResolvedDiscordAccount>,
+    | "id"
+    | "meta"
+    | "setupWizard"
+    | "capabilities"
+    | "commands"
+    | "doctor"
+    | "streaming"
+    | "reload"
+    | "configSchema"
+    | "config"
+    | "setup"
+    | "messaging"
+    | "security"
+    | "secrets"
+  >;
+}

package/src/status-issues.ts

@@ -0,0 +1,201 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelStatusIssue,
+} from "autobot/plugin-sdk/channel-contract";
+import {
+  appendMatchMetadata,
+  asString,
+  isRecord,
+  resolveEnabledConfiguredAccountId,
+} from "autobot/plugin-sdk/status-helpers";
+
+type DiscordIntentSummary = {
+  messageContent?: "enabled" | "limited" | "disabled";
+};
+
+type DiscordApplicationSummary = {
+  intents?: DiscordIntentSummary;
+};
+
+type DiscordAccountStatus = {
+  accountId?: unknown;
+  enabled?: unknown;
+  configured?: unknown;
+  running?: unknown;
+  connected?: unknown;
+  healthState?: unknown;
+  application?: unknown;
+  audit?: unknown;
+};
+
+type DiscordPermissionsAuditSummary = {
+  unresolvedChannels?: number;
+  channels?: Array<{
+    channelId: string;
+    ok?: boolean;
+    missing?: string[];
+    error?: string | null;
+    matchKey?: string;
+    matchSource?: string;
+  }>;
+};
+
+function readDiscordAccountStatus(value: ChannelAccountSnapshot): DiscordAccountStatus | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  return {
+    accountId: value.accountId,
+    enabled: value.enabled,
+    configured: value.configured,
+    running: value.running,
+    connected: value.connected,
+    healthState: value.healthState,
+    application: value.application,
+    audit: value.audit,
+  };
+}
+
+function readDiscordApplicationSummary(value: unknown): DiscordApplicationSummary {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const intentsRaw = value.intents;
+  if (!isRecord(intentsRaw)) {
+    return {};
+  }
+  return {
+    intents: {
+      messageContent:
+        intentsRaw.messageContent === "enabled" ||
+        intentsRaw.messageContent === "limited" ||
+        intentsRaw.messageContent === "disabled"
+          ? intentsRaw.messageContent
+          : undefined,
+    },
+  };
+}
+
+function readDiscordPermissionsAuditSummary(value: unknown): DiscordPermissionsAuditSummary {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const unresolvedChannels =
+    typeof value.unresolvedChannels === "number" && Number.isFinite(value.unresolvedChannels)
+      ? value.unresolvedChannels
+      : undefined;
+  const channelsRaw = value.channels;
+  const channels = Array.isArray(channelsRaw)
+    ? (channelsRaw
+        .map((entry) => {
+          if (!isRecord(entry)) {
+            return null;
+          }
+          const channelId = asString(entry.channelId);
+          if (!channelId) {
+            return null;
+          }
+          const ok = typeof entry.ok === "boolean" ? entry.ok : undefined;
+          const missing = Array.isArray(entry.missing)
+            ? entry.missing.map((v) => asString(v)).filter(Boolean)
+            : undefined;
+          const error = asString(entry.error) ?? null;
+          const matchKey = asString(entry.matchKey) ?? undefined;
+          const matchSource = asString(entry.matchSource) ?? undefined;
+          return {
+            channelId,
+            ok,
+            missing: missing?.length ? missing : undefined,
+            error,
+            matchKey,
+            matchSource,
+          };
+        })
+        .filter(Boolean) as DiscordPermissionsAuditSummary["channels"])
+    : undefined;
+  return { unresolvedChannels, channels };
+}
+
+export function collectDiscordStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+): ChannelStatusIssue[] {
+  const issues: ChannelStatusIssue[] = [];
+  for (const entry of accounts) {
+    const account = readDiscordAccountStatus(entry);
+    if (!account) {
+      continue;
+    }
+    const accountId = resolveEnabledConfiguredAccountId(account);
+    if (!accountId) {
+      continue;
+    }
+
+    const running = account.running === true;
+    const healthState = asString(account.healthState);
+    if (
+      healthState === "stale-socket" ||
+      healthState === "stuck" ||
+      healthState === "disconnected" ||
+      healthState === "not-running"
+    ) {
+      const runningLabel = running ? "running" : "not running";
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "runtime",
+        message: `Discord gateway transport is degraded (${healthState}; account is ${runningLabel}).`,
+        fix: "Check gateway event-loop health and Discord connectivity, then restart the Discord channel or gateway if the transport does not recover.",
+      });
+    } else if (running && account.connected === false) {
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "runtime",
+        message: "Discord gateway transport is running but disconnected.",
+        fix: "Check gateway logs for Discord websocket errors and wait for reconnect; restart the Discord channel or gateway if it does not recover.",
+      });
+    }
+
+    const app = readDiscordApplicationSummary(account.application);
+    const messageContent = app.intents?.messageContent;
+    if (messageContent === "disabled") {
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "intent",
+        message: "Message Content Intent is disabled. Bot may not see normal channel messages.",
+        fix: "Enable Message Content Intent in Discord Dev Portal → Bot → Privileged Gateway Intents, or require mention-only operation.",
+      });
+    }
+
+    const audit = readDiscordPermissionsAuditSummary(account.audit);
+    if (audit.unresolvedChannels && audit.unresolvedChannels > 0) {
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "config",
+        message: `Some configured guild channels are not numeric IDs (unresolvedChannels=${audit.unresolvedChannels}). Permission audit can only check numeric channel IDs.`,
+        fix: "Use numeric channel IDs as keys in channels.discord.guilds.*.channels (then rerun channels status --probe).",
+      });
+    }
+    for (const channel of audit.channels ?? []) {
+      if (channel.ok === true) {
+        continue;
+      }
+      const missing = channel.missing?.length ? ` missing ${channel.missing.join(", ")}` : "";
+      const error = channel.error ? `: ${channel.error}` : "";
+      const baseMessage = `Channel ${channel.channelId} permission check failed.${missing}${error}`;
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "permissions",
+        message: appendMatchMetadata(baseMessage, {
+          matchKey: channel.matchKey,
+          matchSource: channel.matchSource,
+        }),
+        fix: "Ensure the bot role can view + send in this channel (and that channel overrides don't deny it).",
+      });
+    }
+  }
+  return issues;
+}

package/src/subagent-hooks.ts

@@ -0,0 +1,232 @@
+import type { AutoBotPluginApi } from "autobot/plugin-sdk/channel-plugin-common";
+import {
+  formatThreadBindingDisabledError,
+  formatThreadBindingSpawnDisabledError,
+  resolveThreadBindingSpawnPolicy,
+} from "autobot/plugin-sdk/conversation-runtime";
+import {
+  normalizeOptionalLowercaseString,
+  normalizeOptionalStringifiedId,
+} from "autobot/plugin-sdk/string-coerce-runtime";
+import { resolveDiscordAccount } from "./accounts.js";
+import {
+  autoBindSpawnedDiscordSubagent,
+  listThreadBindingsBySessionKey,
+  type ThreadBindingTargetKind,
+  unbindThreadBindingsBySessionKey,
+} from "./monitor/thread-bindings.js";
+
+function summarizeError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  return "error";
+}
+
+type DiscordSubagentSpawningEvent = {
+  threadRequested?: boolean;
+  requester?: {
+    channel?: string;
+    accountId?: string;
+    to?: string;
+    threadId?: string | number;
+  };
+  childSessionKey: string;
+  agentId: string;
+  label?: string;
+};
+
+type DiscordSubagentEndedEvent = {
+  targetSessionKey: string;
+  accountId?: string;
+  targetKind?: ThreadBindingTargetKind;
+  reason?: string;
+  sendFarewell?: boolean;
+};
+
+type DiscordSubagentDeliveryTargetEvent = {
+  expectsCompletionMessage?: boolean;
+  childSessionKey: string;
+  requesterOrigin?: {
+    channel?: string;
+    accountId?: string;
+    threadId?: string | number;
+  };
+};
+
+type DiscordSubagentSpawningResult =
+  | {
+      status: "ok";
+      threadBindingReady?: boolean;
+      deliveryOrigin?: {
+        channel: "discord";
+        accountId?: string;
+        to: string;
+        threadId?: string | number;
+      };
+    }
+  | { status: "error"; error: string }
+  | undefined;
+
+type DiscordSubagentDeliveryTargetResult =
+  | {
+      origin: {
+        channel: "discord";
+        accountId?: string;
+        to: string;
+        threadId?: string | number;
+      };
+    }
+  | undefined;
+
+function normalizeThreadBindingTargetKind(raw?: string): ThreadBindingTargetKind | undefined {
+  const normalized = normalizeOptionalLowercaseString(raw);
+  if (normalized === "subagent" || normalized === "acp") {
+    return normalized;
+  }
+  return undefined;
+}
+
+export async function handleDiscordSubagentSpawning(
+  api: AutoBotPluginApi,
+  event: DiscordSubagentSpawningEvent,
+): Promise<DiscordSubagentSpawningResult> {
+  if (!event.threadRequested) {
+    return undefined;
+  }
+  const channel = normalizeOptionalLowercaseString(event.requester?.channel);
+  if (channel !== "discord") {
+    return undefined;
+  }
+  const account = resolveDiscordAccount({
+    cfg: api.config,
+    accountId: event.requester?.accountId,
+  });
+  const threadBindingPolicy = resolveThreadBindingSpawnPolicy({
+    cfg: api.config,
+    channel: "discord",
+    accountId: account.accountId,
+    kind: "subagent",
+  });
+  if (!threadBindingPolicy.enabled) {
+    return {
+      status: "error" as const,
+      error: formatThreadBindingDisabledError({
+        channel: threadBindingPolicy.channel,
+        accountId: threadBindingPolicy.accountId,
+        kind: "subagent",
+      }),
+    };
+  }
+  if (!threadBindingPolicy.spawnEnabled) {
+    return {
+      status: "error" as const,
+      error: formatThreadBindingSpawnDisabledError({
+        channel: threadBindingPolicy.channel,
+        accountId: threadBindingPolicy.accountId,
+        kind: "subagent",
+      }),
+    };
+  }
+  try {
+    const agentId = event.agentId?.trim() || "subagent";
+    const binding = await autoBindSpawnedDiscordSubagent({
+      cfg: api.config,
+      accountId: account.accountId,
+      channel: event.requester?.channel,
+      to: event.requester?.to,
+      threadId: event.requester?.threadId,
+      childSessionKey: event.childSessionKey,
+      agentId,
+      label: event.label,
+      boundBy: "system",
+    });
+    if (!binding) {
+      return {
+        status: "error" as const,
+        error:
+          "Unable to create or bind a Discord thread for this subagent session. Session mode is unavailable for this target.",
+      };
+    }
+    return {
+      status: "ok" as const,
+      threadBindingReady: true,
+      deliveryOrigin: {
+        channel: "discord",
+        accountId: account.accountId,
+        to: `channel:${binding.threadId}`,
+        threadId: binding.threadId,
+      },
+    };
+  } catch (err) {
+    return {
+      status: "error" as const,
+      error: `Discord thread bind failed: ${summarizeError(err)}`,
+    };
+  }
+}
+
+export function handleDiscordSubagentEnded(event: DiscordSubagentEndedEvent) {
+  unbindThreadBindingsBySessionKey({
+    targetSessionKey: event.targetSessionKey,
+    accountId: event.accountId,
+    targetKind: normalizeThreadBindingTargetKind(event.targetKind),
+    reason: event.reason,
+    sendFarewell: event.sendFarewell,
+  });
+}
+
+export function handleDiscordSubagentDeliveryTarget(
+  event: DiscordSubagentDeliveryTargetEvent,
+): DiscordSubagentDeliveryTargetResult {
+  if (!event.expectsCompletionMessage) {
+    return undefined;
+  }
+  const requesterChannel = normalizeOptionalLowercaseString(event.requesterOrigin?.channel);
+  if (requesterChannel !== "discord") {
+    return undefined;
+  }
+  const requesterAccountId = event.requesterOrigin?.accountId?.trim();
+  const requesterThreadId =
+    event.requesterOrigin?.threadId != null && event.requesterOrigin.threadId !== ""
+      ? (normalizeOptionalStringifiedId(event.requesterOrigin.threadId) ?? "")
+      : "";
+  const bindings = listThreadBindingsBySessionKey({
+    targetSessionKey: event.childSessionKey,
+    ...(requesterAccountId ? { accountId: requesterAccountId } : {}),
+    targetKind: "subagent",
+  });
+  if (bindings.length === 0) {
+    return undefined;
+  }
+
+  let binding: (typeof bindings)[number] | undefined;
+  if (requesterThreadId) {
+    binding = bindings.find((entry) => {
+      if (entry.threadId !== requesterThreadId) {
+        return false;
+      }
+      if (requesterAccountId && entry.accountId !== requesterAccountId) {
+        return false;
+      }
+      return true;
+    });
+  }
+  if (!binding && bindings.length === 1) {
+    binding = bindings[0];
+  }
+  if (!binding) {
+    return undefined;
+  }
+  return {
+    origin: {
+      channel: "discord" as const,
+      accountId: binding.accountId,
+      to: `channel:${binding.threadId}`,
+      threadId: binding.threadId,
+    },
+  };
+}

package/src/target-parsing.ts

@@ -0,0 +1,70 @@
+import {
+  buildMessagingTarget,
+  parseMentionPrefixOrAtUserTarget,
+  requireTargetKind,
+  type MessagingTarget,
+  type MessagingTargetKind,
+  type MessagingTargetParseOptions,
+} from "autobot/plugin-sdk/messaging-targets";
+
+export type DiscordTargetKind = MessagingTargetKind;
+
+export type DiscordTarget = MessagingTarget;
+
+export type DiscordTargetParseOptions = MessagingTargetParseOptions;
+
+export function parseDiscordTarget(
+  raw: string,
+  options: DiscordTargetParseOptions = {},
+): DiscordTarget | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const providerPrefixedTarget = parseDiscordProviderPrefixedTarget(trimmed);
+  if (providerPrefixedTarget) {
+    return providerPrefixedTarget;
+  }
+  const userTarget = parseMentionPrefixOrAtUserTarget({
+    raw: trimmed,
+    mentionPattern: /^<@!?(\d+)>$/,
+    prefixes: [
+      { prefix: "user:", kind: "user" },
+      { prefix: "channel:", kind: "channel" },
+      { prefix: "discord:", kind: "user" },
+    ],
+    atUserPattern: /^\d+$/,
+    atUserErrorMessage: "Discord DMs require a user id (use user:<id> or a <@id> mention)",
+  });
+  if (userTarget) {
+    return userTarget;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    if (options.defaultKind) {
+      return buildMessagingTarget(options.defaultKind, trimmed, trimmed);
+    }
+    throw new Error(
+      options.ambiguousMessage ??
+        `Ambiguous Discord recipient "${trimmed}". For DMs use "user:${trimmed}" or "<@${trimmed}>"; for channels use "channel:${trimmed}".`,
+    );
+  }
+  return buildMessagingTarget("channel", trimmed, trimmed);
+}
+
+function parseDiscordProviderPrefixedTarget(raw: string): DiscordTarget | undefined {
+  const match = /^discord:(channel|user):(.+)$/i.exec(raw);
+  if (!match) {
+    return undefined;
+  }
+  const kind = match[1]?.toLowerCase() as "channel" | "user" | undefined;
+  const id = match[2]?.trim();
+  if (!kind || !id) {
+    return undefined;
+  }
+  return buildMessagingTarget(kind, id, `${kind}:${id}`);
+}
+
+export function resolveDiscordChannelId(raw: string): string {
+  const target = parseDiscordTarget(raw, { defaultKind: "channel" });
+  return requireTargetKind({ platform: "Discord", target, kind: "channel" });
+}