Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

15.5 KB
Raw Blame
import { isNil, tryCatch } from '@activepieces/core-utils'
import { EngineGenericError, EngineResponse, EngineResponseStatus, ExecuteFlowOperation, ExecuteTriggerResponse, ExecutionError, ExecutionErrorType, ExecutionState, ExecutionType, FlowActionType, FlowRunStatus, flowStructureUtil, GenericStepOutput, InvalidSeededStepsError, LoopStepOutput, ResumePayload, ResumeReason, StepOutput, StepOutputStatus, TriggerHookType, TriggerPayload } from '@activepieces/shared'
import dayjs from 'dayjs'
import { engineFileApi } from '../api/engine-file-api'
import { EngineConstants, ResolvedBeginExecuteFlowOperation, ResolvedExecuteFlowOperation } from '../handler/context/engine-constants'
import { FlowExecutorContext } from '../handler/context/flow-execution-context'
import { testExecutionContext } from '../handler/context/test-execution-context'
import { flowExecutor } from '../handler/flow-executor'
import { flowRunProgressReporter } from '../helper/flow-run-progress-reporter'
import { triggerHelper } from '../helper/trigger-helper'
import { utils } from '../utils'
import { resolveJobPayload } from './utils/resolve-job-payload'

export const flowOperation = {
    execute: async (operation: ExecuteFlowOperation): Promise<EngineResponse<undefined>> => {
        const { data: input, error: resolveError } = await tryCatch(() => resolveExecuteFlowOperation(operation))
        if (resolveError) {
            // Resolving inputs before execution downloads files: the trigger payload (BEGIN) or the resume
            // log/payload (RESUME). If one was deleted/expired (404), that is a user/data-lifecycle error, not
            // an engine bug — report a FAILED run instead of letting it escape as INTERNAL_ERROR, which
            // fails+retries the worker job and pages oncall (and can never recover an expired file).
            // EngineFileNotFoundError is USER-typed precisely for this; a BEGIN-only gate defeated it on
            // RESUME. Only genuine ENGINE errors (e.g. a transient 5xx download) keep the throw path.
            if (!isEngineExecutionError(resolveError)) {
                return reportFailedTriggerRun({ operation, error: resolveError })
            }
            throw resolveError
        }
        const constants = EngineConstants.fromExecuteFlowInput(input)
        const { data: output, error: executionError } = await tryCatch(() => executeSingleStepOrFlow(input, constants))
        if (executionError) {
            // Trigger run()/onStart() hooks and single-step test resolution can throw a plain Error/TypeError
            // or a non-ExecutionError (e.g. ENTITY_NOT_FOUND when testing a deleted step). Like an action step
            // throwing, those are user/piece-level failures and must surface as a FAILED run, never
            // INTERNAL_ERROR. Only genuine ENGINE errors keep paging + retrying.
            if (isEngineExecutionError(executionError)) {
                throw executionError
            }
            return reportFailedRun({ input, constants, error: executionError })
        }
        const finished = output.finishExecution()
        await flowRunProgressReporter.sendUpdate({
            engineConstants: constants,
            flowExecutorContext: finished,
        })
        await flowRunProgressReporter.backup()
        const status = finished.verdict.status === FlowRunStatus.LOG_SIZE_EXCEEDED
            ? EngineResponseStatus.LOG_SIZE_EXCEEDED
            : EngineResponseStatus.OK
        return {
            status,
            response: undefined,
        }
    },
}

function isEngineExecutionError(error: unknown): boolean {
    return error instanceof ExecutionError && error.type === ExecutionErrorType.ENGINE
}

async function reportFailedTriggerRun({ operation, error }: ReportFailedTriggerRunParams): Promise<EngineResponse<undefined>> {
    // Inputs were never resolved (that is why we are here), so build a minimal resolved shape purely to report
    // a FAILED run. buildFailedTriggerContext only reads flowVersion + executionType, so the resume
    // placeholders below are never actually consumed — they exist solely to satisfy ResolvedExecuteFlowOperation.
    const input: ResolvedExecuteFlowOperation = operation.executionType === ExecutionType.BEGIN
        ? { ...operation, triggerPayload: undefined }
        : { ...operation, resumePayload: { body: undefined, headers: {}, queryParams: {} }, executionState: { steps: {}, tags: [] } }
    return reportFailedRun({ input, constants: EngineConstants.fromExecuteFlowInput(input), error })
}

async function reportFailedRun({ input, constants, error }: ReportFailedRunParams): Promise<EngineResponse<undefined>> {
    const baseContext = FlowExecutorContext.empty({
        engineApi: {
            engineToken: constants.engineToken,
            internalApiUrl: constants.internalApiUrl,
        },
    })
    const output = (await buildFailedTriggerContext({ input, baseContext, error })).finishExecution()
    await flowRunProgressReporter.sendUpdate({
        engineConstants: constants,
        flowExecutorContext: output,
    })
    await flowRunProgressReporter.backup()
    return {
        status: EngineResponseStatus.OK,
        response: undefined,
    }
}

const executeSingleStepOrFlow = async (input: ResolvedExecuteFlowOperation, constants: EngineConstants): Promise<FlowExecutorContext> => {
    const testSingleStepMode = !isNil(constants.stepNameToTest)
    if (testSingleStepMode) {
        const testContext = await testExecutionContext.stateFromFlowVersion({
            apiUrl: input.internalApiUrl,
            flowVersion: input.flowVersion,
            excludedStepName: input.stepNameToTest!,
            projectId: input.projectId,
            engineToken: input.engineToken,
            sampleData: input.sampleData,
            engineConstants: constants,
        })
        const step = flowStructureUtil.getActionOrThrow(input.stepNameToTest!, input.flowVersion.trigger)
        const executionState = await resolveStateOrThrowOnNonUserError({ input, constants, baseContext: testContext })
        if (executionState.verdict.status !== FlowRunStatus.RUNNING) {
            return executionState
        }
        return flowExecutor.execute({
            action: step,
            executionState,
            constants,
        })
    }
    const emptyContext = FlowExecutorContext.empty({
        engineApi: {
            engineToken: constants.engineToken,
            internalApiUrl: constants.internalApiUrl,
        },
    })
    const executionState = await resolveStateOrThrowOnNonUserError({ input, constants, baseContext: emptyContext })
    if (executionState.verdict.status !== FlowRunStatus.RUNNING) {
        return executionState
    }
    if (!isNil(input.entryStepName)) {
        if (input.executionType === ExecutionType.BEGIN) {
            await flowRunProgressReporter.sendUpdate({
                engineConstants: constants,
                flowExecutorContext: executionState,
                startTime: dayjs().toISOString(),
            })
        }
        return flowExecutor.execute({
            action: flowStructureUtil.getActionOrThrow(input.entryStepName, input.flowVersion.trigger),
            executionState,
            constants,
        })
    }
    return flowExecutor.executeFromTrigger({
        executionState,
        constants,
        input,
    })
}

async function resolveStateOrThrowOnNonUserError({ input, constants, baseContext }: ResolveStateParams): Promise<FlowExecutorContext> {
    const { data: executionState, error } = await tryCatch(() => getFlowExecutionState(input, constants, baseContext))
    if (!error) {
        return executionState
    }
    if (error instanceof ExecutionError && error.type === ExecutionErrorType.USER) {
        return buildFailedTriggerContext({ input, baseContext, error })
    }
    throw error
}

async function buildFailedTriggerContext({ input, baseContext, error }: BuildFailedTriggerContextParams): Promise<FlowExecutorContext> {
    const trigger = input.flowVersion.trigger
    const message = error instanceof ExecutionError ? utils.formatExecutionError(error) : utils.formatError(error)
    const triggerPayload = input.executionType === ExecutionType.BEGIN ? input.triggerPayload : undefined
    const failedTriggerOutput = GenericStepOutput.create({
        type: trigger.type,
        status: StepOutputStatus.FAILED,
        input: {},
    }).setOutput(triggerPayload ?? {}).setErrorMessage(message)
    return (await baseContext.upsertStep(trigger.name, failedTriggerOutput)).setVerdict({
        status: FlowRunStatus.FAILED,
        failedStep: {
            name: trigger.name,
            displayName: trigger.displayName ?? trigger.name,
            message,
        },
    })
}

async function getFlowExecutionState(input: ResolvedExecuteFlowOperation, constants: EngineConstants, flowContext: FlowExecutorContext): Promise<FlowExecutorContext> {
    if (input.executionType === ExecutionType.BEGIN) {
        if (!isNil(input.entryStepName)) {
            if (!isSeededSteps(input.triggerPayload)) {
                throw new InvalidSeededStepsError(input.entryStepName)
            }
            return restoreSteps({ steps: input.triggerPayload, flowContext, keepFailedSteps: true })
        }
        const newPayload = await runOrReturnPayload(input, constants)
        return flowContext.upsertStep(input.flowVersion.trigger.name,
            GenericStepOutput.create({
                type: input.flowVersion.trigger.type,
                status: StepOutputStatus.SUCCEEDED,
                input: {},
            }).setOutput(newPayload))
    }
    return restoreSteps({
        steps: input.executionState.steps,
        flowContext: flowContext.addTags(input.executionState.tags),
        keepFailedSteps: input.resumeReason === ResumeReason.WAITPOINT,
    })
}

async function restoreSteps({ steps, flowContext, keepFailedSteps }: RestoreStepsParams): Promise<FlowExecutorContext> {
    let restored = flowContext
    for (const [step, output] of Object.entries(steps)) {
        if (isStepRestorable({ status: output.status, isWaitpointResume: keepFailedSteps })) {
            const newOutput = await insertSuccessStepsOrPausedRecursively({ stepOutput: output, isWaitpointResume: keepFailedSteps })
            if (!isNil(newOutput)) {
                restored = await restored.upsertStep(step, newOutput)
            }
        }
    }
    return restored
}

function isSeededSteps(payload: unknown): payload is Record<string, StepOutput> {
    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
        return false
    }
    return Object.values(payload).every((step: unknown) => step !== null && typeof step === 'object' && 'type' in step && 'status' in step)
}

async function runOrReturnPayload(input: ResolvedBeginExecuteFlowOperation, constants: EngineConstants): Promise<TriggerPayload> {
    if (!input.executeTrigger) {
        return input.triggerPayload as TriggerPayload
    }
    const newPayload = await triggerHelper.executeTrigger({
        params: {
            ...input,
            hookType: TriggerHookType.RUN,
            test: false,
            webhookUrl: '',
            triggerPayload: input.triggerPayload,
        },
        constants,
    }) as ExecuteTriggerResponse<TriggerHookType.RUN>
    if (newPayload.output.length === 0) {
        throw new ExecutionError('EmptyTriggerPayload', 'The trigger returned no payload, so the flow did not run', ExecutionErrorType.USER)
    }
    return newPayload.output[0] as TriggerPayload
}


async function insertSuccessStepsOrPausedRecursively({ stepOutput, isWaitpointResume }: InsertStepsParams): Promise<StepOutput | null> {
    if (!isStepRestorable({ status: stepOutput.status, isWaitpointResume })) {
        return null
    }
    if (stepOutput.type === FlowActionType.LOOP_ON_ITEMS) {
        const loopOutput = new LoopStepOutput(stepOutput)
        const iterations = loopOutput.output?.iterations ?? []
        const newIterations: Record<string, StepOutput>[] = []
        for (const iteration of iterations) {
            const newSteps: Record<string, StepOutput> = {}
            for (const [step, output] of Object.entries(iteration)) {
                const newOutput = await insertSuccessStepsOrPausedRecursively({ stepOutput: output, isWaitpointResume })
                if (!isNil(newOutput)) {
                    newSteps[step] = newOutput
                }
            }
            newIterations.push(newSteps)
        }
        return loopOutput.setIterations(newIterations)
    }
    return stepOutput
}

async function resolveExecuteFlowOperation(operation: ExecuteFlowOperation): Promise<ResolvedExecuteFlowOperation> {
    if (operation.executionType === ExecutionType.BEGIN) {
        return {
            ...operation,
            triggerPayload: await resolveJobPayload({ payload: operation.triggerPayload, apiUrl: operation.internalApiUrl, engineToken: operation.engineToken }),
        }
    }
    const executionState = await fetchExecutionStateFromLogs(operation.logsFileId, operation)
    if (Object.keys(executionState.steps).length === 0) {
        throw new EngineGenericError('EmptyResumeStateError', 'RESUME operation received with empty execution state')
    }
    return {
        ...operation,
        entryStepName: operation.entryStepName ?? executionState.entryStepName,
        resumePayload: await resolveJobPayload({ payload: operation.resumePayload, apiUrl: operation.internalApiUrl, engineToken: operation.engineToken }) as ResumePayload,
        executionState,
    }
}

async function fetchExecutionStateFromLogs(logsFileId: string | undefined, operation: ExecuteFlowOperation): Promise<ExecutionState> {
    if (isNil(logsFileId)) {
        throw new EngineGenericError('ResumeLogsFileMissing', 'logsFileId is missing for RESUME operation')
    }
    const bytes = await engineFileApi.download({
        fileId: logsFileId,
        apiUrl: operation.internalApiUrl,
        engineToken: operation.engineToken,
    })
    const parsed = JSON.parse(new TextDecoder('utf-8').decode(bytes))
    if (isNil(parsed?.executionState)) {
        throw new EngineGenericError('ExecutionStateMissing', 'executionState is missing in logs file')
    }
    return parsed.executionState as ExecutionState
}

// Waitpoint resumes preserve FAILED so a `continueOnFailure` step isn't replayed,
// which would re-fire its waitpoint and let the global `constants.resumePayload`
// pollute the new output. Retry resumes (FlowRetryStrategy.FROM_FAILED_STEP) drop
// FAILED so the engine re-executes the failed step. The discriminator is the
// explicit `resumeReason` set when the run is enqueued.
function isStepRestorable({ status, isWaitpointResume }: IsStepRestorableParams): boolean {
    if (status === StepOutputStatus.SUCCEEDED || status === StepOutputStatus.PAUSED) {
        return true
    }
    return isWaitpointResume && status === StepOutputStatus.FAILED
}

type ResolveStateParams = {
    input: ResolvedExecuteFlowOperation
    constants: EngineConstants
    baseContext: FlowExecutorContext
}

type BuildFailedTriggerContextParams = {
    input: ResolvedExecuteFlowOperation
    baseContext: FlowExecutorContext
    error: Error
}

type ReportFailedTriggerRunParams = {
    operation: ExecuteFlowOperation
    error: Error
}

type ReportFailedRunParams = {
    input: ResolvedExecuteFlowOperation
    constants: EngineConstants
    error: Error
}

type IsStepRestorableParams = {
    status: StepOutputStatus
    isWaitpointResume: boolean
}

type InsertStepsParams = {
    stepOutput: StepOutput
    isWaitpointResume: boolean
}

type RestoreStepsParams = {
    steps: Record<string, StepOutput>
    flowContext: FlowExecutorContext
    keepFailedSteps: boolean
}