@falai/agent 0.8.1 → 0.9.0-alpha-1

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: "",

package/src/providers/OpenAIProvider.ts

@@ -11,9 +11,10 @@ import type {
   GenerateMessageOutput,
   GenerateMessageStreamChunk,
   AgentStructuredResponse,
-} from "../types/ai";
-import type { StructuredSchema } from "../types/schema";
+  StructuredSchema,
+} from "../types";
 import { withTimeoutAndRetry } from "../utils/retry";
+import { FunctionParameters } from "openai/resources/shared.mjs";
 
 const DEFAULT_RETRY_CONFIG = {
   timeout: 60000,
@@ -281,6 +282,19 @@ export class OpenAIProvider implements AiProvider {
         params.max_tokens = input.parameters.maxOutputTokens;
       }
 
+      // Add tools if provided
+      if (input.tools && input.tools.length > 0) {
+        params.tools = input.tools.map((tool) => ({
+          type: "function" as const,
+          function: {
+            name: tool.name || tool.id,
+            description: tool.description,
+            parameters: tool.parameters as FunctionParameters, // JSON schema
+          },
+        }));
+        params.tool_choice = "auto";
+      }
+
       // Use structured output API if JSON schema is provided
       if (input.parameters?.jsonSchema) {
         const response = await this.client.responses.parse({
@@ -327,6 +341,35 @@ export class OpenAIProvider implements AiProvider {
         throw new Error("No response from OpenAI");
       }
 
+      let toolCalls: Array<{
+        toolName: string;
+        arguments: Record<string, unknown>;
+      }> = [];
+      if (response.choices?.[0]?.message?.tool_calls) {
+        toolCalls = response.choices[0].message.tool_calls
+          .filter((toolCall) => toolCall.type === "function")
+          .map((toolCall) => {
+            let toolCallArguments: Record<string, unknown> = {};
+            try {
+              toolCallArguments = JSON.parse(
+                toolCall.function.arguments
+              ) as Record<string, unknown>;
+            } catch (error) {
+              console.warn(
+                `[OPENAI] Failed to parse tool call arguments: ${getErrorMessage(
+                  error
+                )}`
+              );
+              toolCallArguments = {};
+            }
+            return {
+              toolName: toolCall.function.name,
+              arguments: toolCallArguments,
+            };
+          });
+      }
+      // Extract tool calls from response
+
       return {
         message,
         metadata: {
@@ -336,6 +379,10 @@ export class OpenAIProvider implements AiProvider {
           promptTokens: response.usage?.prompt_tokens,
           completionTokens: response.usage?.completion_tokens,
         },
+        structured:
+          toolCalls.length > 0
+            ? ({ message, toolCalls } as AgentStructuredResponse)
+            : undefined,
       };
     };
 
@@ -439,6 +486,19 @@ export class OpenAIProvider implements AiProvider {
       params.max_tokens = input.parameters.maxOutputTokens;
     }
 
+    // Add tools if provided
+    if (input.tools && input.tools.length > 0) {
+      params.tools = input.tools.map((tool) => ({
+        type: "function" as const,
+        function: {
+          name: tool.name || tool.id,
+          description: tool.description,
+          parameters: tool.parameters as FunctionParameters, // JSON schema
+        },
+      }));
+      params.tool_choice = "auto";
+    }
+
     // Streaming path does not support responses.parse; if schema present,
     // request JSON object and parse at the end.
     if (input.parameters?.jsonSchema) {
@@ -453,11 +513,43 @@ export class OpenAIProvider implements AiProvider {
     let promptTokens: number | undefined;
     let completionTokens: number | undefined;
     let totalTokens: number | undefined;
+    const toolCalls: Array<{
+      toolName: string;
+      arguments: Record<string, unknown>;
+    }> = [];
 
     for await (const chunk of stream) {
       currentModel = chunk.model;
       const delta = chunk.choices[0]?.delta?.content || "";
 
+      // Extract tool calls from delta
+      if (chunk.choices[0]?.delta?.tool_calls) {
+        for (const toolCall of chunk.choices[0].delta.tool_calls) {
+          if (toolCall.function) {
+            let toolCallArguments: Record<string, unknown> = {};
+            try {
+              toolCallArguments = toolCall.function.arguments
+                ? (JSON.parse(toolCall.function.arguments) as Record<
+                    string,
+                    unknown
+                  >)
+                : {};
+            } catch (error) {
+              console.warn(
+                `[OPENAI] Failed to parse tool call arguments in stream: ${getErrorMessage(
+                  error
+                )}`
+              );
+              toolCallArguments = {};
+            }
+            toolCalls.push({
+              toolName: toolCall.function.name || "",
+              arguments: toolCallArguments,
+            });
+          }
+        }
+      }
+
       if (delta) {
         accumulated += delta;
         yield {
@@ -504,7 +596,7 @@ export class OpenAIProvider implements AiProvider {
         promptTokens,
         completionTokens,
       },
-      structured,
+      structured: structured ? { ...structured, toolCalls } : undefined,
     };
   }
 }