@falai/agent 0.8.1 → 0.9.0-alpha-2

package/src/core/ToolExecutor.ts

@@ -5,70 +5,75 @@
  * The LLM sees the enriched context when generating responses.
  */
 
-import type { Event } from "../types/history";
-import type { ToolRef, ToolContext } from "../types/tool";
+import type { Event, Tool, ToolContext } from "../types";
 
 export interface ToolExecutionResult {
   toolName: string;
   success: boolean;
   data?: unknown;
   contextUpdate?: Record<string, unknown>;
-  collectedUpdate?: Record<string, unknown>;
+  dataUpdate?: Record<string, unknown>;
   error?: string;
 }
 
+export interface ExecuteToolParams<TContext = unknown, TData = unknown> {
+  tool: Tool<TContext, TData, unknown[], unknown>;
+  context: TContext;
+  updateContext: (updates: Partial<TContext>) => Promise<void>;
+  updateData: (updates: Partial<TData>) => Promise<void>;
+  history: Event[];
+  data?: Partial<TData>;
+  toolArguments?: Record<string, unknown>;
+}
+
+export interface ExecuteToolsParams<TContext = unknown, TData = unknown> {
+  tools: Array<Tool<TContext, TData, unknown[], unknown>>;
+  context: TContext;
+  updateContext: (updates: Partial<TContext>) => Promise<void>;
+  updateData: (updates: Partial<TData>) => Promise<void>;
+  history: Event[];
+  data?: Partial<TData>;
+}
+
 export class ToolExecutor<TContext = unknown, TData = unknown> {
   /**
    * Execute a single tool with context and collected data
-   * @param allowedDomains - Array of domain names allowed for this execution context (undefined = all domains allowed)
+   * @param params - Execution parameters
    */
   async executeTool(
-    tool: ToolRef<TContext, unknown[], unknown>,
-    context: TContext,
-    updateContext: (updates: Partial<TContext>) => Promise<void>,
-    history: Event[],
-    data?: Partial<TData>,
-    allowedDomains?: string[]
+    params: ExecuteToolParams<TContext, TData>
   ): Promise<ToolExecutionResult> {
+    const { tool, context, updateContext, updateData, history, data, toolArguments } =
+      params;
     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 collected data
+      // Build tool context with complete agent data
       const toolContext: ToolContext<TContext, TData> = {
         context,
         updateContext,
+        updateData,
         history,
         data,
       };
 
-      // Execute tool (no arguments - tools read from context/data)
-      const result = await tool.handler(toolContext);
+      // Execute tool
+      const result = await tool.handler(toolContext, toolArguments);
+
+      // Apply data updates from tool result
+      if (result.dataUpdate) {
+        await updateData(result.dataUpdate);
+      }
 
       // Return execution result
       return {
-        toolName: tool.name,
+        toolName: tool.id || "unknown",
         success: true,
         data: result.data,
         contextUpdate: result.contextUpdate,
-        collectedUpdate: result.collectedUpdate,
+        dataUpdate: result.dataUpdate,
       };
     } catch (error) {
       return {
-        toolName: tool.name,
+        toolName: tool.id || "unknown",
         success: false,
         error: error instanceof Error ? error.message : String(error),
       };
@@ -77,32 +82,31 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
 
   /**
    * Execute multiple tools in sequence
-   * @param allowedDomains - Array of domain names allowed for this execution context (undefined = all domains allowed)
+   * @param params - Execution parameters
    */
   async executeTools(
-    tools: Array<ToolRef<TContext, unknown[], unknown>>,
-    context: TContext,
-    updateContext: (updates: Partial<TContext>) => Promise<void>,
-    history: Event[],
-    data?: Partial<TData>,
-    allowedDomains?: string[]
+    params: ExecuteToolsParams<TContext, TData>
   ): Promise<ToolExecutionResult[]> {
+    const { tools, context, updateContext, updateData, history, data } = params;
     const results: ToolExecutionResult[] = [];
 
     for (const tool of tools) {
-      const result = await this.executeTool(
+      const result = await this.executeTool({
         tool,
         context,
         updateContext,
+        updateData,
         history,
         data,
-        allowedDomains
-      );
+      });
       results.push(result);
 
       // If tool failed, stop execution chain
       if (!result.success) {
-        console.error(`[ToolExecutor] Tool ${tool.name} failed:`, result.error);
+        console.error(
+          `[ToolExecutor] Tool ${tool.id || "unknown"} failed:`,
+          result.error
+        );
         break;
       }
 
@@ -110,6 +114,11 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
       if (result.contextUpdate) {
         await updateContext(result.contextUpdate as Partial<TContext>);
       }
+
+      // Apply data updates from tool result
+      if (result.dataUpdate) {
+        await updateData(result.dataUpdate as Partial<TData>);
+      }
     }
 
     return results;

package/src/index.ts

@@ -8,11 +8,9 @@
 export { Agent } from "./core/Agent";
 export { Route } from "./core/Route";
 export { Step } from "./core/Step";
-export { Transition } from "./core/Transition";
-export { defineTool } from "./core/Tool";
-export { DomainRegistry } from "./core/DomainRegistry";
-export { adaptEvent, createMessageEvent, createToolEvent } from "./core/Events";
+export { adaptEvent, convertHistoryToEvents } from "./core/Events";
 export { PersistenceManager } from "./core/PersistenceManager";
+export { SessionManager } from "./core/SessionManager";
 export { ToolExecutor } from "./core/ToolExecutor";
 export type { ToolExecutionResult } from "./core/ToolExecutor";
 
@@ -66,72 +64,68 @@ export { END_ROUTE, END_ROUTE_ID } from "./constants";
 
 // Utils
 export { generateRouteId, generateStepId, generateToolId } from "./utils/id";
+export { formatKnowledgeBase } from "./utils/template";
+export {
+  normalizeHistory,
+  userMessage,
+  assistantMessage,
+  toolMessage,
+  systemMessage,
+} from "./utils/history";
 
 // Types
 export type {
   AgentOptions,
   Term,
   Guideline,
-  Capability,
   GuidelineMatch,
   ContextLifecycleHooks,
   ContextProvider,
-} from "./types/agent";
-export { CompositionMode } from "./types/agent";
-
-export type {
   Event,
   EmittedEvent,
   MessageEventData,
   ToolEventData,
   StatusEventData,
   Participant,
-} from "./types/history";
-export { EventKind, EventSource } from "./types/history";
-
-export type {
   RouteRef,
   StepRef,
   RouteOptions,
-  TransitionSpec,
-  TransitionResult,
+  StepOptions,
+  StepResult,
   RouteTransitionConfig,
   RouteCompletionHandler,
-} from "./types/route";
-
-export type { SessionState, PendingTransition } from "./types/session";
-export {
-  createSession,
-  enterRoute,
-  enterStep,
-  mergeCollected,
-} from "./types/session";
-
-export type {
+  SessionState,
+  PendingTransition,
   ToolContext,
   ToolResult,
   ToolHandler,
-  ToolRef,
-} from "./types/tool";
-
-export type {
+  Tool,
   AiProvider,
   GenerateMessageInput,
   GenerateMessageOutput,
   AgentStructuredResponse,
   ReasoningConfig,
-} from "./types/ai";
-
-export type { StructuredSchema } from "./types/schema";
-
-export type {
+  StructuredSchema,
   SessionData,
   MessageData,
+  CollectedStateData,
   SessionStatus,
-  MessageRole,
   SessionRepository,
   MessageRepository,
   PersistenceConfig,
   CreateSessionOptions,
   SaveMessageOptions,
-} from "./types/persistence";
+  AgentResponseStreamChunk,
+  Role,
+  HistoryItem,
+  History,
+  PersistenceAdapter,
+  Template,
+  TemplateContext,
+  UserHistoryItem,
+  AssistantHistoryItem,
+  ToolHistoryItem,
+  SystemHistoryItem,
+} from "./types";
+export { CompositionMode, EventKind, MessageRole } from "./types";
+export { createSession, enterRoute, enterStep, mergeCollected } from "./utils";

package/src/providers/AnthropicProvider.ts

@@ -3,7 +3,10 @@
  */
 
 import Anthropic from "@anthropic-ai/sdk";
-import type { MessageCreateParamsNonStreaming } from "@anthropic-ai/sdk/resources/messages";
+import type {
+  MessageCreateParamsNonStreaming,
+  Tool,
+} from "@anthropic-ai/sdk/resources/messages";
 
 import type {
   AiProvider,
@@ -11,7 +14,7 @@ import type {
   GenerateMessageOutput,
   GenerateMessageStreamChunk,
   AgentStructuredResponse,
-} from "../types/ai";
+} from "../types";
 import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
@@ -258,6 +261,15 @@ export class AnthropicProvider implements AiProvider {
         ...this.config,
       };
 
+      // Add tools if provided
+      if (input.tools && input.tools.length > 0) {
+        params.tools = input.tools.map((tool) => ({
+          name: tool.name || tool.id,
+          description: tool.description || "",
+          input_schema: tool.parameters as Tool["input_schema"], // JSON schema
+        }));
+      }
+
       // Handle schema: Anthropic doesn't have a native schema mode, so embed constraints
       if (input.parameters?.jsonSchema) {
         const systemPrompt =
@@ -281,7 +293,7 @@ export class AnthropicProvider implements AiProvider {
 
       const response = await this.client.messages.create(params);
 
-      // Extract text from response
+      // Extract text and tool calls from response
       const textContent = response.content.find(
         (block) => block.type === "text"
       );
@@ -291,6 +303,22 @@ export class AnthropicProvider implements AiProvider {
         throw new Error("No response from Anthropic");
       }
 
+      // Extract tool calls from response
+      const toolCalls: Array<{
+        toolName: string;
+        arguments: Record<string, unknown>;
+      }> = [];
+
+      // Check for tool_use content blocks
+      for (const block of response.content) {
+        if (block.type === "tool_use") {
+          toolCalls.push({
+            toolName: block.name,
+            arguments: block.input as Record<string, unknown>,
+          });
+        }
+      }
+
       // Parse JSON response if schema was provided
       let structured: AgentStructuredResponse | undefined;
       if (input.parameters?.jsonSchema) {
@@ -302,6 +330,15 @@ export class AnthropicProvider implements AiProvider {
         }
       }
 
+      // If tools were used, include them in structured response
+      if (toolCalls.length > 0) {
+        structured = {
+          message,
+          toolCalls,
+          ...structured,
+        } as AgentStructuredResponse;
+      }
+
       return {
         message,
         metadata: {
@@ -415,6 +452,15 @@ export class AnthropicProvider implements AiProvider {
       ...this.config,
     };
 
+    // Add tools if provided
+    if (input.tools && input.tools.length > 0) {
+      params.tools = input.tools.map((tool) => ({
+        name: tool.name || tool.id,
+        description: tool.description || "",
+        input_schema: tool.parameters as Tool["input_schema"], // JSON schema
+      }));
+    }
+
     // Handle schema in streaming: embed constraint
     if (input.parameters?.jsonSchema) {
       const systemPrompt =
@@ -442,11 +488,22 @@ export class AnthropicProvider implements AiProvider {
     let stopReason: string | undefined;
     let inputTokens = 0;
     let outputTokens = 0;
+    const toolCalls: Array<{
+      toolName: string;
+      arguments: Record<string, unknown>;
+    }> = [];
 
     for await (const chunk of stream) {
       if (chunk.type === "message_start") {
         currentModel = chunk.message.model;
         inputTokens = chunk.message.usage.input_tokens;
+      } else if (chunk.type === "content_block_start") {
+        if (chunk.content_block.type === "tool_use") {
+          toolCalls.push({
+            toolName: chunk.content_block.name,
+            arguments: chunk.content_block.input as Record<string, unknown>,
+          });
+        }
       } else if (chunk.type === "content_block_delta") {
         if (chunk.delta.type === "text_delta") {
           const delta = chunk.delta.text;
@@ -476,6 +533,15 @@ export class AnthropicProvider implements AiProvider {
       }
     }
 
+    // If tools were used, include them in structured response
+    if (toolCalls.length > 0) {
+      structured = {
+        message: accumulated,
+        toolCalls,
+        ...structured,
+      } as AgentStructuredResponse;
+    }
+
     // Yield final chunk
     yield {
       delta: "",
@@ -488,7 +554,7 @@ export class AnthropicProvider implements AiProvider {
         promptTokens: inputTokens,
         completionTokens: outputTokens,
       },
-      structured,
-    } as GenerateMessageStreamChunk<TStructured>;
+      structured: structured as TStructured,
+    };
   }
 }

package/src/providers/GeminiProvider.ts

@@ -7,6 +7,7 @@ import type {
   GenerateContentConfig,
   GenerateContentResponse,
   Schema,
+  FunctionDeclaration,
 } from "@google/genai";
 import { GoogleGenAI, Type } from "@google/genai";
 
@@ -16,8 +17,8 @@ import type {
   GenerateMessageOutput,
   GenerateMessageStreamChunk,
   AgentStructuredResponse,
-} from "../types/ai";
-import type { StructuredSchema } from "../types/schema";
+  StructuredSchema,
+} from "../types";
 import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
@@ -342,6 +343,20 @@ export class GeminiProvider implements AiProvider {
     const operation = async (): Promise<GenerateMessageOutput> => {
       // Schema-required: configure response schema
       const configOverride: Partial<GenerateContentConfig> = { ...this.config };
+
+      // Add tools if provided
+      if (input.tools && input.tools.length > 0) {
+        configOverride.tools = [
+          {
+            functionDeclarations: input.tools.map((tool) => ({
+              name: tool.name || tool.id,
+              description: tool.description || "",
+              parameters: tool.parameters as FunctionDeclaration["parameters"], // JSON schema
+            })),
+          },
+        ];
+      }
+
       if (input.parameters?.jsonSchema) {
         configOverride.responseMimeType = "application/json";
         // Adapt common schema format to Gemini's specific requirements
@@ -362,6 +377,24 @@ export class GeminiProvider implements AiProvider {
         throw new Error("No response from Gemini");
       }
 
+      // Extract tool calls from response
+      const toolCalls: Array<{
+        toolName: string;
+        arguments: Record<string, unknown>;
+      }> = [];
+
+      // Check for function calls in the response content
+      if (response.candidates && response.candidates[0]?.content?.parts) {
+        for (const part of response.candidates[0].content.parts) {
+          if (part.functionCall) {
+            toolCalls.push({
+              toolName: part.functionCall.name || "",
+              arguments: part.functionCall.args as Record<string, unknown>,
+            });
+          }
+        }
+      }
+
       // Parse JSON response if schema was provided
       let structured: AgentStructuredResponse | undefined;
       if (input.parameters?.jsonSchema) {
@@ -373,6 +406,15 @@ export class GeminiProvider implements AiProvider {
         }
       }
 
+      // If tools were used, include them in structured response
+      if (toolCalls.length > 0) {
+        structured = {
+          message,
+          toolCalls,
+          ...structured,
+        } as AgentStructuredResponse;
+      }
+
       return {
         message,
         metadata: {
@@ -464,6 +506,20 @@ export class GeminiProvider implements AiProvider {
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Streaming: request JSON if schema provided
     const configOverride: Partial<GenerateContentConfig> = { ...this.config };
+
+    // Add tools if provided
+    if (input.tools && input.tools.length > 0) {
+      configOverride.tools = [
+        {
+          functionDeclarations: input.tools.map((tool) => ({
+            name: tool.name || tool.id,
+            description: tool.description || "",
+            parameters: tool.parameters as FunctionDeclaration["parameters"],
+          })),
+        },
+      ];
+    }
+
     if (input.parameters?.jsonSchema) {
       configOverride.responseMimeType = "application/json";
       // Adapt common schema format to Gemini's specific requirements
@@ -482,10 +538,26 @@ export class GeminiProvider implements AiProvider {
     let promptTokenCount = 0;
     let candidatesTokenCount = 0;
     let totalTokenCount = 0;
+    const toolCalls: Array<{
+      toolName: string;
+      arguments: Record<string, unknown>;
+    }> = [];
 
     for await (const chunk of stream) {
       const delta = chunk.text || "";
 
+      // Extract tool calls from chunk
+      if (chunk.candidates && chunk.candidates[0]?.content?.parts) {
+        for (const part of chunk.candidates[0].content.parts) {
+          if (part.functionCall) {
+            toolCalls.push({
+              toolName: part.functionCall.name || "",
+              arguments: part.functionCall.args as Record<string, unknown>,
+            });
+          }
+        }
+      }
+
       if (delta) {
         accumulated += delta;
         yield {
@@ -516,6 +588,15 @@ export class GeminiProvider implements AiProvider {
       }
     }
 
+    // If tools were used, include them in structured response
+    if (toolCalls.length > 0) {
+      structured = {
+        message: accumulated,
+        toolCalls,
+        ...structured,
+      } as AgentStructuredResponse;
+    }
+
     // Yield final chunk
     yield {
       delta: "",