alvin-bot 4.18.0 → 4.18.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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
@@ -169,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.18.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);
-  });
-});

package/test/alvin-dispatch.test.ts

@@ -1,220 +0,0 @@
-/**
- * v4.13 — alvin_dispatch custom-tool service.
- *
- * `dispatchDetachedAgent(input)` spawns a truly independent `claude -p`
- * subprocess that survives the parent handler's abort. This is the
- * architectural replacement for SDK's built-in Task(run_in_background)
- * tool, which was tied to the parent SDK subprocess lifecycle.
- *
- * Contract:
- *   - Input: { prompt, description, chatId, userId, sessionKey }
- *   - Output (synchronous): { agentId, outputFile, spawned: true }
- *   - Side effect: spawns detached subprocess writing stream-json
- *     output to outputFile, registers with async-agent-watcher.
- *
- * These tests stub child_process.spawn so they run fast and deterministic.
- * The "real subprocess survives parent" property was verified empirically
- * in Phase A (see plan doc).
- */
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import os from "os";
-import fs from "fs";
-import { resolve } from "path";
-
-const TEST_DATA_DIR = resolve(
-  os.tmpdir(),
-  `alvin-dispatch-${process.pid}-${Date.now()}`,
-);
-
-interface SpawnRecord {
-  cmd: string;
-  args: string[];
-  opts: {
-    detached?: boolean;
-    stdio?: unknown;
-    cwd?: string;
-    env?: Record<string, string | undefined>;
-  };
-  unreffed: boolean;
-}
-
-let spawned: SpawnRecord[] = [];
-
-beforeEach(async () => {
-  if (fs.existsSync(TEST_DATA_DIR))
-    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
-  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
-  process.env.ALVIN_DATA_DIR = TEST_DATA_DIR;
-  spawned = [];
-  vi.resetModules();
-
-  vi.doMock("node:child_process", async () => {
-    const actual = await vi.importActual<typeof import("node:child_process")>(
-      "node:child_process",
-    );
-    return {
-      ...actual,
-      spawn: (cmd: string, args: string[], opts: SpawnRecord["opts"]) => {
-        const record: SpawnRecord = {
-          cmd,
-          args,
-          opts,
-          unreffed: false,
-        };
-        spawned.push(record);
-        return {
-          pid: 12345,
-          unref() {
-            record.unreffed = true;
-          },
-          on() {},
-          kill() {},
-        };
-      },
-    };
-  });
-
-  vi.doMock("../src/services/subagent-delivery.js", () => ({
-    deliverSubAgentResult: async () => {},
-    attachBotApi: () => {},
-    __setBotApiForTest: () => {},
-  }));
-});
-
-afterEach(async () => {
-  try {
-    const mod = await import("../src/services/async-agent-watcher.js");
-    mod.stopWatcher();
-    mod.__resetForTest();
-  } catch {
-    /* ignore */
-  }
-});
-
-describe("dispatchDetachedAgent (v4.13)", () => {
-  it("spawns claude -p with detached: true and unrefs", async () => {
-    const mod = await import("../src/services/alvin-dispatch.js");
-    const result = mod.dispatchDetachedAgent({
-      prompt: "research X",
-      description: "X research",
-      chatId: 42,
-      userId: 42,
-      sessionKey: "s1",
-    });
-    expect(result.agentId).toMatch(/^alvin-[a-f0-9]{16,}$/);
-    expect(result.outputFile).toContain(TEST_DATA_DIR);
-    expect(result.spawned).toBe(true);
-
-    expect(spawned).toHaveLength(1);
-    const [s] = spawned;
-    expect(s.cmd).toMatch(/claude/);
-    expect(s.args).toContain("-p");
-    expect(s.args).toContain("research X");
-    expect(s.args).toContain("--output-format");
-    expect(s.args).toContain("stream-json");
-    expect(s.opts.detached).toBe(true);
-    expect(s.unreffed).toBe(true);
-  });
-
-  it("returns unique agentIds for concurrent dispatches", async () => {
-    const mod = await import("../src/services/alvin-dispatch.js");
-    const r1 = mod.dispatchDetachedAgent({
-      prompt: "a",
-      description: "a",
-      chatId: 1,
-      userId: 1,
-      sessionKey: "s1",
-    });
-    const r2 = mod.dispatchDetachedAgent({
-      prompt: "b",
-      description: "b",
-      chatId: 1,
-      userId: 1,
-      sessionKey: "s1",
-    });
-    expect(r1.agentId).not.toBe(r2.agentId);
-    expect(r1.outputFile).not.toBe(r2.outputFile);
-  });
-
-  it("registers the pending agent with the watcher", async () => {
-    const mod = await import("../src/services/alvin-dispatch.js");
-    const watcher = await import("../src/services/async-agent-watcher.js");
-
-    mod.dispatchDetachedAgent({
-      prompt: "x",
-      description: "X audit",
-      chatId: 42,
-      userId: 42,
-      sessionKey: "s1",
-    });
-
-    const pending = watcher.listPendingAgents();
-    expect(pending).toHaveLength(1);
-    expect(pending[0].description).toBe("X audit");
-    expect(pending[0].sessionKey).toBe("s1");
-  });
-
-  it("increments session.pendingBackgroundCount on dispatch", async () => {
-    const mod = await import("../src/services/alvin-dispatch.js");
-    const { getSession } = await import("../src/services/session.js");
-
-    const session = getSession("s-count");
-    session.pendingBackgroundCount = 0;
-
-    mod.dispatchDetachedAgent({
-      prompt: "p",
-      description: "d",
-      chatId: 1,
-      userId: 1,
-      sessionKey: "s-count",
-    });
-    expect(session.pendingBackgroundCount).toBe(1);
-
-    mod.dispatchDetachedAgent({
-      prompt: "p2",
-      description: "d2",
-      chatId: 1,
-      userId: 1,
-      sessionKey: "s-count",
-    });
-    expect(session.pendingBackgroundCount).toBe(2);
-  });
-
-  it("uses stdio redirect so child's stdout goes to outputFile", async () => {
-    const mod = await import("../src/services/alvin-dispatch.js");
-    mod.dispatchDetachedAgent({
-      prompt: "p",
-      description: "d",
-      chatId: 1,
-      userId: 1,
-      sessionKey: "s1",
-    });
-    const [s] = spawned;
-    // stdio should be an array with FD redirects (ignore, pipe-to-file, ignore)
-    // or similar. We verify it's NOT "inherit" (which would attach to parent).
-    expect(s.opts.stdio).not.toBe("inherit");
-    expect(s.opts.stdio).not.toBe(undefined);
-  });
-
-  it("cleans env of CLAUDECODE/CLAUDE_CODE_ENTRYPOINT to prevent nested session errors", async () => {
-    const mod = await import("../src/services/alvin-dispatch.js");
-    process.env.CLAUDECODE = "1";
-    process.env.CLAUDE_CODE_ENTRYPOINT = "cli";
-    try {
-      mod.dispatchDetachedAgent({
-        prompt: "p",
-        description: "d",
-        chatId: 1,
-        userId: 1,
-        sessionKey: "s1",
-      });
-      const [s] = spawned;
-      expect(s.opts.env).toBeDefined();
-      expect(s.opts.env?.CLAUDECODE).toBeUndefined();
-      expect(s.opts.env?.CLAUDE_CODE_ENTRYPOINT).toBeUndefined();
-    } finally {
-      delete process.env.CLAUDECODE;
-      delete process.env.CLAUDE_CODE_ENTRYPOINT;
-    }
-  });
-});

package/test/async-agent-chunk-flow.test.ts

@@ -1,244 +0,0 @@
-/**
- * Fix #17 (Stage 2) — when the SDK yields a tool_result chunk with an
- * "Async agent launched successfully" payload, the message handler
- * must register the pending agent with the watcher.
- *
- * This tests the helper `handleToolResultChunk` in isolation —
- * the integration with message.ts is covered by the live e2e test.
- */
-import { describe, it, expect, beforeEach, vi } from "vitest";
-
-describe("async agent chunk flow (Stage 2)", () => {
-  beforeEach(() => vi.resetModules());
-
-  it("tool_result with async_launched gets registered with the watcher", async () => {
-    const registered: unknown[] = [];
-    vi.doMock("../src/services/async-agent-watcher.js", () => ({
-      registerPendingAgent: (input: unknown) => registered.push(input),
-      startWatcher: () => {},
-      stopWatcher: () => {},
-      pollOnce: async () => {},
-      listPendingAgents: () => [],
-    }));
-
-    const { handleToolResultChunk } = await import(
-      "../src/handlers/async-agent-chunk-handler.js"
-    );
-
-    const chunk = {
-      type: "tool_result" as const,
-      toolUseId: "toolu_1",
-      toolResultContent:
-        "Async agent launched successfully.\n" +
-        "agentId: abc-1 (something)\n" +
-        "output_file: /tmp/out-abc-1.jsonl\n" +
-        "If asked, you can check progress.",
-    };
-    handleToolResultChunk(chunk, {
-      chatId: 42,
-      userId: 99,
-      lastToolUseInput: {
-        description: "SEO audit",
-        prompt: "audit example.com",
-      },
-    });
-
-    expect(registered).toHaveLength(1);
-    const r = registered[0] as { agentId: string; description: string; outputFile: string };
-    expect(r.agentId).toBe("abc-1");
-    expect(r.description).toBe("SEO audit");
-    expect(r.outputFile).toBe("/tmp/out-abc-1.jsonl");
-  });
-
-  it("v4.12.3 — passes sessionKey to registerPendingAgent and increments session counter", async () => {
-    const registered: Array<{ sessionKey?: string }> = [];
-    vi.doMock("../src/services/async-agent-watcher.js", () => ({
-      registerPendingAgent: (input: { sessionKey?: string }) =>
-        registered.push(input),
-      startWatcher: () => {},
-      stopWatcher: () => {},
-      pollOnce: async () => {},
-      listPendingAgents: () => [],
-    }));
-
-    const { getSession } = await import("../src/services/session.js");
-    const session = getSession("v412-chunk-test-session");
-    session.pendingBackgroundCount = 0;
-
-    const { handleToolResultChunk } = await import(
-      "../src/handlers/async-agent-chunk-handler.js"
-    );
-    handleToolResultChunk(
-      {
-        type: "tool_result",
-        toolUseId: "toolu_sess",
-        toolResultContent:
-          "Async agent launched successfully.\n" +
-          "agentId: ag-sess\n" +
-          "output_file: /tmp/ag-sess.jsonl\n",
-      },
-      {
-        chatId: 10,
-        userId: 20,
-        sessionKey: "v412-chunk-test-session",
-        lastToolUseInput: { description: "SEO", prompt: "do it" },
-      },
-    );
-
-    expect(registered).toHaveLength(1);
-    expect(registered[0].sessionKey).toBe("v412-chunk-test-session");
-    expect(session.pendingBackgroundCount).toBe(1);
-  });
-
-  it("v4.12.3 — multiple async launches in same turn stack the counter", async () => {
-    vi.doMock("../src/services/async-agent-watcher.js", () => ({
-      registerPendingAgent: () => {},
-      startWatcher: () => {},
-      stopWatcher: () => {},
-      pollOnce: async () => {},
-      listPendingAgents: () => [],
-    }));
-
-    const { getSession } = await import("../src/services/session.js");
-    const session = getSession("v412-chunk-stack");
-    session.pendingBackgroundCount = 0;
-
-    const { handleToolResultChunk } = await import(
-      "../src/handlers/async-agent-chunk-handler.js"
-    );
-
-    for (let i = 0; i < 3; i++) {
-      handleToolResultChunk(
-        {
-          type: "tool_result",
-          toolUseId: `toolu_${i}`,
-          toolResultContent:
-            `Async agent launched successfully.\n` +
-            `agentId: ag-${i}\n` +
-            `output_file: /tmp/ag-${i}.jsonl\n`,
-        },
-        {
-          chatId: 10,
-          userId: 20,
-          sessionKey: "v412-chunk-stack",
-          lastToolUseInput: { description: `task ${i}`, prompt: "p" },
-        },
-      );
-    }
-
-    expect(session.pendingBackgroundCount).toBe(3);
-  });
-
-  it("v4.12.3 — non-async tool_result does not increment the counter", async () => {
-    vi.doMock("../src/services/async-agent-watcher.js", () => ({
-      registerPendingAgent: () => {
-        throw new Error("should not be called");
-      },
-      startWatcher: () => {},
-      stopWatcher: () => {},
-      pollOnce: async () => {},
-      listPendingAgents: () => [],
-    }));
-
-    const { getSession } = await import("../src/services/session.js");
-    const session = getSession("v412-chunk-nonasync");
-    session.pendingBackgroundCount = 0;
-
-    const { handleToolResultChunk } = await import(
-      "../src/handlers/async-agent-chunk-handler.js"
-    );
-    handleToolResultChunk(
-      {
-        type: "tool_result",
-        toolUseId: "toolu_read",
-        toolResultContent: "plain read result — no async_launched marker",
-      },
-      {
-        chatId: 1,
-        userId: 1,
-        sessionKey: "v412-chunk-nonasync",
-        lastToolUseInput: { description: "read", prompt: "p" },
-      },
-    );
-    expect(session.pendingBackgroundCount).toBe(0);
-  });
-
-  it("falls back to a generic description when no toolUseInput is provided", async () => {
-    const registered: unknown[] = [];
-    vi.doMock("../src/services/async-agent-watcher.js", () => ({
-      registerPendingAgent: (input: unknown) => registered.push(input),
-      startWatcher: () => {},
-      stopWatcher: () => {},
-      pollOnce: async () => {},
-      listPendingAgents: () => [],
-    }));
-
-    const { handleToolResultChunk } = await import(
-      "../src/handlers/async-agent-chunk-handler.js"
-    );
-
-    handleToolResultChunk(
-      {
-        type: "tool_result",
-        toolUseId: "toolu_2",
-        toolResultContent:
-          "Async agent launched successfully.\n" +
-          "agentId: x\n" +
-          "output_file: /tmp/o\n",
-      },
-      { chatId: 42, userId: 99 },
-    );
-
-    expect(registered).toHaveLength(1);
-    const r = registered[0] as { description: string };
-    expect(r.description.length).toBeGreaterThan(0);
-  });
-
-  it("non-async tool_result (e.g. Read) is ignored", async () => {
-    const registered: unknown[] = [];
-    vi.doMock("../src/services/async-agent-watcher.js", () => ({
-      registerPendingAgent: (input: unknown) => registered.push(input),
-      startWatcher: () => {},
-      stopWatcher: () => {},
-      pollOnce: async () => {},
-      listPendingAgents: () => [],
-    }));
-
-    const { handleToolResultChunk } = await import(
-      "../src/handlers/async-agent-chunk-handler.js"
-    );
-
-    handleToolResultChunk(
-      {
-        type: "tool_result",
-        toolUseId: "toolu_3",
-        toolResultContent: "file contents here (plain Read result)",
-      },
-      { chatId: 42, userId: 99 },
-    );
-    expect(registered).toHaveLength(0);
-  });
-
-  it("non-tool_result chunks are ignored without throwing", async () => {
-    vi.doMock("../src/services/async-agent-watcher.js", () => ({
-      registerPendingAgent: () => {
-        throw new Error("should not be called");
-      },
-      startWatcher: () => {},
-      stopWatcher: () => {},
-      pollOnce: async () => {},
-      listPendingAgents: () => [],
-    }));
-
-    const { handleToolResultChunk } = await import(
-      "../src/handlers/async-agent-chunk-handler.js"
-    );
-
-    expect(() =>
-      handleToolResultChunk(
-        { type: "text", text: "hi" },
-        { chatId: 42, userId: 99 },
-      ),
-    ).not.toThrow();
-  });
-});