@stevederico/dotbot 0.16.0

package/storage/SessionStore.js

@@ -0,0 +1,149 @@
+/**
+ * SessionStore Interface
+ *
+ * Abstract interface for session storage backends. Implementations must provide
+ * all methods defined here.
+ */
+export class SessionStore {
+  /**
+   * Initialize the session store
+   *
+   * @param {Object} options - Store-specific initialization options
+   * @param {Function} [options.prefsFetcher] - Async function (userId) => { agentName, agentPersonality }
+   * @param {Function} [options.systemPromptBuilder] - Function ({ agentName, agentPersonality }) => string
+   * @param {Function} [options.heartbeatEnsurer] - Async function (userId) => Promise<Object|null>
+   */
+  async init(options = {}) {
+    throw new Error('SessionStore.init() must be implemented');
+  }
+
+  /**
+   * Create a new session for a user
+   *
+   * @param {string} owner - User ID who owns this session
+   * @param {string} [model] - Initial model name
+   * @param {string} [provider] - AI provider ID
+   * @returns {Promise<Object>} Newly created session document
+   */
+  async createSession(owner, model, provider) {
+    throw new Error('SessionStore.createSession() must be implemented');
+  }
+
+  /**
+   * Get a session by its UUID, verifying ownership
+   *
+   * @param {string} sessionId - Session UUID
+   * @param {string} owner - User ID (for ownership verification)
+   * @returns {Promise<Object|null>} Session document or null
+   */
+  async getSession(sessionId, owner) {
+    throw new Error('SessionStore.getSession() must be implemented');
+  }
+
+  /**
+   * Get a session by ID without ownership check (for internal/cron use)
+   *
+   * @param {string} sessionId - Session UUID
+   * @returns {Promise<Object|null>} Session document or null
+   */
+  async getSessionInternal(sessionId) {
+    throw new Error('SessionStore.getSessionInternal() must be implemented');
+  }
+
+  /**
+   * Get the most recent session for a user, or create one if none exist
+   *
+   * @param {string} owner - User ID
+   * @returns {Promise<Object>} Session document
+   */
+  async getOrCreateDefaultSession(owner) {
+    throw new Error('SessionStore.getOrCreateDefaultSession() must be implemented');
+  }
+
+  /**
+   * Save messages back to storage after agent loop
+   *
+   * @param {string} sessionId - Session UUID
+   * @param {Array} messages - Full conversation history
+   * @param {string} model - Current model name
+   * @param {string} [provider] - AI provider ID
+   */
+  async saveSession(sessionId, messages, model, provider) {
+    throw new Error('SessionStore.saveSession() must be implemented');
+  }
+
+  /**
+   * Add a single message to a session and persist
+   *
+   * @param {string} sessionId - Session UUID
+   * @param {Object} message - Message object with role and content
+   * @returns {Promise<Object>} Updated session
+   */
+  async addMessage(sessionId, message) {
+    throw new Error('SessionStore.addMessage() must be implemented');
+  }
+
+  /**
+   * Set the model for a session
+   *
+   * @param {string} sessionId - Session UUID
+   * @param {string} model - Model name
+   */
+  async setModel(sessionId, model) {
+    throw new Error('SessionStore.setModel() must be implemented');
+  }
+
+  /**
+   * Set the AI provider for a session
+   *
+   * @param {string} sessionId - Session UUID
+   * @param {string} provider - Provider ID
+   */
+  async setProvider(sessionId, provider) {
+    throw new Error('SessionStore.setProvider() must be implemented');
+  }
+
+  /**
+   * Clear a session's conversation history (keeps system prompt)
+   *
+   * @param {string} sessionId - Session UUID
+   */
+  async clearSession(sessionId) {
+    throw new Error('SessionStore.clearSession() must be implemented');
+  }
+
+  /**
+   * List all sessions for a user with summary info
+   *
+   * @param {string} owner - User ID
+   * @returns {Promise<Array>} Session summaries sorted by last update
+   */
+  async listSessions(owner) {
+    throw new Error('SessionStore.listSessions() must be implemented');
+  }
+
+  /**
+   * Delete a session by ID, verifying ownership
+   *
+   * @param {string} sessionId - Session UUID
+   * @param {string} owner - User ID (for ownership verification)
+   * @returns {Promise<any>} Delete result
+   */
+  async deleteSession(sessionId, owner) {
+    throw new Error('SessionStore.deleteSession() must be implemented');
+  }
+
+  /**
+   * Trim messages if conversation is too long
+   *
+   * @param {Array} messages - Full message array
+   * @param {number} [maxMessages] - Maximum messages to keep
+   * @returns {Array} Trimmed message array
+   */
+  trimMessages(messages, maxMessages = 40) {
+    if (messages.length <= maxMessages) return messages;
+    const system = messages[0];
+    const recent = messages.slice(-(maxMessages - 1));
+    return [system, ...recent];
+  }
+}

package/storage/TaskStore.js

@@ -0,0 +1,100 @@
+/**
+ * TaskStore Interface
+ *
+ * Abstract interface for task storage. Implementations must provide
+ * all methods defined here.
+ */
+export class TaskStore {
+  /**
+   * Initialize the task store
+   *
+   * @param {Object} db - Database instance (implementation-specific)
+   * @param {Object} options - Store-specific initialization options
+   */
+  async init(db, options = {}) {
+    throw new Error('TaskStore.init() must be implemented');
+  }
+
+  /**
+   * Create a new task
+   *
+   * @param {Object} params
+   * @param {string} params.userId - Owner user ID
+   * @param {string} params.description - Task description
+   * @param {Array<string|Object>} params.steps - Array of step descriptions or step objects
+   * @param {string} [params.category] - Category (e.g., fitness, learning, productivity)
+   * @param {string} [params.priority] - Priority: low, medium, high
+   * @param {string} [params.deadline] - ISO 8601 deadline
+   * @param {string} [params.mode] - Execution mode: manual or auto
+   * @returns {Promise<Object>} Created task document
+   */
+  async createTask({ userId, description, steps, category, priority, deadline, mode }) {
+    throw new Error('TaskStore.createTask() must be implemented');
+  }
+
+  /**
+   * Get tasks for a user
+   *
+   * @param {string} userId - User ID
+   * @param {Object} filters - Optional filters (status, category, etc.)
+   * @returns {Promise<Array>} Task list
+   */
+  async getTasks(userId, filters = {}) {
+    throw new Error('TaskStore.getTasks() must be implemented');
+  }
+
+  /**
+   * Get a single task by ID
+   *
+   * @param {string} userId - User ID
+   * @param {string} taskId - Task document ID
+   * @returns {Promise<Object|null>} Task document or null
+   */
+  async getTask(userId, taskId) {
+    throw new Error('TaskStore.getTask() must be implemented');
+  }
+
+  /**
+   * Update a task
+   *
+   * @param {string} userId - User ID
+   * @param {string} taskId - Task document ID
+   * @param {Object} updates - Fields to update
+   * @returns {Promise<Object>} Update result
+   */
+  async updateTask(userId, taskId, updates) {
+    throw new Error('TaskStore.updateTask() must be implemented');
+  }
+
+  /**
+   * Delete a task
+   *
+   * @param {string} userId - User ID
+   * @param {string} taskId - Task document ID
+   * @returns {Promise<Object>} Delete result
+   */
+  async deleteTask(userId, taskId) {
+    throw new Error('TaskStore.deleteTask() must be implemented');
+  }
+
+  /**
+   * Search tasks by text
+   *
+   * @param {string} userId - User ID
+   * @param {string} query - Search query
+   * @returns {Promise<Array>} Matching tasks
+   */
+  async searchTasks(userId, query) {
+    throw new Error('TaskStore.searchTasks() must be implemented');
+  }
+
+  /**
+   * Get task statistics
+   *
+   * @param {string} userId - User ID
+   * @returns {Promise<Object>} Stats (total, completed, in_progress, etc.)
+   */
+  async getTaskStats(userId) {
+    throw new Error('TaskStore.getTaskStats() must be implemented');
+  }
+}

package/storage/TriggerStore.js

@@ -0,0 +1,90 @@
+/**
+ * TriggerStore Interface
+ *
+ * Abstract interface for event trigger storage. Implementations must provide
+ * all methods defined here.
+ */
+export class TriggerStore {
+  /**
+   * Initialize the trigger store
+   *
+   * @param {Object} db - Database instance (implementation-specific)
+   * @param {Object} options - Store-specific initialization options
+   */
+  async init(db, options = {}) {
+    throw new Error('TriggerStore.init() must be implemented');
+  }
+
+  /**
+   * Create an event trigger
+   *
+   * @param {Object} params
+   * @param {string} params.userId - Owner user ID
+   * @param {string} params.eventType - Event type to trigger on
+   * @param {string} params.prompt - Prompt to inject when event fires
+   * @param {number} [params.cooldownMs] - Cooldown period in milliseconds
+   * @param {Object} [params.metadata] - Additional metadata (e.g., appName for app_opened events)
+   * @param {boolean} [params.enabled] - Whether trigger is enabled (default: true)
+   * @returns {Promise<Object>} Created trigger document
+   */
+  async createTrigger({ userId, eventType, prompt, cooldownMs, metadata, enabled }) {
+    throw new Error('TriggerStore.createTrigger() must be implemented');
+  }
+
+  /**
+   * List triggers for a user
+   *
+   * @param {string} userId - User ID
+   * @param {Object} filters - Optional filters (enabled, eventType, etc.)
+   * @returns {Promise<Array>} Trigger list
+   */
+  async listTriggers(userId, filters = {}) {
+    throw new Error('TriggerStore.listTriggers() must be implemented');
+  }
+
+  /**
+   * Find enabled triggers matching userId and eventType, filtering out
+   * those still within cooldown period
+   *
+   * @param {string} userId - User ID
+   * @param {string} eventType - Event type to match
+   * @param {Object} metadata - Event metadata for matching (e.g., { appName: 'Mail' })
+   * @returns {Promise<Array>} Matching trigger documents
+   */
+  async findMatchingTriggers(userId, eventType, metadata = {}) {
+    throw new Error('TriggerStore.findMatchingTriggers() must be implemented');
+  }
+
+  /**
+   * Toggle a trigger on/off
+   *
+   * @param {string} userId - User ID
+   * @param {string} triggerId - Trigger document ID
+   * @param {boolean} enabled - Whether to enable or disable
+   * @returns {Promise<Object>} Update result
+   */
+  async toggleTrigger(userId, triggerId, enabled) {
+    throw new Error('TriggerStore.toggleTrigger() must be implemented');
+  }
+
+  /**
+   * Delete a trigger
+   *
+   * @param {string} userId - User ID
+   * @param {string} triggerId - Trigger document ID
+   * @returns {Promise<Object>} Delete result
+   */
+  async deleteTrigger(userId, triggerId) {
+    throw new Error('TriggerStore.deleteTrigger() must be implemented');
+  }
+
+  /**
+   * Record that a trigger has fired by updating its lastFiredAt timestamp
+   *
+   * @param {string} triggerId - Trigger document ID
+   * @returns {Promise<void>}
+   */
+  async markTriggerFired(triggerId) {
+    throw new Error('TriggerStore.markTriggerFired() must be implemented');
+  }
+}

package/storage/cron_constants.js

@@ -0,0 +1,48 @@
+/**
+ * Shared constants and utilities for cron stores
+ *
+ * Used by both MongoCronStore and SQLiteCronStore to ensure consistent
+ * behavior across storage backends.
+ */
+
+/** Heartbeat interval in milliseconds (15 minutes) */
+export const HEARTBEAT_INTERVAL_MS = 15 * 60 * 1000;
+
+/** Max heartbeats processed in parallel per poll cycle */
+export const HEARTBEAT_CONCURRENCY = 5;
+
+/** The current heartbeat prompt — defines proactive agent behavior */
+export const HEARTBEAT_PROMPT = "Review your active tasks and take action on the highest priority one. Use tools to make real progress — search for information, execute steps, send notifications. If no tasks exist, check memories for pending work.";
+
+/**
+ * Run an array of async functions with a concurrency limit
+ *
+ * @param {Array<Function>} fns - Async functions to execute
+ * @param {number} limit - Max concurrent executions
+ */
+export async function runWithConcurrency(fns, limit) {
+  const executing = new Set();
+  for (const fn of fns) {
+    const p = fn().finally(() => executing.delete(p));
+    executing.add(p);
+    if (executing.size >= limit) {
+      await Promise.race(executing);
+    }
+  }
+  await Promise.all(executing);
+}
+
+/**
+ * Parse a human-friendly interval string to milliseconds
+ *
+ * @param {string} str - Interval string e.g. "5m", "2h", "1d", "1w"
+ * @returns {number|null} Milliseconds or null if invalid
+ */
+export function parseInterval(str) {
+  const match = str.match(/^(\d+)\s*(s|m|h|d|w)$/i);
+  if (!match) return null;
+  const num = parseInt(match[1]);
+  const unit = match[2].toLowerCase();
+  const multipliers = { s: 1000, m: 60000, h: 3600000, d: 86400000, w: 604800000 };
+  return num * multipliers[unit];
+}

package/storage/index.js

@@ -0,0 +1,21 @@
+export { SessionStore } from './SessionStore.js';
+export { MongoSessionStore, defaultSystemPrompt } from './MongoAdapter.js';
+export { SQLiteSessionStore } from './SQLiteAdapter.js';
+export { MemorySessionStore } from './MemoryStore.js';
+export { CronStore } from './CronStore.js';
+export { MongoCronStore, parseInterval, HEARTBEAT_INTERVAL_MS, HEARTBEAT_PROMPT } from './MongoCronAdapter.js';
+export { SQLiteCronStore } from './SQLiteCronAdapter.js';
+export { TaskStore } from './TaskStore.js';
+export { MongoTaskStore } from './MongoTaskAdapter.js';
+export { SQLiteTaskStore } from './SQLiteTaskAdapter.js';
+// Backwards compatibility aliases
+export { TaskStore as GoalStore } from './TaskStore.js';
+export { MongoTaskStore as MongoGoalStore } from './MongoTaskAdapter.js';
+export { SQLiteTaskStore as SQLiteGoalStore } from './SQLiteTaskAdapter.js';
+export { TriggerStore } from './TriggerStore.js';
+export { MongoTriggerStore } from './MongoTriggerAdapter.js';
+export { SQLiteTriggerStore } from './SQLiteTriggerAdapter.js';
+export { SQLiteMemoryStore } from './SQLiteMemoryAdapter.js';
+export { EventStore } from './EventStore.js';
+export { SQLiteEventStore } from './SQLiteEventStore.js';
+export * from './cron_constants.js';