@rubytech/taskmaster 1.0.65 → 1.0.67

package/dist/gateway/net.js

@@ -1,5 +1,30 @@
 import net from "node:net";
 import { pickPrimaryTailnetIPv4, pickPrimaryTailnetIPv6 } from "../infra/tailnet.js";
+/**
+ * Check if an IPv4 address belongs to a private (RFC 1918) or link-local range.
+ * These addresses are non-routable on the public internet, so any request
+ * from one is by definition on the local network — safe for LAN access.
+ *
+ * Ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16
+ */
+function isPrivateIPv4(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return false;
+    const a = parseInt(parts[0], 10);
+    const b = parseInt(parts[1], 10);
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return false;
+    if (a === 10)
+        return true; // 10.0.0.0/8
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 (link-local)
+    return false;
+}
 export function isLoopbackAddress(ip) {
     if (!ip)
         return false;
@@ -78,6 +103,10 @@ export function isLocalGatewayAddress(ip) {
     const tailnetIPv6 = pickPrimaryTailnetIPv6();
     if (tailnetIPv6 && ip.trim().toLowerCase() === tailnetIPv6.toLowerCase())
         return true;
+    // Any RFC 1918 private or link-local address is on the local network.
+    // These are non-routable on the public internet, so they're safe.
+    if (isPrivateIPv4(normalized))
+        return true;
     return false;
 }
 /**

package/dist/gateway/server-methods/memory.js

@@ -27,6 +27,7 @@ export const memoryHandlers = {
                 provider: status.provider,
                 model: status.model,
                 fts: status.fts,
+                embeddingState: status.embeddingState,
             });
         }
         catch (err) {

package/dist/memory/embeddings.js

@@ -1,9 +1,26 @@
 import fsSync from "node:fs";
+import os from "node:os";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 import { resolveUserPath } from "../utils.js";
+import { getCustomProviderApiKey } from "../agents/model-auth.js";
 import { createGeminiEmbeddingProvider } from "./embeddings-gemini.js";
 import { createOpenAiEmbeddingProvider } from "./embeddings-openai.js";
 import { importNodeLlamaCpp } from "./node-llama.js";
-const DEFAULT_LOCAL_MODEL = "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
+/**
+ * Default local embedding model. The 0.6B model is small enough to run on
+ * any target hardware (Pi 4GB, Pi 8GB, Mac) without GPU and with minimal
+ * RAM overhead (~1-2 GB runtime). Larger models (4B, 8B) can be configured
+ * explicitly via `local.modelPath` for users who have tested them on their
+ * specific hardware — node-llama-cpp's actual memory footprint varies
+ * enormously across GPU vendors and Metal/Vulkan backends.
+ */
+const DEFAULT_LOCAL_MODEL = {
+    model: "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf",
+    label: "Qwen3-Embedding-0.6B",
+};
+function selectDefaultLocalModel() {
+    return DEFAULT_LOCAL_MODEL;
+}
 function canAutoSelectLocal(options) {
     const modelPath = options.local?.modelPath?.trim();
     if (!modelPath)
@@ -22,30 +39,85 @@ function isMissingApiKeyError(err) {
     const message = formatError(err);
     return message.includes("No API key found for provider");
 }
+/**
+ * Deduplicates concurrent model downloads. When multiple agents resolve the
+ * same model path, only one download runs; the rest await the same promise.
+ */
+const inflightDownloads = new Map();
+/**
+ * Cache of resolved model paths (model URI → absolute file path on disk).
+ * Persists across restarts via a JSON file so we skip `resolveModelFile`
+ * (which re-downloads even when the file exists due to a filename mismatch
+ * between the expected URI-derived name and the actual hf-prefixed name).
+ */
+const RESOLVED_PATHS_FILE = (() => {
+    const homeDir = os.homedir();
+    return `${homeDir}/.taskmaster/memory/resolved-model-paths.json`;
+})();
+function readResolvedPaths() {
+    try {
+        return JSON.parse(fsSync.readFileSync(RESOLVED_PATHS_FILE, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeResolvedPath(key, resolvedPath) {
+    try {
+        const dir = RESOLVED_PATHS_FILE.replace(/\/[^/]+$/, "");
+        fsSync.mkdirSync(dir, { recursive: true });
+        const existing = readResolvedPaths();
+        existing[key] = resolvedPath;
+        fsSync.writeFileSync(RESOLVED_PATHS_FILE, JSON.stringify(existing, null, 2));
+    }
+    catch {
+        // Non-fatal — next restart will re-resolve
+    }
+}
+async function resolveModelFileOnce(resolveModelFile, modelPath, modelCacheDir) {
+    const key = `${modelPath}::${modelCacheDir ?? ""}`;
+    // Check on-disk cache first — avoids re-download on restart
+    const cached = readResolvedPaths()[key];
+    if (cached && fsSync.existsSync(cached)) {
+        return cached;
+    }
+    // Deduplicate concurrent calls
+    const existing = inflightDownloads.get(key);
+    if (existing)
+        return existing;
+    const promise = resolveModelFile(modelPath, modelCacheDir || undefined)
+        .then((resolved) => {
+        writeResolvedPath(key, resolved);
+        return resolved;
+    })
+        .finally(() => {
+        inflightDownloads.delete(key);
+    });
+    inflightDownloads.set(key, promise);
+    return promise;
+}
 async function createLocalEmbeddingProvider(options) {
-    const modelPath = options.local?.modelPath?.trim() || DEFAULT_LOCAL_MODEL;
+    const log = createSubsystemLogger("embeddings");
+    const hasExplicitModelPath = Boolean(options.local?.modelPath?.trim());
+    let modelPath;
+    if (hasExplicitModelPath) {
+        modelPath = options.local.modelPath.trim();
+    }
+    else {
+        const selected = selectDefaultLocalModel();
+        modelPath = selected.model;
+        log.info(`selected tier ${selected.label} (system RAM: ${(os.totalmem() / (1024 ** 3)).toFixed(1)} GB)`);
+    }
     const modelCacheDir = options.local?.modelCacheDir?.trim();
     // Lazy-load node-llama-cpp to keep startup light unless local is enabled.
     const { getLlama, resolveModelFile, LlamaLogLevel } = await importNodeLlamaCpp();
     let llama = null;
     let embeddingModel = null;
     let embeddingContext = null;
-    const ensureContext = async () => {
-        if (!llama) {
-            llama = await getLlama({ logLevel: LlamaLogLevel.error });
-        }
-        if (!embeddingModel) {
-            const resolved = await resolveModelFile(modelPath, modelCacheDir || undefined);
-            embeddingModel = await llama.loadModel({ modelPath: resolved });
-        }
-        if (!embeddingContext) {
-            embeddingContext = await embeddingModel.createEmbeddingContext();
-        }
-        return embeddingContext;
-    };
-    return {
+    const provider = {
         id: "local",
         model: modelPath,
+        state: "idle",
         embedQuery: async (text) => {
             const ctx = await ensureContext();
             const embedding = await ctx.getEmbeddingFor(text);
@@ -60,6 +132,31 @@ async function createLocalEmbeddingProvider(options) {
             return embeddings;
         },
     };
+    const ensureContext = async () => {
+        if (!llama) {
+            // Force CPU-only: GPU backends (Metal on AMD, Vulkan) allocate enormous
+            // memory buffers that dwarf the model itself and can OOM the host.
+            // Embedding models are small enough that CPU inference is fast and safe.
+            llama = await getLlama({ gpu: false, logLevel: LlamaLogLevel.error });
+        }
+        if (!embeddingModel) {
+            try {
+                provider.state = "downloading";
+                const resolved = await resolveModelFileOnce(resolveModelFile, modelPath, modelCacheDir);
+                embeddingModel = await llama.loadModel({ modelPath: resolved, gpuLayers: 0 });
+            }
+            catch (err) {
+                provider.state = "error";
+                throw err;
+            }
+        }
+        if (!embeddingContext) {
+            embeddingContext = await embeddingModel.createEmbeddingContext();
+        }
+        provider.state = "ready";
+        return embeddingContext;
+    };
+    return provider;
 }
 export async function createEmbeddingProvider(options) {
     const requestedProvider = options.provider;
@@ -78,36 +175,48 @@ export async function createEmbeddingProvider(options) {
     };
     const formatPrimaryError = (err, provider) => provider === "local" ? formatLocalSetupError(err) : formatError(err);
     if (requestedProvider === "auto") {
-        const missingKeyErrors = [];
-        let localError = null;
+        const errors = [];
+        // 1. If user configured an explicit local model file, try it first.
         if (canAutoSelectLocal(options)) {
             try {
                 const local = await createProvider("local");
                 return { ...local, requestedProvider };
             }
             catch (err) {
-                localError = formatLocalSetupError(err);
+                errors.push(formatLocalSetupError(err));
             }
         }
-        for (const provider of ["openai", "gemini"]) {
+        // 2. Try remote providers — preferred when API keys are available
+        //    (faster, no RAM overhead, no model download).
+        //    Only consider providers whose key is in the config (apiKeys section).
+        //    Environment variables are ignored for auto-selection to avoid using
+        //    stale dev keys that would fail at runtime.
+        const remoteProviders = [
+            { id: "openai", configKey: "openai" },
+            { id: "gemini", configKey: "google" },
+        ];
+        for (const { id, configKey } of remoteProviders) {
+            if (!getCustomProviderApiKey(options.config, configKey))
+                continue;
             try {
-                const result = await createProvider(provider);
+                const result = await createProvider(id);
                 return { ...result, requestedProvider };
             }
             catch (err) {
-                const message = formatPrimaryError(err, provider);
-                if (isMissingApiKeyError(err)) {
-                    missingKeyErrors.push(message);
-                    continue;
-                }
-                throw new Error(message);
+                errors.push(formatPrimaryError(err, id));
             }
         }
-        const details = [...missingKeyErrors, localError].filter(Boolean);
-        if (details.length > 0) {
-            throw new Error(details.join("\n\n"));
+        // 3. Fall back to local (downloads default model on first use).
+        try {
+            const local = await createProvider("local");
+            return { ...local, requestedProvider };
+        }
+        catch (err) {
+            errors.push(formatLocalSetupError(err));
         }
-        throw new Error("No embeddings provider available.");
+        throw new Error(errors.length > 0
+            ? errors.join("\n\n")
+            : "No embeddings provider available.");
     }
     try {
         const primary = await createProvider(requestedProvider);

package/dist/memory/manager.js

@@ -670,6 +670,7 @@ export class MemoryIndexManager {
             requestedProvider: this.requestedProvider,
             sources: Array.from(this.sources),
             sourceCounts,
+            embeddingState: this.provider.state,
             cache: this.cache.enabled
                 ? {
                     enabled: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/taskmaster",
-  "version": "1.0.65",
+  "version": "1.0.67",
   "description": "AI-powered business assistant for small businesses",
   "publishConfig": {
     "access": "public"

package/taskmaster-docs/USER-GUIDE.md

@@ -533,6 +533,8 @@ All files are markdown (`.md`) — plain text with simple formatting. You can up
 
 When you add or change a file, your assistant picks it up automatically — no restart needed. The status light on the Files page turns red when files have changed since the last index, so you can see at a glance whether a re-index is needed.
 
+After a fresh install or upgrade, the embedding model downloads automatically (~640 MB for most devices, larger on devices with more RAM). During the download, a full-screen overlay blocks all navigation with a "Downloading embedding model" message — this is a one-time download and typically takes a few minutes. Memory search is unavailable until the download completes.
+
 When your assistant writes to **public/** or **shared/**, a shield icon appears in the navigation bar so you can review what was written (see [Data Safety Alert](#data-safety-alert) above).
 
 ### Searching Memory
@@ -1265,6 +1267,57 @@ If the page loses connection during the update and doesn't reconnect within two
 
 ---
 
+## Command Line (CLI)
+
+Taskmaster includes a command-line tool called `taskmaster` that you can run in a terminal (Terminal on Mac, or via SSH on a Pi). You don't need the command line for day-to-day use — the Control Panel handles everything — but it's useful for troubleshooting, updating when the Control Panel isn't accessible, or automating tasks.
+
+### How to access the terminal
+
+- **Mac:** Open **Terminal** (search for "Terminal" in Spotlight)
+- **Raspberry Pi (direct):** Plug in a keyboard and monitor, open Terminal from the taskbar
+- **Raspberry Pi (remote):** From another computer, run `ssh admin@taskmaster.local` (replace `taskmaster` with your hostname if changed)
+
+### Essential commands
+
+| Command | What it does |
+|---------|-------------|
+| `taskmaster update` | Update to the latest version and restart the service |
+| `taskmaster daemon restart` | Restart the gateway service (picks up code and config changes) |
+| `taskmaster daemon status` | Check if the gateway service is running |
+| `taskmaster doctor` | Run health checks and fix common issues automatically |
+| `taskmaster status` | Show connection status for all channels (WhatsApp, Claude, etc.) |
+| `taskmaster dashboard` | Open the Control Panel in your browser |
+
+### Configuration commands
+
+| Command | What it does |
+|---------|-------------|
+| `taskmaster config set <key> <value>` | Change a config setting (e.g., `taskmaster config set gateway.port 19000`) |
+| `taskmaster config get <key>` | Read a config setting |
+| `taskmaster config` | Open the interactive config wizard |
+
+### When to use the CLI instead of the Control Panel
+
+- **Can't reach the Control Panel** — If the web UI is down, SSH into the device and use CLI commands to restart or update
+- **Updating from a specific version** — `taskmaster update` works even when the Control Panel can't load
+- **Changing network settings** — Port and hostname changes require the terminal (see "Changing Network Settings" above)
+- **Diagnosing problems** — `taskmaster doctor` runs automated health checks that can detect and fix issues the UI can't show
+- **Scripting and automation** — CLI commands can be combined in scripts for advanced setups
+
+### Getting help for any command
+
+Add `--help` to any command to see its options:
+
+```bash
+taskmaster update --help
+taskmaster daemon --help
+taskmaster config set --help
+```
+
+Or run `taskmaster help` to see all available commands.
+
+---
+
 ## Uninstalling Taskmaster
 
 ### From the Control Panel