@falai/agent 1.1.2 → 1.2.0

package/src/providers/GeminiProvider.ts

@@ -152,6 +152,66 @@ export class GeminiProvider implements AiProvider {
     };
   }
 
+  /**
+   * Convert tool parameter schemas (JSON Schema) to Gemini's Schema format.
+   * Gemini's FunctionDeclaration.parameters expects its own Schema type,
+   * not raw JSON Schema. This method handles the conversion, including
+   * edge cases like empty objects that Gemini rejects.
+   *
+   * @private
+   */
+  private convertToolParameters(parameters: unknown): Schema | undefined {
+    if (!parameters || typeof parameters !== "object") {
+      return undefined;
+    }
+    try {
+      return this.adaptSchemaForGemini(parameters as StructuredSchema);
+    } catch (error) {
+      logger.warn(`[GeminiProvider] Failed to convert tool parameters, passing as-is:`, error);
+      return parameters as Schema;
+    }
+  }
+
+  /**
+   * Safely extract text from a Gemini response or chunk.
+   * The `.text` getter can throw when the response contains only function calls
+   * (observed in some SDK versions). This method falls back to manually
+   * extracting text parts from candidates.
+   *
+   * @private
+   */
+  private safeExtractText(responseOrChunk: { text?: string; candidates?: Array<{ content?: { parts?: Array<{ text?: string; functionCall?: unknown }> } }> }): string {
+    try {
+      return responseOrChunk.text || "";
+    } catch {
+      // .text getter threw — extract text parts manually
+      const parts = responseOrChunk.candidates?.[0]?.content?.parts;
+      if (parts) {
+        return parts
+          .filter((p) => p.text != null)
+          .map((p) => p.text)
+          .join("");
+      }
+      return "";
+    }
+  }
+
+  /**
+   * Build Gemini function declarations from framework tool definitions.
+   * Converts JSON Schema parameters to Gemini's Schema format.
+   *
+   * @private
+   */
+  private buildFunctionDeclarations(
+    tools: Array<{ id: string; name?: string; description?: string; parameters?: unknown }>
+  ): FunctionDeclaration[] {
+    return tools.map((tool) => ({
+      name: tool.name || tool.id,
+      description: tool.description || "",
+      parameters: this.convertToolParameters(tool.parameters),
+    }));
+  }
+
   /**
    * Adapt common schema format to Gemini's specific requirements.
    * Gemini has strict validation:
@@ -356,15 +416,8 @@ export class GeminiProvider implements AiProvider {
       if (hasTools) {
         const toolNames = input.tools?.map((tool) => tool.name || tool.id) || [];
         logger.debug(`[GeminiProvider] Configuring ${toolNames.length} tools for model ${model}:`, toolNames);
-        configOverride.tools = [
-          {
-            functionDeclarations: input.tools?.map((tool) => ({
-              name: tool.name || tool.id,
-              description: tool.description || "",
-              parameters: tool.parameters as FunctionDeclaration["parameters"], // JSON schema
-            })),
-          },
-        ];
+        const functionDeclarations = this.buildFunctionDeclarations(input.tools!);
+        configOverride.tools = [{ functionDeclarations }];
 
       } else if (hasJsonSchema) {
         // Only set JSON schema if no tools are present
@@ -380,7 +433,10 @@ export class GeminiProvider implements AiProvider {
         response = await this.genAI.models.generateContent({
           model,
           contents: input.prompt,
-          config: configOverride,
+          config: {
+            ...configOverride,
+            ...(input.signal ? { abortSignal: input.signal } : {}),
+          },
         });
       } catch (error: unknown) {
         logger.error(`[GeminiProvider] API call failed:`, error);
@@ -399,7 +455,7 @@ export class GeminiProvider implements AiProvider {
           if (part.functionCall) {
             toolCalls.push({
               toolName: part.functionCall.name || "",
-              arguments: part.functionCall.args as Record<string, unknown>,
+              arguments: (part.functionCall.args as Record<string, unknown>) || {},
             });
           }
         }
@@ -408,30 +464,13 @@ export class GeminiProvider implements AiProvider {
       // Debug logging for response structure
       if (!response.text && toolCalls.length === 0) {
         logger.debug(`[GeminiProvider] Debug - Response structure:`, {
-          hasText: !!response.text,
           candidatesCount: response.candidates?.length || 0,
-          firstCandidateContent: response.candidates?.[0]?.content,
           firstCandidateParts: response.candidates?.[0]?.content?.parts?.length || 0,
         });
       }
-      // Try to get text from response, handling function calls properly
-      let message = "";
-      try {
-        message = response.text || "";
-      } catch (textError) {
-        // Sometimes response.text throws when there are function calls
-        logger.debug(`[GeminiProvider] Could not get response.text (likely due to function calls):`, textError);
-
-        // Try to extract text parts manually
-        if (response.candidates && response.candidates[0]?.content?.parts) {
-          const textParts = response.candidates[0].content.parts
-            .filter(part => part.text)
-            .map(part => part.text)
-            .join('');
-          message = textParts;
-          logger.debug(`[GeminiProvider] Extracted text from parts:`, message);
-        }
-      }
+
+      // Safely extract text — .text getter can throw when response has only function calls
+      const message = this.safeExtractText(response);
 
       // Only throw error if we have no text AND no function calls
       if (!message && toolCalls.length === 0) {
@@ -443,15 +482,8 @@ export class GeminiProvider implements AiProvider {
       // Log when we have function calls but no text (this is normal)
       if (toolCalls.length > 0 && !message) {
         logger.debug(`[GeminiProvider] Function calls detected without text message:`, toolCalls.map(tc => tc.toolName));
-      } else if (toolCalls.length > 0 && message) {
-        logger.debug(`[GeminiProvider] Response has both text and function calls:`, {
-          messageLength: message.length,
-          toolCalls: toolCalls.map(tc => tc.toolName),
-        });
       }
 
-
-
       // Parse JSON response if schema was provided
       let structured: AgentStructuredResponse | undefined;
       if (input.parameters?.jsonSchema) {
@@ -574,15 +606,8 @@ export class GeminiProvider implements AiProvider {
     if (hasTools) {
       const toolNames = input.tools?.map((tool) => tool.name || tool.id) || [];
       logger.debug(`[GeminiProvider] Configuring ${toolNames.length} tools for streaming:`, toolNames);
-      configOverride.tools = [
-        {
-          functionDeclarations: input.tools?.map((tool) => ({
-            name: tool.name || tool.id,
-            description: tool.description || "",
-            parameters: tool.parameters as FunctionDeclaration["parameters"],
-          })),
-        },
-      ];
+      const functionDeclarations = this.buildFunctionDeclarations(input.tools!);
+      configOverride.tools = [{ functionDeclarations }];
 
     } else if (hasJsonSchema) {
       // Only set JSON schema if no tools are present
@@ -598,7 +623,10 @@ export class GeminiProvider implements AiProvider {
       stream = await this.genAI.models.generateContentStream({
         model,
         contents: input.prompt,
-        config: configOverride,
+        config: {
+          ...configOverride,
+          ...(input.signal ? { abortSignal: input.signal } : {}),
+        },
       });
     } catch (error: unknown) {
       logger.error(`[GeminiProvider] Streaming API call failed:`, error);
@@ -615,7 +643,10 @@ export class GeminiProvider implements AiProvider {
     }> = [];
 
     for await (const chunk of stream) {
-      const delta = chunk.text || "";
+      if (input.signal?.aborted) break;
+
+      // Safely extract text — chunk.text can throw when chunk has only function calls
+      const delta = this.safeExtractText(chunk);
 
       // Extract tool calls from chunk
       if (chunk.candidates && chunk.candidates[0]?.content?.parts) {
@@ -623,7 +654,7 @@ export class GeminiProvider implements AiProvider {
           if (part.functionCall) {
             toolCalls.push({
               toolName: part.functionCall.name || "",
-              arguments: part.functionCall.args as Record<string, unknown>,
+              arguments: (part.functionCall.args as Record<string, unknown>) || {},
             });
           }
         }
@@ -657,12 +688,12 @@ export class GeminiProvider implements AiProvider {
       }
     }
 
-    // If tools were used, include them in structured response
+    // Include tool calls in structured response (even without JSON schema)
     if (toolCalls.length > 0) {
       structured = {
         message: structured?.message || accumulated,
-        toolCalls,
         ...structured,
+        toolCalls,
       } as AgentStructuredResponse;
     }
 

package/src/providers/OpenAIProvider.ts

@@ -222,8 +222,7 @@ export class OpenAIProvider implements AiProvider {
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
         logger.debug(
-          `[OPENAI] Trying backup model ${i + 1}/${
-            this.backupModels.length
+          `[OPENAI] Trying backup model ${i + 1}/${this.backupModels.length
           }: ${backupModel}`
         );
 
@@ -336,10 +335,7 @@ export class OpenAIProvider implements AiProvider {
       // 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;
-      if (!message) {
-        throw new Error("No response from OpenAI");
-      }
+      const message = response.choices[0]?.message?.content || "";
 
       let toolCalls: Array<{
         toolName: string;
@@ -368,7 +364,11 @@ export class OpenAIProvider implements AiProvider {
             };
           });
       }
-      // Extract tool calls from response
+
+      // Only throw error if we have no text AND no function calls
+      if (!message && toolCalls.length === 0) {
+        throw new Error("No response from OpenAI");
+      }
 
       return {
         message,
@@ -423,8 +423,7 @@ export class OpenAIProvider implements AiProvider {
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
         logger.debug(
-          `[OPENAI] Trying backup model ${i + 1}/${
-            this.backupModels.length
+          `[OPENAI] Trying backup model ${i + 1}/${this.backupModels.length
           }: ${backupModel}`
         );
 
@@ -530,9 +529,9 @@ export class OpenAIProvider implements AiProvider {
             try {
               toolCallArguments = toolCall.function.arguments
                 ? (JSON.parse(toolCall.function.arguments) as Record<
-                    string,
-                    unknown
-                  >)
+                  string,
+                  unknown
+                >)
                 : {};
             } catch (error) {
               logger.warn(
@@ -584,6 +583,15 @@ export class OpenAIProvider implements AiProvider {
       }
     }
 
+    // Include tool calls in structured response (even without JSON schema)
+    if (toolCalls.length > 0) {
+      structured = {
+        ...(structured || {}),
+        message: (structured as AgentStructuredResponse | undefined)?.message || accumulated,
+        toolCalls,
+      } as TStructured;
+    }
+
     // Yield final chunk
     yield {
       delta: "",
@@ -596,7 +604,7 @@ export class OpenAIProvider implements AiProvider {
         promptTokens,
         completionTokens,
       },
-      structured: structured ? { ...structured, toolCalls } : undefined,
+      structured,
     };
   }
 }

package/src/providers/OpenRouterProvider.ts

@@ -229,8 +229,7 @@ export class OpenRouterProvider implements AiProvider {
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
         logger.debug(
-          `[OPENROUTER] Trying backup model ${i + 1}/${
-            this.backupModels.length
+          `[OPENROUTER] Trying backup model ${i + 1}/${this.backupModels.length
           }: ${backupModel}`
         );
 
@@ -345,10 +344,7 @@ export class OpenRouterProvider implements AiProvider {
       // 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;
-      if (!message) {
-        throw new Error("No response from OpenRouter");
-      }
+      const message = response.choices[0]?.message?.content || "";
 
       let toolCalls: Array<{
         toolName: string;
@@ -378,6 +374,11 @@ export class OpenRouterProvider implements AiProvider {
           });
       }
 
+      // Only throw error if we have no text AND no function calls
+      if (!message && toolCalls.length === 0) {
+        throw new Error("No response from OpenRouter");
+      }
+
       return {
         message,
         metadata: {
@@ -428,8 +429,7 @@ export class OpenRouterProvider implements AiProvider {
       for (let i = 0; i < this.backupModels.length; i++) {
         const backupModel = this.backupModels[i];
         logger.debug(
-          `[OPENROUTER] Trying backup model ${i + 1}/${
-            this.backupModels.length
+          `[OPENROUTER] Trying backup model ${i + 1}/${this.backupModels.length
           }: ${backupModel}`
         );
 
@@ -532,9 +532,9 @@ export class OpenRouterProvider implements AiProvider {
             try {
               toolCallArguments = toolCall.function.arguments
                 ? (JSON.parse(toolCall.function.arguments) as Record<
-                    string,
-                    unknown
-                  >)
+                  string,
+                  unknown
+                >)
                 : {};
             } catch (error) {
               logger.warn(
@@ -589,9 +589,9 @@ export class OpenRouterProvider implements AiProvider {
     // If tools were used, include them in structured response
     if (toolCalls.length > 0) {
       structured = {
-        message: accumulated,
+        ...(structured || {}),
+        message: (structured as AgentStructuredResponse | undefined)?.message || accumulated,
         toolCalls,
-        ...structured,
       } as TStructured;
     }
 

package/src/types/agent.ts

@@ -9,6 +9,39 @@ import type { PersistenceConfig } from "./persistence";
 import type { SessionState } from "./session";
 import type { StructuredSchema } from "./schema";
 import { Template, ConditionTemplate } from "./template";
+import type { PromptCacheConfig } from "../core/PromptSectionCache";
+
+/**
+ * Agent-level compaction configuration.
+ * Unlike CompactionOptions, this does not require a `provider` since the agent already has one.
+ */
+export interface AgentCompactionConfig {
+  /** Maximum token budget for the conversation */
+  maxTokens: number;
+  /**
+   * Threshold ratio (0–1) at which to trigger compaction.
+   * Must be between 0.5 and 0.95.
+   * @default 0.8
+   */
+  compactionThreshold?: number;
+  /**
+   * Number of recent messages to always preserve unchanged.
+   * Must be >= 2.
+   * @default 4
+   */
+  preserveRecentCount?: number;
+  /**
+   * Maximum characters per tool result before truncation.
+   * Must be > 0.
+   * @default 5000
+   */
+  maxToolResultChars?: number;
+  /**
+   * Whether compaction is enabled.
+   * @default true when config is provided
+   */
+  enabled?: boolean;
+}
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -132,6 +165,18 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
    * @default 1
    */
   maxStepsPerBatch?: number;
+  /**
+   * Optional compaction configuration for managing conversation history size.
+   * When provided, the agent will validate the options and make them available
+   * for use by the SessionManager/CompactionEngine.
+   */
+  compaction?: AgentCompactionConfig;
+  /**
+   * Optional prompt cache configuration for controlling section memoization behavior.
+   * When provided, controls whether prompt sections are cached across turns.
+   * @default { enabled: true }
+   */
+  promptCache?: PromptCacheConfig;
 }
 
 /**

package/src/types/compaction.ts

@@ -0,0 +1,52 @@
+/**
+ * Context compaction types for managing conversation history size
+ */
+
+import type { AiProvider } from "./ai";
+import type { HistoryItem } from "./history";
+
+/**
+ * Configuration for the compaction engine.
+ *
+ * Validation constraints:
+ * - `compactionThreshold` must be between 0.5 and 0.95
+ * - `preserveRecentCount` must be >= 2
+ * - `maxToolResultChars` must be > 0
+ */
+export interface CompactionOptions {
+    /** Maximum token budget for the conversation */
+    maxTokens: number;
+    /**
+     * Threshold ratio (0–1) at which to trigger compaction.
+     * Must be between 0.5 and 0.95.
+     */
+    compactionThreshold: number;
+    /**
+     * Number of recent messages to always preserve unchanged.
+     * Must be >= 2.
+     */
+    preserveRecentCount: number;
+    /**
+     * Maximum characters per tool result before truncation.
+     * Must be > 0.
+     */
+    maxToolResultChars: number;
+    /** Provider to use for LLM summarization during auto-compact */
+    provider: AiProvider;
+}
+
+/**
+ * Result of a compaction operation
+ */
+export interface CompactionResult {
+    /** The compacted history */
+    history: HistoryItem[];
+    /** Strategy that was applied */
+    strategy: 'none' | 'tool_result_budget' | 'micro_compact' | 'auto_compact';
+    /** Estimated tokens after compaction */
+    estimatedTokens: number;
+    /** Number of messages removed/compacted */
+    messagesCompacted: number;
+    /** Summary text (if auto-compact was used) */
+    summary?: string;
+}

package/src/types/index.ts

@@ -5,6 +5,7 @@
 // Agent types
 export type {
   AgentOptions,
+  AgentCompactionConfig,
   Term,
   Guideline,
   GuidelineMatch,
@@ -58,12 +59,19 @@ export * from "./route";
 export type { SessionState, PendingTransition } from "./session";
 
 // Tool types
-export type { 
-  Tool, 
-  ToolContext, 
-  ToolResult, 
+export type {
+  Tool,
+  ToolContext,
+  ToolResult,
   ToolHandler,
   ToolExecutionResult,
+  EnhancedTool,
+  ToolValidationResult,
+  ToolPermissionResult,
+  ToolCallRequest,
+  ToolExecutionUpdate,
+  TrackedTool,
+  ToolStatus,
   DataEnrichmentConfig,
   ValidationConfig,
   ApiCallConfig,
@@ -71,6 +79,19 @@ export type {
 } from "./tool";
 export { ToolScope } from "./tool";
 
+// Compaction types
+export type {
+  CompactionOptions,
+  CompactionResult,
+} from "./compaction";
+
+// Prompt cache types (re-exported from core)
+export type {
+  PromptSectionType,
+  PromptCacheConfig,
+  SectionCompute,
+} from "../core/PromptSectionCache";
+
 // AI provider types
 export type {
   AiProvider,
@@ -105,15 +126,15 @@ export type {
 export * from "./persistence";
 
 // Template types
-export type { 
-  Template, 
-  TemplateContext, 
-  ConditionTemplate, 
-  ConditionEvaluationResult 
+export type {
+  Template,
+  TemplateContext,
+  ConditionTemplate,
+  ConditionEvaluationResult
 } from "./template";
-export { 
-  ConditionEvaluator, 
-  createConditionEvaluator, 
-  extractAIContextStrings, 
-  hasProgrammaticConditions 
+export {
+  ConditionEvaluator,
+  createConditionEvaluator,
+  extractAIContextStrings,
+  hasProgrammaticConditions
 } from "../utils/condition";

package/src/types/tool.ts

@@ -116,6 +116,114 @@ export enum ToolScope {
 
 
 
+// --- EnhancedTool and supporting types ---
+
+/**
+ * Result of input validation on a tool call
+ */
+export interface ToolValidationResult {
+  valid: boolean;
+  error?: string;
+  /** Suggested corrected input */
+  correctedInput?: Record<string, unknown>;
+}
+
+/**
+ * Result of a permission check on a tool call
+ */
+export interface ToolPermissionResult {
+  allowed: boolean;
+  reason?: string;
+  /** If not allowed, can the user override? */
+  canOverride?: boolean;
+}
+
+/**
+ * A single tool invocation request from the LLM
+ */
+export interface ToolCallRequest {
+  /** Unique ID for this tool call instance */
+  id: string;
+  /** Tool name/ID to execute */
+  toolName: string;
+  /** Arguments passed to the tool */
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * Result or progress update from a tool execution
+ */
+export interface ToolExecutionUpdate<TData = unknown> {
+  /** The tool call this update relates to */
+  toolCallId: string;
+  /** Result message (undefined for progress updates) */
+  result?: ToolExecutionResult;
+  /** Progress message for long-running tools */
+  progress?: string;
+  /** Updated context after tool execution */
+  contextUpdate?: Record<string, unknown>;
+  /** Updated data after tool execution */
+  dataUpdate?: Partial<TData>;
+}
+
+/**
+ * Internal status of a tracked tool in the executor queue
+ */
+export type ToolStatus = 'queued' | 'executing' | 'completed' | 'yielded';
+
+/**
+ * Internal type tracking the state of a queued or executing tool
+ */
+export interface TrackedTool<TContext = unknown, TData = unknown> {
+  id: string;
+  toolCall: ToolCallRequest;
+  tool: EnhancedTool<TContext, TData>;
+  status: ToolStatus;
+  isConcurrencySafe: boolean;
+  promise?: Promise<void>;
+  results: ToolExecutionResult[];
+  pendingProgress: string[];
+}
+
+/**
+ * Extended tool interface with rich metadata for concurrency control,
+ * permission gating, input validation, and result size management.
+ *
+ * All additional methods/properties are optional — plain `Tool` objects
+ * remain fully compatible.
+ */
+export interface EnhancedTool<
+  TContext = any,
+  TData = any,
+  TResult = any
+> extends Tool<TContext, TData, TResult> {
+  /** Whether this tool is safe to run concurrently with other concurrent-safe tools */
+  isConcurrencySafe?(input?: Record<string, unknown>): boolean;
+  /** Whether this tool only reads data without side effects */
+  isReadOnly?(input?: Record<string, unknown>): boolean;
+  /** Whether this tool performs destructive/irreversible operations */
+  isDestructive?(input?: Record<string, unknown>): boolean;
+
+  /** How the tool responds to abort signals: 'cancel' = immediate abort, 'block' = allow completion */
+  interruptBehavior?(): 'cancel' | 'block';
+  /** Maximum characters for the tool result before truncation */
+  maxResultSizeChars?: number;
+
+  /** Validate input before execution */
+  validateInput?(
+    input: Record<string, unknown>,
+    context: ToolContext<TContext, TData>
+  ): Promise<ToolValidationResult> | ToolValidationResult;
+
+  /** Check permissions before execution */
+  checkPermissions?(
+    input: Record<string, unknown>,
+    context: ToolContext<TContext, TData>
+  ): Promise<ToolPermissionResult> | ToolPermissionResult;
+}
+
+// --- Existing tool configuration types ---
+
 /**
  * Configuration for data enrichment tools
  */