squidclaw 0.8.3 → 1.0.0

package/lib/engine.js

@@ -107,6 +107,31 @@ export class SquidclawEngine {
             return;
           }
 
+          // Handle /usage command
+          if (message.trim() === '/usage') {
+            try {
+              const { UsageAlerts } = await import('./features/usage-alerts.js');
+              const ua = new UsageAlerts(this.storage);
+              const summary = await ua.getSummary(agentId);
+              const fmtT = (n) => n >= 1e6 ? (n/1e6).toFixed(1)+'M' : n >= 1e3 ? (n/1e3).toFixed(1)+'K' : String(n);
+              const lines = [
+                '📊 *Usage Report*', '',
+                '*Today:*',
+                '  💬 ' + summary.today.calls + ' messages',
+                '  🪙 ' + fmtT(summary.today.tokens) + ' tokens',
+                '  💰 $' + summary.today.cost, '',
+                '*Last 30 days:*',
+                '  💬 ' + summary.month.calls + ' messages',
+                '  🪙 ' + fmtT(summary.month.tokens) + ' tokens',
+                '  💰 $' + summary.month.cost,
+              ];
+              await this.telegramManager.sendMessage(agentId, contactId, lines.join('\n'), metadata);
+            } catch (err) {
+              await this.telegramManager.sendMessage(agentId, contactId, '❌ ' + err.message, metadata);
+            }
+            return;
+          }
+
           // Handle /help command
           if (message.trim() === '/help') {
             const helpText = [
@@ -115,6 +140,7 @@ export class SquidclawEngine {
               '/status — model, uptime, usage stats',
               '/backup — save me to a backup file',
               '/memories — what I remember about you',
+              '/usage — spending report (today + 30 days)',
               '/help — this message',
               '',
               'Just chat normally — I\'ll search the web, remember things, and help! 🦑',
@@ -200,6 +226,139 @@ export class SquidclawEngine {
             return;
           }
 
+          // Process Telegram media (voice, images)
+          if (metadata._ctx && metadata.mediaType) {
+            try {
+              if (metadata.mediaType === 'audio') {
+                // Download and transcribe voice note
+                const file = await metadata._ctx.getFile();
+                const fileUrl = `https://api.telegram.org/file/bot${this.config.channels.telegram.token}/${file.file_path}`;
+                const resp = await fetch(fileUrl);
+                const buffer = Buffer.from(await resp.arrayBuffer());
+                
+                // Transcribe with Groq Whisper (free) or OpenAI
+                const groqKey = this.config.ai?.providers?.groq?.key;
+                const openaiKey = this.config.ai?.providers?.openai?.key;
+                const apiKey = groqKey || openaiKey;
+                const apiUrl = groqKey 
+                  ? 'https://api.groq.com/openai/v1/audio/transcriptions'
+                  : 'https://api.openai.com/v1/audio/transcriptions';
+                const model = groqKey ? 'whisper-large-v3' : 'whisper-1';
+
+                if (apiKey) {
+                  const form = new FormData();
+                  form.append('file', new Blob([buffer], { type: 'audio/ogg' }), 'voice.ogg');
+                  form.append('model', model);
+                  
+                  const tRes = await fetch(apiUrl, {
+                    method: 'POST',
+                    headers: { 'Authorization': 'Bearer ' + apiKey },
+                    body: form,
+                  });
+                  const tData = await tRes.json();
+                  if (tData.text) {
+                    message = '[Voice note]: "' + tData.text + '"';
+                    logger.info('telegram', 'Transcribed voice: ' + tData.text.slice(0, 50));
+                  }
+                }
+              } else if (metadata.mediaType === 'image') {
+                // Download and analyze image
+                const photos = metadata._ctx.message?.photo;
+                if (photos?.length > 0) {
+                  const photo = photos[photos.length - 1]; // highest res
+                  const file = await metadata._ctx.api.getFile(photo.file_id);
+                  const fileUrl = `https://api.telegram.org/file/bot${this.config.channels.telegram.token}/${file.file_path}`;
+                  const resp = await fetch(fileUrl);
+                  const buffer = Buffer.from(await resp.arrayBuffer());
+                  const base64 = buffer.toString('base64');
+                  
+                  // Analyze with Claude or OpenAI Vision
+                  const anthropicKey = this.config.ai?.providers?.anthropic?.key;
+                  const caption = message.replace('[📸 Image]', '').trim();
+                  const userPrompt = caption || 'What is in this image? Be concise.';
+                  
+                  if (anthropicKey) {
+                    const vRes = await fetch('https://api.anthropic.com/v1/messages', {
+                      method: 'POST',
+                      headers: {
+                        'x-api-key': anthropicKey,
+                        'content-type': 'application/json',
+                        'anthropic-version': '2023-06-01',
+                      },
+                      body: JSON.stringify({
+                        model: 'claude-sonnet-4-20250514',
+                        max_tokens: 300,
+                        messages: [{
+                          role: 'user',
+                          content: [
+                            { type: 'image', source: { type: 'base64', media_type: 'image/jpeg', data: base64 } },
+                            { type: 'text', text: userPrompt },
+                          ],
+                        }],
+                      }),
+                    });
+                    const vData = await vRes.json();
+                    const analysis = vData.content?.[0]?.text || '';
+                    if (analysis) {
+                      message = caption 
+                        ? '[Image with caption: "' + caption + '"] Image shows: ' + analysis
+                        : '[Image] Image shows: ' + analysis;
+                      logger.info('telegram', 'Analyzed image: ' + analysis.slice(0, 50));
+                    }
+                  }
+                }
+              } else if (metadata.mediaType === 'document') {
+                const file = await metadata._ctx.getFile();
+                const fileUrl = `https://api.telegram.org/file/bot${this.config.channels.telegram.token}/${file.file_path}`;
+                const resp = await fetch(fileUrl);
+                const buffer = Buffer.from(await resp.arrayBuffer());
+                const filename = message.match(/Document: (.+?)\]/)?.[1] || 'file.txt';
+                
+                try {
+                  const { DocIngester } = await import('./features/doc-ingest.js');
+                  const ingester = new DocIngester(this.storage, this.knowledgeBase, this.home);
+                  const result = await ingester.ingest(agentId, buffer, filename, metadata.mimeType);
+                  
+                  await this.telegramManager.sendMessage(agentId, contactId, 
+                    '📄 *Document absorbed!*\n📁 ' + filename + '\n📊 ' + result.chunks + ' chunks\n📝 ' + result.chars + ' chars\n\nI can answer questions about this! 🦑', metadata);
+                  return;
+                } catch (err) {
+                  message = '[Document: ' + filename + '] (Could not process: ' + err.message + ')';
+                }
+              }
+            } catch (err) {
+              logger.error('telegram', 'Media processing error: ' + err.message);
+            }
+          }
+
+          // Auto-read links in message
+          const linkRegex = /https?:\/\/[^\s<>"')\]]+/gi;
+          if (linkRegex.test(message) && this.toolRouter) {
+            try {
+              const { extractAndReadLinks } = await import('./features/auto-links.js');
+              const linkContext = await extractAndReadLinks(message, this.toolRouter.browser);
+              if (linkContext) {
+                metadata._linkContext = linkContext;
+              }
+            } catch {}
+          }
+
+          // Check usage alerts
+          if (this.usageAlerts) {
+            try {
+              const alert = await this.usageAlerts.check(agentId);
+              if (alert.alert) {
+                await this.telegramManager.sendMessage(agentId, contactId, 
+                  '⚠️ *Usage Alert*\nYou have spent $' + alert.total + ' in the last 24h (threshold: $' + alert.threshold + ')', metadata);
+              }
+            } catch {}
+          }
+
+          // Auto-extract facts from user message
+          if (this.autoMemory) {
+            try { await this.autoMemory.extract(agentId, contactId, message); } catch {}
+          }
+
           // Check if user is asking for a skill we don't have
           const skillRequest = detectSkillRequest(message);
           if (skillRequest) {
@@ -214,10 +373,10 @@ export class SquidclawEngine {
           }
 
           // Show typing indicator while processing
-          const chatId = metadata.chatId || contactId;
-          const botInfo = this.telegramManager?.bots?.values()?.next()?.value;
+          const chatId = metadata.chatId || contactId.replace('tg_', '');
+          const botInfo = this.telegramManager?.bots?.get(agentId);
           let typingInterval;
-          if (botInfo) {
+          if (botInfo?.bot) {
             const sendTyping = () => { try { botInfo.bot.api.sendChatAction(chatId, 'typing').catch(() => {}); } catch {} };
             sendTyping();
             typingInterval = setInterval(sendTyping, 4000);
@@ -235,15 +394,40 @@ export class SquidclawEngine {
           }
           
           if (result.messages && result.messages.length > 0) {
+            // Handle reminder if requested
+            if (result._reminder && this.reminders) {
+              const { time, message: remMsg } = result._reminder;
+              this.reminders.add(agentId, contactId, remMsg, time, 'telegram', metadata);
+            }
+
             // Send image if generated
             if (result.image) {
               const photoData = result.image.url ? { url: result.image.url } : { base64: result.image.base64 };
               const caption = result.messages?.[0] || '';
               await this.telegramManager.sendPhoto(agentId, contactId, photoData, caption, metadata);
             } else {
-              // Send image if generated
+              // Handle reminder if requested
+            if (result._reminder && this.reminders) {
+              const { time, message: remMsg } = result._reminder;
+              this.reminders.add(agentId, contactId, remMsg, time, 'telegram', metadata);
+            }
+
+            // Send image if generated
             if (result.image) {
               await this.telegramManager.sendPhoto(agentId, contactId, result.image, result.messages?.[0] || '', metadata);
+            } else if (metadata.originalType === 'voice' && result.messages.length === 1 && result.messages[0].length < 500) {
+              // Reply with voice when user sent voice
+              try {
+                const { VoiceReply } = await import('./features/voice-reply.js');
+                const vr = new VoiceReply(this.config);
+                const lang = /[\u0600-\u06FF]/.test(result.messages[0]) ? 'ar' : 'en';
+                const audio = await vr.generate(result.messages[0], { language: lang });
+                await this.telegramManager.sendVoice(agentId, contactId, audio, metadata);
+              } catch (err) {
+                // Fallback to text
+                logger.warn('voice', 'Voice reply failed, sending text: ' + err.message);
+                await this.telegramManager.sendMessages(agentId, contactId, result.messages, metadata);
+              }
             } else {
               await this.telegramManager.sendMessages(agentId, contactId, result.messages, metadata);
             }
@@ -293,10 +477,11 @@ export class SquidclawEngine {
     this.heartbeat.start();
     console.log(`  💓 Heartbeat: active`);
 
-    // 7. API Server
+    // 7. API Server + Dashboard
     const app = createAPIServer(this);
-    this.server = app.listen(this.port, this.config.engine?.bind || '127.0.0.1', () => {
-      console.log(`  🌐 API: http://${this.config.engine?.bind || '127.0.0.1'}:${this.port}`);
+    try { const { addDashboardRoutes } = await import('./api/dashboard.js'); addDashboardRoutes(app, this); } catch {}
+    this.server = app.listen(this.port, this.config.engine?.bind || '0.0.0.0', () => {
+      console.log(`  🌐 API: http://${this.config.engine?.bind || '0.0.0.0'}:${this.port}`);
       console.log(`  ──────────────────────────`);
       console.log(`  ✅ Engine running!\n`);
     });

package/lib/features/auto-links.js

@@ -0,0 +1,36 @@
+/**
+ * 🦑 Auto-Link Reader
+ * Detects URLs in messages and fetches their content for context
+ */
+
+import { logger } from '../core/logger.js';
+
+const URL_REGEX = /https?:\/\/[^\s<>"')\]]+/gi;
+
+export async function extractAndReadLinks(message, browser) {
+  const urls = message.match(URL_REGEX);
+  if (!urls || urls.length === 0) return null;
+
+  const results = [];
+  for (const url of urls.slice(0, 3)) { // Max 3 links
+    try {
+      const page = await browser.readPage(url, 2000);
+      if (page && page.content) {
+        results.push({
+          url,
+          title: page.title || url,
+          content: page.content.slice(0, 1500),
+        });
+        logger.info('auto-links', `Read: ${page.title || url}`);
+      }
+    } catch (err) {
+      logger.warn('auto-links', `Failed to read ${url}: ${err.message}`);
+    }
+  }
+
+  if (results.length === 0) return null;
+
+  return results.map(r => 
+    `[Link: ${r.title}]\nURL: ${r.url}\nContent:\n${r.content}`
+  ).join('\n\n---\n\n');
+}

package/lib/features/auto-memory.js

@@ -0,0 +1,107 @@
+/**
+ * 🦑 Auto Memory — Extracts facts from conversations automatically
+ * No AI tags needed — scans messages for personal info, preferences, decisions
+ */
+
+import { logger } from '../core/logger.js';
+
+const FACT_PATTERNS = [
+  // Names
+  { regex: /(?:my name is|call me|i'?m|ana|اسمي|اسم)\s+([A-Z\u0600-\u06FF][a-z\u0600-\u06FF]+)/i, key: 'name', extract: 1 },
+  
+  // Location
+  { regex: /(?:i live in|i'?m from|i'?m in|based in|located in|ساكن في|من)\s+([A-Z\u0600-\u06FF][\w\u0600-\u06FF\s]{2,20})/i, key: 'location', extract: 1 },
+  
+  // Job
+  { regex: /(?:i work (?:as|at|in|for)|my job is|i'?m a|i'?m an|اشتغل|شغلي)\s+(.{3,40}?)(?:\.|,|!|\?|$)/i, key: 'job', extract: 1 },
+  
+  // Age
+  { regex: /(?:i'?m|i am|عمري)\s+(\d{1,3})\s*(?:years? old|سنة|سنه)?/i, key: 'age', extract: 1 },
+  
+  // Family
+  { regex: /(?:my (?:wife|husband|son|daughter|brother|sister|mom|dad|father|mother)(?:'s name)? is)\s+(\w+)/i, key: (m) => m[0].match(/wife|husband|son|daughter|brother|sister|mom|dad|father|mother/i)[0], extract: 1 },
+  
+  // Favorites
+  { regex: /(?:my fav(?:orite|ourite)?\s+(\w+)\s+is)\s+(.+?)(?:\.|,|!|$)/i, key: (m) => 'favorite_' + m[1], extract: 2 },
+  { regex: /(?:i (?:love|like|prefer|enjoy))\s+(.{3,30}?)(?:\.|,|!|\?|$)/i, key: 'likes', extract: 1, append: true },
+  { regex: /(?:i (?:hate|dislike|don'?t like))\s+(.{3,30}?)(?:\.|,|!|\?|$)/i, key: 'dislikes', extract: 1, append: true },
+  
+  // Timezone
+  { regex: /(?:my time(?:zone)? is|i'?m in)\s+(UTC[+-]\d+|GMT[+-]\d+|[A-Z]{2,4}\/[A-Za-z_]+)/i, key: 'timezone', extract: 1 },
+  
+  // Birthday
+  { regex: /(?:my birthday is|born on|ميلادي)\s+(.{5,20})/i, key: 'birthday', extract: 1 },
+
+  // Language
+  { regex: /(?:i speak|my language is|لغتي)\s+(\w+)/i, key: 'language', extract: 1 },
+  
+  // Pet
+  { regex: /(?:my (?:cat|dog|pet)(?:'s name)? is)\s+(\w+)/i, key: (m) => m[0].match(/cat|dog|pet/i)[0] + '_name', extract: 1 },
+];
+
+// Extract per-contact facts
+const CONTACT_PATTERNS = [
+  { regex: /(?:remember|don'?t forget|note|تذكر|لا تنسى)\s+(?:that\s+)?(.{5,100})/i, key: 'noted', extract: 1 },
+];
+
+export class AutoMemory {
+  constructor(storage) {
+    this.storage = storage;
+  }
+
+  /**
+   * Scan a user message for facts and auto-save them
+   */
+  async extract(agentId, contactId, message) {
+    const extracted = [];
+
+    for (const pattern of FACT_PATTERNS) {
+      const match = message.match(pattern.regex);
+      if (!match) continue;
+
+      const key = typeof pattern.key === 'function' ? pattern.key(match) : pattern.key;
+      const value = match[pattern.extract].trim();
+
+      if (value.length < 2 || value.length > 100) continue;
+
+      if (pattern.append) {
+        // Append to existing
+        const existing = await this._getMemory(agentId, key);
+        if (existing && existing.includes(value)) continue;
+        const newValue = existing ? existing + ', ' + value : value;
+        await this.storage.saveMemory(agentId, key, newValue, 'auto');
+      } else {
+        await this.storage.saveMemory(agentId, key, value, 'auto');
+      }
+
+      extracted.push({ key, value });
+      logger.info('auto-memory', `Extracted: ${key} = ${value}`);
+    }
+
+    // Check "remember this" patterns
+    for (const pattern of CONTACT_PATTERNS) {
+      const match = message.match(pattern.regex);
+      if (!match) continue;
+      const value = match[pattern.extract].trim();
+      if (value.length < 3) continue;
+      
+      const key = 'user_note_' + Date.now().toString(36);
+      await this.storage.saveMemory(agentId, key, value, 'noted');
+      extracted.push({ key, value });
+      logger.info('auto-memory', `User note: ${value}`);
+    }
+
+    return extracted;
+  }
+
+  async _getMemory(agentId, key) {
+    try {
+      const row = this.storage.db.prepare(
+        'SELECT value FROM memories WHERE agent_id = ? AND key = ?'
+      ).get(agentId, key);
+      return row?.value;
+    } catch {
+      return null;
+    }
+  }
+}

package/lib/features/doc-ingest.js

@@ -0,0 +1,103 @@
+/**
+ * 🦑 Document Ingestion
+ * Process PDFs, text files, docs sent via chat into knowledge base
+ */
+
+import { logger } from '../core/logger.js';
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+export class DocIngester {
+  constructor(storage, knowledgeBase, home) {
+    this.storage = storage;
+    this.kb = knowledgeBase;
+    this.home = home;
+  }
+
+  async ingest(agentId, buffer, filename, mimeType) {
+    logger.info('doc-ingest', `Processing ${filename} (${mimeType})`);
+
+    let text = '';
+
+    if (mimeType === 'application/pdf') {
+      text = await this._extractPdf(buffer);
+    } else if (mimeType?.includes('text') || filename.endsWith('.txt') || filename.endsWith('.md') || filename.endsWith('.csv')) {
+      text = buffer.toString('utf8');
+    } else if (filename.endsWith('.json')) {
+      text = buffer.toString('utf8');
+    } else {
+      // Try as text
+      text = buffer.toString('utf8');
+      if (text.includes('\ufffd') || /[\x00-\x08\x0e-\x1f]/.test(text.slice(0, 100))) {
+        throw new Error('Unsupported file format: ' + mimeType);
+      }
+    }
+
+    if (!text || text.trim().length < 10) {
+      throw new Error('Could not extract text from file');
+    }
+
+    // Save raw file
+    const docsDir = join(this.home, 'agents', agentId, 'docs');
+    mkdirSync(docsDir, { recursive: true });
+    writeFileSync(join(docsDir, filename), buffer);
+
+    // Chunk and save to knowledge base
+    const chunks = this._chunk(text, 500);
+    const docId = 'doc_' + Date.now().toString(36);
+
+    await this.storage.saveDocument(agentId, {
+      id: docId,
+      title: filename,
+      content: text.slice(0, 500),
+      type: mimeType,
+      chunk_count: chunks.length,
+    });
+
+    for (let i = 0; i < chunks.length; i++) {
+      await this.storage.saveKnowledgeChunk(agentId, {
+        document_id: docId,
+        content: chunks[i],
+        chunk_index: i,
+      });
+    }
+
+    logger.info('doc-ingest', `Saved ${chunks.length} chunks from ${filename}`);
+    return { docId, chunks: chunks.length, chars: text.length };
+  }
+
+  async _extractPdf(buffer) {
+    // Try pdf-parse if available
+    try {
+      const pdfParse = (await import('pdf-parse')).default;
+      const data = await pdfParse(buffer);
+      return data.text;
+    } catch {
+      // Fallback: basic text extraction
+      const text = buffer.toString('utf8');
+      const readable = text.replace(/[^\x20-\x7E\n\r\t\u0600-\u06FF]/g, ' ')
+                          .replace(/\s{3,}/g, '\n')
+                          .trim();
+      if (readable.length > 50) return readable;
+      throw new Error('PDF parsing requires pdf-parse package. Run: npm i pdf-parse');
+    }
+  }
+
+  _chunk(text, maxWords) {
+    const paragraphs = text.split(/\n\s*\n/);
+    const chunks = [];
+    let current = '';
+
+    for (const para of paragraphs) {
+      const words = (current + '\n\n' + para).split(/\s+/).length;
+      if (words > maxWords && current) {
+        chunks.push(current.trim());
+        current = para;
+      } else {
+        current = current ? current + '\n\n' + para : para;
+      }
+    }
+    if (current.trim()) chunks.push(current.trim());
+    return chunks;
+  }
+}

package/lib/features/reminders.js

@@ -0,0 +1,144 @@
+/**
+ * 🦑 Reminders & Scheduled Messages
+ * Agent can set reminders and proactively message users at scheduled times
+ */
+
+import { logger } from '../core/logger.js';
+
+export class ReminderManager {
+  constructor(storage) {
+    this.storage = storage;
+    this.timers = new Map(); // id -> timeout
+    this.onFire = null; // callback(agentId, contactId, message, platform, metadata)
+    this._initDb();
+    this._loadPending();
+  }
+
+  _initDb() {
+    try {
+      this.storage.db.exec(`
+        CREATE TABLE IF NOT EXISTS reminders (
+          id TEXT PRIMARY KEY,
+          agent_id TEXT NOT NULL,
+          contact_id TEXT NOT NULL,
+          message TEXT NOT NULL,
+          fire_at TEXT NOT NULL,
+          platform TEXT DEFAULT 'telegram',
+          metadata TEXT DEFAULT '{}',
+          fired INTEGER DEFAULT 0,
+          created_at TEXT DEFAULT (datetime('now'))
+        )
+      `);
+    } catch (err) {
+      logger.error('reminders', 'Failed to init DB: ' + err.message);
+    }
+  }
+
+  _loadPending() {
+    try {
+      const rows = this.storage.db.prepare(
+        "SELECT * FROM reminders WHERE fired = 0 AND fire_at > datetime('now')"
+      ).all();
+      
+      for (const row of rows) {
+        this._schedule(row);
+      }
+      
+      if (rows.length > 0) {
+        logger.info('reminders', `Loaded ${rows.length} pending reminders`);
+      }
+    } catch (err) {
+      logger.error('reminders', 'Failed to load pending: ' + err.message);
+    }
+  }
+
+  _schedule(reminder) {
+    const fireAt = new Date(reminder.fire_at + 'Z');
+    const now = Date.now();
+    const delay = fireAt.getTime() - now;
+
+    if (delay <= 0) {
+      // Already past — fire immediately
+      this._fire(reminder);
+      return;
+    }
+
+    const timer = setTimeout(() => this._fire(reminder), delay);
+    this.timers.set(reminder.id, timer);
+  }
+
+  async _fire(reminder) {
+    logger.info('reminders', `Firing reminder ${reminder.id} for ${reminder.contact_id}`);
+    
+    // Mark as fired
+    try {
+      this.storage.db.prepare('UPDATE reminders SET fired = 1 WHERE id = ?').run(reminder.id);
+    } catch {}
+
+    this.timers.delete(reminder.id);
+
+    // Call the callback
+    if (this.onFire) {
+      const metadata = JSON.parse(reminder.metadata || '{}');
+      metadata.platform = reminder.platform;
+      await this.onFire(reminder.agent_id, reminder.contact_id, reminder.message, reminder.platform, metadata);
+    }
+  }
+
+  /**
+   * Add a reminder
+   * @param {string} agentId
+   * @param {string} contactId 
+   * @param {string} message - What to say when reminder fires
+   * @param {Date|string} fireAt - When to fire (UTC)
+   * @param {string} platform - telegram/whatsapp
+   * @param {object} metadata - chat metadata for sending
+   */
+  add(agentId, contactId, message, fireAt, platform = 'telegram', metadata = {}) {
+    const id = 'rem_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    const fireAtStr = typeof fireAt === 'string' ? fireAt : fireAt.toISOString().replace('Z', '');
+
+    this.storage.db.prepare(
+      'INSERT INTO reminders (id, agent_id, contact_id, message, fire_at, platform, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)'
+    ).run(id, agentId, contactId, message, fireAtStr, platform, JSON.stringify(metadata));
+
+    this._schedule({ id, agent_id: agentId, contact_id: contactId, message, fire_at: fireAtStr, platform, metadata: JSON.stringify(metadata) });
+
+    logger.info('reminders', `Reminder ${id} set for ${fireAtStr}`);
+    return id;
+  }
+
+  /**
+   * List pending reminders for a contact
+   */
+  list(agentId, contactId) {
+    return this.storage.db.prepare(
+      "SELECT * FROM reminders WHERE agent_id = ? AND contact_id = ? AND fired = 0 AND fire_at > datetime('now') ORDER BY fire_at"
+    ).all(agentId, contactId);
+  }
+
+  /**
+   * Cancel a reminder
+   */
+  cancel(id) {
+    const timer = this.timers.get(id);
+    if (timer) clearTimeout(timer);
+    this.timers.delete(id);
+    this.storage.db.prepare('UPDATE reminders SET fired = 1 WHERE id = ?').run(id);
+    return true;
+  }
+
+  /**
+   * Cancel all reminders for a contact
+   */
+  cancelAll(agentId, contactId) {
+    const pending = this.list(agentId, contactId);
+    for (const r of pending) this.cancel(r.id);
+    return pending.length;
+  }
+
+  destroy() {
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers.clear();
+  }
+}