@falai/agent 1.2.7 → 2.0.0

package/src/core/DirectiveBus.ts

@@ -0,0 +1,248 @@
+/**
+ * DirectiveBus — per-turn collection mechanism for directives emitted by
+ * hooks, tools, and branches.
+ *
+ * Two phases per turn:
+ * 1. Pre-LLM: collects from `prepare` hooks and `onEnter` hooks.
+ * 2. Post-LLM: collects from `finalize`, tools via `executeToolCalls`,
+ *    branches via `evaluateBranches`.
+ *
+ * Each entry is stamped with an emitter ID for debug logging. At phase
+ * boundaries, the bus contents are merged using `flow.merge` and the
+ * result is returned via `drain()`.
+ *
+ * Algorithm 4: position precedence `abort > complete > goTo/goToStep > reset`,
+ * ties broken by emission order (last wins).
+ *
+ * **Validates: Requirements 1.3, 10.4, 10.5, 10.6**
+ */
+
+import type { Directive } from "../types/flow";
+import { flow } from "./flow-namespace";
+import { logger } from "../utils";
+
+/** Phase of the turn pipeline the bus is currently collecting for. */
+export type DirectiveBusPhase = "pre-llm" | "post-llm";
+
+/** A single entry on the bus, stamped with its emitter for debug logging. */
+export interface DirectiveBusEntry<TContext = unknown, TData = unknown> {
+    directive: Directive<TContext, TData>;
+    emitterId: string;
+    phase: DirectiveBusPhase;
+    /** Monotonically increasing emission index within the phase. */
+    order: number;
+}
+
+/**
+ * Per-turn directive collection bus.
+ *
+ * Usage:
+ * ```ts
+ * const bus = new DirectiveBus();
+ * bus.setPhase('pre-llm');
+ * bus.emit({ goTo: 'Booking' }, 'step.onEnter:ask_date');
+ * bus.emit({ appendPrompt: ['Be concise.'] }, 'step.prepare:ask_date');
+ * const merged = bus.drain(); // merges all collected directives
+ * bus.setPhase('post-llm');
+ * // ... collect post-LLM emissions ...
+ * const postMerged = bus.drain();
+ * ```
+ */
+export class DirectiveBus<TContext = unknown, TData = unknown> {
+    private entries: DirectiveBusEntry<TContext, TData>[] = [];
+    private currentPhase: DirectiveBusPhase = "pre-llm";
+    private orderCounter = 0;
+
+    /** Set the current collection phase. Resets the order counter for the new phase. */
+    setPhase(phase: DirectiveBusPhase): void {
+        this.currentPhase = phase;
+        // Order counter is NOT reset — emission order is global within the turn
+        // so that cross-phase comparisons (if ever needed) remain consistent.
+    }
+
+    /** Get the current phase. */
+    getPhase(): DirectiveBusPhase {
+        return this.currentPhase;
+    }
+
+    /**
+     * Emit a directive onto the bus.
+     *
+     * @param directive - The directive to collect.
+     * @param emitterId - Human-readable identifier of the emitter (for debug logging).
+     */
+    emit(directive: Directive<TContext, TData>, emitterId: string): void {
+        if (!directive || typeof directive !== "object" || Array.isArray(directive)) {
+            return; // Silently ignore non-object values (void returns from hooks)
+        }
+
+        // Check if the directive has any meaningful fields set
+        const hasFields = Object.keys(directive).some(
+            (k) => (directive as Record<string, unknown>)[k] !== undefined
+        );
+        if (!hasFields) {
+            return; // Empty directive — nothing to collect
+        }
+
+        this.entries.push({
+            directive,
+            emitterId,
+            phase: this.currentPhase,
+            order: this.orderCounter++,
+        });
+
+        logger.debug(
+            `[DirectiveBus] Collected directive from "${emitterId}" (phase=${this.currentPhase}, order=${this.orderCounter - 1})`
+        );
+    }
+
+    /**
+     * Drain the bus: merge all collected directives for the current phase
+     * using Algorithm 4 (position precedence, last-wins tie-breaking,
+     * shallow-merge for state writes).
+     *
+     * Returns `undefined` if no directives were collected.
+     * After draining, the entries for the current phase are cleared.
+     */
+    drain(): Directive<TContext, TData> | undefined {
+        const phaseEntries = this.entries.filter(
+            (e) => e.phase === this.currentPhase
+        );
+
+        if (phaseEntries.length === 0) {
+            return undefined;
+        }
+
+        // Log conflicts when multiple emitters set position or reply fields
+        this.logConflicts(phaseEntries);
+
+        // Merge all directives in emission order using flow.merge (pairwise reduction).
+        // flow.merge implements Algorithm 4: position precedence with last-wins tie-breaking.
+        let merged: Directive<TContext, TData> = phaseEntries[0].directive;
+        for (let i = 1; i < phaseEntries.length; i++) {
+            merged = flow.merge(merged, phaseEntries[i].directive);
+        }
+
+        // Strip pre-LLM-only fields from post-LLM phase emissions
+        if (this.currentPhase === "post-llm") {
+            const asAny = merged as Record<string, unknown>;
+            const preLlmFields = ["appendPrompt", "injectTools", "halt"] as const;
+
+            // Identify which fields are present BEFORE stripping (the merge may
+            // alias phaseEntries[0].directive when there is a single emitter, so
+            // we must collect emitter names first).
+            const droppedFields: string[] = [];
+            for (const f of preLlmFields) {
+                if (asAny[f] !== undefined) {
+                    droppedFields.push(f);
+                }
+            }
+
+            if (droppedFields.length > 0) {
+                // Identify emitters that contributed the dropped fields.
+                const emitters = phaseEntries
+                    .filter((e) => {
+                        const d = e.directive as Record<string, unknown>;
+                        return droppedFields.some((f) => d[f] !== undefined);
+                    })
+                    .map((e) => e.emitterId);
+
+                // Now strip the fields from the merged result.
+                for (const f of droppedFields) {
+                    delete asAny[f];
+                }
+
+                logger.debug(
+                    `[DirectiveBus] Dropped pre-LLM-only fields [${droppedFields.join(", ")}] from post-LLM emitters: ${emitters.join(", ")}`
+                );
+            }
+        }
+
+        // Clear entries for the drained phase
+        this.entries = this.entries.filter((e) => e.phase !== this.currentPhase);
+
+        return merged;
+    }
+
+    /**
+     * Drain ALL entries regardless of phase. Used for final turn cleanup.
+     * Returns `undefined` if no directives were collected.
+     */
+    drainAll(): Directive<TContext, TData> | undefined {
+        if (this.entries.length === 0) {
+            return undefined;
+        }
+
+        this.logConflicts(this.entries);
+
+        let merged: Directive<TContext, TData> = this.entries[0].directive;
+        for (let i = 1; i < this.entries.length; i++) {
+            merged = flow.merge(merged, this.entries[i].directive);
+        }
+
+        this.entries = [];
+        return merged;
+    }
+
+    /** Clear all collected entries and reset the bus for a new turn. */
+    clear(): void {
+        this.entries = [];
+        this.orderCounter = 0;
+        this.currentPhase = "pre-llm";
+    }
+
+    /** Get the number of entries currently on the bus. */
+    get size(): number {
+        return this.entries.length;
+    }
+
+    /** Get all entries (for inspection/testing). */
+    getEntries(): ReadonlyArray<DirectiveBusEntry<TContext, TData>> {
+        return this.entries;
+    }
+
+    /** Check if the bus has any entries for the current phase. */
+    hasEntries(): boolean {
+        return this.entries.some((e) => e.phase === this.currentPhase);
+    }
+
+    // ─── Private helpers ─────────────────────────────────────────────────────
+
+    /**
+     * Log debug-level conflict warnings when multiple emitters set position
+     * fields or reply fields in the same phase.
+     */
+    private logConflicts(
+        entries: DirectiveBusEntry<TContext, TData>[]
+    ): void {
+        // Check for position field conflicts
+        const positionEmitters: Array<{ emitterId: string; field: string }> = [];
+        for (const entry of entries) {
+            const d = entry.directive as Record<string, unknown>;
+            for (const field of ["abort", "complete", "goTo", "goToStep", "reset"]) {
+                if (d[field] !== undefined) {
+                    positionEmitters.push({ emitterId: entry.emitterId, field });
+                }
+            }
+        }
+        if (positionEmitters.length > 1) {
+            const details = positionEmitters
+                .map((e) => `${e.emitterId}(${e.field})`)
+                .join(", ");
+            logger.debug(
+                `[DirectiveBus] Multiple position fields in one turn — conflict resolution applied. Emitters: ${details}`
+            );
+        }
+
+        // Check for reply conflicts
+        const replyEmitters = entries.filter(
+            (e) => (e.directive as Record<string, unknown>).reply !== undefined
+        );
+        if (replyEmitters.length > 1) {
+            const emitterIds = replyEmitters.map((e) => e.emitterId).join(", ");
+            logger.debug(
+                `[DirectiveBus] Multiple reply fields in one turn — using last emission. Emitters: ${emitterIds}`
+            );
+        }
+    }
+}

package/src/core/DirectiveChainTracker.ts

@@ -0,0 +1,144 @@
+/**
+ * Per-turn directive chain depth tracker.
+ *
+ * When directives chain (e.g., tool emits goTo → flow.onEnter emits goTo →
+ * flow.onComplete emits complete.next → …), the chain can theoretically loop
+ * forever. This tracker counts each directive application within a single turn
+ * and throws `FlowConfigurationError` when the configured cap is exceeded.
+ *
+ * Chain breakers (`abort` mid-chain) stop counting and apply the
+ * chain-terminating directive immediately.
+ *
+ * Validates: Requirements 22.1, 22.2, 22.3
+ */
+
+import { FlowConfigurationError } from "./Step";
+import { logger } from "../utils";
+import type { Directive } from "../types/flow";
+
+/**
+ * Entry in the directive chain log — records what was emitted and by whom.
+ */
+export interface DirectiveChainEntry {
+    /** Human-readable description of the directive (e.g., "goTo:Booking", "complete", "abort:timeout") */
+    description: string;
+    /** Identifier of the emitter (e.g., "tool:lookup_order", "hook:onEnter", "pending") */
+    emitter: string;
+}
+
+/**
+ * Tracks directive chain depth within a single turn.
+ * Create one instance per turn; discard at turn end.
+ */
+export class DirectiveChainTracker {
+    private chain: DirectiveChainEntry[] = [];
+    private readonly maxDepth: number;
+
+    constructor(maxDirectiveChain: number) {
+        this.maxDepth = maxDirectiveChain;
+    }
+
+    /**
+     * Record a directive application in the chain.
+     * Throws `FlowConfigurationError` if the chain exceeds `maxDirectiveChain`.
+     *
+     * @param directive - The directive being applied
+     * @param emitter - Identifier of the emitter (for diagnostics)
+     * @returns `true` if the directive is a chain breaker (abort) — caller should
+     *          apply it and stop the chain without further counting.
+     */
+    record(directive: Directive, emitter: string): boolean {
+        const description = describeDirective(directive);
+
+        // Check if this is a chain breaker (abort)
+        if (directive.abort !== undefined) {
+            this.chain.push({ description, emitter });
+            logger.debug(
+                `[DirectiveChainTracker] Chain breaker (abort) at depth ${this.chain.length}: ${description} from ${emitter}`
+            );
+            return true; // Chain breaker — apply and stop
+        }
+
+        this.chain.push({ description, emitter });
+
+        if (this.chain.length > this.maxDepth) {
+            const chainDescription = this.chain
+                .map((entry, i) => `  ${i + 1}. ${entry.description} (from: ${entry.emitter})`)
+                .join("\n");
+
+            throw new FlowConfigurationError(
+                `[FlowConfigurationError] Directive chain cycle detected: ` +
+                `chain depth (${this.chain.length}) exceeded maxDirectiveChain (${this.maxDepth}). ` +
+                `Review flow hooks and tool handlers for circular redirections.\n` +
+                `Chain (in emission order):\n${chainDescription}`
+            );
+        }
+
+        logger.debug(
+            `[DirectiveChainTracker] Chain depth ${this.chain.length}/${this.maxDepth}: ${description} from ${emitter}`
+        );
+
+        return false; // Not a chain breaker — continue normally
+    }
+
+    /** Current chain depth. */
+    get depth(): number {
+        return this.chain.length;
+    }
+
+    /** The full chain log (read-only). */
+    get entries(): ReadonlyArray<DirectiveChainEntry> {
+        return this.chain;
+    }
+
+    /** Reset the tracker (e.g., for testing or if the turn is restarted). */
+    reset(): void {
+        this.chain = [];
+    }
+}
+
+/**
+ * Produce a human-readable one-line description of a directive for diagnostics.
+ */
+function describeDirective(directive: Directive): string {
+    if (directive.abort !== undefined) {
+        const reason = typeof directive.abort === "string"
+            ? directive.abort
+            : typeof directive.abort === "object"
+                ? directive.abort.reason
+                : "";
+        return `abort${reason ? `:${reason}` : ""}`;
+    }
+    if (directive.goTo !== undefined) {
+        const target = typeof directive.goTo === "string"
+            ? directive.goTo
+            : typeof directive.goTo === "object"
+                ? directive.goTo.flow ?? "(no flow)"
+                : "";
+        return `goTo:${target}`;
+    }
+    if (directive.goToStep !== undefined) {
+        const target = typeof directive.goToStep === "string"
+            ? directive.goToStep
+            : typeof directive.goToStep === "object"
+                ? directive.goToStep.step
+                : "";
+        return `goToStep:${target}`;
+    }
+    if (directive.complete !== undefined) {
+        if (directive.complete === true) return "complete";
+        if (typeof directive.complete === "object" && directive.complete.next) {
+            return "complete(chained)";
+        }
+        return "complete";
+    }
+    if (directive.reset !== undefined) {
+        return "reset";
+    }
+    // State-only or reply-only directive
+    const parts: string[] = [];
+    if (directive.reply) parts.push("reply");
+    if (directive.dataUpdate) parts.push("dataUpdate");
+    if (directive.contextUpdate) parts.push("contextUpdate");
+    return parts.length > 0 ? parts.join("+") : "(empty)";
+}