@falai/agent 3.4.5 → 4.0.0-alpha.1

package/dist/cjs/types/persistence.d.ts

@@ -1,254 +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;
-    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;
-}
-//# sourceMappingURL=persistence.d.ts.map

package/dist/cjs/types/persistence.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/types/persistence.ts"],"names":[],"mappings":"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"}

package/dist/cjs/types/persistence.js

@@ -1,7 +0,0 @@
-"use strict";
-/**
- * Persistence-related type definitions
- * Support for optional database persistence (Prisma, etc.)
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=persistence.js.map

package/dist/cjs/types/persistence.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../../src/types/persistence.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/cjs/types/prompt-cache.d.ts

@@ -1,15 +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>;
-//# sourceMappingURL=prompt-cache.d.ts.map

package/dist/cjs/types/prompt-cache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"prompt-cache.d.ts","sourceRoot":"","sources":["../../../src/types/prompt-cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAErD,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAC9B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,yDAAyD;AACzD,MAAM,MAAM,cAAc,GAAG,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC"}

package/dist/cjs/types/prompt-cache.js

@@ -1,6 +0,0 @@
-"use strict";
-/**
- * Prompt section cache configuration types.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=prompt-cache.js.map

package/dist/cjs/types/prompt-cache.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"prompt-cache.js","sourceRoot":"","sources":["../../../src/types/prompt-cache.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/cjs/types/signals.d.ts

@@ -1,263 +0,0 @@
-/**
- * Signals types for v2.x.
- *
- * This is the canonical location for all signals-related types.
- * `SignalsState` and `SignalTriggerState` originated in `session.ts` as v2.0
- * forward-compat reservations and are re-exported from there for backward
- * compatibility within the same major.
- */
-import type { SessionState } from "./session.js";
-import type { Directive } from "./flow.js";
-import type { Event } from "./history.js";
-/**
- * Per-signal trigger tracking state.
- * Shape is locked to enable forward-compatible persistence in v2.0.
- */
-export interface SignalTriggerState {
-    /** When this signal first completed its handler successfully. */
-    firstTriggeredAt: Date;
-    /** When this signal last completed its handler successfully. */
-    lastTriggeredAt: Date;
-    /** Total number of successful handler completions for this signal. */
-    count: number;
-    /** Free-text reason from the last successful trigger (if supplied). */
-    lastReason?: string;
-    /** Which phase the signal last completed in. */
-    lastPhase?: 'pre' | 'post';
-}
-/**
- * Aggregated signals state stored on the session.
- * Shape is locked to enable forward-compatible persistence in v2.0.
- */
-export interface SignalsState {
-    /** Per-signal trigger tracking; keyed by signal id. */
-    triggers: Record<string, SignalTriggerState>;
-}
-/**
- * Schema for extraction signals. JSON Schema subset or Zod-compatible shape.
- * The framework uses this to build the per-signal `extracted` field in the
- * classifier response schema.
- *
- * When set on a signal, the signal operates in extraction mode: the classifier
- * call includes this schema in the response format, and the handler receives
- * `extracted: TExtract` when the signal matches.
- *
- * The type parameter `_T` is a phantom type that carries the extraction shape
- * for downstream inference — the runtime value is always a JSON Schema object.
- */
-export type SignalSchema<_T = unknown> = Record<string, unknown>;
-/**
- * Context passed to signal `if` predicates.
- * Symmetric with `BranchPredicateContext` used by branches.
- */
-export interface SignalPredicateContext<TContext = unknown, TData = unknown> {
-    /** Collected data (partial — null-check fields not guaranteed). */
-    data: Partial<TData>;
-    /** Agent-level context. */
-    context: TContext;
-    /** Full session state. */
-    session: SessionState<TData>;
-    /** Conversation history as events. */
-    history: Event[];
-}
-/**
- * Code-evaluated predicate for signal `if` conditions.
- * Returns `true` to pass (signal proceeds to `when` evaluation or fires),
- * `false` to skip (signal is not evaluated this turn).
- *
- * Predicates evaluate BEFORE `when` conditions — code-first short-circuit.
- * If `if` returns false, `when` is NOT evaluated (token-saving).
- *
- * If a predicate throws, the signal is treated as non-match and other
- * signals continue evaluation.
- */
-export type SignalPredicate<TContext = unknown, TData = unknown> = (ctx: SignalPredicateContext<TContext, TData>) => boolean | Promise<boolean>;
-/**
- * SignalDirective — what signal handlers return.
- * Extends `Directive`. Adds signal-specific fields: `stopOtherSignals` and `replyWith`.
- *
- * All position-control (`goTo`, `goToStep`, `complete`, `abort`, `reset`),
- * state writes (`dataUpdate`, `contextUpdate`), prompt augmentation
- * (`appendPrompt`, `injectTools`), `reply`, and `halt` are inherited unchanged.
- *
- * Post-phase drop rules: when returned in the post-phase, `appendPrompt`,
- * `injectTools`, and `halt` are dropped with a WARN log — they have
- * no meaning after the LLM call has already completed.
- */
-export interface SignalDirective<TContext = unknown, TData = unknown> extends Directive<TContext, TData> {
-    /**
-     * Stop processing remaining signals for this phase after this handler.
-     * Does not affect the other phase.
-     */
-    stopOtherSignals?: boolean;
-    /**
-     * Verbatim reply with optional late-binding (function form).
-     * - String: same as `Directive.reply`.
-     * - Function: evaluated at emit time; result projects onto `Directive.reply`.
-     *
-     * The field is resolved and stripped before reaching the directive merge bus.
-     */
-    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;
-};
-/**
- * Context passed to signal handlers when a signal fires.
- * Symmetric with `ToolContext` — provides session state and writer methods.
- *
- * The `updateContext` and `updateData` writers follow the same D-Q12 contract
- * as `ToolContext` writers.
- */
-export interface SignalContext<TContext = unknown, TData = unknown, TExtract = void> {
-    /** The signal definition that fired. */
-    signal: Signal<TContext, TData, TExtract>;
-    /** Phase in which this signal fired. */
-    phase: 'pre' | 'post';
-    /** Whether the signal matched (always `true` when handler runs). */
-    matched: true;
-    /** AI rationale when `when` matched, or `'code-only'` / `'unconditional'`. */
-    reason: string;
-    /**
-     * Extracted data when the signal has `extract` set. Typed via the
-     * TExtract generic. Undefined for detection-only signals.
-     */
-    extracted: TExtract extends void ? undefined : TExtract;
-    /** Session state. Use writers below for mutations. */
-    session: SessionState<TData>;
-    /** Agent-level context. */
-    context: TContext;
-    /** Collected data (partial). */
-    data: Partial<TData>;
-    /** Conversation history as events. */
-    history: Event[];
-    /** Last user message (convenience). */
-    lastUserMessage?: string;
-    /** Timestamp when the signal fired. */
-    triggeredAt: Date;
-    /** Update agent context (same signature as ToolContext.updateContext). */
-    updateContext: (updates: Partial<TContext>) => Promise<void>;
-    /** Update collected data (same signature as ToolContext.updateData). */
-    updateData: (updates: Partial<TData>) => Promise<void>;
-    /** Imperative directive emission onto the per-turn bus. */
-    dispatch(directive: SignalDirective<TContext, TData>): void;
-}
-/**
- * A signal: a typed event detector (and optional data extractor) that runs
- * around an LLM turn.
- *
- * Conditions use the v2 `when` / `if` split:
- * - `when`: AI-evaluated string(s). Entries prefixed with `!` are exclusion
- *   conditions rendered under "DO NOT TRIGGER WHEN" in the classifier prompt.
- *   Non-prefixed entries render under "TRIGGER WHEN". Positive entries use OR
- *   semantics (any match can trigger). Negative entries also use OR semantics
- *   for exclusion (any match inhibits firing).
- * - `if`: Code-evaluated function(s). Free. AND semantics.
- *
- * When both `if` and `when` are set, `if` evaluates first. If `if` returns
- * false, `when` is not evaluated (token-saving).
- *
- * Signals with neither `when` nor `if` are unconditional — they always fire
- * (subject to behavior gating). If `extract` is set on an unconditional signal,
- * the extraction runs every turn.
- */
-export interface Signal<TContext = unknown, TData = unknown, TExtract = void> {
-    /** Unique identifier. Auto-generated if omitted (stable within session). */
-    id?: string;
-    /** Display title (shown in logs and traces). */
-    title?: string;
-    /** Free-text description of what this signal detects. */
-    description?: string;
-    /**
-     * AI-evaluated trigger condition(s). String or array of strings.
-     * - Non-prefixed entries: OR semantics. Any match can trigger.
-     * - `!`-prefixed entries: OR exclusion. Any match inhibits firing.
-     *
-     * At prompt-render time, the framework splits entries by prefix:
-     * - Non-`!` → rendered under "TRIGGER WHEN"
-     * - `!` → stripped of prefix, rendered under "DO NOT TRIGGER WHEN"
-     */
-    when?: string | string[];
-    /**
-     * Code predicate(s). Function or array of functions (AND).
-     * Free to evaluate; runs before `when`. If `if` returns false, the
-     * signal is skipped — `when` is not evaluated.
-     */
-    if?: SignalPredicate<TContext, TData> | SignalPredicate<TContext, TData>[];
-    /**
-     * Optional structured extraction schema. When set, the signal operates
-     * in extraction mode: the classifier call includes this schema in the
-     * response format, and the handler receives `extracted: TExtract` when
-     * the signal matches.
-     *
-     * Extraction signals participate in the same batched classifier call as
-     * detection signals. The merged response schema includes each signal's
-     * extraction fields alongside the standard `matched` / `reason`.
-     *
-     * When absent, the signal operates in detection mode (boolean match).
-     */
-    extract?: SignalSchema<TExtract>;
-    /**
-     * When this signal evaluates relative to the LLM call.
-     * - `'pre'`: before the LLM call (parallel with routing).
-     * - `'post'`: after the LLM call (sequential, after finalize).
-     * - `'both'`: evaluated in both phases.
-     */
-    phase: 'pre' | 'post' | 'both';
-    /**
-     * Handler invoked when the signal fires. Receives match info and
-     * extracted data (if applicable). Returns void or a SignalDirective.
-     */
-    handler: (ctx: SignalContext<TContext, TData, TExtract>) => void | SignalDirective<TContext, TData> | Promise<void | SignalDirective<TContext, TData>>;
-    /**
-     * Rate-limit / dedup behavior:
-     * - `'once'`: fire once per session.
-     * - `'always'`: fire every match (default).
-     * - `'cooldown'`: fire, then suppress for `cooldownMs`.
-     */
-    behavior?: 'once' | 'always' | 'cooldown';
-    /** Cooldown duration in ms. Required when `behavior === 'cooldown'`. */
-    cooldownMs?: number;
-    /** Whether this signal is currently enabled. @default true */
-    enabled?: boolean;
-    /**
-     * Higher priority signals fire first within a phase. Default 0.
-     * Tie: declaration order in `agent.signals`.
-     */
-    priority?: number;
-}
-/**
- * Observability record for a signal that fired during a turn.
- * Populated in fire order across both pre- and post-phases.
- * Mirrors the observability framing of `executedSteps` and `appliedGuidelines`.
- */
-export interface SignalFiring<TContext = unknown, TData = unknown> {
-    /** The signal's unique identifier. */
-    id: string;
-    /** Which phase the signal fired in. */
-    phase: 'pre' | 'post';
-    /** AI rationale when `when` matched, or 'code-only' / 'unconditional'. */
-    reason?: string;
-    /** Extracted data when the signal operates in extraction mode. */
-    extracted?: unknown;
-    /** 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;
-}
-//# sourceMappingURL=signals.d.ts.map

package/dist/cjs/types/signals.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../../src/types/signals.ts"],"names":[],"mappings":"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"}

package/dist/cjs/types/signals.js

@@ -1,11 +0,0 @@
-"use strict";
-/**
- * Signals types for v2.x.
- *
- * This is the canonical location for all signals-related types.
- * `SignalsState` and `SignalTriggerState` originated in `session.ts` as v2.0
- * forward-compat reservations and are re-exported from there for backward
- * compatibility within the same major.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=signals.js.map

package/dist/cjs/types/signals.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"signals.js","sourceRoot":"","sources":["../../../src/types/signals.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}