@falai/agent 3.4.5 → 4.0.0-alpha.10

package/src/core/AutoChainExecutor.ts

@@ -1,397 +0,0 @@
-/**
- * Auto-step chain executor.
- *
- * Walks consecutive `auto: true` steps in a single turn without making LLM calls.
- * Each auto-step runs its pre-LLM hooks (onEnter, prepare), evaluates skipIf/requires,
- * applies state writes, resolves branches, and advances to the next step.
- *
- * The chain terminates when:
- * - An interactive step (auto !== true) is reached → returned as `resolvedStep`
- * - A `prepare` returns `{ halt: true, reply? }` → turn ends with verbatim reply
- * - A position-changing directive (goTo, goToStep, complete) is returned
- * - The last auto-step has no successor → flow is complete
- * - The chain exceeds `maxAutoStepsPerTurn` → throws FlowConfigurationError
- *
- * Implements Algorithm 1 from `.kiro/specs/auto-steps/design.md`.
- */
-
-import type { Directive, SessionState } from "../types/index.js";
-import type { Event } from "../types/history.js";
-import { FlowConfigurationError, Step } from "./Step.js";
-import { Flow } from "./Flow.js";
-import { flow } from "./flow-namespace.js";
-import { enterStep, mergeCollected, logger } from "../utils/index.js";
-import { createTemplateContext } from "../utils/template.js";
-import type {
-    StoppedReason,
-    BranchMap,
-    BranchEntry,
-    BranchPredicateContext,
-} from "../types/flow.js";
-import { evaluateIfPredicates } from "../utils/condition.js";
-
-/**
- * The directive-like object that `prepare` may return on auto-steps.
- * A structural subset of Directive (pre-LLM + position fields), so results
- * merge through the canonical Algorithm 4 (`flow.merge`).
- */
-export type AutoStepPrepareResult<TContext = unknown, TData = unknown> = Pick<
-    Directive<TContext, TData>,
-    "dataUpdate" | "contextUpdate" | "halt" | "reply" | "goToStep" | "goTo" | "complete"
->;
-
-/**
- * Result of running the auto-chain.
- */
-export interface AutoChainResult<TContext = unknown, TData = unknown> {
-    /** The interactive step to hand off to the LLM path (undefined if chain ended without one). */
-    resolvedStep?: Step<TContext, TData>;
-    /** The merged directive from the halting auto-step's prepare (only set when stoppedReason = 'halt'). */
-    mergedDirective?: AutoStepPrepareResult<TContext, TData>;
-    /** Why the chain stopped, if it didn't reach an interactive step normally. */
-    stoppedReason?: StoppedReason;
-    /** Updated session after all auto-step state writes. */
-    session: SessionState<TData>;
-}
-
-/**
- * Configuration for AutoChainExecutor.
- */
-export interface AutoChainExecutorOptions {
-    /** Maximum number of auto-steps walked in a single turn before throwing. */
-    maxAutoStepsPerTurn: number;
-}
-
-/**
- * Parameters for a single chain run.
- */
-export interface AutoChainRunParams<TContext, TData> {
-    session: SessionState<TData>;
-    context: TContext;
-    flow: Flow<TContext, TData>;
-    /** Conversation history (used for branch predicate context). Optional. */
-    history?: Event[];
-}
-
-/**
- * Executes the auto-step chain for a single turn.
- *
- * Algorithm 1 from design.md — walks while `currentStep.auto === true`,
- * executing skipIf → requires → onEnter/prepare → state writes →
- * halt check → position directives → branches → linear advance.
- */
-export class AutoChainExecutor<TContext = unknown, TData = unknown> {
-    constructor(private readonly options: AutoChainExecutorOptions) { }
-
-    /**
-     * Run the auto-step chain starting from the current step on the session.
-     */
-    async run(params: AutoChainRunParams<TContext, TData>): Promise<AutoChainResult<TContext, TData>> {
-        const { context, flow, history = [] } = params;
-        const { maxAutoStepsPerTurn } = this.options;
-        let { session } = params;
-        const visited: string[] = [];
-
-        while (true) {
-            // Resolve the current step from session
-            const currentStepId = session.currentStep?.id;
-            if (!currentStepId) {
-                // No current step — nothing to walk. Return undefined resolvedStep.
-                return { session };
-            }
-
-            const step = flow.getStep(currentStepId);
-            if (!step) {
-                // Step not found in flow — shouldn't happen, but bail gracefully.
-                return { session };
-            }
-
-            // If the step is not auto, hand off to the interactive path
-            if (!step.auto) {
-                return { resolvedStep: step, session };
-            }
-
-            // Track visited steps for cap/cycle detection
-            visited.push(step.id);
-            if (visited.length > maxAutoStepsPerTurn) {
-                throw new FlowConfigurationError(
-                    `[FlowConfigurationError] Auto-step chain exceeded limit: visited ${visited.length} steps which exceeds maxAutoStepsPerTurn (${maxAutoStepsPerTurn}). ` +
-                    `Break the cycle or increase maxAutoStepsPerTurn. Visited: ${visited.join(' → ')}.`
-                );
-            }
-
-            logger.debug(`[AutoChainExecutor] Processing auto-step: ${step.id} (${visited.length}/${maxAutoStepsPerTurn})`);
-
-            // STEP 1: skip evaluation (code-only predicates, OR semantics)
-            if (step.skip) {
-                const templateContext = createTemplateContext<TContext, TData>({
-                    context,
-                    data: session.data,
-                    session,
-                    history,
-                });
-                const skipResult = await step.evaluateSkip(templateContext);
-
-                if (skipResult.shouldSkip) {
-                    logger.debug(`[AutoChainExecutor] Skipping auto-step ${step.id} due to skip condition`);
-                    const nextSteps = step.getTransitions();
-                    if (nextSteps.length === 0) {
-                        // Last step was skipped and has no successor → flow complete
-                        return { stoppedReason: 'last_step', session };
-                    }
-                    session = enterStep(session, nextSteps[0].id, nextSteps[0].description);
-                    continue;
-                }
-            }
-
-            // STEP 2: requires assertion
-            if (step.requires && step.requires.length > 0) {
-                const sessionData = (session.data || {}) as Record<string, unknown>;
-                const missing = step.requires.filter(
-                    field => sessionData[String(field)] === undefined
-                );
-                if (missing.length > 0) {
-                    throw new FlowConfigurationError(
-                        `[FlowConfigurationError] Auto-step "${step.id}" missing required fields: fields [${missing.join(', ')}] must be populated before this step runs. ` +
-                        `Ensure a preceding step or hook populates these fields.`
-                    );
-                }
-            }
-
-            // STEP 3: Run pre-LLM hooks (onEnter, prepare) and collect directives
-            const merged = await this.runStepHooks(step, session, context);
-
-            // Apply state writes immediately so subsequent steps see them
-            if (merged) {
-                if (merged.dataUpdate && Object.keys(merged.dataUpdate).length > 0) {
-                    session = mergeCollected(session, merged.dataUpdate);
-                    logger.debug(`[AutoChainExecutor] Applied dataUpdate from step ${step.id}`);
-                }
-                if (merged.contextUpdate && Object.keys(merged.contextUpdate).length > 0) {
-                    // contextUpdate is reserved for future agent-level application.
-                    // The caller can read mergedDirective.contextUpdate and apply it externally.
-                    logger.debug(`[AutoChainExecutor] contextUpdate from step ${step.id} will be applied by caller`);
-                }
-
-                // STEP 4: halt short-circuit
-                if (merged.halt) {
-                    logger.debug(`[AutoChainExecutor] Halt directive from step ${step.id}`);
-                    return {
-                        resolvedStep: step,
-                        mergedDirective: merged,
-                        stoppedReason: 'halt',
-                        session,
-                    };
-                }
-
-                // STEP 5: position-changing directive (goToStep, goTo, complete)
-                if (merged.goToStep) {
-                    // String form targets the current flow; object form carrying
-                    // a different `flow` defers to the pipeline for cross-flow
-                    // resolution (same as goTo).
-                    const goTarget = typeof merged.goToStep === "string"
-                        ? { step: merged.goToStep, flowId: undefined }
-                        : { step: merged.goToStep.step, flowId: merged.goToStep.flow };
-                    if (goTarget.flowId && goTarget.flowId !== flow.id) {
-                        return {
-                            resolvedStep: step,
-                            mergedDirective: merged,
-                            stoppedReason: 'goto',
-                            session,
-                        };
-                    }
-                    const targetStep = flow.getStep(goTarget.step);
-                    if (!targetStep) {
-                        throw new FlowConfigurationError(
-                            `[FlowConfigurationError] Auto-step "${step.id}" goToStep targets unknown step: "${goTarget.step}" does not exist in the current flow. ` +
-                            `Check the step id or use goTo to target a different flow.`
-                        );
-                    }
-                    session = enterStep(session, targetStep.id, targetStep.description);
-                    logger.debug(`[AutoChainExecutor] Position directive goToStep → ${targetStep.id}`);
-                    continue; // Re-enter loop at the new step (which may itself be auto)
-                }
-                if (merged.goTo) {
-                    // goTo targets a flow — return to pipeline for cross-flow handling
-                    return {
-                        resolvedStep: step,
-                        mergedDirective: merged,
-                        stoppedReason: 'goto',
-                        session,
-                    };
-                }
-                if (merged.complete) {
-                    return {
-                        resolvedStep: step,
-                        mergedDirective: merged,
-                        stoppedReason: 'completed',
-                        session,
-                    };
-                }
-            }
-
-            // STEP 6: branches resolution (if step has branches)
-            if (step.branches && step.branches.length > 0) {
-                const branchTarget = await this.evaluateBranches(
-                    step.branches,
-                    session,
-                    context,
-                    history
-                );
-                if (branchTarget) {
-                    // Check if it resolves to a step in this flow
-                    const targetStep = flow.getStep(branchTarget);
-                    if (targetStep) {
-                        session = enterStep(session, targetStep.id, targetStep.description);
-                        logger.debug(`[AutoChainExecutor] Branch resolved → ${targetStep.id}`);
-                        continue;
-                    }
-                    // Not a step in this flow — treat as a flow id, return to pipeline
-                    return {
-                        resolvedStep: step,
-                        mergedDirective: { goTo: branchTarget },
-                        stoppedReason: 'goto',
-                        session,
-                    };
-                }
-                // No branch matched — fall through to linear advance
-            }
-
-            // STEP 7: linear advance
-            const nextSteps = step.getTransitions();
-            if (nextSteps.length === 0) {
-                // Auto-step is the last step → flow completes
-                logger.debug(`[AutoChainExecutor] Auto-step ${step.id} is terminal — flow complete`);
-                return { stoppedReason: 'last_step', session };
-            }
-
-            // Take the first transition (linear advance)
-            session = enterStep(session, nextSteps[0].id, nextSteps[0].description);
-        }
-    }
-
-    /**
-     * Run the prepare hook for an auto-step, collecting any
-     * Directive return values (pre-LLM fields honored).
-     */
-    private async runStepHooks(
-        step: Step<TContext, TData>,
-        session: SessionState<TData>,
-        context: TContext
-    ): Promise<AutoStepPrepareResult<TContext, TData> | undefined> {
-        let merged: AutoStepPrepareResult<TContext, TData> | undefined;
-
-        // prepare hook — for auto-steps, prepare may return a Directive with pre-LLM fields
-        if (step.prepare) {
-            if (typeof step.prepare === 'function') {
-                const prepareResult = await (step.prepare as (
-                    context: TContext,
-                    data?: Partial<TData>
-                ) => Promise<unknown>)(
-                    context,
-                    session.data
-                );
-                // prepare may return void or a directive-like object
-                if (prepareResult && typeof prepareResult === 'object') {
-                    merged = this.mergeDirectives(merged, prepareResult as AutoStepPrepareResult<TContext, TData>);
-                }
-            } else {
-                // Tool reference (string or Tool object) — for auto-steps, tool-based
-                // prepare cannot return directives. Log a warning.
-                logger.warn(
-                    `[FlowConfigurationError] Auto-step "${step.id}" has a tool-based prepare: tool-based prepare on auto-steps cannot return directives. ` +
-                    `Use a function-based prepare hook instead.`
-                );
-            }
-        }
-
-        return merged;
-    }
-
-    /**
-     * Merge two directive-like objects via the canonical Algorithm 4 merge —
-     * one algorithm shared with tools, hooks and signals.
-     */
-    private mergeDirectives(
-        base: AutoStepPrepareResult<TContext, TData> | undefined,
-        incoming: AutoStepPrepareResult<TContext, TData>
-    ): AutoStepPrepareResult<TContext, TData> {
-        if (!base) return { ...incoming };
-        // AutoStepPrepareResult is a structural subset of Directive, so both
-        // sides flow through the canonical merge directly — no casts needed.
-        return flow.merge<TContext, TData>(base, incoming);
-    }
-
-    /**
-     * Evaluate branches on an auto-step. Returns the target step/flow id
-     * if a branch matches, or undefined if no branch matched.
-     *
-     * This is a simplified evaluator for code-only (`if`) branches.
-     * AI-evaluated (`when`) branches are not supported in the auto-step
-     * context (no LLM call). If a branch entry has only `when`, it is skipped.
-     */
-    private async evaluateBranches(
-        branches: BranchMap<TContext, TData>,
-        session: SessionState<TData>,
-        context: TContext,
-        history: Event[]
-    ): Promise<string | undefined> {
-        for (let i = 0; i < branches.length; i++) {
-            const entry = branches[i];
-
-            // Unconditional entry (no `if` and no `when`) — must be last, always matches
-            if (!entry.if && !entry.when) {
-                return this.resolveBranchThen(entry.then);
-            }
-
-            // Code predicate evaluation
-            if (entry.if) {
-                const predicateContext: BranchPredicateContext<TContext, TData> = {
-                    data: session.data, context, session, history,
-                };
-                const allPassed = await evaluateIfPredicates<BranchPredicateContext<TContext, TData>>(
-                    entry.if, predicateContext, "AutoChainExecutor"
-                );
-                if (!allPassed) continue;
-
-                // If entry also has `when`, skip it in auto-step context (no LLM available)
-                if (entry.when) {
-                    logger.debug(
-                        `[AutoChainExecutor] Branch entry has 'when' condition — ` +
-                        `skipping AI evaluation in auto-step context`
-                    );
-                    continue;
-                }
-
-                return this.resolveBranchThen(entry.then);
-            }
-
-            // Entry has only `when` (AI condition) — skip in auto-step context
-            if (entry.when && !entry.if) {
-                continue;
-            }
-        }
-
-        return undefined;
-    }
-
-    /**
-     * Resolve a branch entry's `then` value to a string target.
-     * Handles both string targets and Directive objects.
-     */
-    private resolveBranchThen(then: BranchEntry<TContext, TData>["then"]): string | undefined {
-        if (typeof then === 'string') {
-            return then;
-        }
-        // Directive object — extract position field (string or object form)
-        if (then && typeof then === 'object') {
-            if (then.goToStep) {
-                return typeof then.goToStep === 'string' ? then.goToStep : then.goToStep.step;
-            }
-            if (then.goTo) {
-                return typeof then.goTo === 'string' ? then.goTo : then.goTo.flow;
-            }
-        }
-        return undefined;
-    }
-}

package/src/core/BranchEvaluator.ts

@@ -1,161 +0,0 @@
-/**
- * Branch Evaluator — Resolution Algorithm (Algorithm 2 from design.md)
- *
- * Pure function that evaluates a BranchMap in declaration order.
- * Code-first evaluation: `if` predicates run before `when` (AI) conditions
- * to save tokens. First matching entry wins.
- *
- * @module BranchEvaluator
- */
-
-import type {
-    BranchMap,
-    BranchPredicateContext,
-    Directive,
-} from "../types/flow.js";
-import type { AiProvider } from "../types/ai.js";
-import type { Event } from "../types/history.js";
-import { eventsToHistory, logger } from "../utils/index.js";
-import { splitWhenConditions, evaluateIfPredicates, type WhenConditionGroups } from "../utils/condition.js";
-
-/**
- * The AI condition evaluator function signature.
- * Accepts split condition strings and returns whether the condition passes:
- * (no positives OR any positive is satisfied) AND no exclusion is satisfied.
- *
- * This is the same evaluation mechanism used by `step.when` — condition
- * strings are evaluated by the AI provider against the conversation context.
- */
-export type AiConditionEvaluator = (conditions: WhenConditionGroups) => Promise<boolean>;
-
-/**
- * Creates an `AiConditionEvaluator` bound to a provider and conversation context.
- *
- * Reuses the same evaluation pattern as `step.when` array forms: condition
- * strings are passed to the AI provider for evaluation against the conversation
- * history. No new prompt scaffolding — the provider evaluates whether the
- * conditions are met based on the conversation so far.
- *
- * String form (`when: "some condition"`) is normalized to a single-element
- * array by the caller (`evaluateBranches`) for uniformity before reaching
- * this function.
- *
- * @param provider - The AI provider to use for condition evaluation
- * @param history - Conversation history (events) for context
- * @param context - Agent-level context
- * @returns An `AiConditionEvaluator` function
- */
-export function createAiConditionEvaluator<TContext = unknown>(
-    provider: AiProvider,
-    history: Event[],
-    context: TContext,
-): AiConditionEvaluator {
-    return async (conditions: WhenConditionGroups): Promise<boolean> => {
-        if (conditions.positive.length === 0 && conditions.negative.length === 0) {
-            return true;
-        }
-
-        const positiveText = conditions.positive.length === 0
-            ? "None. Treat the positive side as satisfied unless an exclusion matches."
-            : conditions.positive.map((c, i) => `${i + 1}. ${c}`).join("\n");
-        const negativeText = conditions.negative.length === 0
-            ? "None."
-            : conditions.negative.map((c, i) => `${i + 1}. ${c}`).join("\n");
-
-        const prompt = [
-            "Evaluate whether the following condition rule passes based on the conversation so far.",
-            "",
-            "Positive condition(s) (OR):",
-            positiveText,
-            "",
-            "Exclusion condition(s) (OR, any match inhibits):",
-            negativeText,
-            "",
-            "Return JSON with a single boolean field `result`: true only when (there are no positive conditions OR ANY positive condition is satisfied) AND NO exclusion condition is satisfied.",
-        ].join("\n");
-
-        const result = await provider.generateMessage<TContext, { result: boolean }>({
-            prompt,
-            history: eventsToHistory(history),
-            context,
-            parameters: {
-                jsonSchema: {
-                    type: "object",
-                    properties: {
-                        result: {
-                            type: "boolean",
-                            description: "Whether the positive/exclusion condition rule passes based on the conversation context",
-                        },
-                    },
-                    required: ["result"],
-                    additionalProperties: false,
-                },
-                schemaName: "condition_evaluation",
-            },
-        });
-
-        return result.structured?.result ?? false;
-    };
-}
-
-/**
- * Evaluates a BranchMap in declaration order, returning the first matching
- * entry's `then` value, or `undefined` if no entry matches.
- *
- * Resolution rules per entry:
- * 1. Unconditional (no `when`, no `if`) → return `then` immediately.
- * 2. `if` first: normalize to array, await each predicate, short-circuit on first falsy.
- * 3. `when` second: only if `if` passed (or absent); call evaluateAi with condition strings.
- * 4. Both passed (or only one set and it passed) → return `then`.
- *
- * Errors in predicates or AI evaluation are caught, logged at ERROR, and
- * cause `evaluateBranches` to return `undefined` (graceful degradation).
- */
-export async function evaluateBranches<TContext = unknown, TData = unknown>(
-    branches: BranchMap<TContext, TData>,
-    ctx: BranchPredicateContext<TContext, TData>,
-    evaluateAi: AiConditionEvaluator,
-): Promise<string | Directive<TContext, TData> | undefined> {
-    try {
-        for (let i = 0; i < branches.length; i++) {
-            const entry = branches[i];
-
-            // Unconditional fallback: entry has neither `when` nor `if`.
-            // Validation guarantees this is the LAST entry.
-            if (!entry.when && !entry.if) {
-                return entry.then;
-            }
-
-            // Code predicate first (free evaluation)
-            if (entry.if) {
-                const ifPassed = await evaluateIfPredicates<BranchPredicateContext<TContext, TData>>(
-                    entry.if, ctx, "BranchEvaluator"
-                );
-                if (!ifPassed) {
-                    continue; // skip this entry; do NOT evaluate `when`
-                }
-            }
-
-            // AI condition (costs tokens — only reached if `if` passed or was absent)
-            if (entry.when) {
-                const conditions = splitWhenConditions(entry.when);
-
-                const aiResult = await evaluateAi(conditions);
-                if (!aiResult) {
-                    continue; // skip this entry
-                }
-            }
-
-            // Both passed (or only one was set and it passed)
-            return entry.then;
-        }
-
-        // No entry matched
-        return undefined;
-    } catch (error) {
-        logger.error(
-            `[BranchEvaluator] Error during branch evaluation: ${error instanceof Error ? error.message : String(error)}`
-        );
-        return undefined;
-    }
-}