@falai/agent 1.2.7 → 2.0.0

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

@@ -0,0 +1,186 @@
+/**
+ * Flow (Journey) DSL implementation
+ */
+import type { FlowOptions, FlowRef, StepOptions, FlowLifecycleHooks, StructuredSchema, Instruction, Term, Tool, TemplateContext, ConditionEvaluationResult, Directive } from "../types";
+import type { ConditionWhen, ConditionIf } from "../types/flow";
+import { Step } from "./Step";
+import { Agent } from './Agent';
+/**
+ * Represents a conversational flow/journey
+ */
+export declare class Flow<TContext = unknown, TData = unknown> {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly when?: ConditionWhen;
+    readonly if?: ConditionIf<TContext, TData>;
+    private readonly _initialStep;
+    readonly responseOutputSchema?: StructuredSchema;
+    readonly initialData?: Partial<TData>;
+    readonly requiredFields?: (keyof TData)[];
+    readonly optionalFields?: (keyof TData)[];
+    readonly onComplete?: string;
+    readonly reentrant: boolean;
+    readonly hooks?: FlowLifecycleHooks<TContext, TData>;
+    routingExtrasSchema?: StructuredSchema;
+    instructions: Instruction<TContext, TData>[];
+    tools: Tool<TContext, TData>[];
+    knowledgeBase: Record<string, unknown>;
+    /** Get the initial (first) step of this flow. */
+    get initialStep(): Step<TContext, TData>;
+    private parentAgent?;
+    /**
+     * Tracks whether this flow has participated in at least one turn.
+     * Used to emit a DEBUG warning when `addStep` mutates the graph mid-session.
+     * @internal Set by the pipeline after the first turn involving this flow.
+     */
+    _hasHandledTurn: boolean;
+    constructor(options: FlowOptions<TContext, TData>, parentAgent?: Agent<TContext, TData>);
+    /**
+     * Build a sequential step machine from an array of steps
+     * The last step in the array is the implicit terminus of the flow.
+     * @private
+     */
+    private buildSequentialSteps;
+    /**
+     * Imperatively add a step to this flow after construction.
+     *
+     * Applies the same construction-time validations as declarative `steps: [...]`
+     * registration (auto-step shape, `reply` exclusivity, `branches` validation,
+     * schema lookups). Connects the new step as a successor of the current last
+     * step in the flow.
+     *
+     * When called after the agent has handled a turn, emits a DEBUG-level warning
+     * that the flow graph is being mutated mid-session; the operation still succeeds.
+     *
+     * @param options - Step configuration
+     * @returns The newly created and registered Step
+     *
+     * **Validates: Requirements 8.7, 26.1–26.5**
+     */
+    addStep(options: StepOptions<TContext, TData>): Step<TContext, TData>;
+    /**
+     * Find the last step in the sequential chain (the terminal step with no transitions).
+     * If multiple terminal steps exist (branching), returns the one visited last in BFS order.
+     * @private
+     */
+    private getLastStep;
+    /**
+     * 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<ConditionEvaluationResult>;
+    /**
+     * Create an instruction specific to this flow.
+     */
+    createInstruction(instruction: Instruction<TContext, TData>): this;
+    /**
+     * Register a tool for this flow
+     */
+    createTool(tool: Tool<TContext, TData>): this;
+    /**
+     * Register multiple tools for this flow
+     */
+    registerTools(tools: Tool<TContext, TData>[]): this;
+    /**
+     * Add a tool to this flow using the ToolManager API
+     * Creates and adds the tool to flow scope in one operation
+     */
+    addTool(tool: Tool<TContext, TData>): this;
+    /**
+     * Get all instructions for this flow
+     */
+    getInstructions(): Instruction<TContext, TData>[];
+    /**
+     * Get all terms for this flow
+     * @deprecated Flow-level terms removed in v2. Always returns empty array.
+     */
+    getTerms(): Term<TContext>[];
+    /**
+     * Get all tools for this flow
+     */
+    getTools(): Tool<TContext, TData>[];
+    /**
+     * Get optional extras schema requested during routing
+     */
+    getRoutingExtrasSchema(): StructuredSchema | undefined;
+    /**
+     * Get optional structured response schema for this flow's message
+     */
+    getResponseOutputSchema(): StructuredSchema | undefined;
+    getSteps(): Step<TContext, TData>[];
+    /**
+     * Get flow reference
+     */
+    getRef(): FlowRef;
+    /**
+     * Get all steps in this flow (via traversal from initial step)
+     */
+    getAllSteps(): Step<TContext, TData>[];
+    /**
+     * Get a specific step by ID
+     * @param stepId - The step ID to find
+     * @returns The step if found, undefined otherwise
+     */
+    getStep(stepId: string): Step<TContext, TData> | undefined;
+    /**
+     * Get a description of the flow structure for debugging
+     */
+    describe(): string;
+    /**
+     * Handle data updates for this flow, calling the onDataUpdate hook if configured
+     * @param data - New collected data
+     * @param previousCollected - Previously collected data
+     * @returns Modified data after hook processing, or original data if no hook
+     */
+    handleDataUpdate(data: Partial<TData>, previousCollected: Partial<TData>): Promise<Partial<TData>>;
+    /**
+     * Handle context updates for this flow, calling the onContextUpdate hook if configured
+     * @param newContext - New context
+     * @param previousContext - Previous context
+     */
+    handleContextUpdate(newContext: TContext, previousContext: TContext): Promise<void>;
+    /**
+     * Export flow configuration as FlowOptions for copying/cloning
+     * @returns FlowOptions that can be used to create a new flow with identical configuration
+     */
+    toOptions(): FlowOptions<TContext, TData>;
+    /**
+     * Check if this flow is complete based on the provided data
+     * @param data - Currently collected agent-level data
+     * @returns true if all required fields are present, false otherwise
+     *
+     * Note: Flows with no requiredFields (whether they have optionalFields or not)
+     * are never complete based on data — they complete when the last step finishes (implicit terminus).
+     */
+    isComplete(data: Partial<TData>): boolean;
+    /**
+     * Get the list of missing required fields for this flow
+     * @param data - Currently collected agent-level data
+     * @returns Array of missing required field keys
+     */
+    getMissingRequiredFields(data: Partial<TData>): (keyof TData)[];
+    /**
+     * Get the completion progress for this flow as a percentage
+     * @param data - Currently collected agent-level data
+     * @returns Completion progress as a number between 0 and 1
+     *
+     * Note: Must be consistent with isComplete() logic
+     */
+    getCompletionProgress(data: Partial<TData>): number;
+    /**
+     * Evaluate the onComplete handler and return a Directive.
+     *
+     * In v2, top-level `onComplete` is desugared to `hooks.onComplete` at
+     * construction time. This method delegates to `hooks.onComplete` when set.
+     *
+     * @param session - Current session step
+     * @param context - Agent context
+     * @returns Directive or undefined if no transition
+     */
+    evaluateOnComplete(session: {
+        data?: Partial<TData>;
+    }, context?: TContext): Promise<Directive<TContext, TData> | undefined>;
+}
+//# sourceMappingURL=Flow.d.ts.map

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

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