@falai/agent 2.7.0 → 3.1.0

package/src/types/agent.ts

@@ -2,17 +2,17 @@
  * Agent-related type definitions
  */
 
-import type { AgentStructuredResponse, AiProvider } from "./ai";
-import type { Tool } from "./tool";
-import type { Directive, FlowOptions, StepRef, StoppedReason } from "./flow";
-import type { PersistenceConfig } from "./persistence";
-import type { SessionState } from "./session";
-import type { Signal, SignalFiring } from "./signals";
-import type { StructuredSchema } from "./schema";
-import type { Event } from "./history";
-import type { Template } from "./template";
-import type { ConditionWhen, ConditionIf } from "./flow";
-import type { PromptCacheConfig } from "./prompt-cache";
+import type { AgentStructuredResponse, AiProvider } from "./ai.js";
+import type { Tool } from "./tool.js";
+import type { Directive, FlowOptions, StepRef, StoppedReason } from "./flow.js";
+import type { PersistenceConfig } from "./persistence.js";
+import type { SessionState } from "./session.js";
+import type { Signal, SignalFiring } from "./signals.js";
+import type { StructuredSchema } from "./schema.js";
+import type { Event } from "./history.js";
+import type { Template } from "./template.js";
+import type { ConditionWhen, ConditionIf } from "./flow.js";
+import type { PromptCacheConfig } from "./prompt-cache.js";
 
 /**
  * Context passed to every lifecycle hook (flow and step).

package/src/types/ai.ts

@@ -2,31 +2,21 @@
  * AI provider types
  */
 
-import type { HistoryItem } from "./history";
+import type { Effort } from "@providerkit/core";
+import type { HistoryItem } from "./history.js";
 
 /**
- * Reasoning/thinking configuration for AI models
+ * How hard the model thinks before answering.
+ *
+ * v3 takes `@providerkit/core`'s effort union, which every provider speaks:
+ * "none" | "low" | "medium" | "high" | "max". Absent means the provider's own
+ * default and is never sent. v2's "minimal" is spelled "low"; `summary` and
+ * `includeThoughts` are gone because they are no longer choices — the shapes
+ * that need them get them switched on whenever an effort is set, which is the
+ * only setting that ever produced reasoning output.
  */
 export interface ReasoningConfig {
-  /**
-   * Effort level for reasoning models (OpenAI: gpt-5, o-series)
-   * - minimal: Fastest, least reasoning
-   * - low: Basic reasoning
-   * - medium: Balanced reasoning
-   * - high: Maximum reasoning effort
-   */
-  effort?: "minimal" | "low" | "medium" | "high";
-  /**
-   * Summary detail level of reasoning process
-   * - auto: Model decides
-   * - concise: Brief summary
-   * - detailed: Full reasoning details
-   */
-  summary?: "auto" | "concise" | "detailed";
-  /**
-   * Whether to include thinking/reasoning in response (Gemini)
-   */
-  includeThoughts?: boolean;
+  effort?: Effort;
 }
 
 /**

package/src/types/compaction.ts

@@ -2,8 +2,8 @@
  * Context compaction types for managing conversation history size
  */
 
-import type { AiProvider } from "./ai";
-import type { HistoryItem } from "./history";
+import type { AiProvider } from "./ai.js";
+import type { HistoryItem } from "./history.js";
 
 /**
  * Configuration for the compaction engine.

package/src/types/errors.ts

@@ -2,6 +2,23 @@
  * Typed error classes for @falai/agent.
  */
 
+/**
+ * The normalized provider failure, and the kinds it comes in.
+ *
+ * v3 re-exports these from `@providerkit/core` rather than keeping a second
+ * copy. The taxonomy is wider there — thirteen kinds named by what actually
+ * fixes them, where this package had eight — so a caller can now tell an
+ * exhausted balance from a per-minute throttle, a plan that never included the
+ * API from a wrong key, and an outgrown context window from a bad request.
+ *
+ * Breaking: the kind lives on `error.kind`, not `error.code`, and the spellings
+ * changed with the taxonomy (`rate_limited` is `rate`, `overloaded` is
+ * `overload`, `invalid_request` splits into `invalid`, `context`, `model` and
+ * `content`). `schema_rejected` is gone: nothing ever produced it.
+ */
+export { ProviderError } from "@providerkit/core";
+export type { ErrorKind } from "@providerkit/core";
+
 /**
  * Typed error for not-yet-implemented surface. Subclass of Error (not of
  * FlowConfigurationError) so handlers can distinguish "not yet built" from
@@ -17,41 +34,6 @@ export class NotImplementedError extends Error {
     }
 }
 
-/**
- * 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

package/src/types/flow.ts

@@ -2,10 +2,10 @@
  * Flow/Journey DSL type definitions
  */
 
-import type { Tool } from "./tool";
-import type { StructuredSchema } from "./schema";
-import type { Instruction, HookContext, ExitReason } from "./agent";
-import type { Template } from "./template";
+import type { Tool } from "./tool.js";
+import type { StructuredSchema } from "./schema.js";
+import type { Instruction, HookContext, ExitReason } from "./agent.js";
+import type { Template } from "./template.js";
 
 // ─── Condition types (v2 when/if split) ──────────────────────────────────────
 
@@ -14,7 +14,7 @@ import type { Template } from "./template";
  * May be async. Used on `if` fields (free to evaluate, no LLM cost).
  */
 export type ConditionPredicate<TContext = unknown, TData = unknown> = (
-  ctx: { data: Partial<TData>; context: TContext; session: import("./session").SessionState<TData>; history: Event[] }
+  ctx: { data: Partial<TData>; context: TContext; session: import("./session.js").SessionState<TData>; history: Event[] }
 ) => boolean | Promise<boolean>;
 
 /**
@@ -31,8 +31,8 @@ export type ConditionIf<TContext = unknown, TData = unknown> =
  * `when` — they belong on `if` only.
  */
 export type ConditionWhen = string | string[];
-import type { SessionState } from "./session";
-import type { Event } from "./history";
+import type { SessionState } from "./session.js";
+import type { Event } from "./history.js";
 
 /**
  * Reason why execution stopped.

package/src/types/history.ts

@@ -16,7 +16,7 @@ export enum MessageRole {
   SYSTEM = "system",
 }
 
-import type { SessionState } from "./session";
+import type { SessionState } from "./session.js";
 
 /**
  * Types of events in the interaction history

package/src/types/index.ts

@@ -19,7 +19,7 @@ export type {
   ValidationResult,
   HookContext,
   ExitReason,
-} from "./agent";
+} from "./agent.js";
 
 // History types
 export type {
@@ -39,8 +39,8 @@ export type {
   AssistantHistoryItem,
   SystemHistoryItem,
   ToolHistoryItem,
-} from "./history";
-export { EventKind, MessageRole } from "./history";
+} from "./history.js";
+export { EventKind, MessageRole } from "./history.js";
 
 // Flow types
 export type {
@@ -60,10 +60,10 @@ export type {
   ConditionWhen,
   StoppedReason,
   PrepareResult,
-} from "./flow";
+} from "./flow.js";
 
 // Session types
-export type { SessionState } from "./session";
+export type { SessionState } from "./session.js";
 
 // Signals types (canonical source)
 export type {
@@ -77,7 +77,7 @@ export type {
   SignalSchema,
   SignalsState,
   SignalTriggerState,
-} from "./signals";
+} from "./signals.js";
 
 // Tool types
 export type {
@@ -96,21 +96,21 @@ export type {
   ValidationConfig,
   ApiCallConfig,
   ComputationConfig
-} from "./tool";
-export { ToolScope } from "./tool";
+} from "./tool.js";
+export { ToolScope } from "./tool.js";
 
 // Compaction types
 export type {
   CompactionOptions,
   CompactionResult,
-} from "./compaction";
+} from "./compaction.js";
 
 // Prompt cache types
 export type {
   PromptSectionType,
   PromptCacheConfig,
   SectionCompute,
-} from "./prompt-cache";
+} from "./prompt-cache.js";
 
 // AI provider types
 export type {
@@ -121,10 +121,10 @@ export type {
   ReasoningConfig,
   GenerateMessageStreamChunk,
   ProviderCapabilities,
-} from "./ai";
+} from "./ai.js";
 
 // Schema types
-export type { StructuredSchema } from "./schema";
+export type { StructuredSchema } from "./schema.js";
 
 // Persistence types
 export type {
@@ -140,18 +140,18 @@ export type {
   SaveMessageOptions,
   CollectedStateData,
   SessionUpdateOptions,
-} from "./persistence";
+} from "./persistence.js";
 
 // Template types
 export type {
   Template,
   TemplateContext,
   ConditionEvaluationResult
-} from "./template";
+} from "./template.js";
 
 // Error types
-export { NotImplementedError, SessionConflictError, ProviderError } from "./errors";
-export type { ProviderErrorCode } from "./errors";
+export { NotImplementedError, SessionConflictError, ProviderError } from "./errors.js";
+export type { ErrorKind } from "./errors.js";
 
 // Internal — ConditionTemplate is NOT exported from the public surface in v2.
 // It remains internally for the condition evaluator utility.
@@ -161,4 +161,4 @@ export {
   createConditionEvaluator,
   extractAIContextStrings,
   hasProgrammaticConditions
-} from "../utils/condition";
+} from "../utils/condition.js";

package/src/types/persistence.ts

@@ -3,8 +3,8 @@
  * Support for optional database persistence (Prisma, etc.)
  */
 
-import type { Event, MessageRole } from "./history";
-import type { SessionState } from "./session";
+import type { Event, MessageRole } from "./history.js";
+import type { SessionState } from "./session.js";
 
 /**
  * Session status enum

package/src/types/session.ts

@@ -2,12 +2,12 @@
  * Session step types for tracking conversation progress
  */
 
-import type { History } from "./history";
-import type { Directive } from "./flow";
-import type { SignalsState } from "./signals";
+import type { History } from "./history.js";
+import type { Directive } from "./flow.js";
+import type { SignalsState } from "./signals.js";
 
 // Re-export for backward compatibility — canonical declarations live in ./signals.ts
-export type { SignalsState, SignalTriggerState } from "./signals";
+export type { SignalsState, SignalTriggerState } from "./signals.js";
 
 /**
  * Session state tracks the current position in the conversation flow

package/src/types/signals.ts

@@ -7,9 +7,9 @@
  * compatibility within the same major.
  */
 
-import type { SessionState } from "./session";
-import type { Directive } from "./flow";
-import type { Event } from "./history";
+import type { SessionState } from "./session.js";
+import type { Directive } from "./flow.js";
+import type { Event } from "./history.js";
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Persistence types (shape locked in v2.0 — DO NOT modify)

package/src/types/template.ts

@@ -1,5 +1,5 @@
-import type { SessionState } from "./session";
-import type { Event, MessageRole } from "./history";
+import type { SessionState } from "./session.js";
+import type { Event, MessageRole } from "./history.js";
 
 /**
  * Context object passed to template functions for dynamic rendering.

package/src/types/tool.ts

@@ -3,8 +3,8 @@
  * Tool system type definitions
  */
 
-import type { Event, StepRef, ValidationResult } from "./index";
-import type { Directive } from "./flow";
+import type { Event, StepRef, ValidationResult } from "./index.js";
+import type { Directive } from "./flow.js";
 
 /**
  * Context provided to tool handlers

package/src/utils/condition.ts

@@ -1,6 +1,6 @@
-import type { TemplateContext, ConditionEvaluationResult } from "../types/template";
-import { createTemplateContext } from "./template";
-import { logger } from './logger'
+import type { TemplateContext, ConditionEvaluationResult } from "../types/template.js";
+import { createTemplateContext } from "./template.js";
+import { logger } from './logger.js'
 
 /**
  * Condition template — kept as a private type for internal use by the evaluator.

package/src/utils/event.ts

@@ -1,4 +1,4 @@
-import { type Event, EventKind } from "../types";
+import { type Event, EventKind } from "../types/index.js";
 /**
  * Helper to extract last message from history
  */

package/src/utils/history.ts

@@ -3,9 +3,9 @@
  * Convert simplified history format to internal Event format
  */
 
-import type { Event, MessageEventData, ToolEventData, StatusEventData } from "../types";
-import { EventKind, MessageRole } from "../types";
-import type { History, HistoryItem, UserHistoryItem, AssistantHistoryItem, ToolHistoryItem } from "../types/history";
+import type { Event, MessageEventData, ToolEventData, StatusEventData } from "../types/index.js";
+import { EventKind, MessageRole } from "../types/index.js";
+import type { History, HistoryItem, UserHistoryItem, AssistantHistoryItem, ToolHistoryItem } from "../types/history.js";
 
 /**
  * Convert a simplified history item to an internal Event

package/src/utils/index.ts

@@ -9,7 +9,7 @@ export {
   generateToolId,
   generateInlineToolId,
   generateSignalId,
-} from "./id";
+} from "./id.js";
 
 // Session management
 export {
@@ -26,7 +26,7 @@ export {
   mergeCollected,
   sessionStepToData,
   sessionDataToStep,
-} from "./session";
+} from "./session.js";
 
 // Template rendering
 export {
@@ -34,13 +34,13 @@ export {
   renderMany,
   formatKnowledgeBase,
   createTemplateContext,
-} from "./template";
+} from "./template.js";
 
 // Cloning utilities
-export { cloneDeep } from "./clone";
+export { cloneDeep } from "./clone.js";
 
 // Event utilities
-export { getLastMessageFromHistory } from "./event";
+export { getLastMessageFromHistory } from "./event.js";
 
 // History utilities
 export {
@@ -52,33 +52,13 @@ export {
   assistantMessage,
   toolMessage,
   systemMessage,
-} from "./history";
+} from "./history.js";
 
 // Logging
-export { LoggerLevel, logger } from "./logger";
-
-// Retry utilities
-export type {
-  RetryOptions,
-  StreamRetryOptions,
-  RetryConfig,
-  BackupFallbackBase,
-  BackupFallbackOptions,
-  StreamBackupFallbackOptions,
-} from "./retry";
-export {
-  retry,
-  withTimeoutAndRetry,
-  withStreamRetry,
-  resolveRetryConfig,
-  combineAbortSignals,
-  withBackupFallback,
-  streamWithBackupFallback,
-  backupFallbackLogging,
-} from "./retry";
+export { LoggerLevel, logger } from "./logger.js";
 
 // Completion helpers
-export { effectiveMessageText, assertUsableCompletion } from "./completion";
+export { effectiveMessageText, assertUsableCompletion } from "./completion.js";
 
 // Condition utilities
 export {
@@ -86,10 +66,10 @@ export {
   createConditionEvaluator,
   extractAIContextStrings,
   hasProgrammaticConditions,
-} from "./condition";
+} from "./condition.js";
 
 // JSON utilities
-export { parseJSONResponse, tryParseJSONResponse } from "./json";
+export { parseJSONResponse, tryParseJSONResponse } from "./json.js";
 
 // Serialization utilities
-export { serializeToolResult, isToolResultLike, extractResultDirectives } from "./serialize";
+export { serializeToolResult, isToolResultLike, extractResultDirectives } from "./serialize.js";

package/src/utils/serialize.ts

@@ -2,8 +2,8 @@
  * Serialization utilities for tool results and other data
  */
 
-import type { Directive } from "../types/flow";
-import type { ToolResult } from "../types/tool";
+import type { Directive } from "../types/flow.js";
+import type { ToolResult } from "../types/tool.js";
 
 /**
  * Decide whether a tool handler's return value is a ToolResult-shaped object.

package/src/utils/session.ts

@@ -1,9 +1,9 @@
-import { cloneDeep } from "./clone";
-import type { SessionState } from "../types/session";
-import type { History } from "../types/history";
-import type { Directive } from "../types/flow";
-import type { CollectedStateData } from "../types/persistence";
-import { logger } from "./logger";
+import { cloneDeep } from "./clone.js";
+import type { SessionState } from "../types/session.js";
+import type { History } from "../types/history.js";
+import type { Directive } from "../types/flow.js";
+import type { CollectedStateData } from "../types/persistence.js";
+import { logger } from "./logger.js";
 
 /**
  * Helper to create a new session

package/src/utils/template.ts

@@ -1,6 +1,6 @@
-import type { Template, TemplateContext } from "../types";
-import type { Event, MessageEventData } from "../types/history";
-import { MessageRole, EventKind } from "../types/history";
+import type { Template, TemplateContext } from "../types/index.js";
+import type { Event, MessageEventData } from "../types/history.js";
+import { MessageRole, EventKind } from "../types/history.js";
 
 /**
  * Renders a template, which can be a string or a function, using the provided context.

package/dist/cjs/providers/errorClassification.d.ts

@@ -1,68 +0,0 @@
-/**
- * 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 declare function isErrorWithStatus(error: unknown): error is ErrorWithStatus;
-/**
- * Safely extract error message
- */
-export declare function getErrorMessage(error: unknown): string;
-/**
- * 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[];
-}
-/**
- * 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 declare function classifyProviderError(error: unknown, options?: ErrorClassificationOptions): ProviderErrorCode;
-/**
- * Whether an error code qualifies for trying backup models.
- * Mirrors the historical shouldUseBackupModel predicate.
- */
-export declare function isBackupEligible(code: ProviderErrorCode): boolean;
-/**
- * Whether an error is worth retrying with backoff: transient availability,
- * rate-limiting, timeouts and network faults only. Deterministic failures —
- * auth (401/403), invalid request (400/404/422) and caller aborts — must fail
- * fast instead of burning the retry budget on the same outcome.
- */
-export declare function isRetriableProviderError(error: unknown, options?: ErrorClassificationOptions): boolean;
-/**
- * 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 declare function toProviderError(error: unknown, provider: string, options?: ErrorClassificationOptions): ProviderError;
-//# sourceMappingURL=errorClassification.d.ts.map

package/dist/cjs/providers/errorClassification.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errorClassification.d.ts","sourceRoot":"","sources":["../../../src/providers/errorClassification.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAM1E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,qFAAqF;IACrF,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,sFAAsF;IACtF,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,oFAAoF;IACpF,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAaD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,0BAA+B,GACvC,iBAAiB,CA4DnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAEjE;AAcD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAWT;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,0BAA0B,GACnC,aAAa,CAUf"}