alvin-bot 4.17.0 → 4.18.1

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.18.1] — 2026-04-20
+
+### 🔒 Privacy-Guard: pre-publish check blocks PII leaks in shipped files
+
+Adds an automated gate that runs on every `npm publish` and prevents personal information from accidentally shipping. After the 4.18.0 privacy sanitization, this ensures it never happens again.
+
+**New:**
+- `scripts/privacy-check.sh` — scans the exact file list that `npm pack` would ship. Case-insensitive regex match against a patterns file. Any hit fails the publish.
+- `scripts/privacy-patterns.default.txt` — bundled, contains only generic patterns (email shape, IP addresses, postal codes, personal task phrasings). No project or person names — so safe to ship.
+- `package.json` `prepublishOnly` hook — runs the check automatically.
+- `npm run privacy-check` — manual run anytime.
+
+**Maintainer-local overrides:** Put `~/.alvin-bot/privacy-patterns.txt` with personal/project-specific patterns. That file is gitignored, never leaves your machine, and takes precedence over the bundled defaults.
+
+**CI override:** Set `$ALVIN_PRIVACY_PATTERNS` to an absolute path; takes top precedence over both files above.
+
+**Hardening: `.npmignore`** — added `test/` and `vitest.config.ts` to the ignore list. Previously the full test suite shipped with every npm tarball, adding ~2 MB and exposing test fixtures that sometimes referenced internal project names.
+
+**CLAUDE.md** — documents the rule and the patterns-file lookup order so future maintenance sessions catch new cases proactively.
+
+## [4.18.0] — 2026-04-20
+
+### ⚡ Performance + Hardening: medium-priority cleanups from the stability audit
+
+Completes the audit work started in 4.17.0 by addressing the remaining medium-severity findings.
+
+**Performance (hot path):**
+- **User profiles now cached in memory** (`src/services/users.ts`). Previously `touchProfile` — called on every inbound message — did a sync `readFileSync` + `writeFileSync` on disk. Now it updates an in-memory cache and schedules a debounced flush (2s batch window). A final flush runs on graceful shutdown so nothing is lost. Drops 2 blocking fs operations per message.
+- **Embeddings index now cached** (`src/services/embeddings.ts`). Semantic search previously re-read + re-parsed the full on-disk index on every query (100+ MB for large memories). Now cached in memory with mtime-based invalidation — external reindexers still picked up without a restart.
+- **Skills no longer force-reload every 5 minutes** (`src/services/skills.ts`). `getSkills()` used to re-scan the disk after 5min even though `fs.watch` already triggers hot-reload on change. Cache is now authoritative.
+
+**Hardening (unbounded growth):**
+- **Sub-agents map capped at 1000** (`src/services/subagents.ts`). Hits the 90%-target on overflow and evicts oldest delivered/terminated entries first. Running agents are never evicted.
+- **Async-agent pending map capped at 500** (`src/services/async-agent-watcher.ts`). Same LRU strategy for orphaned `registerPending` entries.
+- **Browser gateway + MCP subprocess stderr now have error handlers** (`browser-manager.ts`, `mcp.ts`). Previously a stream error would throw unhandled and could crash the node process.
+
+**Net effect:** message path now does zero blocking fs reads/writes on the profile/skills/embeddings side. Long-running installs can't grow the in-memory state beyond the caps. No API changes.
+
 ## [4.17.0] — 2026-04-20
 
 ### 🛡️ Hardening: long-running stability audit + leak fixes
@@ -151,8 +189,8 @@ The three aliased entries all route through `ClaudeSDKProvider` with different `
 
 ```yaml
 ---
-purpose: Interview prep
-cwd: ~/Documents/Interviews
+purpose: my-project
+cwd: ~/Projects/my-project
 model: sonnet           # opus | sonnet | haiku | claude-opus-4-7 | ...
 ---
 ```

package/bin/cli.js

@@ -1828,7 +1828,7 @@ switch (cmd) {
     const searchQuery = process.argv.slice(3).join(" ");
     if (!searchQuery) {
       console.log("Usage: alvin-bot search <query>");
-      console.log('Example: alvin-bot search "cover letter"');
+      console.log('Example: alvin-bot search "tax document 2024"');
       process.exit(1);
     }
     const { searchSelf, formatSearchResults } = await import("../dist/services/self-search.js");

package/dist/index.js

@@ -158,6 +158,7 @@ import { discoverTools } from "./services/tool-discovery.js";
 import { startHeartbeat, stopHeartbeat } from "./services/heartbeat.js";
 import { stopAutoUpdateLoop } from "./services/updater.js";
 import { startCleanupLoop, stopCleanupLoop } from "./services/disk-cleanup.js";
+import { flushProfiles } from "./services/users.js";
 import { initEmbeddings } from "./services/embeddings.js";
 import { loadSkills } from "./services/skills.js";
 import { loadHooks } from "./services/hooks.js";
@@ -344,6 +345,12 @@ const shutdown = async () => {
     // The debounced timer might be pending; flushSessions() cancels it and writes
     // synchronously so the next boot can rehydrate the latest state.
     await flushSessions().catch((err) => console.warn("[shutdown] flushSessions failed:", err));
+    try {
+        flushProfiles();
+    }
+    catch (err) {
+        console.warn("[shutdown] flushProfiles failed:", err);
+    }
     if (queueInterval)
         clearInterval(queueInterval);
     if (queueCleanupInterval)

package/dist/services/async-agent-watcher.js

@@ -62,6 +62,28 @@ function getMissingFileFailureMs() {
 const pending = new Map();
 let pollTimer = null;
 let started = false;
+/**
+ * Hard cap on the pending-agents map. Without this, a bot that runs many
+ * async agents but sees some fail to write their outputFile would see
+ * entries linger up to `giveUpAt` (12h default). If the rate of
+ * registerPending() outpaces resolutions for days, memory and the disk
+ * state file grow unbounded. We evict oldest-first when over the cap.
+ */
+const MAX_PENDING_AGENTS = 500;
+function enforcePendingCap() {
+    if (pending.size < MAX_PENDING_AGENTS)
+        return;
+    const entries = [...pending.entries()].sort((a, b) => a[1].startedAt - b[1].startedAt);
+    const target = Math.floor(MAX_PENDING_AGENTS * 0.9);
+    let toEvict = pending.size - target;
+    for (const [id] of entries) {
+        if (toEvict <= 0)
+            break;
+        pending.delete(id);
+        toEvict--;
+    }
+    console.warn(`[async-agent-watcher] pending map hit cap ${MAX_PENDING_AGENTS}, evicted to ${pending.size}`);
+}
 // ── Persistence ───────────────────────────────────────────────────
 function loadFromDisk() {
     try {
@@ -110,6 +132,7 @@ export function registerPendingAgent(input) {
         sessionKey: input.sessionKey,
         platform: input.platform,
     };
+    enforcePendingCap();
     pending.set(input.agentId, entry);
     saveToDisk();
 }

package/dist/services/browser-manager.js

@@ -233,6 +233,17 @@ async function ensureGateway() {
     gatewayProcess.on("exit", () => {
         gatewayProcess = null;
     });
+    // Surface spawn failures so we don't silently think the gateway is running.
+    gatewayProcess.on("error", (err) => {
+        log(`gateway spawn error: ${err.message}`);
+        gatewayProcess = null;
+    });
+    // Drain stdio pipes — otherwise stdout/stderr buffer fills and the child
+    // blocks on write. We don't care about the content (just that they drain).
+    gatewayProcess.stdout?.on("error", () => { });
+    gatewayProcess.stderr?.on("error", () => { });
+    gatewayProcess.stdout?.resume();
+    gatewayProcess.stderr?.resume();
     // Wait for startup (max 10s)
     for (let i = 0; i < 20; i++) {
         await new Promise((r) => setTimeout(r, 500));

package/dist/services/embeddings.js

@@ -143,12 +143,26 @@ function chunkMarkdown(content, source) {
     return chunks;
 }
 // ── Index Management ────────────────────────────────────
+// In-memory cache for the embedding index. Without this, every query would
+// re-read and re-parse the on-disk index (can be 100+ MB, making searchMemory
+// the slowest step in a message turn). We keep the parsed object and invalidate
+// via mtime check — so external reindexers are still picked up.
+let indexCache = null;
+let indexCacheMtime = 0;
 function loadIndex() {
     try {
+        const st = fs.statSync(INDEX_FILE);
+        if (indexCache && st.mtimeMs === indexCacheMtime) {
+            return indexCache;
+        }
         const raw = fs.readFileSync(INDEX_FILE, "utf-8");
-        return JSON.parse(raw);
+        indexCache = JSON.parse(raw);
+        indexCacheMtime = st.mtimeMs;
+        return indexCache;
     }
     catch {
+        // File missing or unparseable — return an empty index and don't cache it
+        // (next call will retry, so a freshly-written index gets picked up).
         return {
             model: EMBEDDING_MODEL,
             lastReindex: 0,
@@ -159,6 +173,15 @@ function loadIndex() {
 }
 function saveIndex(index) {
     fs.writeFileSync(INDEX_FILE, JSON.stringify(index));
+    // Refresh cache immediately so the next loadIndex() sees the new state
+    // without a disk round-trip.
+    indexCache = index;
+    try {
+        indexCacheMtime = fs.statSync(INDEX_FILE).mtimeMs;
+    }
+    catch {
+        indexCacheMtime = Date.now();
+    }
 }
 /**
  * Recursively walk a directory, returning file paths.

package/dist/services/mcp.js

@@ -116,6 +116,17 @@ async function connectStdio(name, config) {
         proc.stderr.on("data", (data) => {
             console.error(`MCP ${name} stderr:`, data.toString().trim());
         });
+        // Surface stderr stream errors so we don't silently lose the channel
+        // (EPIPE, ECONNRESET etc). Without this, unhandled 'error' on the
+        // stream would crash the whole Node process.
+        proc.stderr.on("error", (err) => {
+            console.error(`MCP ${name} stderr stream error:`, err.message);
+            server.connected = false;
+        });
+        proc.stdout?.on("error", (err) => {
+            console.error(`MCP ${name} stdout stream error:`, err.message);
+            server.connected = false;
+        });
         proc.on("error", (err) => {
             console.error(`MCP ${name} process error:`, err);
             server.connected = false;

package/dist/services/skills.js

@@ -167,10 +167,12 @@ export function loadSkills() {
     return cachedSkills;
 }
 /**
- * Get all loaded skills.
+ * Get all loaded skills. Cached after the first loadSkills() call; hot-reload
+ * happens via fs.watch when files change on disk. We only force a scan here if
+ * the cache is empty (init-order edge case).
  */
 export function getSkills() {
-    if (cachedSkills.length === 0 || Date.now() - lastScanAt > 300_000) {
+    if (cachedSkills.length === 0) {
         reloadAllSkills();
     }
     return cachedSkills;

package/dist/services/subagents.js

@@ -128,6 +128,43 @@ export function setDefaultTimeoutMs(ms) {
 }
 // ── State ───────────────────────────────────────────────
 const activeAgents = new Map();
+/**
+ * Hard cap on the activeAgents map. Without this, a long-running bot that
+ * spawns many agents (e.g. a chatty cron + manual triggers over months) would
+ * accumulate delivered entries indefinitely. The 30-min auto-cleanup inside
+ * runSubAgent only fires on graceful completion, so crashed/orphaned entries
+ * would linger until the 12h giveUpAt ceiling.
+ *
+ * Enforcement: whenever we insert a new entry and the map is at-or-over the
+ * cap, evict the oldest finished-and-delivered entries first. Running agents
+ * are never evicted.
+ */
+const MAX_ACTIVE_AGENTS = 1000;
+function enforceAgentCap() {
+    if (activeAgents.size < MAX_ACTIVE_AGENTS)
+        return;
+    // Collect evictable entries (delivered OR terminal status), sort by startedAt
+    const evictable = [];
+    for (const [id, entry] of activeAgents) {
+        const status = entry.info.status;
+        const done = entry.delivered || status === "error" || status === "timeout" || status === "cancelled";
+        if (done)
+            evictable.push([id, entry.info.startedAt]);
+    }
+    evictable.sort((a, b) => a[1] - b[1]);
+    // Evict enough to land 10% below the cap, so we don't oscillate.
+    const target = Math.floor(MAX_ACTIVE_AGENTS * 0.9);
+    let toEvict = activeAgents.size - target;
+    for (const [id] of evictable) {
+        if (toEvict <= 0)
+            break;
+        activeAgents.delete(id);
+        toEvict--;
+    }
+    if (toEvict > 0) {
+        console.warn(`[subagents] map at ${activeAgents.size}/${MAX_ACTIVE_AGENTS} — could not evict enough finished entries (too many still running)`);
+    }
+}
 // ── Name resolver (B2) ──────────────────────────────────
 /**
  * Return all currently-tracked agents whose *base* name matches `base`.
@@ -563,6 +600,7 @@ export function spawnSubAgent(agentConfig) {
         nameIndex: resolved.index,
         queuePosition: willRunImmediately ? undefined : queuedLen + 1,
     };
+    enforceAgentCap();
     activeAgents.set(id, { info, abort, delivered: false });
     const queuedSpawn = { id, resolvedName, agentConfig, depth, timeoutId };
     if (willRunImmediately) {

package/dist/services/users.js

@@ -8,6 +8,12 @@
  *
  * The admin/owner user uses the global docs/memory/ and docs/MEMORY.md.
  * Additional users get isolated memory spaces.
+ *
+ * Performance:
+ *   Profiles are cached in memory after first read. `touchProfile` — called
+ *   on every inbound message — writes to cache and schedules a debounced
+ *   disk flush (2s). This avoids two sync fs operations per message on the
+ *   hot path. A final flush happens on graceful shutdown so nothing is lost.
  */
 import fs from "fs";
 import { resolve } from "path";
@@ -18,6 +24,42 @@ import { USERS_DIR, MEMORY_DIR } from "../paths.js";
 // Ensure users dir exists
 if (!fs.existsSync(USERS_DIR))
     fs.mkdirSync(USERS_DIR, { recursive: true });
+// ── In-memory cache + debounced persistence ─────────────
+const cache = new Map();
+const dirty = new Set();
+let flushTimer = null;
+const FLUSH_DELAY_MS = 2000;
+function schedule_flush() {
+    if (flushTimer)
+        return;
+    flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flushProfiles();
+    }, FLUSH_DELAY_MS);
+    flushTimer.unref?.();
+}
+/**
+ * Write every dirty profile to disk synchronously. Called by the debounce
+ * timer AND by the graceful-shutdown handler so no in-flight updates are
+ * lost even if the bot exits between debounce ticks.
+ */
+export function flushProfiles() {
+    if (dirty.size === 0)
+        return;
+    for (const userId of dirty) {
+        const profile = cache.get(userId);
+        if (!profile)
+            continue;
+        try {
+            fs.writeFileSync(profilePath(userId), JSON.stringify(profile, null, 2));
+        }
+        catch (err) {
+            // Don't throw — a persistent error would block future flushes.
+            console.warn(`[users] flush ${userId} failed: ${err.message}`);
+        }
+    }
+    dirty.clear();
+}
 // ── Profile Management ──────────────────────────────────
 function profilePath(userId) {
     return resolve(USERS_DIR, `${userId}.json`);
@@ -26,22 +68,32 @@ function userMemoryDir(userId) {
     return resolve(USERS_DIR, `${userId}`);
 }
 /**
- * Load a user profile. Returns null if not found.
+ * Load a user profile. Returns null if not found. Reads from cache first,
+ * falls back to disk on cache miss.
  */
 export function loadProfile(userId) {
+    const cached = cache.get(userId);
+    if (cached)
+        return cached;
     try {
         const raw = fs.readFileSync(profilePath(userId), "utf-8");
-        return JSON.parse(raw);
+        const profile = JSON.parse(raw);
+        cache.set(userId, profile);
+        return profile;
     }
     catch {
         return null;
     }
 }
 /**
- * Save a user profile.
+ * Save a user profile — updates cache and schedules a debounced disk flush.
+ * For immediate durability (e.g. during shutdown), call flushProfiles()
+ * after this.
  */
 export function saveProfile(profile) {
-    fs.writeFileSync(profilePath(profile.userId), JSON.stringify(profile, null, 2));
+    cache.set(profile.userId, profile);
+    dirty.add(profile.userId);
+    schedule_flush();
 }
 /**
  * Get or create a user profile.
@@ -76,6 +128,9 @@ export function getOrCreateProfile(userId, name, username) {
 }
 /**
  * Update a user's activity (call on each message).
+ *
+ * Previously this did a sync read + write per message. Now it works purely
+ * in memory and lets the debounce timer batch writes to disk.
  */
 export function touchProfile(userId, name, username, platform, messageText) {
     const profile = getOrCreateProfile(userId, name, username);
@@ -95,20 +150,33 @@ export function touchProfile(userId, name, username, platform, messageText) {
     return profile;
 }
 /**
- * List all known user profiles.
+ * List all known user profiles. Reads from disk; populates cache for
+ * subsequent fast access.
  */
 export function listProfiles() {
     const profiles = [];
     try {
         const files = fs.readdirSync(USERS_DIR);
         for (const file of files) {
-            if (file.endsWith(".json")) {
-                try {
-                    const raw = fs.readFileSync(resolve(USERS_DIR, file), "utf-8");
-                    profiles.push(JSON.parse(raw));
-                }
-                catch { /* skip corrupt */ }
+            if (!file.endsWith(".json"))
+                continue;
+            // Parse user id from filename — skip non-numeric (e.g. stray files)
+            const userId = parseInt(file.slice(0, -5), 10);
+            if (!Number.isFinite(userId))
+                continue;
+            // If cached, use that; otherwise read once and cache
+            const cached = cache.get(userId);
+            if (cached) {
+                profiles.push(cached);
+                continue;
+            }
+            try {
+                const raw = fs.readFileSync(resolve(USERS_DIR, file), "utf-8");
+                const p = JSON.parse(raw);
+                cache.set(userId, p);
+                profiles.push(p);
             }
+            catch { /* skip corrupt */ }
         }
     }
     catch { /* dir doesn't exist */ }
@@ -145,6 +213,9 @@ export function addUserNote(userId, note) {
 export function deleteUser(userId) {
     const deleted = [];
     const errors = [];
+    // 0. Drop from cache + dirty set so the debounce doesn't re-create the file
+    cache.delete(userId);
+    dirty.delete(userId);
     // 1. Delete profile JSON
     const pPath = profilePath(userId);
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.17.0",
+  "version": "4.18.1",
   "description": "Alvin Bot \u2014 Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,6 +15,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
+    "privacy-check": "bash scripts/privacy-check.sh",
+    "prepublishOnly": "bash scripts/privacy-check.sh",
     "electron:compile": "tsc -p electron/tsconfig.json",
     "electron:dev": "npm run electron:compile && electron .",
     "electron:build": "npm run build && npm run electron:compile && electron-builder --publish never",

package/test/allowed-users-gate.test.ts

@@ -1,98 +0,0 @@
-/**
- * v4.12.2 — ALLOWED_USERS startup hard-fail gate.
- *
- * When the Telegram bot token is configured but ALLOWED_USERS is empty,
- * starting the bot would leave it open to any Telegram user sending a DM.
- * Previously this only emitted a console.warn and the bot started anyway.
- *
- * v4.12.2 introduces a pure gate function that decides whether to refuse
- * startup, with two explicit escape hatches:
- *   1. AUTH_MODE=open — user explicitly wants an open bot
- *   2. ALVIN_INSECURE_ACKNOWLEDGED=1 — explicit opt-out for test/scripted envs
- *
- * This test file exercises the pure gate. The actual wiring in src/index.ts
- * is a thin if-block that calls process.exit(1) on deny.
- */
-import { describe, it, expect } from "vitest";
-import { checkAllowedUsersGate } from "../src/services/allowed-users-gate.js";
-
-describe("allowed-users-gate (v4.12.2)", () => {
-  it("allows startup when ALLOWED_USERS is populated", () => {
-    const result = checkAllowedUsersGate({
-      hasTelegram: true,
-      allowedUsersCount: 1,
-      authMode: "allowlist",
-      insecureAcknowledged: false,
-    });
-    expect(result.allowed).toBe(true);
-    expect(result.reason).toBeUndefined();
-  });
-
-  it("BLOCKS startup when telegram enabled but allowedUsers empty (allowlist mode)", () => {
-    const result = checkAllowedUsersGate({
-      hasTelegram: true,
-      allowedUsersCount: 0,
-      authMode: "allowlist",
-      insecureAcknowledged: false,
-    });
-    expect(result.allowed).toBe(false);
-    expect(result.reason).toContain("ALLOWED_USERS");
-  });
-
-  it("BLOCKS startup when telegram enabled but allowedUsers empty (pairing mode)", () => {
-    // Pairing mode needs allowedUsers[0] as the admin for approval routing.
-    // Empty array breaks the whole pairing flow.
-    const result = checkAllowedUsersGate({
-      hasTelegram: true,
-      allowedUsersCount: 0,
-      authMode: "pairing",
-      insecureAcknowledged: false,
-    });
-    expect(result.allowed).toBe(false);
-  });
-
-  it("ALLOWS startup when AUTH_MODE=open explicitly", () => {
-    const result = checkAllowedUsersGate({
-      hasTelegram: true,
-      allowedUsersCount: 0,
-      authMode: "open",
-      insecureAcknowledged: false,
-    });
-    expect(result.allowed).toBe(true);
-    expect(result.warning).toContain("open");
-  });
-
-  it("ALLOWS startup when ALVIN_INSECURE_ACKNOWLEDGED=1", () => {
-    const result = checkAllowedUsersGate({
-      hasTelegram: true,
-      allowedUsersCount: 0,
-      authMode: "allowlist",
-      insecureAcknowledged: true,
-    });
-    expect(result.allowed).toBe(true);
-    expect(result.warning).toContain("INSECURE");
-  });
-
-  it("ALLOWS startup when telegram is NOT enabled (bot is WebUI-only)", () => {
-    // WebUI-only deployments don't have a BOT_TOKEN and don't need
-    // ALLOWED_USERS — the gate only applies when hasTelegram === true.
-    const result = checkAllowedUsersGate({
-      hasTelegram: false,
-      allowedUsersCount: 0,
-      authMode: "allowlist",
-      insecureAcknowledged: false,
-    });
-    expect(result.allowed).toBe(true);
-  });
-
-  it("reason message mentions ~/.alvin-bot/.env and @userinfobot for operator guidance", () => {
-    const result = checkAllowedUsersGate({
-      hasTelegram: true,
-      allowedUsersCount: 0,
-      authMode: "allowlist",
-      insecureAcknowledged: false,
-    });
-    expect(result.reason).toMatch(/\.env|alvin-bot/i);
-    expect(result.reason).toMatch(/userinfobot|telegram/i);
-  });
-});