@falai/agent 1.1.3 → 1.2.1

package/src/providers/OpenAIProvider.ts

@@ -13,6 +13,7 @@ import type {
   AgentStructuredResponse,
   StructuredSchema,
 } from "../types";
+import type { HistoryItem } from "../types/history";
 import { withTimeoutAndRetry, logger } from "../utils";
 import { FunctionParameters } from "openai/resources/shared.mjs";
 
@@ -161,6 +162,52 @@ export class OpenAIProvider implements AiProvider {
     };
   }
 
+  /**
+   * Build OpenAI-formatted messages from HistoryItem[] array.
+   * Maps directly to ChatCompletionMessageParam format.
+   */
+  private buildOpenAIMessages(history: HistoryItem[]): Array<unknown> {
+    const messages: Array<unknown> = [];
+
+    for (const item of history) {
+      switch (item.role) {
+        case "system":
+          messages.push({ role: "system", content: item.content });
+          break;
+        case "user":
+          messages.push({ role: "user", content: item.content });
+          break;
+        case "assistant":
+          if (item.tool_calls && item.tool_calls.length > 0) {
+            messages.push({
+              role: "assistant",
+              content: item.content || null,
+              tool_calls: item.tool_calls.map(tc => ({
+                id: tc.id,
+                type: "function",
+                function: {
+                  name: tc.name,
+                  arguments: JSON.stringify(tc.arguments),
+                },
+              })),
+            });
+          } else {
+            messages.push({ role: "assistant", content: item.content || "" });
+          }
+          break;
+        case "tool":
+          messages.push({
+            role: "tool",
+            tool_call_id: item.tool_call_id,
+            content: typeof item.content === "string" ? item.content : JSON.stringify(item.content),
+          });
+          break;
+      }
+    }
+
+    return messages;
+  }
+
   /**
    * Adapt common schema format to OpenAI's format.
    * OpenAI uses standard JSON Schema, so this is mostly a passthrough.
@@ -222,8 +269,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}`
         );
 
@@ -266,14 +312,12 @@ export class OpenAIProvider implements AiProvider {
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput<TStructured>> {
     const operation = async (): Promise<GenerateMessageOutput> => {
+      const historyMessages = this.buildOpenAIMessages(input.history);
+      historyMessages.push({ role: "user", content: input.prompt });
+
       const params: ChatCompletionCreateParamsNonStreaming = {
         model,
-        messages: [
-          {
-            role: "user",
-            content: input.prompt,
-          },
-        ],
+        messages: historyMessages as ChatCompletionCreateParamsNonStreaming["messages"],
         ...this.config,
       };
 
@@ -336,10 +380,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 +409,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 +468,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}`
         );
 
@@ -469,15 +513,14 @@ export class OpenAIProvider implements AiProvider {
     model: string,
     input: GenerateMessageInput<TContext>
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
+    // Build messages from history and append prompt as final user message
+    const historyMessages = this.buildOpenAIMessages(input.history);
+    historyMessages.push({ role: "user" as const, content: input.prompt });
+
     const params = {
       ...this.config,
       model,
-      messages: [
-        {
-          role: "user" as const,
-          content: input.prompt,
-        },
-      ],
+      messages: historyMessages as ChatCompletionCreateParamsNonStreaming["messages"],
       stream: true as const,
     };
 
@@ -530,9 +573,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 +627,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 +648,7 @@ export class OpenAIProvider implements AiProvider {
         promptTokens,
         completionTokens,
       },
-      structured: structured ? { ...structured, toolCalls } : undefined,
+      structured,
     };
   }
 }

package/src/providers/OpenRouterProvider.ts

@@ -15,6 +15,7 @@ import type {
   GenerateMessageStreamChunk,
   StructuredSchema,
 } from "../types";
+import type { HistoryItem } from "../types/history";
 import { withTimeoutAndRetry, logger } from "../utils";
 
 const DEFAULT_RETRY_CONFIG = {
@@ -171,6 +172,52 @@ export class OpenRouterProvider implements AiProvider {
     };
   }
 
+  /**
+   * Build OpenRouter-formatted messages from HistoryItem[] array.
+   * OpenRouter uses OpenAI-compatible format.
+   */
+  private buildOpenRouterMessages(history: HistoryItem[]): Array<unknown> {
+    const messages: Array<unknown> = [];
+
+    for (const item of history) {
+      switch (item.role) {
+        case "system":
+          messages.push({ role: "system", content: item.content });
+          break;
+        case "user":
+          messages.push({ role: "user", content: item.content });
+          break;
+        case "assistant":
+          if (item.tool_calls && item.tool_calls.length > 0) {
+            messages.push({
+              role: "assistant",
+              content: item.content || null,
+              tool_calls: item.tool_calls.map(tc => ({
+                id: tc.id,
+                type: "function",
+                function: {
+                  name: tc.name,
+                  arguments: JSON.stringify(tc.arguments),
+                },
+              })),
+            });
+          } else {
+            messages.push({ role: "assistant", content: item.content || "" });
+          }
+          break;
+        case "tool":
+          messages.push({
+            role: "tool",
+            tool_call_id: item.tool_call_id,
+            content: typeof item.content === "string" ? item.content : JSON.stringify(item.content),
+          });
+          break;
+      }
+    }
+
+    return messages;
+  }
+
   /**
    * Adapt common schema format to OpenRouter's format.
    * OpenRouter is OpenAI-compatible and uses standard JSON Schema.
@@ -229,8 +276,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}`
         );
 
@@ -273,14 +319,12 @@ export class OpenRouterProvider implements AiProvider {
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput<TStructured>> {
     const operation = async (): Promise<GenerateMessageOutput> => {
+      const historyMessages = this.buildOpenRouterMessages(input.history);
+      historyMessages.push({ role: "user", content: input.prompt });
+
       const params: ChatCompletionCreateParamsNonStreaming = {
         model,
-        messages: [
-          {
-            role: "user",
-            content: input.prompt,
-          },
-        ],
+        messages: historyMessages as ChatCompletionCreateParamsNonStreaming["messages"],
         ...this.config,
       };
 
@@ -345,10 +389,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 +419,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 +474,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}`
         );
 
@@ -471,15 +516,13 @@ export class OpenRouterProvider implements AiProvider {
     model: string,
     input: GenerateMessageInput<TContext>
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
+    const historyMessages = this.buildOpenRouterMessages(input.history);
+    historyMessages.push({ role: "user" as const, content: input.prompt });
+
     const params = {
       ...this.config,
       model,
-      messages: [
-        {
-          role: "user" as const,
-          content: input.prompt,
-        },
-      ],
+      messages: historyMessages as ChatCompletionCreateParamsNonStreaming["messages"],
       stream: true as const,
     };
 
@@ -532,9 +575,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 +632,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/ai.ts

@@ -2,7 +2,7 @@
  * AI provider strategy types
  */
 
-import type { Event } from "./history";
+import type { HistoryItem } from "./history";
 
 /**
  * Reasoning/thinking configuration for AI models
@@ -36,7 +36,7 @@ export interface GenerateMessageInput<TContext = unknown> {
   /** The constructed prompt */
   prompt: string;
   /** Interaction history */
-  history: Event[];
+  history: HistoryItem[];
   /** Context data */
   context: TContext;
   /** Tools available for AI to call during this interaction */

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
  */