@falai/agent 3.4.4 → 4.0.0-alpha.1

package/src/adapters/PostgreSQLAdapter.ts

@@ -1,487 +0,0 @@
-/**
- * PostgreSQL adapter for persistence
- * Raw SQL adapter for PostgreSQL with custom schemas
- *
- * ## v2 Migration
- *
- * If upgrading from v1, run the following migration on your sessions table:
- *
- * ```sql
- * ALTER TABLE agent_sessions DROP COLUMN IF EXISTS pending_transition;
- * ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS pending_directive JSONB;
- * ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS signals JSONB;
- * ```
- *
- * `pending_directive` stores the serialized `Directive` that the pipeline
- * applies at the start of the next turn. `signals` is a reserved JSONB column
- * for the v2.x Signals feature — pass-through only in v2.0.
- */
-
-import type {
-  CollectedStateData,
-  SessionRepository,
-  MessageRepository,
-  SessionData,
-  MessageData,
-  SessionStatus,
-  PersistenceAdapter,
-  SessionUpdateOptions,
-} from "../types/index.js";
-import { SessionConflictError } from "../types/errors.js";
-import { createSessionId } from "../utils/index.js";
-import { deserializeSessionRow } from "./sessionRow.js";
-
-/**
- * PostgreSQL query result interface
- */
-export interface PgQueryResult<T = Record<string, unknown>> {
-  rows: T[];
-  rowCount: number;
-}
-
-/**
- * PostgreSQL client interface - matches pg (node-postgres)
- */
-export interface PgClient {
-  query<T = Record<string, unknown>>(
-    sql: string,
-    values?: unknown[]
-  ): Promise<PgQueryResult<T>>;
-  end(): Promise<void>;
-}
-
-/**
- * Options for PostgreSQL adapter
- */
-export interface PostgreSQLAdapterOptions {
-  /**
-   * PostgreSQL client instance (from 'pg' package)
-   */
-  client: PgClient;
-
-  /**
-   * Table names (default: "agent_sessions" and "agent_messages")
-   */
-  tables?: {
-    sessions?: string;
-    messages?: string;
-  };
-}
-
-/**
- * PostgreSQL Adapter - Provider-style API for PostgreSQL persistence
- *
- * @example
- * ```typescript
- * import { Client } from 'pg';
- * import { Agent, PostgreSQLAdapter } from '@falai/agent';
- *
- * const client = new Client({
- *   host: 'localhost',
- *   port: 5432,
- *   database: 'myapp',
- *   user: 'postgres',
- *   password: 'password',
- * });
- * await client.connect();
- *
- * const agent = new Agent({
- *   name: "My Agent",
- *   provider: provider,
- *   persistence: {
- *     adapter: new PostgreSQLAdapter({ client }),
- *     userId: "user_123",
- *   },
- * });
- * ```
- */
-export class PostgreSQLAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
-  public readonly sessionRepository: SessionRepository<TData>;
-  public readonly messageRepository: MessageRepository;
-  private client: PgClient;
-
-  constructor(options: PostgreSQLAdapterOptions) {
-    this.client = options.client;
-
-    const sessionTable = options.tables?.sessions || "agent_sessions";
-    const messageTable = options.tables?.messages || "agent_messages";
-
-    this.sessionRepository = new PostgreSQLSessionRepository<TData>(
-      this.client,
-      sessionTable
-    );
-
-    this.messageRepository = new PostgreSQLMessageRepository(
-      this.client,
-      messageTable
-    );
-  }
-
-  async initialize(): Promise<void> {
-    // Create tables if they don't exist
-    const sessionTable = "agent_sessions";
-    const messageTable = "agent_messages";
-
-    await this.client.query(`
-      CREATE TABLE IF NOT EXISTS ${sessionTable} (
-        id VARCHAR(255) PRIMARY KEY,
-        user_id VARCHAR(255),
-        agent_name VARCHAR(255),
-        status VARCHAR(50) DEFAULT 'active',
-        current_flow VARCHAR(255),
-        current_step VARCHAR(255),
-        collected_data JSONB,
-        pending_directive JSONB,
-        signals JSONB,
-        message_count INTEGER DEFAULT 0,
-        last_message_at TIMESTAMP,
-        completed_at TIMESTAMP,
-        version INTEGER,
-        created_at TIMESTAMP DEFAULT NOW(),
-        updated_at TIMESTAMP DEFAULT NOW()
-      )
-    `);
-
-    // Migration: add the optimistic-concurrency version column to tables
-    // created by pre-2.4 versions
-    await this.client.query(`
-      ALTER TABLE ${sessionTable} ADD COLUMN IF NOT EXISTS version INTEGER
-    `);
-
-    await this.client.query(`
-      CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON ${sessionTable}(user_id);
-      CREATE INDEX IF NOT EXISTS idx_sessions_status ON ${sessionTable}(status);
-    `);
-
-    await this.client.query(`
-      CREATE TABLE IF NOT EXISTS ${messageTable} (
-        id VARCHAR(255) PRIMARY KEY,
-        session_id VARCHAR(255) NOT NULL,
-        user_id VARCHAR(255),
-        role VARCHAR(50) NOT NULL,
-        content TEXT NOT NULL,
-        flow VARCHAR(255),
-        step VARCHAR(255),
-        tool_calls JSONB,
-        event JSONB,
-        created_at TIMESTAMP DEFAULT NOW(),
-        FOREIGN KEY (session_id) REFERENCES ${sessionTable}(id) ON DELETE CASCADE
-      )
-    `);
-
-    await this.client.query(`
-      CREATE INDEX IF NOT EXISTS idx_messages_session_id ON ${messageTable}(session_id);
-      CREATE INDEX IF NOT EXISTS idx_messages_user_id ON ${messageTable}(user_id);
-    `);
-  }
-
-  async disconnect(): Promise<void> {
-    await this.client.end();
-  }
-}
-
-/**
- * PostgreSQL Session Repository
- */
-class PostgreSQLSessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData> {
-  constructor(private client: PgClient, private tableName: string) { }
-
-  async create(
-    data: Omit<SessionData<TData>, "createdAt" | "updatedAt"> & {
-      id?: string;
-    }
-  ): Promise<SessionData<TData>> {
-    const id =
-      data.id || createSessionId();
-    const now = new Date();
-
-    const result = await this.client.query<Record<string, unknown>>(
-      `INSERT INTO ${this.tableName}
-       (id, user_id, agent_name, status, current_flow, current_step, collected_data, message_count, last_message_at, completed_at, version, created_at, updated_at)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
-       RETURNING *`,
-      [
-        id,
-        data.userId || null,
-        data.agentName || null,
-        data.status || "active",
-        data.currentFlow || null,
-        data.currentStep || null,
-        JSON.stringify(data.collectedData || {}),
-        data.messageCount || 0,
-        data.lastMessageAt ?? null,
-        data.completedAt ?? null,
-        data.version ?? 1,
-        now,
-        now,
-      ]
-    );
-
-    return deserializeSessionRow(result.rows[0]);
-  }
-
-  async findById(id: string): Promise<SessionData<TData> | null> {
-    const result = await this.client.query<Record<string, unknown>>(
-      `SELECT * FROM ${this.tableName} WHERE id = $1`,
-      [id]
-    );
-
-    return result.rows[0] ? deserializeSessionRow(result.rows[0]) : null;
-  }
-
-  async findActiveByUserId(userId: string): Promise<SessionData<TData> | null> {
-    const result = await this.client.query<Record<string, unknown>>(
-      `SELECT * FROM ${this.tableName}
-       WHERE user_id = $1 AND status = 'active'
-       ORDER BY created_at DESC
-       LIMIT 1`,
-      [userId]
-    );
-
-    return result.rows[0] ? deserializeSessionRow(result.rows[0]) : null;
-  }
-
-  async findByUserId(
-    userId: string,
-    limit = 100
-  ): Promise<SessionData<TData>[]> {
-    const result = await this.client.query<Record<string, unknown>>(
-      `SELECT * FROM ${this.tableName}
-       WHERE user_id = $1
-       ORDER BY created_at DESC
-       LIMIT $2`,
-      [userId, limit]
-    );
-
-    return result.rows.map((row) => deserializeSessionRow(row));
-  }
-
-  async update(
-    id: string,
-    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>,
-    options?: SessionUpdateOptions
-  ): Promise<SessionData<TData> | null> {
-    const fields: string[] = [];
-    const values: unknown[] = [];
-    let paramIndex = 1;
-
-    if (data.status !== undefined) {
-      fields.push(`status = $${paramIndex++}`);
-      values.push(data.status);
-    }
-    if (data.collectedData !== undefined) {
-      fields.push(`collected_data = $${paramIndex++}`);
-      values.push(JSON.stringify(data.collectedData));
-    }
-    if (data.currentFlow !== undefined) {
-      fields.push(`current_flow = $${paramIndex++}`);
-      values.push(data.currentFlow);
-    }
-    if (data.currentStep !== undefined) {
-      fields.push(`current_step = $${paramIndex++}`);
-      values.push(data.currentStep);
-    }
-    if (data.messageCount !== undefined) {
-      fields.push(`message_count = $${paramIndex++}`);
-      values.push(data.messageCount);
-    }
-    if (data.lastMessageAt !== undefined) {
-      fields.push(`last_message_at = $${paramIndex++}`);
-      values.push(data.lastMessageAt);
-    }
-    if (data.completedAt !== undefined) {
-      fields.push(`completed_at = $${paramIndex++}`);
-      values.push(data.completedAt);
-    }
-
-    fields.push(`updated_at = $${paramIndex++}`);
-    values.push(new Date());
-
-    if (options?.expectedVersion !== undefined) {
-      const expectedVersion = options.expectedVersion;
-
-      // Compare-and-swap in a single statement: rows without a stored version
-      // (pre-2.4) are accepted and adopt expectedVersion as their base
-      fields.push(`version = COALESCE(version, $${paramIndex++}) + 1`);
-      values.push(expectedVersion);
-
-      const idParam = paramIndex++;
-      values.push(id);
-      const versionParam = paramIndex++;
-      values.push(expectedVersion);
-
-      const result = await this.client.query<Record<string, unknown>>(
-        `UPDATE ${this.tableName}
-         SET ${fields.join(", ")}
-         WHERE id = $${idParam} AND (version IS NULL OR version = $${versionParam})
-         RETURNING *`,
-        values
-      );
-
-      if (result.rows[0]) return deserializeSessionRow(result.rows[0]);
-
-      const existing = await this.findById(id);
-      if (!existing) return null;
-      throw new SessionConflictError(id, expectedVersion, existing.version);
-    }
-
-    fields.push(`version = COALESCE(version, 0) + 1`);
-    values.push(id);
-
-    const result = await this.client.query<Record<string, unknown>>(
-      `UPDATE ${this.tableName}
-       SET ${fields.join(", ")}
-       WHERE id = $${paramIndex}
-       RETURNING *`,
-      values
-    );
-
-    return result.rows[0] ? deserializeSessionRow(result.rows[0]) : null;
-  }
-
-  async updateStatus(
-    id: string,
-    status: SessionStatus,
-    completedAt?: Date
-  ): Promise<SessionData<TData> | null> {
-    return await this.update(id, { status, completedAt });
-  }
-
-  async updateCollectedData(
-    id: string,
-    collectedData: CollectedStateData<TData>
-  ): Promise<SessionData<TData> | null> {
-    return await this.update(id, { collectedData });
-  }
-
-  async updateFlowStep(
-    id: string,
-    flow?: string,
-    step?: string
-  ): Promise<SessionData<TData> | null> {
-    return await this.update(id, {
-      currentFlow: flow,
-      currentStep: step,
-    });
-  }
-
-  async incrementMessageCount(id: string): Promise<SessionData<TData> | null> {
-    const result = await this.client.query<Record<string, unknown>>(
-      `UPDATE ${this.tableName}
-       SET message_count = message_count + 1,
-           last_message_at = NOW(),
-           updated_at = NOW()
-       WHERE id = $1
-       RETURNING *`,
-      [id]
-    );
-
-    return result.rows[0] ? deserializeSessionRow(result.rows[0]) : null;
-  }
-
-  async delete(id: string): Promise<boolean> {
-    const result = await this.client.query(
-      `DELETE FROM ${this.tableName} WHERE id = $1`,
-      [id]
-    );
-
-    return result.rowCount > 0;
-  }
-}
-
-/**
- * PostgreSQL Message Repository
- */
-class PostgreSQLMessageRepository implements MessageRepository {
-  constructor(private client: PgClient, private tableName: string) { }
-
-  async create(
-    data: Omit<MessageData, "id" | "createdAt">
-  ): Promise<MessageData> {
-    const id = `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-
-    const result = await this.client.query<MessageData>(
-      `INSERT INTO ${this.tableName}
-       (id, session_id, user_id, role, content, flow, step, tool_calls, event, created_at)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, NOW())
-       RETURNING *`,
-      [
-        id,
-        data.sessionId,
-        data.userId || null,
-        data.role,
-        data.content,
-        data.flow || null,
-        data.step || null,
-        JSON.stringify(data.toolCalls || null),
-        JSON.stringify(data.event || null),
-      ]
-    );
-
-    return result.rows[0];
-  }
-
-  async findById(id: string): Promise<MessageData | null> {
-    const result = await this.client.query<MessageData>(
-      `SELECT * FROM ${this.tableName} WHERE id = $1`,
-      [id]
-    );
-
-    return result.rows[0] || null;
-  }
-
-  async findBySessionId(
-    sessionId: string,
-    limit = 1000
-  ): Promise<MessageData[]> {
-    const result = await this.client.query<MessageData>(
-      `SELECT * FROM ${this.tableName}
-       WHERE session_id = $1
-       ORDER BY created_at ASC
-       LIMIT $2`,
-      [sessionId, limit]
-    );
-
-    return result.rows;
-  }
-
-  async findByUserId(userId: string, limit = 100): Promise<MessageData[]> {
-    const result = await this.client.query<MessageData>(
-      `SELECT * FROM ${this.tableName}
-       WHERE user_id = $1
-       ORDER BY created_at DESC
-       LIMIT $2`,
-      [userId, limit]
-    );
-
-    return result.rows;
-  }
-
-  async delete(id: string): Promise<boolean> {
-    const result = await this.client.query(
-      `DELETE FROM ${this.tableName} WHERE id = $1`,
-      [id]
-    );
-
-    return result.rowCount > 0;
-  }
-
-  async deleteBySessionId(sessionId: string): Promise<number> {
-    const result = await this.client.query(
-      `DELETE FROM ${this.tableName} WHERE session_id = $1`,
-      [sessionId]
-    );
-
-    return result.rowCount;
-  }
-
-  async deleteByUserId(userId: string): Promise<number> {
-    const result = await this.client.query(
-      `DELETE FROM ${this.tableName} WHERE user_id = $1`,
-      [userId]
-    );
-
-    return result.rowCount;
-  }
-}