@falai/agent 1.2.8 → 2.0.1

package/dist/cjs/core/Step.d.ts

@@ -1,26 +1,42 @@
 /**
  * Step in the route DSL
  */
-import type { StepRef, StepOptions, StepResult, BranchSpec, BranchResult, Guideline, GuidelineMatch, Tool, SessionState, Event } from "../types";
-import { ToolScope, Template, ConditionTemplate, TemplateContext } from "../types";
+import type { StepRef, StepOptions, BranchMap, Instruction, Tool, PrepareResult } from "../types";
+import type { StepResult, BranchSpec, BranchResult } from "../types/flow";
+import { ToolScope, Template, TemplateContext } from "../types";
+import type { ConditionWhen, ConditionIf } from "../types/flow";
 import { Agent } from './Agent';
+/**
+ * Error thrown when a step's configuration violates auto-step constraints.
+ */
+export declare class FlowConfigurationError extends Error {
+    constructor(message: string);
+}
 /**
  * Represents a step within a route
  */
 export declare class Step<TContext = unknown, TData = unknown> {
     readonly id: string;
     private nextSteps;
-    private guidelines;
-    readonly routeId: string;
+    private _instructions;
+    readonly flowId: string;
     collect?: (keyof TData)[];
     description?: string;
-    when?: ConditionTemplate<TContext, TData>;
-    skipIf?: ConditionTemplate<TContext, TData>;
+    when?: ConditionWhen;
+    if?: ConditionIf<TContext, TData>;
+    skip?: ConditionIf<TContext, TData>;
     requires?: (keyof TData)[];
     prompt?: Template<TContext, TData>;
-    prepare?: string | Tool<TContext, TData> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
-    finalize?: string | Tool<TContext, TData> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+    reply?: Template<TContext, TData>;
+    prepare?: string | Tool<TContext, TData> | ((context: TContext, data?: Partial<TData>) => void | PrepareResult | Promise<void | PrepareResult>);
+    finalize?: string | Tool<TContext, TData> | ((context: TContext, data?: Partial<TData>) => void | PrepareResult | Promise<void | PrepareResult>);
     tools?: (string | Tool<TContext, TData>)[];
+    private readonly _auto;
+    private readonly _branches?;
+    /** Whether this step runs without an LLM call (computational only). */
+    get auto(): boolean;
+    /** Explicit source-local fork entries, if declared. */
+    get branches(): BranchMap<TContext, TData> | undefined;
     private parentAgent?;
     constructor(routeId: string, options?: StepOptions<TContext, TData>, parentAgent?: Agent<TContext, TData>);
     /**
@@ -30,20 +46,13 @@ export declare class Step<TContext = unknown, TData = unknown> {
     configure(config: {
         description?: string;
         collect?: (keyof TData)[];
-        skipIf?: ConditionTemplate<TContext, TData>;
+        skip?: ConditionIf<TContext, TData>;
         requires?: (keyof TData)[];
         prompt?: Template<TContext, TData>;
         prepare?: string | Tool<TContext, TData> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
         finalize?: string | Tool<TContext, TData> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
         tools?: (string | Tool<TContext, TData>)[];
     }): this;
-    /**
-     * Shortcut to end the current route
-     *
-     * @param options - Optional step options for the end step
-     * @returns Terminal step result
-     */
-    endRoute(options?: Omit<StepOptions<TContext, TData>, "step">): StepResult<TContext, TData>;
     /**
      * Create a transition from this step to another
      *
@@ -59,18 +68,13 @@ export declare class Step<TContext = unknown, TData = unknown> {
      */
     branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>;
     /**
-     * Add a guideline specific to this step
+     * Add an instruction to this step.
      */
-    addGuideline(guideline: Guideline<TContext, TData>): void;
+    addInstruction(instruction: Instruction<TContext, TData>): void;
     /**
-     * Get guidelines for this step
+     * Get instructions for this step
      */
-    getGuidelines(): Guideline<TContext, TData>[];
-    /**
-     * Evaluate and match active guidelines based on their conditions
-     * Returns guidelines that should be active given the current context
-     */
-    evaluateGuidelines(context?: TContext, session?: SessionState<TData>, history?: Event[]): Promise<GuidelineMatch<TContext, TData>[]>;
+    getInstructions(): Instruction<TContext, TData>[];
     /**
      * Add a tool to this step using the unified Tool interface
      * Creates and adds the tool to step scope in one operation
@@ -126,7 +130,9 @@ export declare class Step<TContext = unknown, TData = unknown> {
      */
     getTransitions(): Step<TContext, TData>[];
     /**
-     * Evaluate when condition using ConditionEvaluator
+     * Evaluate when/if conditions using the v2 split logic.
+     * `if` (code predicate) evaluates first (free); `when` (AI) evaluates only when `if` passes.
+     * Both are combined with AND semantics.
      */
     evaluateWhen(templateContext: TemplateContext<TContext, TData>): Promise<{
         shouldActivate: boolean;
@@ -134,9 +140,10 @@ export declare class Step<TContext = unknown, TData = unknown> {
         hasProgrammaticConditions: boolean;
     }>;
     /**
-     * Evaluate skipIf condition using ConditionEvaluator
+     * Evaluate the skip condition (if-only shape — code predicates, OR semantics).
+     * Returns true if the step should be skipped.
      */
-    evaluateSkipIf(templateContext: TemplateContext<TContext, TData>): Promise<{
+    evaluateSkip(templateContext: TemplateContext<TContext, TData>): Promise<{
         shouldSkip: boolean;
         aiContextStrings: string[];
         hasProgrammaticConditions: boolean;
@@ -153,10 +160,6 @@ export declare class Step<TContext = unknown, TData = unknown> {
      * Create a step reference with nextStep capability for chaining
      */
     private createStepRefWithTransition;
-    /**
-     * Create a terminal step reference (for END_ROUTE)
-     */
-    private createTerminalRef;
     /**
      * Create a transition result for this step
      */
@@ -166,5 +169,13 @@ export declare class Step<TContext = unknown, TData = unknown> {
      * @returns StepOptions that can be used to create a new step with identical configuration
      */
     toOptions(): StepOptions<TContext, TData>;
+    /**
+     * Validate the branches array at construction time.
+     * Checks:
+     * - Non-empty array
+     * - Unconditional entries (no `when` and no `if`) only legal as the last entry
+     * - Directive `then` values: at most one position field, no empty `goTo: {}`
+     */
+    private validateBranches;
 }
 //# sourceMappingURL=Step.d.ts.map

package/dist/cjs/core/Step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Step.d.ts","sourceRoot":"","sources":["../../../src/core/Step.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Step.d.ts","sourceRoot":"","sources":["../../../src/core/Step.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/Step.js

@@ -3,33 +3,104 @@
  * Step in the route DSL
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Step = void 0;
+exports.Step = exports.FlowConfigurationError = void 0;
 const types_1 = require("../types");
 const utils_1 = require("../utils");
-const constants_1 = require("../constants");
+/**
+ * Error thrown when a step's configuration violates auto-step constraints.
+ */
+class FlowConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FlowConfigurationError";
+    }
+}
+exports.FlowConfigurationError = FlowConfigurationError;
 /**
  * Represents a step within a route
  */
 class Step {
+    /** Whether this step runs without an LLM call (computational only). */
+    get auto() {
+        return this._auto;
+    }
+    /** Explicit source-local fork entries, if declared. */
+    get branches() {
+        return this._branches;
+    }
     constructor(routeId, options = {}, parentAgent) {
         this.nextSteps = [];
-        this.guidelines = [];
+        this._instructions = [];
         // Use provided ID or generate a deterministic one
         this.id = options.id || (0, utils_1.generateStepId)(routeId, options.description);
-        this.routeId = routeId;
+        this.flowId = routeId;
         this.description = options.description;
+        this._auto = options.auto ?? false;
+        this._branches = options.branches;
         this.collect = options.collect;
-        this.skipIf = options.skipIf;
+        this.skip = options.skip;
         this.requires = options.requires;
         this.prompt = options.prompt;
+        this.reply = options.reply;
         this.when = options.when;
+        this.if = options.if;
         this.prepare = options.prepare;
         this.finalize = options.finalize;
         this.tools = options.tools;
-        // Initialize guidelines from options
-        if (options.guidelines) {
-            options.guidelines.forEach((guideline) => {
-                this.addGuideline(guideline);
+        // Validate when/if split: functions belong on `if`, not `when`
+        if (this.when !== undefined) {
+            const whenValue = this.when;
+            if (typeof whenValue === 'function') {
+                throw new FlowConfigurationError(`[FlowConfigurationError] Step "${this.id}" has a function on "when": functions belong on "if" only. Move the function to the "if" field.`);
+            }
+            if (Array.isArray(whenValue)) {
+                for (let i = 0; i < whenValue.length; i++) {
+                    if (typeof whenValue[i] === 'function') {
+                        throw new FlowConfigurationError(`[FlowConfigurationError] Step "${this.id}" has a function at "when[${i}]": functions belong on "if" only. Move the function to the "if" field.`);
+                    }
+                }
+            }
+        }
+        // Validate auto-step shape: auto-steps cannot define prompt, collect, tools, or finalize
+        if (this._auto) {
+            const violatingFields = [];
+            if (this.prompt != null)
+                violatingFields.push('prompt');
+            if (this.collect != null && this.collect.length > 0)
+                violatingFields.push('collect');
+            if (this.tools != null && this.tools.length > 0)
+                violatingFields.push('tools');
+            if (this.finalize != null)
+                violatingFields.push('finalize');
+            if (violatingFields.length > 0) {
+                throw new FlowConfigurationError(`[FlowConfigurationError] Auto-step "${this.id}" cannot define: ${violatingFields.join(', ')}. Auto-steps run without an LLM call and must not declare prompt, collect, tools, or finalize. Remove these fields or set auto: false.`);
+            }
+        }
+        // Validate reply-step shape: reply steps cannot define prompt, collect, tools, finalize, or auto: true
+        if (this.reply != null) {
+            const conflictingFields = [];
+            if (this.prompt != null)
+                conflictingFields.push('prompt');
+            if (this.collect != null && this.collect.length > 0)
+                conflictingFields.push('collect');
+            if (this.tools != null && this.tools.length > 0)
+                conflictingFields.push('tools');
+            if (this.finalize != null)
+                conflictingFields.push('finalize');
+            if (this._auto)
+                conflictingFields.push('auto: true');
+            if (conflictingFields.length > 0) {
+                throw new FlowConfigurationError(`[FlowConfigurationError] Step "${this.id}" sets "reply" together with conflicting fields: ${conflictingFields.join(', ')}. A reply step skips the LLM call and cannot define prompt, collect, tools, finalize, or auto: true.`);
+            }
+        }
+        // Validate branches shape
+        if (this._branches !== undefined) {
+            this.validateBranches(this._branches);
+        }
+        // Initialize instructions from options
+        if (options.instructions) {
+            options.instructions.forEach((instruction) => {
+                this.addInstruction(instruction);
             });
         }
         // Store reference to parent agent for ToolManager access
@@ -46,8 +117,8 @@ class Step {
         if (config.collect !== undefined) {
             this.collect = config.collect;
         }
-        if (config.skipIf !== undefined) {
-            this.skipIf = config.skipIf;
+        if (config.skip !== undefined) {
+            this.skip = config.skip;
         }
         if (config.requires !== undefined) {
             this.requires = config.requires;
@@ -66,18 +137,6 @@ class Step {
         }
         return this;
     }
-    /**
-     * Shortcut to end the current route
-     *
-     * @param options - Optional step options for the end step
-     * @returns Terminal step result
-     */
-    endRoute(options = {}) {
-        return this.nextStep({
-            ...options,
-            step: constants_1.END_ROUTE,
-        });
-    }
     /**
      * Create a transition from this step to another
      *
@@ -85,23 +144,8 @@ class Step {
      * @returns StepResult that supports chaining
      */
     nextStep(spec) {
-        // Handle END_ROUTE
-        if (spec.step && typeof spec.step === "symbol" && spec.step === constants_1.END_ROUTE) {
-            const endStep = new Step(this.routeId, {
-                ...spec,
-                id: constants_1.END_ROUTE_ID,
-            }, this.parentAgent);
-            this.nextSteps.push(endStep);
-            return this.createTerminalRef();
-        }
-        // Handle direct step reference
-        if (spec.step && typeof spec.step !== "symbol") {
-            // This is a bit tricky. We need to find the actual Step instance.
-            // For now, let's assume the user will provide a Step instance directly.
-            // This part might need to be revisited.
-        }
         // Create new target step for prompt or tool
-        const targetStep = new Step(this.routeId, spec, this.parentAgent);
+        const targetStep = new Step(this.flowId, spec, this.parentAgent);
         this.nextSteps.push(targetStep);
         return this.createStepRefWithTransition(targetStep.getRef(), targetStep);
     }
@@ -119,7 +163,7 @@ class Step {
                 ? { ...branchSpec.step, id: branchSpec.id }
                 : branchSpec.step;
             // Create a new step for this branch
-            const branchStep = new Step(this.routeId, stepOptions, this.parentAgent);
+            const branchStep = new Step(this.flowId, stepOptions, this.parentAgent);
             // Add it to our transitions
             this.nextSteps.push(branchStep);
             // Create a step result for chaining
@@ -129,56 +173,21 @@ class Step {
         return result;
     }
     /**
-     * Add a guideline specific to this step
-     */
-    addGuideline(guideline) {
-        this.guidelines.push(guideline);
-    }
-    /**
-     * Get guidelines for this step
+     * Add an instruction to this step.
      */
-    getGuidelines() {
-        return [...this.guidelines];
+    addInstruction(instruction) {
+        this._instructions.push({
+            ...instruction,
+            kind: instruction.kind || 'should',
+            id: instruction.id || `instruction_${this.id}_${this._instructions.length}`,
+            enabled: instruction.enabled !== false, // Default to true
+        });
     }
     /**
-     * Evaluate and match active guidelines based on their conditions
-     * Returns guidelines that should be active given the current context
+     * Get instructions for this step
      */
-    async evaluateGuidelines(context, session, history) {
-        const templateContext = { context, session, history, data: session?.data || {} };
-        const evaluator = (0, utils_1.createConditionEvaluator)(templateContext);
-        const matches = [];
-        for (const guideline of this.guidelines) {
-            // Skip disabled guidelines
-            if (guideline.enabled === false) {
-                continue;
-            }
-            if (guideline.condition) {
-                const evaluation = await evaluator.evaluateCondition(guideline.condition, 'AND');
-                // Include guideline if:
-                // 1. No programmatic conditions (only strings) - always active
-                // 2. Programmatic conditions evaluate to true
-                if (!evaluation.hasProgrammaticConditions || evaluation.programmaticResult) {
-                    const rationale = evaluation.aiContextStrings.length > 0
-                        ? `Condition met: ${evaluation.aiContextStrings.join(" AND ")}`
-                        : evaluation.hasProgrammaticConditions
-                            ? "Programmatic condition evaluated to true"
-                            : "Always active (no conditions)";
-                    matches.push({
-                        guideline,
-                        rationale
-                    });
-                }
-            }
-            else {
-                // No condition means always active
-                matches.push({
-                    guideline,
-                    rationale: "Always active (no conditions)"
-                });
-            }
-        }
-        return matches;
+    getInstructions() {
+        return [...this._instructions];
     }
     /**
      * Add a tool to this step using the unified Tool interface
@@ -260,7 +269,7 @@ class Step {
         if (!this.parentAgent?.tool) {
             // Fallback to local resolution if no ToolManager available
             const resolved = this.resolveTools();
-            return resolved.find(tool => tool.id === toolId || tool.name === toolId);
+            return resolved.find(tool => tool.id === toolId || tool.id === toolId);
         }
         // Use ToolManager to find the tool with proper scope resolution
         return this.parentAgent.tool.find(toolId, scope || types_1.ToolScope.ALL, this, undefined);
@@ -328,41 +337,107 @@ class Step {
         return [...this.nextSteps];
     }
     /**
-     * Evaluate when condition using ConditionEvaluator
+     * Evaluate when/if conditions using the v2 split logic.
+     * `if` (code predicate) evaluates first (free); `when` (AI) evaluates only when `if` passes.
+     * Both are combined with AND semantics.
      */
     async evaluateWhen(templateContext) {
-        if (!this.when) {
+        // If neither `when` nor `if` is set, step is always eligible
+        if (!this.when && !this.if) {
             return {
                 shouldActivate: true,
                 aiContextStrings: [],
                 hasProgrammaticConditions: false
             };
         }
-        const evaluator = (0, utils_1.createConditionEvaluator)(templateContext);
-        const result = await evaluator.evaluateCondition(this.when, 'AND');
+        // Evaluate `if` first (free, code-only)
+        if (this.if) {
+            const predicates = Array.isArray(this.if) ? this.if : [this.if];
+            for (const predicate of predicates) {
+                try {
+                    const result = await predicate({
+                        data: templateContext.data,
+                        context: templateContext.context,
+                        session: templateContext.session,
+                        history: templateContext.history || [],
+                    });
+                    if (!result) {
+                        // `if` failed — short-circuit, don't bother with `when`
+                        return {
+                            shouldActivate: false,
+                            aiContextStrings: [],
+                            hasProgrammaticConditions: true
+                        };
+                    }
+                }
+                catch (error) {
+                    utils_1.logger.warn(`[Step] "if" predicate failed for step "${this.id}":`, error);
+                    return {
+                        shouldActivate: false,
+                        aiContextStrings: [],
+                        hasProgrammaticConditions: true
+                    };
+                }
+            }
+        }
+        // `if` passed (or was absent) — now evaluate `when` (AI-evaluated strings)
+        if (this.when) {
+            const whenStrings = Array.isArray(this.when) ? this.when : [this.when];
+            // `when` strings are handed to the AI — return them as aiContextStrings
+            // The programmatic result is true (strings don't fail programmatically;
+            // they're scored by the AI at routing time)
+            return {
+                shouldActivate: true,
+                aiContextStrings: whenStrings,
+                hasProgrammaticConditions: !!this.if
+            };
+        }
+        // Only `if` was set and it passed
         return {
-            shouldActivate: result.programmaticResult,
-            aiContextStrings: result.aiContextStrings,
-            hasProgrammaticConditions: result.hasProgrammaticConditions
+            shouldActivate: true,
+            aiContextStrings: [],
+            hasProgrammaticConditions: true
         };
     }
     /**
-     * Evaluate skipIf condition using ConditionEvaluator
+     * Evaluate the skip condition (if-only shape — code predicates, OR semantics).
+     * Returns true if the step should be skipped.
      */
-    async evaluateSkipIf(templateContext) {
-        if (!this.skipIf) {
+    async evaluateSkip(templateContext) {
+        if (!this.skip) {
             return {
                 shouldSkip: false,
                 aiContextStrings: [],
                 hasProgrammaticConditions: false
             };
         }
-        const evaluator = (0, utils_1.createConditionEvaluator)(templateContext);
-        const result = await evaluator.evaluateCondition(this.skipIf, 'OR');
+        const predicates = Array.isArray(this.skip) ? this.skip : [this.skip];
+        // OR semantics: if ANY predicate returns true, skip
+        for (const predicate of predicates) {
+            try {
+                const result = await predicate({
+                    data: templateContext.data,
+                    context: templateContext.context,
+                    session: templateContext.session,
+                    history: templateContext.history || [],
+                });
+                if (result) {
+                    return {
+                        shouldSkip: true,
+                        aiContextStrings: [],
+                        hasProgrammaticConditions: true
+                    };
+                }
+            }
+            catch (error) {
+                utils_1.logger.warn(`[Step] "skip" predicate failed for step "${this.id}":`, error);
+                // On error, default to not skipping (safe fallback)
+            }
+        }
         return {
-            shouldSkip: result.programmaticResult,
-            aiContextStrings: result.aiContextStrings,
-            hasProgrammaticConditions: result.hasProgrammaticConditions
+            shouldSkip: false,
+            aiContextStrings: [],
+            hasProgrammaticConditions: true
         };
     }
     /**
@@ -379,7 +454,7 @@ class Step {
     getRef() {
         return {
             id: this.id,
-            routeId: this.routeId,
+            flowId: this.flowId,
         };
     }
     /**
@@ -391,26 +466,6 @@ class Step {
             ...ref,
             nextStep: (spec) => stepInstance.nextStep(spec),
             branch: (branches) => stepInstance.branch(branches),
-            endRoute: (options) => stepInstance.endRoute(options),
-        };
-    }
-    /**
-     * Create a terminal step reference (for END_ROUTE)
-     */
-    createTerminalRef() {
-        const terminalRef = {
-            id: constants_1.END_ROUTE_ID,
-            routeId: this.routeId,
-        };
-        return {
-            ...terminalRef,
-            nextStep: () => {
-                throw new Error("Cannot transition from END_ROUTE step");
-            },
-            branch: () => {
-                throw new Error("Cannot branch from END_ROUTE step");
-            },
-            endRoute: (options) => this.endRoute(options),
         };
     }
     /**
@@ -421,7 +476,6 @@ class Step {
             ...this.getRef(),
             nextStep: (spec) => this.nextStep(spec),
             branch: (branches) => this.branch(branches),
-            endRoute: (options) => this.endRoute(options),
         };
     }
     /**
@@ -432,17 +486,58 @@ class Step {
         return {
             id: this.id,
             description: this.description,
+            auto: this._auto,
+            branches: this._branches,
             prompt: this.prompt,
+            reply: this.reply,
             tools: this.tools,
             prepare: this.prepare,
             finalize: this.finalize,
             collect: this.collect,
-            skipIf: this.skipIf,
+            skip: this.skip,
             requires: this.requires,
             when: this.when,
-            guidelines: this.getGuidelines(),
+            if: this.if,
+            instructions: this.getInstructions(),
         };
     }
+    /**
+     * Validate the branches array at construction time.
+     * Checks:
+     * - Non-empty array
+     * - Unconditional entries (no `when` and no `if`) only legal as the last entry
+     * - Directive `then` values: at most one position field, no empty `goTo: {}`
+     */
+    validateBranches(branches) {
+        if (branches.length === 0) {
+            throw new FlowConfigurationError(`[FlowConfigurationError] Empty branches array on step "${this.id}": branches must contain at least one entry. Add branch entries or remove the branches field.`);
+        }
+        const POSITION_FIELDS = ['goTo', 'goToStep', 'complete', 'abort', 'reset'];
+        for (let i = 0; i < branches.length; i++) {
+            const entry = branches[i];
+            const isLast = i === branches.length - 1;
+            // Non-last entry without `when` or `if` is dead code — later entries are unreachable
+            if (!isLast && !entry.when && !entry.if) {
+                throw new FlowConfigurationError(`[FlowConfigurationError] Dead-code branch at index ${i}: branches[${i}] has neither "when" nor "if" and is not the last entry. Entries after index ${i} are unreachable. Move the unconditional entry to the end or add a condition.`);
+            }
+            // Validate Directive `then` values
+            if (entry.then && typeof entry.then === 'object') {
+                const directive = entry.then;
+                // Check for multiple position fields
+                const setPositionFields = POSITION_FIELDS.filter((field) => directive[field] !== undefined);
+                if (setPositionFields.length > 1) {
+                    throw new FlowConfigurationError(`[FlowConfigurationError] Multiple position fields in branches[${i}].then: Directive sets ${setPositionFields.join(', ')}. At most one position field is allowed per Directive. Remove all but one.`);
+                }
+                // Check for empty goTo: {}
+                if (directive.goTo !== undefined && typeof directive.goTo === 'object' && directive.goTo !== null) {
+                    const goToObj = directive.goTo;
+                    if (Object.keys(goToObj).length === 0) {
+                        throw new FlowConfigurationError(`[FlowConfigurationError] Empty goTo in branches[${i}].then: Directive has "goTo: {}" with no flow target. Provide at least a flow id or title.`);
+                    }
+                }
+            }
+        }
+    }
 }
 exports.Step = Step;
 //# sourceMappingURL=Step.js.map