@stevederico/dotbot 0.28.0 → 0.31.0

package/core/cron_handler.js

@@ -1,9 +1,8 @@
 /**
  * Cron task handler for dotbot.
  *
- * Extracted from dottie-os server.js to provide a reusable cron task executor
- * that handles session resolution, stale user gates, task injection, and
- * notification hooks.
+ * Reusable cron task executor that handles session resolution, stale user
+ * gates, task injection, and notification hooks.
  */
 
 import { compactMessages } from './compaction.js';
@@ -18,6 +17,7 @@ import { compactMessages } from './compaction.js';
  * @param {Object} options.memoryStore - Memory store instance (optional)
  * @param {Object} options.providers - Provider API keys for compaction
  * @param {number} [options.staleThresholdMs=86400000] - Skip heartbeat if user idle longer than this (default: 24h)
+ * @param {string} [options.notificationTitle='Assistant'] - Title used when dispatching notifications via hooks.onNotification
  * @param {Object} [options.hooks] - Host-specific hooks
  * @param {Function} [options.hooks.onNotification] - async (userId, { title, body, type }) => void
  * @param {Function} [options.hooks.taskFetcher] - async (userId, taskId) => task object
@@ -31,6 +31,7 @@ export function createCronHandler({
   memoryStore,
   providers = {},
   staleThresholdMs = 24 * 60 * 60 * 1000,
+  notificationTitle = 'Assistant',
   hooks = {},
 }) {
   // Agent reference - will be set after init() creates the agent
@@ -139,7 +140,7 @@ export function createCronHandler({
     if (trimmed && trimmed.length > 10 && updatedSession.owner && hooks.onNotification) {
       try {
         await hooks.onNotification(updatedSession.owner, {
-          title: 'Dottie',
+          title: notificationTitle,
           body: trimmed.slice(0, 500),
           type: task.name === 'heartbeat' ? 'heartbeat' : 'cron',
         });
@@ -224,33 +225,43 @@ export function createCronHandler({
         tasks = await taskStore.findTasks(session.owner, { status: ['pending', 'in_progress'] });
       }
 
-      if (tasks.length > 0) {
-        // Check if any task is in auto mode with pending steps
-        const autoTask = tasks.find(t => t.mode === 'auto' && t.steps?.some(s => !s.done));
-        if (autoTask) {
-          const doneCount = autoTask.steps.filter(s => s.done).length;
-          const nextStep = autoTask.steps.find(s => !s.done);
-          taskContent = `[Heartbeat] Auto-mode task "${autoTask.description}" has pending steps (${doneCount}/${autoTask.steps.length} done). Call task_work with task_id "${autoTask._id || autoTask.id}" to execute: "${nextStep.text}"`;
-        } else {
-          // List all active tasks
-          const lines = tasks.map(t => {
-            let line = `• [${t.priority}] ${t.description}`;
-            if (t.mode) line += ` [${t.mode}]`;
-            if (t.deadline) line += ` (due: ${t.deadline})`;
-            if (t.steps && t.steps.length > 0) {
-              const done = t.steps.filter(s => s.done).length;
-              line += ` (${done}/${t.steps.length} steps)`;
-              for (const step of t.steps) {
-                line += `\n  ${step.done ? '[x]' : '[ ]'} ${step.text}`;
-              }
+      // Skip the LLM call entirely when there's nothing to discuss. A heartbeat
+      // with no active tasks is a waste of tokens on every provider (and is
+      // especially expensive on cloud providers that charge per call). The
+      // caller at handleTaskFire() treats a null return as "skip this tick".
+      if (tasks.length === 0) {
+        console.log(`[cron] heartbeat for ${session.owner}: no active tasks, skipping AI call`);
+        return null;
+      }
+
+      // Check if any task is in auto mode with pending steps
+      const autoTask = tasks.find(t => t.mode === 'auto' && t.steps?.some(s => !s.done));
+      if (autoTask) {
+        const doneCount = autoTask.steps.filter(s => s.done).length;
+        const nextStep = autoTask.steps.find(s => !s.done);
+        taskContent = `[Heartbeat] Auto-mode task "${autoTask.description}" has pending steps (${doneCount}/${autoTask.steps.length} done). Call task_work with task_id "${autoTask._id || autoTask.id}" to execute: "${nextStep.text}"`;
+      } else {
+        // List all active tasks
+        const lines = tasks.map(t => {
+          let line = `• [${t.priority}] ${t.description}`;
+          if (t.mode) line += ` [${t.mode}]`;
+          if (t.deadline) line += ` (due: ${t.deadline})`;
+          if (t.steps && t.steps.length > 0) {
+            const done = t.steps.filter(s => s.done).length;
+            line += ` (${done}/${t.steps.length} steps)`;
+            for (const step of t.steps) {
+              line += `\n  ${step.done ? '[x]' : '[ ]'} ${step.text}`;
             }
-            return line;
-          });
-          taskContent += `\n\nActive tasks:\n${lines.join('\n')}`;
-        }
+          }
+          return line;
+        });
+        taskContent += `\n\nActive tasks:\n${lines.join('\n')}`;
       }
     } catch (err) {
+      // Fail closed: if we can't fetch tasks, skip this heartbeat rather
+      // than call the LLM with a meaningless default prompt.
       console.error('[cron] failed to fetch tasks for heartbeat:', err.message);
+      return null;
     }
 
     return taskContent;

package/core/init.js

@@ -25,6 +25,7 @@ import { createTriggerHandler } from './trigger_handler.js';
  * @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 {string} [options.notificationTitle='Assistant'] - Title used when cron/trigger handlers dispatch notifications
  * @param {Function} [options.systemPrompt] - System prompt builder function
  * @param {Function} [options.screenshotUrlPattern] - Screenshot URL pattern function
  * @param {Object} [options.compaction] - Compaction settings
@@ -42,6 +43,7 @@ export async function init({
   providers = {},
   tools = coreTools,
   staleThresholdMs = 24 * 60 * 60 * 1000,
+  notificationTitle = 'Assistant',
   systemPrompt,
   screenshotUrlPattern,
   compaction = { enabled: true },
@@ -68,7 +70,8 @@ export async function init({
     memory: memoryStore,
   };
 
-  // For stores-only mode (e.g., dottie-desktop), skip session/cron/agent setup
+  // For stores-only mode (host manages sessions/cron/agent itself),
+  // skip session/cron/agent setup
   if (storesOnly) {
     return {
       stores,
@@ -101,6 +104,7 @@ export async function init({
     memoryStore,
     providers,
     staleThresholdMs,
+    notificationTitle,
     hooks,
   });
 
@@ -134,6 +138,7 @@ export async function init({
     triggerStore,
     memoryStore,
     providers,
+    notificationTitle,
     hooks,
   });
 

package/core/trigger_handler.js

@@ -1,8 +1,8 @@
 /**
  * Trigger handler for dotbot.
  *
- * Extracted from dottie-os server.js to provide a reusable trigger executor
- * that handles event matching, firing, and notification hooks.
+ * Reusable trigger executor that handles event matching, firing, and
+ * notification hooks.
  */
 
 import { compactMessages } from './compaction.js';
@@ -16,6 +16,7 @@ import { compactMessages } from './compaction.js';
  * @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 {string} [options.notificationTitle='Assistant'] - Title used when dispatching notifications via hooks.onNotification
  * @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>
@@ -26,6 +27,7 @@ export function createTriggerHandler({
   triggerStore,
   memoryStore,
   providers = {},
+  notificationTitle = 'Assistant',
   hooks = {},
 }) {
   /**
@@ -133,7 +135,7 @@ export function createTriggerHandler({
     if (trimmed && trimmed.length > 10 && updatedSession.owner && hooks.onNotification) {
       try {
         await hooks.onNotification(updatedSession.owner, {
-          title: 'Dottie',
+          title: notificationTitle,
           body: trimmed.slice(0, 500),
           type: 'trigger',
         });

package/docs/core.md

@@ -50,7 +50,7 @@ Standard AI Agent Tools (Industry Common)
   14. Notifications - Push alerts to users
   15. Weather - Current conditions/forecasts
 
-  Your Library (@dottie/agent) Has:
+  dotbot Has:
 
   ✅ Memory (6 tools)
   ✅ Web (3 tools)

package/docs/protected-files.md

@@ -48,12 +48,12 @@ Absolutely! Yes, you should definitely protect .ssh and similar system-level dir
   ~/Library/Application Support/Firefox/
 
 
-  Dottie-Specific (Your App)
+  Host-App Data (Example)
 
-  ~/.dottie/logs/           # May contain user conversations
-  ~/.dottie/chat_history.json
-  ~/.dottie/*.db
+  ~/.myapp/logs/           # May contain user conversations
+  ~/.myapp/chat_history.json
+  ~/.myapp/*.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.
+  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 the home directory root — only within specific project directories.
   ctrl+q to copy · 6 snippets

package/index.js

@@ -18,10 +18,8 @@ import {
   notifyTools,
   createBrowserTools,
   taskTools,
-  goalTools,
   triggerTools,
   jobTools,
-  cronTools,
   eventTools,
   appgenTools,
 } from './tools/index.js';
@@ -40,9 +38,6 @@ export {
   runWithConcurrency,
   TaskStore,
   SQLiteTaskStore,
-  // Backwards compatibility aliases
-  GoalStore,
-  SQLiteGoalStore,
   TriggerStore,
   SQLiteTriggerStore,
   SQLiteMemoryStore,
@@ -65,10 +60,8 @@ export {
   browserTools,
   createBrowserTools,
   taskTools,
-  goalTools,   // backwards compatibility alias
   triggerTools,
   jobTools,
-  cronTools,   // backwards compatibility alias
   eventTools,
   appgenTools,
 } from './tools/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevederico/dotbot",
-  "version": "0.28.0",
+  "version": "0.31.0",
   "description": "AI agent CLI and library for Node.js — streaming, multi-provider, tool execution, autonomous tasks",
   "type": "module",
   "main": "index.js",

package/storage/SQLiteAdapter.js

@@ -11,7 +11,7 @@ import { toStandardFormat } from '../core/normalize.js';
  * @param {string} options.agentPersonality - Personality description
  * @returns {string} System prompt
  */
-export function defaultSystemPrompt({ agentName = 'Dottie', agentPersonality = '' } = {}) {
+export function defaultSystemPrompt({ agentName = 'Assistant', agentPersonality = '' } = {}) {
   const now = new Date().toISOString();
   return `You are a helpful personal AI assistant called ${agentName}.${agentPersonality ? `\nYour personality and tone: ${agentPersonality}. Embody this in all responses.` : ''}
 You have access to tools for searching the web, reading/writing files, fetching URLs, running code, long-term memory, and scheduled tasks.

package/storage/SQLiteCronAdapter.js

@@ -220,16 +220,7 @@ export class SQLiteCronStore extends CronStore {
       "SELECT * FROM cron_tasks WHERE session_id = ? AND name != 'heartbeat' ORDER BY next_run_at ASC"
     ).all(sessionId || 'default');
 
-    return rows.map(r => ({
-      id: r.id,
-      name: r.name,
-      prompt: r.prompt,
-      nextRunAt: new Date(r.next_run_at),
-      recurring: !!r.recurring,
-      intervalMs: r.interval_ms,
-      enabled: !!r.enabled,
-      lastRunAt: r.last_run_at ? new Date(r.last_run_at) : null,
-    }));
+    return rows.map(r => this._rowToTask(r));
   }
 
   /**
@@ -257,18 +248,7 @@ export class SQLiteCronStore extends CronStore {
 
     const rows = this.db.prepare(query).all(...params);
 
-    return rows.map(r => ({
-      id: r.id,
-      name: r.name,
-      prompt: r.prompt,
-      sessionId: r.session_id,
-      nextRunAt: new Date(r.next_run_at),
-      recurring: !!r.recurring,
-      intervalMs: r.interval_ms,
-      enabled: !!r.enabled,
-      lastRunAt: r.last_run_at ? new Date(r.last_run_at) : null,
-      createdAt: new Date(r.created_at),
-    }));
+    return rows.map(r => this._rowToTask(r));
   }
 
   /**
@@ -374,53 +354,6 @@ export class SQLiteCronStore extends CronStore {
     return null;
   }
 
-  /**
-   * Ensure a Morning Brief job exists for the user (disabled by default).
-   * Creates a daily recurring job at 8:00 AM if not present.
-   *
-   * @param {string} userId - User ID
-   * @returns {Promise<Object|null>} Created task or null if already exists
-   */
-  async ensureMorningBrief(userId) {
-    if (!this.db || !userId) return null;
-
-    // Check if Morning Brief already exists for this user
-    const existing = this.db.prepare(
-      `SELECT id FROM cron_tasks WHERE user_id = ? AND name = 'Morning Brief' LIMIT 1`
-    ).get(userId);
-    if (existing) return null;
-
-    const DAY_MS = 24 * 60 * 60 * 1000;
-    const MORNING_BRIEF_PROMPT = `Good morning! Give me a brief summary to start my day:
-1. What's on my calendar today?
-2. Any important reminders or tasks due?
-3. A quick weather update for my location.
-Keep it concise and actionable.`;
-
-    // Calculate next 8:00 AM
-    const now = new Date();
-    const today8AM = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 8, 0, 0, 0);
-    const nextRun = now.getTime() < today8AM.getTime()
-      ? today8AM.getTime()
-      : today8AM.getTime() + DAY_MS;
-
-    const id = crypto.randomUUID();
-    const nowMs = Date.now();
-
-    const result = this.db.prepare(`
-      INSERT OR IGNORE INTO cron_tasks (id, name, prompt, session_id, user_id, next_run_at, interval_ms, recurring, enabled, created_at, last_run_at)
-      VALUES (?, 'Morning Brief', ?, 'default', ?, ?, ?, 1, 0, ?, NULL)
-    `).run(id, MORNING_BRIEF_PROMPT, userId, nextRun, DAY_MS, nowMs);
-
-    if (result.changes > 0) {
-      const runTime = new Date(nextRun);
-      console.log(`[cron] created Morning Brief for user ${userId}, next run at ${runTime.toLocaleTimeString()} (disabled by default)`);
-      return { id };
-    }
-
-    return null;
-  }
-
   /**
    * Get heartbeat status for a user
    *
@@ -455,35 +388,18 @@ Keep it concise and actionable.`;
   async resetHeartbeat(userId) {
     if (!this.db || !userId) return null;
 
-    const deleted = this.db.prepare(
+    this.db.prepare(
       "DELETE FROM cron_tasks WHERE user_id = ? AND name = 'heartbeat'"
     ).run(userId);
     console.log(`[cron] deleted existing heartbeat(s) for user ${userId}`);
 
-    const jitter = Math.floor(Math.random() * HEARTBEAT_INTERVAL_MS);
-    const now = Date.now();
-    const id = crypto.randomUUID();
+    const result = await this.ensureHeartbeat(userId);
 
-    this.db.prepare(`
-      INSERT INTO cron_tasks (id, name, prompt, session_id, user_id, next_run_at, interval_ms, recurring, enabled, created_at, last_run_at)
-      VALUES (?, 'heartbeat', ?, 'default', ?, ?, ?, 1, 1, ?, NULL)
-    `).run(id, HEARTBEAT_PROMPT, userId, now + jitter, HEARTBEAT_INTERVAL_MS, now);
-
-    console.log(`[cron] created new heartbeat for user ${userId}, first run in ${Math.round(jitter / 60000)}m`);
+    if (!result) return null;
 
-    return {
-      id,
-      name: 'heartbeat',
-      prompt: HEARTBEAT_PROMPT,
-      userId,
-      sessionId: 'default',
-      nextRunAt: new Date(now + jitter),
-      intervalMs: HEARTBEAT_INTERVAL_MS,
-      recurring: true,
-      enabled: true,
-      createdAt: new Date(now),
-      lastRunAt: null,
-    };
+    // Return the full task object for the newly created heartbeat
+    const row = this.db.prepare('SELECT * FROM cron_tasks WHERE id = ?').get(result.id);
+    return row ? this._rowToTask(row) : null;
   }
 
   /**

package/storage/index.js

@@ -5,9 +5,6 @@ export { CronStore } from './CronStore.js';
 export { SQLiteCronStore, parseInterval, HEARTBEAT_INTERVAL_MS, HEARTBEAT_PROMPT } from './SQLiteCronAdapter.js';
 export { TaskStore } from './TaskStore.js';
 export { SQLiteTaskStore } from './SQLiteTaskAdapter.js';
-// Backwards compatibility aliases
-export { TaskStore as GoalStore } from './TaskStore.js';
-export { SQLiteTaskStore as SQLiteGoalStore } from './SQLiteTaskAdapter.js';
 export { TriggerStore } from './TriggerStore.js';
 export { SQLiteTriggerStore } from './SQLiteTriggerAdapter.js';
 export { SQLiteMemoryStore } from './SQLiteMemoryAdapter.js';

package/test/agent.test.js

@@ -0,0 +1,192 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { agentLoop } from '../core/agent.js';
+
+/**
+ * Regression tests for the mlx_local provider branch of agentLoop.
+ *
+ * These cover the flush branch added in 0.30 that handles short plain-text
+ * responses from local models that never emit gpt-oss channel tokens
+ * (Gemma 4 E2B, LFM2.5, SmolLM). Without the flush, the rawBuffer was
+ * silently discarded on stream end and the downstream consumer received
+ * zero text_delta events — empty assistant bubbles in the UI.
+ */
+
+/**
+ * Build a minimal mlx_local-style provider for agentLoop tests.
+ * The `id` must be "mlx_local" to hit the buffered-parsing branch,
+ * and `local: true` skips the failover path for a direct fetch.
+ */
+function makeLocalProvider() {
+  return {
+    id: 'mlx_local',
+    name: 'Test Local',
+    apiUrl: 'http://127.0.0.1:1316/v1',
+    endpoint: '/chat/completions',
+    local: true,
+    headers: () => ({ 'Content-Type': 'application/json' }),
+  };
+}
+
+/**
+ * Mock a fetch Response carrying an OpenAI-style SSE stream.
+ * Accepts an array of {content?, finish_reason?} deltas. Each becomes one
+ * SSE data line. A final "data: [DONE]" terminator is appended automatically.
+ */
+function mockSSEResponse(deltas) {
+  const encoder = new TextEncoder();
+  const body = new ReadableStream({
+    start(controller) {
+      for (const delta of deltas) {
+        const chunk = { choices: [{ delta }] };
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`));
+      }
+      controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+      controller.close();
+    },
+  });
+  return new Response(body, {
+    status: 200,
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
+
+/**
+ * Replace globalThis.fetch with a mock that returns the given Response
+ * for every call. Returns a restore function to put the original back.
+ */
+function stubFetch(response) {
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => response;
+  return () => { globalThis.fetch = original; };
+}
+
+describe('agentLoop — mlx_local short plain-text response flush', () => {
+  let restoreFetch;
+
+  afterEach(() => {
+    if (restoreFetch) {
+      restoreFetch();
+      restoreFetch = null;
+    }
+  });
+
+  test('yields text_delta for a <200-char greeting that never hits passthrough threshold', async () => {
+    // Gemma 4 E2B greetings are 30-150 chars and emit no <|channel|> markers.
+    // Pre-0.30: rawBuffer accumulated silently, never yielded, full response 0 chars.
+    // Post-0.30: the stream-done handler flushes the buffer to a text_delta.
+    restoreFetch = stubFetch(mockSSEResponse([
+      { content: 'Hi' },
+      { content: ' there!' },
+      { content: ' How can I help?' },
+      { finish_reason: 'stop' },
+    ]));
+
+    const gen = agentLoop({
+      model: 'test-model',
+      messages: [
+        { role: 'system', content: 'test' },
+        { role: 'user', content: 'hi' },
+      ],
+      tools: [],
+      provider: makeLocalProvider(),
+    });
+
+    const events = [];
+    let fullResponse = '';
+    for await (const event of gen) {
+      events.push(event);
+      if (event.type === 'text_delta' && event.text) {
+        fullResponse += event.text;
+      }
+      if (event.type === 'done') break;
+    }
+
+    assert.strictEqual(fullResponse, 'Hi there! How can I help?');
+    const textDeltas = events.filter((e) => e.type === 'text_delta');
+    assert.ok(textDeltas.length >= 1, 'expected at least one text_delta event');
+    const doneEvents = events.filter((e) => e.type === 'done');
+    assert.strictEqual(doneEvents.length, 1);
+  });
+
+  test('does not flush when the buffer contains tool call markers', async () => {
+    // Guards against false-positive text emission when the model emits a
+    // text-based tool call — those are handled by the post-loop parseToolCalls()
+    // branch, not the flush path.
+    restoreFetch = stubFetch(mockSSEResponse([
+      { content: '<tool_call>' },
+      { content: '{"name":"web_search","arguments":{"query":"weather"}}' },
+      { content: '</tool_call>' },
+      { finish_reason: 'stop' },
+    ]));
+
+    const gen = agentLoop({
+      model: 'test-model',
+      messages: [
+        { role: 'system', content: 'test' },
+        { role: 'user', content: 'weather?' },
+      ],
+      tools: [
+        {
+          name: 'web_search',
+          description: 'Search',
+          parameters: { type: 'object' },
+          execute: async () => 'sunny',
+        },
+      ],
+      provider: makeLocalProvider(),
+      maxTurns: 1, // Cap after the first iteration so the loop exits
+    });
+
+    const events = [];
+    for await (const event of gen) {
+      events.push(event);
+      if (events.length > 20) break; // Safety cap in case tool loop misbehaves
+    }
+
+    // Critical assertion: no text_delta should carry the raw <tool_call> markup.
+    // If the flush branch fires unguarded, the user would see literal
+    // "<tool_call>..." in their chat bubble.
+    const textWithMarkers = events
+      .filter((e) => e.type === 'text_delta')
+      .filter((e) => e.text && e.text.includes('<tool_call>'));
+    assert.strictEqual(textWithMarkers.length, 0,
+      'tool_call markup must not leak through the flush branch');
+  });
+
+  test('end-to-end text accumulation matches the realtime consumer pattern', async () => {
+    // Simulates a streaming consumer (e.g. a WebSocket bridge): accumulate
+    // text from text_delta events, break on done. Pre-0.30 the accumulated
+    // string was empty. Post-0.30 it matches the model's full utterance.
+    restoreFetch = stubFetch(mockSSEResponse([
+      { content: 'Hello' },
+      { content: '!' },
+      { finish_reason: 'stop' },
+    ]));
+
+    const gen = agentLoop({
+      model: 'test-model',
+      messages: [{ role: 'user', content: 'hi' }],
+      tools: [],
+      provider: makeLocalProvider(),
+    });
+
+    let fullResponse = '';
+    let textDeltaCount = 0;
+    let sawDone = false;
+    for await (const event of gen) {
+      if (event.type === 'text_delta') {
+        fullResponse += event.text;
+        textDeltaCount++;
+      }
+      if (event.type === 'done') {
+        sawDone = true;
+        break;
+      }
+    }
+
+    assert.strictEqual(fullResponse, 'Hello!');
+    assert.ok(textDeltaCount > 0, 'expected at least one text_delta');
+    assert.strictEqual(sawDone, true);
+  });
+});