daemora 1.0.3 → 1.0.5

package/src/tools/executeCommand.js

@@ -13,12 +13,15 @@ import { resolve } from "node:path";
 import { config } from "../config/default.js";
 import filesystemGuard from "../safety/FilesystemGuard.js";
 import { checkCommand } from "../safety/CommandGuard.js";
+import execApproval from "../safety/ExecApproval.js";
+import dockerSandbox from "../safety/DockerSandbox.js";
+import tenantContext from "../tenants/TenantContext.js";
 
 const DEFAULT_TIMEOUT_MS = 120_000;   // 2 minutes default
 const MAX_TIMEOUT_MS = 600_000;       // 10 minutes hard max
 const MAX_BUFFER = 10 * 1024 * 1024; // 10MB
 
-export function executeCommand(cmd, optionsJson) {
+export async function executeCommand(cmd, optionsJson) {
   const opts = optionsJson ? JSON.parse(optionsJson) : {};
   const {
     cwd: cwdRaw = null,
@@ -42,6 +45,14 @@ export function executeCommand(cmd, optionsJson) {
   if (!cmdCheck.allowed) {
     return `Command blocked by security policy: ${cmdCheck.reason}`;
   }
+
+  // ── Exec approval gate — pause for user approval if needed ──
+  if (execApproval.needsApproval(cmd)) {
+    const decision = await execApproval.requestApproval(cmd, opts.taskId || null);
+    if (decision === "deny") {
+      return `Command denied by approval gate: "${cmd.slice(0, 80)}". User chose to deny execution.`;
+    }
+  }
   // ──────────────────────────────────────────────────────────────────────────
 
   // ── Filesystem scope enforcement ───────────────────────────────────────────
@@ -80,6 +91,13 @@ export function executeCommand(cmd, optionsJson) {
 
   console.log(`      [executeCommand] Running: ${cmd}${cwdRaw ? ` (cwd: ${cwdRaw})` : ""}${background ? " [background]" : ""}`);
 
+  // ── Docker sandbox mode — route through container ──
+  if (config.sandbox?.mode === "docker" && dockerSandbox.isAvailable() && !background) {
+    const store = tenantContext.getStore();
+    const scope = config.sandbox.docker?.scope === "shared" ? "shared" : (store?.sessionId || "shared");
+    return dockerSandbox.exec(scope, cmd, { timeout, cwd });
+  }
+
   // Background mode - spawn detached, return PID immediately
   if (background) {
     try {

package/src/tools/index.js

@@ -26,6 +26,7 @@ import { delegateToAgent, delegateToAgentDescription } from "../a2a/A2AClient.js
 // ─── Media tools ───────────────────────────────────────────────────────────────
 import { transcribeAudio, transcribeAudioDescription } from "./transcribeAudio.js";
 import { sendFile, sendFileDescription } from "./sendFile.js";
+import { replyWithFile, replyWithFileDescription } from "./replyWithFile.js";
 import { textToSpeech, textToSpeechDescription } from "./textToSpeech.js";
 
 // ─── Search & code tools ───────────────────────────────────────────────────────
@@ -38,6 +39,7 @@ import { manageAgents, manageAgentsDescription } from "./manageAgents.js";
 import { cron, cronDescription } from "./cronTool.js";
 import { messageChannel, messageChannelDescription } from "./messageChannel.js";
 import { projectTracker, projectTrackerDescription } from "./projectTracker.js";
+import { taskManager, taskManagerDescription } from "./taskManager.js";
 import { manageMCP, manageMCPDescription } from "./manageMCP.js";
 import { useMCP, useMCPDescription } from "./useMCP.js";
 import { makeVoiceCall, makeVoiceCallDescription } from "./makeVoiceCall.js";
@@ -105,6 +107,7 @@ export const toolFunctions = {
   sendEmail,
   messageChannel,
   sendFile,
+  replyWithFile,
   transcribeAudio,
   textToSpeech,
   // Documents
@@ -124,6 +127,7 @@ export const toolFunctions = {
   manageAgents,
   // Project tracking
   projectTracker,
+  taskManager,
   // Automation
   cron,
   // Vision / Screen
@@ -178,6 +182,7 @@ export const toolDescriptions = [
   sendEmailDescription,
   messageChannelDescription,
   sendFileDescription,
+  replyWithFileDescription,
   transcribeAudioDescription,
   textToSpeechDescription,
   // Documents
@@ -197,6 +202,7 @@ export const toolDescriptions = [
   manageAgentsDescription,
   // Project tracking
   projectTrackerDescription,
+  taskManagerDescription,
   // Automation
   cronDescription,
   // Vision / Screen

package/src/tools/manageAgents.js

@@ -1,12 +1,13 @@
 /**
- * manageAgents(action, paramsJson?) - List, kill, or steer running sub-agents.
- * Inspired by OpenClaw's subagents tool.
+ * manageAgents(action, paramsJson?) - List, kill, or steer running sub-agents + manage persistent sessions.
  */
 import {
   listActiveAgents,
   killAgent,
   steerAgent,
 } from "../agents/SubAgentManager.js";
+import { listSessions, getSession, clearSession } from "../services/sessions.js";
+import tenantContext from "../tenants/TenantContext.js";
 
 export function manageAgents(action, paramsJson) {
   try {
@@ -35,8 +36,55 @@ export function manageAgents(action, paramsJson) {
         return result;
       }
 
+      // ── Persistent sub-agent session management ──────────────────────────
+      case "sessions": {
+        const store = tenantContext.getStore();
+        const mainSessionId = store?.sessionId;
+        if (!mainSessionId) return "No active session context.";
+
+        const subSessions = listSessions(mainSessionId);
+        if (subSessions.length === 0) return "No sub-agent sessions found.";
+
+        const lines = subSessions.map(id => {
+          const label = id.slice(mainSessionId.length + 2); // strip "telegram-123--"
+          const session = getSession(id);
+          const msgCount = session?.messages?.length || 0;
+          return `• ${label} (${msgCount} messages) — sessionId: "${id}"`;
+        });
+        return `Sub-agent sessions (${subSessions.length}):\n${lines.join("\n")}`;
+      }
+
+      case "session_get": {
+        if (!params.sessionId) return 'Error: sessionId is required for "session_get" action';
+        const session = getSession(params.sessionId);
+        if (!session) return `Session "${params.sessionId}" not found.`;
+        const count = params.count || 5;
+        const last = session.messages.slice(-count);
+        if (last.length === 0) return "Session exists but has no messages.";
+        return `Last ${last.length} messages from "${params.sessionId}":\n\n` +
+          last.map(m => `[${m.role}]: ${(m.content || "").slice(0, 300)}`).join("\n\n");
+      }
+
+      case "session_clear": {
+        if (!params.sessionId) return 'Error: sessionId is required for "session_clear" action';
+        const cleared = clearSession(params.sessionId);
+        return cleared
+          ? `Session "${params.sessionId}" cleared.`
+          : `Session "${params.sessionId}" not found.`;
+      }
+
+      case "session_clear_all": {
+        const store = tenantContext.getStore();
+        const mainSessionId = store?.sessionId;
+        if (!mainSessionId) return "No active session context.";
+        const subSessions = listSessions(mainSessionId);
+        if (subSessions.length === 0) return "No sub-agent sessions to clear.";
+        subSessions.forEach(id => clearSession(id));
+        return `Cleared ${subSessions.length} sub-agent session(s).`;
+      }
+
       default:
-        return `Unknown action: "${action}". Available: list, kill, steer`;
+        return `Unknown action: "${action}". Available: list, kill, steer, sessions, session_get, session_clear, session_clear_all`;
     }
   } catch (error) {
     return `Error managing agents: ${error.message}`;
@@ -44,4 +92,7 @@ export function manageAgents(action, paramsJson) {
 }
 
 export const manageAgentsDescription =
-  'manageAgents(action: string, paramsJson?: string) - Manage running sub-agents. Actions: "list" (show all), "kill" ({"agentId":"id"}), "steer" ({"agentId":"id","message":"new instruction"}).';
+  'manageAgents(action: string, paramsJson?: string) - Manage sub-agents and their persistent sessions. ' +
+  'Actions: "list" (running agents), "kill" ({"agentId":"id"}), "steer" ({"agentId":"id","message":"..."}), ' +
+  '"sessions" (list persistent sub-agent sessions), "session_get" ({"sessionId":"id","count":5} - last N messages), ' +
+  '"session_clear" ({"sessionId":"id"} - reset a specialist), "session_clear_all" (clear all sub-agent sessions).';

package/src/tools/replyWithFile.js

@@ -0,0 +1,62 @@
+/**
+ * replyWithFile(filePath, caption?) - Send a file back to the user who sent the current message.
+ *
+ * Reads channel + chatId from TenantContext automatically.
+ * The agent never needs to know which channel or chatId — just the file path.
+ *
+ * Works for images, videos, documents, audio — any file type.
+ * The channel adapter auto-detects the type and sends appropriately
+ * (e.g. Telegram sends photos as photos, videos as videos).
+ */
+import tenantContext from "../tenants/TenantContext.js";
+import channelRegistry from "../channels/index.js";
+import { existsSync, statSync } from "node:fs";
+
+const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB
+
+export async function replyWithFile(filePath, caption) {
+  try {
+    if (!filePath) return "Error: filePath is required.";
+
+    if (!existsSync(filePath)) {
+      return `Error: File not found: ${filePath}`;
+    }
+
+    const size = statSync(filePath).size;
+    if (size > MAX_FILE_SIZE) {
+      return `Error: File too large (${(size / 1024 / 1024).toFixed(1)} MB). Maximum is 50 MB.`;
+    }
+
+    const store = tenantContext.getStore();
+    const channelMeta = store?.channelMeta;
+
+    if (!channelMeta?.channel || !channelMeta?.chatId) {
+      return "Error: No active channel context. Cannot determine where to send the file. Use sendFile(channel, target, filePath) instead.";
+    }
+
+    const ch = channelRegistry.get(channelMeta.channel);
+    if (!ch) {
+      return `Error: Channel "${channelMeta.channel}" not available.`;
+    }
+    if (!ch.running) {
+      return `Error: Channel "${channelMeta.channel}" is not running.`;
+    }
+    if (typeof ch.sendFile !== "function") {
+      return `Error: Channel "${channelMeta.channel}" does not support file sending.`;
+    }
+
+    await ch.sendFile(channelMeta, filePath, caption || "");
+
+    // Mark that we already replied directly — channel should skip the duplicate text message
+    if (store) store.directReplySent = true;
+
+    return `File sent to user: ${filePath}`;
+  } catch (error) {
+    return `Error sending file: ${error.message}`;
+  }
+}
+
+export const replyWithFileDescription =
+  'replyWithFile(filePath, caption?) - Send a file (image, video, document, audio) back to the user. ' +
+  'Automatically uses the current channel — no need to specify channel or chatId. ' +
+  'Use after screenCapture, generateImage, createDocument, or any tool that produces a file the user should receive.';

package/src/tools/screenCapture.js

@@ -12,7 +12,7 @@
  * or sendFile to deliver the result to the user.
  */
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, statSync } from "node:fs";
 import { platform } from "node:os";
 import { join } from "node:path";
 
@@ -61,8 +61,19 @@ export function screenCapture(optionsJson) {
       }
 
       if (!existsSync(outputPath)) {
+        if (os === "darwin") {
+          return "Error: Screenshot failed. The terminal app likely needs Screen Recording permission. Go to: System Settings → Privacy & Security → Screen Recording → enable your terminal app, then restart it.";
+        }
         return "Error: Screenshot command ran but no file was created.";
       }
+
+      if (os === "darwin") {
+        const fileSize = statSync(outputPath).size;
+        if (fileSize < 500) {
+          return `Error: Screenshot captured but appears empty (${fileSize} bytes). The terminal app likely needs Screen Recording permission. Go to: System Settings → Privacy & Security → Screen Recording → enable your terminal app, then restart it.`;
+        }
+      }
+
       return `Screenshot saved to: ${outputPath}`;
     }
 

package/src/tools/taskManager.js

@@ -0,0 +1,164 @@
+import { v4 as uuidv4 } from "uuid";
+import { createTask, startTask, completeTask, failTask } from "../core/Task.js";
+import { saveTask, loadTask, listTasks, listChildTasks } from "../storage/TaskStore.js";
+import tenantContext from "../tenants/TenantContext.js";
+
+/**
+ * Task Manager - Agent-facing tool for creating and tracking tasks.
+ *
+ * Unlike projectTracker (which is a separate project/task system),
+ * this creates real Task records in TaskStore that appear in the UI
+ * and integrate with sub-agent tracking.
+ *
+ * Actions:
+ *   createTask  - create a new agent task (type: "task")
+ *   updateTask  - update status/result of a task
+ *   listTasks   - list agent-created tasks
+ *   getTask     - get full task details + children
+ */
+
+export function taskManager(action, paramsJson) {
+  const params = paramsJson
+    ? (typeof paramsJson === "string" ? JSON.parse(paramsJson) : paramsJson)
+    : {};
+
+  // Get current context for parentTaskId linkage
+  const store = tenantContext.getStore();
+
+  switch (action) {
+
+    // ── Create task ─────────────────────────────────────────────────────────
+    case "createTask": {
+      const { title, description = "", status = "pending", parentTaskId = null } = params;
+      if (!title) return "Error: title is required";
+
+      // Auto-link to current executing task if no explicit parent
+      const effectiveParentId = parentTaskId || store?.currentTaskId || null;
+
+      const task = createTask({
+        input: description || title,
+        type: "task",
+        title,
+        description,
+        parentTaskId: effectiveParentId,
+        agentCreated: true,
+        agentId: store?.agentId || null,
+        channel: "agent",
+        sessionId: store?.sessionId || null,
+      });
+
+      // If created with a non-pending status, apply it
+      if (status === "in_progress") startTask(task);
+      else if (status === "completed") {
+        startTask(task);
+        completeTask(task, "Created as completed");
+      }
+
+      saveTask(task);
+
+      const parentStr = effectiveParentId ? ` (child of ${effectiveParentId.slice(0, 8)})` : "";
+      return `Task created: ${task.id} "${title}"${parentStr} — status: ${task.status}`;
+    }
+
+    // ── Update task ─────────────────────────────────────────────────────────
+    case "updateTask": {
+      const { taskId, status, result, agentId } = params;
+      if (!taskId) return "Error: taskId is required";
+
+      const task = loadTask(taskId);
+      if (!task) return `Error: Task "${taskId}" not found`;
+
+      if (agentId) task.agentId = agentId;
+
+      if (status) {
+        const oldStatus = task.status;
+        switch (status) {
+          case "in_progress":
+            if (task.status === "pending") startTask(task);
+            else task.status = "in_progress";
+            break;
+          case "completed":
+            completeTask(task, result || task.result || "");
+            break;
+          case "failed":
+            failTask(task, result || "Task failed");
+            break;
+          default:
+            return `Error: Invalid status "${status}". Use: pending, in_progress, completed, failed`;
+        }
+        saveTask(task);
+        return `Task ${taskId} "${task.title || task.input?.slice(0, 40)}": ${oldStatus} → ${status}`;
+      }
+
+      saveTask(task);
+      return `Task ${taskId} updated`;
+    }
+
+    // ── List tasks ──────────────────────────────────────────────────────────
+    case "listTasks": {
+      const { status = null, parentTaskId = null, limit = 20 } = params;
+
+      let tasks = listTasks({ limit, status, type: "task" });
+
+      if (parentTaskId) {
+        tasks = tasks.filter(t => t.parentTaskId === parentTaskId);
+      }
+
+      if (tasks.length === 0) return "No agent-created tasks found.";
+
+      return tasks.map(t => {
+        const icon = t.status === "completed" ? "✅" : t.status === "running" ? "🔄" : t.status === "failed" ? "❌" : "⬜";
+        const agent = t.agentId ? ` [agent:${t.agentId}]` : "";
+        const parent = t.parentTaskId ? ` ← ${t.parentTaskId}` : "";
+        return `${icon} ${t.id} ${t.title || t.input?.slice(0, 50)}${agent}${parent} — ${t.status}`;
+      }).join("\n");
+    }
+
+    // ── Get task details ────────────────────────────────────────────────────
+    case "getTask": {
+      const { taskId } = params;
+      if (!taskId) return "Error: taskId is required";
+
+      const task = loadTask(taskId);
+      if (!task) return `Error: Task "${taskId}" not found`;
+
+      const children = listChildTasks(taskId);
+
+      const lines = [
+        `Task: ${task.title || task.input?.slice(0, 60)} [${task.id.slice(0, 8)}]`,
+        `Type: ${task.type || "chat"} | Status: ${task.status}`,
+        task.description ? `Description: ${task.description}` : null,
+        task.agentId ? `Agent: ${task.agentId}` : null,
+        task.parentTaskId ? `Parent: ${task.parentTaskId.slice(0, 8)}` : null,
+        task.cost?.estimatedCost ? `Cost: $${task.cost.estimatedCost.toFixed(4)}` : null,
+        task.toolCalls?.length ? `Tool calls: ${task.toolCalls.length}` : null,
+        task.subAgents?.length ? `Sub-agents: ${task.subAgents.length}` : null,
+      ].filter(Boolean);
+
+      if (children.length > 0) {
+        lines.push("", `Children (${children.length}):`);
+        for (const child of children) {
+          const icon = child.status === "completed" ? "✅" : child.status === "running" ? "🔄" : child.status === "failed" ? "❌" : "⬜";
+          const agent = child.agentId ? ` [${child.agentId.slice(0, 8)}]` : "";
+          lines.push(`  ${icon} [${child.id.slice(0, 8)}] ${child.title || child.input?.slice(0, 40)}${agent} — ${child.status}`);
+        }
+      }
+
+      return lines.join("\n");
+    }
+
+    default:
+      return `Unknown action: "${action}". Valid: createTask, updateTask, listTasks, getTask`;
+  }
+}
+
+export const taskManagerDescription =
+  `taskManager(action: string, paramsJson?: string) - Create, update, and monitor tasks. Tasks appear in the UI and link to sub-agents.
+  Actions:
+    createTask  - {"title":"...","description":"...","status":"pending|in_progress"} → returns full task ID
+    updateTask  - {"taskId":"<full-uuid>","status":"completed|failed","result":"summary of what was done"}
+    listTasks   - {} or {"status":"running","parentTaskId":"<uuid>"} → list tasks with IDs and status
+    getTask     - {"taskId":"<full-uuid>"} → full details + child tasks + sub-agent info
+  Statuses: pending | in_progress | completed | failed
+  Tasks auto-link to the current parent task. Use createTask before starting each step, updateTask when done.
+  When spawning sub-agents, include the task ID in their description so they can call updateTask on it.`;

package/src/tools/useMCP.js

@@ -19,7 +19,9 @@ export async function useMCP(serverName, taskDescription) {
     return `Access denied: MCP server "${serverName}" is not in your allowed list. Contact the operator.`;
   }
 
-  return runMCPAgent(serverName, taskDescription);
+  const mainSessionId = store?.sessionId || null;
+  const parentTaskId = store?.currentTaskId || null;
+  return runMCPAgent(serverName, taskDescription, { mainSessionId, parentTaskId });
 }
 
 export const useMCPDescription =

package/src/utils/Embeddings.js

@@ -5,9 +5,10 @@
  *   1. OPENAI_API_KEY      → text-embedding-3-small  (512 dims)
  *   2. GOOGLE_AI_API_KEY   → text-embedding-004       (768 dims)
  *   3. OLLAMA_HOST         → nomic-embed-text         (768 dims, local/free)
- *   4. None                → returns null (callers fall back to keyword search)
+ *   4. Ollama auto-detect  → tries localhost:11434    (no config needed)
+ *   5. Built-in TF-IDF     → pure JS, zero deps, zero API calls
  *
- * Override with: EMBEDDING_PROVIDER=openai|google|ollama
+ * Override with: EMBEDDING_PROVIDER=openai|google|ollama|tfidf
  * Override Ollama model with: OLLAMA_EMBED_MODEL=nomic-embed-text
  *
  * Note: vectors from different providers are NOT interchangeable.
@@ -17,8 +18,28 @@
 
 import { embed } from "ai";
 
+let _ollamaAutoDetected = null; // null = untested, true/false = tested
+
+/**
+ * Probe localhost:11434 for a running Ollama instance (one-time check, cached).
+ */
+async function _probeOllama() {
+  if (_ollamaAutoDetected !== null) return _ollamaAutoDetected;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 1500);
+    const res = await fetch("http://localhost:11434/api/tags", { signal: ctrl.signal });
+    clearTimeout(timer);
+    _ollamaAutoDetected = res.ok;
+  } catch {
+    _ollamaAutoDetected = false;
+  }
+  return _ollamaAutoDetected;
+}
+
 /**
  * Returns the currently active embedding provider name, or null if none available.
+ * Sync version — returns "ollama-auto" when auto-detect is pending (caller must handle).
  */
 export function getEmbeddingProvider() {
   const override = process.env.EMBEDDING_PROVIDER?.toLowerCase();
@@ -27,45 +48,168 @@ export function getEmbeddingProvider() {
     if (override === "openai"  && process.env.OPENAI_API_KEY)    return "openai";
     if (override === "google"  && process.env.GOOGLE_AI_API_KEY) return "google";
     if (override === "ollama")                                    return "ollama";
-    return null;  // Override set but required key missing
+    if (override === "tfidf")                                     return "tfidf";
+    return null;
   }
 
   // Auto-detect in priority order
   if (process.env.OPENAI_API_KEY)    return "openai";
   if (process.env.GOOGLE_AI_API_KEY) return "google";
   if (process.env.OLLAMA_HOST)       return "ollama";
-  return null;
+  // Ollama auto-detect result (set after first generateEmbedding call)
+  if (_ollamaAutoDetected === true)  return "ollama";
+  // Always available — built-in TF-IDF as last resort
+  return "tfidf";
+}
+
+/**
+ * Async version of getEmbeddingProvider — probes Ollama if not yet tested.
+ */
+export async function getEmbeddingProviderAsync() {
+  const override = process.env.EMBEDDING_PROVIDER?.toLowerCase();
+
+  if (override) {
+    if (override === "openai"  && process.env.OPENAI_API_KEY)    return "openai";
+    if (override === "google"  && process.env.GOOGLE_AI_API_KEY) return "google";
+    if (override === "ollama")                                    return "ollama";
+    if (override === "tfidf")                                     return "tfidf";
+    return "tfidf";
+  }
+
+  if (process.env.OPENAI_API_KEY)    return "openai";
+  if (process.env.GOOGLE_AI_API_KEY) return "google";
+  if (process.env.OLLAMA_HOST)       return "ollama";
+
+  // Auto-probe Ollama on localhost
+  if (_ollamaAutoDetected === null) {
+    const found = await _probeOllama();
+    if (found) {
+      console.log("[Embeddings] Auto-detected Ollama at localhost:11434");
+      return "ollama";
+    }
+  } else if (_ollamaAutoDetected) {
+    return "ollama";
+  }
+
+  return "tfidf";
+}
+
+// ── Built-in TF-IDF ──────────────────────────────────────────────────────────
+// Pure JS, zero deps, zero API calls. Produces sparse vectors for cosine similarity.
+// Quality is lower than neural embeddings but far better than naive keyword matching.
+
+const _idfCache = new Map();   // word → idf score
+const _vocabList = [];         // ordered vocabulary for consistent vector indices
+const _vocabIndex = new Map(); // word → index in _vocabList
+
+/**
+ * Tokenize text into lowercase word stems (simple).
+ */
+function _tokenize(text) {
+  return text.toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter(w => w.length > 1);
+}
+
+/**
+ * Build/update IDF table from a corpus of documents.
+ * Call once with all skill texts at startup.
+ * @param {string[]} docs - array of document texts
+ */
+export function buildTfidfVocab(docs) {
+  _idfCache.clear();
+  _vocabList.length = 0;
+  _vocabIndex.clear();
+
+  const N = docs.length;
+  if (N === 0) return;
+
+  // Count document frequency for each word
+  const df = new Map();
+  for (const doc of docs) {
+    const unique = new Set(_tokenize(doc));
+    for (const w of unique) {
+      df.set(w, (df.get(w) || 0) + 1);
+    }
+  }
+
+  // Compute IDF and build vocabulary (filter rare/ubiquitous words)
+  let idx = 0;
+  for (const [word, count] of df) {
+    if (count < 1 || count === N) continue; // skip words in all/no docs
+    const idf = Math.log((N + 1) / (count + 1)) + 1; // smoothed IDF
+    _idfCache.set(word, idf);
+    _vocabList.push(word);
+    _vocabIndex.set(word, idx++);
+  }
+}
+
+/**
+ * Generate a TF-IDF vector for a text. Returns a sparse Float32Array.
+ * Must call buildTfidfVocab() first.
+ */
+export function tfidfEmbed(text) {
+  if (_vocabList.length === 0) return null;
+
+  const tokens = _tokenize(text);
+  const tf = new Map();
+  for (const t of tokens) {
+    if (_vocabIndex.has(t)) tf.set(t, (tf.get(t) || 0) + 1);
+  }
+
+  const vec = new Float32Array(_vocabList.length);
+  let norm = 0;
+  for (const [word, count] of tf) {
+    const idx = _vocabIndex.get(word);
+    const idf = _idfCache.get(word) || 0;
+    const val = (1 + Math.log(count)) * idf; // log-normalized TF * IDF
+    vec[idx] = val;
+    norm += val * val;
+  }
+
+  // L2 normalize
+  if (norm > 0) {
+    const invNorm = 1 / Math.sqrt(norm);
+    for (let i = 0; i < vec.length; i++) vec[i] *= invNorm;
+  }
+
+  return Array.from(vec);
 }
 
 /**
  * Generate a vector embedding for the given text using the best available provider.
- * Returns null if no provider is configured - callers must fall back to keyword search.
+ * Falls back through: API providers → local Ollama → built-in TF-IDF.
  *
  * @param {string} text
  * @returns {Promise<number[]|null>}
  */
 export async function generateEmbedding(text) {
-  const provider = getEmbeddingProvider();
+  const provider = await getEmbeddingProviderAsync();
   if (!provider) return null;
 
+  // Built-in TF-IDF — no API call needed
+  if (provider === "tfidf") {
+    return tfidfEmbed(text);
+  }
+
   try {
     let model;
 
     if (provider === "openai") {
       const { createOpenAI } = await import("@ai-sdk/openai");
       const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
-      // 512 dims = 3x smaller than default 1536, minimal quality loss for recall tasks
       model = openai.embedding("text-embedding-3-small", { dimensions: 512 });
 
     } else if (provider === "google") {
       const { createGoogleGenerativeAI } = await import("@ai-sdk/google");
       const google = createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_AI_API_KEY });
-      model = google.textEmbeddingModel("text-embedding-004");  // 768 dims
+      model = google.textEmbeddingModel("text-embedding-004");
 
     } else if (provider === "ollama") {
       const { ollama } = await import("ollama-ai-provider");
-      const modelName = process.env.OLLAMA_EMBED_MODEL || "nomic-embed-text";
-      model = ollama.embedding(modelName);  // typically 768 dims
+      const modelName = process.env.OLLAMA_EMBED_MODEL || "all-minilm";
+      model = ollama.embedding(modelName);
     }
 
     if (!model) return null;
@@ -74,6 +218,9 @@ export async function generateEmbedding(text) {
     return embedding;
 
   } catch {
+    // API provider failed — fall back to TF-IDF
+    const tfidfVec = tfidfEmbed(text);
+    if (tfidfVec) return tfidfVec;
     return null;
   }
 }