@falai/agent 1.2.8 → 2.0.1

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

@@ -0,0 +1,152 @@
+/**
+ * SignalProcessor — Orchestration for signal phase execution.
+ *
+ * Owns:
+ * - `behaviorAllowsExecution`: Behavior gating (Algorithm 2)
+ * - `recordTrigger`: Immutable session update for trigger state
+ * - `buildSignalContext`: Constructs the handler context (D-Q12 writers)
+ * - `runPhase` / `runPreSignalPhase` / `runPostSignalPhase`: Phase orchestration (Algorithm 1)
+ *
+ * @module SignalProcessor
+ */
+import type { AiProvider } from "../types/ai";
+import type { Event } from "../types/history";
+import type { SessionState } from "../types/session";
+import type { PreDirective, Directive } from "../types/flow";
+import type { Signal, SignalContext, SignalDirective, SignalFiring, SignalTriggerState } from "../types/signals";
+import type { SignalEvaluator } from "./SignalEvaluator";
+/**
+ * Determines whether a signal's behavior gating allows execution this turn.
+ *
+ * Algorithm 2 from the design document:
+ * - `'always'` (or unset) → always allowed
+ * - `'once'` → allowed only if no prior trigger exists
+ * - `'cooldown'` → allowed when elapsed time since last trigger >= cooldownMs;
+ *   when `cooldownMs` is missing, treated as `'always'` (misconfigured)
+ * - Missing trigger (first-time) → allowed regardless of behavior
+ *
+ * Pure function; no I/O.
+ *
+ * @param signal - The signal definition (with id, behavior, cooldownMs)
+ * @param trigger - The existing trigger state from `session.signals.triggers[signal.id]`, or undefined
+ * @returns true if the signal is allowed to execute
+ *
+ * @requirements 5.1, 5.2, 5.3, 5.4
+ */
+export declare function behaviorAllowsExecution<TContext = unknown, TData = unknown>(signal: Signal<TContext, TData, any>, trigger: SignalTriggerState | undefined): boolean;
+/**
+ * Records a signal trigger on the session, returning a new session object
+ * (immutable update — never mutates input).
+ *
+ * - On first trigger: sets `firstTriggeredAt` and `lastTriggeredAt` to now,
+ *   `count = 1`, plus `lastReason` and `lastPhase`.
+ * - On subsequent triggers: leaves `firstTriggeredAt` unchanged, increments
+ *   `count`, updates `lastTriggeredAt`, `lastReason`, `lastPhase`.
+ *
+ * @param session - Current session state (not mutated)
+ * @param signal - The signal that fired
+ * @param reason - The match reason (AI rationale, 'code-only', or 'unconditional')
+ * @param phase - The phase in which the signal fired
+ * @returns A new session with updated `signals.triggers[signal.id]`
+ *
+ * @requirements 10.1, 10.2
+ */
+export declare function recordTrigger<TData = unknown>(session: SessionState<TData>, signal: Signal<any, TData, any>, reason: string, phase: 'pre' | 'post'): SessionState<TData>;
+/**
+ * Parameters for building the SignalContext.
+ */
+export interface BuildSignalContextParams<TContext = unknown, TData = unknown, TExtract = void> {
+    signal: Signal<TContext, TData, TExtract>;
+    reason: string;
+    extracted: TExtract extends void ? undefined : TExtract;
+    phase: 'pre' | 'post';
+    session: SessionState<TData>;
+    context: TContext;
+    history: Event[];
+    /** Turn-local directive bus — `dispatch` pushes onto this array. */
+    directiveBus: SignalDirective<TContext, TData>[];
+    /** Session updater — called when handler invokes `updateContext`. */
+    onUpdateSession: (updatedSession: SessionState<TData>) => void;
+}
+/**
+ * Builds the `SignalContext` passed to signal handlers.
+ *
+ * - `updateContext` and `updateData` replicate the ToolContext D-Q12 writer
+ *   pattern: shallow-merge partial updates into the session, call the
+ *   `onUpdateSession` callback so the processor can track mutations.
+ * - `dispatch` pushes a `SignalDirective` onto the turn-local bus.
+ * - `lastUserMessage` is derived from the last user-role event in history.
+ * - `triggeredAt` is set to `new Date()` at construction time.
+ * - `matched` is always `true` (literal type).
+ *
+ * @requirements 6.1, 6.2, 6.3
+ */
+export declare function buildSignalContext<TContext = unknown, TData = unknown, TExtract = void>(params: BuildSignalContextParams<TContext, TData, TExtract>): SignalContext<TContext, TData, TExtract>;
+/**
+ * SignalProcessor — Orchestrates signal phase execution.
+ *
+ * Constructed only when `options.signals` is non-empty (Requirement 2.3).
+ * Owns the full Algorithm 1 lifecycle: filtering, gating, evaluation,
+ * handler invocation, directive collection, and state persistence.
+ */
+export declare class SignalProcessor<TContext = unknown, TData = unknown> {
+    private readonly signals;
+    private readonly provider;
+    private readonly evaluator;
+    private readonly options;
+    constructor(signals: Signal<TContext, TData, any>[], provider: AiProvider, evaluator: SignalEvaluator<TContext, TData>, options: {
+        batchSize: number;
+    });
+    /** @internal Expose internals for testability. */
+    get _internals(): {
+        signals: Signal<TContext, TData, any>[];
+        provider: AiProvider;
+        evaluator: SignalEvaluator<TContext, TData>;
+        options: {
+            batchSize: number;
+        };
+    };
+    /**
+     * Pre-signal phase. Delegates to `runPhase('pre', ...)`.
+     * Return type narrows `mergedDirective` to `PreDirective | undefined`.
+     */
+    runPreSignalPhase(params: {
+        session: SessionState<TData>;
+        history: Event[];
+        context: TContext;
+    }): Promise<{
+        mergedDirective?: PreDirective<TContext, TData>;
+        firings: SignalFiring<TContext, TData>[];
+        updatedSession: SessionState<TData>;
+    }>;
+    /**
+     * Post-signal phase. Delegates to `runPhase('post', ...)`.
+     * Return type narrows `mergedDirective` to `Directive | undefined`.
+     * Pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`) are
+     * already dropped inside `runPhase` for the post phase.
+     */
+    runPostSignalPhase(params: {
+        session: SessionState<TData>;
+        history: Event[];
+        context: TContext;
+    }): Promise<{
+        mergedDirective?: Directive<TContext, TData>;
+        firings: SignalFiring<TContext, TData>[];
+        updatedSession: SessionState<TData>;
+    }>;
+    private runPhase;
+    /**
+     * Merges an array of signal directives into a single directive.
+     *
+     * Merge strategy (matches Algorithm 4 / AutoChainExecutor pattern):
+     * - Position fields (`goTo`, `goToStep`, `complete`, `abort`, `reset`, `halt`): last-write-wins
+     * - `reply`: last-write-wins
+     * - `appendPrompt`: array-concat
+     * - `injectTools`: array-concat
+     * - `dataUpdate`: shallow-merge (later values overwrite earlier for same key)
+     * - `contextUpdate`: shallow-merge
+     * - `stopOtherSignals`: OR (any true → true)
+     */
+    private mergeDirectives;
+}
+//# sourceMappingURL=SignalProcessor.d.ts.map

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

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