@falai/agent 2.6.1 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -43,7 +43,7 @@
     "build:cjs": "tsc --project tsconfig.cjs.json",
     "fix:cjs": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
     "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "typecheck:examples": "tsc --noEmit --project examples/tsconfig.json",
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",

package/src/adapters/MemoryAdapter.ts

@@ -155,34 +155,25 @@ class MemorySessionRepository<TData = Record<string, unknown>>
     return Promise.resolve(cloneDeep(updated));
   }
 
+  // Derived updaters route through update() so every state write shares one
+  // semantic across adapters: version bump + updatedAt refresh (the SQL
+  // adapters delegate to their update() the same way).
+
   async updateStatus(
     id: string,
     status: SessionStatus,
     completedAt?: Date
   ): Promise<SessionData<TData> | null> {
-    const session = this.sessions.get(id);
-    if (session) {
-      session.status = status;
-      if (completedAt) {
-        session.completedAt = completedAt;
-      }
-      this.sessions.set(id, cloneDeep(session));
-      return Promise.resolve(cloneDeep(session));
-    }
-    return Promise.resolve(null);
+    // An undefined completedAt must be omitted, not spread — update() writes
+    // whatever keys it receives, and SQL skips undefined columns.
+    return this.update(id, completedAt ? { status, completedAt } : { status });
   }
 
   async updateCollectedData(
     id: string,
     collectedData: CollectedStateData<TData>
   ): Promise<SessionData<TData> | null> {
-    const session = this.sessions.get(id);
-    if (session) {
-      session.collectedData = collectedData;
-      this.sessions.set(id, cloneDeep(session));
-      return Promise.resolve(cloneDeep(session));
-    }
-    return Promise.resolve(null);
+    return this.update(id, { collectedData });
   }
 
   async updateFlowStep(
@@ -190,24 +181,27 @@ class MemorySessionRepository<TData = Record<string, unknown>>
     flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
-    const session = this.sessions.get(id);
-    if (session) {
-      session.currentFlow = flow;
-      session.currentStep = step;
-      this.sessions.set(id, cloneDeep(session));
-      return Promise.resolve(cloneDeep(session));
-    }
-    return Promise.resolve(null);
+    // Mirror SQL's conditional column assembly: only defined values are written.
+    return this.update(id, {
+      ...(flow !== undefined && { currentFlow: flow }),
+      ...(step !== undefined && { currentStep: step }),
+    });
   }
 
   async incrementMessageCount(id: string): Promise<SessionData<TData> | null> {
+    // Bookkeeping write, deliberately NOT routed through update(): count bumps
+    // run alongside saveSessionState's version CAS every turn, so they must not
+    // move `version` (matches the SQL adapters' dedicated statement).
     const session = this.sessions.get(id);
-    if (session) {
-      session.messageCount = (session.messageCount || 0) + 1;
-      this.sessions.set(id, cloneDeep(session));
-      return Promise.resolve(cloneDeep(session));
-    }
-    return Promise.resolve(null);
+    if (!session) return Promise.resolve(null);
+    const updated: SessionData<TData> = {
+      ...session,
+      messageCount: (session.messageCount || 0) + 1,
+      lastMessageAt: new Date(),
+      updatedAt: new Date(),
+    };
+    this.sessions.set(id, cloneDeep(updated));
+    return Promise.resolve(cloneDeep(updated));
   }
 
   async delete(id: string): Promise<boolean> {
@@ -232,8 +226,10 @@ class MemoryMessageRepository implements MessageRepository {
       createdAt: new Date(),
     };
 
-    this.messages.set(id, message);
-    return Promise.resolve(message);
+    // Clone on store and on return so callers can't mutate the stored row —
+    // same isolation the session repository provides.
+    this.messages.set(id, cloneDeep(message));
+    return Promise.resolve(cloneDeep(message));
   }
 
   async findById(id: string): Promise<MessageData | null> {

package/src/adapters/PostgreSQLAdapter.ts

@@ -29,6 +29,7 @@ import type {
 } from "../types";
 import { SessionConflictError } from "../types/errors";
 import { createSessionId } from "../utils";
+import { deserializeSessionRow } from "./sessionRow";
 
 /**
  * PostgreSQL query result interface
@@ -195,61 +196,65 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
       data.id || createSessionId();
     const now = new Date();
 
-    const result = await this.client.query<SessionData<TData>>(
+    const result = await this.client.query<Record<string, unknown>>(
       `INSERT INTO ${this.tableName}
-       (id, user_id, agent_name, status, collected_data, message_count, version, created_at, updated_at)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+       (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 result.rows[0];
+    return deserializeSessionRow(result.rows[0]);
   }
 
   async findById(id: string): Promise<SessionData<TData> | null> {
-    const result = await this.client.query<SessionData<TData>>(
+    const result = await this.client.query<Record<string, unknown>>(
       `SELECT * FROM ${this.tableName} WHERE id = $1`,
       [id]
     );
 
-    return result.rows[0] || null;
+    return result.rows[0] ? deserializeSessionRow(result.rows[0]) : null;
   }
 
   async findActiveByUserId(userId: string): Promise<SessionData<TData> | null> {
-    const result = await this.client.query<SessionData<TData>>(
-      `SELECT * FROM ${this.tableName} 
+    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] || null;
+    return result.rows[0] ? deserializeSessionRow(result.rows[0]) : null;
   }
 
   async findByUserId(
     userId: string,
     limit = 100
   ): Promise<SessionData<TData>[]> {
-    const result = await this.client.query<SessionData<TData>>(
-      `SELECT * FROM ${this.tableName} 
+    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;
+    return result.rows.map((row) => deserializeSessionRow(row));
   }
 
   async update(
@@ -306,7 +311,7 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
       const versionParam = paramIndex++;
       values.push(expectedVersion);
 
-      const result = await this.client.query<SessionData<TData>>(
+      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})
@@ -314,7 +319,7 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
         values
       );
 
-      if (result.rows[0]) return result.rows[0];
+      if (result.rows[0]) return deserializeSessionRow(result.rows[0]);
 
       const existing = await this.findById(id);
       if (!existing) return null;
@@ -324,7 +329,7 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
     fields.push(`version = COALESCE(version, 0) + 1`);
     values.push(id);
 
-    const result = await this.client.query<SessionData<TData>>(
+    const result = await this.client.query<Record<string, unknown>>(
       `UPDATE ${this.tableName}
        SET ${fields.join(", ")}
        WHERE id = $${paramIndex}
@@ -332,7 +337,7 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
       values
     );
 
-    return result.rows[0] || null;
+    return result.rows[0] ? deserializeSessionRow(result.rows[0]) : null;
   }
 
   async updateStatus(
@@ -362,7 +367,7 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
   }
 
   async incrementMessageCount(id: string): Promise<SessionData<TData> | null> {
-    const result = await this.client.query<SessionData<TData>>(
+    const result = await this.client.query<Record<string, unknown>>(
       `UPDATE ${this.tableName}
        SET message_count = message_count + 1,
            last_message_at = NOW(),
@@ -372,7 +377,7 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
       [id]
     );
 
-    return result.rows[0] || null;
+    return result.rows[0] ? deserializeSessionRow(result.rows[0]) : null;
   }
 
   async delete(id: string): Promise<boolean> {

package/src/adapters/RedisAdapter.ts

@@ -15,6 +15,7 @@ import type {
 } from "../types";
 import { SessionConflictError } from "../types/errors";
 import { createSessionId, logger } from "../utils";
+import { coerceDate } from "./sessionRow";
 
 /**
  * Redis client interface - matches ioredis/redis clients
@@ -27,6 +28,7 @@ export interface RedisClient {
   keys(pattern: string): Promise<string[]>;
   hgetall(key: string): Promise<Record<string, string>>;
   hset(key: string, field: string, value: string): Promise<number>;
+  hdel(key: string, field: string): Promise<number>;
   expire(key: string, seconds: number): Promise<number>;
   quit(): Promise<string>;
 }
@@ -162,7 +164,16 @@ class RedisSessionRepository<TData = Record<string, unknown>>
     const data = await this.redis.get(this.getKey(id));
     if (!data) return null;
     try {
-      return JSON.parse(data) as SessionData<TData>;
+      const parsed = JSON.parse(data) as SessionData<TData>;
+      // JSON round-trips turn Dates into ISO strings — coerce on read so
+      // callers always get Date instances (parity with the SQL adapters).
+      return {
+        ...parsed,
+        lastMessageAt: coerceDate(parsed.lastMessageAt),
+        completedAt: coerceDate(parsed.completedAt),
+        createdAt: coerceDate(parsed.createdAt) ?? new Date(),
+        updatedAt: coerceDate(parsed.updatedAt) ?? new Date(),
+      };
     } catch (error) {
       logger.error(`Error parsing session data for id ${id}:`, error);
       return null;
@@ -172,7 +183,13 @@ class RedisSessionRepository<TData = Record<string, unknown>>
   async findActiveByUserId(userId: string): Promise<SessionData<TData> | null> {
     const sessionIds = await this.redis.hgetall(this.getUserKey(userId));
 
-    for (const sessionId of Object.keys(sessionIds)) {
+    // Newest-first: the hash values ARE the sessions' createdAt ISO strings,
+    // which sort lexicographically. Iterating hash order instead would return
+    // an arbitrary active session, not the most recent one.
+    const newestFirst = Object.keys(sessionIds).sort((a, b) =>
+      sessionIds[b].localeCompare(sessionIds[a])
+    );
+    for (const sessionId of newestFirst) {
       const session = await this.findById(sessionId);
       if (session && session.status === "active") {
         return session;
@@ -187,19 +204,21 @@ class RedisSessionRepository<TData = Record<string, unknown>>
     limit = 100
   ): Promise<SessionData<TData>[]> {
     const sessionIds = await this.redis.hgetall(this.getUserKey(userId));
-    const sessions: SessionData<TData>[] = [];
 
-    for (const sessionId of Object.keys(sessionIds).slice(0, limit)) {
+    // Sort BEFORE limiting (hash values are the createdAt ISO strings) —
+    // limiting first would keep an arbitrary hash-order subset.
+    const newestFirst = Object.keys(sessionIds)
+      .sort((a, b) => sessionIds[b].localeCompare(sessionIds[a]))
+      .slice(0, limit);
+    const sessions: SessionData<TData>[] = [];
+    for (const sessionId of newestFirst) {
       const session = await this.findById(sessionId);
       if (session) {
         sessions.push(session);
       }
     }
 
-    return sessions.sort(
-      (a, b) =>
-        new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
-    );
+    return sessions;
   }
 
   async update(
@@ -240,7 +259,9 @@ class RedisSessionRepository<TData = Record<string, unknown>>
     status: SessionStatus,
     completedAt?: Date
   ): Promise<SessionData<TData> | null> {
-    return this.update(id, { status, completedAt });
+    // An undefined completedAt must be omitted, not spread — update() writes
+    // whatever keys it receives, and SQL skips undefined columns.
+    return this.update(id, completedAt ? { status, completedAt } : { status });
   }
 
   async updateCollectedData(
@@ -255,21 +276,40 @@ class RedisSessionRepository<TData = Record<string, unknown>>
     flow?: string,
     step?: string
   ): Promise<SessionData<TData> | null> {
-    return this.update(id, { currentFlow: flow, currentStep: step });
+    // Mirror SQL's conditional column assembly: only defined values are written.
+    return this.update(id, {
+      ...(flow !== undefined && { currentFlow: flow }),
+      ...(step !== undefined && { currentStep: step }),
+    });
   }
 
   async incrementMessageCount(id: string): Promise<SessionData<TData> | null> {
     const session = await this.findById(id);
     if (!session) return null;
 
-    return this.update(id, {
+    // Bookkeeping write, deliberately NOT routed through update(): count bumps
+    // run alongside saveSessionState's version CAS every turn, so they must
+    // not move `version` (matches the SQL adapters' dedicated statement).
+    const updated: SessionData<TData> = {
+      ...session,
       messageCount: (session.messageCount || 0) + 1,
       lastMessageAt: new Date(),
-    });
+      updatedAt: new Date(),
+    };
+    await this.redis.setex(this.getKey(id), this.ttl, JSON.stringify(updated));
+    return updated;
   }
 
   async delete(id: string): Promise<boolean> {
+    // Look up first so the user index can be cleaned too — otherwise
+    // findActiveByUserId/findByUserId chase dead ids forever.
+    const existing = await this.findById(id);
+    if (!existing) return false;
+
     const result = await this.redis.del(this.getKey(id));
+    if (existing.userId) {
+      await this.redis.hdel(this.getUserKey(existing.userId), id);
+    }
     return result > 0;
   }
 }
@@ -316,7 +356,8 @@ class RedisMessageRepository implements MessageRepository {
     const data = await this.redis.get(this.getKey(id));
     if (!data) return null;
     try {
-      return JSON.parse(data) as MessageData;
+      const message = JSON.parse(data) as MessageData;
+      return { ...message, createdAt: coerceDate(message.createdAt) ?? new Date() };
     } catch (error) {
       logger.error(`Error parsing message data for id ${id}:`, error);
       return null;
@@ -328,18 +369,21 @@ class RedisMessageRepository implements MessageRepository {
     limit = 1000
   ): Promise<MessageData[]> {
     const messageIds = await this.redis.hgetall(this.getSessionKey(sessionId));
-    const messages: MessageData[] = [];
-
-    for (const messageId of Object.keys(messageIds).slice(0, limit)) {
-      const message = await this.findById(messageId);
-      if (message) {
-        messages.push(message);
-      }
-    }
 
-    return messages.sort(
-      (a, b) => a.createdAt.getTime() - b.createdAt.getTime()
+    // Fetch ALL candidates first — limiting before sorting would keep an
+    // arbitrary hash-order subset instead of the oldest messages. The fetches
+    // are independent, so run them concurrently instead of N serialized
+    // round trips.
+    const fetched = await Promise.all(
+      Object.keys(messageIds).map((messageId) => this.findById(messageId))
     );
+    const messages = fetched.filter((m): m is MessageData => m !== null);
+
+    // Chronological order (matches PostgreSQL/Mongo adapters); limit applies
+    // only after sorting is meaningful.
+    return messages
+      .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+      .slice(0, limit);
   }
 
   async findByUserId(userId: string, limit = 100): Promise<MessageData[]> {
@@ -347,21 +391,24 @@ class RedisMessageRepository implements MessageRepository {
     // This would require additional indexing
     const pattern = `${this.keyPrefix}message:*`;
     const keys = await this.redis.keys(pattern);
-    const messages: MessageData[] = [];
 
-    for (const key of keys.slice(0, limit)) {
-      const data = await this.redis.get(key);
-      if (data) {
-        const message: MessageData = JSON.parse(data) as MessageData;
-        if (message.userId === userId) {
-          messages.push(message);
-        }
+    // Filter by userId BEFORE limiting — slicing keys first would drop
+    // matching messages that happen to sort after unrelated users' keys.
+    // ponytail: full keyspace scan per user query (pre-existing ceiling of
+    // this adapter); the upgrade path is a per-user message index.
+    const fetched = await Promise.all(keys.map((key) => this.redis.get(key)));
+    const messages: MessageData[] = [];
+    for (const data of fetched) {
+      if (!data) continue;
+      const parsed: MessageData = JSON.parse(data);
+      if (parsed.userId === userId) {
+        messages.push({ ...parsed, createdAt: coerceDate(parsed.createdAt) ?? new Date() });
       }
     }
 
-    return messages.sort(
-      (a, b) => b.createdAt.getTime() - a.createdAt.getTime()
-    );
+    return messages
+      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+      .slice(0, limit);
   }
 
   async delete(id: string): Promise<boolean> {

package/src/adapters/SQLiteAdapter.ts

@@ -33,6 +33,7 @@ import type {
 } from "../types";
 import { SessionConflictError } from "../types/errors";
 import { createSessionId } from "../utils";
+import { deserializeSessionRow } from "./sessionRow";
 
 /**
  * SQLite database interface - matches better-sqlite3
@@ -202,8 +203,8 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
 
     const stmt = this.db.prepare(`
       INSERT INTO ${this.tableName}
-      (id, user_id, agent_name, status, collected_data, message_count, version, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      (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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
 
     stmt.run(
@@ -211,8 +212,12 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
       data.userId || null,
       data.agentName || null,
       session.status,
+      data.currentFlow || null,
+      data.currentStep || null,
       JSON.stringify(data.collectedData || {}),
       session.messageCount,
+      data.lastMessageAt ? data.lastMessageAt.toISOString() : null,
+      data.completedAt ? data.completedAt.toISOString() : null,
       session.version,
       now.toISOString(),
       now.toISOString()
@@ -226,7 +231,7 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
       `SELECT * FROM ${this.tableName} WHERE id = ?`
     );
     const row = stmt.get(id);
-    return Promise.resolve(row ? this.deserializeSession(row) : null);
+    return Promise.resolve(row ? deserializeSessionRow(row) : null);
   }
 
   findActiveByUserId(userId: string): Promise<SessionData<TData> | null> {
@@ -237,7 +242,7 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
        LIMIT 1`
     );
     const row = stmt.get(userId);
-    return Promise.resolve(row ? this.deserializeSession(row) : null);
+    return Promise.resolve(row ? deserializeSessionRow(row) : null);
   }
 
   findByUserId(userId: string, limit = 100): Promise<SessionData<TData>[]> {
@@ -248,7 +253,7 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
        LIMIT ?`
     );
     const rows = stmt.all(userId, limit);
-    return Promise.resolve(rows.map((row) => this.deserializeSession(row)));
+    return Promise.resolve(rows.map((row) => deserializeSessionRow(row)));
   }
 
   async update(
@@ -378,32 +383,6 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
     const result = stmt.run(id);
     return Promise.resolve(result.changes > 0);
   }
-
-  private deserializeSession(row: Record<string, unknown>): SessionData<TData> {
-    return {
-      id: row.id as string,
-      userId: (row.user_id as string) || undefined,
-      agentName: (row.agent_name as string) || undefined,
-      status: row.status as SessionStatus,
-      currentFlow: (row.current_flow as string) || undefined,
-      currentStep: (row.current_step as string) || undefined,
-      collectedData: row.collected_data
-        ? (JSON.parse(
-          row.collected_data as string
-        ) as CollectedStateData<TData>)
-        : undefined,
-      messageCount: (row.message_count as number) || 0,
-      lastMessageAt: row.last_message_at
-        ? new Date(row.last_message_at as string)
-        : undefined,
-      completedAt: row.completed_at
-        ? new Date(row.completed_at as string)
-        : undefined,
-      version: (row.version as number | null) ?? undefined,
-      createdAt: new Date(row.created_at as string),
-      updatedAt: new Date(row.updated_at as string),
-    };
-  }
 }
 
 /**

package/src/adapters/sessionRow.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared row-mapping for the SQL-shaped session adapters (PostgreSQL, SQLite)
+ * and date coercion for JSON-round-tripped values (Redis).
+ *
+ * One implementation so the adapters can't drift on what a stored session row
+ * means. PostgreSQL's driver returns JSONB pre-parsed and timestamptz as Date
+ * instances; SQLite returns strings — both shapes are accepted here.
+ */
+
+import type {
+  CollectedStateData,
+  SessionData,
+  SessionStatus,
+} from "../types";
+
+/**
+ * Coerce a raw stored value into a Date. Drivers variously hand back Date
+ * instances (node-postgres timestamptz) or ISO strings (SQLite, JSON blobs).
+ * `null`/`undefined` maps to `undefined`.
+ */
+export function coerceDate(value: unknown): Date | undefined {
+  if (value == null) return undefined;
+  return value instanceof Date ? value : new Date(value as string);
+}
+
+/**
+ * Map a raw snake_case row onto the camelCase SessionData interface.
+ * `collected_data` arrives JSONB-parsed on PostgreSQL and as a raw string on
+ * SQLite — both are handled. Exported for the adapter mapping tests.
+ */
+export function deserializeSessionRow<TData = Record<string, unknown>>(
+  row: Record<string, unknown>
+): SessionData<TData> {
+  const collected = row.collected_data;
+  return {
+    id: row.id as string,
+    userId: (row.user_id as string) || undefined,
+    agentName: (row.agent_name as string) || undefined,
+    status: row.status as SessionStatus,
+    currentFlow: (row.current_flow as string) || undefined,
+    currentStep: (row.current_step as string) || undefined,
+    collectedData:
+      collected == null
+        ? undefined
+        : typeof collected === "string"
+          ? (JSON.parse(collected) as CollectedStateData<TData>)
+          : (collected as CollectedStateData<TData>),
+    messageCount: (row.message_count as number) || 0,
+    lastMessageAt: coerceDate(row.last_message_at),
+    completedAt: coerceDate(row.completed_at),
+    version: (row.version as number | null) ?? undefined,
+    // created_at/updated_at are NOT NULL in every adapter's schema; the
+    // fallback only covers hand-crafted rows.
+    createdAt: coerceDate(row.created_at) ?? new Date(),
+    updatedAt: coerceDate(row.updated_at) ?? new Date(),
+  };
+}