@falai/agent 0.8.1 → 0.9.0-alpha-2

package/examples/{extracted-data-modification.ts → tools/data-enrichment-tools.ts}

@@ -11,14 +11,10 @@
 
 import {
   Agent,
-  createSession,
-  EventSource,
-  createMessageEvent,
   END_ROUTE,
   OpenAIProvider,
-} from "../src";
-import type { Event } from "../src/types";
-import type { ToolRef } from "../src/types/tool";
+  type Tool,
+} from "../../src";
 
 // ==============================================================================
 // CONTEXT & COLLECTED DATA TYPES
@@ -49,53 +45,55 @@ interface FlightData {
 // ==============================================================================
 
 // Tool 1: Convert city names to airport codes
-const enrichDestinationTool: ToolRef<
-  FlightBookingContext,
-  [],
-  void,
-  FlightData
-> = {
-  id: "enrich_destination",
-  name: "Enrich Destination",
-  description: "Convert city names to IATA airport codes",
-  handler: async (context) => {
-    const { data } = context;
-    const destination = (data as Partial<FlightData>)?.destination;
-
-    if (!destination) {
-      return { data: undefined };
-    }
-
-    // Simulate airport code lookup
-    const airportCodes: Record<string, string> = {
-      Paris: "CDG",
-      London: "LHR",
-      "New York": "JFK",
-      Tokyo: "NRT",
-      "Los Angeles": "LAX",
-    };
-
-    const destinationCode = airportCodes[destination];
-
-    console.log(`[Tool] Enriched: ${destination} → ${destinationCode}`);
-
-    return {
-      data: undefined,
-      dataUpdate: {
-        destinationCode,
-      } as Partial<FlightData>,
-    };
-  },
-};
+const enrichDestinationTool: Tool<FlightBookingContext, FlightData, [], void> =
+  {
+    id: "enrich_destination",
+    name: "Destination Code Lookup",
+    description: "Convert city names to IATA airport codes",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+    handler: ({ data }: { data?: Partial<FlightData> }) => {
+      const destination = (data as Partial<FlightData>)?.destination;
+
+      if (!destination) {
+        return { data: undefined };
+      }
+
+      // Simulate airport code lookup
+      const airportCodes: Record<string, string> = {
+        Paris: "CDG",
+        London: "LHR",
+        "New York": "JFK",
+        Tokyo: "NRT",
+        "Los Angeles": "LAX",
+      };
+
+      const destinationCode = airportCodes[destination];
+
+      console.log(`[Tool] Enriched: ${destination} → ${destinationCode}`);
+
+      return {
+        data: undefined,
+        dataUpdate: {
+          destinationCode,
+        } as Partial<FlightData>,
+      };
+    },
+  };
 
 // Tool 2: Parse and validate dates
-const validateDateTool: ToolRef<FlightBookingContext, [], void, FlightData> = {
+const validateDateTool: Tool<FlightBookingContext, FlightData, [], void> = {
   id: "validate_date",
-  name: "Validate Date",
+  name: "Date Parser & Validator",
   description:
     "Parse relative dates (today, tomorrow) to ISO format and validate",
-  handler: async (context) => {
-    const { data } = context;
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: ({ data }: { data?: Partial<FlightData> }) => {
     const departureDate = (data as Partial<FlightData>)?.departureDate;
 
     if (!departureDate) {
@@ -141,12 +139,15 @@ const validateDateTool: ToolRef<FlightBookingContext, [], void, FlightData> = {
 };
 
 // Tool 3: Search for flights (triggered by flag)
-const searchFlightsTool: ToolRef<FlightBookingContext, [], void, FlightData> = {
+const searchFlightsTool: Tool<FlightBookingContext, FlightData, [], void> = {
   id: "search_flights",
-  name: "Search Flights",
+  name: "Flight Availability Search",
   description: "Search for available flights based on collected data",
-  handler: async (context) => {
-    const { data } = context;
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: ({ data }: { data?: Partial<FlightData> }) => {
     const flightData = data as Partial<FlightData>;
 
     if (!flightData?.destinationCode || !flightData?.departureDateParsed) {
@@ -187,12 +188,15 @@ const searchFlightsTool: ToolRef<FlightBookingContext, [], void, FlightData> = {
 };
 
 // Tool 4: Book the flight
-const bookFlightTool: ToolRef<FlightBookingContext, [], void, FlightData> = {
+const bookFlightTool: Tool<FlightBookingContext, FlightData, [], void> = {
   id: "book_flight",
-  name: "Book Flight",
+  name: "Flight Booking Processor",
   description: "Finalize the flight booking",
-  handler: async (context) => {
-    const { data } = context;
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: ({ data }: { data?: Partial<FlightData> }) => {
     const flightData = data as Partial<FlightData>;
     console.log("[Tool] Booking flight with data:", flightData);
     // Simulate booking API call
@@ -204,10 +208,10 @@ const bookFlightTool: ToolRef<FlightBookingContext, [], void, FlightData> = {
 // LIFECYCLE HOOKS: Data Validation & Business Logic (RESPONSE Phase)
 // ==============================================================================
 
-async function onDataUpdate(
+function onDataUpdate(
   data: Record<string, unknown>,
   previousData: Record<string, unknown>
-): Promise<Record<string, unknown>> {
+): Record<string, unknown> {
   console.log("[Hook] onDataUpdate called");
   console.log("  Previous:", previousData);
   console.log("  New:", data);
@@ -248,7 +252,45 @@ async function onDataUpdate(
 // AGENT SETUP
 // ==============================================================================
 
-const agent = new Agent<FlightBookingContext>({
+// Define flight booking schema
+const flightBookingSchema = {
+  type: "object",
+  properties: {
+    destination: {
+      type: "string",
+      description: "City or airport the user wants to fly to",
+    },
+    destinationCode: {
+      type: "string",
+      description: "IATA airport code (enriched by tool)",
+    },
+    departureDate: {
+      type: "string",
+      description: "When the user wants to depart",
+    },
+    departureDateParsed: {
+      type: "string",
+      description: "Parsed ISO date (enriched by tool)",
+    },
+    passengers: {
+      type: "number",
+      minimum: 1,
+      maximum: 9,
+    },
+    cabinClass: {
+      type: "string",
+      enum: ["economy", "business", "first"],
+      default: "economy",
+    },
+    shouldSearchFlights: {
+      type: "boolean",
+      description: "Flag to trigger flight search",
+    },
+  },
+  required: ["destination", "departureDate", "passengers"],
+};
+
+const agent = new Agent<FlightBookingContext, FlightData>({
   name: "Flight Booking Agent",
   goal: "Help users book flights efficiently",
   description: "I help you find and book flights",
@@ -257,112 +299,82 @@ const agent = new Agent<FlightBookingContext>({
     model: "gpt-5o-mini",
   }),
   context: {},
+  // NEW: Agent-level schema
+  schema: flightBookingSchema,
   hooks: {
     onDataUpdate, // Validation & enrichment hook
   },
 });
 
 // Define route with data extraction
-const bookingRoute = agent.createRoute<FlightData>({
+const bookingRoute = agent.createRoute({
   title: "Book Flight",
   description: "Help user book a flight",
   conditions: [
     "User wants to book a flight",
     "User mentions flying, traveling, or booking",
   ],
-  schema: {
-    type: "object",
-    properties: {
-      destination: {
-        type: "string",
-        description: "City or airport the user wants to fly to",
-      },
-      destinationCode: {
-        type: "string",
-        description: "IATA airport code (enriched by tool)",
-      },
-      departureDate: {
-        type: "string",
-        description: "When the user wants to depart",
-      },
-      departureDateParsed: {
-        type: "string",
-        description: "Parsed ISO date (enriched by tool)",
-      },
-      passengers: {
-        type: "number",
-        minimum: 1,
-        maximum: 9,
-      },
-      cabinClass: {
-        type: "string",
-        enum: ["economy", "business", "first"],
-        default: "economy",
-      },
-      shouldSearchFlights: {
-        type: "boolean",
-        description: "Flag to trigger flight search",
-      },
-    },
-    required: ["destination", "departureDate", "passengers"],
-  },
+  // NEW: Required fields for route completion
+  requiredFields: ["destination", "departureDate", "passengers"],
+  // NEW: Optional fields that enhance the experience
+  optionalFields: ["destinationCode", "departureDateParsed", "cabinClass", "shouldSearchFlights"],
 });
 
 // Step 1: Collect destination
 const collectDestination = bookingRoute.initialStep.nextStep({
-  instructions: "Ask where they want to fly",
+  prompt: "Ask where they want to fly",
   collect: ["destination"],
   skipIf: (data) => !!data.destination,
 });
 
 // Step 2: Enrich destination (tool execution)
 const enrichDestination = collectDestination.nextStep({
-  tool: enrichDestinationTool,
+  tools: [enrichDestinationTool],
   requires: ["destination"],
 });
 
 // Step 3: Collect date
 const collectDate = enrichDestination.nextStep({
-  instructions: "Ask when they want to depart",
+  prompt: "Ask when they want to depart",
   collect: ["departureDate"],
   skipIf: (data) => !!data.departureDate,
 });
 
 // Step 4: Validate/parse date (tool execution)
 const validateDate = collectDate.nextStep({
-  tool: validateDateTool,
+  tools: [validateDateTool],
   requires: ["departureDate"],
 });
 
 // Step 5: Collect passengers
 const collectPassengers = validateDate.nextStep({
-  instructions: "Ask how many passengers",
+  prompt: "Ask how many passengers",
   collect: ["passengers"],
   skipIf: (data) => !!data.passengers,
 });
 
 // Step 6: Search flights (triggered by hook setting shouldSearchFlights)
 const searchFlights = collectPassengers.nextStep({
-  tool: searchFlightsTool,
+  tools: [searchFlightsTool],
   // This step is entered when shouldSearchFlights is true
   // The hook automatically sets this flag when all data is collected
 });
 
 // Step 7: Present results
 const presentResults = searchFlights.nextStep({
-  instructions: "Present available flights to the user",
+  prompt: "Present available flights to the user",
 });
 
 // Step 8: Confirm booking
 const confirmBooking = presentResults.nextStep({
-  instructions: "Ask user to confirm the booking",
+  prompt: "Ask user to confirm the booking",
   requires: ["destinationCode", "departureDateParsed", "passengers"],
 });
 
 // Step 9: Finalize booking
 const finalizeBooking = confirmBooking.nextStep({
-  tool: bookFlightTool,
-  condition: "User confirms the booking",
+  tools: [bookFlightTool],
+  when: "User confirms the booking",
 });
 
 // Step 10: End of conversation
@@ -373,27 +385,26 @@ finalizeBooking.nextStep({ step: END_ROUTE });
 // ==============================================================================
 
 async function main() {
-  let session = createSession<FlightData>();
+  // Session is automatically managed by the agent
+  console.log("✨ Session ready:", agent.session.id);
 
   // Turn 1: User provides everything at once
-  const history: Event[] = [
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "I want to fly to Paris tomorrow with 2 passengers"
-    ),
-  ];
+  await agent.session.addMessage("user", "I want to fly to Paris tomorrow with 2 passengers");
 
-  const response = await agent.respond({ history, session });
+  const response = await agent.respond({ 
+    history: agent.session.getHistory() 
+  });
 
   console.log("\n=== RESPONSE ===");
   console.log("Message:", response.message);
-  console.log("Data:", response.session?.data);
+  console.log("Data:", agent.session.getData());
   console.log("Context:", agent["context"]);
 
+  await agent.session.addMessage("assistant", response.message);
+
   if (response.isRouteComplete) {
     console.log("\n✅ Flight booking complete!");
-    await sendBookingConfirmation(response.session?.data);
+    await sendBookingConfirmation(agent.session.getData());
   }
 
   /*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.8.1",
+  "version": "0.9.0-alpha-2",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -31,7 +31,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/falai-dev/agent.git"
+    "url": "git+https://github.com/falai-dev/agent.git"
   },
   "bugs": {
     "url": "https://github.com/falai-dev/agent/issues"
@@ -52,8 +52,9 @@
     "release:patch": "npm version patch && npm publish",
     "release:minor": "npm version minor && npm publish",
     "release:major": "npm version major && npm publish",
+    "release:alpha": "npm publish --tag alpha",
     "release": "npm publish",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "bun run tests/*.test.ts"
   },
   "keywords": [
     "ai",
@@ -70,27 +71,30 @@
   "author": "Gustavo Salomé <gusnips>",
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^20.11.0",
     "@eslint/js": "^9.17.0",
+    "@types/bun": "^1.3.0",
+    "@types/node": "^20.19.22",
     "eslint": "^9.17.0",
     "typescript": "^5.3.3",
-    "typescript-eslint": "^8.18.2"
+    "typescript-eslint": "^8.18.2",
+    "vitest": "^3.2.4"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.65.0",
     "@google/genai": "^0.3.0",
+    "@types/pg": "^8.15.5",
     "@types/redis": "^4.0.11",
     "loglevel": "^1.9.2",
     "openai": "^6.3.0"
   },
   "peerDependencies": {
+    "@opensearch-project/opensearch": "^2.0.0",
     "@prisma/client": "^6.0.0",
-    "ioredis": "^5.7.0",
-    "mongodb": "^6.0.0 || ^7.0.0",
-    "pg": "^8.11.0",
-    "mysql2": "^3.2.0",
     "better-sqlite3": "^11.0.0 || ^12.0.0",
-    "@opensearch-project/opensearch": "^2.0.0"
+    "ioredis": "",
+    "mongodb": "",
+    "mysql2": "^3.2.0",
+    "pg": ""
   },
   "peerDependenciesMeta": {
     "@prisma/client": {

package/src/adapters/MemoryAdapter.ts

@@ -4,13 +4,16 @@
  */
 
 import type {
-  SessionRepository,
+  CollectedStateData,
+  MessageData,
   MessageRepository,
+  PersistenceAdapter,
   SessionData,
-  MessageData,
+  SessionRepository,
   SessionStatus,
-  PersistenceAdapter,
-} from "../types/persistence";
+  CreateSessionData,
+} from "../types";
+import { cloneDeep } from "../utils/clone";
 
 /**
  * Memory Adapter - Provider-style API for in-memory persistence
@@ -35,17 +38,19 @@ import type {
  * });
  * ```
  */
-export class MemoryAdapter implements PersistenceAdapter {
-  public readonly sessionRepository: SessionRepository;
+export class MemoryAdapter<TData = Record<string, unknown>>
+  implements PersistenceAdapter<TData>
+{
+  public readonly sessionRepository: SessionRepository<TData>;
   public readonly messageRepository: MessageRepository;
-  private sessions: Map<string, SessionData>;
+  private sessions: Map<string, SessionData<TData>>;
   private messages: Map<string, MessageData>;
 
   constructor() {
     this.sessions = new Map();
     this.messages = new Map();
 
-    this.sessionRepository = new MemorySessionRepository(this.sessions);
+    this.sessionRepository = new MemorySessionRepository<TData>(this.sessions);
     this.messageRepository = new MemoryMessageRepository(this.messages);
   }
 
@@ -61,7 +66,7 @@ export class MemoryAdapter implements PersistenceAdapter {
    * Get data snapshot (useful for debugging)
    */
   getSnapshot(): {
-    sessions: SessionData[];
+    sessions: SessionData<TData>[];
     messages: MessageData[];
   } {
     return {
@@ -74,16 +79,17 @@ export class MemoryAdapter implements PersistenceAdapter {
 /**
  * Memory Session Repository
  */
-class MemorySessionRepository implements SessionRepository {
-  constructor(private sessions: Map<string, SessionData>) {}
-
-  async create(
-    data: Omit<SessionData, "id" | "createdAt" | "updatedAt">
-  ): Promise<SessionData> {
-    const id = `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+class MemorySessionRepository<TData = Record<string, unknown>>
+  implements SessionRepository<TData>
+{
+  constructor(private sessions: Map<string, SessionData<TData>>) {}
+
+  create(data: CreateSessionData<TData>): Promise<SessionData<TData>> {
+    const id =
+      data.id || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
     const now = new Date();
 
-    const session: SessionData = {
+    const session: SessionData<TData> = {
       ...data,
       id,
       status: data.status || "active",
@@ -92,16 +98,16 @@ class MemorySessionRepository implements SessionRepository {
       updatedAt: now,
     };
 
-    this.sessions.set(id, session);
-    return Promise.resolve(session);
+    this.sessions.set(id, cloneDeep(session));
+    return Promise.resolve(cloneDeep(session));
   }
 
-  async findById(id: string): Promise<SessionData | null> {
-    const session = this.sessions.get(id) || null;
-    return Promise.resolve(session);
+  findById(id: string): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    return Promise.resolve(session ? cloneDeep(session) : null);
   }
 
-  async findActiveByUserId(userId: string): Promise<SessionData | null> {
+  async findActiveByUserId(userId: string): Promise<SessionData<TData> | null> {
     const sessions = Array.from(this.sessions.values())
       .filter((s) => s.userId === userId && s.status === "active")
       .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
@@ -109,7 +115,10 @@ class MemorySessionRepository implements SessionRepository {
     return Promise.resolve(sessions[0] || null);
   }
 
-  async findByUserId(userId: string, limit = 100): Promise<SessionData[]> {
+  async findByUserId(
+    userId: string,
+    limit = 100
+  ): Promise<SessionData<TData>[]> {
     const sessions = Array.from(this.sessions.values())
       .filter((s) => s.userId === userId)
       .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
@@ -119,55 +128,74 @@ class MemorySessionRepository implements SessionRepository {
 
   async update(
     id: string,
-    data: Partial<Omit<SessionData, "id" | "createdAt">>
-  ): Promise<SessionData | null> {
+    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+  ): Promise<SessionData<TData> | null> {
     const existing = this.sessions.get(id);
     if (!existing) return null;
 
-    const updated: SessionData = {
+    const updated: SessionData<TData> = {
       ...existing,
       ...data,
       updatedAt: new Date(),
     };
 
-    this.sessions.set(id, updated);
-    return Promise.resolve(updated);
+    this.sessions.set(id, cloneDeep(updated));
+    return Promise.resolve(cloneDeep(updated));
   }
 
   async updateStatus(
     id: string,
     status: SessionStatus,
     completedAt?: Date
-  ): Promise<SessionData | null> {
-    return await this.update(id, { status, completedAt });
+  ): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.status = status;
+      if (completedAt) {
+        session.completedAt = completedAt;
+      }
+      this.sessions.set(id, cloneDeep(session));
+      return Promise.resolve(cloneDeep(session));
+    }
+    return Promise.resolve(null);
   }
 
   async updateCollectedData(
     id: string,
-    collectedData: Record<string, unknown>
-  ): Promise<SessionData | null> {
-    return await this.update(id, { collectedData });
+    collectedData: CollectedStateData<TData>
+  ): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.collectedData = collectedData;
+      this.sessions.set(id, cloneDeep(session));
+      return Promise.resolve(cloneDeep(session));
+    }
+    return Promise.resolve(null);
   }
 
   async updateRouteStep(
     id: string,
     route?: string,
     step?: string
-  ): Promise<SessionData | null> {
-    return await this.update(id, {
-      currentRoute: route,
-      currentStep: step,
-    });
+  ): Promise<SessionData<TData> | null> {
+    const session = this.sessions.get(id);
+    if (session) {
+      session.currentRoute = route;
+      session.currentStep = step;
+      this.sessions.set(id, cloneDeep(session));
+      return Promise.resolve(cloneDeep(session));
+    }
+    return Promise.resolve(null);
   }
 
-  async incrementMessageCount(id: string): Promise<SessionData | null> {
+  async incrementMessageCount(id: string): Promise<SessionData<TData> | null> {
     const session = this.sessions.get(id);
-    if (!session) return null;
-
-    return await this.update(id, {
-      messageCount: (session.messageCount || 0) + 1,
-      lastMessageAt: new Date(),
-    });
+    if (session) {
+      session.messageCount = (session.messageCount || 0) + 1;
+      this.sessions.set(id, cloneDeep(session));
+      return Promise.resolve(cloneDeep(session));
+    }
+    return Promise.resolve(null);
   }
 
   async delete(id: string): Promise<boolean> {