@open-mercato/channel-discord 0.6.8-develop.7090.1.4dbca7b350

package/src/modules/channel_discord/lib/ai-agent-directory.ts

@@ -0,0 +1,124 @@
+import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('channel_discord').child({ component: 'ai-agent-directory' })
+
+/** The subset of an agent definition the settings surface needs to describe a choice. */
+export type DiscordEligibleAgent = {
+  id: string
+  label: string
+  description: string
+  requiredFeatures: string[]
+}
+
+export type DiscordAgentDirectory =
+  | { available: false }
+  | { available: true; agents: DiscordEligibleAgent[] }
+
+type AgentRegistryModule = {
+  loadAgentRegistry: () => Promise<unknown>
+  listAgents: () => Array<{
+    id: string
+    label?: string
+    description?: string
+    executionMode?: 'chat' | 'object'
+    output?: unknown
+    requiredFeatures?: string[]
+  }>
+}
+
+/**
+ * List the agents a Discord channel may legitimately be pointed at.
+ *
+ * "Eligible" means the AI runtime would accept the call the subscriber makes:
+ * `runAiAgentObject` requests execution mode `object`, and `checkAgentPolicy`
+ * rejects an agent that is neither declared object-mode nor carrying an output
+ * schema (`execution_mode_not_supported`). Offering a chat-mode agent in the
+ * picker would therefore be offering a setting that can only ever fail at
+ * runtime — the exact failure mode this feature was filed to remove.
+ *
+ * The import is dynamic and failure-tolerant because `@open-mercato/ai-assistant`
+ * is an optional peer: a deployment without it gets `{ available: false }`, and
+ * the settings surface then explains why auto-reply cannot be enabled instead of
+ * rendering an empty dropdown.
+ */
+export async function listDiscordEligibleAgents(): Promise<DiscordAgentDirectory> {
+  let mod: AgentRegistryModule
+  try {
+    mod = (await import('@open-mercato/ai-assistant')) as unknown as AgentRegistryModule
+  } catch {
+    return { available: false }
+  }
+  if (typeof mod.loadAgentRegistry !== 'function' || typeof mod.listAgents !== 'function') {
+    return { available: false }
+  }
+
+  try {
+    await mod.loadAgentRegistry()
+  } catch (err) {
+    logger.warn('Failed to load the AI agent registry', { err })
+    return { available: false }
+  }
+
+  const agents = mod
+    .listAgents()
+    .filter((agent) => agent.executionMode === 'object' || Boolean(agent.output))
+    .map((agent) => ({
+      id: agent.id,
+      label: agent.label ?? agent.id,
+      description: agent.description ?? '',
+      requiredFeatures: agent.requiredFeatures ?? [],
+    }))
+
+  return { available: true, agents }
+}
+
+/**
+ * The eligible agent `agentId` names, or `null` when the AI peer is absent or the
+ * agent is not one auto-reply may be pointed at.
+ *
+ * This replaced a boolean `isDiscordEligibleAgentId`: every caller that wanted the
+ * answer also wanted the agent's `requiredFeatures` for the authorization check
+ * below, and asking twice meant loading the agent registry twice.
+ */
+export async function findDiscordEligibleAgent(agentId: string): Promise<DiscordEligibleAgent | null> {
+  const directory = await listDiscordEligibleAgents()
+  if (!directory.available) return null
+  return directory.agents.find((agent) => agent.id === agentId) ?? null
+}
+
+/** The identity half of the invocability question — see {@link missingAgentFeatures}. */
+export type AgentInvokingPrincipal = {
+  features: string[]
+  isSuperAdmin: boolean
+}
+
+/**
+ * The subset of an agent's `requiredFeatures` the principal does NOT hold.
+ *
+ * This is the second half of "can auto-reply actually invoke this agent", and it
+ * is the half the settings surface used to skip. `listDiscordEligibleAgents`
+ * answers the *shape* question (object-mode, so `runAiAgentObject` will take it);
+ * this answers the *authorization* question the runtime asks next, when
+ * `checkAgentPolicy` runs the agent's `requiredFeatures` against the principal
+ * from `lib/ai-service-principal.ts`. An agent that clears the first and fails the
+ * second stores a setting that can only fail later, inside a background
+ * subscriber — the failure mode issue #4778 was filed for.
+ *
+ * The check delegates to the platform's own `authorizeFeatures`, one feature at a
+ * time so the caller can name what is missing. Going through the shared helper —
+ * rather than a `Set.has` — is what makes wildcard grants (`customers.*`, `*`),
+ * removed features and disabled modules resolve exactly the way the runtime will
+ * resolve them; a hand-rolled comparison would reject a bot user whose role
+ * carries a wildcard and the operator would have no way to tell why.
+ */
+export function missingAgentFeatures(
+  requiredFeatures: readonly string[] | undefined,
+  principal: AgentInvokingPrincipal,
+): string[] {
+  if (!requiredFeatures?.length) return []
+  return requiredFeatures.filter((featureId) => !authorizeFeatures([featureId], {
+    grantedFeatures: principal.features,
+    unrestricted: principal.isSuperAdmin,
+  }))
+}

package/src/modules/channel_discord/lib/ai-features.ts

@@ -0,0 +1,23 @@
+/**
+ * ACL feature ids the AI auto-reply path depends on, in one dependency-free
+ * module so `acl.ts`, `ai-agents.ts`, the API routes, and the service principal
+ * can all import the same literal instead of repeating the string. Feature ids
+ * are FROZEN once shipped (`BACKWARD_COMPATIBILITY.md` § ACL features) — add new
+ * ones rather than renaming these.
+ */
+
+/**
+ * Gates invoking the Discord auto-reply agent. It grants no data access of its
+ * own: the agent it unlocks runs in object mode with no tools, so the only thing
+ * this feature buys its holder is the ability to have text drafted.
+ *
+ * It is also the single grant the subscriber's service principal falls back to
+ * when a tenant has no channel-bot user — see `lib/ai-service-principal.ts`.
+ */
+export const CHANNEL_DISCORD_AI_AUTO_REPLY_RUN_FEATURE = 'channel_discord.ai_auto_reply.run'
+
+/** Gates reading and writing a channel's AI auto-reply configuration. */
+export const CHANNEL_DISCORD_CONFIGURE_FEATURE = 'channel_discord.configure'
+
+/** Gates read-only access to the Discord channel configuration surfaces. */
+export const CHANNEL_DISCORD_VIEW_FEATURE = 'channel_discord.view'

package/src/modules/channel_discord/lib/ai-proposal-contract.ts

@@ -0,0 +1,24 @@
+/**
+ * Ids shared between the AI proposal's message type, its commands, and the
+ * subscriber that files it. They live in their own dependency-free module so
+ * `message-types.ts` (loaded by the messages registry) and `commands/*.ts`
+ * (loaded by the command bus) can agree on the strings without importing each
+ * other and creating a cycle.
+ *
+ * Command ids are a contract surface (`BACKWARD_COMPATIBILITY.md`): renaming one
+ * breaks every proposal message already sitting in an operator's inbox, because
+ * the action row stored on that message still names the old id.
+ */
+export const CHANNEL_DISCORD_AI_PROPOSAL_APPROVE_COMMAND_ID =
+  'channel_discord.ai_reply_proposal.approve'
+
+export const CHANNEL_DISCORD_AI_PROPOSAL_DISMISS_COMMAND_ID =
+  'channel_discord.ai_reply_proposal.dismiss'
+
+/**
+ * `sourceEntityType` on the proposal message. The approve command reads
+ * `sourceEntityId` as the id of the inbound Discord message being answered, so
+ * it can resolve the thread to reply into without trusting anything the operator
+ * sends from the browser.
+ */
+export const CHANNEL_DISCORD_AI_PROPOSAL_SOURCE_ENTITY_TYPE = 'messages.message'

package/src/modules/channel_discord/lib/ai-proposal.ts

@@ -0,0 +1,179 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import {
+  ChannelThreadMapping,
+  CommunicationChannel,
+  ExternalConversation,
+} from '@open-mercato/core/modules/communication_channels/data/entities'
+import type { Message } from '@open-mercato/core/modules/messages/data/entities'
+import { CHANNEL_DISCORD_AI_PROPOSAL_SOURCE_ENTITY_TYPE } from './ai-proposal-contract'
+import { CHANNEL_DISCORD_AI_PROPOSAL_MESSAGE_TYPE } from '../message-types'
+
+const logger = createLogger('channel_discord').child({ component: 'ai-proposal' })
+
+export type DiscordProposalScope = { tenantId: string; organizationId: string | null }
+
+export type FileDiscordProposalResult = {
+  proposalMessageId: string
+  /** `'assigned'` went to a human with approve/dismiss actions; `'stored'` is a draft nobody was notified about. */
+  outcome: 'assigned' | 'stored'
+  reviewerUserId: string | null
+}
+
+const MAX_SUBJECT_LENGTH = 200
+const MAX_SUMMARY_LENGTH = 500
+
+/**
+ * Find the human who should review a proposal for this conversation.
+ *
+ * Order mirrors what the hub itself does when it decides who an INBOUND channel
+ * message is addressed to (`ingest-inbound-message.ts` uses the thread mapping's
+ * assignee), then widens to the two other owners a Discord channel can have. It
+ * deliberately does not fan out to "everyone with the feature": a proposal is a
+ * task for the person who owns the conversation, not a broadcast.
+ */
+export async function resolveDiscordProposalReviewer(params: {
+  em: EntityManager
+  scope: DiscordProposalScope
+  channelId: string
+  messageThreadId: string | null
+  externalConversationId: string | null
+}): Promise<string | null> {
+  const { em, scope, channelId, messageThreadId, externalConversationId } = params
+
+  if (messageThreadId) {
+    const mapping = await em.findOne(ChannelThreadMapping, {
+      messageThreadId,
+      tenantId: scope.tenantId,
+    })
+    if (mapping?.assignedUserId) return mapping.assignedUserId
+  }
+
+  if (externalConversationId) {
+    const conversation = await em.findOne(ExternalConversation, {
+      id: externalConversationId,
+      tenantId: scope.tenantId,
+    })
+    if (conversation?.assignedUserId) return conversation.assignedUserId
+  }
+
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    { id: channelId, tenantId: scope.tenantId, deletedAt: null },
+    undefined,
+    { tenantId: scope.tenantId, organizationId: scope.organizationId ?? scope.tenantId },
+  )
+  return channel?.userId ?? null
+}
+
+/**
+ * File the `complex`-tier proposal (SPEC 2026-06-19 § AI bot wiring step 5,
+ * issue #4778). This is what replaced "log a line and return".
+ *
+ * Two shapes, one helper:
+ *
+ * - A reviewer resolves → an INTERNAL message addressed to them, carrying the
+ *   drafted reply as its body and the approve/dismiss actions declared by
+ *   `message-types.ts`. Approving dispatches
+ *   `channel_discord.ai_reply_proposal.approve`, which composes the public reply
+ *   through the same hub path the easy tier uses.
+ * - No reviewer resolves (an unassigned tenant-scoped channel — the same case
+ *   where the hub files the inbound message with no recipient either) → the
+ *   proposal is stored as a DRAFT so the text is not lost, and the fact that
+ *   nobody was notified is logged. Assigning the conversation is the operator
+ *   action that turns future proposals into approval cards.
+ *
+ * Neither shape can reach Discord on its own: a draft emits no
+ * `messages.message.sent`, and the internal message is `visibility: 'internal'`,
+ * which the hub's outbound bridge does not deliver. Only the approve command
+ * sends, and only a human can call it.
+ */
+export async function fileDiscordReplyProposal(params: {
+  em: EntityManager
+  commandBus: CommandBus
+  containerCtx: unknown
+  scope: DiscordProposalScope
+  channelId: string
+  inboundMessage: Pick<Message, 'id' | 'type' | 'subject' | 'threadId'>
+  externalConversationId: string | null
+  botUserId: string
+  proposedReply: string
+  summary: string
+  reason: string
+}): Promise<FileDiscordProposalResult> {
+  const {
+    em,
+    commandBus,
+    containerCtx,
+    scope,
+    channelId,
+    inboundMessage,
+    externalConversationId,
+    botUserId,
+    proposedReply,
+    summary,
+    reason,
+  } = params
+
+  const reviewerUserId = await resolveDiscordProposalReviewer({
+    em,
+    scope,
+    channelId,
+    messageThreadId: inboundMessage.threadId ?? inboundMessage.id,
+    externalConversationId,
+  })
+
+  const subject = summary.trim().slice(0, MAX_SUBJECT_LENGTH) || 'Proposed Discord reply'
+
+  const composeInput = {
+    type: CHANNEL_DISCORD_AI_PROPOSAL_MESSAGE_TYPE,
+    visibility: 'internal' as const,
+    sourceEntityType: CHANNEL_DISCORD_AI_PROPOSAL_SOURCE_ENTITY_TYPE,
+    sourceEntityId: inboundMessage.id,
+    recipients: reviewerUserId ? [{ userId: reviewerUserId, type: 'to' as const }] : [],
+    subject,
+    body: proposedReply,
+    bodyFormat: 'markdown' as const,
+    priority: 'normal' as const,
+    sendViaEmail: false,
+    // A draft when there is nobody to address it to — the compose validator only
+    // requires a recipient for a message that is actually being delivered.
+    isDraft: !reviewerUserId,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: botUserId,
+  }
+
+  const composeResult = await commandBus.execute<typeof composeInput, { id: string }>(
+    'messages.messages.compose',
+    {
+      input: composeInput,
+      ctx: containerCtx as never,
+    },
+  )
+
+  const outcome: FileDiscordProposalResult['outcome'] = reviewerUserId ? 'assigned' : 'stored'
+  if (outcome === 'stored') {
+    logger.info(
+      'Filed a Discord AI reply proposal with no reviewer — assign the conversation to get approval cards',
+      { channelId, reason, proposalMessageId: composeResult.result.id },
+    )
+  } else {
+    logger.info('Filed a Discord AI reply proposal for review', {
+      channelId,
+      reason,
+      proposalMessageId: composeResult.result.id,
+    })
+  }
+
+  return {
+    proposalMessageId: composeResult.result.id,
+    outcome,
+    reviewerUserId,
+  }
+}
+
+export { MAX_SUMMARY_LENGTH }

package/src/modules/channel_discord/lib/ai-reply.ts

@@ -0,0 +1,179 @@
+import { discordChannelStateSchema, type DiscordChannelState } from './credentials'
+
+/**
+ * AI auto-reply helpers (SPEC 2026-06-19 § AI bot wiring).
+ *
+ * `aiAutoReplyEnabled` / `aiAgentId` are written by the channel's AI auto-reply
+ * settings form (`backend/channel_discord/channels/[id]/ai-auto-reply`) through
+ * `PUT /api/channel_discord/channels/{id}/ai-auto-reply`. Both default to off, so
+ * a channel nobody configured never reaches the model.
+ *
+ * `ai_assistant` is an OPTIONAL peer. This module never statically imports it;
+ * the subscriber resolves it softly via DI (`mcpToolRegistry`) and, only when it
+ * is present AND per-channel auto-reply is enabled, dynamically imports
+ * `runAiAgentObject`. When the peer is absent the subscriber no-ops and the channel
+ * still works as a plain inbox (module-decoupling contract).
+ */
+
+export type ReplyTier = 'easy' | 'complex'
+
+export interface ClassificationResult {
+  tier: ReplyTier
+  confidence: number
+  reason: string
+}
+
+// Signals that a message needs a human (mutations, escalation, sensitive topics).
+// The bot never auto-answers these — it proposes for approval instead (SPEC-056
+// easy-vs-complex tiering).
+const COMPLEX_SIGNALS = [
+  /\brefund\b/i,
+  /\bcancel\b/i,
+  /\binvoice\b/i,
+  /\bchargeback\b/i,
+  /\bcomplain/i,
+  /\bescalat/i,
+  /\blegal\b/i,
+  /\bhuman\b/i,
+  /\bagent\b/i,
+  /\bmanager\b/i,
+  /\border\b/i,
+  /\bpayment\b/i,
+  /\bprice\b/i,
+  /\bdiscount\b/i,
+]
+
+// Signals that a message is trying to steer the model rather than ask a
+// question (prompt injection). Always propose-only — a human sees the attempt
+// before anything is sent.
+const INJECTION_SIGNALS = [
+  /\bignore\b[\s\S]{0,60}\b(instructions?|prompts?|rules?)\b/i,
+  /\bdisregard\b/i,
+  /\bsystem\s*prompt\b/i,
+  /\bjailbreak/i,
+  /\bdeveloper\s+mode\b/i,
+  /\byou\s+are\s+now\b/i,
+  /\bnew\s+instructions?\b/i,
+  /\bpretend\s+(to\s+be|you)\b/i,
+  /\bact\s+as\b/i,
+  /\brole\s*-?\s*play\b/i,
+  /^\s*(system|assistant)\s*:/im,
+]
+
+// The bot must never act on content it would have to fetch — a link is a
+// second, unvetted instruction channel.
+const LINK_SIGNAL = /\bhttps?:\/\/|\bwww\.|\bdiscord\.gg\//i
+
+// Zero-width, bidi-override, and word-joiner characters have no place in a
+// legitimate support question; their presence means someone is hiding content
+// from pattern matching (e.g. `re​fund`).
+const INVISIBLE_CHARS = /[\u200b-\u200f\u202a-\u202e\u2060-\u2064\ufeff]/
+
+/**
+ * Build the copy of the text that signals are matched against. Defeats the
+ * cheap obfuscations of a regex gate: compatibility forms (`ｒｅｆｕｎｄ` →
+ * `refund`, NFKC), invisible characters, markdown emphasis/spoilers splitting a
+ * keyword (`**ref**und`, `||refund||`), and combining-mark zalgo (NFKD + strip).
+ */
+function normalizeForClassification(text: string): string {
+  return text
+    .normalize('NFKC')
+    .replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u2064\ufeff]/g, '')
+    .replace(/[`*_~|]/g, '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^\S\n]+/g, ' ')
+    .trim()
+}
+
+function matchSignal(signals: RegExp[], raw: string, normalized: string): RegExp | null {
+  for (const signal of signals) {
+    if (signal.test(raw) || signal.test(normalized)) return signal
+  }
+  return null
+}
+
+/**
+ * Classify an inbound Discord message as "easy" (bot may answer directly) vs
+ * "complex" (propose-only, human approves). A deliberately conservative
+ * heuristic — when in doubt it returns `complex` so nothing risky auto-sends.
+ *
+ * Hardening note: signals are matched against a normalized copy as well as the
+ * raw text, and injection/link/obfuscation attempts force `complex`. This is
+ * defense-in-depth layering, not a proof — the real containment for anything
+ * that slips through is downstream: propose-only for complex, an object-mode
+ * agent the runtime never gives a tool to, a service principal holding one
+ * non-data feature and never `isSuperAdmin`, `allowed_mentions: { parse: [] }`,
+ * and the audited outbound path.
+ */
+export function classifyDiscordMessage(body: string): ClassificationResult {
+  const text = (body ?? '').trim()
+  if (text.length === 0) {
+    return { tier: 'complex', confidence: 0, reason: 'empty-body' }
+  }
+  if (INVISIBLE_CHARS.test(text)) {
+    return { tier: 'complex', confidence: 0.95, reason: 'obfuscation-suspect' }
+  }
+  const normalized = normalizeForClassification(text)
+  const injection = matchSignal(INJECTION_SIGNALS, text, normalized)
+  if (injection) {
+    return { tier: 'complex', confidence: 0.95, reason: `injection-suspect:${injection.source}` }
+  }
+  if (LINK_SIGNAL.test(text) || LINK_SIGNAL.test(normalized)) {
+    return { tier: 'complex', confidence: 0.9, reason: 'contains-link' }
+  }
+  const complexSignal = matchSignal(COMPLEX_SIGNALS, text, normalized)
+  if (complexSignal) {
+    return { tier: 'complex', confidence: 0.9, reason: `matched:${complexSignal.source}` }
+  }
+  // Long messages or multi-question threads are more likely to need nuance.
+  const questionCount = (text.match(/\?/g) ?? []).length
+  if (text.length > 600 || questionCount > 2) {
+    return { tier: 'complex', confidence: 0.6, reason: 'long-or-multi-question' }
+  }
+  return { tier: 'easy', confidence: 0.8, reason: 'short-simple' }
+}
+
+/** Per-channel AI auto-reply is OFF unless explicitly enabled on channel state. */
+export function isAiAutoReplyEnabled(channelState: unknown): boolean {
+  const parsed = discordChannelStateSchema.safeParse(channelState ?? {})
+  return parsed.success ? Boolean(parsed.data.aiAutoReplyEnabled) : false
+}
+
+export function resolveAiAgentId(channelState: unknown): string | undefined {
+  const parsed = discordChannelStateSchema.safeParse(channelState ?? {})
+  return parsed.success ? parsed.data.aiAgentId : undefined
+}
+
+/** Whether a previous auto-reply attempt left a failure marker still to be cleared. */
+export function hasStoredAutoReplyFailure(channelState: unknown): boolean {
+  const parsed = discordChannelStateSchema.safeParse(channelState ?? {})
+  return parsed.success ? parsed.data.aiAutoReplyLastError !== undefined : false
+}
+
+export interface SubscriberResolver {
+  resolve: <T = unknown>(name: string) => T
+  container?: { resolve: <T = unknown>(name: string) => T }
+}
+
+/**
+ * Soft presence check for the `ai_assistant` module. The module registers
+ * `mcpToolRegistry` in DI, so a successful resolve means the peer is active.
+ * Returns `false` (no-op) when it is absent — never throws.
+ */
+export function isAiAssistantAvailable(ctx: SubscriberResolver): boolean {
+  const resolver =
+    typeof ctx?.resolve === 'function'
+      ? ctx.resolve
+      : ctx?.container?.resolve
+        ? ctx.container.resolve.bind(ctx.container)
+        : null
+  if (!resolver) return false
+  try {
+    return Boolean(resolver('mcpToolRegistry'))
+  } catch {
+    return false
+  }
+}
+
+export type { DiscordChannelState }

package/src/modules/channel_discord/lib/ai-service-principal.ts

@@ -0,0 +1,143 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import {
+  COMMUNICATION_CHANNELS_SYSTEM_USER_ID,
+  resolveCommunicationChannelsSystemUserId,
+} from '@open-mercato/core/modules/communication_channels/lib/system-user'
+import { CHANNEL_DISCORD_AI_AUTO_REPLY_RUN_FEATURE } from './ai-features'
+
+const logger = createLogger('channel_discord').child({ component: 'ai-service-principal' })
+
+/**
+ * The auth context the AI auto-reply subscriber runs an agent under.
+ *
+ * Field names match `AiChatRequestContext` from `@open-mercato/ai-assistant` on
+ * purpose — the subscriber hands this object straight to `runAiAgentObject` —
+ * but the type is declared locally so the optional peer stays optional.
+ */
+export type DiscordAiPrincipal = {
+  tenantId: string
+  organizationId: string | null
+  userId: string
+  features: string[]
+  isSuperAdmin: boolean
+  /** Which of the two identities below produced the grants. Logged, never sent to the model. */
+  source: 'channel_bot_user' | 'provider_service_principal'
+}
+
+/**
+ * The grants the provider's own service principal carries by construction, with
+ * no operator setup. Exactly one non-data feature: it unlocks the provider's own
+ * object-mode auto-reply agent and nothing else. Any agent gated on anything
+ * broader — a customers support agent, say — is NOT reachable from this identity
+ * and needs the channel-bot user path below.
+ */
+const PROVIDER_SERVICE_PRINCIPAL_FEATURES: readonly string[] = [
+  CHANNEL_DISCORD_AI_AUTO_REPLY_RUN_FEATURE,
+]
+
+type AclSnapshot = { features: string[]; isSuperAdmin: boolean }
+
+type RbacServiceLike = {
+  loadAcl: (
+    userId: string,
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<AclSnapshot & { organizations: string[] | null }>
+}
+
+export type DiscordAiPrincipalResolver = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+function tryResolveRbacService(resolver: DiscordAiPrincipalResolver): RbacServiceLike | null {
+  try {
+    const service = resolver.resolve<RbacServiceLike>('rbacService')
+    return service && typeof service.loadAcl === 'function' ? service : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Resolve the identity an inbound Discord message may borrow to have a reply
+ * drafted (SPEC 2026-06-19 § AI bot wiring — "Safety / RBAC", issue #4778).
+ *
+ * There are two identities, and the difference between them is the whole point:
+ *
+ * 1. **Channel-bot user** — a real `auth.user` row following the hub's
+ *    `system+communication_channels@<tenantId>.local` convention. When a tenant
+ *    creates one, its role grants are loaded through `rbacService.loadAcl` and
+ *    become the principal's features. This is the supported way to let auto-reply
+ *    use an agent this provider does not own: grant the bot user the role that
+ *    agent's `requiredFeatures` need.
+ * 2. **Provider service principal** — the fallback when no such user exists.
+ *    It carries {@link PROVIDER_SERVICE_PRINCIPAL_FEATURES} only.
+ *
+ * Two invariants hold on both paths:
+ *
+ * - `isSuperAdmin` is **always** false. An inbound message from a public Discord
+ *   server must not be able to borrow a super-admin's ACL, so a bot user who
+ *   happens to be one is clamped down (and the clamp is logged, because it means
+ *   the tenant gave a bot account far more than it needs).
+ * - The provider grant is always present. It is what makes the provider's own
+ *   agent work out of the box; it can never widen access to anything else,
+ *   because no tool or route is gated on it.
+ */
+export async function resolveDiscordAiPrincipal(params: {
+  em: EntityManager
+  resolver: DiscordAiPrincipalResolver
+  scope: { tenantId: string; organizationId: string | null }
+}): Promise<DiscordAiPrincipal> {
+  const { em, resolver, scope } = params
+  const base: DiscordAiPrincipal = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: COMMUNICATION_CHANNELS_SYSTEM_USER_ID,
+    features: [...PROVIDER_SERVICE_PRINCIPAL_FEATURES],
+    isSuperAdmin: false,
+    source: 'provider_service_principal',
+  }
+
+  const botUserId = await resolveCommunicationChannelsSystemUserId(em, scope.tenantId, null)
+  if (botUserId === COMMUNICATION_CHANNELS_SYSTEM_USER_ID) return base
+
+  const rbacService = tryResolveRbacService(resolver)
+  if (!rbacService) {
+    logger.debug('rbacService unavailable — running auto-reply under the provider service principal', {
+      tenantId: scope.tenantId,
+    })
+    return { ...base, userId: botUserId }
+  }
+
+  let acl: AclSnapshot
+  try {
+    acl = await rbacService.loadAcl(botUserId, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+    })
+  } catch (err) {
+    logger.warn('Failed to load the channel-bot ACL — falling back to the provider service principal', {
+      tenantId: scope.tenantId,
+      err,
+    })
+    return { ...base, userId: botUserId }
+  }
+
+  if (acl.isSuperAdmin) {
+    logger.warn(
+      'Channel-bot user is a super-admin; clamping the auto-reply principal to its explicit features',
+      { tenantId: scope.tenantId },
+    )
+  }
+
+  const features = Array.from(new Set([...PROVIDER_SERVICE_PRINCIPAL_FEATURES, ...acl.features]))
+  return {
+    ...base,
+    userId: botUserId,
+    features,
+    isSuperAdmin: false,
+    source: 'channel_bot_user',
+  }
+}
+
+export { PROVIDER_SERVICE_PRINCIPAL_FEATURES }