@forestadmin/workflow-executor 1.0.0

package/dist/executors/base-step-executor.js

@@ -0,0 +1,267 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ai_proxy_1 = require("@forestadmin/ai-proxy");
+const errors_1 = require("../errors");
+const pending_data_validators_1 = __importDefault(require("../http/pending-data-validators"));
+const step_summary_builder_1 = __importDefault(require("./summary/step-summary-builder"));
+class BaseStepExecutor {
+    constructor(context) {
+        this.context = context;
+    }
+    async execute() {
+        const { baseRecordRef } = this.context;
+        this.context.logger.info('Step execution started', {
+            ...this.logCtx,
+            collection: baseRecordRef.collectionName,
+        });
+        try {
+            // Idempotency guard — mutating executors override this. Runs before doExecute so a cache
+            // hit or uncertain-state error short-circuits before any side effect.
+            const cached = await this.checkIdempotency();
+            if (cached) {
+                this.context.logger.info('Step execution completed (replayed from cache)', {
+                    ...this.logCtx,
+                    status: cached.stepOutcome.status,
+                });
+                return cached;
+            }
+            const result = await this.runWithTimeout();
+            this.context.logger.info('Step execution completed', {
+                ...this.logCtx,
+                status: result.stepOutcome.status,
+            });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof errors_1.StepTimeoutError) {
+                this.context.logger.error(error.message, {
+                    ...this.logCtx,
+                    timeoutMs: this.context.stepTimeoutMs,
+                });
+                return this.buildOutcomeResult({ status: 'error', error: error.userMessage });
+            }
+            if (error instanceof errors_1.WorkflowExecutorError) {
+                this.context.logger.error(error.message, {
+                    ...this.logCtx,
+                    cause: (0, errors_1.extractErrorMessage)(error.cause),
+                    stack: error.cause instanceof Error ? error.cause.stack : undefined,
+                });
+                return this.buildOutcomeResult({ status: 'error', error: error.userMessage });
+            }
+            const { cause: errorCause } = error;
+            this.context.logger.error('Unexpected error during step execution', {
+                ...this.logCtx,
+                error: (0, errors_1.extractErrorMessage)(error),
+                cause: (0, errors_1.extractErrorMessage)(errorCause),
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            return this.buildOutcomeResult({
+                status: 'error',
+                error: 'Unexpected error during step execution',
+            });
+        }
+    }
+    checkIdempotency() {
+        return Promise.resolve(null);
+    }
+    // Promise.race doesn't abort the losing branch — it keeps running in the background. The .catch()
+    // on execPromise must be attached BEFORE the race so a late rejection doesn't trigger
+    // UnhandledPromiseRejection. Late resolutions are silently discarded.
+    async runWithTimeout() {
+        const timeoutMs = this.context.stepTimeoutMs;
+        if (!timeoutMs || timeoutMs <= 0)
+            return this.doExecute();
+        let timer;
+        let hasTimeoutFired = false;
+        const execPromise = this.doExecute();
+        execPromise.catch(err => {
+            if (!hasTimeoutFired)
+                return;
+            this.context.logger.warn('Step work rejected after timeout — result discarded', {
+                ...this.logCtx,
+                error: (0, errors_1.extractErrorMessage)(err),
+            });
+        });
+        try {
+            return await Promise.race([
+                execPromise,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        hasTimeoutFired = true;
+                        reject(new errors_1.StepTimeoutError(timeoutMs));
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async findPendingExecution(type) {
+        const stepExecutions = await this.context.runStore.getStepExecutions(this.context.runId);
+        return stepExecutions.find((e) => e.type === type && e.stepIndex === this.context.stepIndex);
+    }
+    async patchAndReloadPendingData(pendingData) {
+        const { type } = this.context.stepDefinition;
+        const execution = await this.findPendingExecution(type);
+        if (!execution)
+            return undefined;
+        if (pendingData === undefined)
+            return execution;
+        const schema = pending_data_validators_1.default[execution.type];
+        if (!schema) {
+            throw new errors_1.StepStateError(`No pending-data validator registered for step type "${execution.type}"`);
+        }
+        const parsed = schema.safeParse(pendingData);
+        if (!parsed.success) {
+            throw new errors_1.StepStateError(`Invalid pending data: ${parsed.error.issues.map(i => i.message).join(', ')}`);
+        }
+        const userConfirmation = parsed.data;
+        const updated = {
+            ...execution,
+            userConfirmation,
+        };
+        await this.context.runStore.saveStepExecution(this.context.runId, updated);
+        return updated;
+    }
+    // userConfirmed branches: undefined → re-emit awaiting-input (POST not yet called);
+    // false → save as skipped + success outcome; true → resolveAndExecute.
+    async handleConfirmationFlow(execution, resolveAndExecute) {
+        if (!execution.pendingData) {
+            throw new errors_1.StepStateError(`Step at index ${this.context.stepIndex} has no pending data`);
+        }
+        const { userConfirmed } = execution.userConfirmation ?? {};
+        if (userConfirmed === undefined) {
+            return this.buildOutcomeResult({ status: 'awaiting-input' });
+        }
+        if (!userConfirmed) {
+            await this.context.runStore.saveStepExecution(this.context.runId, {
+                ...execution,
+                executionResult: { skipped: true },
+            });
+            return this.buildOutcomeResult({ status: 'success' });
+        }
+        return resolveAndExecute(execution);
+    }
+    buildContextMessage() {
+        const { user, stepDefinition } = this.context;
+        const now = new Date();
+        const lines = [
+            `Step executed by: ${user.firstName} ${user.lastName} (${user.email}, id: ${user.id})`,
+            `Role: ${user.role} | Team: ${user.team}`,
+            `Current date and time: ${now.toISOString()} (UTC)`,
+        ];
+        // Fall back to the step title only when there is no prompt — the prompt, when present, is the
+        // authoritative intent (surfaced by each executor), so the title would just be noise.
+        if (!stepDefinition.prompt?.trim() && stepDefinition.title) {
+            lines.push(`Step title: "${stepDefinition.title}"`);
+        }
+        return new ai_proxy_1.SystemMessage(lines.join('\n'));
+    }
+    async buildPreviousStepsMessages() {
+        if (!this.context.previousSteps.length)
+            return [];
+        const allStepExecutions = await this.context.runStore.getStepExecutions(this.context.runId);
+        const summary = this.context.previousSteps
+            .map(step => {
+            const execution = this.resolveStepExecution(step, allStepExecutions);
+            return step_summary_builder_1.default.build(step.stepDefinition, step.stepOutcome, execution);
+        })
+            .join('\n\n');
+        return [new ai_proxy_1.SystemMessage(summary)];
+    }
+    // A step the executor ran has its execution at its own stepIndex. A revision clone never ran,
+    // so it inherits the record of the step it copied (originalStepIndex). Own-index-first is what
+    // stops a re-executed step (which has its own entry) from resurfacing the superseded
+    // original's record.
+    resolveStepExecution(step, executions) {
+        const own = executions.find(e => e.stepIndex === step.stepOutcome.stepIndex);
+        if (own)
+            return own;
+        // An errored clone persists nothing, so inheriting the copied record would resurface the
+        // superseded original's — only fall back when the clone didn't run-and-fail.
+        if (step.originalStepIndex !== undefined && step.stepOutcome.status !== 'error') {
+            return executions.find(e => e.stepIndex === step.originalStepIndex);
+        }
+        return undefined;
+    }
+    static mergeLeadingSystemMessages(messages) {
+        let i = 0;
+        while (i < messages.length && messages[i] instanceof ai_proxy_1.SystemMessage)
+            i += 1;
+        if (i <= 1)
+            return messages;
+        const merged = new ai_proxy_1.SystemMessage(messages
+            .slice(0, i)
+            .map(m => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content)))
+            .filter(Boolean)
+            .join('\n\n'));
+        return [merged, ...messages.slice(i)];
+    }
+    static assertNoMidArraySystemMessages(messages) {
+        let seenNonSystem = false;
+        for (let i = 0; i < messages.length; i += 1) {
+            if (!(messages[i] instanceof ai_proxy_1.SystemMessage)) {
+                seenNonSystem = true;
+            }
+            else if (seenNonSystem) {
+                throw new errors_1.InvalidAiRequestError(`SystemMessage at position ${i} appears after a non-system message — move all system context to the front of the messages array.`);
+            }
+        }
+    }
+    async invokeWithTools(messages, tools) {
+        BaseStepExecutor.assertNoMidArraySystemMessages(messages);
+        const modelWithTools = this.context.model.bindTools(tools, { tool_choice: 'any' });
+        const preparedMessages = BaseStepExecutor.mergeLeadingSystemMessages(messages);
+        const aiTimeoutMs = this.context.aiInvokeTimeoutMs;
+        const timeoutMs = aiTimeoutMs && aiTimeoutMs > 0 ? aiTimeoutMs : undefined;
+        const signal = timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined;
+        let response;
+        try {
+            // `signal: undefined` is equivalent to passing no options — LangChain leaves the call un-timed.
+            response = await modelWithTools.invoke(preparedMessages, { signal });
+        }
+        catch (err) {
+            // Detect the timeout via our own signal, not the thrown error's name: providers wrap an
+            // aborted request differently (AbortError, TimeoutError, APIUserAbortError, …).
+            if (timeoutMs !== undefined && signal?.aborted)
+                throw new errors_1.AiInvokeTimeoutError(timeoutMs);
+            throw err;
+        }
+        const toolCall = response.tool_calls?.[0];
+        if (toolCall !== undefined) {
+            if (toolCall.args !== undefined && toolCall.args !== null) {
+                return { toolName: toolCall.name, args: toolCall.args };
+            }
+            throw new errors_1.MalformedToolCallError(toolCall.name ?? 'unknown', 'args field is missing or null');
+        }
+        const invalidCall = response.invalid_tool_calls?.[0];
+        if (invalidCall) {
+            throw new errors_1.MalformedToolCallError(invalidCall.name ?? 'unknown', invalidCall.error ?? 'no details available');
+        }
+        throw new errors_1.MissingToolCallError();
+    }
+    async invokeWithTool(messages, tool) {
+        return (await this.invokeWithTools(messages, [tool])).args;
+    }
+    // Overridden by executors that carry type-specific log identifiers (e.g. McpStepExecutor).
+    getExtraLogContext() {
+        return {};
+    }
+    get logCtx() {
+        const { runId, stepId, stepIndex, stepDefinition } = this.context;
+        return {
+            runId,
+            stepId,
+            stepIndex,
+            stepType: stepDefinition.type,
+            ...this.getExtraLogContext(),
+        };
+    }
+}
+exports.default = BaseStepExecutor;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFzZS1zdGVwLWV4ZWN1dG9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2V4ZWN1dG9ycy9iYXNlLXN0ZXAtZXhlY3V0b3IudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUFlQSxvREFBc0Q7QUFFdEQsc0NBU21CO0FBQ25CLDhGQUErRDtBQUMvRCwwRkFBZ0U7QUFFaEUsTUFBOEIsZ0JBQWdCO0lBSzVDLFlBQVksT0FBZ0M7UUFDMUMsSUFBSSxDQUFDLE9BQU8sR0FBRyxPQUFPLENBQUM7SUFDekIsQ0FBQztJQUVELEtBQUssQ0FBQyxPQUFPO1FBQ1gsTUFBTSxFQUFFLGFBQWEsRUFBRSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUM7UUFFdkMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLHdCQUF3QixFQUFFO1lBQ2pELEdBQUcsSUFBSSxDQUFDLE1BQU07WUFDZCxVQUFVLEVBQUUsYUFBYSxDQUFDLGNBQWM7U0FDekMsQ0FBQyxDQUFDO1FBRUgsSUFBSSxDQUFDO1lBQ0gseUZBQXlGO1lBQ3pGLHNFQUFzRTtZQUN0RSxNQUFNLE1BQU0sR0FBRyxNQUFNLElBQUksQ0FBQyxnQkFBZ0IsRUFBRSxDQUFDO1lBRTdDLElBQUksTUFBTSxFQUFFLENBQUM7Z0JBQ1gsSUFBSSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLGdEQUFnRCxFQUFFO29CQUN6RSxHQUFHLElBQUksQ0FBQyxNQUFNO29CQUNkLE1BQU0sRUFBRSxNQUFNLENBQUMsV0FBVyxDQUFDLE1BQU07aUJBQ2xDLENBQUMsQ0FBQztnQkFFSCxPQUFPLE1BQU0sQ0FBQztZQUNoQixDQUFDO1lBRUQsTUFBTSxNQUFNLEdBQUcsTUFBTSxJQUFJLENBQUMsY0FBYyxFQUFFLENBQUM7WUFFM0MsSUFBSSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLDBCQUEwQixFQUFFO2dCQUNuRCxHQUFHLElBQUksQ0FB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

package/dist/executors/condition-step-executor.d.ts

@@ -0,0 +1,15 @@
+import type { StepExecutionResult } from '../types/execution-context';
+import type { ConditionStepDefinition } from '../types/validated/step-definition';
+import type { ConditionStepOutcome } from '../types/validated/step-outcome';
+import BaseStepExecutor from './base-step-executor';
+export default class ConditionStepExecutor extends BaseStepExecutor<ConditionStepDefinition> {
+    protected buildOutcomeResult(outcome: {
+        status: ConditionStepOutcome['status'];
+        error?: string;
+        selectedOption?: string;
+    }): StepExecutionResult;
+    protected doExecute(): Promise<StepExecutionResult>;
+    private readUserChoice;
+    private askAi;
+}
+//# sourceMappingURL=condition-step-executor.d.ts.map

package/dist/executors/condition-step-executor.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ai_proxy_1 = require("@forestadmin/ai-proxy");
+const zod_1 = require("zod");
+const errors_1 = require("../errors");
+const base_step_executor_1 = __importDefault(require("./base-step-executor"));
+const pending_data_validators_1 = __importDefault(require("../http/pending-data-validators"));
+const step_definition_1 = require("../types/validated/step-definition");
+const GATEWAY_SYSTEM_PROMPT = `You are an AI agent selecting the correct option for a workflow gateway decision.
+
+**Task**: Analyze the question and available options, then select the option that DIRECTLY answers the question. Options must be literal answers, not interpretations.
+
+**Critical Rule**: Options must semantically match possible answers to the question.
+- Question "Does X contain Y?" expects options like "yes"/"no", NOT colors or unrelated values
+- Question "What is the status?" expects options like "active"/"inactive", NOT arbitrary words
+- If options don't match expected answer types, select null
+
+**NEVER invent mappings** between options and answers (e.g., never assume "purple"="no" or "red"="yes")
+
+**When to select null**:
+- Options are semantically unrelated to the question type (colors for yes/no questions)
+- None of the options literally match the expected answer
+- The question is ambiguous or lacks necessary context
+- You are less than 80% confident in any option
+
+**Reasoning format**:
+- State which option you selected and why
+- If selecting null: explain why options don't match the question
+- Do not refer to yourself as "I" in the response, use a passive formulation instead.`;
+class ConditionStepExecutor extends base_step_executor_1.default {
+    buildOutcomeResult(outcome) {
+        return {
+            stepOutcome: {
+                type: 'condition',
+                stepId: this.context.stepId,
+                stepIndex: this.context.stepIndex,
+                ...outcome,
+            },
+        };
+    }
+    async doExecute() {
+        const { stepDefinition: step, incomingPendingData } = this.context;
+        // Manual mode: the user picks the option from the frontend. Wait for their input
+        // without ever calling the AI.
+        const isManual = step.executionType === step_definition_1.StepExecutionMode.Manual;
+        if (isManual && incomingPendingData === undefined) {
+            return this.buildOutcomeResult({ status: 'awaiting-input' });
+        }
+        const { selectedOption, reasoning } = incomingPendingData !== undefined
+            ? this.readUserChoice(step, incomingPendingData)
+            : await this.askAi(step);
+        await this.context.runStore.saveStepExecution(this.context.runId, {
+            type: 'condition',
+            stepIndex: this.context.stepIndex,
+            executionParams: { answer: selectedOption, reasoning },
+            executionResult: selectedOption ? { answer: selectedOption } : undefined,
+        });
+        if (!selectedOption) {
+            return this.buildOutcomeResult({
+                status: 'error',
+                error: "The AI couldn't decide. Try rephrasing the step's prompt.",
+            });
+        }
+        return this.buildOutcomeResult({ status: 'success', selectedOption });
+    }
+    readUserChoice(step, incomingPendingData) {
+        const parsed = pending_data_validators_1.default.condition.safeParse(incomingPendingData);
+        if (!parsed.success) {
+            throw new errors_1.StepStateError(`Invalid condition input: ${parsed.error.issues.map(i => i.message).join(', ')}`);
+        }
+        const { selectedOption } = parsed.data;
+        if (!step.options.includes(selectedOption)) {
+            const allowed = step.options.join(', ');
+            throw new errors_1.StepStateError(`Option "${selectedOption}" is not a valid choice (expected one of: ${allowed})`);
+        }
+        return { selectedOption, reasoning: 'Selected by user' };
+    }
+    async askAi(step) {
+        const tool = new ai_proxy_1.DynamicStructuredTool({
+            name: 'choose-gateway-option',
+            description: 'Select the option that answers the question. ' +
+                'Use null if no option matches or you are uncertain. ' +
+                'Explain your reasoning.',
+            schema: zod_1.z.object({
+                reasoning: zod_1.z.string().describe('The reasoning behind the choice'),
+                question: zod_1.z.string().describe('The question to answer by choosing an option'),
+                option: zod_1.z
+                    .enum(step.options)
+                    .nullable()
+                    .describe('The chosen option, or null if no option clearly answers the question.'),
+            }),
+            func: undefined,
+        });
+        const messages = [
+            this.buildContextMessage(),
+            ...(await this.buildPreviousStepsMessages()),
+            new ai_proxy_1.SystemMessage(GATEWAY_SYSTEM_PROMPT),
+            new ai_proxy_1.HumanMessage(`**Question**: ${step.prompt ?? 'Choose the most appropriate option.'}`),
+        ];
+        const args = await this.invokeWithTool(messages, tool);
+        return { selectedOption: args.option, reasoning: args.reasoning };
+    }
+}
+exports.default = ConditionStepExecutor;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uZGl0aW9uLXN0ZXAtZXhlY3V0b3IuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZXhlY3V0b3JzL2NvbmRpdGlvbi1zdGVwLWV4ZWN1dG9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7O0FBSUEsb0RBQTJGO0FBQzNGLDZCQUF3QjtBQUV4QixzQ0FBMkM7QUFDM0MsOEVBQW9EO0FBQ3BELDhGQUErRDtBQUMvRCx3RUFBdUU7QUFhdkUsTUFBTSxxQkFBcUIsR0FBRzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7c0ZBb0J3RCxDQUFDO0FBRXZGLE1BQXFCLHFCQUFzQixTQUFRLDRCQUF5QztJQUNoRixrQkFBa0IsQ0FBQyxPQUk1QjtRQUNDLE9BQU87WUFDTCxXQUFXLEVBQUU7Z0JBQ1gsSUFBSSxFQUFFLFdBQVc7Z0JBQ2pCLE1BQU0sRUFBRSxJQUFJLENBQUMsT0FBTyxDQUFDLE1BQU07Z0JBQzNCLFNBQVMsRUFBRSxJQUFJLENBQUMsT0FBTyxDQUFDLFNBQVM7Z0JBQ2pDLEdBQUcsT0FBTzthQUNYO1NBQ0YsQ0FBQztJQUNKLENBQUM7SUFFUyxLQUFLLENBQUMsU0FBUztRQUN2QixNQUFNLEVBQUUsY0FBYyxFQUFFLElBQUksRUFBRSxtQkFBbUIsRUFBRSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUM7UUFFbkUsaUZBQWlGO1FBQ2pGLCtCQUErQjtRQUMvQixNQUFNLFFBQVEsR0FBRyxJQUFJLENBQUMsYUFBYSxLQUFLLG1DQUFpQixDQUFDLE1BQU0sQ0FBQztRQUVqRSxJQUFJLFFBQVEsSUFBSSxtQkFBbUIsS0FBSyxTQUFTLEVBQUUsQ0FBQztZQUNsRCxPQUFPLElBQUksQ0FBQyxrQkFBa0IsQ0FBQyxFQUFFLE1BQU0sRUFBRSxnQkFBZ0IsRUFBRSxDQUFDLENBQUM7UUFDL0QsQ0FBQztRQUVELE1BQU0sRUFBRSxjQUFjLEVBQUUsU0FBUyxFQUFFLEdBQ2pDLG1CQUFtQixLQUFLLFNBQVM7WUFDL0IsQ0FBQyxDQUFDLElB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

package/dist/executors/guidance-step-executor.d.ts

@@ -0,0 +1,12 @@
+import type { StepExecutionResult } from '../types/execution-context';
+import type { GuidanceStepDefinition } from '../types/validated/step-definition';
+import type { RecordStepStatus } from '../types/validated/step-outcome';
+import BaseStepExecutor from './base-step-executor';
+export default class GuidanceStepExecutor extends BaseStepExecutor<GuidanceStepDefinition> {
+    protected doExecute(): Promise<StepExecutionResult>;
+    protected buildOutcomeResult(outcome: {
+        status: RecordStepStatus;
+        error?: string;
+    }): StepExecutionResult;
+}
+//# sourceMappingURL=guidance-step-executor.d.ts.map

package/dist/executors/guidance-step-executor.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const errors_1 = require("../errors");
+const base_step_executor_1 = __importDefault(require("./base-step-executor"));
+const pending_data_validators_1 = __importDefault(require("../http/pending-data-validators"));
+class GuidanceStepExecutor extends base_step_executor_1.default {
+    async doExecute() {
+        const { incomingPendingData } = this.context;
+        if (!incomingPendingData) {
+            return this.buildOutcomeResult({ status: 'awaiting-input' });
+        }
+        const parsed = pending_data_validators_1.default.guidance.safeParse(incomingPendingData);
+        if (!parsed.success) {
+            throw new errors_1.StepStateError(`Invalid guidance input: ${parsed.error.issues.map(i => i.message).join(', ')}`);
+        }
+        const { userInput } = parsed.data;
+        await this.context.runStore.saveStepExecution(this.context.runId, {
+            type: 'guidance',
+            stepIndex: this.context.stepIndex,
+            executionResult: { userInput: userInput ?? '' },
+        });
+        return this.buildOutcomeResult({ status: 'success' });
+    }
+    buildOutcomeResult(outcome) {
+        return {
+            stepOutcome: {
+                type: 'guidance',
+                stepId: this.context.stepId,
+                stepIndex: this.context.stepIndex,
+                ...outcome,
+            },
+        };
+    }
+}
+exports.default = GuidanceStepExecutor;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ3VpZGFuY2Utc3RlcC1leGVjdXRvci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9leGVjdXRvcnMvZ3VpZGFuY2Utc3RlcC1leGVjdXRvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7OztBQUlBLHNDQUEyQztBQUMzQyw4RUFBb0Q7QUFDcEQsOEZBQStEO0FBRS9ELE1BQXFCLG9CQUFxQixTQUFRLDRCQUF3QztJQUM5RSxLQUFLLENBQUMsU0FBUztRQUN2QixNQUFNLEVBQUUsbUJBQW1CLEVBQUUsR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDO1FBRTdDLElBQUksQ0FBQyxtQkFBbUIsRUFBRSxDQUFDO1lBQ3pCLE9BQU8sSUFBSSxDQUFDLGtCQUFrQixDQUFDLEVBQUUsTUFBTSxFQUFFLGdCQUFnQixFQUFFLENBQUMsQ0FBQztRQUMvRCxDQUFDO1FBRUQsTUFBTSxNQUFNLEdBQUcsaUNBQWdCLENBQUMsUUFBUSxDQUFDLFNBQVMsQ0FBQyxtQkFBbUIsQ0FBQyxDQUFDO1FBRXhFLElBQUksQ0FBQyxNQUFNLENBQUMsT0FBTyxFQUFFLENBQUM7WUFDcEIsTUFBTSxJQUFJLHVCQUFjLENBQ3RCLDJCQUEyQixNQUFNLENBQUMsS0FBSyxDQUFDLE1BQU0sQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsT0FBTyxDQUFDLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxFQUFFLENBQ2hGLENBQUM7UUFDSixDQUFDO1FBRUQsTUFBTSxFQUFFLFNBQVMsRUFBRSxHQUFHLE1BQU0sQ0FBQyxJQUE4QixDQUFDO1FBRTVELE1BQU0sSUFBSSxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsaUJBQWlCLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxLQUFLLEVBQUU7WUFDaEUsSUFBSSxFQUFFLFVBQVU7WUFDaEIsU0FBUyxFQUFFLElBQUksQ0FBQyxPQUFPLENBQUMsU0FBUztZQUNqQyxlQUFlLEVBQUUsRUFBRSxTQUFTLEVBQUUsU0FBUyxJQUFJLEVBQUUsRUFBRTtTQUNoRCxDQUFDLENBQUM7UUFFSCxPQUFPLElBQUksQ0FBQyxrQkFBa0IsQ0FBQyxFQUFFLE1BQU0sRUFBRSxTQUFTLEVBQUUsQ0FBQyxDQUFDO0lBQ3hELENBQUM7SUFFUyxrQkFBa0IsQ0FBQyxPQUc1QjtRQUNDLE9BQU87WUFDTCxXQUFXLEVBQUU7Z0JBQ1gsSUFBSSxFQUFFLFVBQVU7Z0JBQ2hCLE1BQU0sRUFBRSxJQUFJLENBQUMsT0FBTyxDQUFDLE1BQU07Z0JBQzNCLFNBQVMsRUFBRSxJQUFJLENBQUMsT0FBTyxDQUFDLFNBQVM7Z0JBQ2pDLEdBQUcsT0FBTzthQUNYO1NBQ0YsQ0FBQztJQUNKLENBQUM7Q0FDRjtBQXhDRCx1Q0F3Q0MifQ==

package/dist/executors/load-related-record-step-executor.d.ts

@@ -0,0 +1,38 @@
+import type { StepExecutionResult } from '../types/execution-context';
+import type { LoadRelatedRecordStepDefinition } from '../types/validated/step-definition';
+import RecordStepExecutor from './record-step-executor';
+export default class LoadRelatedRecordStepExecutor extends RecordStepExecutor<LoadRelatedRecordStepDefinition> {
+    protected doExecute(): Promise<StepExecutionResult>;
+    private refreshCandidatesForField;
+    private handleFirstCall;
+    private resolveTarget;
+    private targetFromCandidate;
+    private requireRecordAtStepIndex;
+    private buildRelationCandidates;
+    private buildTarget;
+    private saveAndAwaitInput;
+    private collectCandidateIds;
+    private extractReferenceFieldValue;
+    /** Branch B: fully automated. xToOne loads the linked record; HasMany ranks candidates via AI; BelongsToMany takes the first. */
+    private resolveAndLoadAutomatic;
+    private fetchRecordForRelation;
+    private fetchXToOneRecordRef;
+    private fetchXToOneCandidate;
+    private resolveFromSelection;
+    private selectBestFromRelatedData;
+    /** HasMany + fully automated execution: fetch top 50, then AI calls to select the best record. */
+    private selectBestRelatedRecord;
+    private fetchFirstCandidate;
+    private fetchCandidates;
+    private fetchRelatedData;
+    /** Persists the loaded record ref and returns a success outcome. */
+    private persistAndReturn;
+    private relationOptionLabel;
+    private selectRelationToFollow;
+    /** AI call 1 for HasMany: selects the most relevant fields to compare candidates. */
+    private selectRelevantFields;
+    /** AI call 2 for HasMany: selects the best record by index from the candidate list. */
+    private selectBestRecordIndex;
+    private toRecordRef;
+}
+//# sourceMappingURL=load-related-record-step-executor.d.ts.map