@falai/agent 3.4.4 → 4.0.0-alpha.1

package/src/index.ts

@@ -5,22 +5,42 @@
  */
 
 // Core
+export { falai } from "./core/falai.js";
+export type { DataOf, Falai, FalaiRoot } from "./core/falai.js";
 export { Agent } from "./core/Agent.js";
-export type { RespondParams, StreamOptions, GenerateOptions } from "./core/ResponseModal.js";
-export { ResponseGenerationError } from "./core/ResponseGenerationError.js";
-export type { EndedFlow } from "./types/agent.js";
-export { createAgent } from "./core/createAgent.js";
-export { Flow } from "./core/Flow.js";
-export { Step, FlowConfigurationError } from "./core/Step.js";
-export { flow } from "./core/flow-namespace.js";
-
-export { adaptEvent, convertHistoryToEvents } from "./core/Events.js";
-export { PersistenceManager } from "./core/PersistenceManager.js";
-export { SessionManager } from "./core/SessionManager.js";
-export { ToolManager, ToolCreationError, ToolExecutionError } from "./core/ToolManager.js";
-export { NotImplementedError, SessionConflictError, ProviderError } from "./types/errors.js";
+export {
+  FlowConfigurationError,
+  ProviderError,
+  SessionConflictError,
+} from "./types/errors.js";
 export type { ErrorKind } from "./types/errors.js";
 
+// Stored flows as JSON
+export { flowSpecSchema, fromSpec, toSpec, validateFlow } from "./core/FlowSpec.js";
+export type { BranchSpec, FlowSpec, InstructionSpec, Registries, StepKind, StepSpec, TriggerSpec } from "./core/FlowSpec.js";
+
+// Time: a clock you control and an in-memory scheduler (tests, playground)
+export { fakeClock, MemoryScheduler } from "./utils/clock.js";
+export type { FakeClock } from "./utils/clock.js";
+export { assertDuration, isDuration, parseDuration } from "./utils/duration.js";
+export { OUTCOME_MESSAGES } from "./utils/outcomes.js";
+
+// Sessions: reading stored blobs and the seven stores
+export { assertSession, InvalidSessionError, migrateSession } from "./core/Migrate.js";
+export type { MigrateOptions } from "./core/Migrate.js";
+export { MemoryStore } from "./persistence/MemoryStore.js";
+export { PostgresStore } from "./persistence/PostgresStore.js";
+export type { PgClient, PgQueryResult, PostgresStoreOptions } from "./persistence/PostgresStore.js";
+export { PrismaStore } from "./persistence/PrismaStore.js";
+export type { PrismaClient, PrismaSessionField, PrismaSessionModel, PrismaStoreOptions } from "./persistence/PrismaStore.js";
+export { RedisStore } from "./persistence/RedisStore.js";
+export type { RedisClient, RedisStoreOptions } from "./persistence/RedisStore.js";
+export { MongoStore } from "./persistence/MongoStore.js";
+export type { MongoClient, MongoCollection, MongoDatabase, MongoStoreOptions } from "./persistence/MongoStore.js";
+export { SQLiteStore } from "./persistence/SQLiteStore.js";
+export type { SqliteDatabase, SqliteStatement, SQLiteStoreOptions } from "./persistence/SQLiteStore.js";
+export { OpenSearchStore } from "./persistence/OpenSearchStore.js";
+export type { OpenSearchClient, OpenSearchStoreOptions } from "./persistence/OpenSearchStore.js";
 
 // Providers
 export { GeminiProvider } from "./providers/GeminiProvider.js";
@@ -58,156 +78,108 @@ export type {
   RetryConfig,
 } from "./providers/ProviderAdapter.js";
 
-// Adapters
-export { PrismaAdapter } from "./adapters/PrismaAdapter.js";
-export type {
-  PrismaClient,
-  FieldMappings,
-  PrismaAdapterOptions,
-} from "./adapters/PrismaAdapter.js";
-export { RedisAdapter } from "./adapters/RedisAdapter.js";
-export type { RedisClient, RedisAdapterOptions } from "./adapters/RedisAdapter.js";
-export { MongoAdapter } from "./adapters/MongoAdapter.js";
-export type {
-  MongoClient,
-  MongoDatabase,
-  MongoCollection,
-  MongoAdapterOptions,
-} from "./adapters/MongoAdapter.js";
-export { PostgreSQLAdapter } from "./adapters/PostgreSQLAdapter.js";
-export type {
-  PgClient,
-  PgQueryResult,
-  PostgreSQLAdapterOptions,
-} from "./adapters/PostgreSQLAdapter.js";
-export { SQLiteAdapter } from "./adapters/SQLiteAdapter.js";
-export type {
-  SqliteDatabase,
-  SqliteStatement,
-  SQLiteAdapterOptions,
-} from "./adapters/SQLiteAdapter.js";
-export { MemoryAdapter } from "./adapters/MemoryAdapter.js";
-export { OpenSearchAdapter } from "./adapters/OpenSearchAdapter.js";
-export type {
-  OpenSearchClient,
-  OpenSearchAdapterOptions,
-} from "./adapters/OpenSearchAdapter.js";
-
-// Utils
-export { generateFlowId, generateStepId, generateToolId } from "./utils/id.js";
-export { formatKnowledgeBase } from "./utils/template.js";
-export {
-  ConditionEvaluator,
-  createConditionEvaluator,
-  extractAIContextStrings,
-  hasProgrammaticConditions
-} from "./utils/condition.js";
+// History helpers
 export {
+  assistantMessage,
+  eventsToHistory,
+  eventToHistoryItem,
   historyItemToEvent,
   historyToEvents,
-  eventToHistoryItem,
-  eventsToHistory,
-  userMessage,
-  assistantMessage,
-  toolMessage,
   systemMessage,
+  toolMessage,
+  userMessage,
 } from "./utils/history.js";
 
 // Types
 export type {
-  AgentOptions,
+  Action,
+  ActionCtx,
+  ActionMap,
+  ActionResult,
   AgentCompactionConfig,
-  AgentResponse,
-  Term,
-  Instruction,
-  ScopedInstructions,
-  AppliedInstruction,
-  ContextLifecycleHooks,
-  ContextProvider,
-  HookContext,
-  ExitReason,
-  Event,
-  EmittedEvent,
-  MessageEventData,
-  ToolEventData,
-  StatusEventData,
-  Participant,
-  FlowRef,
-  StepRef,
-  FlowOptions,
-  StepOptions,
-  FlowLifecycleHooks,
-  StepLifecycleHooks,
-  SessionState,
-  SignalsState,
-  SignalTriggerState,
-  Signal,
-  SignalContext,
-  SignalDirective,
-  ResolvedSignalDirective,
-  SignalPredicate,
-  SignalPredicateContext,
-  SignalFiring,
-  SignalSchema,
-  ToolContext,
-  ToolResult,
-  ToolHandler,
-  Tool,
-
-  ToolValidationResult,
-  ToolPermissionResult,
-  ToolCallRequest,
-  ToolExecutionUpdate,
-
+  AgentOptions,
+  AgentStructuredResponse,
+  AiProvider,
+  AssistantHistoryItem,
+  Branch,
+  BusinessHours,
+  Clock,
   CompactionOptions,
   CompactionResult,
-
-  DataEnrichmentConfig,
-  ValidationConfig,
-  ValidationError,
-  ApiCallConfig,
-  ComputationConfig,
-  ToolScope,
-  AiProvider,
-  ProviderCapabilities,
+  Condition,
+  ConditionMap,
+  ConditionSpec,
+  DoStep,
+  Duration,
+  EmittedEvent,
+  EndReason,
+  Event,
+  EventDef,
+  EventMap,
+  EventToolResult,
+  FieldDef,
+  FieldDefs,
+  Flow,
   GenerateMessageInput,
   GenerateMessageOutput,
-  AgentStructuredResponse,
+  TokenUsage,
+  GenerateMessageStreamChunk,
+  History,
+  HistoryItem,
+  Idle,
+  IfStep,
+  InferData,
+  InferParams,
+  Instruction,
+  MessageEventData,
+  Next,
+  OutboundMessage,
+  ParamDef,
+  ParamDefs,
+  Participant,
+  Pred,
+  PredCtx,
+  ProviderCapabilities,
   ReasoningConfig,
-  StructuredSchema,
-  SessionData,
-  MessageData,
-  CollectedStateData,
-  SessionStatus,
-  SessionRepository,
-  SessionUpdateOptions,
-  MessageRepository,
-  PersistenceConfig,
-  CreateSessionOptions,
-  SaveMessageOptions,
-  AgentResponseStreamChunk,
+  Repeat,
   Role,
-  HistoryItem,
-  History,
-  PersistenceAdapter,
+  Run,
+  RunStatus,
+  SayStep,
+  ScalarDef,
+  ScalarType,
+  ScheduleEntry,
+  Session,
+  Silenced,
+  StatusEventData,
+  Step,
+  StepBase,
+  StepOutcome,
+  StepOutcomeCode,
+  StepOutcomeKind,
+  StepOutcomeStatus,
+  Store,
+  StructuredSchema,
+  SystemHistoryItem,
+  TalkStep,
   Template,
-  TemplateContext,
-  ConditionEvaluationResult,
-  UserHistoryItem,
-  AssistantHistoryItem,
+  Tool,
+  ToolCall,
+  ToolCtx,
+  ToolEventData,
   ToolHistoryItem,
-  SystemHistoryItem,
-  // Flow execution types
-  StoppedReason,
-  PrepareResult,
-  Directive,
-  BranchEntry,
-  BranchMap,
-  BranchPredicate,
-  BranchPredicateContext,
-  ConditionPredicate,
-  ConditionIf,
-  ConditionWhen,
+  ToolPermissionResult,
+  ToolResult,
+  ToolValidationResult,
+  Trigger,
+  TriggerKind,
+  TurnBase,
+  TurnInput,
+  TurnKind,
+  TurnResult,
+  TurnStreamChunk,
+  UserHistoryItem,
+  WaitEventStep,
+  WaitStep,
 } from "./types/index.js";
 export { EventKind, MessageRole } from "./types/index.js";
-export { restoreSession, createSession, createSessionId, createPersistedState, enterFlow, enterStep, completeCurrentFlow, isFlowCompletedThisSession, mergeCollected } from "./utils/index.js";

package/src/persistence/MemoryStore.ts

@@ -0,0 +1,37 @@
+/**
+ * In-memory Store: tests, the playground, prototypes. Nothing survives the
+ * process. Rows are kept as JSON text and read back through the same check
+ * every other store runs, so a session round-trips here exactly as it would
+ * through PostgreSQL or Redis: Dates come back as text, `undefined` drops.
+ */
+
+import { SessionConflictError } from "../types/errors.js";
+import type { Session, Store } from "../types/session.js";
+import { asPromise, readBlob, toBlob } from "./sessionRow.js";
+
+export class MemoryStore<D = unknown> implements Store<D> {
+  private readonly rows = new Map<string, { version: number; blob: string }>();
+
+  load(id: string): Promise<Session<D> | null> {
+    return asPromise(() => {
+      const row = this.rows.get(id);
+      return row ? readBlob<D>(row.blob, id) : null;
+    });
+  }
+
+  save(session: Session<D>, expectedVersion: number): Promise<Session<D>> {
+    return asPromise(() => {
+      const current = this.rows.get(session.id);
+      const conflict = expectedVersion === 0 ? current !== undefined : current?.version !== expectedVersion;
+      if (conflict) throw new SessionConflictError(session.id, expectedVersion, current?.version);
+      const blob = toBlob(session, expectedVersion + 1);
+      this.rows.set(session.id, { version: blob.version, blob: JSON.stringify(blob) });
+      return blob;
+    });
+  }
+
+  /** Drop every session. */
+  clear(): void {
+    this.rows.clear();
+  }
+}

package/src/persistence/MongoStore.ts

@@ -0,0 +1,89 @@
+/**
+ * MongoDB Store over the official driver's client.
+ *
+ * One document per session: `_id` (the session id), `version`, `blob`,
+ * `createdAt`, `updatedAt`. A first save is `insertOne`, and the duplicate
+ * key error is the conflict; later saves are `updateOne` filtered on
+ * `{ _id, version }`, and `matchedCount === 0` is the conflict.
+ */
+
+import { isRecord } from "../utils/json.js";
+import { SessionConflictError } from "../types/errors.js";
+import type { Session, Store } from "../types/session.js";
+import { readBlob, toBlob } from "./sessionRow.js";
+
+/** Matches the mongodb driver's Collection. */
+export interface MongoCollection<T = Record<string, unknown>> {
+  insertOne(doc: T): Promise<unknown>;
+  findOne(filter: Record<string, unknown>): Promise<T | null>;
+  updateOne(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<{ matchedCount: number }>;
+}
+
+export interface MongoDatabase {
+  collection<T = Record<string, unknown>>(name: string): MongoCollection<T>;
+}
+
+export interface MongoClient {
+  db(name?: string): MongoDatabase;
+  close(): Promise<void>;
+}
+
+export interface MongoStoreOptions {
+  client: MongoClient;
+  databaseName: string;
+  /** Collection name. Default `agent_sessions`. */
+  collections?: { sessions?: string };
+}
+
+export class MongoStore<D = unknown> implements Store<D> {
+  private readonly client: MongoClient;
+  private readonly sessions: MongoCollection;
+
+  constructor(options: MongoStoreOptions) {
+    this.client = options.client;
+    this.sessions = options.client.db(options.databaseName).collection(options.collections?.sessions ?? "agent_sessions");
+  }
+
+  async disconnect(): Promise<void> {
+    await this.client.close();
+  }
+
+  async load(id: string): Promise<Session<D> | null> {
+    const doc = await this.sessions.findOne({ _id: id });
+    return doc ? readBlob<D>(doc.blob, id) : null;
+  }
+
+  async save(session: Session<D>, expectedVersion: number): Promise<Session<D>> {
+    const next = expectedVersion + 1;
+    const blob = toBlob(session, next);
+    // ponytail: the blob is stored as JSON text, not a sub-document, because
+    // claim keys carry channel message ids and those may contain dots, which
+    // older servers reject in field names. Upgrade: a sub-document once keys
+    // are escaped, for queries on runs and claims.
+    const json = JSON.stringify(blob);
+    const now = new Date();
+    if (expectedVersion === 0) {
+      try {
+        await this.sessions.insertOne({ _id: session.id, version: next, blob: json, createdAt: now, updatedAt: now });
+      } catch (error) {
+        if (!isDuplicateKey(error)) throw error;
+        throw new SessionConflictError(session.id, 0, await this.storedVersion(session.id));
+      }
+      return blob;
+    }
+    const { matchedCount } = await this.sessions.updateOne(
+      { _id: session.id, version: expectedVersion },
+      { $set: { version: next, blob: json, updatedAt: now } },
+    );
+    if (matchedCount === 0) throw new SessionConflictError(session.id, expectedVersion, await this.storedVersion(session.id));
+    return blob;
+  }
+
+  private async storedVersion(id: string): Promise<number | undefined> {
+    const doc = await this.sessions.findOne({ _id: id });
+    return typeof doc?.version === "number" ? doc.version : undefined;
+  }
+}
+
+/** The driver's `MongoServerError` for a unique index hit. */
+const isDuplicateKey = (error: unknown): boolean => isRecord(error) && error.code === 11000;

package/src/persistence/OpenSearchStore.ts

@@ -0,0 +1,153 @@
+/**
+ * OpenSearch Store over the official client (Elasticsearch 7.x fits too).
+ *
+ * One document per session: `id`, `version`, `blob` (stored, not indexed),
+ * `createdAt`, `updatedAt`. A first save is an `index` with `op_type:
+ * 'create'`, and the 409 is the conflict; later saves are a scripted
+ * `update` that compares `version` and becomes a `noop` when it differs,
+ * so the check and the write happen together on the shard (3.x read, then
+ * wrote).
+ */
+
+import { SessionConflictError } from "../types/errors.js";
+import type { Session, Store } from "../types/session.js";
+import { readBlob, toBlob } from "./sessionRow.js";
+
+type Refresh = boolean | "wait_for";
+
+/** Matches `@opensearch-project/opensearch`'s Client. */
+export interface OpenSearchClient {
+  index(params: {
+    index: string;
+    id: string;
+    body: Record<string, unknown>;
+    op_type?: "index" | "create";
+    refresh?: Refresh;
+  }): Promise<{ body: { result: string } }>;
+  update(params: {
+    index: string;
+    id: string;
+    body: Record<string, unknown>;
+    retry_on_conflict?: number;
+    refresh?: Refresh;
+  }): Promise<{ body: { result: string } }>;
+  get(params: { index: string; id: string }): Promise<{ body: { _source: Record<string, unknown> } }>;
+  indices: {
+    exists(params: { index: string }): Promise<{ body: boolean }>;
+    create(params: { index: string; body: { mappings?: Record<string, unknown> } }): Promise<{ body: { acknowledged: boolean } }>;
+  };
+}
+
+export interface OpenSearchStoreOptions {
+  /** Index name. Default `agent_sessions`. */
+  indices?: { sessions?: string };
+  /** Create the index with its mappings on `initialize()`. Default true. */
+  autoCreateIndices?: boolean;
+  /** Refresh policy on writes: `true` at once, `false` in the background, `'wait_for'` blocks. Default false. */
+  refresh?: Refresh;
+}
+
+/** Writes the new version only when the stored one is the expected one; otherwise a noop. */
+const CAS_SCRIPT =
+  "if (ctx._source.version != params.expected) { ctx.op = 'noop' } " +
+  "else { ctx._source.version = params.version; ctx._source.blob = params.blob; ctx._source.updatedAt = params.updatedAt }";
+
+export class OpenSearchStore<D = unknown> implements Store<D> {
+  private readonly client: OpenSearchClient;
+  private readonly index: string;
+  private readonly autoCreateIndices: boolean;
+  private readonly refresh: Refresh;
+
+  constructor(client: OpenSearchClient, options: OpenSearchStoreOptions = {}) {
+    this.client = client;
+    this.index = options.indices?.sessions ?? "agent_sessions";
+    this.autoCreateIndices = options.autoCreateIndices ?? true;
+    this.refresh = options.refresh ?? false;
+  }
+
+  /** Create the index with its mappings when it is missing and `autoCreateIndices` is on. */
+  async initialize(): Promise<void> {
+    if (!this.autoCreateIndices) return;
+    const exists = await this.client.indices.exists({ index: this.index });
+    if (exists.body) return;
+    await this.client.indices.create({
+      index: this.index,
+      body: {
+        mappings: {
+          properties: {
+            id: { type: "keyword" },
+            version: { type: "integer" },
+            blob: { type: "object", enabled: false },
+            createdAt: { type: "date" },
+            updatedAt: { type: "date" },
+          },
+        },
+      },
+    });
+  }
+
+  async load(id: string): Promise<Session<D> | null> {
+    try {
+      const response = await this.client.get({ index: this.index, id });
+      return readBlob<D>(response.body._source.blob, id);
+    } catch (error) {
+      if (statusCodeOf(error) === 404) return null;
+      throw error;
+    }
+  }
+
+  async save(session: Session<D>, expectedVersion: number): Promise<Session<D>> {
+    const next = expectedVersion + 1;
+    const blob = toBlob(session, next);
+    const now = new Date().toISOString();
+    if (expectedVersion === 0) {
+      try {
+        await this.client.index({
+          index: this.index,
+          id: session.id,
+          op_type: "create",
+          body: { id: session.id, version: next, blob, createdAt: now, updatedAt: now },
+          refresh: this.refresh,
+        });
+      } catch (error) {
+        if (statusCodeOf(error) !== 409) throw error;
+        throw new SessionConflictError(session.id, 0, await this.storedVersion(session.id));
+      }
+      return blob;
+    }
+    try {
+      const response = await this.client.update({
+        index: this.index,
+        id: session.id,
+        retry_on_conflict: 3,
+        refresh: this.refresh,
+        body: {
+          script: { lang: "painless", source: CAS_SCRIPT, params: { expected: expectedVersion, version: next, blob, updatedAt: now } },
+        },
+      });
+      if (response.body.result !== "noop") return blob;
+    } catch (error) {
+      const status = statusCodeOf(error);
+      if (status !== 404 && status !== 409) throw error;
+    }
+    throw new SessionConflictError(session.id, expectedVersion, await this.storedVersion(session.id));
+  }
+
+  private async storedVersion(id: string): Promise<number | undefined> {
+    try {
+      const response = await this.client.get({ index: this.index, id });
+      const version = response.body._source.version;
+      return typeof version === "number" ? version : undefined;
+    } catch (error) {
+      if (statusCodeOf(error) === 404) return undefined;
+      throw error;
+    }
+  }
+}
+
+/** The client's `ResponseError` carries the HTTP status as `statusCode`. */
+function statusCodeOf(error: unknown): number | undefined {
+  return typeof error === "object" && error !== null && "statusCode" in error && typeof error.statusCode === "number"
+    ? error.statusCode
+    : undefined;
+}

package/src/persistence/PostgresStore.ts

@@ -0,0 +1,89 @@
+/**
+ * PostgreSQL Store over a `pg` client or pool.
+ *
+ * One row per session: `id`, `version`, `blob` (the v4 session as JSONB),
+ * `created_at`, `updated_at`. The compare-and-swap is the statement itself:
+ * `INSERT … ON CONFLICT DO NOTHING` for a first save, `UPDATE … WHERE
+ * version = $n` after; no row back means someone else got there first.
+ *
+ * A 3.x `agent_sessions` table has different columns. Point `tables.sessions`
+ * at a fresh table; 3.x blobs move through `migrateSession` at the host's
+ * choke point, not through this table.
+ */
+
+import { SessionConflictError } from "../types/errors.js";
+import type { Session, Store } from "../types/session.js";
+import { readBlob, toBlob } from "./sessionRow.js";
+
+export interface PgQueryResult<T = Record<string, unknown>> {
+  rows: T[];
+  rowCount?: number | null;
+}
+
+/** Matches `pg`'s Client and Pool. */
+export interface PgClient {
+  query<T = Record<string, unknown>>(sql: string, values?: unknown[]): Promise<PgQueryResult<T>>;
+  end(): Promise<void>;
+}
+
+export interface PostgresStoreOptions {
+  client: PgClient;
+  /** Table name. Default `agent_sessions`. */
+  tables?: { sessions?: string };
+}
+
+export class PostgresStore<D = unknown> implements Store<D> {
+  private readonly client: PgClient;
+  private readonly table: string;
+
+  constructor(options: PostgresStoreOptions) {
+    this.client = options.client;
+    this.table = options.tables?.sessions ?? "agent_sessions";
+  }
+
+  /** Create the table when it is missing. */
+  async initialize(): Promise<void> {
+    await this.client.query(
+      `CREATE TABLE IF NOT EXISTS ${this.table} (
+        id VARCHAR(255) PRIMARY KEY,
+        version INTEGER NOT NULL,
+        blob JSONB NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )`,
+    );
+  }
+
+  async disconnect(): Promise<void> {
+    await this.client.end();
+  }
+
+  async load(id: string): Promise<Session<D> | null> {
+    const { rows } = await this.client.query(`SELECT blob FROM ${this.table} WHERE id = $1`, [id]);
+    return rows.length > 0 ? readBlob<D>(rows[0].blob, id) : null;
+  }
+
+  async save(session: Session<D>, expectedVersion: number): Promise<Session<D>> {
+    const next = expectedVersion + 1;
+    const blob = toBlob(session, next);
+    const json = JSON.stringify(blob);
+    const { rows } =
+      expectedVersion === 0
+        ? await this.client.query(
+            `INSERT INTO ${this.table} (id, version, blob) VALUES ($1, $2, $3) ON CONFLICT (id) DO NOTHING RETURNING version`,
+            [session.id, next, json],
+          )
+        : await this.client.query(
+            `UPDATE ${this.table} SET version = $2, blob = $3, updated_at = NOW() WHERE id = $1 AND version = $4 RETURNING version`,
+            [session.id, next, json, expectedVersion],
+          );
+    if (rows.length === 0) throw new SessionConflictError(session.id, expectedVersion, await this.storedVersion(session.id));
+    return blob;
+  }
+
+  private async storedVersion(id: string): Promise<number | undefined> {
+    const { rows } = await this.client.query(`SELECT version FROM ${this.table} WHERE id = $1`, [id]);
+    const version = rows[0]?.version;
+    return typeof version === "number" ? version : undefined;
+  }
+}