@falai/agent 0.6.4 → 0.6.6

package/docs/PUBLISHING.md

@@ -3,6 +3,7 @@
 ## Pre-publish Checklist
 
 ### 1. Build and Test
+
 ```bash
 # Clean previous builds
 rm -rf dist/
@@ -22,13 +23,15 @@ npm pack
 ### 2. Version Management
 
 Update version in `package.json`:
+
 ```json
 {
-  "version": "0.1.0"  // Follow semver: major.minor.patch
+  "version": "0.1.0" // Follow semver: major.minor.patch
 }
 ```
 
 **Semver Guidelines:**
+
 - **Patch** (0.1.X): Bug fixes, documentation updates
 - **Minor** (0.X.0): New features, backwards compatible
 - **Major** (X.0.0): Breaking changes
@@ -44,6 +47,7 @@ npm pack --dry-run
 ```
 
 Should include:
+
 - ✅ `dist/` - Compiled JavaScript + type definitions
 - ✅ `docs/` - Documentation
 - ✅ `examples/` - Example files
@@ -51,6 +55,7 @@ Should include:
 - ✅ `LICENSE` - MIT license
 
 Should NOT include:
+
 - ❌ `src/*.ts` source files (only .d.ts)
 - ❌ `node_modules/`
 - ❌ Development configs
@@ -99,11 +104,13 @@ npm view @falai/agent
 ## Post-Publish
 
 1. **Update GitHub Release**
-   - Go to https://github.com/gusnips/falai/releases
+
+   - Go to https://github.com/falai-dev/agent/releases
    - Create a new release for the tag
    - Add release notes
 
 2. **Verify Installation**
+
    ```bash
    # In a new project
    npm install @falai/agent
@@ -112,12 +119,13 @@ npm view @falai/agent
    ```
 
 3. **Test the Published Package**
+
    ```bash
    # Create test project
    mkdir test-agent && cd test-agent
    bun init -y
    bun add @falai/agent
-   
+
    # Try importing
    echo 'import { Agent } from "@falai/agent"; console.log(Agent);' > test.ts
    bun run test.ts
@@ -126,20 +134,24 @@ npm view @falai/agent
 ## Troubleshooting
 
 ### "You do not have permission to publish"
+
 - Make sure you're logged in: `npm whoami`
 - Verify you have access to the `@falai` scope
 - Contact scope owner if needed
 
 ### "Package already exists"
+
 - You can't republish the same version
 - Bump version in `package.json` and try again
 
 ### "Missing required files"
+
 - Check `package.json` `files` field
 - Ensure `dist/` exists after build
 - Run `npm pack --dry-run` to preview
 
 ### Types not working
+
 - Verify `types` field in `package.json`
 - Ensure `.d.ts` files are in `dist/`
 - Check `tsconfig.json` has `"declaration": true`

package/examples/travel-agent.ts

@@ -182,7 +182,7 @@ async function createTravelAgent() {
     apiKey: process.env.OPENROUTER_API_KEY || "test-key",
     model: "google/gemini-2.0-flash-exp",
     backupModels: ["anthropic/claude-sonnet-4-5", "openai/gpt-5"],
-    siteUrl: "https://github.com/gusnips/falai",
+    siteUrl: "https://github.com/falai-dev/agent",
     siteName: "Falai Travel Agent Example",
     retryConfig: {
       timeout: 60000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -31,12 +31,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gusnips/falai.git"
+    "url": "https://github.com/falai-dev/agent.git"
   },
   "bugs": {
-    "url": "https://github.com/gusnips/falai/issues"
+    "url": "https://github.com/falai-dev/agent/issues"
   },
-  "homepage": "https://github.com/gusnips/falai#readme",
+  "homepage": "https://github.com/falai-dev/agent#readme",
   "scripts": {
     "build": "npm run build:esm && npm run build:cjs && npm run fix:cjs",
     "build:esm": "tsc",

package/src/core/Agent.ts

@@ -405,7 +405,7 @@ export class Agent<TContext = unknown> {
         const candidates = this.routingEngine.getCandidateStates(
           selectedRoute,
           undefined,
-          session.extracted
+          session.extracted || {}
         );
         if (candidates.length > 0) {
           nextState = candidates[0].state;
@@ -438,6 +438,7 @@ export class Agent<TContext = unknown> {
       // Build response prompt
       const responsePrompt = this.responseEngine.buildResponsePrompt(
         selectedRoute,
+        nextState,
         selectedRoute.getRules(),
         selectedRoute.getProhibitions(),
         responseDirectives,
@@ -735,7 +736,7 @@ export class Agent<TContext = unknown> {
         const candidates = this.routingEngine.getCandidateStates(
           selectedRoute,
           undefined,
-          session.extracted
+          session.extracted || {}
         );
         if (candidates.length > 0) {
           nextState = candidates[0].state;
@@ -768,6 +769,7 @@ export class Agent<TContext = unknown> {
       // Build response prompt
       const responsePrompt = this.responseEngine.buildResponsePrompt(
         selectedRoute,
+        nextState,
         selectedRoute.getRules(),
         selectedRoute.getProhibitions(),
         responseDirectives,
@@ -810,7 +812,7 @@ export class Agent<TContext = unknown> {
 
         // Merge gathered data into session
         if (Object.keys(gatheredData).length > 0) {
-          session = mergeExtracted(session, gatheredData);
+          session = await this.updateExtracted(session, gatheredData);
           logger.debug(`[Agent] Extracted data:`, gatheredData);
         }
       }
@@ -1014,11 +1016,11 @@ export class Agent<TContext = unknown> {
     }
     if (routeId) {
       return (
-        (this.currentSession.extractedByRoute[
+        (this.currentSession.extractedByRoute?.[
           routeId
         ] as Partial<TExtracted>) || ({} as Partial<TExtracted>)
       );
     }
-    return this.currentSession.extracted as Partial<TExtracted>;
+    return (this.currentSession.extracted as Partial<TExtracted>) || {};
   }
 }

package/src/core/ResponseEngine.ts

@@ -44,6 +44,7 @@ export class ResponseEngine<TContext = unknown> {
 
   buildResponsePrompt(
     route: Route<TContext>,
+    currentState: State<TContext>,
     rules: string[],
     prohibitions: string[],
     directives: string[] | undefined,
@@ -71,6 +72,11 @@ export class ResponseEngine<TContext = unknown> {
         route.description ? ` — ${route.description}` : ""
       }`
     );
+    if (currentState.chatState) {
+      pc.addInstruction(
+        `Guideline for your response (adapt to the conversation):\n${currentState.chatState}`
+      );
+    }
     if (rules.length) pc.addInstruction(`Rules:\n- ${rules.join("\n- ")}`);
     if (prohibitions.length)
       pc.addInstruction(`Prohibitions:\n- ${prohibitions.join("\n- ")}`);

package/src/core/RoutingEngine.ts

@@ -87,7 +87,7 @@ export class RoutingEngine<TContext = unknown> {
     const candidates = this.getCandidateStates(
       route,
       currentState,
-      updatedSession.extracted
+      updatedSession.extracted || {}
     );
 
     if (candidates.length === 0) {
@@ -128,7 +128,7 @@ export class RoutingEngine<TContext = unknown> {
       route,
       currentState,
       candidates,
-      updatedSession.extracted,
+      updatedSession.extracted || {},
       history,
       lastUserMessage,
       agentMeta
@@ -465,7 +465,7 @@ export class RoutingEngine<TContext = unknown> {
         const candidates = this.getCandidateStates(
           activeRoute,
           currentState,
-          session.extracted
+          session.extracted || {}
         );
 
         // Check if route is complete
@@ -857,7 +857,7 @@ export class RoutingEngine<TContext = unknown> {
           sessionInfo.push(`  "${session.currentState.description}"`);
         }
       }
-      if (Object.keys(session.extracted).length > 0) {
+      if (session.extracted && Object.keys(session.extracted).length > 0) {
         sessionInfo.push(
           `- Extracted data: ${JSON.stringify(session.extracted)}`
         );

package/src/core/State.ts

@@ -23,6 +23,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
   public gatherFields?: string[];
   public skipIf?: (extracted: Partial<TExtracted>) => boolean;
   public requiredData?: string[];
+  public chatState?: string;
 
   constructor(
     public readonly routeId: string,
@@ -30,13 +31,15 @@ export class State<TContext = unknown, TExtracted = unknown> {
     customId?: string,
     gatherFields?: string[],
     skipIf?: (extracted: Partial<TExtracted>) => boolean,
-    requiredData?: string[]
+    requiredData?: string[],
+    chatState?: string
   ) {
     // Use provided ID or generate a deterministic one
     this.id = customId || generateStateId(routeId, description);
     this.gatherFields = gatherFields;
     this.skipIf = skipIf;
     this.requiredData = requiredData;
+    this.chatState = chatState;
   }
 
   /**
@@ -48,6 +51,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     gatherFields?: string[];
     skipIf?: (extracted: Partial<TExtracted>) => boolean;
     requiredData?: string[];
+    chatState?: string;
   }): this {
     if (config.description !== undefined) {
       this.description = config.description;
@@ -61,6 +65,9 @@ export class State<TContext = unknown, TExtracted = unknown> {
     if (config.requiredData !== undefined) {
       this.requiredData = config.requiredData;
     }
+    if (config.chatState !== undefined) {
+      this.chatState = config.chatState;
+    }
     return this;
   }
 
@@ -107,7 +114,8 @@ export class State<TContext = unknown, TExtracted = unknown> {
       spec.id, // Use custom ID if provided
       spec.gather,
       spec.skipIf,
-      spec.requiredData
+      spec.requiredData,
+      spec.chatState
     );
     const transition = new Transition<TContext, TExtracted>(
       this.getRef(),

package/src/types/session.ts

@@ -28,14 +28,14 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
    * Data extracted during the current route
    * This is a convenience reference to extractedByRoute[currentRoute.id]
    */
-  extracted: Partial<TExtracted>;
+  extracted?: Partial<TExtracted>;
 
   /**
    * Extracted data organized by route ID
    * Preserves data when switching between routes
    * Format: { "routeId": { ...extractedData } }
    */
-  extractedByRoute: Record<string, Partial<unknown>>;
+  extractedByRoute?: Record<string, Partial<unknown>>;
 
   /** History of routes visited in this session */
   routeHistory: Array<{
@@ -86,7 +86,11 @@ export function enterRoute<TExtracted = Record<string, unknown>>(
 ): SessionState<TExtracted> {
   // Save current route's extracted data before switching
   const extractedByRoute = { ...session.extractedByRoute };
-  if (session.currentRoute && Object.keys(session.extracted).length > 0) {
+  if (
+    session.currentRoute &&
+    session.extracted &&
+    Object.keys(session.extracted).length > 0
+  ) {
     extractedByRoute[session.currentRoute.id] = session.extracted;
   }