@falai/agent 0.4.1 → 0.5.0

package/src/core/Events.ts

@@ -71,7 +71,16 @@ export function createMessageEvent(
   source: EventSource,
   participantName: string,
   message: string,
-  timestamp?: string
+  options?: {
+    timestamp?: string;
+    session?: {
+      routeId?: string;
+      routeTitle?: string;
+      stateId?: string;
+      stateDescription?: string;
+      extracted?: Record<string, unknown>;
+    };
+  }
 ): Event<MessageEventData> {
   return {
     kind: EventKind.MESSAGE,
@@ -79,8 +88,9 @@ export function createMessageEvent(
     data: {
       participant: { display_name: participantName },
       message,
+      session: options?.session,
     },
-    timestamp: timestamp || new Date().toISOString(),
+    timestamp: options?.timestamp || new Date().toISOString(),
   };
 }
 

package/src/core/PersistenceManager.ts

@@ -14,6 +14,12 @@ import type {
   MessageRepository,
 } from "../types/persistence";
 import type { Event } from "../types/history";
+import type { SessionState } from "../types/session";
+import {
+  createSession,
+  sessionStateToData,
+  sessionDataToState,
+} from "../types/session";
 
 /**
  * Manager for handling persistence operations
@@ -219,4 +225,81 @@ export class PersistenceManager {
       .map((m) => this.messageToEvent(m))
       .filter((e): e is Event => e !== undefined);
   }
+
+  /**
+   * Save SessionState to database
+   * Converts SessionState to SessionData and persists it
+   */
+  async saveSessionState<TExtracted = Record<string, unknown>>(
+    sessionId: string,
+    sessionState: SessionState<TExtracted>
+  ): Promise<SessionData | null> {
+    const persistenceData = sessionStateToData(sessionState);
+
+    return await this.sessionRepository.update(sessionId, {
+      currentRoute: persistenceData.currentRoute,
+      currentState: persistenceData.currentState,
+      collectedData: persistenceData.collectedData,
+      lastMessageAt: new Date(),
+    });
+  }
+
+  /**
+   * Load SessionState from database
+   * Converts SessionData to SessionState
+   */
+  async loadSessionState<TExtracted = Record<string, unknown>>(
+    sessionId: string
+  ): Promise<SessionState<TExtracted> | null> {
+    const sessionData = await this.sessionRepository.findById(sessionId);
+
+    if (!sessionData) {
+      return null;
+    }
+
+    const stateData = sessionDataToState<TExtracted>({
+      currentRoute: sessionData.currentRoute,
+      currentState: sessionData.currentState,
+      collectedData: sessionData.collectedData,
+    });
+
+    // Create a full session state with the loaded data
+    const session = createSession<TExtracted>({
+      sessionId,
+      createdAt: sessionData.createdAt,
+      lastUpdatedAt: sessionData.updatedAt,
+    });
+
+    return {
+      ...session,
+      ...stateData,
+    };
+  }
+
+  /**
+   * Create session with SessionState support
+   * Returns both SessionData and initialized SessionState
+   */
+  async createSessionWithState<TExtracted = Record<string, unknown>>(
+    options: CreateSessionOptions
+  ): Promise<{
+    sessionData: SessionData;
+    sessionState: SessionState<TExtracted>;
+  }> {
+    const sessionData = await this.createSession(options);
+
+    // Create SessionState with database session ID
+    const sessionState = createSession<TExtracted>({
+      sessionId: sessionData.id,
+      createdAt: sessionData.createdAt,
+      lastUpdatedAt: sessionData.updatedAt,
+    });
+
+    // If initial data was provided, merge it as extracted data
+    if (options.initialData) {
+      sessionState.extracted = options.initialData as Partial<TExtracted>;
+    }
+
+    return { sessionData, sessionState };
+  }
 }

package/src/core/PromptComposer.ts

@@ -0,0 +1,143 @@
+import type { Event } from "../types/history";
+import type { Term, Guideline, Capability } from "../types/agent";
+import type { Route } from "./Route";
+
+export class PromptComposer<TContext = unknown> {
+  private parts: string[] = [];
+
+  // Specific, typed sections tailored to the framework
+
+  addAgentMeta(agent: {
+    name: string;
+    goal?: string;
+    description?: string;
+  }): this {
+    const lines: string[] = [];
+    lines.push(`Agent: ${agent.name}`);
+    if (agent.goal) lines.push(`Goal: ${agent.goal}`);
+    if (agent.description) lines.push(`Description: ${agent.description}`);
+    this.parts.push(lines.join("\n"));
+    return this;
+  }
+
+  addPersonality(personality?: string): this {
+    if (personality && personality.trim().length) {
+      this.parts.push(`Personality: ${personality.trim()}`);
+    }
+    return this;
+  }
+
+  addRoutingOverview(routes: Route<TContext>[]): this {
+    return this.addActiveRoutes(routes);
+  }
+
+  addScoringRules(): this {
+    this.parts.push(
+      [
+        "Scoring rules:",
+        "- 90-100: explicit keywords + clear intent",
+        "- 70-89: strong contextual evidence + relevant keywords",
+        "- 50-69: moderate relevance",
+        "- 30-49: weak connection or ambiguous",
+        "- 0-29: minimal/none",
+        "Return ONLY JSON matching the provided schema. Include scores for ALL routes.",
+      ].join("\n")
+    );
+    return this;
+  }
+
+  addInstruction(text: string): this {
+    if (text) this.parts.push(text);
+    return this;
+  }
+
+  addInteractionHistory(history: Event[], note?: string): this {
+    const recent = history
+      .slice(-10)
+      .map((e) => JSON.stringify(e))
+      .join("\n");
+    const header = note ? `${note}\n` : "";
+    this.parts.push(`${header}Recent conversation events:\n${recent}`);
+    return this;
+  }
+
+  addLastMessage(message: string): this {
+    this.parts.push(`Last user message:\n${message}`);
+    return this;
+  }
+
+  addGlossary(terms: Term[]): this {
+    if (!terms.length) return this;
+    const text = terms
+      .map(
+        (t, i) =>
+          `${i + 1}) ${t.name}${
+            t.synonyms?.length ? ` (synonyms: ${t.synonyms.join(", ")})` : ""
+          }: ${t.description}`
+      )
+      .join("\n");
+    this.parts.push(`Glossary:\n${text}`);
+    return this;
+  }
+
+  addGuidelines(guidelines: Guideline[]): this {
+    const enabled = guidelines.filter((g) => g.enabled !== false);
+    if (!enabled.length) return this;
+    const text = enabled
+      .map((g, i) => {
+        const cond = g.condition
+          ? `When ${g.condition}, then ${g.action}`
+          : g.action;
+        return `Guideline #${i + 1}) ${cond}`;
+      })
+      .join("\n");
+    this.parts.push(`Guidelines:\n${text}`);
+    return this;
+  }
+
+  addCapabilities(capabilities: Capability[]): this {
+    if (!capabilities.length) return this;
+    const text = capabilities
+      .map((c, i) => `Capability ${i + 1}: ${c.title}\n${c.description}`)
+      .join("\n\n");
+    this.parts.push(`Capabilities:\n${text}`);
+    return this;
+  }
+
+  addActiveRoutes(routes: Route<TContext>[]): this {
+    if (!routes.length) return this;
+    const text = routes
+      .map((r, i) => {
+        const conditions = r.conditions.length
+          ? `\n  Triggered when: ${r.conditions.join(" OR ")}`
+          : "";
+        const desc = r.description ? `\n  ${r.description}` : "";
+        const rules = r.getRules();
+        const prohibitions = r.getProhibitions();
+        const rulesInfo = rules.length
+          ? `\n  RULES: ${rules.map((x, idx) => `${idx + 1}. ${x}`).join("; ")}`
+          : "";
+        const prohibitionsInfo = prohibitions.length
+          ? `\n  PROHIBITIONS: ${prohibitions
+              .map((x, idx) => `${idx + 1}. ${x}`)
+              .join("; ")}`
+          : "";
+        return `${i + 1}) ${
+          r.title
+        }${desc}${conditions}${rulesInfo}${prohibitionsInfo}`;
+      })
+      .join("\n\n");
+    this.parts.push(`Available routes:\n${text}`);
+    return this;
+  }
+
+  addDirectives(directives?: string[]): this {
+    if (!directives?.length) return this;
+    this.parts.push(`Address concisely:\n- ${directives.join("\n- ")}`);
+    return this;
+  }
+
+  build(): string {
+    return this.parts.filter(Boolean).join("\n\n").trim();
+  }
+}

package/src/core/ResponseEngine.ts

@@ -0,0 +1,82 @@
+import type { Event } from "../types/history";
+import type { Route } from "./Route";
+import type { State } from "./State";
+import type { StructuredSchema } from "../types/schema";
+import { PromptComposer } from "./PromptComposer";
+
+export interface ResponseOutput<TData = unknown> {
+  message: string;
+  data?: TData;
+  contextUpdate?: Record<string, unknown>;
+}
+
+export class ResponseEngine<TContext = unknown> {
+  responseSchemaForRoute<TExtracted = unknown>(
+    route: Route<TContext, TExtracted>,
+    currentState?: State<TContext, TExtracted>
+  ): StructuredSchema {
+    const base: StructuredSchema = {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "Final user-facing message" },
+        data: route.responseOutputSchema || { type: "object" },
+        contextUpdate: { type: "object" },
+      },
+      required: ["message"],
+      additionalProperties: false,
+    };
+
+    // Add gather fields from current state
+    if (currentState?.gatherFields && route.gatherSchema?.properties) {
+      for (const field of currentState.gatherFields) {
+        const fieldSchema = route.gatherSchema.properties[field];
+        if (fieldSchema) {
+          base.properties![field] = fieldSchema;
+        }
+      }
+    }
+
+    return base;
+  }
+
+  buildResponsePrompt(
+    route: Route<TContext>,
+    rules: string[],
+    prohibitions: string[],
+    directives: string[] | undefined,
+    history: Event[],
+    lastMessage: string,
+    agentMeta?: {
+      name?: string;
+      goal?: string;
+      description?: string;
+      personality?: string;
+    }
+  ): string {
+    const pc = new PromptComposer();
+    if (agentMeta?.name || agentMeta?.goal || agentMeta?.description)
+      pc.addAgentMeta({
+        name: agentMeta?.name || "Agent",
+        goal: agentMeta?.goal,
+        description: agentMeta?.description,
+      });
+    const personality =
+      agentMeta?.personality || "Tone: brief, natural, 1-2 short sentences.";
+    pc.addPersonality(personality);
+    pc.addInstruction(
+      `Route: ${route.title}${
+        route.description ? ` — ${route.description}` : ""
+      }`
+    );
+    if (rules.length) pc.addInstruction(`Rules:\n- ${rules.join("\n- ")}`);
+    if (prohibitions.length)
+      pc.addInstruction(`Prohibitions:\n- ${prohibitions.join("\n- ")}`);
+    pc.addDirectives(directives);
+    pc.addInteractionHistory(history);
+    pc.addLastMessage(lastMessage);
+    pc.addInstruction(
+      "Return ONLY JSON matching the schema (message + optional data/contextUpdate)."
+    );
+    return pc.build();
+  }
+}

package/src/core/Route.ts

@@ -3,6 +3,7 @@
  */
 
 import type { RouteOptions, RouteRef } from "../types/route";
+import type { StructuredSchema } from "../types/schema";
 import type { Guideline } from "../types/agent";
 
 import { State } from "./State";
@@ -11,7 +12,7 @@ import { generateRouteId } from "../utils/id";
 /**
  * Represents a conversational route/journey
  */
-export class Route<TContext = unknown> {
+export class Route<TContext = unknown, TExtracted = unknown> {
   public readonly id: string;
   public readonly title: string;
   public readonly description?: string;
@@ -19,10 +20,14 @@ export class Route<TContext = unknown> {
   public readonly domains?: string[];
   public readonly rules: string[];
   public readonly prohibitions: string[];
-  public readonly initialState: State<TContext>;
+  public readonly initialState: State<TContext, TExtracted>;
+  public readonly responseOutputSchema?: StructuredSchema;
+  public readonly gatherSchema?: StructuredSchema;
+  public readonly initialData?: Partial<TExtracted>;
+  private routingExtrasSchema?: StructuredSchema;
   private guidelines: Guideline[] = [];
 
-  constructor(options: RouteOptions) {
+  constructor(options: RouteOptions<TExtracted>) {
     // Use provided ID or generate a deterministic one from the title
     this.id = options.id || generateRouteId(options.title);
     this.title = options.title;
@@ -31,7 +36,14 @@ export class Route<TContext = unknown> {
     this.domains = options.domains;
     this.rules = options.rules || ([] as string[]);
     this.prohibitions = options.prohibitions || ([] as string[]);
-    this.initialState = new State<TContext>(this.id, "Initial state");
+    this.initialState = new State<TContext, TExtracted>(
+      this.id,
+      "Initial state"
+    );
+    this.routingExtrasSchema = options.routingExtrasSchema;
+    this.responseOutputSchema = options.responseOutputSchema;
+    this.gatherSchema = options.gatherSchema;
+    this.initialData = options.initialData;
 
     // Initialize guidelines from options
     if (options.guidelines) {
@@ -83,32 +95,35 @@ export class Route<TContext = unknown> {
   }
 
   /**
-   * Get route reference
+   * Get optional extras schema requested during routing
    */
-  getRef(): RouteRef {
-    return {
-      id: this.id,
-    };
+  getRoutingExtrasSchema(): StructuredSchema | undefined {
+    return this.routingExtrasSchema;
   }
 
   /**
-   * Create a route reference that includes this route instance
-   * Useful for disambiguation
+   * Get optional structured response schema for this route's message
    */
-  toRef(): RouteRef & { route: Route<TContext> } {
+  getResponseOutputSchema(): StructuredSchema | undefined {
+    return this.responseOutputSchema;
+  }
+
+  /**
+   * Get route reference
+   */
+  getRef(): RouteRef {
     return {
       id: this.id,
-      route: this,
     };
   }
 
   /**
    * Get all states in this route (via traversal from initial state)
    */
-  getAllStates(): State<TContext>[] {
+  getAllStates(): State<TContext, TExtracted>[] {
     const visited = new Set<string>();
-    const states: State<TContext>[] = [];
-    const queue: State<TContext>[] = [this.initialState];
+    const states: State<TContext, TExtracted>[] = [];
+    const queue: State<TContext, TExtracted>[] = [this.initialState];
 
     while (queue.length > 0) {
       const current = queue.shift()!;
@@ -137,7 +152,7 @@ export class Route<TContext = unknown> {
    * @param stateId - The state ID to find
    * @returns The state if found, undefined otherwise
    */
-  getState(stateId: string): State<TContext> | undefined {
+  getState(stateId: string): State<TContext, TExtracted> | undefined {
     const states = this.getAllStates();
     return states.find((state) => state.id === stateId);
   }

package/src/core/RoutingEngine.ts

@@ -0,0 +1,165 @@
+import type { Event } from "../types/history";
+import type { Route } from "./Route";
+import type { StructuredSchema } from "../types/schema";
+import type { RoutingDecision } from "../types/routing";
+import type { SessionState } from "../types/session";
+import { PromptComposer } from "./PromptComposer";
+
+export interface RoutingDecisionOutput {
+  context: string;
+  routes: Record<string, number>;
+  responseDirectives?: string[];
+  extractions?: Array<{
+    name: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    value: any;
+    confidence?: number;
+    source?: "message" | "history";
+  }>;
+  contextUpdate?: Record<string, unknown>;
+}
+
+export interface RoutingEngineOptions {
+  allowRouteSwitch?: boolean;
+  switchThreshold?: number; // 0-100
+  maxCandidates?: number;
+}
+
+export class RoutingEngine<TContext = unknown> {
+  constructor(private readonly options?: RoutingEngineOptions) {}
+
+  buildDynamicRoutingSchema(
+    routes: Route<TContext>[],
+    extrasSchema?: StructuredSchema
+  ): StructuredSchema {
+    const routeIds = routes.map((r) => r.id);
+    const routeProperties: Record<string, StructuredSchema> = {};
+    for (const id of routeIds) {
+      routeProperties[id] = {
+        type: "number",
+        nullable: false,
+        description: `Score for route ${id} based on direct evidence, context and semantic fit (0-100)`,
+        minimum: 0,
+        maximum: 100,
+      } as StructuredSchema;
+    }
+
+    const base: StructuredSchema = {
+      description:
+        "Full intent analysis: score ALL available routes (0-100) using evidence and context",
+      type: "object",
+      properties: {
+        context: {
+          type: "string",
+          nullable: false,
+          description: "Brief summary of the user's intent/context",
+        },
+        routes: {
+          type: "object",
+          properties: routeProperties,
+          required: routeIds,
+          nullable: false,
+          description: "Mapping of routeId to score (0-100)",
+        },
+        responseDirectives: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional bullet points the response should address (concise)",
+        },
+      },
+      required: ["context", "routes"],
+      additionalProperties: false,
+    };
+
+    if (extrasSchema) {
+      base.properties = base.properties || {};
+      base.properties.extractions = extrasSchema;
+    }
+
+    return base;
+  }
+
+  buildRoutingPrompt(
+    history: Event[],
+    routes: Route<TContext>[],
+    lastMessage: string,
+    agentMeta?: {
+      name?: string;
+      goal?: string;
+      description?: string;
+      personality?: string;
+    },
+    session?: SessionState
+  ): string {
+    const pc = new PromptComposer();
+    if (agentMeta?.name || agentMeta?.goal || agentMeta?.description) {
+      pc.addAgentMeta({
+        name: agentMeta?.name || "Agent",
+        description: agentMeta?.description,
+        goal: agentMeta?.goal,
+      });
+    }
+    const personality =
+      agentMeta?.personality || "Tone: brief, natural, 1-2 short sentences.";
+    pc.addPersonality(personality);
+    pc.addInstruction(
+      "Task: Intent analysis and route scoring (0-100). Score ALL listed routes."
+    );
+
+    // Add session context if available
+    if (session?.currentRoute) {
+      const sessionInfo = [
+        "Current conversation context:",
+        `- Active route: ${session.currentRoute.title} (${session.currentRoute.id})`,
+      ];
+      if (session.currentState) {
+        sessionInfo.push(`- Current state: ${session.currentState.id}`);
+        if (session.currentState.description) {
+          sessionInfo.push(`  "${session.currentState.description}"`);
+        }
+      }
+      if (Object.keys(session.extracted).length > 0) {
+        sessionInfo.push(
+          `- Extracted data: ${JSON.stringify(session.extracted)}`
+        );
+      }
+      sessionInfo.push(
+        "Note: User is mid-conversation. They may want to continue current route or switch to a new one based on their intent."
+      );
+      pc.addInstruction(sessionInfo.join("\n"));
+    }
+
+    pc.addInteractionHistory(history);
+    pc.addLastMessage(lastMessage);
+    // Cast to unknown to satisfy generic constraints in composer
+    // This is safe because PromptComposer only reads route metadata (id, title, description)
+    pc.addRoutingOverview(routes as unknown as Route<unknown>[]);
+    pc.addInstruction(
+      [
+        "Scoring rules:",
+        "- 90-100: explicit keywords + clear intent",
+        "- 70-89: strong contextual evidence + relevant keywords",
+        "- 50-69: moderate relevance",
+        "- 30-49: weak connection or ambiguous",
+        "- 0-29: minimal/none",
+        "Return ONLY JSON matching the provided schema. Include scores for ALL routes.",
+      ].join("\n")
+    );
+    return pc.build();
+  }
+
+  decideRouteFromScores(output: RoutingDecision): {
+    routeId: string;
+    maxScore: number;
+  } {
+    // Optionally limit candidates and apply switching threshold
+    const entries = Object.entries(output.routes).sort((a, b) => b[1] - a[1]);
+    const limited = this.options?.maxCandidates
+      ? entries.slice(0, this.options.maxCandidates)
+      : entries;
+    const [topId, topScore] = limited[0] || ["", 0];
+    // switchThreshold is enforced by caller when a current route exists
+    return { routeId: topId, maxScore: topScore };
+  }
+}