@stevederico/dotbot 0.16.0

package/core/init.js

@@ -0,0 +1,154 @@
+/**
+ * Unified initialization for dotbot.
+ *
+ * Provides a single entry point that creates and wires all stores, handlers,
+ * and the agent instance. Host apps only need to provide hooks for host-specific
+ * behavior (notifications, preferences).
+ */
+
+import { SQLiteSessionStore } from '../storage/SQLiteAdapter.js';
+import { SQLiteCronStore } from '../storage/SQLiteCronAdapter.js';
+import { SQLiteTaskStore } from '../storage/SQLiteTaskAdapter.js';
+import { SQLiteTriggerStore } from '../storage/SQLiteTriggerAdapter.js';
+import { SQLiteMemoryStore } from '../storage/SQLiteMemoryAdapter.js';
+import { coreTools } from '../tools/index.js';
+import { createCronHandler } from './cron_handler.js';
+import { createTriggerHandler } from './trigger_handler.js';
+
+/**
+ * Initialize dotbot with unified configuration.
+ *
+ * @param {Object} options - Configuration options
+ * @param {string} options.dbPath - Path to SQLite database file
+ * @param {boolean} [options.storesOnly=false] - If true, only initialize stores (no agent, cron, triggers)
+ * @param {Object} [options.sessionStore] - Custom session store (default: SQLiteSessionStore)
+ * @param {Object} [options.providers] - Provider API keys: { anthropic: { apiKey }, openai: { apiKey }, xai: { apiKey } }
+ * @param {Array} [options.tools] - Tool definitions (default: coreTools)
+ * @param {number} [options.staleThresholdMs=86400000] - Skip heartbeat if user idle longer than this (default: 24h)
+ * @param {Function} [options.systemPrompt] - System prompt builder function
+ * @param {Function} [options.screenshotUrlPattern] - Screenshot URL pattern function
+ * @param {Object} [options.compaction] - Compaction settings
+ * @param {Object} [options.hooks] - Host-specific hooks
+ * @param {Function} [options.hooks.onNotification] - async (userId, { title, body, type }) => void
+ * @param {Function} [options.hooks.prefsFetcher] - async (userId) => { agentName, agentPersonality }
+ * @param {Function} [options.hooks.taskFetcher] - async (userId, taskId) => task object
+ * @param {Function} [options.hooks.tasksFinder] - async (userId, filter) => tasks array
+ * @returns {Promise<Object>} { agent, stores, fireTrigger, shutdown } or { stores, shutdown } if storesOnly
+ */
+export async function init({
+  dbPath,
+  storesOnly = false,
+  sessionStore: customSessionStore,
+  providers = {},
+  tools = coreTools,
+  staleThresholdMs = 24 * 60 * 60 * 1000,
+  systemPrompt,
+  screenshotUrlPattern,
+  compaction = { enabled: true },
+  hooks = {},
+} = {}) {
+  if (!dbPath) {
+    throw new Error('init() requires a dbPath');
+  }
+
+  // Initialize stores
+  const taskStore = new SQLiteTaskStore();
+  const triggerStore = new SQLiteTriggerStore();
+  const memoryStore = new SQLiteMemoryStore();
+
+  // Initialize task, trigger, and memory stores (always needed)
+  await taskStore.init({ dbPath });
+  await triggerStore.init({ dbPath });
+  await memoryStore.init({ dbPath });
+
+  // Bundle stores
+  const stores = {
+    task: taskStore,
+    trigger: triggerStore,
+    memory: memoryStore,
+  };
+
+  // For stores-only mode (e.g., dottie-desktop), skip session/cron/agent setup
+  if (storesOnly) {
+    return {
+      stores,
+      shutdown: async () => {},
+    };
+  }
+
+  // Full initialization with sessions, cron, and agent
+  const sessionStore = customSessionStore || new SQLiteSessionStore();
+  const cronStore = new SQLiteCronStore();
+
+  stores.session = sessionStore;
+  stores.cron = cronStore;
+
+  // Initialize session store with hooks
+  if (!customSessionStore) {
+    await sessionStore.init(dbPath, {
+      prefsFetcher: hooks.prefsFetcher,
+      heartbeatEnsurer: async (userId) => {
+        return await cronStore.ensureHeartbeat(userId);
+      },
+    });
+  }
+
+  // Build cron handler with extracted logic
+  const handleCronTask = createCronHandler({
+    sessionStore,
+    cronStore,
+    taskStore,
+    memoryStore,
+    providers,
+    staleThresholdMs,
+    hooks,
+  });
+
+  // Initialize cron store with the handler
+  await cronStore.init(dbPath, { onTaskFire: handleCronTask });
+
+  // Import createAgent dynamically to avoid circular dependency
+  const { createAgent } = await import('../index.js');
+
+  // Create the agent
+  const agent = createAgent({
+    sessionStore,
+    cronStore,
+    taskStore,
+    triggerStore,
+    memoryStore,
+    providers,
+    tools,
+    systemPrompt,
+    screenshotUrlPattern,
+    compaction,
+  });
+
+  // Wire agent to cron handler (resolves chicken-and-egg dependency)
+  handleCronTask.setAgent(agent);
+
+  // Create trigger handler
+  const fireTrigger = createTriggerHandler({
+    agent,
+    sessionStore,
+    triggerStore,
+    memoryStore,
+    providers,
+    hooks,
+  });
+
+  /**
+   * Gracefully shut down all stores and handlers.
+   */
+  async function shutdown() {
+    cronStore.stop();
+    // Add any other cleanup needed
+  }
+
+  return {
+    agent,
+    stores,
+    fireTrigger,
+    shutdown,
+  };
+}

package/core/normalize.js

@@ -0,0 +1,324 @@
+// core/normalize.js
+// Standardize message formats across providers (Anthropic, OpenAI, xAI, Ollama).
+// Provides bidirectional conversion between provider-specific formats and a
+// unified schema that apps can consume without coupling to provider quirks.
+
+/**
+ * Standard message schema (provider-agnostic):
+ *
+ * User message:
+ * {
+ *   role: "user",
+ *   content: string,
+ *   _ts?: number
+ * }
+ *
+ * Assistant message:
+ * {
+ *   role: "assistant",
+ *   content: string,
+ *   toolCalls?: [{ id, name, input, result?, status: "pending"|"done"|"error" }],
+ *   thinking?: string,
+ *   images?: [{ url, prompt }],
+ *   _ts?: number
+ * }
+ *
+ * System message:
+ * {
+ *   role: "system",
+ *   content: string
+ * }
+ */
+
+/**
+ * Convert provider-specific messages to standard format.
+ * Collapses assistant + tool_result pairs into single messages with toolCalls array.
+ *
+ * @param {Array} messages - Raw messages in Anthropic or OpenAI format
+ * @returns {Array} Normalized messages in standard format
+ */
+export function toStandardFormat(messages) {
+  // Build tool result lookup (tool_use_id/tool_call_id → result content)
+  const toolResults = new Map();
+
+  for (const msg of messages) {
+    // Anthropic tool results (role: user, content: [{type: "tool_result", ...}])
+    if (msg.role === 'user' && Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block.type === 'tool_result') {
+          toolResults.set(block.tool_use_id, block.content);
+        }
+      }
+    }
+    // OpenAI tool results (role: tool)
+    if (msg.role === 'tool' && msg.tool_call_id) {
+      toolResults.set(msg.tool_call_id, msg.content);
+    }
+  }
+
+  const normalized = [];
+
+  for (const msg of messages) {
+    // Skip tool-result-only user messages (Anthropic)
+    if (msg.role === 'user' && Array.isArray(msg.content) &&
+        msg.content.length > 0 && msg.content.every(b => b.type === 'tool_result')) {
+      continue;
+    }
+    // Skip OpenAI tool messages
+    if (msg.role === 'tool') continue;
+
+    // System messages
+    if (msg.role === 'system') {
+      normalized.push({ role: 'system', content: msg.content });
+      continue;
+    }
+
+    // User messages
+    if (msg.role === 'user') {
+      normalized.push({
+        role: 'user',
+        content: typeof msg.content === 'string' ? msg.content : '',
+        ...(msg._ts && { _ts: msg._ts })
+      });
+      continue;
+    }
+
+    // Assistant messages
+    if (msg.role === 'assistant') {
+      const standard = {
+        role: 'assistant',
+        content: '',
+        ...(msg._ts && { _ts: msg._ts })
+      };
+
+      // OpenAI format (string content + tool_calls array)
+      if (!Array.isArray(msg.content)) {
+        standard.content = typeof msg.content === 'string' ? msg.content : '';
+
+        if (msg.tool_calls) {
+          standard.toolCalls = msg.tool_calls.map(tc => {
+            const result = toolResults.get(tc.id);
+            let input = {};
+            try {
+              input = JSON.parse(tc.function?.arguments || '{}');
+            } catch {}
+
+            const toolCall = {
+              id: tc.id,
+              name: tc.function?.name,
+              input,
+              status: 'done'
+            };
+
+            if (result !== undefined) {
+              toolCall.result = result;
+              // Check if result is an image
+              try {
+                const parsed = JSON.parse(result);
+                if (parsed.type === 'image' && parsed.url) {
+                  if (!standard.images) standard.images = [];
+                  standard.images.push({ url: parsed.url, prompt: parsed.prompt });
+                }
+              } catch {}
+            }
+
+            return toolCall;
+          });
+        }
+      }
+      // Anthropic format (content block array)
+      else {
+        const toolCalls = [];
+
+        for (const block of msg.content) {
+          if (block.type === 'text') {
+            standard.content += block.text;
+          }
+          else if (block.type === 'tool_use') {
+            const result = toolResults.get(block.id);
+            const toolCall = {
+              id: block.id,
+              name: block.name,
+              input: block.input || {},
+              status: 'done'
+            };
+
+            if (result !== undefined) {
+              toolCall.result = result;
+              // Check if result is an image
+              try {
+                const parsed = JSON.parse(result);
+                if (parsed.type === 'image' && parsed.url) {
+                  if (!standard.images) standard.images = [];
+                  standard.images.push({ url: parsed.url, prompt: parsed.prompt });
+                }
+              } catch {}
+            }
+
+            toolCalls.push(toolCall);
+          }
+          else if (block.type === 'thinking') {
+            standard.thinking = (standard.thinking || '') + (block.thinking || '');
+          }
+        }
+
+        if (toolCalls.length > 0) {
+          standard.toolCalls = toolCalls;
+        }
+      }
+
+      // Clean up empty arrays
+      if (standard.toolCalls?.length === 0) delete standard.toolCalls;
+      if (standard.images?.length === 0) delete standard.images;
+
+      normalized.push(standard);
+    }
+  }
+
+  // Merge consecutive assistant messages (collapse tool-call phases)
+  const merged = [];
+  for (const msg of normalized) {
+    const prev = merged[merged.length - 1];
+    if (prev && prev.role === 'assistant' && msg.role === 'assistant') {
+      // Merge toolCalls
+      if (prev.toolCalls?.length) {
+        msg.toolCalls = [...prev.toolCalls, ...(msg.toolCalls || [])];
+      }
+      // Merge thinking
+      if (prev.thinking) {
+        msg.thinking = (prev.thinking || '') + (msg.thinking || '');
+      }
+      // Merge images
+      if (prev.images?.length) {
+        msg.images = [...(prev.images || []), ...(msg.images || [])];
+      }
+      // Keep first content if current is empty
+      if (!msg.content && prev.content) {
+        msg.content = prev.content;
+      }
+      // Keep earlier timestamp
+      if (prev._ts && !msg._ts) {
+        msg._ts = prev._ts;
+      }
+      merged[merged.length - 1] = msg;
+    } else {
+      merged.push(msg);
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Convert standard format messages to provider-specific format.
+ * Splits assistant messages with toolCalls into separate assistant + tool_result messages.
+ *
+ * @param {Array} messages - Normalized messages in standard format
+ * @param {"anthropic"|"openai"} targetFormat - Target provider format
+ * @returns {Array} Messages in provider-specific format
+ */
+export function toProviderFormat(messages, targetFormat) {
+  const result = [];
+
+  for (const msg of messages) {
+    // System and user messages stay the same
+    if (msg.role === 'system' || msg.role === 'user') {
+      result.push({ ...msg });
+      continue;
+    }
+
+    // Assistant messages with tool calls
+    if (msg.role === 'assistant') {
+      if (targetFormat === 'anthropic') {
+        // Anthropic: content block array
+        const contentBlocks = [];
+
+        if (msg.content) {
+          contentBlocks.push({ type: 'text', text: msg.content });
+        }
+
+        if (msg.thinking) {
+          contentBlocks.push({ type: 'thinking', thinking: msg.thinking });
+        }
+
+        const toolUses = [];
+        if (msg.toolCalls) {
+          for (const tc of msg.toolCalls) {
+            contentBlocks.push({
+              type: 'tool_use',
+              id: tc.id,
+              name: tc.name,
+              input: tc.input
+            });
+            toolUses.push({ id: tc.id, result: tc.result });
+          }
+        }
+
+        result.push({
+          role: 'assistant',
+          content: contentBlocks,
+          ...(msg._ts && { _ts: msg._ts })
+        });
+
+        // Add tool results as separate user message
+        if (toolUses.length > 0) {
+          result.push({
+            role: 'user',
+            content: toolUses.map(tu => ({
+              type: 'tool_result',
+              tool_use_id: tu.id,
+              content: tu.result || ''
+            }))
+          });
+        }
+      }
+      else {
+        // OpenAI: string content + tool_calls array
+        const assistantMsg = {
+          role: 'assistant',
+          content: msg.content || '',
+          ...(msg._ts && { _ts: msg._ts })
+        };
+
+        if (msg.toolCalls) {
+          assistantMsg.tool_calls = msg.toolCalls.map(tc => ({
+            id: tc.id,
+            type: 'function',
+            function: {
+              name: tc.name,
+              arguments: typeof tc.input === 'string' ? tc.input : JSON.stringify(tc.input)
+            }
+          }));
+        }
+
+        result.push(assistantMsg);
+
+        // Add tool results as separate tool messages
+        if (msg.toolCalls) {
+          for (const tc of msg.toolCalls) {
+            if (tc.result !== undefined) {
+              result.push({
+                role: 'tool',
+                tool_call_id: tc.id,
+                content: tc.result
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Normalize messages for frontend display.
+ * Alias for toStandardFormat() for backward compatibility.
+ *
+ * @param {Array} messages - Raw provider-specific messages
+ * @returns {Array} Normalized messages
+ */
+export function normalizeMessages(messages) {
+  return toStandardFormat(messages);
+}

package/core/trigger_handler.js

@@ -0,0 +1,148 @@
+/**
+ * Trigger handler for dotbot.
+ *
+ * Extracted from dottie-os server.js to provide a reusable trigger executor
+ * that handles event matching, firing, and notification hooks.
+ */
+
+import { compactMessages } from './compaction.js';
+
+/**
+ * Create a trigger handler function.
+ *
+ * @param {Object} options
+ * @param {Object} options.agent - Agent instance with chat() method
+ * @param {Object} options.sessionStore - Session store instance
+ * @param {Object} options.triggerStore - Trigger store instance
+ * @param {Object} options.memoryStore - Memory store instance (optional)
+ * @param {Object} options.providers - Provider API keys for compaction
+ * @param {Object} [options.hooks] - Host-specific hooks
+ * @param {Function} [options.hooks.onNotification] - async (userId, { title, body, type }) => void
+ * @returns {Function} Async function: (eventType, userId, eventData?) => Promise<void>
+ */
+export function createTriggerHandler({
+  agent,
+  sessionStore,
+  triggerStore,
+  memoryStore,
+  providers = {},
+  hooks = {},
+}) {
+  /**
+   * Fire triggers for an event.
+   *
+   * @param {string} eventType - Event type (e.g., "user_login", "app_opened")
+   * @param {string} userId - User ID
+   * @param {Object} [eventData] - Optional event payload
+   */
+  async function fireTrigger(eventType, userId, eventData = {}) {
+    if (!userId) {
+      console.warn(`[triggers] fireTrigger called without userId for event ${eventType}`);
+      return;
+    }
+
+    try {
+      // Find matching triggers for this user and event
+      const triggers = await triggerStore.findMatchingTriggers(userId, eventType);
+      if (triggers.length === 0) {
+        console.log(`[triggers] no matching triggers for ${eventType} (user=${userId})`);
+        return;
+      }
+
+      console.log(`[triggers] found ${triggers.length} trigger(s) for ${eventType}`);
+
+      // Get or create the user's session
+      const session = await sessionStore.getOrCreateDefaultSession(userId);
+      if (!session) {
+        console.warn(`[triggers] could not get/create session for user ${userId}`);
+        return;
+      }
+
+      // Process each matching trigger
+      for (const trigger of triggers) {
+        await executeTrigger(trigger, eventType, session, eventData);
+      }
+    } catch (err) {
+      console.error(`[triggers] error handling ${eventType}:`, err.message);
+    }
+  }
+
+  /**
+   * Execute a single trigger.
+   *
+   * @param {Object} trigger - Trigger object
+   * @param {string} eventType - Event type
+   * @param {Object} session - User session
+   * @param {Object} eventData - Event payload
+   */
+  async function executeTrigger(trigger, eventType, session, eventData) {
+    // Mark trigger as fired (handles cooldown tracking)
+    await triggerStore.markTriggerFired(trigger.id);
+
+    // Build the message content
+    let messageContent = `[Event: ${eventType}] ${trigger.prompt}`;
+    if (Object.keys(eventData).length > 0) {
+      messageContent += `\n\nEvent data: ${JSON.stringify(eventData)}`;
+    }
+
+    // Add message to session
+    await sessionStore.addMessage(session.id, {
+      role: 'user',
+      content: messageContent,
+    });
+
+    // Re-fetch session to pick up the added message
+    const updatedSession = await sessionStore.getSessionInternal(session.id);
+    const providerId = updatedSession.provider || 'ollama';
+
+    // Compact old messages before running agent loop
+    const compacted = await compactMessages(updatedSession.messages, {
+      providerId,
+      providers,
+    });
+
+    if (compacted.compacted) {
+      updatedSession.messages = compacted.messages;
+      updatedSession.messages.push({
+        role: 'user',
+        content: '[Compaction] Compressed conversation history',
+        _ts: Date.now(),
+      });
+    }
+
+    // Run the agent chat loop
+    let finalText = '';
+    for await (const event of agent.chat({
+      sessionId: updatedSession.id,
+      message: '', // Message already added to session
+      provider: providerId,
+      model: updatedSession.model,
+      context: {
+        userID: updatedSession.owner,
+        sessionId: updatedSession.id,
+        memoryStore,
+      },
+    })) {
+      if (event.type === 'text_delta' && event.text) {
+        finalText += event.text;
+      }
+    }
+
+    // Create notification if the agent produced meaningful output
+    const trimmed = finalText.trim();
+    if (trimmed && trimmed.length > 10 && updatedSession.owner && hooks.onNotification) {
+      try {
+        await hooks.onNotification(updatedSession.owner, {
+          title: 'Dottie',
+          body: trimmed.slice(0, 500),
+          type: 'trigger',
+        });
+        console.log(`[triggers] notification created for ${updatedSession.owner} (${trimmed.length} chars)`);
+      } catch (err) {
+        console.error(`[triggers] failed to create notification for ${eventType}:`, err.message);
+      }
+    }
+  }
+
+  return fireTrigger;
+}