Skip to content

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

TypeScript
12.8 KB
Raw Blame
import { createHash } from 'node:crypto'
import { getMcpHostRuntimeCallerKey } from '../../workflow/mcpHostRuntimeJwt'
import { gateStep } from '../../workflow/userApprovalRequester'
import { WorkflowTool } from './workflowBaseTool'
import { shouldResolveEffectiveWorkflowTargets } from './workflowEffectiveTargets'
import { approvalAuth, getObject, getString, requireWorkflowRef } from './workflowShared'
import { workflowTriggerApprovalExecutionId } from './workflowTriggerApprovalIdentity'
import {
  AUTHENTICATED_CHAT_APPROVAL_TIMEOUT_SECONDS,
  type EffectiveWorkflowTriggerParams,
  isApprovalTargetFallbackError,
  resolveAuthenticatedChatWorkflowTriggerParams,
  validateAuthenticatedChatWorkflowTriggerParams,
} from './workflowTriggerTargetResolution'

export class WorkflowTriggerTool extends WorkflowTool {
  private workflowArtifactScope: Record<string, unknown> | undefined

  name(): string {
    return 'workflow_trigger'
  }

  description(): string {
    return 'Request approval and trigger a workflow recipe after approval is granted.'
  }

  requiresApproval(): boolean {
    if (
      this.workflowCallerContext?.originChannelType === 'telegram' ||
      this.workflowCallerContext?.originChannelType === 'slack' ||
      this.workflowCallerContext?.originChannelType === 'teams'
    ) {
      return false
    }
    return true
  }

  parametersSchema(): Record<string, unknown> {
    if (this.workflowCallerContext?.targetUserId || this.workflowCallerContext?.targetTeamId) {
      const properties: Record<string, unknown> = {
        name: { type: 'string', description: 'WorkflowRecipe name.' },
        inputs: { type: 'object', description: 'Workflow business inputs.' },
      }
      if (shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext)) {
        properties.targetLabel = {
          type: 'string',
          description:
            'Human target label returned by workflow_list, such as Personal or a team name.',
        }
      }
      return {
        type: 'object',
        properties,
        required: ['name'],
      }
    }
    return {
      type: 'object',
      properties: {
        namespace: { type: 'string', description: 'WorkflowRecipe namespace.' },
        name: { type: 'string', description: 'WorkflowRecipe name.' },
        targetUserId: { type: 'string', description: 'User UUID to request approval from.' },
        targetTeamId: { type: 'string', description: 'Team UUID to request approval from.' },
        approvalMessage: { type: 'string', description: 'Message shown to the approver.' },
        timeoutSeconds: { type: 'number', description: 'Approval polling timeout in seconds.' },
        inputs: { type: 'object', description: 'Workflow inputs.' },
        intermediateParameters: {
          type: 'object',
          description: 'Workflow intermediate parameters.',
        },
        outputOverrides: { type: 'object', description: 'Workflow output overrides.' },
      },
      required: ['namespace', 'name'],
    }
  }

  private async effectiveParamsForResolvedAuthenticatedChat(
    params: Record<string, unknown>
  ): Promise<EffectiveWorkflowTriggerParams | Record<string, unknown>> {
    return resolveAuthenticatedChatWorkflowTriggerParams({
      client: this.client,
      workflowCallerContext: this.workflowCallerContext,
      triggerParams: params,
    })
  }

  private effectiveParamSet(params: Record<string, unknown>): EffectiveWorkflowTriggerParams[] {
    if (this.workflowCallerContext?.targetUserId || this.workflowCallerContext?.targetTeamId) {
      const { namespace, name, inputs } = validateAuthenticatedChatWorkflowTriggerParams(
        params,
        this.workflowCallerContext
      )
      const authenticatedTargetUserId = this.workflowCallerContext.targetUserId
      const authenticatedTargetTeamId = this.workflowCallerContext.targetTeamId
      const base = {
        namespace,
        name,
        timeoutSeconds: AUTHENTICATED_CHAT_APPROVAL_TIMEOUT_SECONDS,
        inputs,
      }
      if (authenticatedTargetUserId && authenticatedTargetTeamId) {
        return [
          { ...base, targetUserId: authenticatedTargetUserId },
          { ...base, targetTeamId: authenticatedTargetTeamId },
        ]
      }
      if (!authenticatedTargetUserId && !authenticatedTargetTeamId) {
        throw new Error('authenticated conversation is missing workflow approval target')
      }
      return [
        authenticatedTargetUserId
          ? { ...base, targetUserId: authenticatedTargetUserId }
          : { ...base, targetTeamId: authenticatedTargetTeamId },
      ]
    }

    const { namespace, name } = requireWorkflowRef(params)
    return [
      {
        namespace,
        name,
        targetUserId: getString(params, 'targetUserId') || undefined,
        targetTeamId: getString(params, 'targetTeamId') || undefined,
        approvalMessage: getString(params, 'approvalMessage') || undefined,
        timeoutSeconds:
          typeof params.timeoutSeconds === 'number' && Number.isFinite(params.timeoutSeconds)
            ? Math.max(1, Math.floor(params.timeoutSeconds))
            : undefined,
        inputs: getObject(params, 'inputs') || undefined,
        intermediateParameters: getObject(params, 'intermediateParameters') || undefined,
        outputOverrides: getObject(params, 'outputOverrides') || undefined,
      },
    ]
  }

  async run(params: Record<string, unknown>): Promise<unknown> {
    if (shouldResolveEffectiveWorkflowTargets(this.workflowCallerContext)) {
      const resolved = await this.effectiveParamsForResolvedAuthenticatedChat(params)
      if (!('namespace' in resolved) || !('name' in resolved)) return resolved
      return this.runWithEffectiveParams(resolved as EffectiveWorkflowTriggerParams)
    }

    const candidates = this.effectiveParamSet(params)
    let lastError: unknown
    for (const effective of candidates) {
      try {
        return await this.runWithEffectiveParams(effective)
      } catch (error) {
        lastError = error
        if (candidates.length === 1 || !isApprovalTargetFallbackError(error)) throw error
      }
    }
    throw lastError
  }

  private async runWithEffectiveParams(
    effective: EffectiveWorkflowTriggerParams
  ): Promise<unknown> {
    const { namespace, name } = effective
    const targetUserId = effective.targetUserId
    const targetTeamId = effective.targetTeamId
    if (Boolean(targetUserId) === Boolean(targetTeamId)) {
      throw new Error('workflow_trigger requires exactly one of targetUserId or targetTeamId')
    }

    const workflowToken = await this.workflowControlTokenProvider.getWorkflowControlToken()
    const workflowControlCaller = getMcpHostRuntimeCallerKey(workflowToken)
    if (!workflowControlCaller) {
      throw new Error('workflow-control token must include hostRefs[0] for workflow_trigger')
    }

    const auth = approvalAuth(this.getEnv)
    if (auth.hostRef !== workflowControlCaller) {
      throw new Error(
        'workflow runtime token and workflow-control token caller bindings must match'
      )
    }
    const caller = workflowControlCaller
    const timeout = effective.timeoutSeconds
    const message =
      effective.approvalMessage ||
      (this.workflowCallerContext
        ? `Approve workflow trigger for ${name}`
        : `Approve workflow trigger for ${namespace}/${name}`)
    const providerBinding =
      this.workflowCallerContext?.providerChannelId &&
      (this.workflowCallerContext.originChannelType === 'telegram' ||
        this.workflowCallerContext.originChannelType === 'slack' ||
        this.workflowCallerContext.originChannelType === 'teams')
        ? {
            medium: this.workflowCallerContext.originChannelType,
            providerChannelId: this.workflowCallerContext.providerChannelId,
            ...(this.workflowCallerContext.providerWorkspaceId
              ? { providerWorkspaceId: this.workflowCallerContext.providerWorkspaceId }
              : {}),
            ...(this.workflowCallerContext.sourceThreadId
              ? { providerThreadId: this.workflowCallerContext.sourceThreadId }
              : {}),
          }
        : undefined
    const approvalExecutionId = workflowTriggerApprovalExecutionId({
      caller,
      namespace,
      name,
      targetUserId,
      targetTeamId,
      inputs: effective.inputs,
      workflowCallerContext: this.workflowCallerContext,
    })
    if (this.workflowCallerContext && !approvalExecutionId) {
      throw new Error('workflow_trigger requires a stable approval execution id')
    }
    const runIdempotencyKey = approvalExecutionId
      ? `workflow-trigger-${createHash('sha256').update(approvalExecutionId).digest('hex')}`
      : undefined

    const runtimeMcpHostRef = this.runtimeMcpHostRef()
    const approval = await gateStep(
      {
        stepId: `workflow_trigger:${namespace}/${name}`,
        executionId: approvalExecutionId,
        ...(runIdempotencyKey ? { idempotencyKeyOverride: runIdempotencyKey } : {}),
        ...(runtimeMcpHostRef ? { runtimeMcpHostRef } : {}),
        target: targetUserId ? { userId: targetUserId } : { teamId: targetTeamId },
        message,
        timeoutSeconds: timeout,
        approvalRecipe: {
          recipeNamespace: namespace,
          recipeName: name,
        },
        payloadMetadata: {
          workflowTrigger: {
            namespace,
            name,
            caller,
            ...(this.workflowCallerContext?.targetUserId
              ? { requesterUserId: this.workflowCallerContext.targetUserId }
              : {}),
            ...(this.workflowCallerContext?.conversationId
              ? { conversationId: this.workflowCallerContext.conversationId }
              : {}),
            ...(providerBinding ? { providerBinding } : {}),
          },
        },
        ...(runIdempotencyKey
          ? {
              workflowTriggerRunIntent: {
                inputs: effective.inputs ?? {},
                intermediateParameters: effective.intermediateParameters ?? null,
                outputOverrides: effective.outputOverrides ?? null,
              },
            }
          : {}),
        allowConsumedTerminal: true,
      },
      auth
    )
    if (!approval.approvalRequestId) {
      throw new Error('workflow_trigger approval completed without approvalRequestId')
    }

    const idempotencyKey =
      runIdempotencyKey ||
      `workflow-trigger-${createHash('sha256')
        .update(`${approval.approvalRequestId}:${namespace}:${name}:${caller}`)
        .digest('hex')}`
    const body: Record<string, unknown> = {
      approvalRequestId: approval.approvalRequestId,
    }
    if (effective.inputs) body.inputs = effective.inputs
    if (effective.intermediateParameters) {
      body.intermediateParameters = effective.intermediateParameters
    }
    if (effective.outputOverrides) body.outputOverrides = effective.outputOverrides

    const run = await this.client.request(
      `/api/v1/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/trigger`,
      {
        method: 'POST',
        headers: { 'Idempotency-Key': idempotencyKey },
        body: JSON.stringify(body),
      }
    )
    const runRecord = run && typeof run === 'object' ? (run as Record<string, unknown>) : {}
    const runId = typeof runRecord.id === 'string' ? runRecord.id : ''
    const triggeredAt =
      typeof runRecord.triggeredAt === 'string' ? runRecord.triggeredAt : undefined
    const requestedAt = triggeredAt ? Date.parse(triggeredAt) : undefined
    this.workflowArtifactScope = runId
      ? {
          workflowArtifactScope: {
            namespace,
            name,
            label: name,
            runId,
            ...(requestedAt !== undefined && Number.isFinite(requestedAt) ? { requestedAt } : {}),
          },
        }
      : undefined
    return {
      workflowName: name,
      ...(this.workflowCallerContext && effective.targetLabel
        ? { target: { label: effective.targetLabel } }
        : {}),
      phase: typeof runRecord.phase === 'string' ? runRecord.phase : undefined,
      triggeredAt,
      startedAt: typeof runRecord.startedAt === 'string' ? runRecord.startedAt : null,
      completedAt: typeof runRecord.completedAt === 'string' ? runRecord.completedAt : null,
      message: typeof runRecord.message === 'string' ? runRecord.message : null,
      ...(this.workflowCallerContext
        ? {}
        : {
            runId: runId || undefined,
            workflowNamespace: namespace,
          }),
    }
  }

  private runtimeMcpHostRef(): string | undefined {
    const namespace = this.getEnv('CLERUM_WORKFLOW_NAMESPACE')?.trim()
    const recipeName = this.getEnv('CLERUM_WORKFLOW_RECIPE')?.trim()
    if (!namespace || !recipeName) return undefined
    if (namespace !== 'sandbox-recipes') return undefined
    if (!/^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/.test(recipeName)) return undefined
    return `${namespace}/${recipeName}`
  }

  protected metadataForResult(_data: unknown): Record<string, unknown> | undefined {
    return this.workflowArtifactScope
  }
}