@falai/agent 3.4.5 → 4.0.0-alpha.1

package/src/core/createAgent.ts

@@ -1,40 +0,0 @@
-/**
- * Level-1 factory for constructing an Agent from a single options object.
- *
- * `createAgent` is syntactic sugar over `new Agent(options)` and is the
- * recommended entry point in docs and examples. Generic inference flows
- * from `schema` through `flows[].steps[].collect` identically to `new Agent`.
- *
- * @example
- * ```typescript
- * const agent = createAgent({
- *   name: 'BookingBot',
- *   provider: new GeminiProvider({ apiKey }),
- *   schema: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' } } },
- *   flows: [{ title: 'Onboarding', steps: [{ collect: ['name', 'email'] }] }],
- * });
- * ```
- *
- * **Validates: Requirements 14.1–14.7**
- */
-
-import { Agent } from "./Agent.js";
-import type { AgentOptions } from "../types/index.js";
-
-/**
- * Create an Agent from a single options object.
- *
- * This is the recommended entry point for constructing agents in v2.
- * Accepts the same options as `new Agent(options)` — `schema`, `provider`,
- * `instructions`, `flows`, and everything else `AgentOptions` carries.
- *
- * Generic inference flows from `schema` through `flows[].steps[].collect`.
- * Invalid `collect` references throw `FlowConfigurationError` at construction time.
- *
- * Post-construction flow registration is still available via `agent.createFlow(...)`.
- */
-export function createAgent<TContext = unknown, TData = unknown>(
-    options: AgentOptions<TContext, TData>
-): Agent<TContext, TData> {
-    return new Agent<TContext, TData>(options);
-}

package/src/core/flow-namespace.ts

@@ -1,227 +0,0 @@
-/**
- * `flow` namespace — type guards, merge, and validation helpers for Directives.
- *
- * No builder constructors live here (no `flow.goTo(...)`, `flow.complete(...)` etc.).
- * Directives are plain object literals; this namespace provides runtime utilities only.
- */
-
-import type { Directive } from "../types/flow.js";
-import type { SessionState } from "../types/session.js";
-import { FlowConfigurationError } from "./Step.js";
-
-// ─── Position field metadata ─────────────────────────────────────────────────
-
-/** Position fields in precedence order (highest first). */
-const POSITION_FIELDS = ["abort", "complete", "goTo", "goToStep", "reset"] as const;
-type PositionField = (typeof POSITION_FIELDS)[number];
-
-/** Precedence map: lower number = higher priority. */
-const POSITION_PRECEDENCE: Record<PositionField, number> = {
-    abort: 0,
-    complete: 1,
-    goTo: 2,
-    goToStep: 2,
-    reset: 3,
-};
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-/** Structural type for anything that has position fields (read-only access). */
-type HasPositionFields = {
-    readonly [K in PositionField]?: unknown;
-};
-
-function getSetPositionFields(d: HasPositionFields): PositionField[] {
-    return POSITION_FIELDS.filter((f) => d[f] !== undefined && d[f] !== null);
-}
-
-/**
- * Determines whether `candidate` beats `current` by precedence.
- * Lower precedence number wins. On tie, candidate wins (last-emission-wins).
- */
-function beatsCurrent(
-    candidate: PositionField,
-    current: PositionField | null
-): boolean {
-    if (current === null) return true;
-    return POSITION_PRECEDENCE[candidate] <= POSITION_PRECEDENCE[current];
-}
-
-// ─── Public API ──────────────────────────────────────────────────────────────
-
-/**
- * Type guard: is `x` a Directive (or any subtype like SignalDirective)?
- *
- * A value is considered a Directive if it is a non-null object. The Directive
- * interface has all-optional fields, so any plain object qualifies structurally.
- * This guard filters out primitives, null, undefined, arrays, and functions.
- */
-function isDirective(x: unknown): x is Directive {
-    return (
-        x !== null &&
-        x !== undefined &&
-        typeof x === "object" &&
-        !Array.isArray(x)
-    );
-}
-
-/**
- * Merge two directives by Algorithm 4's rules:
- * - Position fields: precedence (abort > complete > goTo/goToStep > reset);
- *   ties broken by emission order (b wins over a — last wins).
- * - reply: last-wins (b.reply overrides a.reply if set).
- * - dataUpdate / contextUpdate: shallow-merge (b overrides a on key collision).
- * - appendPrompt / injectTools (pre-LLM fields): concatenate then dedupe.
- * - halt: logical-OR.
- */
-function merge<TContext, TData>(a: Directive<TContext, TData>, b: Directive<TContext, TData>): Directive<TContext, TData> {
-    const result = {} as Record<string, unknown>;
-
-    // ── Position field: winner-takes-all by precedence, b wins ties ──
-    const aPos = getSetPositionFields(a);
-    const bPos = getSetPositionFields(b);
-
-    // Pick the highest-priority position field across both directives.
-    // b's fields are evaluated after a's, so b wins on same precedence (last-wins).
-    let winnerField: PositionField | null = null;
-    let winnerSource: Directive<TContext, TData> | null = null;
-
-    for (const field of aPos) {
-        if (beatsCurrent(field, winnerField)) {
-            winnerField = field;
-            winnerSource = a;
-        }
-    }
-    for (const field of bPos) {
-        if (beatsCurrent(field, winnerField)) {
-            winnerField = field;
-            winnerSource = b;
-        }
-    }
-
-    if (winnerField !== null && winnerSource !== null) {
-        result[winnerField] = (winnerSource as Record<string, unknown>)[winnerField];
-    }
-
-    // ── reply: last-wins ──
-    if (b.reply !== undefined) {
-        result.reply = b.reply;
-    } else if (a.reply !== undefined) {
-        result.reply = a.reply;
-    }
-
-    // ── dataUpdate: shallow merge ──
-    if (a.dataUpdate || b.dataUpdate) {
-        result.dataUpdate = { ...a.dataUpdate, ...b.dataUpdate };
-    }
-
-    // ── contextUpdate: shallow merge ──
-    if (a.contextUpdate || b.contextUpdate) {
-        result.contextUpdate = { ...a.contextUpdate, ...b.contextUpdate };
-    }
-
-    // ── appendPrompt (pre-LLM): concatenate ──
-    if (a.appendPrompt || b.appendPrompt) {
-        result.appendPrompt = [...(a.appendPrompt ?? []), ...(b.appendPrompt ?? [])];
-    }
-
-    // ── injectTools (pre-LLM): concatenate then dedupe by id (last wins) ──
-    if (a.injectTools || b.injectTools) {
-        const combined = [...(a.injectTools ?? []), ...(b.injectTools ?? [])];
-        // Dedupe by id — last definition wins
-        const seen = new Map<string, (typeof combined)[number]>();
-        for (const tool of combined) {
-            seen.set(tool.id, tool);
-        }
-        result.injectTools = Array.from(seen.values());
-    }
-
-    // ── halt (pre-LLM): logical OR ──
-    if (a.halt || b.halt) {
-        result.halt = true;
-    }
-
-    return result as Directive<TContext, TData>;
-}
-
-/**
- * Runtime validator. Throws FlowConfigurationError for invalid combinations:
- * - Multiple position fields set.
- * - `goTo` set as empty object `{}` (no flow target).
- * - `reply` co-existing with `abort` (abort ends the conversation; a reply is nonsensical).
- */
-function validate<TContext, TData>(d: Directive<TContext, TData>): void {
-    // ── Multiple position fields ──
-    const setFields = getSetPositionFields(d);
-    if (setFields.length > 1) {
-        throw new FlowConfigurationError(
-            `[FlowConfigurationError] Invalid directive: multiple position fields set (${setFields.join(", ")}). ` +
-            `A directive may have at most one position field. Remove the extras.`
-        );
-    }
-
-    // ── Empty goTo object ──
-    if (d.goTo !== undefined && d.goTo !== null) {
-        if (typeof d.goTo === "object") {
-            const goToObj = d.goTo as { flow?: string; step?: string };
-            if (!goToObj.flow && !goToObj.step) {
-                throw new FlowConfigurationError(
-                    `[FlowConfigurationError] Invalid directive: goTo is set as an empty object. ` +
-                    `goTo requires a flow id or title. Provide { flow: "<id>" } or use the string shorthand.`
-                );
-            }
-        }
-    }
-
-    // ── reply co-existing with abort ──
-    if (d.reply !== undefined && d.abort !== undefined) {
-        throw new FlowConfigurationError(
-            `[FlowConfigurationError] Invalid directive: reply cannot co-exist with abort. ` +
-            `An aborted conversation cannot deliver a reply. Remove one of the fields.`
-        );
-    }
-}
-
-/**
- * Reduce an array of directives into one via the canonical Algorithm 4 merge
- * (position precedence, reply last-wins, state shallow-merge, halt OR).
- * Empty arrays yield undefined.
- */
-function mergeAll<TContext, TData>(
-    directives: Directive<TContext, TData>[]
-): Directive<TContext, TData> | undefined {
-    if (directives.length === 0) return undefined;
-    return directives.reduce((a, b) => merge(a, b));
-}
-
-/**
- * Queue a control directive on the session for the pendingDirective applier at
- * the START of the next turn, merging with anything already queued via the
- * canonical Algorithm 4 merge.
- */
-function queuePending<TData>(
-    session: SessionState<TData>,
-    directive: Directive<unknown, TData>
-): void {
-    session.pendingDirective = session.pendingDirective
-        ? merge(session.pendingDirective, directive)
-        : directive;
-}
-
-/**
- * The `flow` namespace object. Exported as a single const for ergonomic usage:
- *
- * ```ts
- * import { flow } from '@falai/agent';
- * if (flow.isDirective(x)) { ... }
- * const merged = flow.merge(a, b);
- * flow.validate(d);
- * ```
- */
-export const flow = {
-    isDirective,
-    merge,
-    mergeAll,
-    queuePending,
-    validate,
-} as const;

package/src/core/toolGates.ts

@@ -1,72 +0,0 @@
-/**
- * Shared pre-execution gates for tool calls.
- *
- * A tool's `validateInput` and `checkPermissions` hooks must be applied
- * identically regardless of how the call is executed. Previously the gates
- * lived only in `ToolManager.executeTool` (the sequential `generate()`/
- * `respond()` path), so the streaming path (`StreamingToolExecutor`, used by
- * `stream()`) invoked handlers without them — a documented authorization gate
- * ("when denied, handler is NOT invoked") was silently a no-op on one
- * transport. Centralizing the logic here keeps both executors in lockstep.
- */
-import type { Tool, ToolContext, ToolExecutionResult } from "../types/tool.js";
-import { logger } from "../utils/index.js";
-
-/**
- * Run a tool's pre-execution gates in order: `validateInput`, then
- * `checkPermissions`. Returns a failed `ToolExecutionResult` when a gate
- * blocks the call (the handler must NOT be invoked), or `null` when both
- * gates pass.
- *
- * @param startTime - optional execution start time (ms from `Date.now()`).
- *   When provided, denial metadata includes `executionTime`, matching the
- *   sequential executor's result shape; omit it on the streaming path.
- */
-export async function evaluateToolGates<TContext, TData>(
-  tool: Tool<TContext, TData>,
-  toolArguments: Record<string, unknown> | undefined,
-  toolContext: ToolContext<TContext, TData>,
-  startTime?: number
-): Promise<ToolExecutionResult | null> {
-  // Tool validation gate (Req 6.1, 6.7)
-  if (typeof tool.validateInput === "function" && toolArguments) {
-    const validation = await tool.validateInput(toolArguments, toolContext);
-    if (!validation.valid) {
-      logger.warn(
-        `[DataValidationError] Tool "${tool.id}" input validation failed: ${validation.error}. Fix the tool call arguments to match the expected schema.`
-      );
-      return {
-        success: false,
-        error: `Validation failed: ${validation.error || "Invalid input"}`,
-        metadata: {
-          toolId: tool.id,
-          ...(startTime !== undefined ? { executionTime: Date.now() - startTime } : {}),
-          gate: "validateInput",
-        },
-      };
-    }
-  }
-
-  // Tool permission gate (Req 6.7, 6.8)
-  // When denied: do not invoke handler, do not process directives, do not apply state writes
-  if (typeof tool.checkPermissions === "function" && toolArguments) {
-    const permission = await tool.checkPermissions(toolArguments, toolContext);
-    if (!permission.allowed) {
-      logger.warn(
-        `[ToolExecutionError] Tool "${tool.id}" permission denied: ${permission.reason}. The tool's checkPermissions hook rejected this call.`
-      );
-      return {
-        success: false,
-        error: `Permission denied: ${permission.reason || "Not allowed"}`,
-        metadata: {
-          toolId: tool.id,
-          ...(startTime !== undefined ? { executionTime: Date.now() - startTime } : {}),
-          gate: "checkPermissions",
-          canOverride: permission.canOverride,
-        },
-      };
-    }
-  }
-
-  return null;
-}

package/src/types/persistence.ts

@@ -1,303 +0,0 @@
-/**
- * Persistence-related type definitions
- * Support for optional database persistence (Prisma, etc.)
- */
-
-import type { Event, MessageRole } from "./history.js";
-import type { SessionState } from "./session.js";
-
-/**
- * Session status enum
- */
-export type SessionStatus = "active" | "completed" | "abandoned";
-
-/**
- * Base session data structure
- */
-export interface SessionData<TData = Record<string, unknown>> {
-  id: string;
-  userId?: string;
-  agentName?: string;
-  status: SessionStatus;
-  currentFlow?: string;
-  currentStep?: string;
-  collectedData?: CollectedStateData<TData>;
-  messageCount?: number;
-  lastMessageAt?: Date;
-  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;
-}
-
-/**
- * Data for creating a new session (subset of SessionData)
- */
-export type CreateSessionData<TData = Record<string, unknown>> = Omit<
-  SessionData<TData>,
-  "id" | "createdAt" | "updatedAt"
-> & {
-  id?: string;
-};
-
-/**
- * Structure for data collected during a session that needs to be persisted.
- * 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"];
-  currentFlowTitle?: string;
-  currentStepDescription?: string;
-  metadata: SessionState<TData>["metadata"];
-  /** Pending directive — included only when a directive is actually present. */
-  pendingDirective?: SessionState<TData>["pendingDirective"];
-  /** Reserved for v2.x Signals. Passed through bit-identical. */
-  signals?: SessionState<TData>["signals"];
-}
-
-/**
- * Base message data structure
- */
-export interface MessageData {
-  id: string;
-  sessionId: string;
-  userId?: string;
-  role: MessageRole;
-  content: string;
-  flow?: string;
-  step?: string;
-  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
-  event?: Event; // Optional: store full event data
-  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
- */
-export interface SessionRepository<TData = Record<string, unknown>> {
-  /**
-   * Create a new session
-   */
-  create(data: CreateSessionData<TData>): Promise<SessionData<TData>>;
-
-  /**
-   * Find session by ID
-   */
-  findById(id: string): Promise<SessionData<TData> | null>;
-
-  /**
-   * Find active session by user ID
-   */
-  findActiveByUserId(userId: string): Promise<SessionData<TData> | null>;
-
-  /**
-   * Find all sessions for a user
-   */
-  findByUserId(userId: string, limit?: number): Promise<SessionData<TData>[]>;
-
-  /**
-   * 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">>,
-    options?: SessionUpdateOptions
-  ): Promise<SessionData<TData> | null>;
-
-  /**
-   * Update session status
-   */
-  updateStatus(
-    id: string,
-    status: SessionStatus,
-    completedAt?: Date
-  ): Promise<SessionData<TData> | null>;
-
-  /**
-   * Update collected data
-   */
-  updateCollectedData(
-    id: string,
-    collectedData: CollectedStateData<TData>
-  ): Promise<SessionData<TData> | null>;
-
-  /**
-   * Update current flow and step
-   */
-  updateFlowStep(
-    id: string,
-    flow?: string,
-    step?: string
-  ): Promise<SessionData<TData> | null>;
-
-  /**
-   * Increment message count
-   */
-  incrementMessageCount(id: string): Promise<SessionData<TData> | null>;
-
-  /**
-   * Delete session
-   */
-  delete(id: string): Promise<boolean>;
-}
-
-/**
- * Repository interface for messages
- * Implement this interface with your database of choice
- */
-export interface MessageRepository {
-  /**
-   * Create a new message
-   */
-  create(data: Omit<MessageData, "id" | "createdAt">): Promise<MessageData>;
-
-  /**
-   * Find message by ID
-   */
-  findById(id: string): Promise<MessageData | null>;
-
-  /**
-   * Find all messages for a session
-   */
-  findBySessionId(sessionId: string, limit?: number): Promise<MessageData[]>;
-
-  /**
-   * Find messages for a user
-   */
-  findByUserId(userId: string, limit?: number): Promise<MessageData[]>;
-
-  /**
-   * Delete message by ID
-   */
-  delete(id: string): Promise<boolean>;
-
-  /**
-   * Delete all messages for a session
-   */
-  deleteBySessionId(sessionId: string): Promise<number>;
-
-  /**
-   * Delete all messages for a user
-   */
-  deleteByUserId(userId: string): Promise<number>;
-}
-
-/**
- * Persistence adapter interface
- * Implement this to create adapters for different databases
- */
-export interface PersistenceAdapter<TData = Record<string, unknown>> {
-  /**
-   * Session repository
-   */
-  readonly sessionRepository: SessionRepository<TData>;
-
-  /**
-   * Message repository
-   */
-  readonly messageRepository: MessageRepository;
-
-  /**
-   * Initialize the adapter (create tables, indexes, etc.)
-   * Called automatically when adapter is created
-   */
-  initialize?(): Promise<void>;
-
-  /**
-   * Disconnect/cleanup resources
-   */
-  disconnect?(): Promise<void>;
-}
-
-/**
- * Configuration for persistence
- */
-export interface PersistenceConfig<TData = Record<string, unknown>> {
-  /**
-   * Persistence adapter instance (e.g., PrismaAdapter)
-   */
-  adapter: PersistenceAdapter<TData>;
-
-  /**
-   * Whether to auto-save messages (default: true)
-   */
-  autoSave?: boolean;
-
-  /**
-   * User ID to associate with sessions/messages
-   * 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>>;
-}
-
-/**
- * Options for creating a session
- */
-export interface CreateSessionOptions<TData = Record<string, unknown>> {
-  userId?: string;
-  agentName?: string;
-  initialData?: Partial<TData>;
-}
-
-/**
- * Options for saving a message
- */
-export interface SaveMessageOptions {
-  sessionId: string;
-  userId?: string;
-  role: MessageRole;
-  content: string;
-  flow?: string;
-  step?: string;
-  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
-  event?: Event;
-}

package/src/types/prompt-cache.ts

@@ -1,17 +0,0 @@
-/**
- * Prompt section cache configuration types.
- */
-
-/** Section type: static sections are cached, dynamic sections recompute every turn */
-export type PromptSectionType = "static" | "dynamic";
-
-/** Configuration for prompt section caching behavior */
-export interface PromptCacheConfig {
-    /** Whether to enable section memoization (default: true) */
-    enabled?: boolean;
-    /** Keys of sections that should always recompute every turn, even if registered as static */
-    volatileKeys?: string[];
-}
-
-/** Compute function that produces a section's content */
-export type SectionCompute = () => string | null | Promise<string | null>;