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

package/src/modules/channel_discord/lib/capabilities.ts

@@ -0,0 +1,104 @@
+import type { ChannelCapabilities } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+
+/**
+ * Discord message content hard limit — the REST API rejects `content` longer
+ * than 2000 characters (embeds have their own separate budget we don't use here).
+ */
+export const DISCORD_MAX_BODY_LENGTH = 2000
+
+/**
+ * Discord capability profile (SPEC 2026-06-19 § Adapter method map).
+ *
+ * The hub treats these flags as a contract: it routes work to the adapter based
+ * on them, so each one describes what THIS adapter implements today, not what
+ * the Discord API is able to do. Everything the first release does not implement
+ * is declared `false` and stays `false` until the corresponding code lands.
+ *
+ * Enabled, with the implementation behind each:
+ * - `richText` / `supportedBodyFormats: ['text', 'markdown']` — Discord content
+ *   is markdown-native; HTML is down-converted in `convertOutbound`.
+ * - `reactions` / `editMessage` / `deleteMessage` — backed by the matching
+ *   `discord-rest` calls the adapter exposes.
+ * - `conversationHistory` — `fetchHistory` pages `GET /channels/{id}/messages`.
+ * - `realtimePush` — the provider owns a long-running Gateway WebSocket worker
+ *   that delivers `MESSAGE_CREATE` / reaction events in real time, so the hub's
+ *   polling scheduler skips this channel (no redundant `fetchHistory`).
+ * - `interactiveComponents` — slash commands, buttons, select menus and modal
+ *   submissions round-trip for real: the signed Interactions endpoint answers
+ *   with a deferred acknowledgement AND hands the interaction to
+ *   `workers/discord-interactions.ts`, which normalizes it into the hub's
+ *   existing inbound queue under the matched channel's tenant scope and then
+ *   replaces the "thinking…" placeholder over Discord's interaction-webhook
+ *   endpoints. Pinned by the parity test in `lib/__tests__/capabilities.test.ts`,
+ *   which drives the whole path rather than asserting the flag alone.
+ *
+ * Deliberately disabled until implemented (declaring them would make the hub
+ * hand this adapter work it silently drops):
+ * - `threading` — `convertOutbound` reads `channelMetadata.replyToExternalId`
+ *   and emits `message_reference` from it, but nothing hub-side ever writes that
+ *   key into OUTBOUND metadata: `replyToExternalId` exists only on the inbound
+ *   `NormalizedInboundMessage` shape, and the hub's outbound metadata producers
+ *   (`send-as-user.ts`, `deliver-outbound-message.ts`) write the email-shaped
+ *   `inReplyTo` / `references` instead. The conversion is therefore unreachable
+ *   in production — confirmed against a live bot in #5541. The flag flips back
+ *   to `true` in the same change that gives the hub an outbound reply producer
+ *   this adapter can read, guarded by a contract test.
+ * - `fileSharing` / `inlineImages` — `convertOutbound` drops
+ *   `input.content.attachments` and `discord-rest` has no multipart upload, so
+ *   outbound attachments never reach Discord. `maxFileSize` /
+ *   `supportedMimeTypes` are omitted for the same reason.
+ * - `typingIndicators` — no `POST /channels/{id}/typing` call exists here.
+ * - `presence` — the bot identifies without the `GUILD_PRESENCES` intent and no
+ *   presence dispatch is handled.
+ * - `richBlocks` — outbound is plain markdown `content`; embeds are not built.
+ * - `stickers` — no sticker is sent or normalized.
+ *
+ * AI auto-reply (issue #4778) deliberately flips NONE of these back to `true`.
+ * `ChannelCapabilities` describes what the hub may hand this ADAPTER — message
+ * shapes, transport features, whether to schedule polling. Auto-reply is not an
+ * adapter capability at all: it is a subscriber on the hub's generic
+ * `message.received` event that composes a reply through the same outbound path
+ * any module uses. Adding a flag for it would tell the hub to route work here
+ * that the adapter does not implement, which is exactly the failure mode this
+ * list exists to prevent.
+ */
+export const discordCapabilities: ChannelCapabilities = {
+  // A Discord recipient is a channel snowflake, never an address. Without this
+  // the hub falls back to its `'email'` default and `validateOutboundRecipient`
+  // rejects every real recipient with "Recipient must be a valid email address"
+  // — which is #4976 still broken for the provider it was filed against, even
+  // though #5261 built the mechanism to fix it. The hub then applies transport
+  // safety only (allowlist + length), and this adapter owns the format and must
+  // keep treating the value as untrusted.
+  recipientFormat: 'provider-native',
+
+  // Core
+  threading: false,
+  richText: true,
+  fileSharing: false,
+  readReceipts: false,
+  deliveryReceipts: false,
+  typingIndicators: false,
+
+  // Extended
+  reactions: true,
+  multiReactionPerUser: false,
+  editMessage: true,
+  deleteMessage: true,
+  presence: false,
+  richBlocks: false,
+  interactiveComponents: true,
+  inlineImages: false,
+  conversationHistory: true,
+  contactCards: false,
+  locationSharing: false,
+  voiceNotes: false,
+  stickers: false,
+
+  // Content format support
+  supportedBodyFormats: ['text', 'markdown'],
+  maxBodyLength: DISCORD_MAX_BODY_LENGTH,
+
+  // The gateway worker is the real-time source; the hub must not schedule polling.
+  realtimePush: true,
+}

package/src/modules/channel_discord/lib/channel-access.ts

@@ -0,0 +1,110 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { NextResponse } from 'next/server'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { resolveOrganizationScopeFilter } from '@open-mercato/core/modules/directory/utils/organizationScopeFilter'
+import { CommunicationChannel } from '@open-mercato/core/modules/communication_channels/data/entities'
+import {
+  assertCanAccessChannel,
+  assertCanManageChannel,
+  channelOrgScopeWhereFromFilter,
+  ChannelAccessDeniedError,
+} from '@open-mercato/core/modules/communication_channels/lib/access-control'
+
+type RouteAuth = {
+  sub?: string | null
+  tenantId?: string | null
+  orgId?: string | null
+}
+
+type RbacServiceLike = {
+  loadAcl: (
+    userId: string,
+    scope: { tenantId: string | null; organizationId: string | null },
+  ) => Promise<{ isSuperAdmin: boolean; features: string[]; organizations: string[] | null }>
+}
+
+export type DiscordChannelAccess = {
+  channel: CommunicationChannel
+  /** Organizations the caller may see, for the command's own scoped re-lookup. */
+  organizationIds: string[] | null
+  /** Organization the decryption scope is anchored to. */
+  rbacOrganizationId: string | null
+}
+
+/**
+ * Load a Discord channel for a provider-owned route, scoped and authorized the
+ * same way the hub's own channel-scoped routes do.
+ *
+ * Reusing the hub's helpers rather than filtering on `auth.orgId` matters twice
+ * over. A Discord bot channel is usually tenant-scoped (`organization_id IS
+ * NULL`), so an equality filter on the caller's selected organization would hide
+ * exactly the channels this feature configures (#5012 fixed the same bug on the
+ * hub's detail route). And a per-user channel belongs to its owner: the shared
+ * access guards are what stop one operator from arming an AI on another's
+ * mailbox, which no feature grant should be able to override.
+ *
+ * Returns `{ response }` with a masked 404 when the channel is absent or the
+ * caller may not touch it — existence masking, consistent with the hub.
+ */
+export async function loadDiscordChannelForRequest(params: {
+  container: AwilixContainer
+  req: Request
+  auth: RouteAuth
+  channelId: string
+  mode: 'read' | 'manage'
+}): Promise<DiscordChannelAccess | { response: Response }> {
+  const { container, req, auth, channelId, mode } = params
+  const notFound = { response: NextResponse.json({ error: 'Channel not found' }, { status: 404 }) }
+
+  const em = (container.resolve('em') as EntityManager).fork()
+  const scope = await resolveOrganizationScopeForRequest({ container, auth: auth as never, request: req })
+  const orgFilter = resolveOrganizationScopeFilter(scope, auth as never)
+
+  const channel = await findOneWithDecryption(
+    em,
+    CommunicationChannel,
+    {
+      id: channelId,
+      tenantId: auth.tenantId as string,
+      providerKey: 'discord',
+      ...channelOrgScopeWhereFromFilter(orgFilter),
+      deletedAt: null,
+    },
+    undefined,
+    { tenantId: auth.tenantId as string, organizationId: orgFilter.rbacOrganizationId },
+  )
+  if (!channel) return notFound
+
+  let userFeatures: string[] = []
+  try {
+    const rbac = container.resolve('rbacService') as RbacServiceLike
+    const acl = await rbac.loadAcl(auth.sub as string, {
+      tenantId: auth.tenantId as string,
+      organizationId: orgFilter.rbacOrganizationId,
+    })
+    userFeatures = acl.features
+  } catch {
+    // A failed ACL load leaves `userFeatures` empty, which only makes the guard
+    // below stricter — it can deny, never grant.
+    userFeatures = []
+  }
+
+  try {
+    if (mode === 'manage') {
+      assertCanManageChannel(channel, auth.sub ?? null, userFeatures, 'communication_channels.manage')
+    } else {
+      assertCanAccessChannel(channel, auth.sub ?? null, userFeatures)
+    }
+  } catch (err) {
+    if (err instanceof ChannelAccessDeniedError) return notFound
+    throw err
+  }
+
+  return {
+    channel,
+    organizationIds: orgFilter.organizationIds ?? null,
+    rbacOrganizationId: orgFilter.rbacOrganizationId,
+  }
+}

package/src/modules/channel_discord/lib/channel-state-store.ts

@@ -0,0 +1,217 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { CommunicationChannel } from '@open-mercato/core/modules/communication_channels/data/entities'
+import { discordChannelStateSchema, type DiscordChannelState } from './credentials'
+
+/**
+ * Tenant/organization scope every Discord channel-state write MUST carry.
+ * The gateway worker persists resume state from a WebSocket callback that fires
+ * long after the job handler returned, so the scope is captured up front from
+ * the channel row the job loaded and replayed on every write.
+ */
+export type DiscordChannelScope = {
+  tenantId: string
+  organizationId: string | null
+}
+
+/** The gateway-owned subset of `channelState` this store is allowed to write. */
+export type DiscordChannelStatePatch = {
+  sessionId?: string
+  sequence?: number | null
+  resumeGatewayUrl?: string
+  botUserId?: string
+}
+
+export type PersistDiscordChannelStateResult = 'written' | 'skipped' | 'not_found'
+
+/**
+ * Merge a gateway resume-state patch onto the state currently stored on the
+ * channel row, or return `null` when the patch must not be written.
+ *
+ * Two rules make this safe against the socket callbacks racing each other:
+ *
+ * - Only the gateway-owned keys are touched; every other key (`aiAutoReplyEnabled`,
+ *   `aiAgentId`, operator-set fields) is carried forward from the row that was
+ *   just read, so a concurrent UI edit is never clobbered wholesale.
+ * - A patch that would rewind the sequence of the session already stored is
+ *   dropped. A late `READY` callback from a superseded socket must not overwrite
+ *   fresher resume state with a stale cursor.
+ */
+export function mergeDiscordChannelState(
+  currentRaw: unknown,
+  patch: DiscordChannelStatePatch,
+  now: Date,
+): DiscordChannelState | null {
+  const current = discordChannelStateSchema.parse(currentRaw ?? {})
+  const sameSession = Boolean(patch.sessionId) && patch.sessionId === current.sessionId
+  const rewindsSequence =
+    sameSession &&
+    typeof patch.sequence === 'number' &&
+    typeof current.sequence === 'number' &&
+    patch.sequence < current.sequence
+  if (rewindsSequence) return null
+
+  return {
+    ...current,
+    ...patch,
+    lastConnectedAt: now.toISOString(),
+  }
+}
+
+/**
+ * Scoped read-modify-write of a Discord channel's gateway resume state.
+ *
+ * The lookup filters by `tenant_id` / `organization_id` (never by id alone) so a
+ * socket callback can only ever touch the row its own channel scope owns, and it
+ * runs on its own `EntityManager` fork so the flush never rides on the request
+ * context the worker job was started from.
+ */
+export async function persistDiscordChannelState(params: {
+  em: EntityManager
+  channelId: string
+  scope: DiscordChannelScope
+  patch: DiscordChannelStatePatch
+  now?: Date
+}): Promise<PersistDiscordChannelStateResult> {
+  const fork = params.em.fork()
+  const channel = await findOneWithDecryption(
+    fork,
+    CommunicationChannel,
+    {
+      id: params.channelId,
+      tenantId: params.scope.tenantId,
+      organizationId: params.scope.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    {
+      tenantId: params.scope.tenantId,
+      organizationId: params.scope.organizationId ?? params.scope.tenantId,
+    },
+  )
+  if (!channel) return 'not_found'
+
+  const merged = mergeDiscordChannelState(channel.channelState, params.patch, params.now ?? new Date())
+  if (!merged) return 'skipped'
+
+  channel.channelState = merged
+  await fork.flush()
+  return 'written'
+}
+
+export type RecordAutoReplyOutcomeResult = 'written' | 'unchanged' | 'not_found'
+
+/** Truncated so a provider stack trace cannot grow the JSONB column without bound. */
+const AUTO_REPLY_ERROR_MAX_LENGTH = 500
+
+/**
+ * Record — or clear — why the last AI auto-reply attempt on this channel produced
+ * nothing.
+ *
+ * The subscriber degrades every failure to a no-op on purpose: a broken model, a
+ * denied policy check or a malformed object must never turn into a send. Being
+ * *silent* about it is the part that hurts, because the operator's surface still
+ * reads "Auto-reply on" while the channel answers nothing, and a `logger.warn` in
+ * a background subscriber is not somewhere anyone looks. A save-time check cannot
+ * close this on its own either — the settings route validates the agent against
+ * the auto-reply principal, but a role edited afterwards makes that verdict stale.
+ *
+ * `failure: null` clears the marker, and the caller is expected to skip the write
+ * when there is nothing to clear — a successful reply on a healthy channel must
+ * not cost a row update per inbound message.
+ *
+ * The channel row's own `lastError` is deliberately left alone: the hub owns it
+ * for delivery and polling failures, clears it on a successful poll, and keys the
+ * reauth banner off `status`. Borrowing it here would let an AI failure mask a
+ * delivery failure and let a successful poll erase an AI one.
+ */
+export async function recordDiscordAutoReplyOutcome(params: {
+  em: EntityManager
+  channelId: string
+  scope: DiscordChannelScope
+  failure: string | null
+  now?: Date
+}): Promise<RecordAutoReplyOutcomeResult> {
+  const fork = params.em.fork()
+  const channel = await findOneWithDecryption(
+    fork,
+    CommunicationChannel,
+    {
+      id: params.channelId,
+      tenantId: params.scope.tenantId,
+      organizationId: params.scope.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    {
+      tenantId: params.scope.tenantId,
+      organizationId: params.scope.organizationId ?? params.scope.tenantId,
+    },
+  )
+  if (!channel) return 'not_found'
+
+  const current = discordChannelStateSchema.parse(channel.channelState ?? {})
+  const failure = params.failure?.slice(0, AUTO_REPLY_ERROR_MAX_LENGTH) ?? null
+  if (failure === null && current.aiAutoReplyLastError === undefined) return 'unchanged'
+  if (failure !== null && current.aiAutoReplyLastError === failure) return 'unchanged'
+
+  const next: DiscordChannelState = { ...current }
+  if (failure === null) {
+    delete next.aiAutoReplyLastError
+    delete next.aiAutoReplyLastErrorAt
+  } else {
+    next.aiAutoReplyLastError = failure
+    next.aiAutoReplyLastErrorAt = (params.now ?? new Date()).toISOString()
+  }
+
+  channel.channelState = next
+  await fork.flush()
+  return 'written'
+}
+
+export type QuarantineDiscordChannelResult = 'quarantined' | 'not_found'
+
+/**
+ * Park a channel Discord has fatally rejected so the reconciler stops re-opening it.
+ *
+ * A `4004` (invalid token) or `4014` (disallowed intents) close is not
+ * recoverable by retrying: the token or the Developer Portal toggle has to
+ * change first. Without a persisted status the refresh job sees "no live
+ * session" on the next tick and IDENTIFYs again — at the CLI's default 60s
+ * refresh that is ~1440 session starts per day against Discord's ~1000/day
+ * per-bot budget, while the row and the admin UI still read `connected`.
+ *
+ * Writing `requires_reauth` mirrors what the hub already does for a channel
+ * whose credentials could not be persisted (`connect-channel.ts`), so the
+ * existing reauth banner, the mutation guard that keys on `status`, and the
+ * operator's reconnect flow all engage without any hub change.
+ */
+export async function quarantineDiscordChannel(params: {
+  em: EntityManager
+  channelId: string
+  scope: DiscordChannelScope
+  reason: string
+}): Promise<QuarantineDiscordChannelResult> {
+  const fork = params.em.fork()
+  const channel = await findOneWithDecryption(
+    fork,
+    CommunicationChannel,
+    {
+      id: params.channelId,
+      tenantId: params.scope.tenantId,
+      organizationId: params.scope.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    {
+      tenantId: params.scope.tenantId,
+      organizationId: params.scope.organizationId ?? params.scope.tenantId,
+    },
+  )
+  if (!channel) return 'not_found'
+
+  channel.status = 'requires_reauth'
+  channel.lastError = params.reason
+  await fork.flush()
+  return 'quarantined'
+}

package/src/modules/channel_discord/lib/convert-outbound.ts

@@ -0,0 +1,88 @@
+import type {
+  ChannelNativeContent,
+  ConvertOutboundInput,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { DISCORD_MAX_BODY_LENGTH } from './capabilities'
+
+const logger = createLogger('channel_discord').child({ component: 'convert-outbound' })
+
+/**
+ * Very small HTML → markdown down-converter for the common inline tags the hub's
+ * `html` body format produces. Discord content is markdown-native, so we map the
+ * handful of tags that have a markdown equivalent and strip the rest rather than
+ * pulling in a full HTML parser dependency.
+ */
+function htmlToMarkdown(html: string): string {
+  return html
+    .replace(/<\s*br\s*\/?\s*>/gi, '\n')
+    .replace(/<\s*\/\s*p\s*>/gi, '\n\n')
+    .replace(/<\s*p[^>]*>/gi, '')
+    .replace(/<\s*(strong|b)\s*>(.*?)<\s*\/\s*\1\s*>/gis, '**$2**')
+    .replace(/<\s*(em|i)\s*>(.*?)<\s*\/\s*\1\s*>/gis, '*$2*')
+    .replace(/<\s*code\s*>(.*?)<\s*\/\s*code\s*>/gis, '`$1`')
+    .replace(/<\s*a[^>]*href=["']([^"']+)["'][^>]*>(.*?)<\s*\/\s*a\s*>/gis, '[$2]($1)')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+/**
+ * Convert the hub's normalized outbound body into Discord native content.
+ *
+ * - `markdown` / `text` pass through unchanged (Discord is markdown-native).
+ * - `html` is down-converted to markdown.
+ * - Content is clamped to Discord's 2000-char hard limit (a longer body is
+ *   truncated with an ellipsis marker rather than rejected by the API).
+ * - `allowed_mentions` defaults to `{ parse: [] }` so an AI/automated reply can
+ *   never accidentally @-ping everyone; callers can widen it via `channelMetadata`.
+ * - Attachments are NOT uploaded: `discord-rest` has no multipart upload, so the
+ *   capability profile declares `fileSharing: false` and the hub should never
+ *   route an attachment here. If one arrives anyway we log it rather than drop
+ *   it silently, and report the count in `metadata.droppedAttachmentCount` so the
+ *   caller can surface the gap.
+ */
+export async function convertOutboundForDiscord(input: ConvertOutboundInput): Promise<ChannelNativeContent> {
+  const droppedAttachmentCount = input.attachments?.length ?? 0
+  if (droppedAttachmentCount > 0) {
+    logger.warn('discord outbound attachments are not supported — sending text only', {
+      droppedAttachmentCount,
+    })
+  }
+
+  const raw = input.body ?? ''
+  const markdown = input.bodyFormat === 'html' ? htmlToMarkdown(raw) : raw
+
+  const TRUNCATE_MARKER = '…'
+  const content =
+    markdown.length > DISCORD_MAX_BODY_LENGTH
+      ? markdown.slice(0, DISCORD_MAX_BODY_LENGTH - TRUNCATE_MARKER.length) + TRUNCATE_MARKER
+      : markdown
+
+  const allowedMentions =
+    (input.channelMetadata?.allowedMentions as Record<string, unknown> | undefined) ?? { parse: [] }
+
+  return {
+    content: {
+      text: content,
+      bodyFormat: 'markdown',
+    },
+    metadata: {
+      allowedMentions,
+      droppedAttachmentCount,
+      // Reply threading, dormant: no hub producer writes `replyToExternalId`
+      // into outbound metadata today, which is why `capabilities.threading` is
+      // declared `false`. Kept so that flag flips back with the hub-side
+      // producer and nothing else.
+      messageReferenceId:
+        typeof input.channelMetadata?.replyToExternalId === 'string'
+          ? (input.channelMetadata.replyToExternalId as string)
+          : undefined,
+    },
+  }
+}

package/src/modules/channel_discord/lib/credentials.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod'
+
+/**
+ * Discord bot channel credentials (SPEC 2026-06-19 § Data models).
+ *
+ * The hub persists this blob inside `IntegrationCredentials.credentials`
+ * (encrypted at rest, scope `channel_discord`). Never log any value — the bot
+ * token grants full control of the bot user.
+ *
+ * `.passthrough()` (not `.strict()`) so the connect-credential-channel command
+ * can stash bookkeeping fields (e.g. `userId`) alongside the entered credentials,
+ * mirroring the IMAP provider.
+ */
+export const discordCredentialsSchema = z
+  .object({
+    // "Bot <token>" — used as `Authorization: Bot <token>` on every REST call and
+    // for the gateway Identify handshake. Never logged.
+    botToken: z.string().min(1, 'Bot token required'),
+    // Application (client) id — needed to register slash commands + build invites.
+    applicationId: z.string().min(1, 'Application ID required'),
+    // Ed25519 public key (hex) from the application's General Information tab —
+    // verifies signed interaction requests. Never used as a secret; safe to store.
+    publicKey: z
+      .string()
+      .min(1, 'Public key required')
+      .regex(/^[0-9a-fA-F]+$/, 'Public key must be hex')
+      .refine((value) => value.length === 64, 'Public key must be a 32-byte (64 hex char) Ed25519 key'),
+    // Scope the bot to one guild (recommended). Optional.
+    guildId: z.string().optional(),
+    // Default outbound text channel id (used by the test-send smoke test).
+    defaultChannelId: z.string().optional(),
+  })
+  .passthrough()
+
+export type DiscordCredentials = z.infer<typeof discordCredentialsSchema>
+
+/**
+ * Gateway resume state persisted on `CommunicationChannel.channelState` (JSONB,
+ * additive) so the worker can `RESUME` instead of re-`IDENTIFY` after a
+ * disconnect. Discord requires the stored `resumeGatewayUrl` + `sessionId` +
+ * last `sequence` to resume a session.
+ */
+export const discordChannelStateSchema = z
+  .object({
+    sessionId: z.string().optional(),
+    sequence: z.number().nullable().optional(),
+    resumeGatewayUrl: z.string().optional(),
+    // Bot's own user id — cached after the READY event so the worker can drop
+    // events it authored (feedback-loop guard) without an extra REST call.
+    botUserId: z.string().optional(),
+    lastConnectedAt: z.string().optional(),
+    // Per-channel AI auto-reply toggle (default OFF). When truthy, the AI
+    // auto-reply subscriber may answer "easy" inbound messages and proposes a
+    // reply for everything else. Written by the channel's AI auto-reply settings
+    // form via `PUT /api/channel_discord/channels/{id}/ai-auto-reply`.
+    aiAutoReplyEnabled: z.boolean().optional(),
+    // Object-mode agent id invoked when auto-reply is enabled. Defaults to the
+    // provider's own `channel_discord.auto_reply` agent; a tenant may point it at
+    // any object-mode agent whose `requiredFeatures` its channel-bot user holds.
+    aiAgentId: z.string().optional(),
+    // Why the last auto-reply attempt produced nothing, cleared by the next
+    // attempt that gets somewhere. The settings route validates a channel's agent
+    // against the auto-reply principal before arming it, but a role edit after the
+    // fact can still make the runtime start denying the call — and the subscriber
+    // degrades to a no-op by design, because a broken model must never become a
+    // send. Without a persisted marker that leaves an "Auto-reply on" channel
+    // answering nothing with nothing for an operator to look at. Written only by
+    // `lib/channel-state-store.ts`, never by the subscriber directly.
+    aiAutoReplyLastError: z.string().optional(),
+    // When the *current* failure was first observed. A channel that keeps failing
+    // for the same reason does not rewrite the row on every inbound message, so
+    // this is a first-seen stamp rather than a last-attempt one — the alternative
+    // is a row update per message on exactly the channels already misbehaving.
+    aiAutoReplyLastErrorAt: z.string().optional(),
+  })
+  .partial()
+  .passthrough()
+
+export type DiscordChannelState = z.infer<typeof discordChannelStateSchema>
+
+export function parseDiscordCredentialsOrThrow(value: unknown): DiscordCredentials {
+  const parsed = discordCredentialsSchema.safeParse(value)
+  if (!parsed.success) {
+    const first = parsed.error.issues[0]
+    throw new Error(`[internal] Invalid Discord credentials: ${first?.message ?? 'unknown validation error'}`)
+  }
+  return parsed.data
+}