@falai/agent 2.2.4 → 2.4.2

package/src/providers/errorClassification.ts

@@ -0,0 +1,172 @@
+/**
+ * Shared provider error utilities: classification of SDK/HTTP errors onto
+ * normalized ProviderErrorCode values, backup-model eligibility, and
+ * wrapping of terminal failures in ProviderError.
+ *
+ * The classification is derived once and reused for both backup-model
+ * decisions and final error wrapping, so the two can never drift apart.
+ */
+
+import { ProviderError, type ProviderErrorCode } from "../types/errors";
+
+/**
+ * Shape of errors with status/code properties thrown by provider SDKs
+ */
+export interface ErrorWithStatus {
+  status?: number;
+  code?: string;
+  message?: string;
+  type?: string;
+}
+
+/**
+ * Type guard to check if error is ErrorWithStatus
+ */
+export 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
+ */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (isErrorWithStatus(error) && error.message) {
+    return error.message;
+  }
+  return String(error);
+}
+
+/**
+ * Provider-specific signals treated as "overloaded/unavailable", in
+ * addition to the shared defaults (HTTP 500/503 and the common message
+ * substrings below).
+ */
+export interface ErrorClassificationOptions {
+  /** Extra HTTP statuses treated as overloaded (e.g. Anthropic's 529) */
+  overloadedStatuses?: readonly number[];
+  /** Error `code` values treated as overloaded/unavailable (e.g. "model_not_found") */
+  overloadedCodes?: readonly string[];
+  /** Error `type` values treated as overloaded (e.g. Anthropic's "overloaded_error") */
+  overloadedTypes?: readonly string[];
+  /** Extra message substrings treated as overloaded (e.g. OpenRouter's "capacity") */
+  overloadedMessages?: readonly string[];
+}
+
+/**
+ * Message substrings every provider historically treated as
+ * overloaded/unavailable for backup-model purposes.
+ */
+const DEFAULT_OVERLOADED_MESSAGES: readonly string[] = [
+  "overloaded",
+  "unavailable",
+  "internal error",
+  "Internal error",
+];
+
+/**
+ * Classify an unknown error into a normalized ProviderErrorCode.
+ *
+ * Overload/availability checks run first so that backup-model decisions
+ * (rate_limited/overloaded) match the historical shouldUseBackupModel
+ * predicate exactly.
+ */
+export function classifyProviderError(
+  error: unknown,
+  options: ErrorClassificationOptions = {}
+): ProviderErrorCode {
+  if (!isErrorWithStatus(error)) {
+    return "unknown";
+  }
+
+  const { status, code, type } = error;
+  const message = getErrorMessage(error);
+
+  // Server errors / overload
+  if (status === 500 || status === 503) {
+    return "overloaded";
+  }
+
+  // Rate limiting
+  if (status === 429) {
+    return "rate_limited";
+  }
+
+  // Provider-specific overload/unavailability signals
+  if (status !== undefined && options.overloadedStatuses?.includes(status)) {
+    return "overloaded";
+  }
+  if (code !== undefined && options.overloadedCodes?.includes(code)) {
+    return "overloaded";
+  }
+  if (type !== undefined && options.overloadedTypes?.includes(type)) {
+    return "overloaded";
+  }
+  const overloadedMessages = options.overloadedMessages
+    ? [...DEFAULT_OVERLOADED_MESSAGES, ...options.overloadedMessages]
+    : DEFAULT_OVERLOADED_MESSAGES;
+  if (overloadedMessages.some((pattern) => message.includes(pattern))) {
+    return "overloaded";
+  }
+
+  // Non-retriable classifications (never triggered backup models)
+  if (status === 401 || status === 403) {
+    return "auth";
+  }
+  if (status === 400 || status === 404 || status === 422) {
+    return "invalid_request";
+  }
+  if (
+    status === 408 ||
+    message.includes("timed out") ||
+    message.includes("timeout")
+  ) {
+    return "timeout";
+  }
+  if (
+    message.includes("fetch failed") ||
+    message.includes("ECONNREFUSED") ||
+    message.includes("ECONNRESET") ||
+    message.includes("ETIMEDOUT") ||
+    message.includes("network")
+  ) {
+    return "network";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Whether an error code qualifies for trying backup models.
+ * Mirrors the historical shouldUseBackupModel predicate.
+ */
+export function isBackupEligible(code: ProviderErrorCode): boolean {
+  return code === "rate_limited" || code === "overloaded";
+}
+
+/**
+ * Wrap a terminal failure (after retries/backup exhaustion) in a
+ * normalized ProviderError, preserving the original error as `cause`.
+ * Already-wrapped errors pass through untouched.
+ */
+export function toProviderError(
+  error: unknown,
+  provider: string,
+  options?: ErrorClassificationOptions
+): ProviderError {
+  if (error instanceof ProviderError) {
+    return error;
+  }
+  return new ProviderError(
+    classifyProviderError(error, options),
+    provider,
+    getErrorMessage(error),
+    error
+  );
+}

package/src/providers/index.ts

@@ -17,3 +17,16 @@ export type { OpenRouterProviderOptions } from "./OpenRouterProvider";
 
 export { DeepSeekProvider } from "./DeepSeekProvider";
 export type { DeepSeekProviderOptions } from "./DeepSeekProvider";
+
+export { OpenAICompatibleProvider } from "./OpenAICompatibleProvider";
+export type {
+  OpenAICompatibleProviderInit,
+  OpenAICompatibleRequestConfig,
+} from "./OpenAICompatibleProvider";
+
+export {
+  classifyProviderError,
+  isBackupEligible,
+  toProviderError,
+} from "./errorClassification";
+export type { ErrorClassificationOptions } from "./errorClassification";

package/src/types/agent.ts

@@ -267,7 +267,8 @@ export interface Instruction<TContext = unknown, TData = unknown> {
    */
   kind?: 'must' | 'never' | 'should';
   /**
-   * AI-evaluated activation condition. String or array of strings (OR semantics).
+   * AI-evaluated activation condition. Non-`!` strings are OR alternatives;
+   * `!` strings are OR exclusions where any match inhibits the instruction.
    * Undefined = always active. Functions are NOT allowed here — use `if`.
    */
   when?: ConditionWhen;

package/src/types/ai.ts

@@ -132,6 +132,25 @@ export interface GenerateMessageStreamChunk<
   structured?: TStructured;
 }
 
+/**
+ * Static capability flags exposed by a provider implementation.
+ *
+ * Values describe what the implementation actually does (e.g. Anthropic
+ * enforces JSON output via a prompt instruction, not a native schema mode).
+ */
+export interface ProviderCapabilities {
+  /** Provider supports tool/function calling */
+  supportsTools: boolean;
+  /** Provider natively enforces a JSON schema on output (vs. prompt-based JSON instruction) */
+  supportsNativeJsonSchema: boolean;
+  /** Provider supports streaming responses */
+  supportsStreaming: boolean;
+  /** Provider surfaces tool calls during streaming */
+  supportsStreamingToolCalls: boolean;
+  /** Provider supports prompt caching */
+  supportsPromptCaching: boolean;
+}
+
 /**
  * AI provider interface (strategy pattern)
  */
@@ -139,6 +158,9 @@ export interface AiProvider {
   /** Provider name/identifier */
   readonly name: string;
 
+  /** Static capability flags for this provider implementation */
+  capabilities: ProviderCapabilities;
+
   /**
    * Generate a message based on prompt and context
    */

package/src/types/errors.ts

@@ -16,3 +16,60 @@ export class NotImplementedError extends Error {
         this.name = 'NotImplementedError';
     }
 }
+
+/**
+ * Normalized error codes for AI provider failures.
+ *
+ * Providers map their SDK/HTTP errors onto these codes so callers can
+ * handle failures uniformly regardless of which provider is configured.
+ */
+export type ProviderErrorCode =
+    | 'rate_limited'
+    | 'overloaded'
+    | 'auth'
+    | 'invalid_request'
+    | 'schema_rejected'
+    | 'timeout'
+    | 'network'
+    | 'unknown';
+
+/**
+ * Normalized error thrown by AI providers for terminal failures — i.e.
+ * after retries and backup models (if any) have been exhausted.
+ *
+ * The original SDK/HTTP error is preserved as `cause` for debugging and
+ * provider-specific handling.
+ */
+export class ProviderError extends Error {
+    constructor(
+        public readonly code: ProviderErrorCode,
+        public readonly provider: string,
+        message: string,
+        public readonly cause?: unknown,
+    ) {
+        super(message);
+        this.name = 'ProviderError';
+    }
+}
+
+/**
+ * Thrown by the persistence layer when a session save carries a stale
+ * `version` — i.e. another writer persisted the session after this one
+ * loaded it (concurrent respond() calls, parallel webhooks, two tabs).
+ *
+ * Handlers should reload the session and retry or surface the conflict.
+ */
+export class SessionConflictError extends Error {
+    constructor(
+        public readonly sessionId: string,
+        public readonly expectedVersion: number,
+        public readonly actualVersion: number | undefined,
+    ) {
+        super(
+            `[SessionConflictError] Session "${sessionId}" was modified concurrently: ` +
+            `expected version ${expectedVersion}, found ${actualVersion ?? 'none'}. ` +
+            `Reload the session and retry the operation.`
+        );
+        this.name = 'SessionConflictError';
+    }
+}

package/src/types/flow.ts

@@ -25,8 +25,10 @@ export type ConditionIf<TContext = unknown, TData = unknown> =
   | ConditionPredicate<TContext, TData>[];
 
 /**
- * The `when` field shape: a single AI-evaluated string or array of strings (OR semantics).
- * Functions are NOT allowed on `when` — they belong on `if` only.
+ * The `when` field shape: a single AI-evaluated string or array of strings.
+ * Non-`!` entries use OR semantics. `!`-prefixed entries are OR exclusions:
+ * any matching exclusion inhibits the condition. Functions are NOT allowed on
+ * `when` — they belong on `if` only.
  */
 export type ConditionWhen = string | string[];
 import type { SessionState } from "./session";
@@ -196,7 +198,8 @@ export type BranchPredicate<TContext = unknown, TData = unknown> = (
  */
 export interface BranchEntry<TContext = unknown, TData = unknown> {
   /**
-   * AI-evaluated condition. String or array of strings (OR semantics).
+   * AI-evaluated condition. Non-`!` strings are OR alternatives; `!` strings
+   * are OR exclusions where any match inhibits the branch.
    * Costs LLM tokens. Reuses the same machinery as `step.when`.
    * Only evaluated if `if` passes (or is absent) — code-first short-circuit.
    */
@@ -324,7 +327,8 @@ export interface FlowOptions<TContext = unknown, TData = unknown> {
   description?: string;
 
   /**
-   * AI-evaluated activation condition(s). String or array of strings (OR semantics).
+   * AI-evaluated activation condition(s). Non-`!` strings are OR alternatives;
+   * `!` strings are OR exclusions where any match inhibits activation.
    * Costs LLM tokens. Functions are NOT allowed here — use `if` for code predicates.
    */
   when?: ConditionWhen;
@@ -498,7 +502,8 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
    */
   requires?: (keyof TData)[];
   /**
-   * AI-evaluated activation condition(s). String or array of strings (OR semantics).
+   * AI-evaluated activation condition(s). Non-`!` strings are OR alternatives;
+   * `!` strings are OR exclusions where any match inhibits activation.
    * Costs LLM tokens. Functions are NOT allowed here — use `if` for code predicates.
    */
   when?: ConditionWhen;

package/src/types/history.ts

@@ -64,8 +64,7 @@ export type ToolHistoryItem = {
   role: "tool";
   tool_call_id: string;
   name: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  content: any;
+  content: unknown;
 };
 
 export type SystemHistoryItem = {

package/src/types/index.ts

@@ -69,6 +69,7 @@ export type {
   Signal,
   SignalContext,
   SignalDirective,
+  ResolvedSignalDirective,
   SignalPredicate,
   SignalPredicateContext,
   SignalFiring,
@@ -118,6 +119,7 @@ export type {
   AgentStructuredResponse,
   ReasoningConfig,
   GenerateMessageStreamChunk,
+  ProviderCapabilities,
 } from "./ai";
 
 // Schema types
@@ -136,6 +138,7 @@ export type {
   CreateSessionData,
   SaveMessageOptions,
   CollectedStateData,
+  SessionUpdateOptions,
 } from "./persistence";
 
 // Template types
@@ -146,7 +149,8 @@ export type {
 } from "./template";
 
 // Error types
-export { NotImplementedError } from "./errors";
+export { NotImplementedError, SessionConflictError, ProviderError } from "./errors";
+export type { ProviderErrorCode } from "./errors";
 
 // Internal — ConditionTemplate is NOT exported from the public surface in v2.
 // It remains internally for the condition evaluator utility.

package/src/types/persistence.ts

@@ -27,6 +27,11 @@ export interface SessionData<TData = Record<string, unknown>> {
   completedAt?: Date;
   createdAt: Date;
   updatedAt: Date;
+  /**
+   * Optimistic-concurrency version. Incremented by the repository on every
+   * update. Undefined on rows written by pre-2.4 versions.
+   */
+  version?: number;
 }
 
 /**
@@ -44,6 +49,12 @@ export type CreateSessionData<TData = Record<string, unknown>> = Omit<
  * This is a subset of SessionState, stored within SessionData.
  */
 export interface CollectedStateData<TData = Record<string, unknown>> {
+  /**
+   * User-defined schema version of the agent that wrote this state.
+   * Set from `PersistenceConfig.schemaVersion` on save; checked on load so
+   * `migrateSession` can upgrade state written by older agent deployments.
+   */
+  schemaVersion?: number;
   data: Partial<TData>;
   flowHistory: SessionState<TData>["flowHistory"];
   history?: SessionState<TData>["history"];
@@ -72,6 +83,18 @@ export interface MessageData {
   createdAt: Date;
 }
 
+/**
+ * Options for SessionRepository.update
+ */
+export interface SessionUpdateOptions {
+  /**
+   * Optimistic-concurrency guard. When set, the repository must reject the
+   * update with SessionConflictError if the stored session's `version`
+   * differs from this value.
+   */
+  expectedVersion?: number;
+}
+
 /**
  * Repository interface for sessions
  * Implement this interface with your database of choice
@@ -98,11 +121,17 @@ export interface SessionRepository<TData = Record<string, unknown>> {
   findByUserId(userId: string, limit?: number): Promise<SessionData<TData>[]>;
 
   /**
-   * Update session
+   * Update session.
+   *
+   * When `options.expectedVersion` is provided, the update is a compare-and-swap:
+   * it must throw SessionConflictError if the stored `version` differs (rows with
+   * no stored version — written by pre-2.4 — are accepted). Every successful
+   * update increments `version` by one.
    */
   update(
     id: string,
-    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>,
+    options?: SessionUpdateOptions
   ): Promise<SessionData<TData> | null>;
 
   /**
@@ -229,6 +258,25 @@ export interface PersistenceConfig<TData = Record<string, unknown>> {
    * Can also be provided per-call in methods
    */
   userId?: string;
+
+  /**
+   * Version of the user-defined agent schema. Stamped onto persisted state on
+   * save. When a loaded session carries a different (or missing) schemaVersion,
+   * `migrateSession` is invoked to upgrade it; without a migrator, a warning is
+   * logged and the state is used as-is.
+   */
+  schemaVersion?: number;
+
+  /**
+   * Migrate persisted session state written under an older schemaVersion.
+   * Receives the stored state and the version it was written with
+   * (undefined for pre-versioning rows); must return state valid for the
+   * current schemaVersion.
+   */
+  migrateSession?: (
+    collectedData: CollectedStateData<TData>,
+    fromVersion: number | undefined
+  ) => CollectedStateData<TData> | Promise<CollectedStateData<TData>>;
 }
 
 /**

package/src/types/session.ts

@@ -74,4 +74,13 @@ export interface SessionState<TData = unknown> {
     lastUpdatedAt?: Date;
     [key: string]: unknown;
   };
+
+  /**
+   * Optimistic-concurrency version, managed by the persistence layer.
+   * Incremented on every successful save; a save with a stale version
+   * throws SessionConflictError instead of silently overwriting state
+   * written by a concurrent turn. Undefined for sessions never persisted
+   * or persisted by a pre-2.4 version (no conflict check is performed then).
+   */
+  version?: number;
 }

package/src/types/signals.ts

@@ -128,6 +128,18 @@ export interface SignalDirective<TContext = unknown, TData = unknown>
     replyWith?: string | ((ctx: SignalContext<TContext, TData>) => string);
 }
 
+/**
+ * A signal directive as reported on the response surface (SignalFiring).
+ * `replyWith` has been resolved onto `reply` and stripped by the processor,
+ * leaving a directive that is covariant in TContext — which lets firings
+ * flow into AgentResponse without casts.
+ */
+export type ResolvedSignalDirective<TContext = unknown, TData = unknown> =
+    Directive<TContext, TData> & {
+        /** Stop processing remaining signals for this phase after this handler. */
+        stopOtherSignals?: boolean;
+    };
+
 // ──────────────────────────────────────────────────────────────────────────────
 // Signal context (handler argument)
 // ──────────────────────────────────────────────────────────────────────────────
@@ -311,10 +323,16 @@ export interface SignalFiring<TContext = unknown, TData = unknown> {
     reason?: string;
     /** Extracted data when the signal operates in extraction mode. */
     extracted?: unknown;
-    /** The directive returned by the signal handler (if any). */
-    directive?: SignalDirective<TContext, TData>;
+    /** The directive returned by the signal handler (if any), with `replyWith` already resolved to `reply`. */
+    directive?: ResolvedSignalDirective<TContext, TData>;
     /** Error message if the handler threw. */
     handlerError?: string;
+    /**
+     * Set when the signal matched in extraction mode (`extract` defined) but the
+     * classifier returned no extracted payload — the handler ran with
+     * `extracted: undefined`. Independent of `handlerError`.
+     */
+    extractionError?: string;
     /** Wall-clock duration of the handler invocation in milliseconds. */
     durationMs?: number;
 }

package/src/types/template.ts

@@ -83,8 +83,10 @@ export type Template<TContext = unknown, TData = unknown> =
 export interface ConditionEvaluationResult {
   /** Result of function evaluations only */
   programmaticResult: boolean;
-  /** String values for AI context */
+  /** Positive string values for AI context. Any one may satisfy the condition. */
   aiContextStrings: string[];
+  /** Negative string values for AI context. Any one inhibits the condition. */
+  aiExclusionStrings?: string[];
   /** Whether any functions were evaluated */
   hasProgrammaticConditions: boolean;
   /** Detailed evaluation information for debugging */

package/src/types/tool.ts

@@ -9,7 +9,7 @@ import type { Directive } from "./flow";
 /**
  * Context provided to tool handlers
  */
-export interface ToolContext<TContext = any, TData = any> {
+export interface ToolContext<TContext = unknown, TData = unknown> {
   /** The agent's context data */
   context: TContext;
   /** Complete agent-level data collected so far */
@@ -47,9 +47,9 @@ export interface ToolContext<TContext = any, TData = any> {
  * Result returned by a tool
  */
 export interface ToolResult<
-  TResultData = any,
-  TContext = any,
-  TData = any
+  TResultData = unknown,
+  TContext = unknown,
+  TData = unknown
 > {
   /** The result data */
   data?: TResultData;
@@ -71,9 +71,9 @@ export interface ToolResult<
  * Handler function for a tool
  */
 export type ToolHandler<
-  TContext = any,
-  TData = any,
-  TResult = any
+  TContext = unknown,
+  TData = unknown,
+  TResult = unknown
 > = (
   context: ToolContext<TContext, TData>,
   args?: Record<string, unknown>
@@ -90,9 +90,9 @@ export type ToolHandler<
  * metadata fields optional. `EnhancedTool` is removed from the public surface.
  */
 export interface Tool<
-  TContext = any,
-  TData = any,
-  TResult = any
+  TContext = unknown,
+  TData = unknown,
+  TResult = unknown
 > {
   /** Tool identifier */
   id: string;