@falai/agent 2.6.1 → 2.7.0

package/src/types/flow.ts

@@ -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/index.ts

@@ -12,6 +12,7 @@ export type {
   AppliedInstruction,
   AgentResponseStreamChunk,
   AgentResponse,
+  EndedFlow,
   ContextLifecycleHooks,
   ContextProvider,
   ValidationError,

package/src/types/tool.ts

@@ -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/index.ts

@@ -15,7 +15,10 @@ export {
 export {
   createSession,
   createSessionId,
+  boundConversationHistory,
+  DEFAULT_MAX_HISTORY_MESSAGES,
   createPersistedState,
+  restoreSession,
   enterFlow,
   enterStep,
   completeCurrentFlow,
@@ -55,8 +58,24 @@ export {
 export { LoggerLevel, logger } from "./logger";
 
 // Retry utilities
-export type { RetryOptions, StreamRetryOptions, RetryConfig } from "./retry";
-export { retry, withTimeoutAndRetry, withStreamRetry, resolveRetryConfig, combineAbortSignals } from "./retry";
+export type {
+  RetryOptions,
+  StreamRetryOptions,
+  RetryConfig,
+  BackupFallbackBase,
+  BackupFallbackOptions,
+  StreamBackupFallbackOptions,
+} from "./retry";
+export {
+  retry,
+  withTimeoutAndRetry,
+  withStreamRetry,
+  resolveRetryConfig,
+  combineAbortSignals,
+  withBackupFallback,
+  streamWithBackupFallback,
+  backupFallbackLogging,
+} from "./retry";
 
 // Completion helpers
 export { effectiveMessageText, assertUsableCompletion } from "./completion";
@@ -73,4 +92,4 @@ export {
 export { parseJSONResponse, tryParseJSONResponse } from "./json";
 
 // Serialization utilities
-export { serializeToolResult } from "./serialize";
+export { serializeToolResult, isToolResultLike, extractResultDirectives } from "./serialize";

package/src/utils/retry.ts

@@ -2,6 +2,7 @@
  * Retry utility with exponential backoff
  */
 import {logger} from './logger'
+import { getErrorMessage } from '../providers/errorClassification'
 
 export interface RetryOptions<T> {
   operation: () => Promise<T>;
@@ -9,6 +10,13 @@ export interface RetryOptions<T> {
   delay: (attempt: number) => number;
   onRetry?: (attempt: number, error: unknown) => void;
   onFailure?: (error: unknown) => boolean;
+  /**
+   * Predicate deciding whether an error may be retried at all. When it returns
+   * `false` the error is rethrown immediately — no backoff, no further attempts.
+   * Providers pass a classifier here so deterministic failures (401, 400,
+   * caller aborts) fail fast instead of burning the full retry budget.
+   */
+  isRetriable?: (error: unknown) => boolean;
 }
 
 /** Provider timeout (ms) + retry count, after defaults are applied. */
@@ -40,7 +48,7 @@ export function resolveRetryConfig(input?: {
 }
 
 export async function retry<T>(options: RetryOptions<T>): Promise<T> {
-  const { operation, maxRetries, delay, onRetry, onFailure } = options;
+  const { operation, maxRetries, delay, onRetry, onFailure, isRetriable } = options;
 
   let lastError: unknown;
 
@@ -50,6 +58,12 @@ export async function retry<T>(options: RetryOptions<T>): Promise<T> {
     } catch (error: unknown) {
       lastError = error;
 
+      // Unretriable errors (auth, invalid request, caller aborts) fail fast —
+      // retrying a deterministic failure only adds latency to the same outcome.
+      if (isRetriable && !isRetriable(error)) {
+        throw error;
+      }
+
       if (attempt === maxRetries) {
         const shouldRethrow = onFailure ? onFailure(lastError) : true;
         if (shouldRethrow) {
@@ -111,7 +125,8 @@ export const withTimeoutAndRetry = async <T>(
   operation: (signal: AbortSignal) => Promise<T>,
   timeoutMs: number = 60000,
   maxRetries: number = 3,
-  operationName: string = "AI operation"
+  operationName: string = "AI operation",
+  isRetriable?: (error: unknown) => boolean
 ): Promise<T> => {
   const createTimeoutOperation = () => async (): Promise<T> => {
     const controller = new AbortController();
@@ -144,6 +159,7 @@ export const withTimeoutAndRetry = async <T>(
     operation: createTimeoutOperation(),
     maxRetries,
     delay: defaultBackoff,
+    isRetriable,
     onRetry: (attempt: number, error: unknown) => {
       const message = error instanceof Error ? error.message : String(error);
       logger.error(
@@ -170,6 +186,12 @@ export interface StreamRetryOptions {
   delay?: (attempt: number) => number;
   /** Label used in retry logs. */
   operationName?: string;
+  /**
+   * Predicate deciding whether a pre-first-chunk failure may be retried.
+   * When it returns `false` the error propagates immediately. Post-first-chunk
+   * failures are never retried regardless (the stream is already committed).
+   */
+  isRetriable?: (error: unknown) => boolean;
   /**
    * Max ms to wait for the *first* chunk (time-to-first-token) before treating
    * the attempt as failed. Guards a provider that opens a stream and then
@@ -221,6 +243,7 @@ export async function* withStreamRetry<T>(
     delay = defaultBackoff,
     operationName = "AI stream",
     firstChunkTimeoutMs,
+    isRetriable,
   } = options;
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -246,6 +269,11 @@ export async function* withStreamRetry<T>(
         yield result.value;
       }
     } catch (error: unknown) {
+      // Unretriable errors (auth, invalid request, caller aborts) propagate
+      // immediately — no backoff for a deterministic failure.
+      if (isRetriable && !isRetriable(error)) {
+        throw error;
+      }
       // Can't retry once deltas are out, and don't retry past the budget.
       if (yielded || attempt === maxRetries) {
         throw error;
@@ -272,3 +300,224 @@ export async function* withStreamRetry<T>(
     }
   }
 }
+
+/**
+ * Inputs shared by {@link withBackupFallback} and {@link streamWithBackupFallback}.
+ *
+ * The walkers own only control flow: which model runs next and when the walk
+ * gives up. Logging and terminal-error wrapping stay with the caller (via the
+ * callbacks and a try/catch around the call), so each provider keeps its exact
+ * log prefixes, classification options and error normalization.
+ */
+export interface BackupFallbackBase {
+  /**
+   * Models to try in order: `[primaryModel, ...backupModels]`. The first
+   * successful attempt wins; every failure advances (or stops) the walk.
+   */
+  models: string[];
+  /**
+   * Predicate deciding whether a failure may fall through to the remaining
+   * models. Returning `false` stops the walk and rethrows the error — a
+   * deterministic failure (auth, invalid request) would hit identically on
+   * every backup. Must be a pure classifier: it may be evaluated more than
+   * once per error (the failure callback recomputes it to annotate logs).
+   */
+  shouldTryBackup: (error: unknown) => boolean;
+  /**
+   * Called once per failed model, before the backup decision is applied.
+   * `attemptNo` is the 1-based position in `models` (`1` = primary) and
+   * `total` is `models.length`, so callers can distinguish the primary
+   * failure and tell whether any model remains after this one
+   * (`attemptNo < total`).
+   */
+  onModelFailed?: (
+    model: string,
+    error: unknown,
+    attemptNo: number,
+    total: number
+  ) => void;
+  /**
+   * Called before each *backup* attempt (position > 0). `backupNo` and
+   * `backupTotal` count backups only (`1..models.length - 1`), matching the
+   * historical "Trying backup model 1/2: …" log shape.
+   */
+  onBackupStart?: (
+    model: string,
+    backupNo: number,
+    backupTotal: number
+  ) => void;
+  /** Called when a backup succeeds, just before its result is returned/yielded. */
+  onBackupSucceeded?: (model: string) => void;
+}
+
+export interface BackupFallbackOptions<T> extends BackupFallbackBase {
+  /** Run one model. A rejection marks the model failed; the resolved value wins. */
+  attempt: (model: string) => Promise<T>;
+}
+
+export interface StreamBackupFallbackOptions<T> extends BackupFallbackBase {
+  /** Produce one model's chunk stream; consumed lazily via `yield*`. */
+  attempt: (model: string) => AsyncGenerator<T>;
+}
+
+/**
+ * Try `models[0]` (the primary); on failure, if `shouldTryBackup` allows,
+ * walk the remaining backup models in order. Resolves with the first
+ * successful result; otherwise rethrows the last error seen. Errors are
+ * rethrown untouched — wrap them at the call site.
+ *
+ * Streaming twin: {@link streamWithBackupFallback}.
+ */
+export async function withBackupFallback<T>(
+  opts: BackupFallbackOptions<T>
+): Promise<T> {
+  const {
+    models,
+    attempt,
+    shouldTryBackup,
+    onModelFailed,
+    onBackupStart,
+    onBackupSucceeded,
+  } = opts;
+
+  if (models.length === 0) {
+    throw new Error(
+      "withBackupFallback: `models` must include a primary model"
+    );
+  }
+
+  let lastError: unknown;
+  for (let i = 0; i < models.length; i++) {
+    const model = models[i];
+    if (i > 0) onBackupStart?.(model, i, models.length - 1);
+    try {
+      const result = await attempt(model);
+      if (i > 0) onBackupSucceeded?.(model);
+      return result;
+    } catch (error: unknown) {
+      lastError = error;
+      onModelFailed?.(model, error, i + 1, models.length);
+      // A failure that doesn't qualify for backup ends the walk — the
+      // remaining models would hit the same deterministic error. Falling
+      // through to the throw covers both this early exit and exhaustion.
+      if (!shouldTryBackup(error)) break;
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Streaming twin of {@link withBackupFallback}: same walk, consuming each
+ * model's chunk stream lazily via `yield*` so chunks flow through unchanged.
+ * A stream that errors before completion counts as that model's failure and
+ * the walk proceeds exactly as in the non-streaming case.
+ */
+export async function* streamWithBackupFallback<T>(
+  opts: StreamBackupFallbackOptions<T>
+): AsyncGenerator<T> {
+  const {
+    models,
+    attempt,
+    shouldTryBackup,
+    onModelFailed,
+    onBackupStart,
+    onBackupSucceeded,
+  } = opts;
+
+  if (models.length === 0) {
+    throw new Error(
+      "streamWithBackupFallback: `models` must include a primary model"
+    );
+  }
+
+  let lastError: unknown;
+  for (let i = 0; i < models.length; i++) {
+    const model = models[i];
+    if (i > 0) onBackupStart?.(model, i, models.length - 1);
+    try {
+      yield* attempt(model);
+      if (i > 0) onBackupSucceeded?.(model);
+      return;
+    } catch (error: unknown) {
+      lastError = error;
+      onModelFailed?.(model, error, i + 1, models.length);
+      if (!shouldTryBackup(error)) break;
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Standard logging observer for the backup-fallback walkers. Holds the
+ * per-walk state (primary error message, whether backups were tried) that the
+ * terminal "All models failed" log needs, so each provider call site is just
+ * `attempt` + `shouldTryBackup` + its own terminal error wrap.
+ *
+ * ```ts
+ * const observer = backupFallbackLogging("[OPENAI]", shouldUseBackupModel);
+ * try {
+ *   return await withBackupFallback({ models, attempt, shouldTryBackup, ...observer.callbacks });
+ * } catch (error) {
+ *   observer.logExhausted(error);
+ *   throw wrap(error);
+ * }
+ * ```
+ */
+export function backupFallbackLogging(
+  label: string,
+  shouldTryBackup: (error: unknown) => boolean,
+  options?: { streaming?: boolean }
+): {
+  callbacks: Pick<
+    BackupFallbackBase,
+    "onModelFailed" | "onBackupStart" | "onBackupSucceeded"
+  >;
+  logExhausted: (lastError: unknown) => void;
+} {
+  let primaryErrMsg = "";
+  // Records that the primary failed but qualified for backups — the only path
+  // that reaches the "All models failed" terminal log; an ineligible primary
+  // rethrows directly.
+  let tryingBackups = false;
+  const streamSuffix = options?.streaming ? " for streaming" : "";
+
+  return {
+    callbacks: {
+      onModelFailed: (model, error, attemptNo, total) => {
+        const errMsg = getErrorMessage(error);
+        if (attemptNo === 1) {
+          primaryErrMsg = errMsg;
+          logger.warn(`${label} Primary model ${model} failed: ${errMsg}`);
+          if (shouldTryBackup(error)) {
+            tryingBackups = true;
+            logger.debug(`${label} Trying backup models${streamSuffix}`);
+          }
+          return;
+        }
+        logger.warn(`${label} Backup model ${model} failed: ${errMsg}`);
+        if (!shouldTryBackup(error) && attemptNo < total) {
+          logger.debug(
+            `${label} Backup model error doesn't qualify for further attempts`
+          );
+        }
+      },
+      onBackupStart: (model, backupNo, backupTotal) => {
+        logger.debug(
+          `${label} Trying backup model ${backupNo}/${backupTotal}: ${model}`
+        );
+      },
+      onBackupSucceeded: (model) => {
+        logger.debug(`${label} Backup model ${model} succeeded`);
+      },
+    },
+    logExhausted: (lastError) => {
+      if (tryingBackups) {
+        logger.error(
+          `${label} All models failed. Primary: ${primaryErrMsg}, Last backup: ${getErrorMessage(lastError)}`
+        );
+      }
+    },
+  };
+}

package/src/utils/serialize.ts

@@ -2,6 +2,44 @@
  * Serialization utilities for tool results and other data
  */
 
+import type { Directive } from "../types/flow";
+import type { ToolResult } from "../types/tool";
+
+/**
+ * Decide whether a tool handler's return value is a ToolResult-shaped object.
+ * Only SEMANTIC markers identify one — bare `{data}` / `{error}` shapes are
+ * indistinguishable from ordinary business payloads (e.g. upstream API
+ * envelopes) and must be wrapped as raw results instead. Shared by the
+ * sequential (ToolManager) and concurrent (StreamingToolExecutor) paths so the
+ * definition of "is a ToolResult" can't drift between them.
+ */
+export function isToolResultLike(result: unknown): result is ToolResult {
+  return (
+    result !== null &&
+    typeof result === "object" &&
+    (("success" in result &&
+      typeof (result as Record<string, unknown>).success === "boolean") ||
+      "directive" in result ||
+      "directives" in result ||
+      "dataUpdate" in result ||
+      "contextUpdate" in result)
+  );
+}
+
+/**
+ * Collect a ToolResult's directives — `{directive}` (singular shorthand) and
+ * `{directives}` both count. Singular merges FIRST so plural entries win reply
+ * ties (last-wins merge), identical on both executor paths.
+ */
+export function extractResultDirectives<TContext = unknown, TData = unknown>(
+  result: ToolResult<unknown, TContext, TData>
+): Directive<TContext, TData>[] {
+  const directives: Directive<TContext, TData>[] = [];
+  if (result.directive) directives.push(result.directive);
+  if (Array.isArray(result.directives)) directives.push(...result.directives);
+  return directives;
+}
+
 /**
  * Serialize a tool execution result into a string suitable for conversation history.
  *

package/src/utils/session.ts

@@ -1,5 +1,6 @@
 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";
@@ -68,8 +69,44 @@ export function createSession<TData = Record<string, unknown>>(
 }
 
 /**
- * Helper to create a new session ID
+ * Default conversation-history bound applied when the agent configures neither
+ * `maxHistoryMessages` nor compaction: generous enough to never bite a real
+ * thread, finite so a long-running chat()/stream() session can't grow until
+ * the provider context limit bricks it.
  */
+export const DEFAULT_MAX_HISTORY_MESSAGES = 400;
+
+/**
+ * Bound a conversation history to its most recent `max` entries. The left
+ * edge never opens on an orphaned role:'tool' message (whose assistant
+ * tool_calls parent was cut) — providers reject such histories. Returns the
+ * SAME array reference when no truncation is needed.
+ */
+export function boundConversationHistory(
+  history: History,
+  max: number
+): History {
+  if (!history || history.length <= max || max <= 0) return history;
+  let start = history.length - max;
+  while (start < history.length && (history[start] as { role?: string }).role === "tool") {
+    start++;
+  }
+  return history.slice(start);
+}
+
+/**
+ * Restore a session from a persisted blob (the named inverse of
+ * `createPersistedState`). Restores data + flowHistory verbatim — including a
+ * completed-flow blob, whose collected state MUST survive the round trip.
+ * Prefer this over the ambiguous `createSession(state)` overload.
+ */
+export function restoreSession<TData = Record<string, unknown>>(
+  state: Partial<SessionState<TData>>
+): SessionState<TData> {
+  return createSession<TData>(state);
+}
+
+/** Helper to create a new session ID */
 export function createSessionId(): string {
   return `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 }
@@ -361,9 +398,9 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
  * `appendPrompt`, `injectTools`, and `halt` are transient (one-turn lifetime)
  * and must not be serialized. This is a belt-and-suspenders safety net —
  * `Agent.dispatch` already strips before setting `pendingDirective`, and the
- * DirectiveBus's post-LLM drain strips from post-LLM emitters. This function
- * ensures the persistence layer never writes these fields regardless of the
- * upstream path.
+ * signal pipeline strips pre-LLM-only fields from post-phase directives. This
+ * function ensures the persistence layer never writes these fields regardless
+ * of the upstream path.
  */
 function stripPreDirectiveFields<TData>(
   directive: Directive<unknown, TData>