@stevederico/dotbot 0.16.0

package/observer/index.js

@@ -0,0 +1,164 @@
+/**
+ * Browser Observer — in-memory snapshot store and agent tool.
+ *
+ * The frontend pushes structured browser-state snapshots via POST /api/agent/observer.
+ * The agent reads the latest snapshot via the `browser_observe` tool to understand
+ * what the user is currently doing in the browser.
+ */
+
+const SNAPSHOT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/** @type {Map<string, Object>} userID → { ...snapshot, receivedAt } */
+const snapshots = new Map();
+
+/**
+ * Store the latest browser snapshot for a user.
+ *
+ * @param {string} userID - Authenticated user ID
+ * @param {Object} snapshot - Structured browser state from the frontend
+ */
+export function storeSnapshot(userID, snapshot) {
+  snapshots.set(userID, { ...snapshot, receivedAt: Date.now() });
+}
+
+/**
+ * Retrieve the latest snapshot for a user, or null if stale/missing.
+ *
+ * @param {string} userID - Authenticated user ID
+ * @returns {Object|null} Snapshot with receivedAt, or null
+ */
+export function getSnapshot(userID) {
+  const entry = snapshots.get(userID);
+  if (!entry) return null;
+  if (Date.now() - entry.receivedAt > SNAPSHOT_TTL_MS) {
+    snapshots.delete(userID);
+    return null;
+  }
+  return entry;
+}
+
+/**
+ * Remove a user's snapshot (cleanup on logout, etc.).
+ *
+ * @param {string} userID - Authenticated user ID
+ */
+export function clearSnapshot(userID) {
+  snapshots.delete(userID);
+}
+
+/**
+ * Format a snapshot into plain-text for LLM consumption.
+ *
+ * @param {Object} snap - Snapshot object from the store
+ * @param {boolean} includeActions - Whether to include recent actions
+ * @returns {string} Human-readable state description
+ */
+function formatSnapshot(snap, includeActions = true) {
+  const ageSec = Math.round((Date.now() - snap.timestamp) / 1000);
+  const lines = [];
+
+  lines.push(`Browser state (${ageSec}s ago):`);
+  lines.push('');
+
+  // Windows
+  if (snap.windows && snap.windows.length > 0) {
+    lines.push(`Open apps (${snap.windowCount || snap.windows.length}):`);
+    for (const w of snap.windows) {
+      const focus = w.isFocused ? ' [focused]' : '';
+      lines.push(`  - ${w.app}${w.title ? ': ' + w.title : ''}${focus}`);
+    }
+  } else {
+    lines.push('No apps open.');
+  }
+
+  if (snap.focusedApp) {
+    lines.push(`Focused: ${snap.focusedApp}`);
+  }
+
+  // Docked panel
+  if (snap.isDottieDocked) {
+    lines.push('DotBot panel: docked (sidebar)');
+  }
+
+  // Input bar
+  if (snap.isInputElevated) {
+    lines.push(`Input bar: elevated${snap.inputValue ? ' — "' + snap.inputValue + '"' : ''}`);
+  }
+
+  // Voice
+  if (snap.voiceState && snap.voiceState !== 'idle') {
+    lines.push(`Voice: ${snap.voiceState}`);
+  }
+
+  // Streaming
+  if (snap.isStreaming) {
+    lines.push('Agent: streaming response');
+  }
+
+  // Last tool call
+  if (snap.lastToolCall) {
+    const tc = snap.lastToolCall;
+    const tcAge = Math.round((Date.now() - tc.timestamp) / 1000);
+    lines.push(`Last tool: ${tc.name} (${tc.status}, ${tcAge}s ago)`);
+  }
+
+  // Messages
+  if (snap.messageCount > 0) {
+    lines.push(`Messages in session: ${snap.messageCount}`);
+  }
+
+  // Provider/model
+  if (snap.currentProvider || snap.currentModel) {
+    lines.push(`Model: ${snap.currentProvider || '?'}/${snap.currentModel || '?'}`);
+  }
+
+  // Layout + dock
+  lines.push(`Layout: ${snap.layoutMode || 'desktop'}`);
+  if (snap.dockApps && snap.dockApps.length > 0) {
+    lines.push(`Dock: ${snap.dockApps.join(', ')}`);
+  }
+
+  // Viewport
+  if (snap.viewport) {
+    lines.push(`Viewport: ${snap.viewport.width}x${snap.viewport.height}`);
+  }
+
+  // Recent actions
+  if (includeActions && snap.recentActions && snap.recentActions.length > 0) {
+    lines.push('');
+    lines.push('Recent actions:');
+    for (const a of snap.recentActions) {
+      const aAge = Math.round((Date.now() - a.timestamp) / 1000);
+      const detail = a.app ? ` (${a.app})` : a.tool ? ` (${a.tool})` : '';
+      lines.push(`  - ${a.action}${detail} — ${aAge}s ago`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/** Agent tool definitions for the browser observer. */
+export const observerTools = [
+  {
+    name: 'browser_observe',
+    description:
+      "See what the user is currently doing in Dottie OS — open apps, focused window, voice state, recent actions. " +
+      "Call this when you need context about the user's current activity, or when they reference 'this', 'what I'm looking at', or 'current'.",
+    parameters: {
+      type: 'object',
+      properties: {
+        include_actions: {
+          type: 'boolean',
+          description: 'Include recent user actions (default true)',
+        },
+      },
+    },
+    execute: async (input, signal, context) => {
+      if (!context?.userID) return 'Error: user context not available';
+      const snap = getSnapshot(context.userID);
+      if (!snap) return 'No browser state available. The user may have the tab in the background or just opened the page.';
+      const includeActions = input.include_actions !== false;
+      return formatSnapshot(snap, includeActions);
+    },
+  },
+];

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@stevederico/dotbot",
+  "version": "0.16.0",
+  "description": "AI agent CLI and library for Node.js — streaming, multi-provider, tool execution, autonomous tasks",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "dotbot": "./bin/dotbot.js"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./core/*": "./core/*.js",
+    "./tools/*": "./tools/*.js",
+    "./storage/*": "./storage/*.js",
+    "./utils/*": "./utils/*.js"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "anthropic",
+    "openai",
+    "xai",
+    "chatbot",
+    "autonomous",
+    "tasks",
+    "triggers"
+  ],
+  "author": "Steve Derico",
+  "license": "MIT",
+  "peerDependencies": {
+    "mongodb": "^6.0.0"
+  },
+  "dependencies": {
+    "playwright": "^1.58.2"
+  },
+  "devDependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stevederico/dotbot.git"
+  }
+}

package/storage/CronStore.js

@@ -0,0 +1,145 @@
+/**
+ * CronStore Interface
+ *
+ * Abstract interface for scheduled task storage. Implementations must provide
+ * all methods defined here.
+ */
+export class CronStore {
+  /**
+   * Initialize the cron store
+   *
+   * @param {Object} options - Store-specific initialization options
+   * @param {Function} options.onTaskFire - Callback when a task fires: (task) => Promise<void>
+   */
+  async init(options = {}) {
+    throw new Error('CronStore.init() must be implemented');
+  }
+
+  /**
+   * Stop the cron polling loop
+   */
+  stop() {
+    throw new Error('CronStore.stop() must be implemented');
+  }
+
+  /**
+   * Create a scheduled task
+   *
+   * @param {Object} params
+   * @param {string} params.name - Short task name
+   * @param {string} params.prompt - Message to inject when task fires
+   * @param {string} [params.sessionId] - Session to inject into
+   * @param {string} [params.userId] - Owner user ID
+   * @param {string} params.runAt - ISO 8601 datetime for first run
+   * @param {number} [params.intervalMs] - Repeat interval in milliseconds
+   * @param {boolean} [params.recurring] - Whether task repeats
+   * @param {string} [params.taskId] - Associated task ID
+   * @returns {Promise<Object>} Created task document
+   */
+  async createTask({ name, prompt, sessionId, userId, runAt, intervalMs, recurring, taskId }) {
+    throw new Error('CronStore.createTask() must be implemented');
+  }
+
+  /**
+   * List tasks for a session
+   *
+   * @param {string} [sessionId] - Session ID to filter by
+   * @returns {Promise<Array>} Task list sorted by next run time
+   */
+  async listTasks(sessionId) {
+    throw new Error('CronStore.listTasks() must be implemented');
+  }
+
+  /**
+   * List tasks for multiple session IDs
+   *
+   * @param {string[]} sessionIds - Array of session IDs
+   * @param {string} [userId] - User ID to filter by
+   * @returns {Promise<Array>} Task list sorted by next run time
+   */
+  async listTasksBySessionIds(sessionIds, userId) {
+    throw new Error('CronStore.listTasksBySessionIds() must be implemented');
+  }
+
+  /**
+   * Get a task by ID
+   *
+   * @param {string} id - Task document ID
+   * @returns {Promise<Object|null>} Task document or null
+   */
+  async getTask(id) {
+    throw new Error('CronStore.getTask() must be implemented');
+  }
+
+  /**
+   * Delete a task by its ID
+   *
+   * @param {string} id - Task document ID
+   * @returns {Promise<any>} Delete result
+   */
+  async deleteTask(id) {
+    throw new Error('CronStore.deleteTask() must be implemented');
+  }
+
+  /**
+   * Toggle a task's enabled/disabled state
+   *
+   * @param {string} id - Task document ID
+   * @param {boolean} enabled - Whether the task should be enabled
+   * @returns {Promise<any>} Update result
+   */
+  async toggleTask(id, enabled) {
+    throw new Error('CronStore.toggleTask() must be implemented');
+  }
+
+  /**
+   * Update a task's details
+   *
+   * @param {string} id - Task document ID
+   * @param {Object} updates - Fields to update
+   * @returns {Promise<any>} Update result
+   */
+  async updateTask(id, updates) {
+    throw new Error('CronStore.updateTask() must be implemented');
+  }
+
+  /**
+   * Ensure a single recurring heartbeat task exists for a user
+   *
+   * @param {string} userId - User ID
+   * @returns {Promise<Object|null>} Created task or null if already exists
+   */
+  async ensureHeartbeat(userId) {
+    throw new Error('CronStore.ensureHeartbeat() must be implemented');
+  }
+
+  /**
+   * Get heartbeat status for a user
+   *
+   * @param {string} userId - User ID
+   * @returns {Promise<Object|null>} Heartbeat task or null
+   */
+  async getHeartbeatStatus(userId) {
+    throw new Error('CronStore.getHeartbeatStatus() must be implemented');
+  }
+
+  /**
+   * Reset/update an existing heartbeat to use the latest prompt
+   *
+   * @param {string} userId - User ID
+   * @returns {Promise<Object|null>} New heartbeat task or null
+   */
+  async resetHeartbeat(userId) {
+    throw new Error('CronStore.resetHeartbeat() must be implemented');
+  }
+
+  /**
+   * Manually trigger the heartbeat task immediately
+   *
+   * @param {string} userId - User ID
+   * @returns {Promise<boolean>} True if heartbeat was fired
+   */
+  async triggerHeartbeatNow(userId) {
+    throw new Error('CronStore.triggerHeartbeatNow() must be implemented');
+  }
+}

package/storage/EventStore.js

@@ -0,0 +1,71 @@
+/**
+ * EventStore Interface
+ *
+ * Abstract interface for event/analytics storage. Implementations must provide
+ * all methods defined here.
+ */
+export class EventStore {
+  /**
+   * Initialize the event store
+   *
+   * @param {Object} db - Database instance (implementation-specific)
+   * @param {Object} options - Store-specific initialization options
+   */
+  async init(db, options = {}) {
+    throw new Error('EventStore.init() must be implemented');
+  }
+
+  /**
+   * Log an event
+   *
+   * @param {Object} params
+   * @param {string} params.userId - User ID
+   * @param {string} params.type - Event type (message_sent, message_received, tool_call, task_created, task_completed, trigger_fired)
+   * @param {Object} [params.data] - Event-specific data (e.g., { tool: 'web_search' })
+   * @param {number} [params.timestamp] - Unix ms timestamp (defaults to now)
+   * @returns {Promise<Object>} Created event document
+   */
+  async logEvent({ userId, type, data, timestamp }) {
+    throw new Error('EventStore.logEvent() must be implemented');
+  }
+
+  /**
+   * Query events with filters
+   *
+   * @param {Object} params
+   * @param {string} params.userId - User ID
+   * @param {string} [params.type] - Filter by event type
+   * @param {string} [params.startDate] - ISO date start (inclusive)
+   * @param {string} [params.endDate] - ISO date end (inclusive)
+   * @param {number} [params.limit=100] - Max results
+   * @returns {Promise<Array>} Matching events
+   */
+  async query({ userId, type, startDate, endDate, limit }) {
+    throw new Error('EventStore.query() must be implemented');
+  }
+
+  /**
+   * Get aggregated usage statistics
+   *
+   * @param {Object} params
+   * @param {string} params.userId - User ID
+   * @param {string} [params.startDate] - ISO date start
+   * @param {string} [params.endDate] - ISO date end
+   * @param {string} [params.groupBy='type'] - Group by: type, day, week, month
+   * @returns {Promise<Object>} Summary statistics
+   */
+  async summary({ userId, startDate, endDate, groupBy }) {
+    throw new Error('EventStore.summary() must be implemented');
+  }
+
+  /**
+   * Delete events older than a given date
+   *
+   * @param {string} userId - User ID
+   * @param {string} beforeDate - ISO date cutoff
+   * @returns {Promise<Object>} Delete result with count
+   */
+  async deleteOldEvents(userId, beforeDate) {
+    throw new Error('EventStore.deleteOldEvents() must be implemented');
+  }
+}

package/storage/MemoryStore.js

@@ -0,0 +1,175 @@
+import crypto from 'crypto';
+import { SessionStore } from './SessionStore.js';
+import { defaultSystemPrompt } from './MongoAdapter.js';
+import { toStandardFormat } from '../core/normalize.js';
+
+/**
+ * In-memory SessionStore implementation for testing
+ */
+export class MemorySessionStore extends SessionStore {
+  constructor() {
+    super();
+    this.sessions = new Map();
+    this.prefsFetcher = null;
+    this.systemPromptBuilder = defaultSystemPrompt;
+    this.heartbeatEnsurer = null;
+  }
+
+  async init(options = {}) {
+    this.prefsFetcher = options.prefsFetcher || null;
+    this.systemPromptBuilder = options.systemPromptBuilder || defaultSystemPrompt;
+    this.heartbeatEnsurer = options.heartbeatEnsurer || null;
+    console.log('[sessions] initialized with in-memory store');
+  }
+
+  async buildSystemPrompt(owner) {
+    const prefs = this.prefsFetcher ? await this.prefsFetcher(owner) : {};
+    return this.systemPromptBuilder(prefs);
+  }
+
+  async createSession(owner, model = 'gpt-oss:20b', provider = 'ollama') {
+    const session = {
+      id: crypto.randomUUID(),
+      owner,
+      title: '',
+      messages: [{ role: 'system', content: await this.buildSystemPrompt(owner) }],
+      model,
+      provider,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    this.sessions.set(session.id, session);
+    return session;
+  }
+
+  async getOrCreateDefaultSession(owner) {
+    // Find most recent session for this owner
+    const userSessions = Array.from(this.sessions.values())
+      .filter(s => s.owner === owner)
+      .sort((a, b) => b.updatedAt - a.updatedAt);
+
+    let session = userSessions[0];
+    if (!session) {
+      session = await this.createSession(owner);
+    } else {
+      // Refresh system prompt timestamp
+      session.messages[0] = { role: 'system', content: await this.buildSystemPrompt(owner) };
+    }
+    if (this.heartbeatEnsurer) {
+      this.heartbeatEnsurer(owner).catch((err) => {
+        console.error(`[session] failed to ensure heartbeat for ${owner}:`, err.message);
+      });
+    }
+    return session;
+  }
+
+  async getSession(sessionId, owner) {
+    const session = this.sessions.get(sessionId);
+    if (!session || session.owner !== owner) return null;
+
+    // Refresh system prompt timestamp
+    session.messages[0] = { role: 'system', content: await this.buildSystemPrompt(owner) };
+    return session;
+  }
+
+  async getSessionInternal(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+
+    session.messages[0] = { role: 'system', content: await this.buildSystemPrompt(session.owner) };
+    return session;
+  }
+
+  /**
+   * Save session with normalized messages.
+   * Converts any provider-specific message formats to standard format before persisting.
+   *
+   * @param {string} sessionId - Session UUID
+   * @param {Array} messages - Messages (provider-specific or standard format)
+   * @param {string} model - Model identifier
+   * @param {string} [provider] - Provider name
+   */
+  async saveSession(sessionId, messages, model, provider) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error(`Session ${sessionId} not found`);
+
+    session.messages = toStandardFormat(messages);
+    session.model = model;
+    session.updatedAt = new Date();
+    if (provider) session.provider = provider;
+
+    // Auto-populate title from first user message if empty
+    if (!session.title) {
+      const firstUserMsg = messages.find((m) => m.role === 'user');
+      if (firstUserMsg) {
+        session.title = firstUserMsg.content.slice(0, 60);
+      }
+    }
+  }
+
+  /**
+   * Add a message to a session, normalizing to standard format before saving.
+   *
+   * @param {string} sessionId - Session UUID
+   * @param {Object} message - Message object (any provider format)
+   * @returns {Promise<Object>} Updated session
+   */
+  async addMessage(sessionId, message) {
+    const session = await this.getSessionInternal(sessionId);
+    if (!session) throw new Error(`Session ${sessionId} not found`);
+    if (!message._ts) message._ts = Date.now();
+    const normalized = toStandardFormat([message]);
+    session.messages.push(...normalized);
+    await this.saveSession(sessionId, session.messages, session.model);
+    return session;
+  }
+
+  async setModel(sessionId, model) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.model = model;
+      session.updatedAt = new Date();
+    }
+  }
+
+  async setProvider(sessionId, provider) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.provider = provider;
+      session.updatedAt = new Date();
+    }
+  }
+
+  async clearSession(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.messages = [{ role: 'system', content: await this.buildSystemPrompt(session.owner) }];
+      session.updatedAt = new Date();
+    }
+  }
+
+  async listSessions(owner) {
+    return Array.from(this.sessions.values())
+      .filter(s => s.owner === owner)
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .slice(0, 50)
+      .map(s => ({
+        id: s.id,
+        title: s.title || '',
+        model: s.model,
+        provider: s.provider || 'ollama',
+        createdAt: s.createdAt,
+        updatedAt: s.updatedAt,
+        messageCount: s.messages.length,
+      }));
+  }
+
+  async deleteSession(sessionId, owner) {
+    const session = this.sessions.get(sessionId);
+    if (session && session.owner === owner) {
+      this.sessions.delete(sessionId);
+      return { deletedCount: 1 };
+    }
+    return { deletedCount: 0 };
+  }
+}