@falai/agent 2.6.1 → 3.0.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).
@@ -126,6 +126,13 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
    * Rendered into the system prompt as "who you are and how you communicate."
    */
   persona?: Template<TContext>;
+  /**
+   * Hard bound on session.history length (default: 400). The oldest entries
+   * are trimmed — never splitting an assistant/tool pair — when the bound is
+   * exceeded and no compaction strategy shrank the history first. Set 0 to
+   * disable bounding entirely.
+   */
+  maxHistoryMessages?: number;
   /** Enable debug logging */
   debug?: boolean;
   /** Default context data available to the agent */
@@ -330,6 +337,13 @@ export interface AppliedInstruction {
   scopeRef?: string;
 }
 
+/** A flow that left its active position during a turn. */
+export interface EndedFlow {
+  flowId: string;
+  title?: string;
+  reason: StoppedReason;
+}
+
 export interface AgentResponse<TData = Record<string, unknown>> {
   message: string;
   session?: SessionState<TData>;
@@ -350,6 +364,17 @@ export interface AgentResponse<TData = Record<string, unknown>> {
    * Mirrors the observability framing of `executedSteps` and `appliedInstructions`.
    */
   triggeredSignals?: SignalFiring<unknown, TData>[];
+  /**
+   * Provider-reported usage for this turn's primary generation (routing and
+   * extraction sub-calls are not included).
+   */
+  metadata?: { tokensUsed?: number };
+  /**
+   * Flows that LEFT their active position this turn — completions, redirects,
+   * resets. planTurn knows these internally; surfaced so consumers stop
+   * re-deriving them from executedSteps + session cursor inspection.
+   */
+  endedFlows?: EndedFlow[];
 }
 
 export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {

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.
@@ -59,21 +59,32 @@ export type StoppedReason =
  * Result that a prepare/finalize hook may return to issue directives.
  * All fields are optional — returning void is also valid.
  */
-export interface PrepareResult {
+export interface PrepareResult<TContext = unknown, TData = unknown> {
   /** Partial data to merge into session.data */
-  dataUpdate?: Record<string, unknown>;
+  dataUpdate?: Partial<TData>;
   /** Partial context to merge into the agent context */
-  contextUpdate?: Record<string, unknown>;
+  contextUpdate?: Partial<TContext>;
   /** If true, stop the auto-step chain and end the turn with `reply` */
   halt?: boolean;
   /** Verbatim reply to send when halting */
   reply?: string;
   /** Jump to a step within the current flow */
-  goToStep?: string;
+  goToStep?: string | { step: string; flow?: string; data?: Partial<TData>; reason?: string; };
   /** Jump to another flow */
-  goTo?: string;
+  goTo?: string | { flow?: string; step?: string; data?: Partial<TData>; reason?: string; carry?: 'preserve' | 'reset'; };
   /** Mark the current flow as complete */
-  complete?: boolean;
+  complete?: true | { next?: Directive<unknown, unknown>; reason?: string; };
+  /**
+   * Prompt lines appended to this turn's generation prompt. Pre-LLM
+   * augmentation: honored by auto steps' prepare; other step kinds drop it
+   * with a loud warning rather than silently ignoring it.
+   */
+  appendPrompt?: string[];
+  /**
+   * Extra tools made available for this turn only. Same auto-step-only
+   * honoring as {@link appendPrompt}.
+   */
+  injectTools?: Tool[];
 }
 
 
@@ -416,46 +427,32 @@ export interface FlowOptions<TContext = unknown, TData = unknown> {
 }
 
 /**
- * Step lifecycle hooks for managing step-specific behavior.
+ * Step lifecycle hooks for managing step-specific behavior. Desugared onto the
+ * equivalent top-level `prepare` / `finalize` fields by the Step constructor —
+ * both spellings run through the same lifecycle machinery, and declaring both
+ * runs them in sequence with their returns merged (Algorithm 4).
  *
- * Pre-LLM hooks (`onEnter`, `prepare`) return `void | Directive`.
- * Post-LLM hooks (`finalize`) return `void | Directive`.
- * Informational hooks (`onExit`) return `void`.
+ * `prepare` runs before the AI responds; `finalize` runs after the turn's
+ * generation completes (before persistence). Both may return a Directive to
+ * write state or redirect flow.
  */
 export interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
   /**
-   * Called on step entry. May return a Directive to augment the prompt,
-   * inject tools, halt, or redirect.
-   * Pre-LLM fields (`appendPrompt`, `injectTools`, `halt`) are honored here.
-   */
-  onEnter?: (
-    ctx: HookContext<TContext, TData>
-  ) => void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
-
-  /**
-   * Called when the step is exited. Informational only — cannot influence flow control.
-   * Receives the reason the step was exited.
-   */
-  onExit?: (
-    ctx: HookContext<TContext, TData>,
-    reason: ExitReason
-  ) => void | Promise<void>;
-
-  /**
-   * Called pre-LLM. May return a Directive to augment the prompt,
-   * inject tools, or halt the LLM call.
-   * Pre-LLM fields (`appendPrompt`, `injectTools`, `halt`) are honored here.
+   * Called pre-LLM (alongside any top-level `prepare`). May return a Directive
+   * to write state or redirect flow.
    */
   prepare?: (
-    ctx: HookContext<TContext, TData>
+    context: TContext,
+    data?: Partial<TData>
   ) => void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
 
   /**
-   * Called post-LLM. May return a Directive to redirect flow, write state,
-   * or emit a verbatim reply.
+   * Called after generation (alongside any top-level `finalize`, before
+   * persistence). May return a Directive to redirect flow or write state.
    */
   finalize?: (
-    ctx: HookContext<TContext, TData>
+    context: TContext,
+    data?: Partial<TData>
   ) => void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
 }
 
@@ -475,12 +472,12 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
   prepare?:
   | string
   | Tool<TContext, TData>
-  | ((context: TContext, data?: Partial<TData>) => void | PrepareResult | Promise<void | PrepareResult>);
+  | ((context: TContext, data?: Partial<TData>) => void | PrepareResult<TContext, TData> | Promise<void | PrepareResult<TContext, TData>>);
   /** Programmatic function or tool to run after AI responds */
   finalize?:
   | string
   | Tool<TContext, TData>
-  | ((context: TContext, data?: Partial<TData>) => void | PrepareResult | Promise<void | PrepareResult>);
+  | ((context: TContext, data?: Partial<TData>) => void | PrepareResult<TContext, TData> | Promise<void | PrepareResult<TContext, TData>>);
 
   /**
    * Fields to collect from the conversation in this step
@@ -569,8 +566,9 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
   branches?: BranchMap<TContext, TData>;
 
   /**
-   * Step lifecycle hooks for managing step-specific behavior.
-   * Provides onEnter, onExit, prepare, and finalize hooks that receive HookContext.
+   * Step lifecycle hooks — an alternative spelling of the top-level
+   * `prepare` / `finalize` fields. Both spellings run when declared together;
+   * returns are merged via Algorithm 4.
    */
   hooks?: StepLifecycleHooks<TContext, TData>;
 }

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

@@ -12,13 +12,14 @@ export type {
   AppliedInstruction,
   AgentResponseStreamChunk,
   AgentResponse,
+  EndedFlow,
   ContextLifecycleHooks,
   ContextProvider,
   ValidationError,
   ValidationResult,
   HookContext,
   ExitReason,
-} from "./agent";
+} from "./agent.js";
 
 // History types
 export type {
@@ -38,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 {
@@ -59,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 {
@@ -76,7 +77,7 @@ export type {
   SignalSchema,
   SignalsState,
   SignalTriggerState,
-} from "./signals";
+} from "./signals.js";
 
 // Tool types
 export type {
@@ -95,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 {
@@ -120,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 {
@@ -139,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.
@@ -160,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
@@ -65,6 +65,8 @@ export interface ToolResult<
   meta?: Record<string, unknown>;
   /** Emit a directive declaratively (alternative to ctx.dispatch). */
   directive?: Directive<TContext, TData>;
+  /** Emit multiple directives at once (alternative to repeated dispatch calls). */
+  directives?: Directive<TContext, TData>[];
 }
 
 /**

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,13 +9,16 @@ export {
   generateToolId,
   generateInlineToolId,
   generateSignalId,
-} from "./id";
+} from "./id.js";
 
 // Session management
 export {
   createSession,
   createSessionId,
+  boundConversationHistory,
+  DEFAULT_MAX_HISTORY_MESSAGES,
   createPersistedState,
+  restoreSession,
   enterFlow,
   enterStep,
   completeCurrentFlow,
@@ -23,7 +26,7 @@ export {
   mergeCollected,
   sessionStepToData,
   sessionDataToStep,
-} from "./session";
+} from "./session.js";
 
 // Template rendering
 export {
@@ -31,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 {
@@ -49,17 +52,13 @@ export {
   assistantMessage,
   toolMessage,
   systemMessage,
-} from "./history";
+} from "./history.js";
 
 // Logging
-export { LoggerLevel, logger } from "./logger";
-
-// Retry utilities
-export type { RetryOptions, StreamRetryOptions, RetryConfig } from "./retry";
-export { retry, withTimeoutAndRetry, withStreamRetry, resolveRetryConfig, combineAbortSignals } from "./retry";
+export { LoggerLevel, logger } from "./logger.js";
 
 // Completion helpers
-export { effectiveMessageText, assertUsableCompletion } from "./completion";
+export { effectiveMessageText, assertUsableCompletion } from "./completion.js";
 
 // Condition utilities
 export {
@@ -67,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 } from "./serialize";
+export { serializeToolResult, isToolResultLike, extractResultDirectives } from "./serialize.js";