@falai/agent 0.4.1 → 0.5.0

package/src/core/State.ts

@@ -16,18 +16,27 @@ import { generateStateId } from "../utils/id";
 /**
  * Represents a state within a route
  */
-export class State<TContext = unknown> {
+export class State<TContext = unknown, TExtracted = unknown> {
   public readonly id: string;
-  private transitions: Transition<TContext>[] = [];
+  private transitions: Transition<TContext, TExtracted>[] = [];
   private guidelines: Guideline[] = [];
+  public readonly gatherFields?: string[];
+  public readonly skipIf?: (extracted: Partial<TExtracted>) => boolean;
+  public readonly requiredData?: string[];
 
   constructor(
     public readonly routeId: string,
     public readonly description?: string,
-    customId?: string
+    customId?: string,
+    gatherFields?: string[],
+    skipIf?: (extracted: Partial<TExtracted>) => boolean,
+    requiredData?: string[]
   ) {
     // Use provided ID or generate a deterministic one
     this.id = customId || generateStateId(routeId, description);
+    this.gatherFields = gatherFields;
+    this.skipIf = skipIf;
+    this.requiredData = requiredData;
   }
 
   /**
@@ -38,16 +47,16 @@ export class State<TContext = unknown> {
    * @returns TransitionResult that supports chaining
    */
   transitionTo(
-    spec: TransitionSpec<TContext>,
+    spec: TransitionSpec<TContext, TExtracted>,
     condition?: string
-  ): TransitionResult<TContext> {
+  ): TransitionResult<TContext, TExtracted> {
     // Handle END_ROUTE
     if (
       spec.state &&
       typeof spec.state === "symbol" &&
       spec.state === END_ROUTE
     ) {
-      const endTransition = new Transition<TContext>(
+      const endTransition = new Transition<TContext, TExtracted>(
         this.getRef(),
         { state: END_ROUTE },
         condition
@@ -60,7 +69,7 @@ export class State<TContext = unknown> {
 
     // Handle direct state reference
     if (spec.state && typeof spec.state !== "symbol") {
-      const transition = new Transition<TContext>(
+      const transition = new Transition<TContext, TExtracted>(
         this.getRef(),
         spec,
         condition
@@ -71,8 +80,19 @@ export class State<TContext = unknown> {
     }
 
     // Create new target state for chatState or toolState
-    const targetState = new State<TContext>(this.routeId, spec.chatState);
-    const transition = new Transition<TContext>(this.getRef(), spec, condition);
+    const targetState = new State<TContext, TExtracted>(
+      this.routeId,
+      spec.chatState,
+      undefined,
+      spec.gather,
+      spec.skipIf,
+      spec.requiredData
+    );
+    const transition = new Transition<TContext, TExtracted>(
+      this.getRef(),
+      spec,
+      condition
+    );
     transition.setTarget(targetState);
 
     this.transitions.push(transition);
@@ -97,10 +117,28 @@ export class State<TContext = unknown> {
   /**
    * Get all transitions from this state
    */
-  getTransitions(): Transition<TContext>[] {
+  getTransitions(): Transition<TContext, TExtracted>[] {
     return [...this.transitions];
   }
 
+  /**
+   * Check if this state should be skipped based on extracted data
+   */
+  shouldSkip(extracted: Partial<TExtracted>): boolean {
+    if (!this.skipIf) return false;
+    return this.skipIf(extracted);
+  }
+
+  /**
+   * Check if this state has all required data to proceed
+   */
+  hasRequiredData(extracted: Partial<TExtracted>): boolean {
+    if (!this.requiredData || this.requiredData.length === 0) return true;
+    return this.requiredData.every(
+      (key) => extracted[key as keyof TExtracted] !== undefined
+    );
+  }
+
   /**
    * Get state reference
    */
@@ -116,21 +154,23 @@ export class State<TContext = unknown> {
    */
   private createStateRefWithTransition(
     ref: StateRef,
-    state?: State<TContext>
-  ): TransitionResult<TContext> {
+    state?: State<TContext, TExtracted>
+  ): TransitionResult<TContext, TExtracted> {
     const stateInstance = state || this;
 
     return {
       ...ref,
-      transitionTo: (spec: TransitionSpec<TContext>, condition?: string) =>
-        stateInstance.transitionTo(spec, condition),
+      transitionTo: (
+        spec: TransitionSpec<TContext, TExtracted>,
+        condition?: string
+      ) => stateInstance.transitionTo(spec, condition),
     };
   }
 
   /**
    * Create a terminal state reference (for END_ROUTE)
    */
-  private createTerminalRef(): TransitionResult<TContext> {
+  private createTerminalRef(): TransitionResult<TContext, TExtracted> {
     const terminalRef: StateRef = {
       id: "END",
       routeId: this.routeId,

package/src/core/ToolExecutor.ts

@@ -0,0 +1,117 @@
+/**
+ * ToolExecutor - Simple utility for executing tools with context
+ *
+ * Tools execute BEFORE message generation to enrich context with data.
+ * The LLM sees the enriched context when generating responses.
+ */
+
+import type { Event } from "../types/history";
+import type { ToolRef, ToolContext } from "../types/tool";
+
+export interface ToolExecutionResult {
+  toolName: string;
+  success: boolean;
+  data?: unknown;
+  contextUpdate?: Record<string, unknown>;
+  extractedUpdate?: Record<string, unknown>;
+  error?: string;
+}
+
+export class ToolExecutor<TContext = unknown, TExtracted = unknown> {
+  /**
+   * Execute a single tool with context and extracted data
+   * @param allowedDomains - Array of domain names allowed for this execution context (undefined = all domains allowed)
+   */
+  async executeTool(
+    tool: ToolRef<TContext, unknown[], unknown>,
+    context: TContext,
+    updateContext: (updates: Partial<TContext>) => Promise<void>,
+    history: Event[],
+    extracted?: Partial<TExtracted>,
+    allowedDomains?: string[]
+  ): Promise<ToolExecutionResult> {
+    try {
+      // Domain enforcement: Check if tool's domain is allowed
+      if (allowedDomains !== undefined && tool.domainName) {
+        // allowedDomains is explicitly set (could be empty array)
+        if (!allowedDomains.includes(tool.domainName)) {
+          throw new Error(
+            `Domain security violation: Tool "${
+              tool.name
+            }" belongs to domain "${
+              tool.domainName
+            }" which is not allowed in this route. Allowed domains: [${allowedDomains.join(
+              ", "
+            )}]`
+          );
+        }
+      }
+
+      // Build tool context with extracted data
+      const toolContext: ToolContext<TContext, TExtracted> = {
+        context,
+        updateContext,
+        history,
+        extracted,
+      };
+
+      // Execute tool (no arguments - tools read from context/extracted)
+      const result = await tool.handler(toolContext);
+
+      // Return execution result
+      return {
+        toolName: tool.name,
+        success: true,
+        data: result.data,
+        contextUpdate: result.contextUpdate,
+        extractedUpdate: result.extractedUpdate,
+      };
+    } catch (error) {
+      return {
+        toolName: tool.name,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Execute multiple tools in sequence
+   * @param allowedDomains - Array of domain names allowed for this execution context (undefined = all domains allowed)
+   */
+  async executeTools(
+    tools: Array<ToolRef<TContext, unknown[], unknown>>,
+    context: TContext,
+    updateContext: (updates: Partial<TContext>) => Promise<void>,
+    history: Event[],
+    extracted?: Partial<TExtracted>,
+    allowedDomains?: string[]
+  ): Promise<ToolExecutionResult[]> {
+    const results: ToolExecutionResult[] = [];
+
+    for (const tool of tools) {
+      const result = await this.executeTool(
+        tool,
+        context,
+        updateContext,
+        history,
+        extracted,
+        allowedDomains
+      );
+      results.push(result);
+
+      // If tool failed, stop execution chain
+      if (!result.success) {
+        console.error(`[ToolExecutor] Tool ${tool.name} failed:`, result.error);
+        break;
+      }
+
+      // Apply context updates from tool result
+      if (result.contextUpdate) {
+        await updateContext(result.contextUpdate as Partial<TContext>);
+      }
+    }
+
+    return results;
+  }
+}

package/src/core/Transition.ts

@@ -8,26 +8,26 @@ import type { State } from "./State";
 /**
  * Represents a transition from one state to another
  */
-export class Transition<TContext = unknown> {
-  private target?: State<TContext>;
+export class Transition<TContext = unknown, TExtracted = unknown> {
+  private target?: State<TContext, TExtracted>;
 
   constructor(
     public readonly source: StateRef,
-    public readonly spec: TransitionSpec<TContext>,
+    public readonly spec: TransitionSpec<TContext, TExtracted>,
     public readonly condition?: string
   ) {}
 
   /**
    * Set the target state for this transition
    */
-  setTarget(state: State<TContext>): void {
+  setTarget(state: State<TContext, TExtracted>): void {
     this.target = state;
   }
 
   /**
    * Get the target state
    */
-  getTarget(): State<TContext> | undefined {
+  getTarget(): State<TContext, TExtracted> | undefined {
     return this.target;
   }
 

package/src/index.ts

@@ -9,14 +9,12 @@ export { Agent } from "./core/Agent";
 export { Route } from "./core/Route";
 export { State } from "./core/State";
 export { Transition } from "./core/Transition";
-export { Observation } from "./core/Observation";
 export { defineTool } from "./core/Tool";
 export { DomainRegistry } from "./core/DomainRegistry";
 export { adaptEvent, createMessageEvent, createToolEvent } from "./core/Events";
-export { PromptBuilder } from "./core/PromptBuilder";
-export type { Customer, AgentInfo } from "./core/PromptBuilder";
-export { BuiltInSection } from "./core/PromptBuilder";
 export { PersistenceManager } from "./core/PersistenceManager";
+export { ToolExecutor } from "./core/ToolExecutor";
+export type { ToolExecutionResult } from "./core/ToolExecutor";
 
 // Providers
 export { GeminiProvider } from "./providers/GeminiProvider";
@@ -67,12 +65,7 @@ export type {
 export { END_ROUTE } from "./constants";
 
 // Utils
-export {
-  generateRouteId,
-  generateStateId,
-  generateObservationId,
-  generateToolId,
-} from "./utils/id";
+export { generateRouteId, generateStateId, generateToolId } from "./utils/id";
 
 // Types
 export type {
@@ -104,6 +97,14 @@ export type {
   TransitionResult,
 } from "./types/route";
 
+export type { SessionState } from "./types/session";
+export {
+  createSession,
+  enterRoute,
+  enterState,
+  mergeExtracted,
+} from "./types/session";
+
 export type {
   ToolContext,
   ToolResult,
@@ -119,17 +120,7 @@ export type {
   ReasoningConfig,
 } from "./types/ai";
 
-export type {
-  PromptSection,
-  ContextVariable,
-  ContextVariableValue,
-} from "./types/prompt";
-export { SectionStatus } from "./types/prompt";
-
-export type {
-  Observation as IObservation,
-  ObservationOptions,
-} from "./types/observation";
+export type { StructuredSchema } from "./types/schema";
 
 export type {
   SessionData,

package/src/providers/AnthropicProvider.ts

@@ -258,13 +258,10 @@ export class AnthropicProvider implements AiProvider {
         ...this.config,
       };
 
-      // Handle JSON mode if requested
-      // Note: Anthropic doesn't have a native JSON mode like OpenAI,
-      // but we can add it to the system prompt
-      if (input.parameters?.jsonMode) {
-        // Add system message requesting JSON output
+      // Handle schema: Anthropic doesn't have a native schema mode, so embed constraints
+      if (input.parameters?.jsonSchema) {
         const systemPrompt =
-          "You must respond with valid JSON only. Do not include any text outside the JSON structure.";
+          "You must respond with valid JSON only and it MUST match the provided schema.";
 
         // Merge with existing system if present
         if (typeof this.config?.system === "string") {
@@ -294,9 +291,9 @@ export class AnthropicProvider implements AiProvider {
         throw new Error("No response from Anthropic");
       }
 
-      // Parse JSON response if JSON mode was enabled
+      // Parse JSON response if schema was provided
       let structured: AgentStructuredResponse | undefined;
-      if (input.parameters?.jsonMode) {
+      if (input.parameters?.jsonSchema) {
         try {
           structured = JSON.parse(message) as AgentStructuredResponse;
         } catch (error) {
@@ -418,10 +415,10 @@ export class AnthropicProvider implements AiProvider {
       ...this.config,
     };
 
-    // Handle JSON mode if requested
-    if (input.parameters?.jsonMode) {
+    // Handle schema in streaming: embed constraint
+    if (input.parameters?.jsonSchema) {
       const systemPrompt =
-        "You must respond with valid JSON only. Do not include any text outside the JSON structure.";
+        "You must respond with valid JSON only and it MUST match the provided schema.";
 
       if (typeof this.config?.system === "string") {
         params.system = `${this.config.system}\n\n${systemPrompt}`;
@@ -466,9 +463,9 @@ export class AnthropicProvider implements AiProvider {
       }
     }
 
-    // Parse JSON response if JSON mode was enabled
+    // Parse JSON response if schema was provided
     let structured: AgentStructuredResponse | undefined;
-    if (input.parameters?.jsonMode && accumulated) {
+    if (input.parameters?.jsonSchema && accumulated) {
       try {
         structured = JSON.parse(accumulated) as AgentStructuredResponse;
       } catch (error) {

package/src/providers/GeminiProvider.ts

@@ -235,10 +235,13 @@ export class GeminiProvider implements AiProvider {
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput<TStructured>> {
     const operation = async (): Promise<GenerateMessageOutput> => {
-      // Enable JSON mode if requested
+      // Schema-required: configure response schema
       const configOverride: Partial<GenerateContentConfig> = { ...this.config };
-      if (input.parameters?.jsonMode) {
+      if (input.parameters?.jsonSchema) {
         configOverride.responseMimeType = "application/json";
+        // Gemini expects responseSchema. We pass through our schema as-is.
+        // A deeper mapping can be added via utils if needed.
+        configOverride.responseSchema = input.parameters.jsonSchema;
       }
 
       const response: GenerateContentResponse =
@@ -253,9 +256,9 @@ export class GeminiProvider implements AiProvider {
         throw new Error("No response from Gemini");
       }
 
-      // Parse JSON response if JSON mode was enabled
+      // Parse JSON response if schema was provided
       let structured: AgentStructuredResponse | undefined;
-      if (input.parameters?.jsonMode) {
+      if (input.parameters?.jsonSchema) {
         try {
           structured = JSON.parse(message) as AgentStructuredResponse;
         } catch (error) {
@@ -353,10 +356,11 @@ export class GeminiProvider implements AiProvider {
     model: string,
     input: GenerateMessageInput<TContext>
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
-    // Enable JSON mode if requested
+    // Streaming: request JSON if schema provided
     const configOverride: Partial<GenerateContentConfig> = { ...this.config };
-    if (input.parameters?.jsonMode) {
+    if (input.parameters?.jsonSchema) {
       configOverride.responseMimeType = "application/json";
+      configOverride.responseSchema = input.parameters.jsonSchema;
     }
 
     const stream = await this.genAI.models.generateContentStream({
@@ -390,9 +394,9 @@ export class GeminiProvider implements AiProvider {
       }
     }
 
-    // Parse JSON response if JSON mode was enabled
+    // Parse JSON response if schema was provided
     let structured: AgentStructuredResponse | undefined;
-    if (input.parameters?.jsonMode && accumulated) {
+    if (input.parameters?.jsonSchema && accumulated) {
       try {
         structured = JSON.parse(accumulated) as AgentStructuredResponse;
       } catch (error) {

package/src/providers/OpenAIProvider.ts

@@ -266,53 +266,8 @@ export class OpenAIProvider implements AiProvider {
         params.max_tokens = input.parameters.maxOutputTokens;
       }
 
-      // Use structured output API if JSON mode is enabled
-      if (input.parameters?.jsonMode) {
-        // Define the JSON schema for agent response
-        const agentResponseSchema = {
-          type: "object",
-          properties: {
-            message: {
-              type: "string",
-              description: "The actual message to send to the user",
-            },
-            route: {
-              type: ["string", "null"],
-              description:
-                "The title of the route chosen (or null if no specific route)",
-            },
-            state: {
-              type: ["string", "null"],
-              description:
-                "The current state within the route (or null if not in a route)",
-            },
-            toolCalls: {
-              type: "array",
-              items: {
-                type: "object",
-                properties: {
-                  toolName: {
-                    type: "string",
-                    description: "Name of the tool to call",
-                  },
-                  arguments: {
-                    type: "object",
-                    description: "Arguments to pass to the tool",
-                  },
-                },
-                required: ["toolName", "arguments"],
-              },
-              description: "Tool calls the agent wants to execute",
-            },
-            reasoning: {
-              type: "string",
-              description: "Optional: Internal reasoning for this response",
-            },
-          },
-          required: ["message"],
-          additionalProperties: false,
-        };
-
+      // Use structured output API if JSON schema is provided
+      if (input.parameters?.jsonSchema) {
         const response = await this.client.responses.parse({
           model,
           instructions: input.prompt,
@@ -323,8 +278,8 @@ export class OpenAIProvider implements AiProvider {
           text: {
             format: {
               type: "json_schema",
-              name: "agentResponseSchema",
-              schema: agentResponseSchema,
+              name: input.parameters?.schemaName || "structured_output",
+              schema: input.parameters.jsonSchema,
             },
           },
         });
@@ -348,7 +303,7 @@ export class OpenAIProvider implements AiProvider {
         };
       }
 
-      // Fall back to regular chat completions API if JSON mode not enabled
+      // Fall back to regular chat completions API if no schema provided
       const response = await this.client.chat.completions.create(params);
 
       const message = response.choices[0]?.message?.content;
@@ -468,10 +423,9 @@ export class OpenAIProvider implements AiProvider {
       params.max_tokens = input.parameters.maxOutputTokens;
     }
 
-    // Use JSON mode if requested
-    // Note: OpenAI streaming doesn't support the responses.parse API,
-    // so we use response_format with JSON mode instead
-    if (input.parameters?.jsonMode) {
+    // Streaming path does not support responses.parse; if schema present,
+    // request JSON object and parse at the end.
+    if (input.parameters?.jsonSchema) {
       params.response_format = { type: "json_object" };
     }
 
@@ -509,9 +463,9 @@ export class OpenAIProvider implements AiProvider {
       }
     }
 
-    // Parse JSON response if JSON mode was enabled
+    // Parse JSON response if schema was provided
     let structured: TStructured | undefined;
-    if (input.parameters?.jsonMode && accumulated) {
+    if (input.parameters?.jsonSchema && accumulated) {
       try {
         structured = JSON.parse(accumulated) as TStructured;
       } catch (error) {

package/src/providers/OpenRouterProvider.ts

@@ -273,53 +273,8 @@ export class OpenRouterProvider implements AiProvider {
         params.max_tokens = input.parameters.maxOutputTokens;
       }
 
-      // Use structured output API if JSON mode is enabled
-      if (input.parameters?.jsonMode) {
-        // Define the JSON schema for agent response
-        const agentResponseSchema = {
-          type: "object",
-          properties: {
-            message: {
-              type: "string",
-              description: "The actual message to send to the user",
-            },
-            route: {
-              type: ["string", "null"],
-              description:
-                "The title of the route chosen (or null if no specific route)",
-            },
-            state: {
-              type: ["string", "null"],
-              description:
-                "The current state within the route (or null if not in a route)",
-            },
-            toolCalls: {
-              type: "array",
-              items: {
-                type: "object",
-                properties: {
-                  toolName: {
-                    type: "string",
-                    description: "Name of the tool to call",
-                  },
-                  arguments: {
-                    type: "object",
-                    description: "Arguments to pass to the tool",
-                  },
-                },
-                required: ["toolName", "arguments"],
-              },
-              description: "Tool calls the agent wants to execute",
-            },
-            reasoning: {
-              type: "string",
-              description: "Optional: Internal reasoning for this response",
-            },
-          },
-          required: ["message"],
-          additionalProperties: false,
-        };
-
+      // Use structured output API if JSON schema is provided
+      if (input.parameters?.jsonSchema) {
         const response = await this.client.responses.parse({
           model,
           instructions: input.prompt,
@@ -330,8 +285,8 @@ export class OpenRouterProvider implements AiProvider {
           text: {
             format: {
               type: "json_schema",
-              name: "agentResponseSchema",
-              schema: agentResponseSchema,
+              name: input.parameters?.schemaName || "structured_output",
+              schema: input.parameters.jsonSchema,
             },
           },
         });
@@ -355,7 +310,7 @@ export class OpenRouterProvider implements AiProvider {
         };
       }
 
-      // Fall back to regular chat completions API if JSON mode not enabled
+      // Fall back to regular chat completions API if no schema provided
       const response = await this.client.chat.completions.create(params);
 
       const message = response.choices[0]?.message?.content;
@@ -469,10 +424,9 @@ export class OpenRouterProvider implements AiProvider {
       params.max_tokens = input.parameters.maxOutputTokens;
     }
 
-    // Use JSON mode if requested
-    // Note: OpenRouter streaming doesn't support the responses.parse API,
-    // so we use response_format with JSON mode instead
-    if (input.parameters?.jsonMode) {
+    // Streaming path does not support responses.parse; if schema present,
+    // request JSON object and parse at the end.
+    if (input.parameters?.jsonSchema) {
       params.response_format = { type: "json_object" };
     }
 
@@ -510,9 +464,9 @@ export class OpenRouterProvider implements AiProvider {
       }
     }
 
-    // Parse JSON response if JSON mode was enabled
+    // Parse JSON response if schema was provided
     let structured: TStructured | undefined;
-    if (input.parameters?.jsonMode && accumulated) {
+    if (input.parameters?.jsonSchema && accumulated) {
       try {
         structured = JSON.parse(accumulated) as TStructured;
       } catch (error) {