Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
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
}
}