@falai/agent 2.2.2 → 2.2.4

package/dist/types/signals.d.ts

@@ -14,15 +14,15 @@ import type { Event } from "./history";
  * Shape is locked to enable forward-compatible persistence in v2.0.
  */
 export interface SignalTriggerState {
-    /** When this signal first fired. */
+    /** When this signal first completed its handler successfully. */
     firstTriggeredAt: Date;
-    /** When this signal last fired. */
+    /** When this signal last completed its handler successfully. */
     lastTriggeredAt: Date;
-    /** Total number of times this signal has fired. */
+    /** Total number of successful handler completions for this signal. */
     count: number;
-    /** Free-text reason from the last trigger (if the signal supplied one). */
+    /** Free-text reason from the last successful trigger (if supplied). */
     lastReason?: string;
-    /** Which phase the signal last fired in. */
+    /** Which phase the signal last completed in. */
     lastPhase?: 'pre' | 'post';
 }
 /**
@@ -146,9 +146,9 @@ export interface SignalContext<TContext = unknown, TData = unknown, TExtract = v
  * Conditions use the v2 `when` / `if` split:
  * - `when`: AI-evaluated string(s). Entries prefixed with `!` are exclusion
  *   conditions rendered under "DO NOT TRIGGER WHEN" in the classifier prompt.
- *   Non-prefixed entries render under "TRIGGER WHEN". Positive entries use AND
- *   semantics (all must match). Negative entries use OR semantics (any match
- *   inhibits firing).
+ *   Non-prefixed entries render under "TRIGGER WHEN". Positive entries use OR
+ *   semantics (any match can trigger). Negative entries also use OR semantics
+ *   for exclusion (any match inhibits firing).
  * - `if`: Code-evaluated function(s). Free. AND semantics.
  *
  * When both `if` and `when` are set, `if` evaluates first. If `if` returns
@@ -167,7 +167,7 @@ export interface Signal<TContext = unknown, TData = unknown, TExtract = void> {
     description?: string;
     /**
      * AI-evaluated trigger condition(s). String or array of strings.
-     * - Non-prefixed entries: AND semantics. All must match to trigger.
+     * - Non-prefixed entries: OR semantics. Any match can trigger.
      * - `!`-prefixed entries: OR exclusion. Any match inhibits firing.
      *
      * At prompt-render time, the framework splits entries by prefix:

package/dist/types/signals.d.ts.map

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

package/docs/guides/streaming.md

@@ -36,7 +36,7 @@ interface AgentResponseStreamChunk<TData> {
 }
 ```
 
-`delta` is the new token(s); concatenating every `delta` reproduces the final reply. `accumulated` is the running total — useful when your renderer needs the full string each tick (e.g., a Markdown view that re-parses on every update). `done` flips to `true` exactly once, on the terminal chunk.
+`delta` is the new token(s); concatenating every `delta` reproduces the final reply unless a post-phase signal replaces the message on the terminal chunk. `accumulated` is the authoritative running total — useful when your renderer needs the full string each tick (e.g., a Markdown view that re-parses on every update). `done` flips to `true` exactly once, on the terminal chunk.
 
 ## Render incrementally
 

package/docs/reference/signals.md

@@ -130,7 +130,7 @@ interface AgentOptions<TContext, TData> {
 | `id` | `string` | no | auto-generated | Stable identifier within a session. Used for `SignalsState.triggers` keying and on `SignalFiring`. Must be unique across the agent's signals. |
 | `title` | `string` | no | — | Display title shown in logs and traces. |
 | `description` | `string` | no | — | Free-text description; rendered into the classifier prompt. |
-| `when` | `string \| string[]` | no | — | AI-evaluated condition(s). Entries prefixed with `!` are exclusion conditions rendered under "DO NOT TRIGGER WHEN" (OR semantics — any match inhibits firing). Non-prefixed entries render under "TRIGGER WHEN" (AND semantics — all must match). |
+| `when` | `string \| string[]` | no | — | AI-evaluated condition(s). Non-prefixed entries render under "TRIGGER WHEN" (OR semantics — any match can trigger). Entries prefixed with `!` are exclusion conditions rendered under "DO NOT TRIGGER WHEN" (OR semantics — any match inhibits firing). |
 | `if` | `SignalPredicate \| SignalPredicate[]` | no | — | Code predicate(s). AND semantics. Free to evaluate. Runs before `when`; if any returns `false`, `when` is skipped (no token cost). |
 | `extract` | `SignalSchema<TExtract>` | no | — | When set, the signal operates in extraction mode. JSON Schema object describing the per-signal `extracted` field merged into the classifier response. The `TExtract` generic carries the resulting type onto `ctx.extracted`. |
 | `phase` | `'pre' \| 'post' \| 'both'` | yes | — | When the signal evaluates. `'pre'` runs in parallel with routing. `'post'` runs after the LLM call, before persistence. `'both'` evaluates in both phases. |
@@ -207,11 +207,13 @@ Persisted on `session.signals`. Adapters preserve this shape bit-identical.
 
 | `SignalTriggerState` field | Type | Notes |
 |----------------------------|------|-------|
-| `firstTriggeredAt` | `Date` | When this signal first fired in the session. Never updated on subsequent fires. |
-| `lastTriggeredAt` | `Date` | When this signal last fired. Drives `cooldown` arithmetic. |
-| `count` | `number` | Total fires for this signal in this session. Monotonically increasing. |
-| `lastReason` | `string \| undefined` | The `reason` from the most recent firing. |
-| `lastPhase` | `'pre' \| 'post' \| undefined` | The phase of the most recent firing. |
+| `firstTriggeredAt` | `Date` | When this signal first completed its handler successfully in the session. Never updated on subsequent successful triggers. |
+| `lastTriggeredAt` | `Date` | When this signal last completed its handler successfully. Drives `cooldown` arithmetic. |
+| `count` | `number` | Total successful handler completions for this signal in this session. Monotonically increasing. |
+| `lastReason` | `string \| undefined` | The `reason` from the most recent successful trigger. |
+| `lastPhase` | `'pre' \| 'post' \| undefined` | The phase of the most recent successful trigger. |
+
+Handler errors are still surfaced on `SignalFiring.handlerError`, but they do not update `SignalsState.triggers`. A `behavior: 'once'` or cooldown signal can therefore retry after an app-side handler failure.
 
 ### `signalBatchSize`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/ResponseModal.ts

@@ -370,6 +370,18 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         return this.agent.tool;
     }
 
+    /**
+     * Post-phase signal replies replace the user-visible message after the
+     * response has otherwise completed. Undefined means "leave it unchanged";
+     * an empty string is an explicit replacement.
+     */
+    private applyPostSignalReply(
+        message: string,
+        directive: Directive<TContext, TData> | undefined,
+    ): string {
+        return directive?.reply !== undefined ? directive.reply : message;
+    }
+
     /**
      * Collect scoped instructions from agent, flow, and step into a ScopedInstructions value.
      * @private
@@ -1112,14 +1124,16 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 session = { ...session, pendingDirective: postResult.mergedDirective };
             }
 
+            const message = this.applyPostSignalReply(haltMessage, postResult.mergedDirective);
+
             await this.finalizeSession(session, effectiveContext);
             return {
-                message: haltMessage,
+                message,
                 session,
                 toolCalls: undefined,
                 isFlowComplete: false,
                 executedSteps: [],
-                stoppedReason: signalHaltReply ? 'reply' : 'halt',
+                stoppedReason: haltMessage ? 'reply' : 'halt',
                 triggeredSignals: signalFirings.length > 0 ? signalFirings as unknown as SignalFiring<unknown, TData>[] : undefined,
             };
         }
@@ -1287,6 +1301,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             session = { ...session, pendingDirective: postResult.mergedDirective };
         }
 
+        message = this.applyPostSignalReply(message, postResult.mergedDirective);
+
         // Ensure response structure completeness (Requirement 8.1, 8.2, 8.3)
         // - executedSteps: array of steps executed (empty array if none)
         // - stoppedReason: why execution stopped (undefined for fallback)
@@ -1634,10 +1650,12 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 session = { ...session, pendingDirective: postResult.mergedDirective };
             }
 
+            const message = this.applyPostSignalReply(haltMessage, postResult.mergedDirective);
+
             await this.finalizeSession(session, effectiveContext);
             yield {
-                delta: haltMessage,
-                accumulated: haltMessage,
+                delta: message,
+                accumulated: message,
                 done: true,
                 session,
                 stoppedReason: haltMessage ? 'reply' : 'halt',
@@ -1767,8 +1785,15 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     finalSession = { ...finalSession, pendingDirective: postResult.mergedDirective };
                 }
 
+                const accumulated = this.applyPostSignalReply(chunk.accumulated, postResult.mergedDirective);
+                const delta = postResult.mergedDirective?.reply !== undefined
+                    ? accumulated
+                    : chunk.delta;
+
                 yield {
                     ...chunk,
+                    delta,
+                    accumulated,
                     session: finalSession,
                     triggeredSignals: signalFirings.length > 0 ? signalFirings as unknown as SignalFiring<unknown, TData>[] : undefined,
                 } as AgentResponseStreamChunk<TData>;
@@ -2880,4 +2905,4 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         }
     }
 
-}
+}

package/src/core/SignalEvaluator.ts

@@ -45,7 +45,7 @@ export interface EvaluateSignalsParams<TContext = unknown, TData = unknown> {
  * Builds the classifier prompt for a batch of signals.
  *
  * Splits `when` entries by `!` prefix at render time:
- * - Non-`!` → "TRIGGER WHEN (ALL must match)"
+ * - Non-`!` → "TRIGGER WHEN (ANY matches)"
  * - `!` entries → prefix stripped, "DO NOT TRIGGER WHEN (ANY inhibits)"
  *
  * Extraction schemas render under "WHEN MATCHED, EXTRACT".
@@ -61,6 +61,7 @@ export function buildSignalClassifierPrompt<TContext = unknown, TData = unknown>
         "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[] = [];
@@ -89,7 +90,7 @@ export function buildSignalClassifierPrompt<TContext = unknown, TData = unknown>
             // Unconditional + extract → ALWAYS EXTRACT
             lines.push(`  ALWAYS EXTRACT`);
         } else if (positiveEntries.length > 0) {
-            lines.push(`  TRIGGER WHEN (ALL must match):`);
+            lines.push(`  TRIGGER WHEN (ANY matches):`);
             for (const entry of positiveEntries) {
                 lines.push(`    • ${entry}`);
             }

package/src/core/SignalProcessor.ts

@@ -533,7 +533,7 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
                     bus.push(resolvedDirective);
                 }
 
-                // Update session via recordTrigger
+                // Record trigger only after the handler has completed successfully.
                 updatedSession = recordTrigger(updatedSession, m.signal, m.reason, phase);
 
                 const handlerDurationMs = performance.now() - start;
@@ -568,9 +568,6 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
                 // Handler errors logged at ERROR regardless of debug flag (Requirement 13.2)
                 logger.error(`[Signals] Handler threw for signal "${m.signal.id ?? 'unknown'}": ${errorMessage}`);
 
-                // Still record trigger even on error (the signal matched)
-                updatedSession = recordTrigger(updatedSession, m.signal, m.reason, phase);
-
                 firings.push({
                     id: m.signal.id ?? 'unknown',
                     phase,

package/src/index.ts

@@ -183,4 +183,4 @@ export type {
   ConditionWhen,
 } from "./types";
 export { EventKind, MessageRole } from "./types";
-export { createSession, createSessionId, enterFlow, enterStep, completeCurrentFlow, isFlowCompletedThisSession, mergeCollected } from "./utils";
+export { createSession, createSessionId, createPersistedState, enterFlow, enterStep, completeCurrentFlow, isFlowCompletedThisSession, mergeCollected } from "./utils";

package/src/types/signals.ts

@@ -20,15 +20,15 @@ import type { Event } from "./history";
  * Shape is locked to enable forward-compatible persistence in v2.0.
  */
 export interface SignalTriggerState {
-    /** When this signal first fired. */
+    /** When this signal first completed its handler successfully. */
     firstTriggeredAt: Date;
-    /** When this signal last fired. */
+    /** When this signal last completed its handler successfully. */
     lastTriggeredAt: Date;
-    /** Total number of times this signal has fired. */
+    /** Total number of successful handler completions for this signal. */
     count: number;
-    /** Free-text reason from the last trigger (if the signal supplied one). */
+    /** Free-text reason from the last successful trigger (if supplied). */
     lastReason?: string;
-    /** Which phase the signal last fired in. */
+    /** Which phase the signal last completed in. */
     lastPhase?: 'pre' | 'post';
 }
 
@@ -197,9 +197,9 @@ export interface SignalContext<
  * Conditions use the v2 `when` / `if` split:
  * - `when`: AI-evaluated string(s). Entries prefixed with `!` are exclusion
  *   conditions rendered under "DO NOT TRIGGER WHEN" in the classifier prompt.
- *   Non-prefixed entries render under "TRIGGER WHEN". Positive entries use AND
- *   semantics (all must match). Negative entries use OR semantics (any match
- *   inhibits firing).
+ *   Non-prefixed entries render under "TRIGGER WHEN". Positive entries use OR
+ *   semantics (any match can trigger). Negative entries also use OR semantics
+ *   for exclusion (any match inhibits firing).
  * - `if`: Code-evaluated function(s). Free. AND semantics.
  *
  * When both `if` and `when` are set, `if` evaluates first. If `if` returns
@@ -225,7 +225,7 @@ export interface Signal<
 
     /**
      * AI-evaluated trigger condition(s). String or array of strings.
-     * - Non-prefixed entries: AND semantics. All must match to trigger.
+     * - Non-prefixed entries: OR semantics. Any match can trigger.
      * - `!`-prefixed entries: OR exclusion. Any match inhibits firing.
      *
      * At prompt-render time, the framework splits entries by prefix: