@falai/agent 3.4.5 → 4.0.0-alpha.1

package/src/core/SignalCoordinator.ts

@@ -1,263 +0,0 @@
-/**
- * SignalCoordinator owns the signal pre/post phase orchestration for a turn:
- *
- * - `runPrePhase()` / `runPostPhase()` — delegation to the SignalProcessor,
- *   returning a stable empty shape when no processor is configured.
- * - `applyPositionDirective()` — applies a pre-phase directive's position
- *   field (goTo, goToStep, complete, abort, reset) as the turn's routing
- *   decision, discarding the router's result.
- * - `applyPostPhase()` — runs the post phase and applies its directive to
- *   the turn result in one step: session updates, pendingDirective for
- *   position fields (no mid-turn re-entry per D6), and the reply override
- *   of the user-visible message.
- */
-
-import type { Directive, Event, SessionState } from "../types/index.js";
-import type { SignalFiring } from "../types/signals.js";
-import type { SignalProcessor } from "./SignalProcessor.js";
-import type { Flow } from "./Flow.js";
-import type { Step } from "./Step.js";
-import { hasDirectivePositionField } from "./ResponsePipeline.js";
-import { enterFlow, enterStep, mergeCollected, logger } from "../utils/index.js";
-
-/** Result of a signal phase run (pre or post). */
-export interface SignalPhaseResult<TContext = unknown, TData = unknown> {
-    firings: SignalFiring<TContext, TData>[];
-    updatedSession: SessionState<TData>;
-    mergedDirective: Directive<TContext, TData> | undefined;
-}
-
-export class SignalCoordinator<TContext = unknown, TData = unknown> {
-    constructor(
-        private readonly deps: {
-            getFlows: () => Flow<TContext, TData>[];
-            signalProcessor?: SignalProcessor<TContext, TData>;
-        }
-    ) { }
-
-    /** Whether a signal processor is configured (zero-cost path when absent). */
-    get enabled(): boolean {
-        return this.deps.signalProcessor !== undefined;
-    }
-
-    /**
-     * PRE-SIGNAL PHASE — Evaluates pre/both signals in parallel with routing.
-     *
-     * Delegates to `signalProcessor.runPreSignalPhase(...)` when configured.
-     * When no signal processor is present (zero-cost path), returns a stable
-     * empty shape so callers don't need to branch.
-     *
-     * @requirements 2.1, 2.3, 8.6, 13.3
-     */
-    async runPrePhase(
-        session: SessionState<TData>,
-        context: TContext,
-        history: Event[],
-    ): Promise<SignalPhaseResult<TContext, TData>> {
-        if (!this.deps.signalProcessor) {
-            return { firings: [], updatedSession: session, mergedDirective: undefined };
-        }
-        const result = await this.deps.signalProcessor.runPreSignalPhase({ session, history, context });
-        return {
-            firings: result.firings,
-            updatedSession: result.updatedSession,
-            mergedDirective: result.mergedDirective,
-        };
-    }
-
-    /**
-     * POST-SIGNAL PHASE — Evaluates post/both signals after finalize/onComplete.
-     *
-     * Delegates to `signalProcessor.runPostSignalPhase(...)` when configured.
-     * When no signal processor is present, returns a stable empty shape.
-     *
-     * Post-phase signals see the complete turn result: assistant message in history,
-     * collected data, tool results. Position directives from this phase set
-     * `session.pendingDirective` (no mid-turn re-entry per D6 decision).
-     *
-     * Pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`) are already
-     * dropped inside `runPostSignalPhase` per Phase 4.5 — this seam does NOT
-     * re-introduce them.
-     *
-     * @requirements 9.1, 9.2, 9.3, 9.4
-     */
-    async runPostPhase(
-        session: SessionState<TData>,
-        context: TContext,
-        history: Event[],
-    ): Promise<SignalPhaseResult<TContext, TData>> {
-        if (!this.deps.signalProcessor) {
-            return { firings: [], updatedSession: session, mergedDirective: undefined };
-        }
-        const result = await this.deps.signalProcessor.runPostSignalPhase({ session, history, context });
-        return {
-            firings: result.firings,
-            updatedSession: result.updatedSession,
-            mergedDirective: result.mergedDirective,
-        };
-    }
-
-    /**
-     * Run the post phase and apply its merged directive to the turn result:
-     * session updates from the phase, `pendingDirective` for position fields
-     * (Requirement 9.3, no mid-turn re-entry per D6), and the reply override
-     * of the user-visible message (undefined means "leave it unchanged"; an
-     * empty string is an explicit replacement).
-     *
-     * @requirements 9.1, 9.2, 9.3, 9.4
-     */
-    async applyPostPhase(params: {
-        session: SessionState<TData>;
-        context: TContext;
-        historyEvents: Event[];
-        message: string;
-    }): Promise<{
-        session: SessionState<TData>;
-        message: string;
-        firings: SignalFiring<TContext, TData>[];
-        /** True when the directive's `reply` replaced the message. */
-        replyOverridden: boolean;
-    }> {
-        const postResult = await this.runPostPhase(
-            params.session, params.context, params.historyEvents,
-        );
-        let session = postResult.updatedSession;
-
-        // Requirement 9.3: Post-phase position directive sets session.pendingDirective
-        if (postResult.mergedDirective && hasDirectivePositionField(postResult.mergedDirective)) {
-            session = { ...session, pendingDirective: postResult.mergedDirective };
-        }
-
-        const replyOverridden = postResult.mergedDirective?.reply !== undefined;
-        const message = replyOverridden
-            ? postResult.mergedDirective!.reply!
-            : params.message;
-
-        return { session, message, firings: postResult.firings, replyOverridden };
-    }
-
-    /**
-     * Apply a signal's position directive (goTo, goToStep, complete, abort, reset).
-     * Discards routing result and uses the signal's position decision.
-     *
-     * @requirements 8.3
-     */
-    applyPositionDirective(
-        signalResult: {
-            firings: SignalFiring<TContext, TData>[];
-            updatedSession: SessionState<TData>;
-            mergedDirective: Directive<TContext, TData> | undefined;
-        },
-    ): {
-        selectedFlow?: Flow<TContext, TData>;
-        selectedStep?: Step<TContext, TData>;
-        responseDirectives?: string[];
-        session: SessionState<TData>;
-        isFlowComplete: boolean;
-        signalFirings?: SignalFiring<TContext, TData>[];
-        signalPreDirective?: Directive<TContext, TData>;
-        signalHalted?: boolean;
-        signalHaltReply?: string;
-    } {
-        const directive = signalResult.mergedDirective!;
-        let session = signalResult.updatedSession;
-        const flows = this.deps.getFlows();
-        let selectedFlow: Flow<TContext, TData> | undefined;
-        let selectedStep: Step<TContext, TData> | undefined;
-        let isFlowComplete = false;
-
-        // Apply data updates if present alongside position
-        if (directive.dataUpdate) {
-            session = mergeCollected(session, directive.dataUpdate);
-        }
-
-        if (directive.goTo) {
-            const flowTarget = typeof directive.goTo === 'string'
-                ? directive.goTo
-                : directive.goTo.flow ?? directive.goTo.step;
-
-            if (flowTarget) {
-                const targetFlow = flows.find(f => f.id === flowTarget || f.title === flowTarget);
-                if (targetFlow) {
-                    session = enterFlow(session, targetFlow.id, targetFlow.title);
-                    selectedFlow = targetFlow;
-
-                    if (typeof directive.goTo === 'object' && directive.goTo.step) {
-                        const targetStep = targetFlow.getStep(directive.goTo.step);
-                        if (targetStep) {
-                            session = enterStep(session, targetStep.id, targetStep.description);
-                            selectedStep = targetStep;
-                        }
-                    }
-                } else {
-                    logger.warn(`[Signals] Pre-phase goTo target not found: "${flowTarget}". Falling back to no flow.`);
-                }
-            }
-        } else if (directive.goToStep) {
-            const stepTarget = typeof directive.goToStep === 'string'
-                ? directive.goToStep
-                : directive.goToStep.step;
-            const flowTarget = typeof directive.goToStep === 'object'
-                ? directive.goToStep.flow
-                : undefined;
-
-            if (flowTarget) {
-                const targetFlow = flows.find(f => f.id === flowTarget || f.title === flowTarget);
-                if (targetFlow) {
-                    session = enterFlow(session, targetFlow.id, targetFlow.title);
-                    selectedFlow = targetFlow;
-                    const targetStep = targetFlow.getStep(stepTarget);
-                    if (targetStep) {
-                        session = enterStep(session, targetStep.id, targetStep.description);
-                        selectedStep = targetStep;
-                    }
-                }
-            } else if (session.currentFlow) {
-                const currentFlow = flows.find(f => f.id === session.currentFlow?.id);
-                if (currentFlow) {
-                    selectedFlow = currentFlow;
-                    const targetStep = currentFlow.getStep(stepTarget);
-                    if (targetStep) {
-                        session = enterStep(session, targetStep.id, targetStep.description);
-                        selectedStep = targetStep;
-                    }
-                }
-            }
-        } else if (directive.complete) {
-            isFlowComplete = true;
-        } else if (directive.abort) {
-            // Abort — no flow, session cleared or marked
-            isFlowComplete = true;
-        } else if (directive.reset) {
-            if (session.currentFlow) {
-                const currentFlow = flows.find(f => f.id === session.currentFlow?.id);
-                if (currentFlow) {
-                    selectedFlow = currentFlow;
-                    const resetStep = typeof directive.reset === 'object' && directive.reset.step
-                        ? directive.reset.step
-                        : undefined;
-                    if (resetStep) {
-                        const targetStep = currentFlow.getStep(resetStep);
-                        if (targetStep) {
-                            session = enterStep(session, targetStep.id, targetStep.description);
-                            selectedStep = targetStep;
-                        }
-                    } else {
-                        const initialStep = currentFlow.initialStep;
-                        session = enterStep(session, initialStep.id, initialStep.description);
-                        selectedStep = initialStep;
-                    }
-                }
-            }
-        }
-
-        return {
-            selectedFlow,
-            selectedStep,
-            session,
-            isFlowComplete,
-            signalFirings: signalResult.firings,
-            signalPreDirective: signalResult.mergedDirective || undefined,
-        };
-    }
-}

package/src/core/SignalEvaluator.ts

@@ -1,404 +0,0 @@
-/**
- * SignalEvaluator — Batched AI classifier + extraction for signals.
- *
- * Handles:
- * - `evaluateIf`: code-first predicate evaluation (AND semantics, short-circuit)
- * - `evaluateSignals`: single batched provider call for detection + extraction
- * - `buildSignalClassifierPrompt` / `buildMergedSchema`: prompt & schema construction
- *
- * @module SignalEvaluator
- */
-
-import type { AiProvider } from "../types/ai.js";
-import type { Event } from "../types/history.js";
-import type { SessionState } from "../types/session.js";
-import type {
-    Signal,
-    SignalPredicate,
-    SignalPredicateContext,
-} from "../types/signals.js";
-import { eventsToHistory, logger } from "../utils/index.js";
-import { splitWhenConditions, evaluateIfPredicates } from "../utils/condition.js";
-
-// ──────────────────────────────────────────────────────────────────────────────
-// Types
-// ──────────────────────────────────────────────────────────────────────────────
-
-export interface SignalEvaluationResult {
-    matched: boolean;
-    reason?: string;
-    extracted?: unknown;
-}
-
-export interface EvaluateSignalsParams<TContext = unknown, TData = unknown> {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    signals: Signal<TContext, TData, any>[];
-    session: SessionState<TData>;
-    history: Event[];
-    context: TContext;
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// Prompt builder (exported for testing)
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Builds the classifier prompt for a batch of signals.
- *
- * Splits `when` entries with the shared ConditionWhen parser:
- * - Positive entries → "TRIGGER WHEN (ANY matches)"
- * - `!` entries → prefix stripped, "DO NOT TRIGGER WHEN (ANY inhibits)"
- *
- * Extraction schemas render under "WHEN MATCHED, EXTRACT".
- * Unconditional + extract signals render under "ALWAYS EXTRACT".
- */
-export function buildSignalClassifierPrompt<TContext = unknown, TData = unknown>(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    signals: Signal<TContext, TData, any>[],
-    history: Event[],
-    _context: TContext,
-): string {
-    const header = [
-        "You are evaluating signals for this conversation.",
-        "",
-        "For each signal, decide whether it matched based on the most recent user message AND the conversation context. Be conservative: only mark a signal matched when there is CLEAR, EXPLICIT evidence.",
-        "Positive TRIGGER WHEN entries are alternatives: ANY one positive entry can trigger the signal. DO NOT TRIGGER WHEN entries are exclusions: ANY one exclusion inhibits the signal.",
-    ].join("\n");
-
-    const signalBlocks: string[] = [];
-
-    for (const signal of signals) {
-        const id = signal.id ?? "unknown";
-        const title = signal.title ?? id;
-        const lines: string[] = [];
-
-        // Header
-        lines.push(`- SIGNAL "${id}" | "${title}"`);
-
-        // Description
-        if (signal.description) {
-            lines.push(`  DESCRIPTION: ${signal.description}`);
-        }
-
-        // Split when entries
-        const whenConditions = splitWhenConditions(signal.when);
-        const positiveEntries = whenConditions.positive;
-        const negativeEntries = whenConditions.negative;
-
-        const isUnconditional = positiveEntries.length === 0 && negativeEntries.length === 0;
-
-        if (isUnconditional && signal.extract) {
-            // Unconditional + extract → ALWAYS EXTRACT
-            lines.push(`  ALWAYS EXTRACT`);
-        } else if (positiveEntries.length > 0) {
-            lines.push(`  TRIGGER WHEN (ANY matches):`);
-            for (const entry of positiveEntries) {
-                lines.push(`    • ${entry}`);
-            }
-        } else if (negativeEntries.length > 0) {
-            lines.push(`  TRIGGER WHEN: no positive condition; trigger unless an exclusion matches.`);
-        }
-
-        if (negativeEntries.length > 0) {
-            lines.push(`  DO NOT TRIGGER WHEN (ANY inhibits):`);
-            for (const entry of negativeEntries) {
-                lines.push(`    • ${entry}`);
-            }
-        }
-
-        // Extraction schema
-        if (signal.extract) {
-            lines.push(`  WHEN MATCHED, EXTRACT:`);
-            const schemaLines = renderExtractionSchema(signal.extract);
-            for (const line of schemaLines) {
-                lines.push(`    • ${line}`);
-            }
-        }
-
-        signalBlocks.push(lines.join("\n"));
-    }
-
-    // Render conversation history
-    const historySection = renderHistoryForClassifier(history);
-
-    const outputInstructions = [
-        "# OUTPUT",
-        "For each signal, return:",
-        "  { id, matched, reason (required when matched=true) }",
-        "  + extracted fields (when signal defines extraction and matched=true)",
-    ].join("\n");
-
-    return [
-        header,
-        "",
-        "# SIGNALS",
-        "",
-        signalBlocks.join("\n\n"),
-        "",
-        historySection,
-        "",
-        outputInstructions,
-    ].join("\n");
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// Schema builder (exported for testing)
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Builds the merged JSON schema for the classifier response.
- *
- * Shape: `{ signals: [{ id, matched, reason?, extracted? }, ...] }`
- * where `extracted` is only present for signals with `extract` set.
- */
-export function buildMergedSchema<TContext = unknown, TData = unknown>(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    signals: Signal<TContext, TData, any>[],
-): Record<string, unknown> {
-    const signalEntrySchemas = signals.map(signal => {
-        const entry: Record<string, unknown> = {
-            type: "object",
-            properties: {
-                id: { type: "string", description: "Signal identifier" },
-                matched: { type: "boolean", description: "Whether the signal matched" },
-                reason: { type: "string", description: "Reason for the match (required when matched=true)" },
-            },
-            required: ["id", "matched"],
-            additionalProperties: false,
-        };
-
-        // Add extracted field only when signal has extract schema
-        if (signal.extract) {
-            (entry.properties as Record<string, unknown>).extracted = signal.extract;
-            entry.additionalProperties = false;
-        }
-
-        return entry;
-    });
-
-    return {
-        type: "object",
-        properties: {
-            signals: {
-                type: "array",
-                items: {
-                    anyOf: signalEntrySchemas,
-                },
-                description: "Evaluation results for each signal",
-            },
-        },
-        required: ["signals"],
-        additionalProperties: false,
-    };
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// SignalEvaluator class
-// ──────────────────────────────────────────────────────────────────────────────
-
-export class SignalEvaluator<TContext = unknown, TData = unknown> {
-    constructor(private readonly provider: AiProvider) { }
-
-    /**
-     * Code-first predicate evaluation with AND semantics and short-circuit.
-     *
-     * Normalizes predicates to an array. Awaits each; returns false on first
-     * falsy result. Catches throws/rejections, logs at ERROR with predicate
-     * index, and returns false (signal treated as non-match).
-     */
-    async evaluateIf(
-        predicates: SignalPredicate<TContext, TData> | SignalPredicate<TContext, TData>[],
-        ctx: SignalPredicateContext<TContext, TData>,
-    ): Promise<boolean> {
-        return evaluateIfPredicates<SignalPredicateContext<TContext, TData>>(
-            predicates, ctx, "Signals"
-        );
-    }
-
-    /**
-     * Batched AI classifier + extraction call (Algorithm 3).
-     *
-     * Builds the classifier prompt and merged schema, makes a single provider
-     * call, and parses the response into an id → result map. Any signal absent
-     * from the response defaults to `{ matched: false }`. Provider errors are
-     * caught and logged; all signals default to non-match.
-     */
-    async evaluateSignals(
-        params: EvaluateSignalsParams<TContext, TData>,
-    ): Promise<Record<string, SignalEvaluationResult>> {
-        const { signals, history, context } = params;
-
-        // Build prompt and schema
-        const prompt = buildSignalClassifierPrompt(signals, history, context);
-        const jsonSchema = buildMergedSchema(signals);
-
-        try {
-            const response = await this.provider.generateMessage<TContext, { signals: Array<{ id: string; matched: boolean; reason?: string; extracted?: unknown }> }>({
-                prompt,
-                history: eventsToHistory(history),
-                context,
-                parameters: {
-                    jsonSchema,
-                    schemaName: "signal_evaluation",
-                },
-            });
-
-            // Parse response into id → result map
-            const results: Record<string, SignalEvaluationResult> = {};
-            const entries = response.structured?.signals ?? [];
-
-            for (const entry of entries) {
-                results[entry.id] = {
-                    matched: entry.matched,
-                    reason: entry.matched ? entry.reason : undefined,
-                    extracted: entry.matched ? entry.extracted : undefined,
-                };
-            }
-
-            // Defensive defaults: any signal absent from the response → matched: false
-            for (const signal of signals) {
-                const id = signal.id ?? "unknown";
-                if (!results[id]) {
-                    results[id] = { matched: false };
-                }
-            }
-
-            return results;
-        } catch (error) {
-            logger.error(
-                `[Signals] Classifier call failed: ${error instanceof Error ? error.message : String(error)}`,
-            );
-
-            // On provider error, all signals default to non-match
-            const results: Record<string, SignalEvaluationResult> = {};
-            for (const signal of signals) {
-                const id = signal.id ?? "unknown";
-                results[id] = { matched: false };
-            }
-            return results;
-        }
-    }
-
-    /**
-     * Parallel batched evaluation. Splits signals into batches of `batchSize`,
-     * evaluates each batch via `evaluateSignals` in parallel using `Promise.all`,
-     * and merges all result maps into a single record.
-     *
-     * No key collisions because signal ids are unique within a phase.
-     */
-    async evaluateSignalsBatched(params: {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        signals: Signal<TContext, TData, any>[];
-        batchSize?: number;
-        session: SessionState<TData>;
-        history: Event[];
-        context: TContext;
-    }): Promise<Record<string, SignalEvaluationResult>> {
-        const { signals, batchSize = 10, session, history, context } = params;
-
-        if (signals.length === 0) return {};
-
-        const batches = splitIntoBatches(signals, batchSize);
-
-        const batchResults = await Promise.all(
-            batches.map(batch =>
-                this.evaluateSignals({ signals: batch, session, history, context }),
-            ),
-        );
-
-        // Merge all batch result maps into a single record
-        const merged: Record<string, SignalEvaluationResult> = {};
-        for (const result of batchResults) {
-            Object.assign(merged, result);
-        }
-        return merged;
-    }
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// Batch helper (exported for testing)
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Splits an array into fixed-size chunks.
- *
- * Returns an array of sub-arrays, each of at most `batchSize` elements.
- * The last chunk may be shorter. Returns an empty array when `items` is empty.
- */
-export function splitIntoBatches<T>(items: T[], batchSize: number): T[][] {
-    if (items.length === 0) return [];
-
-    const batches: T[][] = [];
-    for (let i = 0; i < items.length; i += batchSize) {
-        batches.push(items.slice(i, i + batchSize));
-    }
-    return batches;
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// Internal helpers
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Render extraction schema properties as human-readable lines for the prompt.
- * Lists each property's name, type, and constraints (enum, min/max, format).
- */
-function renderExtractionSchema(schema: Record<string, unknown>): string[] {
-    const lines: string[] = [];
-    const properties = schema.properties as Record<string, Record<string, unknown>> | undefined;
-
-    if (!properties) return lines;
-
-    for (const [name, fieldSchema] of Object.entries(properties)) {
-        if (!fieldSchema || typeof fieldSchema !== "object") continue;
-
-        const type = (fieldSchema.type as string) ?? "unknown";
-        let line = `${name} (${type})`;
-
-        // Add constraints
-        const constraints: string[] = [];
-
-        if (fieldSchema.enum && Array.isArray(fieldSchema.enum)) {
-            constraints.push((fieldSchema.enum as string[]).join("|"));
-        }
-        if (fieldSchema.minimum !== undefined || fieldSchema.maximum !== undefined) {
-            const min = fieldSchema.minimum !== undefined ? `${fieldSchema.minimum as number}` : "";
-            const max = fieldSchema.maximum !== undefined ? `${fieldSchema.maximum as number}` : "";
-            constraints.push(`${min}-${max}`);
-        }
-        if (fieldSchema.format) {
-            constraints.push(fieldSchema.format as string);
-        }
-
-        if (constraints.length > 0) {
-            line += `, ${constraints.join(", ")}`;
-        }
-
-        // Add description
-        if (fieldSchema.description) {
-            line += `: ${fieldSchema.description as string}`;
-        }
-
-        lines.push(line);
-    }
-
-    return lines;
-}
-
-/**
- * Render conversation history into a simple text block for the classifier prompt.
- */
-function renderHistoryForClassifier(history: Event[]): string {
-    if (history.length === 0) return "# CONVERSATION HISTORY\n(empty)";
-
-    const lines: string[] = ["# CONVERSATION HISTORY"];
-    for (const event of history) {
-        const source = event.source ?? "unknown";
-        const data = event.data as { message?: string } | undefined;
-        const message = data?.message ?? "";
-        if (message) {
-            lines.push(`${source}: ${message}`);
-        }
-    }
-    return lines.join("\n");
-}