@falai/agent 0.7.0 → 0.8.1

package/src/core/Agent.ts

@@ -6,7 +6,7 @@ import type { AgentOptions, Term, Guideline, Capability } from "../types/agent";
 import type { Event, StepRef } from "../types/index";
 import type { RouteOptions } from "../types/route";
 
-import type { SessionStep } from "../types/session";
+import type { SessionState } from "../types/session";
 import type { AgentStructuredResponse } from "../types/ai";
 import {
   createSession,
@@ -42,7 +42,7 @@ export class Agent<TContext = unknown> {
   private persistenceManager: PersistenceManager | undefined;
   private routingEngine: RoutingEngine<TContext>;
   private responseEngine: ResponseEngine<TContext>;
-  private currentSession?: SessionStep;
+  private currentSession?: SessionState;
 
   /**
    * Dynamic domain property - populated via addDomain
@@ -236,9 +236,9 @@ export class Agent<TContext = unknown> {
    * @internal
    */
   private async updateData<TData = unknown>(
-    session: SessionStep<TData>,
+    session: SessionState<TData>,
     collectedUpdate: Partial<TData>
-  ): Promise<SessionStep<TData>> {
+  ): Promise<SessionState<TData>> {
     const previousCollected = { ...session.data };
 
     // Merge new collected data
@@ -279,14 +279,14 @@ export class Agent<TContext = unknown> {
   async *respondStream(params: {
     history: Event[];
     step?: StepRef;
-    session?: SessionStep;
+    session?: SessionState;
     contextOverride?: Partial<TContext>;
     signal?: AbortSignal;
   }): AsyncGenerator<{
     delta: string;
     accumulated: string;
     done: boolean;
-    session?: SessionStep;
+    session?: SessionState;
     toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
     isRouteComplete?: boolean;
   }> {
@@ -412,7 +412,7 @@ export class Agent<TContext = unknown> {
           description: this.options.description,
           personality: this.options.personality,
         },
-        ai: this.options.ai,
+        provider: this.options.provider,
         context: effectiveContext,
         signal,
       });
@@ -491,7 +491,7 @@ export class Agent<TContext = unknown> {
       );
 
       // Generate message stream using AI provider
-      const stream = this.options.ai.generateMessageStream({
+      const stream = this.options.provider.generateMessageStream({
         prompt: responsePrompt,
         history,
         context: effectiveContext,
@@ -548,7 +548,7 @@ export class Agent<TContext = unknown> {
           session.id &&
           this.options.persistence?.autoSave !== false
         ) {
-          await this.persistenceManager.saveSessionStep(session.id, session);
+          await this.persistenceManager.saveSessionState(session.id, session);
           logger.debug(
             `[Agent] Auto-saved session step to persistence: ${session.id}`
           );
@@ -612,7 +612,7 @@ export class Agent<TContext = unknown> {
       );
 
       // Stream completion message using AI provider
-      const stream = this.options.ai.generateMessageStream({
+      const stream = this.options.provider.generateMessageStream({
         prompt: completionPrompt,
         history,
         context: effectiveContext,
@@ -698,7 +698,7 @@ export class Agent<TContext = unknown> {
         .addCapabilities(this.capabilities)
         .build();
 
-      const stream = this.options.ai.generateMessageStream({
+      const stream = this.options.provider.generateMessageStream({
         prompt: fallbackPrompt,
         history,
         context: effectiveContext,
@@ -740,12 +740,12 @@ export class Agent<TContext = unknown> {
   async respond(params: {
     history: Event[];
     step?: StepRef;
-    session?: SessionStep;
+    session?: SessionState;
     contextOverride?: Partial<TContext>;
     signal?: AbortSignal;
   }): Promise<{
     message: string;
-    session?: SessionStep;
+    session?: SessionState;
     toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
     isRouteComplete?: boolean;
   }> {
@@ -872,7 +872,7 @@ export class Agent<TContext = unknown> {
           description: this.options.description,
           personality: this.options.personality,
         },
-        ai: this.options.ai,
+        provider: this.options.provider,
         context: effectiveContext,
         signal,
       });
@@ -956,7 +956,7 @@ export class Agent<TContext = unknown> {
       );
 
       // Generate message using AI provider
-      const result = await this.options.ai.generateMessage({
+      const result = await this.options.provider.generateMessage({
         prompt: responsePrompt,
         history,
         context: effectiveContext,
@@ -1044,7 +1044,7 @@ export class Agent<TContext = unknown> {
       );
 
       // Generate completion message using AI provider
-      const completionResult = await this.options.ai.generateMessage({
+      const completionResult = await this.options.provider.generateMessage({
         prompt: completionPrompt,
         history,
         context: effectiveContext,
@@ -1115,7 +1115,7 @@ export class Agent<TContext = unknown> {
         .addCapabilities(this.capabilities)
         .build();
 
-      const result = await this.options.ai.generateMessage({
+      const result = await this.options.provider.generateMessage({
         prompt: fallbackPrompt,
         history,
         context: effectiveContext,
@@ -1142,7 +1142,7 @@ export class Agent<TContext = unknown> {
       session.id &&
       this.options.persistence?.autoSave !== false
     ) {
-      await this.persistenceManager.saveSessionStep(session.id, session);
+      await this.persistenceManager.saveSessionState(session.id, session);
       logger.debug(
         `[Agent] Auto-saved session step to persistence: ${session.id}`
       );
@@ -1250,14 +1250,14 @@ export class Agent<TContext = unknown> {
    * Set the current session for convenience methods
    * @param session - Session step to use for subsequent calls
    */
-  setCurrentSession(session: SessionStep): void {
+  setCurrentSession(session: SessionState): void {
     this.currentSession = session;
   }
 
   /**
    * Get the current session (if set)
    */
-  getCurrentSession(): SessionStep | undefined {
+  getCurrentSession(): SessionState | undefined {
     return this.currentSession;
   }
 
@@ -1305,9 +1305,9 @@ export class Agent<TContext = unknown> {
    */
   nextStepRoute(
     routeIdOrTitle: string,
-    session?: SessionStep,
+    session?: SessionState,
     condition?: string
-  ): SessionStep {
+  ): SessionState {
     const targetSession = session || this.currentSession;
 
     if (!targetSession) {
@@ -1329,7 +1329,7 @@ export class Agent<TContext = unknown> {
       );
     }
 
-    const updatedSession: SessionStep = {
+    const updatedSession: SessionState = {
       ...targetSession,
       pendingTransition: {
         targetRouteId: targetRoute.id,

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;
@@ -50,17 +50,18 @@ export class RoutingEngine<TContext = unknown> {
       description?: string;
       personality?: string;
     };
-    ai: AiProvider;
+    provider: AiProvider;
     context: TContext;
     signal?: AbortSignal;
   }): Promise<{
     selectedRoute?: Route<TContext>;
     selectedStep?: Step<TContext>;
     responseDirectives?: string[];
-    session: SessionStep;
+    session: SessionState;
     isRouteComplete?: boolean;
   }> {
-    const { route, session, history, agentMeta, ai, context, signal } = params;
+    const { route, session, history, agentMeta, provider, context, signal } =
+      params;
 
     let updatedSession = session;
     const selectedRoute = route;
@@ -138,7 +139,7 @@ export class RoutingEngine<TContext = unknown> {
       candidates.map((c) => c.step.id)
     );
 
-    const stepResult = await ai.generateMessage<
+    const stepResult = await provider.generateMessage<
       TContext,
       {
         reasoning: string;
@@ -403,7 +404,7 @@ export class RoutingEngine<TContext = unknown> {
    */
   async decideRouteAndStep(params: {
     routes: Route<TContext, unknown>[];
-    session: SessionStep;
+    session: SessionState;
     history: Event[];
     agentMeta?: {
       name?: string;
@@ -411,17 +412,18 @@ export class RoutingEngine<TContext = unknown> {
       description?: string;
       personality?: string;
     };
-    ai: AiProvider;
+    provider: AiProvider;
     context: TContext;
     signal?: AbortSignal;
   }): Promise<{
     selectedRoute?: Route<TContext>;
     selectedStep?: Step<TContext>;
     responseDirectives?: string[];
-    session: SessionStep;
+    session: SessionState;
     isRouteComplete?: boolean;
   }> {
-    const { routes, session, history, agentMeta, ai, context, signal } = params;
+    const { routes, session, history, agentMeta, provider, context, signal } =
+      params;
 
     if (routes.length === 0) {
       return { session };
@@ -434,7 +436,7 @@ export class RoutingEngine<TContext = unknown> {
         session,
         history,
         agentMeta,
-        ai,
+        provider,
         context,
         signal,
       });
@@ -504,7 +506,7 @@ export class RoutingEngine<TContext = unknown> {
       activeRouteSteps
     );
 
-    const routingResult = await ai.generateMessage<
+    const routingResult = await provider.generateMessage<
       TContext,
       RoutingDecisionOutput
     >({
@@ -819,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,13 +80,13 @@ 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 */
   hooks?: ContextLifecycleHooks<TContext>;
   /** AI provider strategy for generating responses */
-  ai: AiProvider;
+  provider: AiProvider;
   /** Composition mode for response generation */
   compositionMode?: CompositionMode;
   /** Initial terms for domain glossary */

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"]) || {},
   };
 }