@falai/agent 1.2.7 → 2.0.0

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

@@ -0,0 +1,182 @@
+import type { Event, AgentOptions, StructuredSchema, SessionState, AiProvider, TemplateContext } from "../types";
+import type { Flow } from "./Flow";
+import type { Step } from "./Step";
+import { PromptSectionCache } from "./PromptSectionCache";
+export interface CandidateStep<TContext = unknown, TData = unknown> {
+    step: Step<TContext, TData>;
+    isFlowComplete?: boolean;
+}
+export interface FlowRoutingDecisionOutput {
+    context: string;
+    flows: Record<string, number>;
+    selectedStepId?: string;
+    stepReasoning?: string;
+    responseDirectives?: string[];
+    extractions?: Array<{
+        name: string;
+        value: any;
+        confidence?: number;
+        source?: "message" | "history";
+    }>;
+    contextUpdate?: Record<string, unknown>;
+}
+export interface FlowRouterOptions {
+    /**
+     * Score margin the best alternative flow must exceed the current flow's score
+     * by before the agent switches flows. Prevents flip-flopping on marginal differences.
+     * @default 15
+     */
+    flowSwitchMargin?: number;
+    /**
+     * Callback invoked when the active flow changes.
+     * Used by Agent to invalidate flow-dependent prompt cache sections.
+     */
+    onFlowSwitch?: () => void;
+    /**
+     * Shared prompt section cache for memoizing static prompt sections.
+     */
+    promptSectionCache?: PromptSectionCache;
+}
+export interface BuildStepSelectionPromptParams<TContext = unknown, TData = unknown> {
+    flow: Flow<TContext, TData>;
+    currentStep: Step<TContext, TData> | undefined;
+    candidates: CandidateStep<TContext, TData>[];
+    data: Partial<TData>;
+    history: Event[];
+    lastMessage: string;
+    agentOptions?: AgentOptions<TContext, TData>;
+    context?: TContext;
+    session?: SessionState<TData>;
+    stepConditionContext?: string[];
+}
+export interface BuildRoutingPromptParams<TContext = unknown, TData = unknown> {
+    history: Event[];
+    flows: Flow<TContext, TData>[];
+    lastMessage: string;
+    agentOptions?: AgentOptions<TContext, TData>;
+    session?: SessionState<TData>;
+    activeFlowSteps?: Step<TContext, TData>[];
+    context?: TContext;
+}
+export declare class FlowRouter<TContext = unknown, TData = unknown> {
+    private readonly options?;
+    constructor(options?: FlowRouterOptions | undefined);
+    /**
+     * Check whether the history contains any user messages.
+     * Used to detect "session resume" scenarios where a flow/step was
+     * pre-set programmatically and the conversation starts with only
+     * system messages (or no messages at all).
+     * @private
+     */
+    private hasUserMessages;
+    /**
+     * Handle the "session resume" fast-path: when a session already has a
+     * pre-set currentFlow (and optionally currentStep) and the conversation
+     * history contains no user messages, honor the pre-set position instead
+     * of running AI flow/step selection.
+     *
+     * Returns `undefined` when the fast-path does not apply.
+     * @private
+     */
+    private handleSessionResume;
+    /**
+     * Enter a flow if not already in it, merging initial data.
+     *
+     * When the flow is `reentrant` and was previously completed in this
+     * session, clears every field declared in the flow's `requiredFields`
+     * and `optionalFields` before entering — so the flow starts fresh from
+     * its initial step instead of being instantly marked complete by stale
+     * data. Fields not owned by this flow are preserved.
+     *
+     * @private
+     */
+    private enterFlowIfNeeded;
+    /**
+     * Optimized decision for single-flow scenarios
+     * Skips flow scoring and only does step selection
+     * @private
+     */
+    private decideSingleFlowStep;
+    /**
+     * Recursively traverse step chain to find first non-skipped step using new condition evaluation
+     * @private
+     */
+    private findFirstValidStepRecursiveWithConditions;
+    /**
+     * Identify valid next candidate steps using new condition evaluation system
+     * Returns step with isFlowComplete flag if flow is complete (all steps skipped or no transitions remain)
+     *
+     * Flow completion is implicit: when the last step has no transitions, the flow is done.
+     */
+    getCandidateStepsWithConditions(route: Flow<TContext, TData>, currentStep: Step<TContext, TData> | undefined, templateContext: TemplateContext<TContext, TData>): Promise<CandidateStep<TContext, TData>[]>;
+    /**
+     * Full routing orchestration: builds prompt and schema, calls AI, selects route/step,
+     * and updates the session (including initialData merge when entering a new flow).
+     *
+     * OPTIMIZATION: If there's only 1 route, skips route scoring and only does step selection.
+     * CROSS-FLOW COMPLETION: Evaluates all flows for completion based on collected data.
+     */
+    decideFlowAndStep(params: {
+        flows: Flow<TContext, TData>[];
+        session: SessionState<TData>;
+        history: Event[];
+        agentOptions?: AgentOptions<TContext, TData>;
+        provider: AiProvider;
+        context: TContext;
+        signal?: AbortSignal;
+    }): Promise<{
+        selectedFlow?: Flow<TContext, TData>;
+        selectedStep?: Step<TContext, TData>;
+        responseDirectives?: string[];
+        session: SessionState<TData>;
+        isFlowComplete?: boolean;
+        completedFlows?: Flow<TContext, TData>[];
+    }>;
+    /**
+     * Filter flows based on when conditions
+     * @param routes - Flows that passed skipIf filtering
+     * @param templateContext - Context for condition evaluation
+     * @returns Object with eligible flows and collected AI context strings
+     */
+    filterFlowsByWhen(routes: Flow<TContext, TData>[], templateContext: TemplateContext<TContext, TData>): Promise<{
+        eligibleRoutes: Flow<TContext, TData>[];
+        aiContextStrings: string[];
+    }>;
+    /**
+     * Evaluate all flows for completion based on collected data
+     * @param routes - All available flows
+     * @param data - Currently collected agent-level data
+     * @returns Array of flows that are complete
+     */
+    evaluateFlowCompletions(routes: Flow<TContext, TData>[], data: Partial<TData>): Flow<TContext, TData>[];
+    /**
+     * Get completion status for all flows
+     * @param routes - All available flows
+     * @param data - Currently collected agent-level data
+     * @returns Map of flow ID to completion progress (0-1)
+     */
+    getFlowCompletionStatus(routes: Flow<TContext, TData>[], data: Partial<TData>): Map<string, number>;
+    /**
+     * Find the best flow to continue based on completion status and user intent
+     * Prioritizes flows that are partially complete but not finished
+     * IMPORTANT: Completed flows are excluded to prevent re-entering finished tasks
+     * @param routes - All available flows
+     * @param data - Currently collected agent-level data
+     * @param routeScores - AI-generated route scores from routing decision
+     * @returns Flow that should be prioritized for continuation
+     */
+    selectOptimalFlow(routes: Flow<TContext, TData>[], data: Partial<TData>, routeScores: Record<string, number>, currentRouteId?: string): Flow<TContext, TData> | undefined;
+    /**
+     * Build prompt for step selection within a single flow
+     * @private
+     */
+    private buildStepSelectionPrompt;
+    /**
+     * Build schema for step selection
+     * @private
+     */
+    private buildStepSelectionSchema;
+    buildDynamicFlowSchema(routes: Flow<TContext, TData>[], extrasSchema?: StructuredSchema, activeFlowSteps?: Step<TContext, TData>[]): StructuredSchema;
+    buildRoutingPrompt(params: BuildRoutingPromptParams<TContext, TData>): Promise<string>;
+}
+//# sourceMappingURL=FlowRouter.d.ts.map

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

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