@stevederico/dotbot 0.16.0

package/docs/core.md

@@ -0,0 +1,103 @@
+Core AI Agent Framework Features (Both Have)                                                                                      
+                                                                                                                                    
+  1. Multi-Provider AI Support - Anthropic, OpenAI, multiple LLM backends                                                           
+  2. Long-Term Memory - Persistent storage across sessions
+  3. Tool Execution System - Agent can perform actions (web search, file ops, etc.)                                                 
+  4. Session Management - Track conversation history
+  5. Scheduled Tasks - Cron/recurring actions
+  6. Web Search Integration - Access current information
+  7. File Operations - Read/write/manage files
+  8. Context Preservation - Maintain state between turns
+
+  The "Must-Have" List
+
+  Every AI agent framework needs:
+
+  - ✅ LLM Integration (API to Claude/GPT/etc.)
+  - ✅ Memory/Storage (remember past conversations)
+  - ✅ Tool System (execute actions beyond chat)
+  - ✅ Session Tracking (multi-turn conversations)
+  - ✅ Scheduling (delayed/recurring tasks)
+
+  Optional but common:
+  - Web search
+  - File management
+  - Multi-user support
+  - Event triggers
+Standard AI Agent Tools (Industry Common)                                                                                         
+                                                    
+  Core Tier (Nearly Universal)                                                                                                      
+                                                                                                                                    
+  1. Memory/Storage - Save, search, retrieve information                                                                            
+  2. Web Search - Current information lookup                                                                                        
+  3. Web Fetch - HTTP requests to APIs/URLs                                                                                         
+  4. File Operations - Read, write, list, delete files
+  5. Code Execution - Run code snippets (Python/JS/etc.)
+
+  Common Tier (Most Frameworks)
+
+  6. Calculator/Math - Precise calculations
+  7. Time/Date - Current time, scheduling
+  8. Command Execution - Shell commands (sandboxed)
+  9. Database Queries - Read/write to databases
+
+  Extended Tier (Advanced Frameworks)
+
+  10. Browser Automation - Navigate, click, screenshot
+  11. Image Generation - Create images from prompts
+  12. Image Analysis - Describe/analyze images
+  13. Email - Send/read emails
+  14. Notifications - Push alerts to users
+  15. Weather - Current conditions/forecasts
+
+  Your Library (@dottie/agent) Has:
+
+  ✅ Memory (6 tools)
+  ✅ Web (3 tools)
+  ✅ Files (6 tools)
+  ✅ Code execution (1 tool)
+  ✅ Browser (7 tools)
+  ✅ Images (3 tools)
+  ✅ Weather (1 tool)
+  ✅ Notifications (1 tool)
+  ✅ Messages (4 tools)
+  ✅ Goals (9 tools)
+  ✅ Triggers (4 tools)
+
+  45 total - well above baseline expectations.
+
+  Missing Common Tools (Consider Adding)
+
+  - Calculator - Math operations (LLMs are bad at precise math)
+  - Time/Date - Current time, timezone conversions
+  - Email - Send/read emails
+  - Database - Direct SQL/NoSQL queries
+
+  Minimal Viable Agent Toolkit
+
+  If starting from scratch, the absolute minimum:
+
+  1. Memory (save/search)
+  2. Web search
+  3. File read/write
+  4. Code execution
+
+  Everything else is optional depending on use case.
+
+
+Anthropic SDK
+  Built-in tools - Read files, run bash commands, edit code, search web, glob patterns. Zero setup needed.
+Context management - Automatic compaction, long-running sessions, context windows handled for you.
+Agent loop - Built-in gather → action → verify → repeat pattern.
+MCP integration - Connect to any MCP server for enterprise tools (Slack, GitHub, Drive, etc).
+Hooks - Intercept tool calls, modify behavior, add custom logic.
+Subagents - Spawn specialized agents for parallel work.
+Permissions - Fine-grained control over what agents can access/modify.
+Structured outputs - JSON schema support.
+
+
+xAI
+
+xai-sdk (Python/TypeScript) - standard client SDK
+Agent Tools API - server-side tools (web search, X search, code execution, MCP, file search)
+Agentic tool calling - Grok decides when to invoke tools autonomously

package/docs/protected-files.md

@@ -0,0 +1,59 @@
+Absolutely! Yes, you should definitely protect .ssh and similar system-level directories. Here's a critical list of system paths to exclude:                                                                                                                                  
+                                                              
+  Critical System Directories (NEVER SHARE)                                                                                                                                                                                                                                     
+                                                              
+  ~/.ssh/                    # SSH keys, known_hosts, config                                                                                                                                                                                                                    
+  ~/.aws/                    # AWS credentials                                                                                                                                                                                                                                  
+  ~/.config/                 # App configs (may contain tokens)                                                                                                                                                                                                                 
+  ~/.kube/                   # Kubernetes credentials
+  ~/.docker/                 # Docker credentials
+  ~/.gnupg/                  # GPG keys
+  ~/.password-store/         # Password manager data
+  ~/Library/Keychains/       # macOS keychain files
+  ~/Library/Application Support/*/
+
+
+  Shell & Environment
+
+  ~/.zshrc                   # May contain exported secrets
+  ~/.bashrc
+  ~/.bash_profile
+  ~/.zsh_history            # Command history (may leak secrets)
+  ~/.bash_history
+  ~/.netrc                  # Network credentials
+
+
+  API & Service Credentials
+
+  ~/.gitconfig              # May contain GitHub tokens
+  ~/.npmrc                  # NPM tokens
+  ~/.pypirc                 # PyPI credentials
+  ~/.gem/credentials        # RubyGems API keys
+  ~/.gradle/gradle.properties
+
+
+  Cloud & Infrastructure
+
+  ~/.azure/
+  ~/.gcloud/
+  ~/.terraform.d/
+  ~/.ansible/
+
+
+  Browser & Personal Data
+
+  ~/Library/Safari/
+  ~/Library/Cookies/
+  ~/Library/Application Support/Google/Chrome/
+  ~/Library/Application Support/Firefox/
+
+
+  Dottie-Specific (Your App)
+
+  ~/.dottie/logs/           # May contain user conversations
+  ~/.dottie/chat_history.json
+  ~/.dottie/*.db
+
+
+  Bottom line: Any path under ~ (home directory) that contains credentials, personal data, command history, or configuration files should be protected. The general rule is: never search/glob/grep from ~ or /Users/sd root — only within specific project directories.
+  ctrl+q to copy · 6 snippets

package/examples/sqlite-session-example.js

@@ -0,0 +1,69 @@
+/**
+ * SQLiteSessionStore Usage Example
+ *
+ * Demonstrates how to use SQLite as a session storage backend
+ * for the @dottie/agent library. Requires Node.js 22.5+.
+ */
+
+import { createAgent, SQLiteSessionStore, coreTools } from '@dottie/agent';
+
+// Initialize SQLite session store
+const sessionStore = new SQLiteSessionStore();
+await sessionStore.init('./sessions.db', {
+  // Optional: Fetch user preferences from your database
+  prefsFetcher: async (userId) => {
+    // Example: fetch from a user database
+    return {
+      agentName: 'Dottie',
+      agentPersonality: 'helpful and concise',
+    };
+  },
+  // Optional: Ensure user heartbeat for cron tasks
+  heartbeatEnsurer: async (userId) => {
+    // Example: update last_seen timestamp in user database
+    console.log(`User ${userId} active`);
+    return null;
+  },
+});
+
+// Create agent with SQLite session storage
+const agent = createAgent({
+  sessionStore,
+  providers: {
+    anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
+  },
+  tools: coreTools,
+});
+
+// Example 1: Create a new session
+const session = await agent.createSession('user-123', 'claude-sonnet-4-5', 'anthropic');
+console.log('Created session:', session.id);
+
+// Example 2: Chat with the agent
+for await (const event of agent.chat({
+  sessionId: session.id,
+  message: 'What can you help me with?',
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5',
+})) {
+  if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
+    process.stdout.write(event.delta.text);
+  }
+}
+console.log('\n');
+
+// Example 3: List all sessions for a user
+const sessions = await sessionStore.listSessions('user-123');
+console.log('User sessions:', sessions);
+
+// Example 4: Get or create default session
+const defaultSession = await sessionStore.getOrCreateDefaultSession('user-123');
+console.log('Default session:', defaultSession.id);
+
+// Example 5: Clear session history
+await sessionStore.clearSession(session.id);
+console.log('Session cleared');
+
+// Example 6: Delete a session
+await sessionStore.deleteSession(session.id, 'user-123');
+console.log('Session deleted');

package/index.js

@@ -0,0 +1,341 @@
+/**
+ * DotBot Agent Library
+ *
+ * Framework-agnostic AI agent system with tool execution, session management,
+ * and scheduled tasks.
+ */
+
+// Import tool arrays for use in createAgent()
+import {
+  coreTools,
+  memoryTools,
+  webTools,
+  codeTools,
+  fileTools,
+  messageTools,
+  imageTools,
+  weatherTools,
+  notifyTools,
+  createBrowserTools,
+  taskTools,
+  goalTools,
+  triggerTools,
+  jobTools,
+  cronTools,
+  eventTools,
+  appgenTools,
+} from './tools/index.js';
+
+// Export core abstractions
+export {
+  SessionStore,
+  SQLiteSessionStore,
+  MongoSessionStore,
+  MemorySessionStore,
+  defaultSystemPrompt,
+  CronStore,
+  MongoCronStore,
+  SQLiteCronStore,
+  parseInterval,
+  HEARTBEAT_INTERVAL_MS,
+  HEARTBEAT_PROMPT,
+  runWithConcurrency,
+  TaskStore,
+  MongoTaskStore,
+  SQLiteTaskStore,
+  // Backwards compatibility aliases
+  GoalStore,
+  MongoGoalStore,
+  SQLiteGoalStore,
+  TriggerStore,
+  MongoTriggerStore,
+  SQLiteTriggerStore,
+  SQLiteMemoryStore,
+  EventStore,
+  SQLiteEventStore,
+} from './storage/index.js';
+
+// Export tool system
+export {
+  createToolRegistry,
+  coreTools,
+  memoryTools,
+  webTools,
+  codeTools,
+  fileTools,
+  messageTools,
+  imageTools,
+  weatherTools,
+  notifyTools,
+  browserTools,
+  createBrowserTools,
+  taskTools,
+  goalTools,   // backwards compatibility alias
+  triggerTools,
+  jobTools,
+  cronTools,   // backwards compatibility alias
+  eventTools,
+  appgenTools,
+} from './tools/index.js';
+
+// Export provider configuration
+import { AI_PROVIDERS } from './utils/providers.js';
+export { AI_PROVIDERS };
+
+// Export agent loop (already well-abstracted)
+export { agentLoop } from './core/agent.js';
+
+// Export compaction utilities
+export { compactMessages, estimateTokens } from './core/compaction.js';
+
+// Export message normalization
+export { toStandardFormat, toProviderFormat, normalizeMessages } from './core/normalize.js';
+
+// Export event system
+export { validateEvent, normalizeStatsEvent } from './core/events.js';
+
+// Export unified initialization
+export { init } from './core/init.js';
+
+// Export handler factories for advanced use cases
+export { createCronHandler } from './core/cron_handler.js';
+export { createTriggerHandler } from './core/trigger_handler.js';
+
+/**
+ * Create an agent instance with configurable stores, providers, and tools
+ *
+ * @param {Object} options - Configuration options
+ * @param {SessionStore} options.sessionStore - Session storage backend
+ * @param {Object} options.providers - Provider API keys: { anthropic: { apiKey }, openai: { apiKey }, xai: { apiKey }, ollama: { baseUrl } }
+ * @param {Function} [options.systemPrompt] - System prompt builder: (agentName, agentPersonality, timestamp) => string
+ * @param {Array} [options.tools] - Tool definitions (defaults to coreTools)
+ * @param {CronStore} [options.cronStore] - Optional cron storage backend for scheduled tasks
+ * @param {TaskStore} [options.taskStore] - Optional task storage backend for multi-step autonomous execution
+ * @param {TriggerStore} [options.triggerStore] - Optional trigger storage backend for event-driven responses
+ * @param {SQLiteMemoryStore} [options.memoryStore] - Optional memory storage backend for long-term memory
+ * @param {EventStore} [options.eventStore] - Optional event storage backend for usage analytics
+ * @param {Function} [options.screenshotUrlPattern] - Screenshot URL pattern: (filename) => URL string
+ * @param {Object} [options.compaction] - Compaction settings: { enabled: true, ... }
+ * @returns {Object} Agent API
+ */
+export function createAgent({
+  sessionStore,
+  providers = {},
+  systemPrompt,
+  tools = coreTools,
+  cronStore = null,
+  taskStore = null,
+  triggerStore = null,
+  memoryStore = null,
+  eventStore = null,
+  screenshotUrlPattern = (filename) => `/screenshots/${filename}`,
+  compaction = { enabled: true },
+} = {}) {
+  if (!sessionStore) {
+    throw new Error('createAgent() requires a sessionStore (SessionStore instance)');
+  }
+
+  // If custom screenshotUrlPattern provided, rebuild browser tools
+  let finalTools = tools;
+  if (screenshotUrlPattern && tools === coreTools) {
+    // Replace default browser tools with customized ones
+    const customBrowserTools = createBrowserTools(screenshotUrlPattern);
+    finalTools = [
+      ...memoryTools,
+      ...webTools,
+      ...codeTools,
+      ...fileTools,
+      ...messageTools,
+      ...imageTools,
+      ...weatherTools,
+      ...notifyTools,
+      ...customBrowserTools,
+      ...taskTools,
+      ...triggerTools,
+      ...jobTools,
+      ...eventTools,
+      ...appgenTools,
+    ];
+  }
+
+  return {
+    /**
+     * Run agent chat loop with streaming
+     *
+     * @param {Object} params
+     * @param {string} params.sessionId - Session UUID
+     * @param {string} params.message - User message
+     * @param {string} params.provider - AI provider ID
+     * @param {string} params.model - Model name
+     * @param {AbortSignal} [params.signal] - Abort signal
+     * @param {Object} [params.context] - Tool execution context
+     * @returns {AsyncGenerator} SSE event stream
+     */
+    async* chat({ sessionId, message, provider, model, signal, context = {} }) {
+      // Get session
+      const session = await sessionStore.getSessionInternal(sessionId);
+      if (!session) throw new Error(`Session ${sessionId} not found`);
+
+      // Inject providers and stores into context
+      const enhancedContext = {
+        ...context,
+        providers,
+        cronStore,
+        taskStore,
+        triggerStore,
+        memoryStore,
+        eventStore,
+      };
+
+      // Resolve string provider ID to a full provider config object.
+      // agentLoop expects a provider config (with apiUrl, headers, etc.),
+      // not a string ID. Inject the API key from the providers config.
+      let resolvedProvider = provider;
+      if (typeof provider === 'string') {
+        const base = AI_PROVIDERS[provider];
+        if (base) {
+          const apiKey = providers[provider]?.apiKey;
+          resolvedProvider = apiKey
+            ? { ...base, headers: () => base.headers(apiKey) }
+            : base;
+        }
+      }
+
+      // Run agent loop
+      const generator = agentLoop({
+        session,
+        userMessage: message,
+        tools: finalTools,
+        provider: resolvedProvider,
+        model,
+        signal,
+        context: enhancedContext,
+        compaction: { ...compaction, providers },
+      });
+
+      // Stream events and save session on completion
+      let finalMessages = session.messages;
+      let finalModel = model;
+      let finalProvider = provider;
+
+      for await (const event of generator) {
+        yield event;
+        if (event.type === 'done' && event.messages) {
+          finalMessages = event.messages;
+          if (event.model) finalModel = event.model;
+          if (event.provider) finalProvider = event.provider;
+        }
+      }
+
+      // Save session after loop completes
+      await sessionStore.saveSession(sessionId, finalMessages, finalModel, finalProvider);
+    },
+
+    /**
+     * Create a new session
+     *
+     * @param {string} owner - User ID
+     * @param {string} [model] - Initial model
+     * @param {string} [provider] - Initial provider
+     * @returns {Promise<Object>} Session document
+     */
+    async createSession(owner, model, provider) {
+      return await sessionStore.createSession(owner, model, provider);
+    },
+
+    /**
+     * Get a session by ID
+     *
+     * @param {string} sessionId - Session UUID
+     * @param {string} owner - User ID
+     * @returns {Promise<Object|null>} Session document
+     */
+    async getSession(sessionId, owner) {
+      return await sessionStore.getSession(sessionId, owner);
+    },
+
+    /**
+     * List sessions for a user
+     *
+     * @param {string} owner - User ID
+     * @returns {Promise<Array>} Session summaries
+     */
+    async listSessions(owner) {
+      return await sessionStore.listSessions(owner);
+    },
+
+    /**
+     * Delete a session
+     *
+     * @param {string} sessionId - Session UUID
+     * @param {string} owner - User ID
+     * @returns {Promise<any>} Delete result
+     */
+    async deleteSession(sessionId, owner) {
+      return await sessionStore.deleteSession(sessionId, owner);
+    },
+
+    /**
+     * Clear session conversation history
+     *
+     * @param {string} sessionId - Session UUID
+     */
+    async clearSession(sessionId) {
+      await sessionStore.clearSession(sessionId);
+    },
+
+    /**
+     * Get registered tools
+     *
+     * @returns {Array} Tool definitions
+     */
+    getTools() {
+      return finalTools;
+    },
+
+    /**
+     * Get cron store (if configured)
+     *
+     * @returns {CronStore|null} Cron store instance
+     */
+    getCronStore() {
+      return cronStore;
+    },
+
+    /**
+     * Get task store (if configured)
+     *
+     * @returns {TaskStore|null} Task store instance
+     */
+    getTaskStore() {
+      return taskStore;
+    },
+
+    /**
+     * Get trigger store (if configured)
+     *
+     * @returns {TriggerStore|null} Trigger store instance
+     */
+    getTriggerStore() {
+      return triggerStore;
+    },
+
+    /**
+     * Get memory store (if configured)
+     *
+     * @returns {SQLiteMemoryStore|null} Memory store instance
+     */
+    getMemoryStore() {
+      return memoryStore;
+    },
+
+    /**
+     * Get event store (if configured)
+     *
+     * @returns {EventStore|null} Event store instance
+     */
+    getEventStore() {
+      return eventStore;
+    },
+  };
+}