@falai/agent 1.2.7 → 2.0.0

package/src/utils/condition.ts

@@ -1,14 +1,23 @@
-import type { TemplateContext, ConditionTemplate, ConditionEvaluationResult } from "../types/template";
+import type { TemplateContext, ConditionEvaluationResult } from "../types/template";
 import { createTemplateContext } from "./template";
 import { logger } from './logger'
 
+/**
+ * Condition template — kept as a private type for internal use by the evaluator.
+ * Removed from the public surface in v2.
+ */
+type ConditionTemplate<TContext = unknown, TData = unknown> =
+  | string
+  | ((params: TemplateContext<TContext, TData>) => boolean | Promise<boolean>)
+  | ConditionTemplate<TContext, TData>[];
+
 /**
  * Utility class for evaluating ConditionTemplate instances.
  * Handles mixed string/function conditions and separates programmatic
  * evaluation from AI context collection.
  */
 export class ConditionEvaluator<TContext = unknown, TData = unknown> {
-  constructor(private templateContext: TemplateContext<TContext, TData>) {}
+  constructor(private templateContext: TemplateContext<TContext, TData>) { }
 
   /**
    * Evaluates a condition template and returns both programmatic results
@@ -102,10 +111,10 @@ export class ConditionEvaluator<TContext = unknown, TData = unknown> {
 
     for (const condition of conditions) {
       const conditionResult = await this.evaluateCondition(condition, logic);
-      
+
       // Collect AI context strings
       result.aiContextStrings.push(...conditionResult.aiContextStrings);
-      
+
       // Track if we have programmatic conditions
       if (conditionResult.hasProgrammaticConditions) {
         result.hasProgrammaticConditions = true;

package/src/utils/id.ts

@@ -25,32 +25,32 @@ function sanitize(str: string): string {
 }
 
 /**
- * Generate a deterministic route ID
- * Format: route_{sanitized_title}_{hash}
+ * Generate a deterministic flow ID
+ * Format: flow_{sanitized_title}_{hash}
  */
-export function generateRouteId(title: string): string {
+export function generateFlowId(title: string): string {
   const sanitized = sanitize(title);
   const hash = simpleHash(title);
-  return `route_${sanitized}_${hash}`;
+  return `flow_${sanitized}_${hash}`;
 }
 
 /**
  * Generate a deterministic step ID
- * Format: step_{sanitized_description}_{hash} or step_{routeId}_{index}
+ * Format: step_{sanitized_description}_{hash} or step_{flowId}_{index}
  */
 export function generateStepId(
-  routeId: string,
+  flowId: string,
   description?: string,
   index?: number
 ): string {
   if (description) {
     const sanitized = sanitize(description);
-    const hash = simpleHash(`${routeId}_${description}`);
+    const hash = simpleHash(`${flowId}_${description}`);
     return `step_${sanitized}_${hash}`;
   }
   // Fallback for steps without descriptions
-  const suffix = index !== undefined ? index : simpleHash(routeId);
-  return `step_${routeId}_${suffix}`;
+  const suffix = index !== undefined ? index : simpleHash(flowId);
+  return `step_${flowId}_${suffix}`;
 }
 
 /**
@@ -71,3 +71,21 @@ export function generateInlineToolId(stepId: string): string {
   const hash = simpleHash(`${stepId}_inline_tool`);
   return `tool_inline_${stepId}_${hash}`;
 }
+
+/**
+ * Generate a deterministic signal ID.
+ * Format: signal_{sanitized}_{hash}
+ *
+ * Uses a combination of the signal's title/description/index to produce
+ * a stable id that is deterministic within a session (same inputs → same id).
+ */
+export function generateSignalId(
+  title?: string,
+  description?: string,
+  index?: number
+): string {
+  const seed = title || description || `signal_${index ?? 0}`;
+  const sanitized = sanitize(seed);
+  const hash = simpleHash(`signal_${seed}_${index ?? 0}`);
+  return `signal_${sanitized}_${hash}`;
+}

package/src/utils/index.ts

@@ -4,18 +4,22 @@
 
 // ID generation
 export {
-  generateRouteId,
+  generateFlowId,
   generateStepId,
   generateToolId,
   generateInlineToolId,
+  generateSignalId,
 } from "./id";
 
 // Session management
 export {
   createSession,
   createSessionId,
-  enterRoute,
+  createPersistedState,
+  enterFlow,
   enterStep,
+  completeCurrentFlow,
+  isFlowCompletedThisSession,
   mergeCollected,
   sessionStepToData,
   sessionDataToStep,

package/src/utils/session.ts

@@ -1,6 +1,8 @@
 import { cloneDeep } from "./clone";
 import type { SessionState } from "../types/session";
+import type { Directive } from "../types/flow";
 import type { CollectedStateData } from "../types/persistence";
+import { logger } from "./logger";
 
 /**
  * Helper to create a new session
@@ -34,10 +36,11 @@ export function createSession<TData = Record<string, unknown>>(
     return {
       id,
       data: state.data ?? ({} as Partial<TData>),
-      routeHistory: state.routeHistory ?? [],
-      currentRoute: state.currentRoute,
+      flowHistory: state.flowHistory ?? [],
+      currentFlow: state.currentFlow,
       currentStep: state.currentStep,
-      pendingTransition: state.pendingTransition,
+      pendingDirective: state.pendingDirective,
+      signals: state.signals,
       history: state.history,
       metadata: {
         createdAt: now,
@@ -55,7 +58,7 @@ export function createSession<TData = Record<string, unknown>>(
   return {
     id,
     data: {} as Partial<TData>,
-    routeHistory: [],
+    flowHistory: [],
     metadata: {
       ...metadata,
       createdAt: new Date(),
@@ -80,40 +83,40 @@ export function cloneSession<TData>(
 }
 
 /**
- * Helper to update session with new route
- * With agent-level data, routes share the same data structure
+ * Helper to update session with new flow
+ * With agent-level data, flows share the same data structure
  */
-export function enterRoute<TData = Record<string, unknown>>(
+export function enterFlow<TData = Record<string, unknown>>(
   session: SessionState<TData>,
-  routeId: string,
-  routeTitle: string
+  flowId: string,
+  flowTitle: string
 ): SessionState<TData> {
-  // Exit current route if exists
-  const routeHistory = [...(session.routeHistory || [])];
-  if (session.currentRoute) {
-    const lastRouteIndex = routeHistory.findIndex(
-      (r) => r.routeId === session.currentRoute?.id && !r.exitedAt
+  // Exit current flow if exists
+  const flowHistory = [...(session.flowHistory || [])];
+  if (session.currentFlow) {
+    const lastFlowIndex = flowHistory.findIndex(
+      (r) => r.flowId === session.currentFlow?.id && !r.exitedAt
     );
-    if (lastRouteIndex >= 0) {
-      routeHistory[lastRouteIndex].exitedAt = new Date();
+    if (lastFlowIndex >= 0) {
+      flowHistory[lastFlowIndex].exitedAt = new Date();
     }
   }
 
-  // Enter new route - data persists across routes at agent level
+  // Enter new flow - data persists across flows at agent level
   const now = new Date();
   return {
     ...session,
-    currentRoute: {
-      id: routeId,
-      title: routeTitle,
+    currentFlow: {
+      id: flowId,
+      title: flowTitle,
       enteredAt: now,
     },
     currentStep: undefined,
-    // data remains the same - shared across all routes
-    routeHistory: [
-      ...routeHistory,
+    // data remains the same - shared across all flows
+    flowHistory: [
+      ...flowHistory,
       {
-        routeId,
+        flowId: flowId,
         enteredAt: now,
         completed: false,
       },
@@ -147,6 +150,84 @@ export function enterStep<TData = Record<string, unknown>>(
   };
 }
 
+/**
+ * Helper to release the session to idle state on flow completion.
+ *
+ * Marks the active flow's `flowHistory` entry as completed (sets
+ * `completed: true` and `exitedAt: <now>`), clears `currentFlow` and
+ * `currentStep`, and (when `clearOwnedFields` is provided) removes those
+ * fields from `session.data` to support `flow.reentrant` re-entry.
+ *
+ * Does **not** generate any message, copy, or LLM call. The framework
+ * speaks no text of its own at the completion boundary — the developer
+ * controls every word emitted to the user via flow steps.
+ */
+export function completeCurrentFlow<TData = Record<string, unknown>>(
+  session: SessionState<TData>,
+  options?: { clearOwnedFields?: ReadonlyArray<keyof TData> }
+): SessionState<TData> {
+  const now = new Date();
+  const flowHistory = [...(session.flowHistory || [])];
+
+  if (session.currentFlow) {
+    const lastFlowIndex = flowHistory.findIndex(
+      (entry) => entry.flowId === session.currentFlow?.id && !entry.exitedAt
+    );
+    if (lastFlowIndex >= 0) {
+      flowHistory[lastFlowIndex] = {
+        ...flowHistory[lastFlowIndex],
+        exitedAt: now,
+        completed: true,
+      };
+    }
+  }
+
+  let nextData = session.data;
+  if (options?.clearOwnedFields && options.clearOwnedFields.length > 0) {
+    const owned = new Set<keyof TData>(options.clearOwnedFields);
+    const filtered: Partial<TData> = {};
+    for (const key of Object.keys(session.data ?? {}) as (keyof TData)[]) {
+      if (!owned.has(key)) {
+        (filtered as Record<keyof TData, unknown>)[key] =
+          (session.data as Record<keyof TData, unknown>)[key];
+      }
+    }
+    nextData = filtered;
+  }
+
+  return {
+    ...session,
+    currentFlow: undefined,
+    currentStep: undefined,
+    flowHistory,
+    data: nextData,
+    metadata: {
+      ...session.metadata,
+      lastUpdatedAt: now,
+    },
+  };
+}
+
+/**
+ * Returns true when the given flow id has a most-recent `flowHistory`
+ * entry marked as completed within this session. Used by the router to
+ * exclude completed flows from candidate scoring (unless the flow is
+ * `reentrant`).
+ */
+export function isFlowCompletedThisSession<TData = Record<string, unknown>>(
+  session: SessionState<TData>,
+  flowId: string
+): boolean {
+  const history = session.flowHistory ?? [];
+  for (let i = history.length - 1; i >= 0; i--) {
+    const entry = history[i];
+    if (entry.flowId === flowId) {
+      return entry.completed === true;
+    }
+  }
+  return false;
+}
+
 /**
  * Helper to merge collected data into session
  * Updates agent-level data structure
@@ -177,21 +258,39 @@ export function mergeCollected<TData = Record<string, unknown>>(
 export function sessionStepToData<TData = Record<string, unknown>>(
   session: SessionState<TData>
 ): {
-  currentRoute?: string;
+  currentFlow?: string;
   currentStep?: string;
   collectedData: CollectedStateData<TData>;
 } {
+  // Strip PreDirective fields before persisting pendingDirective
+  let pendingDirective: SessionState<TData>["pendingDirective"] | undefined;
+  if (session.pendingDirective) {
+    pendingDirective = stripPreDirectiveFields(session.pendingDirective);
+  }
+
+  const collectedData: CollectedStateData<TData> = {
+    data: session.data || {},
+    flowHistory: session.flowHistory,
+    history: session.history,
+    currentFlowTitle: session.currentFlow?.title,
+    currentStepDescription: session.currentStep?.description,
+    metadata: session.metadata,
+  };
+
+  // Only include pendingDirective when defined (omit key when undefined)
+  if (pendingDirective !== undefined) {
+    collectedData.pendingDirective = pendingDirective;
+  }
+
+  // Pass through signals bit-identical (reserved for v2.x)
+  if (session.signals !== undefined) {
+    collectedData.signals = session.signals;
+  }
+
   return {
-    currentRoute: session.currentRoute?.id,
+    currentFlow: session.currentFlow?.id,
     currentStep: session.currentStep?.id,
-    collectedData: {
-      data: session.data || {},
-      routeHistory: session.routeHistory,
-      history: session.history, // Include conversation history
-      currentRouteTitle: session.currentRoute?.title,
-      currentStepDescription: session.currentStep?.description,
-      metadata: session.metadata,
-    },
+    collectedData,
   };
 }
 
@@ -204,26 +303,26 @@ export function sessionStepToData<TData = Record<string, unknown>>(
 export function sessionDataToStep<TData = Record<string, unknown>>(
   sessionId: string,
   data: {
-    currentRoute?: string;
+    currentFlow?: string;
     currentStep?: string;
     collectedData?: CollectedStateData<TData>;
   }
 ): SessionState<TData> {
   const collectedData: CollectedStateData<TData> = data.collectedData || {
     data: {},
-    routeHistory: [],
+    flowHistory: [],
     history: [],
     metadata: {},
-    currentRouteTitle: undefined,
+    currentFlowTitle: undefined,
     currentStepDescription: undefined,
   };
 
-  return {
+  const session: SessionState<TData> = {
     id: sessionId,
-    currentRoute: data.currentRoute
+    currentFlow: data.currentFlow
       ? {
-        id: data.currentRoute,
-        title: collectedData.currentRouteTitle || data.currentRoute,
+        id: data.currentFlow,
+        title: collectedData.currentFlowTitle || data.currentFlow,
         enteredAt: new Date(),
       }
       : undefined,
@@ -235,8 +334,105 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
       }
       : undefined,
     data: collectedData.data || {},
-    routeHistory: collectedData.routeHistory || [],
+    flowHistory: collectedData.flowHistory || [],
     history: collectedData.history || [],
     metadata: collectedData.metadata || {},
   };
+
+  // Restore pendingDirective if present (ignore any legacy pendingTransition — per Req 12.3)
+  if (collectedData.pendingDirective !== undefined) {
+    session.pendingDirective = collectedData.pendingDirective;
+  }
+
+  // Restore signals bit-identical (reserved for v2.x)
+  if (collectedData.signals !== undefined) {
+    session.signals = collectedData.signals;
+  }
+
+  return session;
+}
+
+
+/**
+ * Strip PreDirective-only fields from a directive before persistence.
+ *
+ * `appendPrompt`, `injectTools`, and `halt` are transient (one-turn lifetime)
+ * and must not be serialized. This is a belt-and-suspenders safety net —
+ * `Agent.dispatch` already strips before setting `pendingDirective`, and the
+ * DirectiveBus's post-LLM drain strips from post-LLM emitters. This function
+ * ensures the persistence layer never writes these fields regardless of the
+ * upstream path.
+ */
+function stripPreDirectiveFields<TData>(
+  directive: Directive<unknown, TData>
+): Directive<unknown, TData> {
+  const raw = directive as Record<string, unknown>;
+  if (!raw.appendPrompt && !raw.injectTools && raw.halt === undefined) {
+    return directive;
+  }
+
+  const { appendPrompt, injectTools, halt, ...rest } = raw;
+
+  const droppedFields = [
+    appendPrompt && "appendPrompt",
+    injectTools && "injectTools",
+    halt !== undefined && "halt",
+  ].filter(Boolean);
+
+  if (droppedFields.length > 0) {
+    logger.debug(
+      `[createPersistedState] Stripped PreDirective-only fields before persistence: ${droppedFields.join(", ")}`
+    );
+  }
+
+  return rest as Directive<unknown, TData>;
+}
+
+/**
+ * Prepare a session state for persistence by stripping transient fields.
+ *
+ * This is the shared helper that every persistence adapter should call before
+ * writing session state. It ensures:
+ * - `pendingDirective` has PreDirective-only fields (`appendPrompt`,
+ *   `injectTools`, `halt`) stripped (these are one-turn-lifetime and not
+ *   serializable across turns).
+ * - `pendingDirective` is omitted from the result when `undefined` (adapters
+ *   should not store a null/undefined key).
+ * - `signals` is passed through bit-identical (reserved for v2.x Signals).
+ * - Never writes `pendingTransition`.
+ *
+ * @param session - The in-memory session state to prepare for persistence.
+ * @returns A new session state object safe for serialization.
+ */
+export function createPersistedState<TData = Record<string, unknown>>(
+  session: SessionState<TData>
+): SessionState<TData> {
+  let pendingDirective: Directive<unknown, TData> | undefined =
+    session.pendingDirective;
+
+  if (pendingDirective) {
+    pendingDirective = stripPreDirectiveFields(pendingDirective);
+  }
+
+  // Build the persisted state — omit pendingDirective key entirely when undefined
+  const persisted: SessionState<TData> = {
+    id: session.id,
+    data: session.data,
+    flowHistory: session.flowHistory,
+    currentFlow: session.currentFlow,
+    currentStep: session.currentStep,
+    history: session.history,
+    metadata: session.metadata,
+  };
+
+  if (pendingDirective !== undefined) {
+    persisted.pendingDirective = pendingDirective;
+  }
+
+  // Pass through signals bit-identical (reserved for v2.x)
+  if (session.signals !== undefined) {
+    persisted.signals = session.signals;
+  }
+
+  return persisted;
 }