Skip to content

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

TypeScript
13.8 KB
Raw Blame
import { config } from './config'
import {
  type NotificationDelivery,
  type NotificationDeliveryClient,
  type NotificationDeliveryMedium,
} from './notificationDeliveryClient'
import type { RPCClient } from './rpcClient'
import type { ChannelAdapter, CommunicationChannelCRD, Message, ProviderIdentity } from './types'
import type {
  WorkflowApprovalDecisionCallbackCommand,
  WorkflowApprovalDecisionCommand,
} from './workflowApprovalDecision'
import { formatNotificationDelivery } from './workflowApprovalNotificationFormatter'
import { WorkflowApprovalPendingApprovals } from './workflowApprovalPendingApprovals'
import {
  getConfiguredProviderChannelGroups,
  hostRefForProviderIdentity,
} from './workflowApprovalProviderChannels'

type WorkflowApprovalRpcClient = Pick<
  RPCClient,
  'sendWorkflowApprovalDecision' | 'resolveWorkflowApproval'
>

type WorkflowApprovalNotificationClient = Pick<
  NotificationDeliveryClient,
  'fetchDeliveries' | 'acknowledge' | 'fail'
>

export type WorkflowApprovalCoordinatorOptions = {
  rpcClient: WorkflowApprovalRpcClient
  notificationDeliveryClient: WorkflowApprovalNotificationClient | null
  getAdapters: () => Map<string, ChannelAdapter>
  getAdapterForChannel?: (
    medium: NotificationDeliveryMedium,
    channelRef: { namespace: string; name: string }
  ) => ChannelAdapter | undefined
  getChannels: () => CommunicationChannelCRD[]
  sendReply: (message: Message, content: string) => Promise<void>
}

type TeamsThreadTarget = {
  conversationId: string
  replyToMessageId: string
}

function asRecord(value: unknown): Record<string, unknown> | null {
  return value && typeof value === 'object' && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : null
}

function optionalString(value: unknown): string | null {
  return typeof value === 'string' && value.trim() ? value.trim() : null
}

export class WorkflowApprovalCoordinator {
  private readonly rpcClient: WorkflowApprovalRpcClient
  private readonly notificationDeliveryClient: WorkflowApprovalNotificationClient | null
  private readonly getAdapters: () => Map<string, ChannelAdapter>
  private readonly getAdapterForChannel:
    | ((
        medium: NotificationDeliveryMedium,
        channelRef: { namespace: string; name: string }
      ) => ChannelAdapter | undefined)
    | null
  private readonly getChannels: () => CommunicationChannelCRD[]
  private readonly sendReply: (message: Message, content: string) => Promise<void>
  private readonly pendingWorkflowApprovals = new WorkflowApprovalPendingApprovals()

  constructor(options: WorkflowApprovalCoordinatorOptions) {
    this.rpcClient = options.rpcClient
    this.notificationDeliveryClient = options.notificationDeliveryClient
    this.getAdapters = options.getAdapters
    this.getAdapterForChannel = options.getAdapterForChannel ?? null
    this.getChannels = options.getChannels
    this.sendReply = options.sendReply
  }

  async handleDecisionCommand(
    msg: Message,
    command: WorkflowApprovalDecisionCommand | null
  ): Promise<void> {
    if (!command) return
    if (
      (command.providerIdentity.medium === 'slack' ||
        command.providerIdentity.medium === 'teams') &&
      !command.providerIdentity.providerWorkspaceId
    ) {
      await this.sendReply(msg, 'Unable to verify provider workspace identity for this approval.')
      return
    }

    const resolvedCommand = await this.resolveDecisionCommand(msg, command)
    if (!resolvedCommand) return

    const decisionPayload = {
      approvalRequestId: resolvedCommand.approvalRequestId,
      decision: resolvedCommand.decision,
      providerIdentity: resolvedCommand.providerIdentity,
      ...(resolvedCommand.note ? { note: resolvedCommand.note } : {}),
    }
    const result = await this.rpcClient.sendWorkflowApprovalDecision(decisionPayload)
    if (!result.success) {
      await this.sendReply(
        msg,
        `Failed to record workflow approval: ${result.error ?? 'unknown error'}`
      )
      return
    }

    this.pendingWorkflowApprovals.forget(resolvedCommand.approvalRequestId)
    const action = command.decision === 'approve' ? 'Approved' : 'Denied'
    await this.sendReply(
      msg,
      result.duplicate
        ? `${action}. This provider decision was already processed.`
        : `${action}. Workflow approval recorded.`
    )
  }

  async handleDecisionCallback(
    msg: Message,
    command: WorkflowApprovalDecisionCallbackCommand | null
  ): Promise<void> {
    if (!command) return
    if (
      (command.providerIdentity.medium === 'slack' ||
        command.providerIdentity.medium === 'teams') &&
      !command.providerIdentity.providerWorkspaceId
    ) {
      await this.sendReply(msg, 'Unable to verify provider workspace identity for this approval.')
      return
    }

    const decisionPayload = {
      approvalRequestId: command.approvalRequestId,
      decision: command.decision,
      providerIdentity: command.providerIdentity,
      ...(command.note ? { note: command.note } : {}),
    }
    const result = await this.rpcClient.sendWorkflowApprovalDecision(decisionPayload)
    if (!result.success) {
      await this.sendReply(
        msg,
        `Failed to record workflow approval: ${result.error ?? 'unknown error'}`
      )
      return
    }

    this.pendingWorkflowApprovals.forget(command.approvalRequestId)
    const action = command.decision === 'approve' ? 'Approved' : 'Denied'
    await this.sendReply(
      msg,
      result.duplicate
        ? `${action}. This provider decision was already processed.`
        : `${action}. Workflow approval recorded.`
    )
  }

  async pollNotifications(): Promise<void> {
    if (!this.notificationDeliveryClient) return

    for (const medium of ['telegram', 'slack', 'teams'] as const) {
      const providerChannelGroups = getConfiguredProviderChannelGroups(medium, this.getChannels())
      if (providerChannelGroups.length === 0) continue

      for (const providerChannelGroup of providerChannelGroups) {
        const adapter =
          this.getAdapterForChannel?.(medium, {
            namespace: providerChannelGroup.communicationChannelNamespace,
            name: providerChannelGroup.communicationChannelName,
          }) ?? this.getAdapters().get(medium)
        if (!adapter) continue

        let deliveries: NotificationDelivery[]
        try {
          deliveries = await this.notificationDeliveryClient.fetchDeliveries({
            medium,
            providerChannelIds: providerChannelGroup.providerChannelIds,
            providerWorkspaceId: providerChannelGroup.providerWorkspaceId,
            hostRef: providerChannelGroup.hostRef,
            limit: config.notificationDeliveryPollLimit,
          })
        } catch (err) {
          console.error(`[WorkflowApproval] Failed to fetch ${medium} notifications:`, err)
          continue
        }

        for (const delivery of deliveries) {
          await this.deliverNotification(adapter, delivery, medium, providerChannelGroup.hostRef, {
            namespace: providerChannelGroup.communicationChannelNamespace,
            name: providerChannelGroup.communicationChannelName,
          })
        }
      }
    }
  }

  private async deliverNotification(
    adapter: ChannelAdapter,
    delivery: NotificationDelivery,
    medium: NotificationDeliveryMedium,
    hostRef: string,
    channelRef: { namespace: string; name: string }
  ): Promise<void> {
    try {
      if (delivery.eventType === 'approval.updated') {
        this.pendingWorkflowApprovals.forget(delivery.payload.approvalRequestId)
        await this.notificationDeliveryClient?.acknowledge(delivery.id, {
          medium,
          providerUserId: delivery.providerUserId,
          providerChannelId: delivery.providerChannelId,
          providerWorkspaceId: delivery.providerWorkspaceId,
          hostRef,
        })
        return
      }

      const message = formatNotificationDelivery(delivery, {
        communicationChannelRef: `${channelRef.namespace}/${channelRef.name}`,
      })
      const teamsThreadTarget = this.teamsThreadTarget(delivery, channelRef)
      await adapter.sendMessage(
        teamsThreadTarget?.conversationId ?? delivery.providerChannelId,
        message.content,
        teamsThreadTarget?.replyToMessageId,
        undefined,
        message.sendOptions
      )
      if (delivery.eventType === 'approval.requested') {
        this.pendingWorkflowApprovals.track(delivery)
      }
      await this.notificationDeliveryClient?.acknowledge(delivery.id, {
        medium,
        providerUserId: delivery.providerUserId,
        providerChannelId: delivery.providerChannelId,
        providerWorkspaceId: delivery.providerWorkspaceId,
        hostRef,
      })
    } catch (err) {
      console.error(`[WorkflowApproval] Failed to deliver notification ${delivery.id}:`, err)
      try {
        await this.notificationDeliveryClient?.fail(delivery.id, {
          medium,
          providerUserId: delivery.providerUserId,
          providerChannelId: delivery.providerChannelId,
          providerWorkspaceId: delivery.providerWorkspaceId,
          hostRef,
        })
      } catch (failErr) {
        console.error(
          `[WorkflowApproval] Failed to record notification delivery failure ${delivery.id}:`,
          failErr
        )
      }
    }
  }

  private teamsThreadTarget(
    delivery: NotificationDelivery,
    channelRef: { namespace: string; name: string }
  ): TeamsThreadTarget | null {
    if (delivery.medium !== 'teams') return null
    const channel = this.getChannels().find(
      item => item.namespace === channelRef.namespace && item.name === channelRef.name
    )
    const group = channel?.spec.teams?.find(
      item =>
        item.channelId === delivery.providerChannelId &&
        item.tenantId === delivery.providerWorkspaceId
    )
    if (group?.replyInThreads === false) return null

    if (delivery.eventType === 'approval.requested') {
      const metadata = asRecord(delivery.payload.metadata)
      const workflowTrigger = asRecord(metadata?.workflowTrigger)
      const providerBinding = asRecord(workflowTrigger?.providerBinding)
      if (optionalString(providerBinding?.medium) !== 'teams') return null
      return this.validTeamsThreadTarget(
        optionalString(workflowTrigger?.conversationId),
        optionalString(providerBinding?.providerThreadId)
      )
    }

    if (delivery.eventType === 'workflow.run.completed') {
      return this.validTeamsThreadTarget(
        optionalString(delivery.payload.providerConversationId),
        optionalString(delivery.payload.providerThreadId)
      )
    }

    return null
  }

  private validTeamsThreadTarget(
    conversationId: string | null,
    replyToMessageId: string | null
  ): TeamsThreadTarget | null {
    return conversationId && replyToMessageId ? { conversationId, replyToMessageId } : null
  }

  private async resolveDecisionCommand(
    msg: Message,
    command: WorkflowApprovalDecisionCommand
  ): Promise<(WorkflowApprovalDecisionCommand & { approvalRequestId: string }) | null> {
    const recipeName = command.recipeName.trim()
    if (!recipeName) return null

    const approvals = this.pendingWorkflowApprovals.list(command.providerIdentity, recipeName)
    if (approvals.length === 0) {
      let restoredApprovalRequestId: string | null
      try {
        restoredApprovalRequestId = await this.resolvePendingApprovalFromRuntime(
          command.providerIdentity,
          recipeName
        )
      } catch (err) {
        console.error(
          `[WorkflowApproval] Failed to resolve pending approval through mcp-host:`,
          err
        )
        await this.sendReply(
          msg,
          `Could not verify the pending workflow approval for ${recipeName}. Try again after the approval request is delivered.`
        )
        return null
      }
      if (restoredApprovalRequestId) {
        return { ...command, approvalRequestId: restoredApprovalRequestId }
      }
      await this.sendReply(
        msg,
        `No pending workflow approval found for ${recipeName}. Use the workflow name shown in the approval request.`
      )
      return null
    }
    if (approvals.length > 1) {
      let restoredApprovalRequestId: string | null
      try {
        restoredApprovalRequestId = await this.resolvePendingApprovalFromRuntime(
          command.providerIdentity,
          recipeName
        )
      } catch (err) {
        console.error(
          `[WorkflowApproval] Failed to reconcile ambiguous pending workflow approvals through mcp-host:`,
          err
        )
        const message = err instanceof Error ? err.message : ''
        await this.sendReply(
          msg,
          message === 'pending_workflow_approval_ambiguous'
            ? `More than one pending workflow approval was found for ${recipeName}. Use the approval button on the specific request.`
            : `Could not verify the pending workflow approval for ${recipeName}. Try again after the approval request is delivered.`
        )
        return null
      }
      if (restoredApprovalRequestId) {
        this.pendingWorkflowApprovals.replace(
          command.providerIdentity,
          recipeName,
          restoredApprovalRequestId
        )
        return { ...command, approvalRequestId: restoredApprovalRequestId }
      }
      this.pendingWorkflowApprovals.clear(command.providerIdentity, recipeName)
      await this.sendReply(
        msg,
        `No pending workflow approval found for ${recipeName}. Use the workflow name shown in the approval request.`
      )
      return null
    }

    return { ...command, approvalRequestId: approvals[0].approvalRequestId }
  }

  private async resolvePendingApprovalFromRuntime(
    identity: ProviderIdentity,
    recipeName: string
  ): Promise<string | null> {
    const hostRef = hostRefForProviderIdentity(identity, this.getChannels())
    if (!hostRef) return null
    const resolved = await this.rpcClient.resolveWorkflowApproval({
      recipeName,
      providerIdentity: identity,
    })
    return resolved?.approvalRequestId ?? null
  }
}