Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
96.6 KB
Raw Blame
import { randomBytes } from 'node:crypto'
import http from 'node:http'
import { validateCommunicationChannelConfig } from './channelConfigValidation'
import { EmailAdapter, SlackAdapter, TeamsAdapter, TelegramAdapter } from './channels'
import { config } from './config'
import { CredentialsResolver, DevCredentialsResolver, ResolvedCredentials } from './credentials'
import {
  type SlackEnrollmentHandoff,
  type SlackHandoffRequest,
  type SlackHandoffResponse,
  type SlackMessageHandoff,
  type TeamsEnrollmentHandoff,
  type TeamsFileConsentHandoff,
  type TeamsHandoffRequest,
  type TeamsMessageHandoff,
  createChannelReaderHandoffServer,
} from './handoffServer'
import type { NotificationDeliveryClient } from './notificationDeliveryClient'
import { createProgressStream } from './progressClient'
import { formatFinalMessage, formatProgressUpdate } from './progressFormatter'
import { type ChannelReaderRuntimeSource, MessageResponse, RPCClient } from './rpcClient'
import { type TraceContextV1, mintChannelTraceContext } from './traceContext'
import {
  Attachment,
  ChannelAdapter,
  CommunicationChannelCRD,
  CommunicationChannelSpec,
  Message,
  ProgressStep,
  ProviderTargetIdentity,
  SendMessageOptions,
  TelegramProviderChatType,
} from './types'
import { WorkflowApprovalCoordinator } from './workflowApprovalCoordinator'
import {
  contentWithoutAddressedBotMention,
  parseWorkflowApprovalDecisionCallback,
  parseWorkflowApprovalDecisionCommand,
} from './workflowApprovalDecision'

// Only import k8s client in production mode
let CommunicationChannelWatcher: typeof import('./k8sClient').CommunicationChannelWatcher

/**
 * Read the pod's own namespace from the Kubernetes downward-API ServiceAccount
 * file. Returns 'channels' as a safe default when the file is absent (dev/test).
 */
async function readPodNamespace(): Promise<string> {
  try {
    const { readFile } = await import('fs/promises')
    const nsPath = '/var/run/secrets/kubernetes.io/serviceaccount/namespace'
    const ns = await readFile(nsPath, 'utf8')
    return ns.trim() || 'channels'
  } catch {
    return 'channels'
  }
}

/**
 * Namespace where channel-reader resolves CC.spec.credentialsSecretRef Secrets.
 * Uses the reader's OWN namespace (CLERUM_NAMESPACE); falls back first to the
 * pod's self-derived namespace (downward-API SA file) and then to 'channels'
 * for single-tenant Clerum where CLERUM_NAMESPACE is empty and the reader runs
 * in 'channels'. In multi-tenant (MCC) deployments CLERUM_NAMESPACE is the
 * slug-scoped 'channels-<slug>' namespace where the credentials Secret lives —
 * a hardcoded 'channels' there 403s.
 */
export async function resolveCredentialsNamespace(clerumNamespace: string): Promise<string> {
  if (clerumNamespace) return clerumNamespace
  return readPodNamespace() // env empty → self-derive from downward API file
}

/**
 * Tracks a pending approval for a user/channel so channel-reader can
 * intercept /approve and /deny commands and poll for the final result.
 */
interface PendingApprovalState {
  taskId: string
  requestId: string
  userId: string
  channelType: 'telegram' | 'email' | 'slack' | 'teams'
  channelId: string
  originalMessage: Message
  createdAt: Date
  actionToken: string
  startResultPollingFallback?: () => void
  updateStatusAfterDecision?: (content: string) => Promise<void>
}

interface ProcessedProviderEvent {
  seenAt: number
}

/** Stale approval entries are cleaned up after this interval. */
const PENDING_APPROVAL_TTL_MS = 10 * 60 * 1000 // 10 minutes
const RESULT_POLL_FALLBACK_INTERVAL_MS = 2 * 1000
const RESULT_POLL_FALLBACK_TIMEOUT_MS = 30 * 60 * 1000
/** Telegram and Slack can redeliver the same provider event while poll offsets settle. */
const PROVIDER_EVENT_DEDUPE_TTL_MS = 10 * 60 * 1000 // 10 minutes
/** One "you are not linked" notice per Slack user per conversation per day. */
const UNRESOLVED_NOTICE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
const UNRESOLVED_NOTICE_COPY =
  "I can't accept messages from this Slack account. If you haven't linked it yet on the " +
  'profile UI, open Settings > Social channels > Slack and choose Connect Slack. ' +
  'If you think you should already have access, contact your admin.'
const UNRESOLVED_NOTICE_COPY_TEAMS =
  "I can't accept messages from this Teams account. If you haven't linked it yet on the " +
  'profile UI, open Settings > Social channels > Teams and choose Connect Microsoft Teams. ' +
  'If you think you should already have access, contact your admin.'

/**
 * Profile UI tab that owns the Connect button for a provider.
 *
 * The bare Profile UI root lands the user on their profile with no sign of
 * where to go next, and the control they need is four levels in: Settings >
 * Social channels > <provider> > Connect. These are real App Router segments
 * (profile-ui/app/settings/social/[network]), not query params, so they are
 * safe to link directly.
 *
 * The copy above still names the path in words. A deep link can be defeated by
 * a sign-in redirect that drops the user at the root, and someone reading this
 * from a phone needs to be able to find the screen without the link.
 */
const PROFILE_SOCIAL_CHANNEL_PATH: Partial<Record<ChannelType, string>> = {
  slack: '/settings/social/slack',
  teams: '/settings/social/teams',
}

/**
 * Profile UI link for the tab where `channelType` is linked. Falls back to the
 * configured base URL for a provider with no such tab, so a new channel type
 * degrades to today's behaviour rather than emitting a 404 path.
 */
export function profileSocialChannelUrl(baseUrl: string, channelType: ChannelType): string {
  const trimmed = baseUrl.trim()
  // Trailing slashes are walked off by index rather than matched with /\/+$/.
  // An end-anchored `+` over a run of the same character backtracks
  // polynomially (CodeQL js/polynomial-redos), and profileUiUrl is deployment
  // config that arrives here unvalidated. The walk is linear and needs no
  // reasoning about the regex engine to stay that way.
  let end = trimmed.length
  while (end > 0 && trimmed.charCodeAt(end - 1) === 47 /* '/' */) end--
  return `${trimmed.slice(0, end)}${PROFILE_SOCIAL_CHANNEL_PATH[channelType] ?? ''}`
}
// Telegram deliberately gets no Profile UI link and no product name: unlike Teams
// and Slack, anyone who discovers the bot handle can message it, so a reply must
// not confirm what the bot belongs to.
const UNRESOLVED_NOTICE_COPY_TELEGRAM =
  "I can't accept messages from this account. If you think that is wrong, contact your administrator."
/**
 * Ceiling on live notice records, so a misconfiguration cannot turn the bot
 * into a flooder. Exported so tests assert against the real value.
 */
export const UNRESOLVED_NOTICE_GLOBAL_CAP = 50
/**
 * Limiter key prefix for a provider identity with no workspace/tenant scope.
 * Only Telegram ever reaches this: Slack and Teams identities always carry a
 * real workspaceId (sendUnresolvedSenderNotice returns early otherwise), so
 * this literal can never collide with an actual workspace or tenant id.
 */
const UNRESOLVED_NOTICE_NO_WORKSPACE_KEY = 'no-workspace'
const SLACK_VERIFICATION_SCAN_INTERVAL_MS = 60 * 1000
const TOOL_APPROVAL_ACTION_RE = /^tool:([ald]):([A-Za-z0-9_-]{16})$/
/**
 * Periodic CommunicationChannel resync interval (production mode only).
 * Even when no watch event fires, a re-list every 60 s self-heals missed
 * events from earlier reconnect gaps.
 */
export const CHANNEL_RESYNC_INTERVAL_MS = 60_000 // 60 seconds

type ToolApprovalDecision = '/approve' | '/approve always' | '/deny'

function newToolApprovalActionToken(): string {
  return randomBytes(12).toString('base64url')
}

function toolApprovalActionValue(
  decision: 'approve' | 'approveAlways' | 'deny',
  actionToken: string
): string {
  const code = decision === 'approve' ? 'a' : decision === 'approveAlways' ? 'l' : 'd'
  return `tool:${code}:${actionToken}`
}

function parseToolApprovalAction(content: string): {
  command: ToolApprovalDecision
  actionToken: string
} | null {
  const match = TOOL_APPROVAL_ACTION_RE.exec(content.trim())
  if (!match) return null
  return {
    command: match[1] === 'a' ? '/approve' : match[1] === 'l' ? '/approve always' : '/deny',
    actionToken: match[2],
  }
}

function toolApprovalMessageOptions(
  channelType: Message['channelType'],
  notification: string,
  actionToken: string
): SendMessageOptions | undefined {
  const approve = toolApprovalActionValue('approve', actionToken)
  const approveAlways = toolApprovalActionValue('approveAlways', actionToken)
  const deny = toolApprovalActionValue('deny', actionToken)
  if (channelType === 'telegram') {
    return {
      telegramInlineKeyboard: [
        [
          { text: 'Approve', callbackData: approve },
          { text: 'Deny', callbackData: deny },
        ],
        [{ text: 'Always approve', callbackData: approveAlways }],
      ],
    }
  }
  if (channelType === 'slack') {
    return {
      slackBlocks: [
        { type: 'section', text: { type: 'mrkdwn', text: notification } },
        {
          type: 'actions',
          block_id: `tool_approval_${actionToken}`,
          elements: [
            {
              type: 'button',
              action_id: 'tool_approval_approve',
              text: { type: 'plain_text', text: 'Approve' },
              value: approve,
              style: 'primary',
            },
            {
              type: 'button',
              action_id: 'tool_approval_always',
              text: { type: 'plain_text', text: 'Always approve' },
              value: approveAlways,
            },
            {
              type: 'button',
              action_id: 'tool_approval_deny',
              text: { type: 'plain_text', text: 'Deny' },
              value: deny,
              style: 'danger',
            },
          ],
        },
      ],
    }
  }
  if (channelType === 'teams') {
    return {
      teamsActions: [
        { title: 'Approve', value: approve, style: 'positive' },
        { title: 'Always approve', value: approveAlways },
        { title: 'Deny', value: deny, style: 'destructive' },
      ],
    }
  }
  return undefined
}

function supportedTelegramOperationalChatType(value: unknown): TelegramProviderChatType | null {
  return value === 'private' || value === 'group' || value === 'supergroup' ? value : null
}

function providerTargetFromChannel(
  channelCRD: CommunicationChannelCRD
): ProviderTargetIdentity | null {
  const hostRef = channelCRD.spec.hostRef?.trim()
  const communicationChannelName = channelCRD.name?.trim()
  const communicationChannelNamespace = channelCRD.namespace?.trim()
  if (!hostRef || !communicationChannelName || !communicationChannelNamespace) return null
  return { hostRef, communicationChannelNamespace, communicationChannelName }
}

function hasSlackChannelConfig(spec: CommunicationChannelSpec): boolean {
  if (spec.slack && spec.slack.length > 0) return true
  const settings = spec.slackSettings
  return !!(settings?.workspaceId?.trim() || settings?.botHandle?.trim())
}

function hasTeamsChannelConfig(spec: CommunicationChannelSpec): boolean {
  if (spec.teams && spec.teams.length > 0) return true
  const settings = spec.teamsSettings
  return !!(
    settings?.tenantId?.trim() ||
    settings?.appId?.trim() ||
    settings?.appName?.trim() ||
    settings?.replyOnlyWhenMentioned !== undefined
  )
}

type ChannelReaderRpcClient = Pick<
  RPCClient,
  | 'healthCheck'
  | 'sendMessage'
  | 'getBaseUrl'
  | 'getTaskResult'
  | 'sendApproval'
  | 'sendDenial'
  | 'sendWorkflowApprovalDecision'
  | 'resolveWorkflowApproval'
  | 'fetchDeliveries'
  | 'acknowledge'
  | 'fail'
  | 'confirmTelegramChallenge'
  | 'getCronResults'
  | 'acknowledgeCronResult'
> & {
  authorizeProviderMessage?: RPCClient['authorizeProviderMessage']
  downloadWorkflowResultByRun?: RPCClient['downloadWorkflowResultByRun']
  confirmSlackLinkSession?: RPCClient['confirmSlackLinkSession']
  confirmTeamsLinkSession?: RPCClient['confirmTeamsLinkSession']
}

type ChannelType = ChannelAdapter['channelType']
type CommunicationChannelRef = {
  namespace: string
  name: string
}

export interface ChannelReaderOptions {
  rpcClient?: ChannelReaderRpcClient
  notificationDeliveryClient?: NotificationDeliveryClient | null
  adapters?: Map<string, ChannelAdapter>
  channels?: CommunicationChannelCRD[]
  sleep?: (ms: number) => Promise<void>
  credentialsResolver?: { resolve(cc: CommunicationChannelCRD): Promise<ResolvedCredentials> }
}

export class ChannelReader {
  private watcher?: InstanceType<typeof CommunicationChannelWatcher>
  private adapters: Map<string, ChannelAdapter> = new Map()
  private channels: CommunicationChannelCRD[] = []
  private running: boolean = false
  private needsRestart: boolean = false
  private rpcClient: ChannelReaderRpcClient
  private notificationDeliveryClient: NotificationDeliveryClient | null
  private sleepImpl: (ms: number) => Promise<void>
  private credentialsResolver: {
    resolve(cc: CommunicationChannelCRD): Promise<ResolvedCredentials>
  } | null
  /** Pending approvals keyed by provider conversation/thread and sender. */
  private pendingApprovals: Map<string, PendingApprovalState> = new Map()
  /** Recently processed provider events keyed by stable provider or channel message identity. */
  private processedProviderEvents: Map<string, ProcessedProviderEvent> = new Map()
  /** Unresolved-sender notices already sent, keyed by workspace + user + channel. */
  private unresolvedNoticesSent: Map<string, { seenAt: number }> = new Map()
  /**
   * Whether the global-cap warning below has already logged for the current
   * capped episode. Reset to false once cleanupStaleApprovals' TTL sweep drains
   * unresolvedNoticesSent back under UNRESOLVED_NOTICE_GLOBAL_CAP, so a later
   * trip into the cap logs again instead of staying silent forever.
   */
  private unresolvedNoticeCapLogged = false
  /** Adapter route key by provider + CommunicationChannel ref. */
  private adapterKeysByCommunicationChannel: Map<string, string> = new Map()
  /** Adapter route key by provider + runtime channel id. */
  private adapterKeysByRuntimeChannel: Map<string, string> = new Map()
  /** Default adapter route key by provider for legacy/generic delivery paths. */
  private defaultAdapterKeyByChannelType: Map<ChannelType, string> = new Map()
  /** Last full Slack conversation scan by CommunicationChannel target key. */
  private lastSlackVerificationScanAtByTarget: Map<string, number> = new Map()
  private handoffServer: http.Server | null = null
  private workflowApprovalCoordinator: WorkflowApprovalCoordinator
  /** Timestamp (Date.now()) of the last periodic CommunicationChannel resync. */
  private lastChannelResyncAt: number = 0

  constructor(options: ChannelReaderOptions = {}) {
    if (options.rpcClient) {
      this.rpcClient = options.rpcClient
    } else {
      this.rpcClient = new RPCClient(config.mcpHostUrl)
    }
    this.notificationDeliveryClient =
      options.notificationDeliveryClient === undefined
        ? this.rpcClient
        : options.notificationDeliveryClient
    this.adapters = options.adapters ?? new Map()
    this.channels = options.channels ?? []
    this.sleepImpl = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)))
    this.credentialsResolver = options.credentialsResolver ?? null
    this.workflowApprovalCoordinator = new WorkflowApprovalCoordinator({
      rpcClient: this.rpcClient,
      notificationDeliveryClient: this.notificationDeliveryClient,
      getAdapters: () => this.adapters,
      getChannels: () => this.channels,
      getAdapterForChannel: (medium, channelRef) =>
        this.adapterForCommunicationChannelRef(medium, channelRef),
      sendReply: (message, content) => this.sendReply(message, content),
    })
  }

  async initialize(): Promise<void> {
    if (!config.devMode) {
      // Dynamically import k8s client only in production mode
      const k8sModule = await import('./k8sClient')
      CommunicationChannelWatcher = k8sModule.CommunicationChannelWatcher

      this.watcher = new CommunicationChannelWatcher(config.hostRef, config.namespace)

      // Set up change handler
      this.watcher.onChange(channels => {
        console.log(`[Main] CommunicationChannel CRDs changed, scheduling restart...`)
        this.needsRestart = true
      })
    }

    if (!this.credentialsResolver) {
      if (config.devMode) {
        this.credentialsResolver = new DevCredentialsResolver()
      } else {
        const k8s = await import('@kubernetes/client-node')
        const kc = new k8s.KubeConfig()
        kc.loadFromCluster()
        const coreApi = kc.makeApiClient(k8s.CoreV1Api)
        const credentialsNamespace = await resolveCredentialsNamespace(config.namespace)
        this.credentialsResolver = new CredentialsResolver(coreApi, credentialsNamespace)
      }
    }

    // Check if mcp-host is reachable
    console.log(`[Main] Checking mcp-host connectivity at ${config.mcpHostUrl}...`)
    const healthy = await this.rpcClient.healthCheck()
    if (healthy) {
      console.log('[Main] mcp-host is reachable')
    } else {
      console.warn(
        '[Main] mcp-host is not reachable - messages will be queued until it becomes available'
      )
    }
  }

  validateChannelConfig(channelCRD: CommunicationChannelCRD): void {
    validateCommunicationChannelConfig(channelCRD)
  }

  private shouldRunSlackVerificationScan(scanKey: string): boolean {
    const now = Date.now()
    const lastRun = this.lastSlackVerificationScanAtByTarget.get(scanKey)
    if (lastRun === undefined) {
      this.lastSlackVerificationScanAtByTarget.set(scanKey, now)
      return true
    }
    if (now - lastRun < SLACK_VERIFICATION_SCAN_INTERVAL_MS) return false
    this.lastSlackVerificationScanAtByTarget.set(scanKey, now)
    return true
  }

  /**
   * Initialize channel adapters for configured channels. If no channels are
   * loaded yet (zero CRDs match the hostRef filter), logs a warning and
   * returns. The CRD watcher will trigger a restart when channels appear.
   */
  async initializeAdapters(): Promise<void> {
    console.log('[Main] Initializing channel adapters...')
    this.adapterKeysByCommunicationChannel.clear()
    this.adapterKeysByRuntimeChannel.clear()
    this.defaultAdapterKeyByChannelType.clear()

    for (const channel of this.channels) {
      this.validateChannelConfig(channel)
    }

    const ccsWithTelegram = this.channels.filter(
      c =>
        (c.spec.telegram && c.spec.telegram.length > 0) ||
        (c.spec.telegramSettings &&
          typeof c.spec.telegramSettings === 'object' &&
          !Array.isArray(c.spec.telegramSettings))
    )
    const ccsWithEmail = this.channels.filter(c => c.spec.email && c.spec.email.length > 0)
    const ccsWithSlack = this.channels.filter(c => hasSlackChannelConfig(c.spec))
    const ccsWithTeams = this.channels.filter(c => hasTeamsChannelConfig(c.spec))

    console.log(`[Main] needsTelegram: ${ccsWithTelegram.length > 0}`)
    console.log(`[Main] needsEmail: ${ccsWithEmail.length > 0}`)
    console.log(`[Main] needsSlack: ${ccsWithSlack.length > 0}`)
    console.log(`[Main] needsTeams: ${ccsWithTeams.length > 0}`)

    if (
      ccsWithTelegram.length === 0 &&
      ccsWithEmail.length === 0 &&
      ccsWithSlack.length === 0 &&
      ccsWithTeams.length === 0
    ) {
      console.warn(
        '[Main] No channel adapters to initialize yet. Waiting for CommunicationChannel CRDs to be created.'
      )
      return
    }

    // Build per-channel-type credential winner. Conflict policy: pick the
    // CC whose name sorts first (localeCompare en) and log a warning.
    const resolved = new Map<string, ResolvedCredentials>()
    if (this.credentialsResolver) {
      for (const cc of this.channels) {
        resolved.set(cc.name, await this.credentialsResolver.resolve(cc))
      }
    }

    const pickToken = (
      ccs: CommunicationChannelCRD[],
      channelType: 'telegram' | 'slack' | 'email',
      pluck: (r: ResolvedCredentials) => string | undefined
    ): { creds: ResolvedCredentials | undefined; sourceChannel?: CommunicationChannelCRD } => {
      const withCreds = ccs
        .map(cc => ({
          cc,
          name: cc.name,
          token: pluck(resolved.get(cc.name) ?? {}),
          creds: resolved.get(cc.name),
        }))
        .filter(({ token }) => !!token)
        .sort((a, b) => a.name.localeCompare(b.name, 'en'))
      if (withCreds.length === 0) return { creds: undefined }
      const distinctTokens = new Set(withCreds.map(c => c.token))
      if (distinctTokens.size > 1) {
        const losers = withCreds
          .slice(1)
          .map(c => c.name)
          .join(', ')
        console.warn(
          `[Main] WARN: multiple CCs with different credentialsSecretRef for ${channelType}; using ${withCreds[0].name}'s token (losers: ${losers}). PR2 will lift this.`
        )
      }
      return { creds: withCreds[0].creds, sourceChannel: withCreds[0].cc }
    }

    if (ccsWithTelegram.length > 0) {
      const withTelegramCreds = ccsWithTelegram
        .map(cc => ({
          cc,
          token: resolved.get(cc.name)?.telegramBotToken,
        }))
        .filter((entry): entry is { cc: CommunicationChannelCRD; token: string } =>
          Boolean(entry.token)
        )
        .sort((a, b) => a.cc.name.localeCompare(b.cc.name, 'en'))
      const groupsByToken = new Map<string, CommunicationChannelCRD[]>()
      for (const entry of withTelegramCreds) {
        const current = groupsByToken.get(entry.token) ?? []
        current.push(entry.cc)
        groupsByToken.set(entry.token, current)
      }
      const telegramCredentialGroups = [...groupsByToken.entries()]
      if (telegramCredentialGroups.length > 1) {
        console.log(
          `[Main] Initializing ${telegramCredentialGroups.length} Telegram adapters from CommunicationChannel credentials`
        )
      }
      for (const [telegramBotToken, ccs] of telegramCredentialGroups) {
        const sourceChannel = ccs[0]!
        const providerTargets = ccs
          .map(cc => providerTargetFromChannel(cc))
          .filter((target): target is ProviderTargetIdentity => target !== null)
        const adapterKey = `telegram:${sourceChannel.namespace}/${sourceChannel.name}`
        for (const cc of ccs) {
          this.bindAdapterToCommunicationChannel('telegram', cc, adapterKey)
        }
        this.defaultAdapterKeyByChannelType.set(
          'telegram',
          this.defaultAdapterKeyByChannelType.get('telegram') ?? adapterKey
        )
        const adapter = this.adapters.get(adapterKey) ?? new TelegramAdapter(this.rpcClient)
        await adapter.connect({
          telegramBotToken,
          providerTarget: providerTargetFromChannel(sourceChannel) ?? undefined,
          providerTargets,
        })
        this.adapters.set(adapterKey, adapter)
      }
    }

    if (ccsWithEmail.length > 0) {
      const { creds } = pickToken(ccsWithEmail, 'email', r => r.emailUsername)
      if (creds?.emailUsername && creds?.emailPassword) {
        const adapter = this.adapters.get('email') ?? new EmailAdapter()
        await adapter.connect({
          emailUsername: creds.emailUsername,
          emailPassword: creds.emailPassword,
        })
        this.adapters.set('email', adapter)
        for (const cc of ccsWithEmail) {
          this.bindAdapterToCommunicationChannel('email', cc, 'email')
        }
        this.defaultAdapterKeyByChannelType.set('email', 'email')
      }
    }

    if (ccsWithSlack.length > 0) {
      const withSlackCreds = ccsWithSlack
        .map(cc => ({
          cc,
          token: resolved.get(cc.name)?.slackBotToken,
        }))
        .filter((entry): entry is { cc: CommunicationChannelCRD; token: string } =>
          Boolean(entry.token)
        )
        .sort((a, b) => a.cc.name.localeCompare(b.cc.name, 'en'))
      const groupsByToken = new Map<string, CommunicationChannelCRD[]>()
      for (const entry of withSlackCreds) {
        const current = groupsByToken.get(entry.token) ?? []
        current.push(entry.cc)
        groupsByToken.set(entry.token, current)
      }
      const slackCredentialGroups = [...groupsByToken.entries()]
      if (slackCredentialGroups.length > 1) {
        console.log(
          `[Main] Initializing ${slackCredentialGroups.length} Slack adapters from CommunicationChannel credentials`
        )
      }
      for (const [slackBotToken, ccs] of slackCredentialGroups) {
        const sourceChannel = ccs[0]!
        const providerTargets = ccs
          .map(cc => providerTargetFromChannel(cc))
          .filter((target): target is ProviderTargetIdentity => target !== null)
        const adapterKey = `slack:${sourceChannel.namespace}/${sourceChannel.name}`
        for (const cc of ccs) {
          this.bindAdapterToCommunicationChannel('slack', cc, adapterKey)
        }
        this.defaultAdapterKeyByChannelType.set(
          'slack',
          this.defaultAdapterKeyByChannelType.get('slack') ?? adapterKey
        )
        const slackVerificationClient = this.rpcClient.confirmSlackLinkSession
          ? {
              confirmSlackLinkSession: (
                params: Parameters<RPCClient['confirmSlackLinkSession']>[0]
              ) => this.rpcClient.confirmSlackLinkSession!(params),
            }
          : null
        const adapter = this.adapters.get(adapterKey) ?? new SlackAdapter(slackVerificationClient)
        await adapter.connect({
          slackBotToken,
          providerTarget: providerTargetFromChannel(sourceChannel) ?? undefined,
          providerTargets,
        })
        this.adapters.set(adapterKey, adapter)
      }
    }

    if (ccsWithTeams.length > 0) {
      const withTeamsCreds = ccsWithTeams
        .map(cc => ({
          cc,
          appId: cc.spec.teamsSettings?.appId?.trim(),
          tenantId: cc.spec.teamsSettings?.tenantId?.trim(),
          password: resolved.get(cc.name)?.teamsAppPassword,
        }))
        .filter(
          (
            entry
          ): entry is {
            cc: CommunicationChannelCRD
            appId: string
            tenantId: string
            password: string
          } => Boolean(entry.appId && entry.tenantId && entry.password)
        )
        .sort((a, b) => a.cc.name.localeCompare(b.cc.name, 'en'))
      const groupsByCredential = new Map<string, typeof withTeamsCreds>()
      for (const entry of withTeamsCreds) {
        const key = `${entry.tenantId}\0${entry.appId}\0${entry.password}`
        const current = groupsByCredential.get(key) ?? []
        current.push(entry)
        groupsByCredential.set(key, current)
      }
      const teamsCredentialGroups = [...groupsByCredential.values()]
      if (teamsCredentialGroups.length > 1) {
        console.log(
          `[Main] Initializing ${teamsCredentialGroups.length} Teams adapters from CommunicationChannel credentials`
        )
      }
      for (const entries of teamsCredentialGroups) {
        const source = entries[0]!
        const ccs = entries.map(entry => entry.cc)
        const sourceChannel = source.cc
        const providerTargets = ccs
          .map(cc => providerTargetFromChannel(cc))
          .filter((target): target is ProviderTargetIdentity => target !== null)
        const serviceUrls = new Map<string, string>()
        for (const cc of ccs) {
          for (const group of cc.spec.teams ?? []) {
            const conversationId = group.channelId?.trim()
            const serviceUrl = group.serviceUrl?.trim()
            if (conversationId && serviceUrl) serviceUrls.set(conversationId, serviceUrl)
          }
        }
        const adapterKey = `teams:${sourceChannel.namespace}/${sourceChannel.name}`
        for (const cc of ccs) {
          this.bindAdapterToCommunicationChannel('teams', cc, adapterKey)
        }
        this.defaultAdapterKeyByChannelType.set(
          'teams',
          this.defaultAdapterKeyByChannelType.get('teams') ?? adapterKey
        )
        const adapter = this.adapters.get(adapterKey) ?? new TeamsAdapter()
        await adapter.connect({
          teamsAppId: source.appId,
          teamsTenantId: source.tenantId,
          teamsAppPassword: source.password,
          teamsServiceUrlsByConversationId: serviceUrls,
          providerTarget: providerTargetFromChannel(sourceChannel) ?? undefined,
          providerTargets,
        })
        this.adapters.set(adapterKey, adapter)
      }
    }

    if (this.adapters.size === 0) {
      console.warn(
        '[Main] No channel adapters connected — credentials may be missing. Set them via Control UI on the relevant CommunicationChannel.'
      )
      return
    }

    console.log(`[Main] Initialized ${this.adapters.size} channel adapter(s)`)
  }

  /**
   * Shutdown all channel adapters.
   */
  async shutdownAdapters(): Promise<void> {
    console.log('[Main] Shutting down channel adapters...')

    await Promise.all([...new Set(this.adapters.values())].map(adapter => adapter.disconnect()))

    this.adapters.clear()
    this.adapterKeysByCommunicationChannel.clear()
    this.adapterKeysByRuntimeChannel.clear()
    this.defaultAdapterKeyByChannelType.clear()
    console.log('[Main] Channel adapters shut down')
  }

  private communicationChannelKey(channel: CommunicationChannelRef): string {
    return `${channel.namespace}/${channel.name}`
  }

  private communicationChannelAdapterMapKey(
    channelType: ChannelType,
    channel: CommunicationChannelRef
  ): string {
    return `${channelType}:${this.communicationChannelKey(channel)}`
  }

  private runtimeChannelAdapterMapKey(channelType: ChannelType, channelId: string): string {
    return `${channelType}:${channelId}`
  }

  private runtimeChannelIdsForChannel(
    channelType: ChannelType,
    channel: CommunicationChannelCRD
  ): string[] {
    const groups =
      channelType === 'telegram'
        ? channel.spec.telegram
        : channelType === 'slack'
          ? channel.spec.slack
          : channelType === 'teams'
            ? channel.spec.teams
            : channel.spec.email
    return (groups ?? []).map(group => String(group.channelId || '').trim()).filter(Boolean)
  }

  private bindAdapterToCommunicationChannel(
    channelType: ChannelType,
    channel: CommunicationChannelCRD,
    adapterKey: string
  ): void {
    this.adapterKeysByCommunicationChannel.set(
      this.communicationChannelAdapterMapKey(channelType, channel),
      adapterKey
    )
    for (const channelId of this.runtimeChannelIdsForChannel(channelType, channel)) {
      this.adapterKeysByRuntimeChannel.set(
        this.runtimeChannelAdapterMapKey(channelType, channelId),
        adapterKey
      )
    }
  }

  private adapterForCommunicationChannelRef(
    channelType: ChannelType,
    channel: CommunicationChannelRef
  ): ChannelAdapter | undefined {
    const adapterKey = this.adapterKeysByCommunicationChannel.get(
      this.communicationChannelAdapterMapKey(channelType, channel)
    )
    if (adapterKey) {
      const adapter = this.adapters.get(adapterKey)
      if (adapter) return adapter
      console.warn(
        `[Main] Adapter key ${adapterKey} for ${channelType} CommunicationChannel ` +
          `${this.communicationChannelKey(channel)} is not initialized; using default adapter`
      )
    } else {
      console.warn(
        `[Main] No ${channelType} adapter key for CommunicationChannel ` +
          `${this.communicationChannelKey(channel)}; using default adapter`
      )
    }
    return this.adapterForChannelType(channelType)
  }

  private adapterForChannel(
    channelType: ChannelType,
    channel: CommunicationChannelCRD
  ): ChannelAdapter | undefined {
    return this.adapterForCommunicationChannelRef(channelType, channel)
  }

  private adapterForChannelType(channelType: ChannelType): ChannelAdapter | undefined {
    const defaultKey = this.defaultAdapterKeyByChannelType.get(channelType)
    if (defaultKey) return this.adapters.get(defaultKey)
    return this.adapters.get(channelType)
  }

  private adapterForMessage(message: Message): ChannelAdapter | undefined {
    const target = message.providerIdentity?.providerTarget
    if (target?.communicationChannelNamespace && target.communicationChannelName) {
      return this.adapterForCommunicationChannelRef(message.channelType, {
        namespace: target.communicationChannelNamespace,
        name: target.communicationChannelName,
      })
    }
    return this.adapterForChannelType(message.channelType)
  }

  private adapterForRuntimeSource(source: ChannelReaderRuntimeSource): ChannelAdapter | undefined {
    const adapterKey = this.adapterKeysByRuntimeChannel.get(
      this.runtimeChannelAdapterMapKey(source.channelType, source.channelId)
    )
    if (adapterKey) {
      const adapter = this.adapters.get(adapterKey)
      if (adapter) return adapter
      console.warn(
        `[Main] Adapter key ${adapterKey} for ${source.channelType} runtime channel ` +
          `${source.channelId} is not initialized; using default adapter`
      )
    } else {
      console.warn(
        `[Main] No ${source.channelType} adapter key for runtime channel ` +
          `${source.channelId}; using default adapter`
      )
    }
    return this.adapterForChannelType(source.channelType)
  }

  private slackMessageFromHandoff(handoff: SlackMessageHandoff): Message | null {
    const providerTarget = handoff.providerTarget
    if (
      !handoff.content?.trim() ||
      !handoff.providerUserId?.trim() ||
      !handoff.providerWorkspaceId?.trim() ||
      !handoff.providerChannelId?.trim() ||
      !handoff.providerEventId?.trim() ||
      !handoff.providerMessageTs?.trim() ||
      !providerTarget?.hostRef ||
      !providerTarget.communicationChannelNamespace ||
      !providerTarget.communicationChannelName
    ) {
      return null
    }

    const timestampMs = Number.parseFloat(handoff.providerMessageTs) * 1000
    return {
      channelType: 'slack',
      channelId: handoff.providerChannelId,
      sender: handoff.providerUserId,
      content: handoff.content,
      timestamp: Number.isFinite(timestampMs) ? new Date(timestampMs) : new Date(),
      messageId: handoff.providerMessageTs,
      ...(handoff.responseThreadTs ? { threadId: handoff.responseThreadTs } : {}),
      providerIdentity: {
        medium: 'slack',
        providerUserId: handoff.providerUserId,
        providerWorkspaceId: handoff.providerWorkspaceId,
        providerChannelId: handoff.providerChannelId,
        providerEventId: handoff.providerEventId,
        providerTarget,
      },
      rawData: handoff.rawData ?? {},
    }
  }

  private teamsMessageFromHandoff(handoff: TeamsMessageHandoff): Message | null {
    const providerTarget = handoff.providerTarget
    if (
      !handoff.content?.trim() ||
      !handoff.providerUserId?.trim() ||
      !handoff.providerWorkspaceId?.trim() ||
      !handoff.providerChannelId?.trim() ||
      !handoff.providerConversationId?.trim() ||
      !handoff.providerReplyToMessageId?.trim() ||
      !handoff.providerEventId?.trim() ||
      !handoff.providerMessageId?.trim() ||
      !handoff.serviceUrl?.trim() ||
      !providerTarget?.hostRef ||
      !providerTarget.communicationChannelNamespace ||
      !providerTarget.communicationChannelName
    ) {
      return null
    }

    return {
      channelType: 'teams',
      channelId: handoff.providerConversationId,
      sender: handoff.providerUserId,
      content: handoff.content,
      timestamp: new Date(),
      messageId: handoff.providerMessageId,
      threadId: handoff.providerReplyToMessageId,
      providerIdentity: {
        medium: 'teams',
        providerUserId: handoff.providerUserId,
        providerWorkspaceId: handoff.providerWorkspaceId,
        providerChannelId: handoff.providerChannelId,
        providerChannelType: handoff.providerChannelType ?? null,
        providerEventId: handoff.providerEventId,
        providerTarget,
      },
      rawData: {
        ...(handoff.rawData ?? {}),
        serviceUrl: handoff.serviceUrl,
      },
    }
  }

  private rememberTeamsConversation(
    providerTarget: ProviderTargetIdentity,
    channelId: string,
    serviceUrl: string
  ): void {
    const adapter = this.adapterForCommunicationChannelRef('teams', {
      namespace: providerTarget.communicationChannelNamespace,
      name: providerTarget.communicationChannelName,
    })
    if (adapter instanceof TeamsAdapter) {
      adapter.rememberConversation(channelId, serviceUrl)
    }
  }

  private async deliverProviderWorkflowResult(
    message: Message,
    workflowRunId: string
  ): Promise<void> {
    const adapter = this.adapterForMessage(message)
    if (!adapter) return
    if (!this.rpcClient.downloadWorkflowResultByRun) {
      await adapter.sendMessage(
        message.channelId,
        'Workflow result download is not available from this channel.',
        message.threadId
      )
      return
    }
    const result = await this.rpcClient.downloadWorkflowResultByRun(message, workflowRunId)
    if (!result.success) {
      await adapter.sendMessage(
        message.channelId,
        result.error?.message || 'Workflow result could not be downloaded.',
        message.threadId
      )
      return
    }

    const attachments = result.attachments ?? []
    if (adapter instanceof TeamsAdapter && attachments.length > 0) {
      const attachment = attachments[0]!
      if (message.providerIdentity?.providerChannelType === 'personal') {
        await adapter.sendFileConsent(
          message.channelId,
          attachment,
          {
            workflowRunId,
            artifactName: attachment.artifactName || attachment.filename || attachment.id,
          },
          message.threadId
        )
        return
      }
      if (attachment.mimeType.split(';', 1)[0]?.toLowerCase() !== 'text/plain') {
        await adapter.sendMessage(
          message.channelId,
          'Open a direct chat with this bot to download the workflow result file.',
          message.threadId
        )
        return
      }
    }

    await adapter.sendMessage(
      message.channelId,
      attachments.length > 0 ? '' : result.response || 'No workflow result file is available.',
      message.threadId,
      attachments
    )
  }

  async handleSlackHandoff(request: SlackHandoffRequest): Promise<SlackHandoffResponse> {
    if (request.kind === 'slack.message') {
      const message = this.slackMessageFromHandoff(request)
      if (!message) return { ok: false, status: 400, error: 'invalid_slack_message_handoff' }
      if (request.workflowRunId) {
        await this.deliverProviderWorkflowResult(message, request.workflowRunId)
      } else {
        await this.handleMessages([message])
      }
      return { ok: true }
    }

    if (request.kind === 'slack.enrollment') {
      return this.handleSlackEnrollmentHandoff(request)
    }

    return { ok: false, status: 400, error: 'unsupported_handoff_kind' }
  }

  async handleTeamsHandoff(request: TeamsHandoffRequest): Promise<SlackHandoffResponse> {
    if (request.kind === 'teams.message') {
      const message = this.teamsMessageFromHandoff(request)
      if (!message) return { ok: false, status: 400, error: 'invalid_teams_message_handoff' }
      this.rememberTeamsConversation(
        request.providerTarget,
        request.providerConversationId,
        request.serviceUrl
      )
      if (request.workflowRunId) {
        await this.deliverProviderWorkflowResult(message, request.workflowRunId)
      } else {
        await this.handleMessages([message])
      }
      return { ok: true }
    }

    if (request.kind === 'teams.file-consent') {
      return this.handleTeamsFileConsentHandoff(request)
    }

    if (request.kind === 'teams.enrollment') {
      return this.handleTeamsEnrollmentHandoff(request)
    }

    return { ok: false, status: 400, error: 'unsupported_handoff_kind' }
  }

  private async handleTeamsFileConsentHandoff(
    handoff: TeamsFileConsentHandoff
  ): Promise<SlackHandoffResponse> {
    const providerTarget = handoff.providerTarget
    if (
      !handoff.workflowRunId?.trim() ||
      !handoff.artifactName?.trim() ||
      !handoff.providerUserId?.trim() ||
      !handoff.providerWorkspaceId?.trim() ||
      !handoff.providerChannelId?.trim() ||
      !handoff.providerConversationId?.trim() ||
      !handoff.providerEventId?.trim() ||
      !handoff.providerMessageId?.trim() ||
      !handoff.serviceUrl?.trim() ||
      !providerTarget?.hostRef ||
      !providerTarget.communicationChannelNamespace ||
      !providerTarget.communicationChannelName
    ) {
      return { ok: false, status: 400, error: 'invalid_teams_file_consent_handoff' }
    }

    const adapter = this.adapterForCommunicationChannelRef('teams', {
      namespace: providerTarget.communicationChannelNamespace,
      name: providerTarget.communicationChannelName,
    })
    if (!(adapter instanceof TeamsAdapter)) {
      return { ok: false, status: 503, error: 'teams_adapter_unavailable' }
    }
    adapter.rememberConversation(handoff.providerConversationId, handoff.serviceUrl)
    if (handoff.action === 'decline') {
      await adapter.sendMessage(
        handoff.providerConversationId,
        'Workflow result download canceled.',
        handoff.providerReplyToMessageId || undefined
      )
      return { ok: true }
    }
    if (!handoff.uploadInfo) {
      return { ok: false, status: 400, error: 'teams_file_upload_info_missing' }
    }

    const message: Message = {
      channelType: 'teams',
      channelId: handoff.providerConversationId,
      sender: handoff.providerUserId,
      content: 'Download the completed workflow result',
      timestamp: new Date(),
      messageId: handoff.providerMessageId,
      threadId: handoff.providerReplyToMessageId,
      providerIdentity: {
        medium: 'teams',
        providerUserId: handoff.providerUserId,
        providerWorkspaceId: handoff.providerWorkspaceId,
        providerChannelId: handoff.providerChannelId,
        providerChannelType: handoff.providerChannelType ?? null,
        providerEventId: handoff.providerEventId,
        providerTarget,
      },
      rawData: { serviceUrl: handoff.serviceUrl },
    }
    if (!this.rpcClient.downloadWorkflowResultByRun) {
      return { ok: false, status: 503, error: 'workflow_result_download_unavailable' }
    }
    const result = await this.rpcClient.downloadWorkflowResultByRun(
      message,
      handoff.workflowRunId,
      handoff.artifactName
    )
    const attachment = result.attachments?.[0]
    if (!result.success || !attachment) {
      await adapter.sendMessage(
        handoff.providerConversationId,
        result.error?.message || 'Workflow result could not be downloaded.',
        handoff.providerReplyToMessageId || undefined
      )
      return { ok: true }
    }

    try {
      await adapter.uploadConsentedFile(
        handoff.providerConversationId,
        attachment,
        handoff.uploadInfo,
        handoff.providerReplyToMessageId || undefined
      )
    } catch (error) {
      console.error(
        '[Teams] Workflow result upload failed:',
        error instanceof Error ? error.message : error
      )
      await adapter.sendMessage(
        handoff.providerConversationId,
        'Teams could not upload the workflow result file. Try the download again.',
        handoff.providerReplyToMessageId || undefined
      )
    }
    return { ok: true }
  }

  private async handleSlackEnrollmentHandoff(
    handoff: SlackEnrollmentHandoff
  ): Promise<SlackHandoffResponse> {
    const providerTarget = handoff.providerTarget
    if (
      !handoff.nonce?.trim() ||
      !handoff.providerUserId?.trim() ||
      !handoff.providerWorkspaceId?.trim() ||
      !handoff.providerChannelId?.trim() ||
      !providerTarget?.hostRef ||
      !providerTarget.communicationChannelNamespace ||
      !providerTarget.communicationChannelName
    ) {
      return { ok: false, status: 400, error: 'invalid_slack_enrollment_handoff' }
    }

    if (!this.rpcClient.confirmSlackLinkSession) {
      return { ok: false, status: 503, error: 'slack_verification_unavailable' }
    }

    const adapter = this.adapterForCommunicationChannelRef('slack', {
      namespace: providerTarget.communicationChannelNamespace,
      name: providerTarget.communicationChannelName,
    })
    if (!adapter) {
      return { ok: false, status: 503, error: 'slack_adapter_unavailable' }
    }
    const conversationMetadata =
      adapter instanceof SlackAdapter
        ? await adapter.getConversationMetadata(handoff.providerChannelId, handoff.providerUserId)
        : {}

    const result = await this.rpcClient.confirmSlackLinkSession({
      nonce: handoff.nonce,
      providerUserId: handoff.providerUserId,
      providerWorkspaceId: handoff.providerWorkspaceId,
      providerChannelId: handoff.providerChannelId,
      providerChannelType:
        handoff.providerChannelType ?? conversationMetadata.providerChannelType ?? null,
      providerChannelTitle:
        handoff.providerChannelTitle ?? conversationMetadata.providerChannelTitle ?? null,
      providerTarget,
    })
    await adapter.sendMessage(
      handoff.providerChannelId,
      result.ok
        ? 'Slack identity confirmed.'
        : 'Slack verification failed. Check that the code is active and try again.',
      handoff.responseThreadTs || undefined
    )
    return { ok: true }
  }

  private async handleTeamsEnrollmentHandoff(
    handoff: TeamsEnrollmentHandoff
  ): Promise<SlackHandoffResponse> {
    const providerTarget = handoff.providerTarget
    if (
      !handoff.nonce?.trim() ||
      !handoff.providerUserId?.trim() ||
      !handoff.providerWorkspaceId?.trim() ||
      !handoff.providerChannelId?.trim() ||
      !handoff.providerConversationId?.trim() ||
      !handoff.providerReplyToMessageId?.trim() ||
      !handoff.serviceUrl?.trim() ||
      !providerTarget?.hostRef ||
      !providerTarget.communicationChannelNamespace ||
      !providerTarget.communicationChannelName
    ) {
      return { ok: false, status: 400, error: 'invalid_teams_enrollment_handoff' }
    }

    if (!this.rpcClient.confirmTeamsLinkSession) {
      return { ok: false, status: 503, error: 'teams_verification_unavailable' }
    }

    const adapter = this.adapterForCommunicationChannelRef('teams', {
      namespace: providerTarget.communicationChannelNamespace,
      name: providerTarget.communicationChannelName,
    })
    if (!adapter) {
      return { ok: false, status: 503, error: 'teams_adapter_unavailable' }
    }
    this.rememberTeamsConversation(
      providerTarget,
      handoff.providerConversationId,
      handoff.serviceUrl
    )
    if (adapter instanceof TeamsAdapter) {
      await adapter.verifyCredentials()
    }

    const result = await this.rpcClient.confirmTeamsLinkSession({
      nonce: handoff.nonce,
      providerUserId: handoff.providerUserId,
      providerWorkspaceId: handoff.providerWorkspaceId,
      providerChannelId: handoff.providerChannelId,
      providerChannelType: handoff.providerChannelType ?? null,
      providerChannelTitle: handoff.providerChannelTitle ?? null,
      providerTeamId: handoff.providerTeamId ?? null,
      providerTeamsChannelId: handoff.providerTeamsChannelId ?? null,
      serviceUrl: handoff.serviceUrl,
      providerTarget,
    })
    const replyAdapter =
      this.adapterForCommunicationChannelRef('teams', {
        namespace: providerTarget.communicationChannelNamespace,
        name: providerTarget.communicationChannelName,
      }) ?? adapter
    if (replyAdapter instanceof TeamsAdapter) {
      replyAdapter.rememberConversation(handoff.providerConversationId, handoff.serviceUrl)
    }
    await replyAdapter.sendMessage(
      handoff.providerConversationId,
      result.ok
        ? 'Teams identity confirmed.'
        : 'Teams verification failed. Check that the code is active and try again.',
      result.ok && result.replyInThreads === false
        ? undefined
        : handoff.providerReplyToMessageId || handoff.providerMessageId || undefined
    )
    return { ok: true }
  }

  /**
   * Load channels from dev config.
   * @throws Error if no channel config is provided in dev mode
   */
  loadDevChannels(): CommunicationChannelCRD[] {
    if (!config.devChannelConfig) {
      throw new Error(
        'No CLERUM_CHANNEL environment variable provided. In dev mode, you must set CLERUM_CHANNEL with a JSON channel configuration.'
      )
    }

    const crd: CommunicationChannelCRD = {
      name: 'dev-channel',
      namespace: 'dev',
      spec: config.devChannelConfig,
    }

    return [crd]
  }

  /**
   * Run a single poll cycle across all channels.
   */
  async pollCycle(): Promise<Message[]> {
    const allMessages: Message[] = []

    for (const channelCRD of this.channels) {
      const { spec } = channelCRD

      // Process Telegram private chats, groups, and supergroups. Personal identity is verified separately.
      //
      // Two separate hazards are guarded here, and both used to cost the channel
      // every provider declared after telegram.
      //
      // 1. Guard on length, not presence. Channels created before this release
      //    carry `telegram: []` even when they are Teams or Slack channels, and
      //    an empty array is truthy. An empty array means "no telegram groups to
      //    poll", not "this is a telegram channel".
      // 2. The exits below leave the LABELLED BLOCK, not the channel loop. A
      //    `continue` here aborted the whole channel, so a channel with real
      //    telegram groups but no telegram adapter (credentials absent) silently
      //    stopped polling its email and everything else too.
      //    charts/clerum-crds/examples/channels.yaml ships exactly that shape:
      //    one CommunicationChannel carrying telegram + email + slack.
      telegramGroups: if (spec.telegram?.length) {
        const adapter = this.adapterForChannel('telegram', channelCRD)
        if (!adapter) {
          // Previously silent, which is what made this hard to diagnose.
          console.warn(
            '[Main] Skipping Telegram groups for ' +
              channelCRD.namespace +
              '/' +
              channelCRD.name +
              ': no telegram adapter; other providers on this channel still poll'
          )
          break telegramGroups
        }
        const providerTarget = providerTargetFromChannel(channelCRD)
        if (!providerTarget) {
          console.warn(
            '[Main] Skipping Telegram channels for ' +
              channelCRD.namespace +
              '/' +
              channelCRD.name +
              ': provider target is incomplete'
          )
          break telegramGroups
        }
        const telegramPollGroups = new Map<
          string,
          {
            channelId: string
            chatType: TelegramProviderChatType
            userIds: Set<string>
            allowUnlistedSender: boolean
            replyOnlyWhenMentioned: boolean
          }
        >()
        for (const group of spec.telegram) {
          const channelId = String(group.channelId || '').trim()
          const chatType = supportedTelegramOperationalChatType(group.chatType)
          if (!channelId) {
            console.warn(
              '[Main] Skipping Telegram channel for ' +
                channelCRD.namespace +
                '/' +
                channelCRD.name +
                ': missing channelId'
            )
            continue
          }
          if (!chatType) {
            console.warn(
              '[Main] Skipping Telegram channel ' +
                channelId +
                ': unsupported or missing chatType ' +
                String(group.chatType ?? '')
            )
            continue
          }
          const configuredUserIds = (group.userIds ?? [])
            .map(id => String(id).trim())
            .filter(Boolean)
          const key = `${channelId}\0${chatType}`
          const current = telegramPollGroups.get(key) ?? {
            channelId,
            chatType,
            userIds: new Set<string>(),
            allowUnlistedSender: false,
            replyOnlyWhenMentioned: false,
          }
          for (const userId of configuredUserIds) {
            current.userIds.add(userId)
          }
          // OR wins here by design: a confirmed-user approval row has no userIds,
          // so channel-reader forwards the group message and backend auth decides
          // whether the Telegram sender has current member/channel access.
          current.allowUnlistedSender =
            current.allowUnlistedSender || configuredUserIds.length === 0
          current.replyOnlyWhenMentioned =
            current.replyOnlyWhenMentioned || !!group.replyOnlyWhenMentioned
          telegramPollGroups.set(key, current)
        }
        for (const group of telegramPollGroups.values()) {
          const messages = await adapter.fetchMessages(group.channelId, group.userIds, {
            replyOnlyWhenMentioned:
              spec.telegramSettings?.replyOnlyWhenMentioned ?? group.replyOnlyWhenMentioned,
            telegramChatType: group.chatType,
            allowUnlistedSender: group.allowUnlistedSender,
            providerTarget,
          })
          allMessages.push(...messages)
        }
      }

      // Process Email groups. Same two hazards as the telegram guard above: an
      // empty array is not an email channel, and a missing adapter must not cost
      // the channel its remaining providers.
      emailGroups: if (spec.email?.length) {
        const adapter = this.adapterForChannel('email', channelCRD)
        if (!adapter) break emailGroups
        for (const group of spec.email) {
          const allowedSenders = new Set(group.emails)
          const messages = await adapter.fetchMessages(group.channelId, allowedSenders)
          allMessages.push(...messages)
        }
      }

      // Process Slack groups
      if (hasSlackChannelConfig(spec)) {
        console.log(
          `[Main] Skipping Slack polling for CommunicationChannel ${this.communicationChannelKey(
            channelCRD
          )}; Slack app messages are handled by workflow-approval-request-reader webhooks`
        )
      }

      if (hasTeamsChannelConfig(spec)) {
        console.log(
          `[Main] Skipping Teams polling for CommunicationChannel ${this.communicationChannelKey(
            channelCRD
          )}; Teams app messages are handled by workflow-approval-request-reader webhooks`
        )
      }
    }

    if (allMessages.length > 0) {
      console.log(`[Main] Received ${allMessages.length} message(s)`)
      await this.handleMessages(allMessages)
    }

    // Deliver any pending cron task results
    await this.pollCronResults()

    // Deliver workflow approval notifications via mcp-host, which is the
    // authenticated control-plane caller for the control-api hop.
    await this.workflowApprovalCoordinator.pollNotifications()

    // Clean up stale pending approvals and provider event dedupe keys.
    this.cleanupStaleApprovals()

    return allMessages
  }

  /**
   * Handle received messages by forwarding them to mcp-host and replying with LLM response.
   * Intercepts /approve and /deny commands when an approval is pending.
   */
  async handleMessages(messages: Message[]): Promise<void> {
    for (const msg of messages) {
      console.log('\n' + '-'.repeat(50))
      console.log(`[Main] New message from ${msg.channelType}`)
      console.log(`[Main]   Channel: ${msg.channelType} (${msg.channelId})`)
      console.log(`[Main]   Sender: ${msg.sender}`)
      console.log(`[Main]   Message ID: ${msg.messageId || '(none)'}`)
      if (msg.providerIdentity?.providerEventId) {
        console.log(`[Main]   Provider Event: ${msg.providerIdentity.providerEventId}`)
      }
      console.log(`[Main]   Time: ${msg.timestamp.toISOString()}`)
      console.log(
        `[Main]   Content: ${msg.content.substring(0, 100)}${msg.content.length > 100 ? '...' : ''}`
      )
      console.log('-'.repeat(50))

      const providerEventKey = this.providerEventDedupeKey(msg)
      if (providerEventKey && this.processedProviderEvents.has(providerEventKey)) {
        console.warn(`[Main] Duplicate provider message ignored: ${providerEventKey}`)
        continue
      }
      if (msg.providerIdentity && this.rpcClient.authorizeProviderMessage) {
        const authorization = await this.rpcClient.authorizeProviderMessage(msg.providerIdentity)
        if (!authorization.authorized) {
          if (providerEventKey) {
            this.processedProviderEvents.set(providerEventKey, { seenAt: Date.now() })
          }
          console.warn(
            `[Main] Ignoring unauthorized ${msg.channelType} message from ${msg.sender} in ${msg.channelId}`
          )
          if (authorization.reason === 'unresolved') {
            await this.sendUnresolvedSenderNotice(msg)
          }
          continue
        }
      }

      const traceContext = mintChannelTraceContext(msg)
      if (providerEventKey) {
        this.processedProviderEvents.set(providerEventKey, { seenAt: Date.now() })
      }

      // Check if this is an approval/denial command
      const runtimeContent = contentWithoutAddressedBotMention(msg)
      const runtimeMsg = runtimeContent === msg.content ? msg : { ...msg, content: runtimeContent }
      const trimmed = runtimeContent.trim().toLowerCase()
      const toolApprovalAction = parseToolApprovalAction(runtimeContent)
      if (toolApprovalAction) {
        await this.handleApprovalCommand(
          msg,
          toolApprovalAction.command,
          toolApprovalAction.actionToken
        )
        continue
      }
      const workflowApprovalCallback = parseWorkflowApprovalDecisionCallback(msg)
      if (workflowApprovalCallback) {
        await this.workflowApprovalCoordinator.handleDecisionCallback(msg, workflowApprovalCallback)
        continue
      }
      const workflowApprovalDecision = parseWorkflowApprovalDecisionCommand(msg)
      if (workflowApprovalDecision) {
        await this.workflowApprovalCoordinator.handleDecisionCommand(msg, workflowApprovalDecision)
        continue
      }
      if (
        trimmed === '/approve' ||
        trimmed === '/approve always' ||
        trimmed === '/deny' ||
        trimmed === '\\approve' ||
        trimmed === '\\approve always' ||
        trimmed === '\\deny'
      ) {
        await this.handleApprovalCommand(msg, trimmed.replace(/^\\/, '/') as ToolApprovalDecision)
        continue
      }

      // Forward to mcp-host
      console.log('[Main] Forwarding message to mcp-host...')

      const adapter = this.adapterForMessage(msg)
      if (adapter && msg.channelType !== 'email') {
        // Telegram, Slack, and Teams: use async progress flow with edit-in-place
        try {
          await this.handleMessageWithProgress(runtimeMsg, adapter, traceContext)
        } catch (err) {
          console.error(`[Main] Progress flow failed, falling back:`, err)
          // Fall back to synchronous
          const response = await this.rpcClient.sendMessage(runtimeMsg, { traceContext })
          if (response.success && response.status === 'waiting_approval' && response.approval) {
            const { taskId, requestId, userId, notification } = response.approval
            console.log(`[Main] Tool approval needed (task: ${taskId}, request: ${requestId})`)
            const approvalKey = this.pendingApprovalKey(msg)
            const actionToken = newToolApprovalActionToken()
            this.pendingApprovals.set(approvalKey, {
              taskId,
              requestId,
              userId,
              channelType: msg.channelType,
              channelId: msg.channelId,
              originalMessage: msg,
              createdAt: new Date(),
              actionToken,
            })
            await this.sendReply(
              msg,
              notification,
              undefined,
              toolApprovalMessageOptions(msg.channelType, notification, actionToken)
            )
          } else if (response.success && response.response) {
            console.log('[Main] mcp-host response:')
            console.log(`[Main]   Model: ${response.model}`)
            console.log(
              `[Main]   Response: ${response.response.substring(0, 200)}${response.response.length > 200 ? '...' : ''}`
            )
            if (response.usage) {
              console.log(`[Main]   Tokens: ${response.usage.totalTokens}`)
            }
            await this.sendReply(msg, response.response, response.attachments)
          } else {
            console.error(
              `[Main] Failed to process message: ${response.error?.message ?? 'unknown error'}`
            )
          }
        }
      } else {
        // Email: existing synchronous flow
        const response = await this.rpcClient.sendMessage(runtimeMsg, { traceContext })

        if (response.success && response.status === 'waiting_approval' && response.approval) {
          const { taskId, requestId, userId, notification } = response.approval
          console.log(`[Main] Tool approval needed (task: ${taskId}, request: ${requestId})`)
          const approvalKey = this.pendingApprovalKey(msg)
          const actionToken = newToolApprovalActionToken()
          this.pendingApprovals.set(approvalKey, {
            taskId,
            requestId,
            userId,
            channelType: msg.channelType,
            channelId: msg.channelId,
            originalMessage: msg,
            createdAt: new Date(),
            actionToken,
          })
          await this.sendReply(
            msg,
            notification,
            undefined,
            toolApprovalMessageOptions(msg.channelType, notification, actionToken)
          )
        } else if (response.success && response.response) {
          console.log('[Main] mcp-host response:')
          console.log(`[Main]   Model: ${response.model}`)
          console.log(
            `[Main]   Response: ${response.response.substring(0, 200)}${response.response.length > 200 ? '...' : ''}`
          )
          if (response.usage) {
            console.log(`[Main]   Tokens: ${response.usage.totalTokens}`)
          }
          await this.sendReply(msg, response.response, response.attachments)
        } else {
          console.error(
            `[Main] Failed to process message: ${response.error?.message ?? 'unknown error'}`
          )
        }
      }
    }
  }

  private providerEventDedupeKey(msg: Message): string | null {
    const providerEventId = msg.providerIdentity?.providerEventId?.trim()
    if (providerEventId) {
      return `provider:${providerEventId}`
    }

    const messageId = msg.messageId?.trim()
    if (!messageId) {
      return null
    }

    return ['message', msg.channelType, msg.channelId, msg.sender, messageId].join(':')
  }

  /**
   * Tell an unresolved Slack, Teams, or Telegram sender why the agent is ignoring
   * them, at most once per user per conversation per UNRESOLVED_NOTICE_TTL_MS, and
   * never past UNRESOLVED_NOTICE_GLOBAL_CAP live notice records in total.
   */
  private async sendUnresolvedSenderNotice(msg: Message): Promise<void> {
    if (
      msg.channelType !== 'slack' &&
      msg.channelType !== 'teams' &&
      msg.channelType !== 'telegram'
    )
      return
    const identity = msg.providerIdentity
    const userId = identity?.providerUserId?.trim()
    const workspaceId = identity?.providerWorkspaceId?.trim()
    const channelId = msg.channelId?.trim()
    if (!userId || !channelId) return
    // Slack and Teams identities are scoped to a workspace/tenant an admin
    // controls, and the limiter key below relies on that scope. Telegram has no
    // such concept: every real Telegram message carries providerWorkspaceId: null,
    // so requiring one here would silently drop the notice for every Telegram
    // sender.
    if (msg.channelType !== 'telegram' && !workspaceId) return

    // Scope the limiter by provider identity, the same way pendingApprovalChannelScope
    // does. The SEND still targets msg.channelId, which is what replyChannelId hands
    // every other outbound Slack call; only the dedupe identity is provider-scoped.
    const conversationId = identity?.providerChannelId?.trim() || channelId
    const key = `${workspaceId ?? UNRESOLVED_NOTICE_NO_WORKSPACE_KEY}:${userId}:${conversationId}`
    if (this.unresolvedNoticesSent.has(key)) return
    if (this.unresolvedNoticesSent.size >= UNRESOLVED_NOTICE_GLOBAL_CAP) {
      // Log only on the transition into the capped state, not on every blocked
      // send: at the cap, every inbound message from every unresolved sender
      // across every provider would otherwise emit its own warning, which is
      // loudest in exactly the misconfiguration this cap exists to contain.
      // unresolvedNoticeCapLogged resets once cleanupStaleApprovals' TTL sweep
      // drains the map back under the cap, so a later trip logs again.
      if (!this.unresolvedNoticeCapLogged) {
        this.unresolvedNoticeCapLogged = true
        console.warn(
          `[Main] Unresolved-sender notice cap (${UNRESOLVED_NOTICE_GLOBAL_CAP}) reached; ` +
            `suppressing further notices until the TTL sweep frees a slot.`
        )
      }
      return
    }
    // Record on ATTEMPT, not on success: a conversation Slack keeps rejecting
    // must not produce one outbound call per inbound message.
    this.unresolvedNoticesSent.set(key, { seenAt: Date.now() })

    const adapter = this.adapterForMessage(msg)
    if (!adapter) return
    let content: string
    if (msg.channelType === 'telegram') {
      content = UNRESOLVED_NOTICE_COPY_TELEGRAM
    } else {
      const profileUrl = config.profileUiUrl?.trim()
      const baseCopy =
        msg.channelType === 'teams' ? UNRESOLVED_NOTICE_COPY_TEAMS : UNRESOLVED_NOTICE_COPY
      content = profileUrl
        ? `${baseCopy} ${profileSocialChannelUrl(profileUrl, msg.channelType)}`
        : baseCopy
    }
    try {
      if (msg.channelType === 'teams') {
        // TeamsAdapter has no ephemeral concept, so the notice is a normal message.
        // Thread it under the triggering message so an unconnected user does not
        // produce a top-level post in a shared channel.
        //
        // The reply target is the thread ROOT, the same target replyTargetMessageId
        // picks for every other Teams reply. threadId is the root activity id
        // (providerReplyToMessageId) and messageId is the leaf activity that just
        // arrived; replying to the leaf does not attach the notice to the
        // conversation, which is the whole mitigation here. The fallback is for a
        // direct chat, which has no separate root.
        await adapter.sendMessage(channelId, content, msg.threadId || msg.messageId)
      } else if (msg.channelType === 'telegram') {
        // No reply id: the spec fixes this as sendMessage(channelId, content) for
        // Telegram, with no threading. Group and supergroup chats do have a
        // channel-wide audience (see telegramOperationalMessage.ts), so this is
        // not a threading-is-pointless argument; the copy itself is deliberately
        // terse so a top-level post leaks nothing meaningful, and threading here
        // is a possible follow-up.
        await adapter.sendMessage(channelId, content)
      } else {
        if (!adapter.sendEphemeral) return
        await adapter.sendEphemeral(channelId, userId, content)
      }
    } catch (error) {
      // Contain the failure HERE. SlackAdapter swallows its own errors today, but
      // the ChannelAdapter interface promises nothing, and this runs inside the
      // per-message loop in handleMessages: an adapter that ever throws would
      // abort the rest of the batch over a notice that is best-effort by design.
      console.warn(
        `[Main] Could not send unresolved-sender notice to ${userId} in ${channelId}: ${
          error instanceof Error ? error.message : String(error)
        }`
      )
    }
  }

  private pendingApprovalChannelScope(msg: Message): string {
    return `${msg.channelType}:${msg.providerIdentity?.providerChannelId || msg.channelId}`
  }

  private pendingApprovalKey(msg: Message): string {
    let threadId = ''
    if (msg.channelType === 'telegram' || msg.channelType === 'slack') {
      threadId = msg.threadId || ''
    } else if (
      msg.channelType === 'teams' &&
      msg.providerIdentity?.providerChannelType === 'channel'
    ) {
      threadId = msg.threadId || ''
    }
    return [this.pendingApprovalChannelScope(msg), threadId, msg.sender].join(':')
  }

  private pendingApprovalByActionToken(
    msg: Message,
    actionToken: string
  ): [string, PendingApprovalState] | null {
    const channelScope = this.pendingApprovalChannelScope(msg)
    for (const [key, pending] of this.pendingApprovals) {
      if (
        pending.actionToken === actionToken &&
        pending.originalMessage.sender === msg.sender &&
        this.pendingApprovalChannelScope(pending.originalMessage) === channelScope
      ) {
        return [key, pending]
      }
    }
    return null
  }

  private clearPendingApprovalForTask(msg: Message, taskId: string): void {
    const channelScope = this.pendingApprovalChannelScope(msg)
    for (const [key, pending] of this.pendingApprovals) {
      if (
        pending.taskId === taskId &&
        this.pendingApprovalChannelScope(pending.originalMessage) === channelScope
      ) {
        this.pendingApprovals.delete(key)
      }
    }
  }

  private replyTargetMessageId(msg: Message): string | undefined {
    if (msg.channelType === 'slack') return msg.threadId
    if (msg.channelType === 'teams') {
      return this.teamsReplyInThreads(msg) ? msg.threadId || msg.messageId : undefined
    }
    return msg.messageId
  }

  private teamsReplyInThreads(msg: Message): boolean {
    if (msg.channelType !== 'teams') return false
    const target = msg.providerIdentity?.providerTarget
    const workspaceId = msg.providerIdentity?.providerWorkspaceId
    const providerChannelId = msg.providerIdentity?.providerChannelId
    const channel = this.channels.find(
      item =>
        item.namespace === target?.communicationChannelNamespace &&
        item.name === target?.communicationChannelName
    )
    const group = channel?.spec.teams?.find(
      item => item.channelId === providerChannelId && item.tenantId === workspaceId
    )
    return group?.replyInThreads !== false
  }

  private replyChannelId(msg: Message): string {
    if (msg.channelType === 'teams' && !this.teamsReplyInThreads(msg)) {
      return msg.providerIdentity?.providerChannelId || msg.channelId
    }
    return msg.channelId
  }

  /**
   * Handle a message using the async progress flow.
   * Sends the message with async=true, opens an SSE progress stream that stays
   * open for the entire task lifecycle, and edits a status message in-place as
   * progress events arrive.
   *
   * Architecture:
   * - The wrapping Promise resolves on the FIRST state-signal event
   *   (suspended OR terminal OR error). This unblocks handleMessages's for
   *   loop quickly so the poll cycle can move on.
   * - The SSE stream's IIFE in progressClient.ts keeps reading via its own
   *   abortController/fetch reader; JavaScript closures keep msg, adapter,
   *   editStatus, and `this` (ChannelReader instance) alive for the callbacks
   *   to use after this function returns.
   * - On `suspended`: register pending approval, edit bubble with the
   *   notification (fetched once from getTaskResult; falls back to a generic
   *   message if the cache hasn't been written yet — the sub-millisecond
   *   micro-race in mcp-host's taskExecutor.ts:472-485).
   * - On `tool_start`/`tool_complete` after approval: keeps editing the
   *   bubble with progress.
   * - On `terminal`: fetch final response via getTaskResult, edit bubble.
   * - After approval: keep relying on SSE, with a task-result polling fallback
   *   if the stream closes or misses the terminal event.
   * - No waitForTaskResult. No drainApprovalCommands.
   */
  private async handleMessageWithProgress(
    msg: Message,
    adapter: ChannelAdapter,
    traceContext: TraceContextV1
  ): Promise<void> {
    // 1. Send message with async=true
    const response = await this.rpcClient.sendMessage(msg, { async: true, traceContext })

    if (!response.taskId) {
      console.log('[Main] No taskId returned from async send, falling back to sync')
      if (response.success && response.status === 'waiting_approval' && response.approval) {
        const { taskId, requestId, userId, notification } = response.approval
        console.log(`[Main] Tool approval needed (task: ${taskId}, request: ${requestId})`)
        const approvalKey = this.pendingApprovalKey(msg)
        const actionToken = newToolApprovalActionToken()
        this.pendingApprovals.set(approvalKey, {
          taskId,
          requestId,
          userId,
          channelType: msg.channelType,
          channelId: msg.channelId,
          originalMessage: msg,
          createdAt: new Date(),
          actionToken,
        })
        await this.sendReply(
          msg,
          notification,
          undefined,
          toolApprovalMessageOptions(msg.channelType, notification, actionToken)
        )
      } else if (response.success && response.response) {
        await this.sendReply(msg, response.response, response.attachments)
      } else if (response.error) {
        console.error(
          `[Main] Failed to process message: ${response.error?.message ?? 'unknown error'}`
        )
      }
      return
    }

    const taskId = response.taskId
    console.log(`[Main] Async task created: ${taskId}`)
    const responseChannelId = this.replyChannelId(msg)

    // 2. Send initial processing message and capture messageId for editing.
    const statusMessageId = await adapter.sendMessage(
      responseChannelId,
      '\u23f3 Processing your request...',
      this.replyTargetMessageId(msg)
    )

    if (!statusMessageId) {
      console.log('[Main] No messageId returned from initial status message; cannot edit-in-place')
      return
    }

    // 3. Open SSE stream and wire callbacks. The stream stays open until terminal.
    //
    // Fire-and-detach: we create the wrapping Promise so the callback lambdas
    // capture a shared `resolveOnce()` (used by every state-signal handler to
    // mark the "first state event" boundary cleanly), but we do NOT await it.
    // Awaiting would serialise channel-reader's `for (msg of messages)` loop
    // on a slow task; instead, JavaScript closures keep `msg`, `adapter`,
    // `editStatus`, the stream handle, and `this` alive for the SSE callbacks
    // to use after this function returns. The SSE IIFE in progressClient.ts
    // owns its own abortController + reader and runs independently.
    void new Promise<void>(resolve => {
      let resolved = false
      const resolveOnce = () => {
        if (!resolved) {
          resolved = true
          resolve()
        }
      }

      let statusEditQueue: Promise<void> = Promise.resolve()
      let acceptProgressUpdates = true

      const editStatus = (
        content: string,
        mustSucceed = false,
        options?: SendMessageOptions
      ): Promise<void> => {
        const operation = statusEditQueue.then(async () => {
          try {
            await adapter.editMessage(responseChannelId, statusMessageId, content, options)
          } catch (err) {
            console.error(`[Main] Failed to edit status message for task ${taskId}:`, err)
            if (mustSucceed) throw err
          }
        })
        statusEditQueue = operation.catch(() => undefined)
        return operation
      }

      let finalDelivered = false
      let finalDeliveryInFlight: Promise<boolean> | null = null
      let resultPollingFallbackStarted = false
      let approvalPromptDelivered = false

      const deliverApprovalPrompt = async (params: {
        requestId: string
        userId: string
        notification: string
      }): Promise<void> => {
        const approvalKey = this.pendingApprovalKey(msg)
        const existing = this.pendingApprovals.get(approvalKey)
        if (approvalPromptDelivered && existing?.requestId === params.requestId) return

        approvalPromptDelivered = true
        acceptProgressUpdates = false
        const actionToken =
          existing?.requestId === params.requestId
            ? existing.actionToken
            : newToolApprovalActionToken()

        console.log(`[Main] Tool approval needed (task: ${taskId}, request: ${params.requestId})`)
        this.pendingApprovals.set(approvalKey, {
          taskId,
          requestId: params.requestId,
          userId: params.userId,
          channelType: msg.channelType,
          channelId: msg.channelId,
          originalMessage: msg,
          createdAt: new Date(),
          actionToken,
          startResultPollingFallback,
          updateStatusAfterDecision: content => {
            acceptProgressUpdates = true
            return editStatus(content)
          },
        })
        await editStatus(
          params.notification,
          false,
          toolApprovalMessageOptions(msg.channelType, params.notification, actionToken)
        )
      }

      const deliverFinalResult = async (): Promise<boolean> => {
        if (finalDelivered) return true
        if (finalDeliveryInFlight) return finalDeliveryInFlight

        finalDeliveryInFlight = (async () => {
          const result = await this.rpcClient.getTaskResult(taskId, msg)
          if (result.status === 'waiting_approval' && result.approval) {
            await deliverApprovalPrompt({
              requestId: result.approval.requestId,
              userId: result.approval.userId,
              notification: result.approval.notification,
            })
            return false
          }
          if (result.status === 'pending' || result.status === 'waiting_approval') {
            return false
          }
          acceptProgressUpdates = false

          if (result.success && result.response) {
            const finalText = formatFinalMessage(stream.steps, result.response)
            try {
              await editStatus(finalText, true)
            } catch {
              await adapter.sendMessage(
                responseChannelId,
                finalText,
                this.replyTargetMessageId(msg)
              )
            }
            finalDelivered = true
            this.clearPendingApprovalForTask(msg, taskId)
            console.log(`[Main] Final result delivered for task ${taskId} via ${msg.channelType}`)
            if (result.attachments && result.attachments.length > 0) {
              await adapter.sendMessage(
                responseChannelId,
                '',
                this.replyTargetMessageId(msg),
                result.attachments
              )
            }
          } else if (result.error) {
            const errorText = `Error: ${result.error.message ?? 'Unknown error'}`
            try {
              await editStatus(errorText, true)
            } catch {
              await adapter.sendMessage(
                responseChannelId,
                errorText,
                this.replyTargetMessageId(msg)
              )
            }
            finalDelivered = true
            this.clearPendingApprovalForTask(msg, taskId)
            console.log(`[Main] Final error delivered for task ${taskId} via ${msg.channelType}`)
          } else {
            const finalText = formatFinalMessage(stream.steps, 'Done.')
            try {
              await editStatus(finalText, true)
            } catch {
              await adapter.sendMessage(
                responseChannelId,
                finalText,
                this.replyTargetMessageId(msg)
              )
            }
            finalDelivered = true
            this.clearPendingApprovalForTask(msg, taskId)
            console.log(`[Main] Final result delivered for task ${taskId} via ${msg.channelType}`)
          }
          return true
        })()

        try {
          return await finalDeliveryInFlight
        } finally {
          finalDeliveryInFlight = null
        }
      }

      const startResultPollingFallback = () => {
        if (resultPollingFallbackStarted) return
        resultPollingFallbackStarted = true

        void (async () => {
          const deadline = Date.now() + RESULT_POLL_FALLBACK_TIMEOUT_MS
          while (!finalDelivered && Date.now() < deadline) {
            await new Promise(resolve => setTimeout(resolve, RESULT_POLL_FALLBACK_INTERVAL_MS))
            if (finalDelivered) return
            try {
              const delivered = await deliverFinalResult()
              if (delivered) {
                stream.close()
                resolveOnce()
                return
              }
            } catch (err) {
              console.error(`[Main] result polling fallback failed for task ${taskId}:`, err)
            }
          }
          if (!finalDelivered) {
            console.warn(`[Main] Result polling fallback timed out for task ${taskId}`)
          }
        })()
      }

      const stream = createProgressStream({
        mcpHostUrl: this.rpcClient.getBaseUrl(),
        taskId,
        source: msg,
        onProgress: (steps: ProgressStep[]) => {
          if (!acceptProgressUpdates) return
          void editStatus(formatProgressUpdate(steps))
        },
        onSuspended: async suspended => {
          // Approval needed. Fetch the server-formatted notification (which
          // includes tool parameters) once. If the cache hasn't been written
          // yet (sub-ms micro-race), fall back to a generic notification.
          let notification =
            `Tool \`${suspended.toolName}\` requires approval. ` +
            (msg.channelType === 'slack'
              ? `Reply \\approve or \\deny to this message.`
              : msg.channelType === 'teams'
                ? `Reply approve or deny to this message.`
                : `Reply /approve or /deny to this message.`)
          try {
            const result = await this.rpcClient.getTaskResult(taskId, msg)
            if (
              result.success &&
              result.status === 'waiting_approval' &&
              result.approval?.notification
            ) {
              notification = result.approval.notification
            }
          } catch (err) {
            console.error(`[Main] Failed to fetch approval notification for task ${taskId}:`, err)
          }
          await deliverApprovalPrompt({
            requestId: suspended.requestId,
            userId: msg.sender,
            notification,
          })
          // Release handleMessages's for loop. The stream stays open; the next
          // tool_start/tool_complete/suspended/terminal events keep firing.
          resolveOnce()
        },
        onTerminal: async terminal => {
          if (finalDelivered) {
            stream.close()
            resolveOnce()
            return
          }
          if (terminal.status === 'cancelled') {
            acceptProgressUpdates = false
            finalDelivered = true
            await editStatus('Request cancelled.')
            this.clearPendingApprovalForTask(msg, taskId)
          } else if (terminal.status === 'failed' && terminal.error) {
            acceptProgressUpdates = false
            finalDelivered = true
            await editStatus(`Error: ${terminal.error.message}`)
            this.clearPendingApprovalForTask(msg, taskId)
          } else {
            // status === 'completed' (or unknown — treat as completed)
            try {
              const delivered = await deliverFinalResult()
              if (!delivered) {
                startResultPollingFallback()
                await editStatus(
                  formatFinalMessage(stream.steps, 'Final response is still syncing.')
                )
              }
            } catch (err) {
              console.error(`[Main] terminal(completed) result fetch failed:`, err)
              startResultPollingFallback()
              await editStatus(formatFinalMessage(stream.steps, 'Final response is still syncing.'))
            }
          }
          // Belt-and-braces close: the SSE IIFE closes itself on terminal
          // (progressClient.ts), but the test mock returns a static handle
          // that doesn't auto-close — and an explicit close here is harmless
          // (close() is idempotent) and matches the spec's "closes the stream"
          // language for onTerminal.
          stream.close()
          resolveOnce()
        },
        onError: async (error: string) => {
          console.error(`[Main] Progress stream error: ${error}`)
          // `task_not_found_or_expired` is NOT a transport failure: mcp-host is
          // healthy. It means the reporter was never registered within the 180s
          // wait (queue saturation \u2014 task may still be processing) or was evicted
          // by TTL >5min after completion (the result already exists). Mirror the
          // Desktop App (appService.ts) \u2014 reconcile against the stored result
          // instead of crying "Lost connection". (issue #581)
          if (error.includes('task_not_found_or_expired')) {
            try {
              // Path B: the answer is already computed + stored \u2192 deliver it.
              const delivered = await deliverFinalResult()
              if (delivered) {
                stream.close()
                resolveOnce()
                return
              }
              if (approvalPromptDelivered) {
                resolveOnce()
                return
              }
            } catch (err) {
              console.error(
                `[Main] reconcile after task_not_found_or_expired failed for task ${taskId}:`,
                err
              )
            }
            // Path A: still queued/processing \u2192 keep polling for the result,
            // don't mislabel it as a connection loss.
            await editStatus('Still processing \u2014 taking longer than usual\u2026')
            startResultPollingFallback()
            resolveOnce()
            return
          }
          // Genuine transport/network failure.
          await editStatus('\u26a0\ufe0f Lost connection to processing stream.')
          resolveOnce()
        },
      })
      // Webhook-origin Slack/Teams requests can lose the terminal SSE while still
      // receiving normal tool progress. Keep webhook-origin chats backed up by polling;
      // Telegram keeps the narrower existing fallbacks below.
      if (msg.channelType === 'slack' || msg.channelType === 'teams') {
        startResultPollingFallback()
      }
    })
  }

  /**
   * Handle /approve, /approve always, or /deny commands from the user.
   *
   * Since the SSE stream opened by handleMessageWithProgress is still running
   * (it stays open until the task's terminal event), this function only needs
   * to (a) submit the decision to mcp-host and (b) send a user-facing
   * acknowledgment. The SSE stream will surface subsequent state transitions
   * (multi-approval, completion) on its own.
   *
   * For cron tasks: results continue to arrive via pollCronResults on the next
   * poll cycle (cron has no message-thread SSE).
   */
  private async handleApprovalCommand(
    msg: Message,
    command: ToolApprovalDecision,
    actionToken?: string
  ): Promise<void> {
    const contextualKey = this.pendingApprovalKey(msg)
    const matched = actionToken
      ? this.pendingApprovalByActionToken(msg, actionToken)
      : this.pendingApprovals.has(contextualKey)
        ? ([contextualKey, this.pendingApprovals.get(contextualKey)!] as [
            string,
            PendingApprovalState,
          ])
        : null
    const approvalKey = matched?.[0] ?? contextualKey
    const pending = matched?.[1]

    if (!pending) {
      console.log(`[Main] No pending approval for ${approvalKey}`)
      await this.sendReply(
        msg,
        'No pending approval found. Send a message first that triggers a tool requiring approval.'
      )
      return
    }

    const { requestId, userId } = pending

    if (command === '/deny') {
      console.log(`[Main] User denied approval (request: ${requestId})`)
      const result = await this.rpcClient.sendDenial(
        userId,
        requestId,
        pending.channelType,
        pending.channelId
      )
      if (result.success) {
        this.pendingApprovals.delete(approvalKey)
        await pending.updateStatusAfterDecision?.('Denied. The tool will not be executed.')
        await this.sendReply(msg, 'Denied. The tool will not be executed.')
      } else {
        await this.sendReply(msg, `Failed to send denial: ${result.error ?? 'unknown error'}`)
      }
      return
    }

    // /approve or /approve always
    const alwaysApprove = command === '/approve always'
    console.log(`[Main] User approved (request: ${requestId}, always: ${alwaysApprove})`)

    const result = await this.rpcClient.sendApproval(
      userId,
      requestId,
      alwaysApprove,
      pending.channelType,
      pending.channelId
    )
    if (!result.success) {
      await this.sendReply(msg, `Failed to send approval: ${result.error ?? 'unknown error'}`)
      return
    }

    this.pendingApprovals.delete(approvalKey)
    const acknowledgement = alwaysApprove
      ? 'Approved (always for this tool). Processing...'
      : 'Approved. Processing...'
    await pending.updateStatusAfterDecision?.(acknowledgement)
    await this.sendReply(msg, acknowledgement)

    // The SSE stream opened by handleMessageWithProgress remains the primary
    // delivery path. The fallback starts only after approval, so a stream that
    // closes before terminal cannot strand a completed task result.
    pending.startResultPollingFallback?.()
  }

  /**
   * Poll mcp-host for pending cron task results and deliver them to channels.
   * Cron tasks bypass the approval gate, so mcp-host only emits completed results.
   */
  private async pollCronResults(): Promise<void> {
    try {
      const results = await this.rpcClient.getCronResults()
      for (const result of results) {
        const adapter = this.adapterForRuntimeSource(result.origin)
        if (!adapter) {
          console.warn(
            `[Main] No adapter for ${result.origin.channelType}, cannot deliver cron result ${result.id}`
          )
          continue
        }

        // Cron tasks bypass the approval gate, so mcp-host only ever emits completed
        // cron results (status === 'completed', no approval payload). Deliver and acknowledge.
        console.log(
          `[Main] Delivering cron result: ${result.cronJobName} → ${result.origin.channelType}:${result.origin.channelId}`
        )
        await adapter.sendMessage(
          result.origin.channelId,
          result.response,
          undefined,
          result.attachments
        )
        await this.rpcClient.acknowledgeCronResult(result.id, result.origin)
        console.log(`[Main] Cron result delivered and acknowledged: ${result.id}`)
      }
    } catch (err) {
      // Silent — cron results are best-effort, don't break poll loop
      console.error('[Main] Failed to poll cron results:', err)
    }
  }

  /**
   * Remove stale pending approval entries.
   */
  private cleanupStaleApprovals(): void {
    const now = Date.now()
    for (const [key, state] of this.pendingApprovals) {
      if (now - state.createdAt.getTime() > PENDING_APPROVAL_TTL_MS) {
        console.log(`[Main] Cleaning up stale approval: ${key}`)
        this.pendingApprovals.delete(key)
      }
    }
    for (const [key, processed] of this.processedProviderEvents) {
      if (now - processed.seenAt > PROVIDER_EVENT_DEDUPE_TTL_MS) {
        this.processedProviderEvents.delete(key)
      }
    }
    for (const [key, notice] of this.unresolvedNoticesSent) {
      if (now - notice.seenAt > UNRESOLVED_NOTICE_TTL_MS) {
        this.unresolvedNoticesSent.delete(key)
      }
    }
    // A later trip into the cap must warn again, so once eviction above drains
    // the map back under it, allow the next crossing to log.
    if (this.unresolvedNoticesSent.size < UNRESOLVED_NOTICE_GLOBAL_CAP) {
      this.unresolvedNoticeCapLogged = false
    }
  }

  /**
   * Send a reply back to the original channel.
   */
  async sendReply(
    originalMessage: Message,
    replyContent: string,
    attachments?: Attachment[],
    options?: SendMessageOptions
  ): Promise<void> {
    const adapter = this.adapterForMessage(originalMessage)
    if (!adapter) {
      console.warn(`[Main] No adapter found for ${originalMessage.channelType}, cannot send reply`)
      return
    }

    try {
      console.log(`[Main] Sending reply to ${originalMessage.channelType}...`)
      await adapter.sendMessage(
        this.replyChannelId(originalMessage),
        replyContent,
        this.replyTargetMessageId(originalMessage),
        attachments,
        options
      )
      console.log(`[Main] Reply sent successfully`)
    } catch (err) {
      console.error(`[Main] Failed to send reply:`, err)
    }
  }

  /**
   * Restart the reader with new channel configurations (production mode only).
   */
  async restart(): Promise<void> {
    if (config.devMode) return

    console.log('[Main] Restarting with new channel configurations...')

    // Shutdown existing adapters
    await this.shutdownAdapters()

    // Reload channels
    this.channels = this.watcher!.getChannels()

    if (this.channels.length === 0) {
      console.warn(`[Main] No CommunicationChannels found for hostRef "${config.hostRef}"`)
    } else {
      console.log(`[Main] Loaded ${this.channels.length} CommunicationChannel(s)`)
    }

    // Reinitialize adapters
    await this.initializeAdapters()

    this.needsRestart = false
    console.log('[Main] Restart complete')
  }

  private async startHandoffServer(): Promise<void> {
    if (this.handoffServer || !config.channelReaderHandoffToken) return

    this.handoffServer = createChannelReaderHandoffServer(this, config.channelReaderHandoffToken)
    await new Promise<void>((resolve, reject) => {
      this.handoffServer!.once('error', reject)
      this.handoffServer!.listen(config.channelReaderHandoffPort, '0.0.0.0', () => {
        this.handoffServer!.off('error', reject)
        console.log(
          `[Main] Channel-reader handoff server listening on ${config.channelReaderHandoffPort}`
        )
        resolve()
      })
    })
  }

  private async stopHandoffServer(): Promise<void> {
    const server = this.handoffServer
    if (!server) return
    this.handoffServer = null
    await new Promise<void>(resolve => server.close(() => resolve()))
  }

  /**
   * Start the reader. If no CommunicationChannels match the hostRef filter,
   * warns and continues — the CRD watcher will trigger a restart when
   * channels appear.
   */
  async start(): Promise<void> {
    console.log('[Main] Starting Clerum Channel Reader...')
    console.log(`[Main] Mode: ${config.devMode ? 'DEV' : 'PRODUCTION'}`)
    console.log(`[Main] Host ref: "${config.hostRef}"`)
    console.log(`[Main] Poll interval: ${config.pollIntervalSeconds}s`)

    await this.initialize()

    if (config.devMode) {
      // Dev mode: load from env var (throws if not configured)
      console.log('[Main] Dev mode: reading channel config from CLERUM_CHANNEL env var')
      this.channels = this.loadDevChannels()
    } else {
      // Production mode: watch Kubernetes CRDs
      console.log(`[Main] Production mode: watching K8s namespace "${config.namespace || 'all'}"`)
      this.channels = await this.watcher!.listChannels()

      if (this.channels.length === 0) {
        console.warn(
          `[Main] No CommunicationChannel CRDs found for hostRef "${config.hostRef}" in namespace "${config.namespace || 'all'}". ` +
            `Channel-reader will idle and pick up channels as they appear via the CRD watcher.`
        )
      } else {
        console.log(`[Main] Found ${this.channels.length} CommunicationChannel(s)`)
      }

      // Start watching for changes
      await this.watcher!.startWatch()
    }

    // Initialize adapters (idles if no channels configured yet)
    this.running = true
    this.lastChannelResyncAt = Date.now()

    await this.initializeAdapters()
    await this.startHandoffServer()

    // Polling loop
    while (this.running) {
      // Check if we need to restart due to CRD changes (production mode only)
      if (!config.devMode && this.needsRestart) {
        try {
          await this.restart()
        } catch (err) {
          console.error(
            '[Main] Restart failed (will retry on next cycle if CRD watch keeps needsRestart):',
            err instanceof Error ? err.message : err
          )
        }
      }

      // Periodic CommunicationChannel resync (production mode only).
      // Re-lists channels so a missed watch event self-heals within one
      // CHANNEL_RESYNC_INTERVAL_MS window, independent of onChange.
      if (
        !config.devMode &&
        this.watcher &&
        Date.now() - this.lastChannelResyncAt >= CHANNEL_RESYNC_INTERVAL_MS
      ) {
        console.log('[Main] Periodic CommunicationChannel resync...')
        await this.watcher.resyncChannels()
        this.lastChannelResyncAt = Date.now()
      }

      // Run poll cycle if we have channels
      if (this.channels.length > 0) {
        await this.pollCycle()
      }

      await this.sleep(config.pollIntervalSeconds * 1000)
    }
  }

  /**
   * Stop the reader.
   */
  async stop(): Promise<void> {
    console.log('[Main] Stopping...')
    this.running = false
    if (this.watcher) {
      this.watcher.stopWatch()
    }
    await this.stopHandoffServer()
    await this.shutdownAdapters()
    console.log('[Main] Stopped')
  }

  private sleep(ms: number): Promise<void> {
    return this.sleepImpl(ms)
  }
}

// Main entry point
async function main(): Promise<void> {
  const reader = new ChannelReader()

  // Handle shutdown signals
  process.on('SIGINT', async () => {
    await reader.stop()
    process.exit(0)
  })

  process.on('SIGTERM', async () => {
    await reader.stop()
    process.exit(0)
  })

  await reader.start()
}

if (require.main === module) {
  main().catch(error => {
    console.error('[Main] Fatal error:', error)
    process.exit(1)
  })
}