agent-relay 2.0.28 → 2.0.32

package/packages/storage/src/sqlite-adapter.ts

@@ -0,0 +1,1058 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import {
+  type AgentSummary,
+  type MessageQuery,
+  type MessageStatus,
+  type SessionQuery,
+  type StorageAdapter,
+  type StorageHealth,
+  type StoredMessage,
+  type StoredSession,
+} from './adapter.js';
+
+export interface SqliteAdapterOptions {
+  dbPath: string;
+  /** Message retention period in milliseconds (default: 7 days) */
+  messageRetentionMs?: number;
+  /** Auto-cleanup interval in milliseconds (default: 1 hour, 0 to disable) */
+  cleanupIntervalMs?: number;
+}
+
+/** Default retention: 7 days */
+const DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** Default cleanup interval: 1 hour */
+const DEFAULT_CLEANUP_INTERVAL_MS = 60 * 60 * 1000;
+
+// Re-export types for backwards compatibility
+export type { StoredSession, SessionQuery } from './adapter.js';
+
+type SqliteDriverName = 'better-sqlite3' | 'node';
+
+interface SqliteStatement {
+  run: (...params: any[]) => unknown;
+  all: (...params: any[]) => any[];
+  get: (...params: any[]) => any;
+}
+
+interface SqliteDatabase {
+  exec: (sql: string) => void;
+  prepare: (sql: string) => SqliteStatement;
+  close: () => void;
+  pragma?: (value: string) => void;
+}
+
+export class SqliteStorageAdapter implements StorageAdapter {
+  private dbPath: string;
+  private db?: SqliteDatabase;
+  private insertStmt?: SqliteStatement;
+  private insertSessionStmt?: SqliteStatement;
+  private driver?: SqliteDriverName;
+  private retentionMs: number;
+  private cleanupIntervalMs: number;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+
+  constructor(options: SqliteAdapterOptions) {
+    this.dbPath = options.dbPath;
+    this.retentionMs = options.messageRetentionMs ?? DEFAULT_RETENTION_MS;
+    this.cleanupIntervalMs = options.cleanupIntervalMs ?? DEFAULT_CLEANUP_INTERVAL_MS;
+  }
+
+  private resolvePreferredDriver(): SqliteDriverName | undefined {
+    const raw = process.env.AGENT_RELAY_SQLITE_DRIVER?.trim().toLowerCase();
+    if (!raw) return undefined;
+    if (raw === 'node' || raw === 'node:sqlite' || raw === 'nodesqlite') return 'node';
+    if (raw === 'better-sqlite3' || raw === 'better' || raw === 'bss') return 'better-sqlite3';
+    return undefined;
+  }
+
+  private async openDatabase(driver: SqliteDriverName): Promise<SqliteDatabase> {
+    if (driver === 'node') {
+      // Use require() to avoid toolchains that don't recognize node:sqlite yet (Vitest/Vite).
+      const require = createRequire(import.meta.url);
+      const mod: any = require('node:sqlite');
+      const db: any = new mod.DatabaseSync(this.dbPath);
+      db.exec('PRAGMA journal_mode = WAL;');
+      return db as SqliteDatabase;
+    }
+
+    const mod = await import('better-sqlite3');
+    const DatabaseCtor: any = (mod as any).default ?? mod;
+    const db: any = new DatabaseCtor(this.dbPath);
+    if (typeof db.pragma === 'function') {
+      db.pragma('journal_mode = WAL');
+    } else {
+      db.exec('PRAGMA journal_mode = WAL;');
+    }
+    return db as SqliteDatabase;
+  }
+
+  async init(): Promise<void> {
+    const dir = path.dirname(this.dbPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const preferred = this.resolvePreferredDriver();
+    const attempts: SqliteDriverName[] = preferred
+      ? [preferred, preferred === 'better-sqlite3' ? 'node' : 'better-sqlite3']
+      : ['better-sqlite3', 'node'];
+
+    // Try the fastest/native option first, then fall back to the built-in driver so startup still succeeds on systems without prebuilt binaries
+    let lastError: unknown = null;
+    for (const driver of attempts) {
+      try {
+        this.db = await this.openDatabase(driver);
+        this.driver = driver;
+        lastError = null;
+        break;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[storage] SQLite driver "${driver}" failed: ${msg}`);
+        lastError = err;
+      }
+    }
+
+    if (!this.db) {
+      throw new Error(
+        `Failed to initialize SQLite storage at ${this.dbPath}: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+      );
+    }
+
+    // Check if messages table exists for migration decisions
+    const messagesTableExists = this.db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='messages'"
+    ).get() as { name: string } | undefined;
+
+    if (!messagesTableExists) {
+      // Fresh install: create messages table with all columns
+      this.db.exec(`
+        CREATE TABLE messages (
+          id TEXT PRIMARY KEY,
+          ts INTEGER NOT NULL,
+          sender TEXT NOT NULL,
+          recipient TEXT NOT NULL,
+          topic TEXT,
+          kind TEXT NOT NULL,
+          body TEXT NOT NULL,
+          data TEXT,
+          payload_meta TEXT,
+          thread TEXT,
+          delivery_seq INTEGER,
+          delivery_session_id TEXT,
+          session_id TEXT,
+          status TEXT NOT NULL DEFAULT 'unread',
+          is_urgent INTEGER NOT NULL DEFAULT 0,
+          is_broadcast INTEGER NOT NULL DEFAULT 0
+        );
+        CREATE INDEX idx_messages_ts ON messages (ts);
+        CREATE INDEX idx_messages_sender ON messages (sender);
+        CREATE INDEX idx_messages_recipient ON messages (recipient);
+        CREATE INDEX idx_messages_topic ON messages (topic);
+        CREATE INDEX idx_messages_thread ON messages (thread);
+        CREATE INDEX idx_messages_status ON messages (status);
+        CREATE INDEX idx_messages_is_urgent ON messages (is_urgent);
+      `);
+    } else {
+      // Existing database: run migrations for missing columns
+      const columns = this.db.prepare("PRAGMA table_info(messages)").all() as { name: string }[];
+      const columnNames = new Set(columns.map(c => c.name));
+
+      if (!columnNames.has('thread')) {
+        this.db.exec('ALTER TABLE messages ADD COLUMN thread TEXT');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_messages_thread ON messages (thread)');
+      }
+      if (!columnNames.has('payload_meta')) {
+        this.db.exec('ALTER TABLE messages ADD COLUMN payload_meta TEXT');
+      }
+      if (!columnNames.has('status')) {
+        this.db.exec("ALTER TABLE messages ADD COLUMN status TEXT NOT NULL DEFAULT 'unread'");
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_messages_status ON messages (status)');
+      }
+      if (!columnNames.has('is_urgent')) {
+        this.db.exec("ALTER TABLE messages ADD COLUMN is_urgent INTEGER NOT NULL DEFAULT 0");
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_messages_is_urgent ON messages (is_urgent)');
+      }
+      if (!columnNames.has('is_broadcast')) {
+        this.db.exec("ALTER TABLE messages ADD COLUMN is_broadcast INTEGER NOT NULL DEFAULT 0");
+      }
+    }
+
+    // Create sessions table (IF NOT EXISTS is safe here)
+    // Note: Don't create resume_token index here - it's created after migration check
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        id TEXT PRIMARY KEY,
+        agent_name TEXT NOT NULL,
+        cli TEXT,
+        project_id TEXT,
+        project_root TEXT,
+        started_at INTEGER NOT NULL,
+        ended_at INTEGER,
+        message_count INTEGER DEFAULT 0,
+        summary TEXT,
+        resume_token TEXT,
+        closed_by TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions (agent_name);
+      CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions (started_at);
+      CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions (project_id);
+    `);
+
+    // Migrate existing sessions table to add resume_token if missing
+    const sessionColumns = this.db.prepare("PRAGMA table_info(sessions)").all() as { name: string }[];
+    const sessionColumnNames = new Set(sessionColumns.map(c => c.name));
+    if (!sessionColumnNames.has('resume_token')) {
+      this.db.exec('ALTER TABLE sessions ADD COLUMN resume_token TEXT');
+    }
+    // Create index after ensuring column exists (either from CREATE TABLE or migration)
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_resume_token ON sessions (resume_token)');
+
+    // Create agent_summaries table (IF NOT EXISTS is safe here - no new columns to migrate)
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS agent_summaries (
+        agent_name TEXT PRIMARY KEY,
+        project_id TEXT,
+        last_updated INTEGER NOT NULL,
+        current_task TEXT,
+        completed_tasks TEXT,
+        decisions TEXT,
+        context TEXT,
+        files TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_summaries_updated ON agent_summaries (last_updated);
+    `);
+
+    // Create presence table for real-time status tracking
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS presence (
+        agent_name TEXT PRIMARY KEY,
+        status TEXT NOT NULL DEFAULT 'offline',
+        status_text TEXT,
+        last_activity INTEGER NOT NULL,
+        typing_in TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_presence_status ON presence (status);
+      CREATE INDEX IF NOT EXISTS idx_presence_activity ON presence (last_activity);
+    `);
+
+    // Create read_state table for tracking last read message per channel/conversation
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS read_state (
+        agent_name TEXT NOT NULL,
+        channel TEXT NOT NULL,
+        last_read_ts INTEGER NOT NULL,
+        last_read_id TEXT,
+        PRIMARY KEY (agent_name, channel)
+      );
+    `);
+
+    this.insertStmt = this.db.prepare(`
+      INSERT OR REPLACE INTO messages
+      (id, ts, sender, recipient, topic, kind, body, data, payload_meta, thread, delivery_seq, delivery_session_id, session_id, status, is_urgent, is_broadcast)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    // Start automatic cleanup if enabled
+    if (this.cleanupIntervalMs > 0) {
+      this.startCleanupTimer();
+    }
+  }
+
+  /**
+   * Start the automatic cleanup timer
+   */
+  private startCleanupTimer(): void {
+    // Run cleanup once at startup (async, don't block)
+    this.cleanupExpiredMessages().catch(() => {});
+
+    // Schedule periodic cleanup
+    this.cleanupTimer = setInterval(() => {
+      this.cleanupExpiredMessages().catch(() => {});
+    }, this.cleanupIntervalMs);
+
+    // Prevent timer from keeping process alive
+    if (this.cleanupTimer.unref) {
+      this.cleanupTimer.unref();
+    }
+  }
+
+  /**
+   * Clean up messages older than the retention period
+   * @returns Number of messages deleted
+   */
+  async cleanupExpiredMessages(): Promise<number> {
+    if (!this.db) {
+      return 0;
+    }
+
+    const cutoffTs = Date.now() - this.retentionMs;
+    const stmt = this.db.prepare('DELETE FROM messages WHERE ts < ?');
+    const result = stmt.run(cutoffTs) as { changes?: number };
+    const deleted = result.changes ?? 0;
+
+    if (deleted > 0) {
+      console.log(`[storage] Cleaned up ${deleted} expired messages (older than ${Math.round(this.retentionMs / 86400000)}d)`);
+    }
+
+    return deleted;
+  }
+
+  /**
+   * Check storage health and persistence characteristics.
+   * Uses a tiny helper table to avoid mutating message data.
+   */
+  async healthCheck(): Promise<StorageHealth> {
+    const result: StorageHealth = {
+      persistent: true,
+      driver: 'sqlite',
+      canRead: false,
+      canWrite: false,
+    };
+
+    try {
+      if (!this.db) {
+        await this.init();
+      }
+
+      if (!this.db) {
+        result.error = 'SqliteStorageAdapter not initialized';
+        return result;
+      }
+
+      try {
+        this.db.prepare("SELECT name FROM sqlite_master WHERE type='table' LIMIT 1").get();
+        result.canRead = true;
+      } catch (err) {
+        result.error = `Read check failed: ${err instanceof Error ? err.message : String(err)}`;
+      }
+
+      try {
+        this.db.exec('CREATE TABLE IF NOT EXISTS __relay_health (ts INTEGER NOT NULL)');
+        this.db.prepare('INSERT OR REPLACE INTO __relay_health (ts) VALUES (?)').run(Date.now());
+        // Keep the helper table tiny
+        this.db.exec('DELETE FROM __relay_health WHERE ts < strftime(\'%s\', \'now\') * 1000 - 86400000');
+        result.canWrite = true;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        result.error = result.error
+          ? `${result.error}; write check failed: ${msg}`
+          : `Write check failed: ${msg}`;
+      }
+    } catch (err) {
+      result.error = err instanceof Error ? err.message : String(err);
+    }
+
+    result.persistent = result.canRead && result.canWrite;
+    return result;
+  }
+
+  /**
+   * Get storage statistics
+   */
+  async getStats(): Promise<{ messageCount: number; sessionCount: number; oldestMessageTs?: number }> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const msgCount = this.db.prepare('SELECT COUNT(*) as count FROM messages').get() as { count: number };
+    const sessionCount = this.db.prepare('SELECT COUNT(*) as count FROM sessions').get() as { count: number };
+    const oldest = this.db.prepare('SELECT MIN(ts) as ts FROM messages').get() as { ts: number | null };
+
+    return {
+      messageCount: msgCount.count,
+      sessionCount: sessionCount.count,
+      oldestMessageTs: oldest.ts ?? undefined,
+    };
+  }
+
+  async saveMessage(message: StoredMessage): Promise<void> {
+    if (!this.db || !this.insertStmt) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    this.insertStmt.run(
+      message.id,
+      message.ts,
+      message.from,
+      message.to,
+      message.topic ?? null,
+      message.kind,
+      message.body,
+      message.data ? JSON.stringify(message.data) : null,
+      message.payloadMeta ? JSON.stringify(message.payloadMeta) : null,
+      message.thread ?? null,
+      message.deliverySeq ?? null,
+      message.deliverySessionId ?? null,
+      message.sessionId ?? null,
+      message.status,
+      message.is_urgent ? 1 : 0,
+      message.is_broadcast ? 1 : 0
+    );
+  }
+
+  async getMessages(query: MessageQuery = {}): Promise<StoredMessage[]> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const clauses: string[] = [];
+    const params: unknown[] = [];
+
+    if (query.sinceTs) {
+      clauses.push('m.ts >= ?');
+      params.push(query.sinceTs);
+    }
+    if (query.from) {
+      clauses.push('m.sender = ?');
+      params.push(query.from);
+    }
+    if (query.to) {
+      clauses.push('m.recipient = ?');
+      params.push(query.to);
+    }
+    if (query.topic) {
+      clauses.push('m.topic = ?');
+      params.push(query.topic);
+    }
+    if (query.thread) {
+      clauses.push('m.thread = ?');
+      params.push(query.thread);
+    }
+    if (query.unreadOnly) {
+      clauses.push('m.status = ?');
+      params.push('unread');
+    }
+    if (query.urgentOnly) {
+      clauses.push('m.is_urgent = ?');
+      params.push(1);
+    }
+
+    const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+    const order = query.order === 'asc' ? 'ASC' : 'DESC';
+    const limit = query.limit ?? 200;
+
+    const stmt = this.db.prepare(`
+      SELECT m.id, m.ts, m.sender, m.recipient, m.topic, m.kind, m.body, m.data, m.payload_meta, m.thread, m.delivery_seq, m.delivery_session_id, m.session_id, m.status, m.is_urgent, m.is_broadcast,
+        (SELECT COUNT(*) FROM messages WHERE thread = m.id) as reply_count
+      FROM messages m
+      ${where}
+      ORDER BY m.ts ${order}
+      LIMIT ?
+    `);
+
+    const rows = stmt.all(...params, limit);
+    return rows.map((row: any) => ({
+      id: row.id,
+      ts: row.ts,
+      from: row.sender,
+      to: row.recipient,
+      topic: row.topic ?? undefined,
+      kind: row.kind,
+      body: row.body,
+      data: row.data ? JSON.parse(row.data) : undefined,
+      payloadMeta: row.payload_meta ? JSON.parse(row.payload_meta) : undefined,
+      thread: row.thread ?? undefined,
+      deliverySeq: row.delivery_seq ?? undefined,
+      deliverySessionId: row.delivery_session_id ?? undefined,
+      sessionId: row.session_id ?? undefined,
+      status: row.status,
+      is_urgent: row.is_urgent === 1,
+      is_broadcast: row.is_broadcast === 1,
+      replyCount: row.reply_count || 0,
+    }));
+  }
+
+  async updateMessageStatus(id: string, status: MessageStatus): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+    const stmt = this.db.prepare('UPDATE messages SET status = ? WHERE id = ?');
+    stmt.run(status, id);
+  }
+
+  async getMessageById(id: string): Promise<StoredMessage | null> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    // Support both exact match and prefix match (for short IDs like "06eb33da")
+    const stmt = this.db.prepare(`
+      SELECT m.id, m.ts, m.sender, m.recipient, m.topic, m.kind, m.body, m.data, m.payload_meta, m.thread, m.delivery_seq, m.delivery_session_id, m.session_id, m.status, m.is_urgent, m.is_broadcast,
+        (SELECT COUNT(*) FROM messages WHERE thread = m.id) as reply_count
+      FROM messages m
+      WHERE m.id = ? OR m.id LIKE ?
+      ORDER BY m.ts DESC
+      LIMIT 1
+    `);
+
+    const row: any = stmt.get(id, `${id}%`);
+    if (!row) return null;
+
+    return {
+      id: row.id,
+      ts: row.ts,
+      from: row.sender,
+      to: row.recipient,
+      topic: row.topic ?? undefined,
+      kind: row.kind,
+      body: row.body,
+      data: row.data ? JSON.parse(row.data) : undefined,
+      payloadMeta: row.payload_meta ? JSON.parse(row.payload_meta) : undefined,
+      thread: row.thread ?? undefined,
+      deliverySeq: row.delivery_seq ?? undefined,
+      deliverySessionId: row.delivery_session_id ?? undefined,
+      sessionId: row.session_id ?? undefined,
+      status: row.status ?? 'unread',
+      is_urgent: row.is_urgent === 1,
+      is_broadcast: row.is_broadcast === 1,
+      replyCount: row.reply_count || 0,
+    };
+  }
+
+  async getPendingMessagesForSession(agentName: string, sessionId: string): Promise<StoredMessage[]> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT id, ts, sender, recipient, topic, kind, body, data, payload_meta, thread, delivery_seq, delivery_session_id, session_id, status, is_urgent, is_broadcast
+      FROM messages
+      WHERE recipient = ? AND delivery_session_id = ? AND status != 'acked'
+      ORDER BY delivery_seq ASC, ts ASC
+    `);
+
+    const rows = stmt.all(agentName, sessionId);
+    return rows.map((row: any) => ({
+      id: row.id,
+      ts: row.ts,
+      from: row.sender,
+      to: row.recipient,
+      topic: row.topic ?? undefined,
+      kind: row.kind,
+      body: row.body,
+      data: row.data ? JSON.parse(row.data) : undefined,
+      payloadMeta: row.payload_meta ? JSON.parse(row.payload_meta) : undefined,
+      thread: row.thread ?? undefined,
+      deliverySeq: row.delivery_seq ?? undefined,
+      deliverySessionId: row.delivery_session_id ?? undefined,
+      sessionId: row.session_id ?? undefined,
+      status: row.status ?? 'unread',
+      is_urgent: row.is_urgent === 1,
+      is_broadcast: row.is_broadcast === 1,
+    }));
+  }
+
+  async getMaxSeqByStream(agentName: string, sessionId: string): Promise<Array<{ peer: string; topic?: string; maxSeq: number }>> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT sender, topic, MAX(delivery_seq) as max_seq
+      FROM messages
+      WHERE recipient = ? AND delivery_session_id = ? AND delivery_seq IS NOT NULL
+      GROUP BY sender, topic
+    `);
+
+    const rows = stmt.all(agentName, sessionId) as Array<{ sender: string; topic: string | null; max_seq: number }>;
+    return rows.map(row => ({
+      peer: row.sender,
+      topic: row.topic ?? undefined,
+      maxSeq: row.max_seq,
+    }));
+  }
+
+  async close(): Promise<void> {
+    // Stop cleanup timer
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+
+    if (this.db) {
+      this.db.close();
+      this.db = undefined;
+    }
+  }
+
+  // ============ Session Management ============
+
+  async startSession(session: Omit<StoredSession, 'messageCount'>): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT INTO sessions
+      (id, agent_name, cli, project_id, project_root, started_at, ended_at, message_count, summary, resume_token, closed_by)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        agent_name = excluded.agent_name,
+        cli = COALESCE(excluded.cli, sessions.cli),
+        project_id = COALESCE(excluded.project_id, sessions.project_id),
+        project_root = COALESCE(excluded.project_root, sessions.project_root),
+        started_at = COALESCE(sessions.started_at, excluded.started_at),
+        ended_at = excluded.ended_at,
+        message_count = COALESCE(sessions.message_count, excluded.message_count),
+        summary = COALESCE(excluded.summary, sessions.summary),
+        resume_token = COALESCE(excluded.resume_token, sessions.resume_token),
+        closed_by = excluded.closed_by
+    `);
+
+    stmt.run(
+      session.id,
+      session.agentName,
+      session.cli ?? null,
+      session.projectId ?? null,
+      session.projectRoot ?? null,
+      session.startedAt,
+      session.endedAt ?? null,
+      0,
+      session.summary ?? null,
+      session.resumeToken ?? null,
+      null
+    );
+  }
+
+  /**
+   * End a session and optionally set a summary.
+   *
+   * Note: The summary uses COALESCE(?, summary) - if a summary was previously
+   * set (e.g., during startSession or a prior endSession call), passing null/undefined
+   * for summary will preserve the existing value rather than clearing it.
+   * To explicitly clear a summary, pass an empty string.
+   */
+  async endSession(
+    sessionId: string,
+    options?: { summary?: string; closedBy?: 'agent' | 'disconnect' | 'error' }
+  ): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      UPDATE sessions
+      SET ended_at = ?, summary = COALESCE(?, summary), closed_by = ?
+      WHERE id = ?
+    `);
+
+    stmt.run(
+      Date.now(),
+      options?.summary ?? null,
+      options?.closedBy ?? null,
+      sessionId
+    );
+  }
+
+  async incrementSessionMessageCount(sessionId: string): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      UPDATE sessions SET message_count = message_count + 1 WHERE id = ?
+    `);
+
+    stmt.run(sessionId);
+  }
+
+  async getSessions(query: SessionQuery = {}): Promise<StoredSession[]> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const clauses: string[] = [];
+    const params: unknown[] = [];
+
+    if (query.agentName) {
+      clauses.push('agent_name = ?');
+      params.push(query.agentName);
+    }
+    if (query.projectId) {
+      clauses.push('project_id = ?');
+      params.push(query.projectId);
+    }
+    if (query.since) {
+      clauses.push('started_at >= ?');
+      params.push(query.since);
+    }
+
+    const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+    const limit = query.limit ?? 50;
+
+    const stmt = this.db.prepare(`
+      SELECT id, agent_name, cli, project_id, project_root, started_at, ended_at, message_count, summary, resume_token, closed_by
+      FROM sessions
+      ${where}
+      ORDER BY started_at DESC
+      LIMIT ?
+    `);
+
+    const rows = stmt.all(...params, limit);
+    return rows.map((row: any) => ({
+      id: row.id,
+      agentName: row.agent_name,
+      cli: row.cli ?? undefined,
+      projectId: row.project_id ?? undefined,
+      projectRoot: row.project_root ?? undefined,
+      startedAt: row.started_at,
+      endedAt: row.ended_at ?? undefined,
+      messageCount: row.message_count,
+      summary: row.summary ?? undefined,
+      resumeToken: row.resume_token ?? undefined,
+      closedBy: row.closed_by ?? undefined,
+    }));
+  }
+
+  async getRecentSessions(limit: number = 10): Promise<StoredSession[]> {
+    return this.getSessions({ limit });
+  }
+
+  async getSessionByResumeToken(resumeToken: string): Promise<StoredSession | null> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const row = this.db.prepare(`
+      SELECT id, agent_name, cli, project_id, project_root, started_at, ended_at, message_count, summary, resume_token, closed_by
+      FROM sessions
+      WHERE resume_token = ?
+      LIMIT 1
+    `).get(resumeToken) as any;
+
+    if (!row) {
+      return null;
+    }
+
+    return {
+      id: row.id,
+      agentName: row.agent_name,
+      cli: row.cli ?? undefined,
+      projectId: row.project_id ?? undefined,
+      projectRoot: row.project_root ?? undefined,
+      startedAt: row.started_at,
+      endedAt: row.ended_at ?? undefined,
+      messageCount: row.message_count,
+      summary: row.summary ?? undefined,
+      resumeToken: row.resume_token ?? undefined,
+      closedBy: row.closed_by ?? undefined,
+    };
+  }
+
+  // ============ Agent Summaries ============
+
+  async saveAgentSummary(summary: {
+    agentName: string;
+    projectId?: string;
+    currentTask?: string;
+    completedTasks?: string[];
+    decisions?: string[];
+    context?: string;
+    files?: string[];
+  }): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO agent_summaries
+      (agent_name, project_id, last_updated, current_task, completed_tasks, decisions, context, files)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    stmt.run(
+      summary.agentName,
+      summary.projectId ?? null,
+      Date.now(),
+      summary.currentTask ?? null,
+      summary.completedTasks ? JSON.stringify(summary.completedTasks) : null,
+      summary.decisions ? JSON.stringify(summary.decisions) : null,
+      summary.context ?? null,
+      summary.files ? JSON.stringify(summary.files) : null
+    );
+  }
+
+  async getAgentSummary(agentName: string): Promise<AgentSummary | null> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT agent_name, project_id, last_updated, current_task, completed_tasks, decisions, context, files
+      FROM agent_summaries
+      WHERE agent_name = ?
+    `);
+
+    const row: any = stmt.get(agentName);
+    if (!row) return null;
+
+    return {
+      agentName: row.agent_name,
+      projectId: row.project_id ?? undefined,
+      lastUpdated: row.last_updated,
+      currentTask: row.current_task ?? undefined,
+      completedTasks: row.completed_tasks ? JSON.parse(row.completed_tasks) : undefined,
+      decisions: row.decisions ? JSON.parse(row.decisions) : undefined,
+      context: row.context ?? undefined,
+      files: row.files ? JSON.parse(row.files) : undefined,
+    };
+  }
+
+  async getAllAgentSummaries(): Promise<AgentSummary[]> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT agent_name, project_id, last_updated, current_task, completed_tasks, decisions, context, files
+      FROM agent_summaries
+      ORDER BY last_updated DESC
+    `);
+
+    const rows = stmt.all();
+    return rows.map((row: any) => ({
+      agentName: row.agent_name,
+      projectId: row.project_id ?? undefined,
+      lastUpdated: row.last_updated,
+      currentTask: row.current_task ?? undefined,
+      completedTasks: row.completed_tasks ? JSON.parse(row.completed_tasks) : undefined,
+      decisions: row.decisions ? JSON.parse(row.decisions) : undefined,
+      context: row.context ?? undefined,
+      files: row.files ? JSON.parse(row.files) : undefined,
+    }));
+  }
+
+  // ============ Presence Management ============
+
+  async updatePresence(presence: {
+    agentName: string;
+    status: 'online' | 'away' | 'busy' | 'offline';
+    statusText?: string;
+    typingIn?: string;
+  }): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO presence
+      (agent_name, status, status_text, last_activity, typing_in)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+
+    stmt.run(
+      presence.agentName,
+      presence.status,
+      presence.statusText ?? null,
+      Date.now(),
+      presence.typingIn ?? null
+    );
+  }
+
+  async getPresence(agentName: string): Promise<{
+    agentName: string;
+    status: 'online' | 'away' | 'busy' | 'offline';
+    statusText?: string;
+    lastActivity: number;
+    typingIn?: string;
+  } | null> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT agent_name, status, status_text, last_activity, typing_in
+      FROM presence
+      WHERE agent_name = ?
+    `);
+
+    const row: any = stmt.get(agentName);
+    if (!row) return null;
+
+    return {
+      agentName: row.agent_name,
+      status: row.status,
+      statusText: row.status_text ?? undefined,
+      lastActivity: row.last_activity,
+      typingIn: row.typing_in ?? undefined,
+    };
+  }
+
+  async getAllPresence(): Promise<Array<{
+    agentName: string;
+    status: 'online' | 'away' | 'busy' | 'offline';
+    statusText?: string;
+    lastActivity: number;
+    typingIn?: string;
+  }>> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT agent_name, status, status_text, last_activity, typing_in
+      FROM presence
+      ORDER BY last_activity DESC
+    `);
+
+    const rows = stmt.all();
+    return rows.map((row: any) => ({
+      agentName: row.agent_name,
+      status: row.status,
+      statusText: row.status_text ?? undefined,
+      lastActivity: row.last_activity,
+      typingIn: row.typing_in ?? undefined,
+    }));
+  }
+
+  async setTypingIndicator(agentName: string, channel: string | null): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      UPDATE presence
+      SET typing_in = ?, last_activity = ?
+      WHERE agent_name = ?
+    `);
+
+    stmt.run(channel, Date.now(), agentName);
+  }
+
+  // ============ Read State Management ============
+
+  async updateReadState(agentName: string, channel: string, lastReadTs: number, lastReadId?: string): Promise<void> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO read_state
+      (agent_name, channel, last_read_ts, last_read_id)
+      VALUES (?, ?, ?, ?)
+    `);
+
+    stmt.run(agentName, channel, lastReadTs, lastReadId ?? null);
+  }
+
+  async getReadState(agentName: string, channel: string): Promise<{
+    lastReadTs: number;
+    lastReadId?: string;
+  } | null> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    const stmt = this.db.prepare(`
+      SELECT last_read_ts, last_read_id
+      FROM read_state
+      WHERE agent_name = ? AND channel = ?
+    `);
+
+    const row: any = stmt.get(agentName, channel);
+    if (!row) return null;
+
+    return {
+      lastReadTs: row.last_read_ts,
+      lastReadId: row.last_read_id ?? undefined,
+    };
+  }
+
+  async getUnreadCounts(agentName: string): Promise<Record<string, number>> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    // Get all read states for this agent
+    const readStates = this.db.prepare(`
+      SELECT channel, last_read_ts FROM read_state WHERE agent_name = ?
+    `).all(agentName) as Array<{ channel: string; last_read_ts: number }>;
+
+    const counts: Record<string, number> = {};
+
+    // Count unread messages for each channel (conversation with agent)
+    for (const { channel, last_read_ts } of readStates) {
+      const count = this.db.prepare(`
+        SELECT COUNT(*) as count FROM messages
+        WHERE recipient = ? AND ts > ?
+      `).get(channel, last_read_ts) as { count: number };
+
+      if (count.count > 0) {
+        counts[channel] = count.count;
+      }
+    }
+
+    return counts;
+  }
+
+  // ============ Channel Membership Helpers ============
+
+  /**
+   * Get channels that an agent is a member of based on stored membership events.
+   * Uses window function to find the most recent action per channel.
+   * @returns List of channel names where the agent's latest action is not "leave"
+   */
+  async getChannelMembershipsForAgent(memberName: string): Promise<string[]> {
+    if (!this.db) {
+      throw new Error('SqliteStorageAdapter not initialized');
+    }
+
+    // Query messages with _channelMembership metadata to find channels where
+    // the agent's most recent action is NOT "leave" (i.e., 'join' or 'invite')
+    // Note: 'invite' also adds a member to a channel (see handleMembershipUpdate)
+    const stmt = this.db.prepare(`
+      WITH membership_events AS (
+        SELECT
+          recipient AS channel,
+          json_extract(data, '$._channelMembership.member') AS member,
+          json_extract(data, '$._channelMembership.action') AS action,
+          ts,
+          ROW_NUMBER() OVER (
+            PARTITION BY recipient, json_extract(data, '$._channelMembership.member')
+            ORDER BY ts DESC
+          ) AS rn
+        FROM messages
+        WHERE json_extract(data, '$._channelMembership.member') = ?
+          AND json_extract(data, '$._channelMembership.action') IS NOT NULL
+      )
+      SELECT channel
+      FROM membership_events
+      WHERE rn = 1 AND action != 'leave'
+    `);
+
+    const rows = stmt.all(memberName) as Array<{ channel: string }>;
+    return rows.map(row => row.channel);
+  }
+
+  /**
+   * Remove an agent from the sessions table.
+   * This is used to clean up stale agents from the registry.
+   */
+  async removeAgent(agentName: string): Promise<void> {
+    if (!this.db) {
+      await this.init();
+    }
+
+    const stmt = this.db!.prepare(`
+      DELETE FROM sessions WHERE agent_name = ?
+    `);
+    stmt.run(agentName);
+  }
+
+  /**
+   * Remove all messages from/to an agent.
+   * Use with caution - this permanently deletes message history.
+   */
+  async removeMessagesForAgent(agentName: string): Promise<void> {
+    if (!this.db) {
+      await this.init();
+    }
+
+    const stmt = this.db!.prepare(`
+      DELETE FROM messages WHERE sender = ? OR recipient = ?
+    `);
+    stmt.run(agentName, agentName);
+  }
+}