@falai/agent 0.3.30 → 0.4.1

package/src/providers/AnthropicProvider.ts

@@ -149,24 +149,36 @@ export class AnthropicProvider implements AiProvider {
     };
   }
 
-  async generateMessage<TContext = unknown>(
+  async generateMessage<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
-    return this.generateWithBackup(input);
+  ): Promise<GenerateMessageOutput<TStructured>> {
+    return this.generateWithBackup<TContext, TStructured>(input);
   }
 
-  async *generateMessageStream<TContext = unknown>(
+  async *generateMessageStream<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
-    yield* this.generateStreamWithBackup(input);
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
+    yield* this.generateStreamWithBackup<TContext, TStructured>(input);
   }
 
-  private async generateWithBackup<TContext = unknown>(
+  private async generateWithBackup<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
+  ): Promise<GenerateMessageOutput<TStructured>> {
     // Try primary model first
     try {
-      return await this.generateWithModel(this.primaryModel, input);
+      return await this.generateWithModel<TContext, TStructured>(
+        this.primaryModel,
+        input
+      );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
       console.warn(
@@ -190,7 +202,10 @@ export class AnthropicProvider implements AiProvider {
         );
 
         try {
-          const result = await this.generateWithModel(backupModel, input);
+          const result = await this.generateWithModel<TContext, TStructured>(
+            backupModel,
+            input
+          );
           console.log(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
           return result;
         } catch (backupError: unknown) {
@@ -220,10 +235,13 @@ export class AnthropicProvider implements AiProvider {
     }
   }
 
-  private async generateWithModel<TContext = unknown>(
+  private async generateWithModel<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     model: string,
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
+  ): Promise<GenerateMessageOutput<TStructured>> {
     const operation = async (): Promise<GenerateMessageOutput> => {
       // Anthropic requires max_tokens to be specified
       const maxTokens = input.parameters?.maxOutputTokens || 4096;
@@ -306,15 +324,21 @@ export class AnthropicProvider implements AiProvider {
       this.retryConfig.timeout,
       this.retryConfig.retries,
       `Anthropic ${model}`
-    );
+    ) as Promise<GenerateMessageOutput<TStructured>>;
   }
 
-  private async *generateStreamWithBackup<TContext = unknown>(
+  private async *generateStreamWithBackup<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Try primary model first
     try {
-      yield* this.generateStreamWithModel(this.primaryModel, input);
+      yield* this.generateStreamWithModel<TContext, TStructured>(
+        this.primaryModel,
+        input
+      );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
       console.warn(
@@ -338,7 +362,10 @@ export class AnthropicProvider implements AiProvider {
         );
 
         try {
-          yield* this.generateStreamWithModel(backupModel, input);
+          yield* this.generateStreamWithModel<TContext, TStructured>(
+            backupModel,
+            input
+          );
           console.log(`[ANTHROPIC] Backup model ${backupModel} succeeded`);
           return;
         } catch (backupError: unknown) {
@@ -368,10 +395,13 @@ export class AnthropicProvider implements AiProvider {
     }
   }
 
-  private async *generateStreamWithModel<TContext = unknown>(
+  private async *generateStreamWithModel<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     model: string,
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Anthropic requires max_tokens to be specified
     const maxTokens = input.parameters?.maxOutputTokens || 4096;
 
@@ -428,7 +458,7 @@ export class AnthropicProvider implements AiProvider {
             delta,
             accumulated,
             done: false,
-          };
+          } as GenerateMessageStreamChunk<TStructured>;
         }
       } else if (chunk.type === "message_delta") {
         stopReason = chunk.delta.stop_reason || undefined;
@@ -462,6 +492,6 @@ export class AnthropicProvider implements AiProvider {
         completionTokens: outputTokens,
       },
       structured,
-    };
+    } as GenerateMessageStreamChunk<TStructured>;
   }
 }

package/src/providers/GeminiProvider.ts

@@ -48,39 +48,67 @@ export interface GeminiProviderOptions {
  */
 interface ErrorWithStatus {
   status?: number;
-  code?: number;
+  code?: string;
   message?: string;
+  type?: string;
+}
+
+/**
+ * Type guard to check if error is ErrorWithStatus
+ */
+function isErrorWithStatus(error: unknown): error is ErrorWithStatus {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    ("status" in error || "code" in error || "message" in error)
+  );
+}
+
+/**
+ * Safely extract error message
+ */
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (isErrorWithStatus(error) && error.message) {
+    return error.message;
+  }
+  return String(error);
 }
 
 /**
  * Determines if an error should trigger backup model usage
  */
 const shouldUseBackupModel = (error: unknown): boolean => {
-  const err = error as ErrorWithStatus;
+  if (!isErrorWithStatus(error)) {
+    return false;
+  }
 
-  if (err?.status === 500 || err?.code === 500) {
+  // Server errors
+  if (error.status === 500 || error.status === 503) {
     return true;
   }
 
-  const message = err?.message ?? String(error);
-  if (
-    message.includes("internal error") ||
-    message.includes("Internal error") ||
-    message.includes("INTERNAL")
-  ) {
+  // Rate limiting
+  if (error.status === 429) {
     return true;
   }
 
-  if (
-    err?.status === 429 ||
-    err?.code === 429 ||
-    err?.status === 503 ||
-    err?.code === 503
-  ) {
+  // Model overloaded or unavailable
+  if (error.code === "overloaded") {
     return true;
   }
 
-  if (message.includes("unavailable") || message.includes("not available")) {
+  const message = getErrorMessage(error);
+  if (
+    message.includes("overloaded") ||
+    message.includes("unavailable") ||
+    message.includes("not available") ||
+    message.includes("internal error") ||
+    message.includes("Internal error") ||
+    message.includes("INTERNAL")
+  ) {
     return true;
   }
 
@@ -119,26 +147,35 @@ export class GeminiProvider implements AiProvider {
     };
   }
 
-  async generateMessage<TContext = unknown>(
+  async generateMessage<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
-    return this.generateWithBackup(input);
+  ): Promise<GenerateMessageOutput<TStructured>> {
+    return this.generateWithBackup<TContext, TStructured>(input);
   }
 
-  async *generateMessageStream<TContext = unknown>(
+  async *generateMessageStream<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
-    yield* this.generateStreamWithBackup(input);
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
+    yield* this.generateStreamWithBackup<TContext, TStructured>(input);
   }
 
-  private async generateWithBackup<TContext = unknown>(
+  private async generateWithBackup<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
+  ): Promise<GenerateMessageOutput<TStructured>> {
     // Try primary model first
     try {
       return await this.generateWithModel(this.primaryModel, input);
     } catch (primaryError: unknown) {
-      const primaryErrMsg = String(primaryError);
+      const primaryErrMsg = getErrorMessage(primaryError);
       console.warn(
         `[GEMINI] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
       );
@@ -162,9 +199,9 @@ export class GeminiProvider implements AiProvider {
         try {
           const result = await this.generateWithModel(backupModel, input);
           console.log(`[GEMINI] Backup model ${backupModel} succeeded`);
-          return result;
+          return result as GenerateMessageOutput<TStructured>;
         } catch (backupError: unknown) {
-          const backupErrMsg = String(backupError);
+          const backupErrMsg = getErrorMessage(backupError);
           console.warn(
             `[GEMINI] Backup model ${backupModel} failed: ${backupErrMsg}`
           );
@@ -182,7 +219,7 @@ export class GeminiProvider implements AiProvider {
         }
       }
 
-      const lastBackupErrMsg = String(lastBackupError);
+      const lastBackupErrMsg = getErrorMessage(lastBackupError);
       console.error(
         `[GEMINI] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
       );
@@ -190,10 +227,13 @@ export class GeminiProvider implements AiProvider {
     }
   }
 
-  private async generateWithModel<TContext = unknown>(
+  private async generateWithModel<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     model: string,
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
+  ): Promise<GenerateMessageOutput<TStructured>> {
     const operation = async (): Promise<GenerateMessageOutput> => {
       // Enable JSON mode if requested
       const configOverride: Partial<GenerateContentConfig> = { ...this.config };
@@ -214,7 +254,7 @@ export class GeminiProvider implements AiProvider {
       }
 
       // Parse JSON response if JSON mode was enabled
-      let structured;
+      let structured: AgentStructuredResponse | undefined;
       if (input.parameters?.jsonMode) {
         try {
           structured = JSON.parse(message) as AgentStructuredResponse;
@@ -241,17 +281,20 @@ export class GeminiProvider implements AiProvider {
       this.retryConfig.timeout,
       this.retryConfig.retries,
       `Gemini ${model}`
-    );
+    ) as Promise<GenerateMessageOutput<TStructured>>;
   }
 
-  private async *generateStreamWithBackup<TContext = unknown>(
+  private async *generateStreamWithBackup<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Try primary model first
     try {
       yield* this.generateStreamWithModel(this.primaryModel, input);
     } catch (primaryError: unknown) {
-      const primaryErrMsg = String(primaryError);
+      const primaryErrMsg = getErrorMessage(primaryError);
       console.warn(
         `[GEMINI] Primary model ${this.primaryModel} failed: ${primaryErrMsg}`
       );
@@ -277,7 +320,7 @@ export class GeminiProvider implements AiProvider {
           console.log(`[GEMINI] Backup model ${backupModel} succeeded`);
           return;
         } catch (backupError: unknown) {
-          const backupErrMsg = String(backupError);
+          const backupErrMsg = getErrorMessage(backupError);
           console.warn(
             `[GEMINI] Backup model ${backupModel} failed: ${backupErrMsg}`
           );
@@ -295,7 +338,7 @@ export class GeminiProvider implements AiProvider {
         }
       }
 
-      const lastBackupErrMsg = String(lastBackupError);
+      const lastBackupErrMsg = getErrorMessage(lastBackupError);
       console.error(
         `[GEMINI] All models failed. Primary: ${primaryErrMsg}, Last backup: ${lastBackupErrMsg}`
       );
@@ -303,10 +346,13 @@ export class GeminiProvider implements AiProvider {
     }
   }
 
-  private async *generateStreamWithModel<TContext = unknown>(
+  private async *generateStreamWithModel<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     model: string,
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Enable JSON mode if requested
     const configOverride: Partial<GenerateContentConfig> = { ...this.config };
     if (input.parameters?.jsonMode) {
@@ -368,7 +414,7 @@ export class GeminiProvider implements AiProvider {
         promptTokens: promptTokenCount,
         completionTokens: candidatesTokenCount,
       },
-      structured,
+      structured: structured as TStructured | undefined,
     };
   }
 }

package/src/providers/OpenAIProvider.ts

@@ -159,24 +159,36 @@ export class OpenAIProvider implements AiProvider {
     };
   }
 
-  async generateMessage<TContext = unknown>(
+  async generateMessage<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
-    return this.generateWithBackup(input);
+  ): Promise<GenerateMessageOutput<TStructured>> {
+    return this.generateWithBackup<TContext, TStructured>(input);
   }
 
-  async *generateMessageStream<TContext = unknown>(
+  async *generateMessageStream<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
-    yield* this.generateStreamWithBackup(input);
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
+    yield* this.generateStreamWithBackup<TContext, TStructured>(input);
   }
 
-  private async generateWithBackup<TContext = unknown>(
+  private async generateWithBackup<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
+  ): Promise<GenerateMessageOutput<TStructured>> {
     // Try primary model first
     try {
-      return await this.generateWithModel(this.primaryModel, input);
+      return await this.generateWithModel<TContext, TStructured>(
+        this.primaryModel,
+        input
+      );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
       console.warn(
@@ -202,7 +214,7 @@ export class OpenAIProvider implements AiProvider {
         try {
           const result = await this.generateWithModel(backupModel, input);
           console.log(`[OPENAI] Backup model ${backupModel} succeeded`);
-          return result;
+          return result as GenerateMessageOutput<TStructured>;
         } catch (backupError: unknown) {
           const backupErrMsg = getErrorMessage(backupError);
           console.warn(
@@ -230,10 +242,13 @@ export class OpenAIProvider implements AiProvider {
     }
   }
 
-  private async generateWithModel<TContext = unknown>(
+  private async generateWithModel<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     model: string,
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
+  ): Promise<GenerateMessageOutput<TStructured>> {
     const operation = async (): Promise<GenerateMessageOutput> => {
       const params: ChatCompletionCreateParamsNonStreaming = {
         model,
@@ -358,15 +373,21 @@ export class OpenAIProvider implements AiProvider {
       this.retryConfig.timeout,
       this.retryConfig.retries,
       `OpenAI ${model}`
-    );
+    ) as Promise<GenerateMessageOutput<TStructured>>;
   }
 
-  private async *generateStreamWithBackup<TContext = unknown>(
+  private async *generateStreamWithBackup<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Try primary model first
     try {
-      yield* this.generateStreamWithModel(this.primaryModel, input);
+      yield* this.generateStreamWithModel<TContext, TStructured>(
+        this.primaryModel,
+        input
+      );
     } catch (primaryError: unknown) {
       const primaryErrMsg = getErrorMessage(primaryError);
       console.warn(
@@ -390,7 +411,10 @@ export class OpenAIProvider implements AiProvider {
         );
 
         try {
-          yield* this.generateStreamWithModel(backupModel, input);
+          yield* this.generateStreamWithModel<TContext, TStructured>(
+            backupModel,
+            input
+          );
           console.log(`[OPENAI] Backup model ${backupModel} succeeded`);
           return;
         } catch (backupError: unknown) {
@@ -420,10 +444,13 @@ export class OpenAIProvider implements AiProvider {
     }
   }
 
-  private async *generateStreamWithModel<TContext = unknown>(
+  private async *generateStreamWithModel<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     model: string,
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     const params = {
       ...this.config,
       model,
@@ -483,10 +510,10 @@ export class OpenAIProvider implements AiProvider {
     }
 
     // Parse JSON response if JSON mode was enabled
-    let structured: AgentStructuredResponse | undefined;
+    let structured: TStructured | undefined;
     if (input.parameters?.jsonMode && accumulated) {
       try {
-        structured = JSON.parse(accumulated) as AgentStructuredResponse;
+        structured = JSON.parse(accumulated) as TStructured;
       } catch (error) {
         console.warn(
           "[OPENAI] Failed to parse JSON response in stream:",

package/src/providers/OpenRouterProvider.ts

@@ -169,21 +169,30 @@ export class OpenRouterProvider implements AiProvider {
     };
   }
 
-  async generateMessage<TContext = unknown>(
+  async generateMessage<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
-    return this.generateWithBackup(input);
+  ): Promise<GenerateMessageOutput<TStructured>> {
+    return this.generateWithBackup<TContext, TStructured>(input);
   }
 
-  async *generateMessageStream<TContext = unknown>(
+  async *generateMessageStream<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
-    yield* this.generateStreamWithBackup(input);
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
+    yield* this.generateStreamWithBackup<TContext, TStructured>(input);
   }
 
-  private async generateWithBackup<TContext = unknown>(
+  private async generateWithBackup<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
+  ): Promise<GenerateMessageOutput<TStructured>> {
     // Try primary model first
     try {
       return await this.generateWithModel(this.primaryModel, input);
@@ -212,7 +221,7 @@ export class OpenRouterProvider implements AiProvider {
         try {
           const result = await this.generateWithModel(backupModel, input);
           console.log(`[OPENROUTER] Backup model ${backupModel} succeeded`);
-          return result;
+          return result as GenerateMessageOutput<TStructured>;
         } catch (backupError: unknown) {
           const backupErrMsg = getErrorMessage(backupError);
           console.warn(
@@ -240,10 +249,13 @@ export class OpenRouterProvider implements AiProvider {
     }
   }
 
-  private async generateWithModel<TContext = unknown>(
+  private async generateWithModel<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     model: string,
     input: GenerateMessageInput<TContext>
-  ): Promise<GenerateMessageOutput> {
+  ): Promise<GenerateMessageOutput<TStructured>> {
     const operation = async (): Promise<GenerateMessageOutput> => {
       const params: ChatCompletionCreateParamsNonStreaming = {
         model,
@@ -368,12 +380,15 @@ export class OpenRouterProvider implements AiProvider {
       this.retryConfig.timeout,
       this.retryConfig.retries,
       `OpenRouter ${model}`
-    );
+    ) as Promise<GenerateMessageOutput<TStructured>>;
   }
 
-  private async *generateStreamWithBackup<TContext = unknown>(
+  private async *generateStreamWithBackup<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     // Try primary model first
     try {
       yield* this.generateStreamWithModel(this.primaryModel, input);
@@ -430,10 +445,13 @@ export class OpenRouterProvider implements AiProvider {
     }
   }
 
-  private async *generateStreamWithModel<TContext = unknown>(
+  private async *generateStreamWithModel<
+    TContext = unknown,
+    TStructured = AgentStructuredResponse
+  >(
     model: string,
     input: GenerateMessageInput<TContext>
-  ): AsyncGenerator<GenerateMessageStreamChunk> {
+  ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
     const params = {
       ...this.config,
       model,
@@ -493,10 +511,10 @@ export class OpenRouterProvider implements AiProvider {
     }
 
     // Parse JSON response if JSON mode was enabled
-    let structured: AgentStructuredResponse | undefined;
+    let structured: TStructured | undefined;
     if (input.parameters?.jsonMode && accumulated) {
       try {
-        structured = JSON.parse(accumulated) as AgentStructuredResponse;
+        structured = JSON.parse(accumulated) as TStructured;
       } catch (error) {
         console.warn(
           "[OPENROUTER] Failed to parse JSON response in stream:",

package/src/types/agent.ts

@@ -25,6 +25,7 @@ export enum CompositionMode {
  * Forward declare observation types
  */
 import type { ObservationOptions } from "./observation";
+import { PreparationEngineOptions } from "@core/PreparationEngine";
 
 /**
  * Context lifecycle hooks for managing state persistence
@@ -74,6 +75,8 @@ export interface AgentOptions<TContext = unknown> {
   ai: AiProvider;
   /** Maximum number of processing iterations per request */
   maxEngineIterations?: number;
+  /** Optional parallelism controls for preparation engine */
+  preparation?: PreparationEngineOptions;
   /** Composition mode for response generation */
   compositionMode?: CompositionMode;
   /** Initial terms for domain glossary */