@falai/agent 0.8.0 → 0.8.1

package/src/core/PersistenceManager.ts

@@ -14,7 +14,7 @@ import type {
   MessageRepository,
 } from "../types/persistence";
 import type { Event } from "../types/history";
-import type { SessionStep } from "../types/session";
+import type { SessionState } from "../types/session";
 import {
   createSession,
   sessionStepToData,
@@ -223,12 +223,12 @@ export class PersistenceManager {
   }
 
   /**
-   * Save SessionStep to database
-   * Converts SessionStep to SessionData and persists it
+   * Save SessionState to database
+   * Converts SessionState to SessionData and persists it
    */
-  async saveSessionStep<TData = Record<string, unknown>>(
+  async saveSessionState<TData = Record<string, unknown>>(
     sessionId: string,
-    sessionStep: SessionStep<TData>
+    sessionStep: SessionState<TData>
   ): Promise<SessionData | null> {
     const persistenceData = sessionStepToData(sessionStep);
 
@@ -241,12 +241,12 @@ export class PersistenceManager {
   }
 
   /**
-   * Load SessionStep from database
-   * Converts SessionData to SessionStep
+   * Load SessionState from database
+   * Converts SessionData to SessionState
    */
-  async loadSessionStep<TData = Record<string, unknown>>(
+  async loadSessionState<TData = Record<string, unknown>>(
     sessionId: string
-  ): Promise<SessionStep<TData> | null> {
+  ): Promise<SessionState<TData> | null> {
     const sessionData = await this.sessionRepository.findById(sessionId);
 
     if (!sessionData) {
@@ -272,18 +272,18 @@ export class PersistenceManager {
   }
 
   /**
-   * Create session with SessionStep support
-   * Returns both SessionData and initialized SessionStep
+   * Create session with SessionState support
+   * Returns both SessionData and initialized SessionState
    */
   async createSessionWithStep<TData = Record<string, unknown>>(
     options: CreateSessionOptions
   ): Promise<{
     sessionData: SessionData;
-    sessionStep: SessionStep<TData>;
+    sessionStep: SessionState<TData>;
   }> {
     const sessionData = await this.createSession(options);
 
-    // Create SessionStep with database session ID
+    // Create SessionState with database session ID
     const sessionStep = createSession<TData>(sessionData.id, {
       createdAt: sessionData.createdAt,
       lastUpdatedAt: sessionData.updatedAt,

package/src/core/RoutingEngine.ts

@@ -3,7 +3,7 @@ import type { Route } from "./Route";
 import type { Step } from "./Step";
 import type { StructuredSchema } from "../types/schema";
 import type { RoutingDecision } from "../types/routing";
-import type { SessionStep } from "../types/session";
+import type { SessionState } from "../types/session";
 import type { AiProvider } from "../types/ai";
 import { enterRoute, mergeCollected } from "../types/session";
 import { PromptComposer } from "./PromptComposer";
@@ -42,7 +42,7 @@ export class RoutingEngine<TContext = unknown> {
    */
   private async decideSingleRouteStep(params: {
     route: Route<TContext, unknown>;
-    session: SessionStep;
+    session: SessionState;
     history: Event[];
     agentMeta?: {
       name?: string;
@@ -57,7 +57,7 @@ export class RoutingEngine<TContext = unknown> {
     selectedRoute?: Route<TContext>;
     selectedStep?: Step<TContext>;
     responseDirectives?: string[];
-    session: SessionStep;
+    session: SessionState;
     isRouteComplete?: boolean;
   }> {
     const { route, session, history, agentMeta, provider, context, signal } =
@@ -404,7 +404,7 @@ export class RoutingEngine<TContext = unknown> {
    */
   async decideRouteAndStep(params: {
     routes: Route<TContext, unknown>[];
-    session: SessionStep;
+    session: SessionState;
     history: Event[];
     agentMeta?: {
       name?: string;
@@ -419,7 +419,7 @@ export class RoutingEngine<TContext = unknown> {
     selectedRoute?: Route<TContext>;
     selectedStep?: Step<TContext>;
     responseDirectives?: string[];
-    session: SessionStep;
+    session: SessionState;
     isRouteComplete?: boolean;
   }> {
     const { routes, session, history, agentMeta, provider, context, signal } =
@@ -821,7 +821,7 @@ export class RoutingEngine<TContext = unknown> {
       description?: string;
       personality?: string;
     },
-    session?: SessionStep,
+    session?: SessionState,
     activeRouteSteps?: Array<{
       stepId: string;
       description: string;

package/src/index.ts

@@ -99,7 +99,7 @@ export type {
   RouteCompletionHandler,
 } from "./types/route";
 
-export type { SessionStep, PendingTransition } from "./types/session";
+export type { SessionState, PendingTransition } from "./types/session";
 export {
   createSession,
   enterRoute,

package/src/types/agent.ts

@@ -6,7 +6,7 @@ import type { AiProvider } from "./ai";
 import type { ToolRef } from "./tool";
 import type { RouteOptions } from "./route";
 import type { PersistenceConfig } from "./persistence";
-import type { SessionStep } from "./session";
+import type { SessionState } from "./session";
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -80,7 +80,7 @@ export interface AgentOptions<TContext = unknown> {
   /** Default context data available to the agent */
   context?: TContext;
   /** Optional current session for convenience methods */
-  session?: SessionStep;
+  session?: SessionState;
   /** Context provider function for always-fresh context (alternative to static context) */
   contextProvider?: ContextProvider<TContext>;
   /** Lifecycle hooks for context management */

package/src/types/session.ts

@@ -18,7 +18,7 @@ export interface PendingTransition {
  * Session step tracks the current position in the conversation flow
  * and data collected during the route progression
  */
-export interface SessionStep<TData = Record<string, unknown>> {
+export interface SessionState<TData = Record<string, unknown>> {
   /** Unique session identifier (useful for persistence) */
   id?: string;
 
@@ -78,8 +78,8 @@ export interface SessionStep<TData = Record<string, unknown>> {
  */
 export function createSession<TData = Record<string, unknown>>(
   sessionId?: string,
-  metadata?: SessionStep<TData>["metadata"]
-): SessionStep<TData> {
+  metadata?: SessionState<TData>["metadata"]
+): SessionState<TData> {
   return {
     id: sessionId,
     data: {},
@@ -98,10 +98,10 @@ export function createSession<TData = Record<string, unknown>>(
  * Preserves collected data per route in dataByRoute map
  */
 export function enterRoute<TData = Record<string, unknown>>(
-  session: SessionStep<TData>,
+  session: SessionState<TData>,
   routeId: string,
   routeTitle: string
-): SessionStep<TData> {
+): SessionState<TData> {
   // Save current route's collected data before switching
   const dataByRoute = { ...session.dataByRoute };
   if (
@@ -157,10 +157,10 @@ export function enterRoute<TData = Record<string, unknown>>(
  * Helper to update session with new step
  */
 export function enterStep<TData = Record<string, unknown>>(
-  session: SessionStep<TData>,
+  session: SessionState<TData>,
   stepId: string,
   stepDescription?: string
-): SessionStep<TData> {
+): SessionState<TData> {
   return {
     ...session,
     currentStep: {
@@ -180,9 +180,9 @@ export function enterStep<TData = Record<string, unknown>>(
  * Updates both the data field and the dataByRoute map
  */
 export function mergeCollected<TData = Record<string, unknown>>(
-  session: SessionStep<TData>,
+  session: SessionState<TData>,
   data: Partial<unknown>
-): SessionStep<TData> {
+): SessionState<TData> {
   const newCollected = {
     ...session.data,
     ...data,
@@ -206,11 +206,11 @@ export function mergeCollected<TData = Record<string, unknown>>(
 }
 
 /**
- * Helper to convert SessionStep to persistence-friendly format
+ * Helper to convert SessionState to persistence-friendly format
  * Used when saving to database
  */
 export function sessionStepToData<TData = Record<string, unknown>>(
-  session: SessionStep<TData>
+  session: SessionState<TData>
 ): {
   currentRoute?: string;
   currentStep?: string;
@@ -231,7 +231,7 @@ export function sessionStepToData<TData = Record<string, unknown>>(
 }
 
 /**
- * Helper to convert database SessionData back to SessionStep
+ * Helper to convert database SessionData back to SessionState
  * Used when loading from database
  * @param sessionId - The database session ID
  * @param data - The database session data
@@ -243,7 +243,7 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
     currentStep?: string;
     collectedData?: Record<string, unknown>;
   }
-): SessionStep<TData> {
+): SessionState<TData> {
   const collectedData = data.collectedData || {};
 
   return {
@@ -268,7 +268,7 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
     dataByRoute:
       (collectedData.dataByRoute as Record<string, Partial<unknown>>) || {}, // Restore per-route data
     routeHistory:
-      (collectedData.routeHistory as SessionStep<TData>["routeHistory"]) || [],
-    metadata: (collectedData.metadata as SessionStep<TData>["metadata"]) || {},
+      (collectedData.routeHistory as SessionState<TData>["routeHistory"]) || [],
+    metadata: (collectedData.metadata as SessionState<TData>["metadata"]) || {},
   };
 }