@stevederico/dotbot 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+0.31
+
+  Document mlx_local provider
+  Fix CLI local auth
+  Remove shields.io badges
+  Generify personal path example
+
+0.30
+
+  Flush buffered plain text
+  Add agentLoop regression tests
+  Rename dottie_desktop to mlx_local
+  Rename getDottieDesktopStatus helper
+  Rename DOTTIE_DESKTOP_URL env var
+  Parameterize notification title
+  Default agentName to Assistant
+  Scrub host-specific doc references
+  Skip heartbeat without tasks
+  Fail closed on task fetch error
+  Add mlx_local provider entry
+  Add cron_handler regression tests
+
 0.29
 
   Extract shared streamEvents

package/README.md

@@ -5,18 +5,6 @@
     The ultra-lean AI agent.<br>
     11k lines. 53 tools. 0 dependencies.
   </h3>
-  <p align="center">
-    <a href="https://opensource.org/licenses/mit">
-      <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License">
-    </a>
-    <a href="https://github.com/stevederico/dotbot/stargazers">
-      <img src="https://img.shields.io/github/stars/stevederico/dotbot?style=social" alt="GitHub stars">
-    </a>
-    <a href="https://github.com/stevederico/dotbot">
-      <img src="https://img.shields.io/badge/version-0.28-green" alt="version">
-    </a>
-    <img src="https://img.shields.io/badge/LOC-11k-orange" alt="Lines of Code">
-  </p>
 </div>
 
 <br />
@@ -204,7 +192,7 @@ for await (const event of agent.chat({
 ## CLI Reference
 
 ```
-dotbot v0.28 — AI agent CLI
+dotbot — AI agent CLI
 
 Usage:
   dotbot "message"            One-shot query
@@ -229,7 +217,7 @@ Commands:
   events [--summary]          View audit log
 
 Options:
-  --provider, -p   AI provider: xai, anthropic, openai, ollama (default: xai)
+  --provider, -p   AI provider: xai, anthropic, openai, ollama, mlx_local (default: xai)
   --model, -m      Model name (default: grok-4-1-fast-reasoning)
   --system, -s     Custom system prompt (prepended to default)
   --session        Resume a specific session by ID
@@ -248,6 +236,7 @@ Environment Variables:
   ANTHROPIC_API_KEY    API key for Anthropic
   OPENAI_API_KEY       API key for OpenAI
   OLLAMA_BASE_URL      Base URL for Ollama (default: http://localhost:11434)
+  MLX_LOCAL_URL        Base URL for a local MLX-style OpenAI-compatible server (default: http://127.0.0.1:1316/v1)
 
 Config File:
   ~/.dotbotrc          JSON config for defaults (provider, model, db, sandbox)

package/bin/dotbot.js

@@ -115,7 +115,7 @@ Commands:
   events [--summary]          View audit log
 
 Options:
-  --provider, -p   AI provider: xai, anthropic, openai, ollama (default: xai)
+  --provider, -p   AI provider: xai, anthropic, openai, ollama, mlx_local (default: xai)
   --model, -m      Model name (default: grok-4-1-fast-reasoning)
   --system, -s     Custom system prompt (prepended to default)
   --session        Resume a specific session by ID
@@ -134,6 +134,7 @@ Environment Variables:
   ANTHROPIC_API_KEY    API key for Anthropic
   OPENAI_API_KEY       API key for OpenAI
   OLLAMA_BASE_URL      Base URL for Ollama (default: http://localhost:11434)
+  MLX_LOCAL_URL        Base URL for a local MLX-style OpenAI-compatible server (default: http://127.0.0.1:1316/v1)
 
 Config File:
   ~/.dotbotrc                 JSON config for defaults (provider, model, db)
@@ -295,6 +296,13 @@ async function getProviderConfig(providerId) {
     return { ...base, apiUrl: `${baseUrl}/api/chat` };
   }
 
+  // Local OpenAI-compatible servers (mlx_local, etc.) don't use API keys —
+  // they're served from localhost and the apiUrl is already baked into the
+  // provider config (or overridden via env var inside providers.js).
+  if (base.local) {
+    return base;
+  }
+
   const envKey = base.envKey;
   let apiKey = process.env[envKey];
 

package/core/agent.js

@@ -174,7 +174,7 @@ export async function* agentLoop({ model, messages, tools, signal, provider, con
       };
     };
 
-    // Local providers (ollama, dottie_desktop): direct fetch, no failover
+    // Local providers (ollama, mlx_local): direct fetch, no failover
     if (provider.local) {
       const { url, headers, body } = buildAgentRequest(provider);
       response = await fetch(url, { method: "POST", headers, body, signal });
@@ -210,8 +210,9 @@ export async function* agentLoop({ model, messages, tools, signal, provider, con
       const result = yield* parseAnthropicStream(response, fullContent, toolCalls, signal, activeProvider.id);
       fullContent = result.fullContent;
       toolCalls = result.toolCalls;
-    } else if (activeProvider.id === "dottie_desktop") {
-      // Dottie Desktop serves local models which may use:
+    } else if (activeProvider.id === "mlx_local") {
+      // Local MLX-style OpenAI-compatible server. Models served this way
+      // may emit output in one of three formats:
       // 1. gpt-oss channel tokens (<|channel|>analysis/final<|message|>)
       // 2. Native reasoning (delta.reasoning from parseOpenAIStream)
       // 3. Plain text (LFM2.5, SmolLM, etc. — no special tokens)
@@ -235,6 +236,21 @@ export async function* agentLoop({ model, messages, tools, signal, provider, con
         if (done) {
           fullContent = value.fullContent;
           toolCalls = value.toolCalls;
+          // Flush buffered plain-text responses that never hit the
+          // CHANNEL_DETECT_THRESHOLD. Happens for short greetings and
+          // small-talk from models that don't emit gpt-oss channel tokens
+          // (Gemma 4 E2B, LFM2.5, SmolLM, etc.). Without this flush, the
+          // rawBuffer is silently discarded and the downstream consumer
+          // never receives any text_delta — the UI renders an empty bubble.
+          // Skip if the buffer contains tool call markers so the existing
+          // post-loop parseToolCalls() below can handle them.
+          if (!usesPassthrough && !usesNativeReasoning && !analysisStarted && !finalMarkerFound && rawBuffer.length > 0) {
+            if (!hasToolCallMarkers(rawBuffer)) {
+              const textEvent = { type: "text_delta", text: rawBuffer };
+              validateEvent(textEvent);
+              yield textEvent;
+            }
+          }
           break;
         }
 
@@ -270,7 +286,7 @@ export async function* agentLoop({ model, messages, tools, signal, provider, con
         // the model doesn't use gpt-oss format (e.g. LFM2.5, SmolLM).
         // Flush buffer and switch to passthrough for remaining tokens.
         if (!analysisStarted && !finalMarkerFound && rawBuffer.length > CHANNEL_DETECT_THRESHOLD) {
-          console.log("[dottie_desktop] no channel tokens after", rawBuffer.length, "chars — switching to passthrough");
+          console.log("[mlx_local] no channel tokens after", rawBuffer.length, "chars — switching to passthrough");
           usesPassthrough = true;
           const textEvent = { type: "text_delta", text: rawBuffer };
           validateEvent(textEvent);
@@ -285,7 +301,7 @@ export async function* agentLoop({ model, messages, tools, signal, provider, con
             if (aIdx !== -1) {
               analysisStarted = true;
               lastThinkingYieldPos = aIdx + ANALYSIS_MARKER.length;
-              console.log("[dottie_desktop] analysis marker found at", aIdx, "| yieldPos:", lastThinkingYieldPos);
+              console.log("[mlx_local] analysis marker found at", aIdx, "| yieldPos:", lastThinkingYieldPos);
             }
           }
 
@@ -295,7 +311,7 @@ export async function* agentLoop({ model, messages, tools, signal, provider, con
             if (endIdx !== -1) {
               const chunk = rawBuffer.slice(lastThinkingYieldPos, endIdx);
               if (chunk) {
-                console.log("[dottie_desktop] thinking (final):", chunk.slice(0, 80));
+                console.log("[mlx_local] thinking (final):", chunk.slice(0, 80));
                 const thinkingEvent = {
                   type: "thinking",
                   text: chunk,
@@ -309,7 +325,7 @@ export async function* agentLoop({ model, messages, tools, signal, provider, con
             } else {
               const chunk = rawBuffer.slice(lastThinkingYieldPos);
               if (chunk) {
-                console.log("[dottie_desktop] thinking (incr):", chunk.slice(0, 80));
+                console.log("[mlx_local] thinking (incr):", chunk.slice(0, 80));
                 const thinkingEvent = {
                   type: "thinking",
                   text: chunk,
@@ -325,7 +341,7 @@ export async function* agentLoop({ model, messages, tools, signal, provider, con
           // Check for final channel marker
           const fIdx = rawBuffer.indexOf(FINAL_MARKER);
           if (fIdx !== -1) {
-            console.log("[dottie_desktop] final marker found at", fIdx, "| bufLen:", rawBuffer.length);
+            console.log("[mlx_local] final marker found at", fIdx, "| bufLen:", rawBuffer.length);
             finalMarkerFound = true;
             lastFinalYieldPos = fIdx + FINAL_MARKER.length;
             const pending = rawBuffer.slice(lastFinalYieldPos);
@@ -740,8 +756,9 @@ export async function getOllamaStatus() {
 }
 
 /**
- * Check if Dottie Desktop is running and list available models.
- * Uses the OpenAI-compatible /v1/models endpoint.
+ * Check if a local OpenAI-compatible model server is running and list
+ * available models. Defaults to the MLX LM server convention
+ * (http://localhost:1316/v1) and can be overridden with MLX_LOCAL_URL.
  *
  * @returns {Promise<{running: boolean, models: Array<{name: string}>}>}
  */
@@ -765,8 +782,8 @@ function stripGptOssTokens(text) {
   return text.replace(TOKEN_RE, "").trim();
 }
 
-export async function getDottieDesktopStatus() {
-  const baseUrl = (process.env.DOTTIE_DESKTOP_URL || 'http://localhost:1316/v1').replace(/\/v1$/, '');
+export async function getMlxLocalStatus() {
+  const baseUrl = (process.env.MLX_LOCAL_URL || 'http://localhost:1316/v1').replace(/\/v1$/, '');
   try {
     const res = await fetch(`${baseUrl}/v1/models`);
     if (!res.ok) return { running: false, models: [] };

package/core/compaction.js

@@ -12,7 +12,7 @@ const CONTEXT_LIMITS = {
   openai: 120000,
   xai: 120000,
   ollama: 6000,
-  dottie_desktop: 6000,
+  mlx_local: 6000,
 };
 
 /** Number of recent messages to always preserve verbatim. */

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevederico/dotbot",
-  "version": "0.29.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/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);
+  });
+});

package/test/cron_handler.test.js

@@ -0,0 +1,116 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { createCronHandler } from '../core/cron_handler.js';
+
+/**
+ * Regression tests for the cron heartbeat path.
+ *
+ * These cover the skip-when-no-tasks optimization added in 0.30: a heartbeat
+ * firing with zero active tasks used to send a pointless "[Heartbeat] ..."
+ * message to the LLM on every tick. Now it returns null from
+ * buildHeartbeatContent before the agent is ever called, saving a round trip
+ * on every provider (and real dollars on cloud providers).
+ */
+
+/**
+ * Build a minimal sessionStore stub that returns a fixed session. The session
+ * has no `updatedAt` so the stale-user check is skipped.
+ */
+function makeSessionStore(owner = 'user-1') {
+  return {
+    async getOrCreateDefaultSession() {
+      return { id: 'session-1', owner, messages: [] };
+    },
+    async getSessionInternal(id) {
+      return { id, owner, messages: [], provider: 'ollama', model: 'test' };
+    },
+    async addMessage() {},
+  };
+}
+
+/**
+ * Track whether agent.chat was invoked, without any real streaming.
+ */
+function makeAgentSpy() {
+  const calls = [];
+  return {
+    calls,
+    async *chat(opts) {
+      calls.push(opts);
+      yield { type: 'done', content: '' };
+    },
+  };
+}
+
+describe('cron_handler — heartbeat skip optimization', () => {
+  test('skips the agent call entirely when there are no active tasks', async () => {
+    const sessionStore = makeSessionStore();
+    const agent = makeAgentSpy();
+
+    const handleTask = createCronHandler({
+      sessionStore,
+      cronStore: {},
+      taskStore: null,
+      memoryStore: null,
+      providers: {},
+      hooks: {
+        tasksFinder: async () => [], // the key condition — zero tasks
+      },
+    });
+    handleTask.setAgent(agent);
+
+    await handleTask({ name: 'heartbeat', userId: 'user-1', prompt: 'Any updates?' });
+
+    // Agent must NOT have been called since there's nothing to discuss.
+    assert.strictEqual(agent.calls.length, 0,
+      'agent.chat must not be invoked when tasksFinder returns []');
+  });
+
+  test('still calls the agent when there is at least one active task', async () => {
+    const sessionStore = makeSessionStore();
+    const agent = makeAgentSpy();
+
+    const handleTask = createCronHandler({
+      sessionStore,
+      cronStore: {},
+      taskStore: null,
+      memoryStore: null,
+      providers: {},
+      hooks: {
+        tasksFinder: async () => [
+          { id: 't1', description: 'Ship the scrub', priority: 'high' },
+        ],
+      },
+    });
+    handleTask.setAgent(agent);
+
+    await handleTask({ name: 'heartbeat', userId: 'user-1', prompt: 'Any updates?' });
+
+    assert.strictEqual(agent.calls.length, 1,
+      'agent.chat should be invoked when at least one active task exists');
+  });
+
+  test('skips the agent call if tasksFinder throws', async () => {
+    // Fail-closed guard: if the task store is down, a heartbeat should not
+    // degrade to a meaningless default prompt sent to the LLM.
+    const sessionStore = makeSessionStore();
+    const agent = makeAgentSpy();
+
+    const handleTask = createCronHandler({
+      sessionStore,
+      cronStore: {},
+      taskStore: null,
+      memoryStore: null,
+      providers: {},
+      hooks: {
+        tasksFinder: async () => { throw new Error('db unreachable'); },
+      },
+    });
+    handleTask.setAgent(agent);
+
+    await handleTask({ name: 'heartbeat', userId: 'user-1', prompt: 'Any updates?' });
+
+    assert.strictEqual(agent.calls.length, 0,
+      'agent.chat must not be invoked when tasksFinder throws');
+  });
+});

package/tools/memory.js

@@ -37,7 +37,7 @@ export const memoryTools = [
           type: "array",
           items: { type: "string" },
           description:
-            "Short tags for categorization. e.g. ['personal', 'name'] or ['project', 'dottie']",
+            "Short tags for categorization. e.g. ['personal', 'name'] or ['project', 'myapp']",
         },
       },
       required: ["content"],

package/utils/providers.js

@@ -133,4 +133,25 @@ export const AI_PROVIDERS = {
     }),
     formatResponse: (data) => data.choices?.[0]?.message?.content
   },
+  mlx_local: {
+    // Local MLX-style OpenAI-compatible server (e.g. mlx_lm.server, LM Studio,
+    // vLLM, llama.cpp server). Routes through the `mlx_local` branch in
+    // core/agent.js which auto-detects gpt-oss channel tokens, native
+    // reasoning, and plain-text responses. Override the URL with MLX_LOCAL_URL.
+    id: 'mlx_local',
+    name: 'Local (MLX)',
+    apiUrl: process.env.MLX_LOCAL_URL || 'http://127.0.0.1:1316/v1',
+    defaultModel: '',
+    models: [],
+    local: true,
+    headers: () => ({
+      'Content-Type': 'application/json'
+    }),
+    endpoint: '/chat/completions',
+    formatRequest: (messages, model) => ({
+      model,
+      messages
+    }),
+    formatResponse: (data) => data.choices?.[0]?.message?.content
+  },
 };

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(grep -r \"grok-3\" /Users/sd/Desktop/projects/dotbot --include=\"*.js\" --include=\"*.md\" 2>/dev/null | grep -v node_modules)"
-    ]
-  }
-}