alvin-bot 4.25.1 → 5.0.0

package/dist/services/critical-notify.js

@@ -0,0 +1,203 @@
+/**
+ * Critical-Event Cross-Channel Notify (Self-Preservation Phase 1, feature 1D).
+ *
+ * When something genuinely critical happens — watchdog brake engaged,
+ * repeated Telegram 409s, all providers dead, disk full, memory blow-up —
+ * deliver the alert through a fallback chain so the user actually finds
+ * out even if Telegram (the primary channel) is itself the failure mode.
+ *
+ * Channel cascade — ALL fire, in order of preference:
+ *   1. File flag at ~/.alvin-bot/CRITICAL.log     [durable audit trail, always written]
+ *   2. macOS native notification (osascript)      [if darwin, visible immediately]
+ *   3. Telegram DM to admin (detached curl)       [survives process exit via spawn+unref]
+ *
+ * Order is deliberate: we ALWAYS persist the audit (1) first, so even
+ * if the process crashes mid-notify we have a forensic record. Then we
+ * try the user-facing channels (2, 3) best-effort.
+ *
+ * The Telegram channel uses a detached child `curl` process precisely
+ * because critical events often come paired with process.exit() — most
+ * notably the watchdog brake. A normal in-process fetch() wouldn't
+ * survive parent termination. `spawn + detached + unref` does.
+ *
+ * Performance: ZERO steady-state overhead. Only the file-flag write
+ * runs at all, and only when emitCritical() is called.
+ *
+ * Opt-out:
+ *   ALVIN_DISABLE_CRITICAL_NOTIFY=true     → skip Tier 1/2/3 entirely
+ *   ALVIN_DISABLE_SELF_PRESERVATION=true   → skip ALL Phase-1 features
+ */
+import { spawn, execFileSync, spawnSync } from "child_process";
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function isDisabled() {
+    return (process.env.ALVIN_DISABLE_CRITICAL_NOTIFY === "true" ||
+        process.env.ALVIN_DISABLE_SELF_PRESERVATION === "true");
+}
+function resolveOptions(opts) {
+    const botToken = opts?.botToken ?? process.env.BOT_TOKEN ?? undefined;
+    let adminChatId = opts?.adminChatId;
+    if (adminChatId === undefined && process.env.ALLOWED_USERS) {
+        const first = process.env.ALLOWED_USERS.split(",")[0]?.trim();
+        if (first) {
+            const parsed = parseInt(first, 10);
+            if (Number.isFinite(parsed))
+                adminChatId = parsed;
+        }
+    }
+    return { botToken, adminChatId };
+}
+// ── Tier 3: Durable file flag — ALWAYS written first ──────────────────────
+function writeFileFlag(event) {
+    try {
+        const dir = join(homedir(), ".alvin-bot");
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, "CRITICAL.log");
+        const ts = (event.ts || new Date()).toISOString();
+        const block = [
+            `[${ts}] ${event.severity.toUpperCase()} ${event.category}`,
+            `  ${event.title}`,
+            ...event.detail.split("\n").map((l) => `  ${l}`),
+            ...(event.suggestedAction ? [`  Suggested: ${event.suggestedAction}`] : []),
+            "",
+        ].join("\n");
+        appendFileSync(path, block);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Tier 2: macOS native notification (silent on Linux/Windows) ───────────
+function macosNotification(event) {
+    if (process.platform !== "darwin")
+        return false;
+    try {
+        // Escape any embedded double-quotes for AppleScript string literal
+        const message = `${event.title} — ${event.detail.split("\n")[0]}`.replace(/"/g, '\\"');
+        const title = `Alvin Bot ${event.severity === "critical" ? "🚨" : "⚠️"}`;
+        execFileSync("osascript", ["-e", `display notification "${message}" with title "${title}"`], { timeout: 3000, stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Tier 1: Telegram DM to admin via detached curl ────────────────────────
+//
+// Why detached + curl instead of in-process fetch:
+//   - emitCritical() is sometimes called moments before process.exit()
+//     (notably from the watchdog brake path). In-process async work
+//     would be cancelled.
+//   - A detached child with stdio:'ignore' + unref() outlives its parent
+//     and is the standard pattern for "survive my own death" notifications.
+//   - curl is universally available on macOS + Linux. No node-only deps.
+function telegramAdminDM(event, opts) {
+    if (!opts.botToken || !opts.adminChatId)
+        return false;
+    // Plain text — NOT Markdown. Critical events frequently contain shell
+    // commands in `suggestedAction` (paths with quotes, `&&` chains, etc.)
+    // which break Telegram's Markdown parser with HTTP 400. Reliability >
+    // visual prettiness for an alarm channel. The emoji prefix already
+    // makes it visually obvious.
+    const lines = [
+        `🚨 Alvin Bot — ${event.severity.toUpperCase()}`,
+        "",
+        event.title,
+        "",
+        event.detail,
+    ];
+    if (event.suggestedAction) {
+        lines.push("", `Suggested: ${event.suggestedAction}`);
+    }
+    const text = lines.join("\n");
+    const curlArgs = [
+        "-s",
+        "-o", "/dev/null",
+        "-X", "POST",
+        "--max-time", "5",
+        `https://api.telegram.org/bot${opts.botToken}/sendMessage`,
+        "-d", `chat_id=${opts.adminChatId}`,
+        "--data-urlencode", `text=${text}`,
+    ];
+    if (opts.blockTelegram) {
+        // Synchronous: caller is about to process.exit(). spawnSync blocks
+        // up to max-time + a small buffer, then returns. Guaranteed delivery
+        // attempt — no fork-race with process termination.
+        try {
+            // Drop -s -o /dev/null so we can see the HTTP response. The body
+            // is logged to stderr if Telegram returns a non-2xx.
+            const verboseArgs = curlArgs.filter((a) => a !== "-s" && a !== "/dev/null" && a !== "-o");
+            verboseArgs.push("-w", "HTTP=%{http_code}");
+            const result = spawnSync("curl", verboseArgs, { timeout: 7000, encoding: "utf-8" });
+            const stdout = (result.stdout || "").toString();
+            const stderr = (result.stderr || "").toString();
+            // Diagnostic — only logs in failure path. Helps debug "DM never arrived".
+            if (result.status !== 0 || !/HTTP=2\d\d/.test(stdout)) {
+                console.error(`[critical-notify] telegram sync curl status=${result.status} stdout=${stdout.slice(0, 200)} stderr=${stderr.slice(0, 200)}`);
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            console.error(`[critical-notify] telegram sync curl threw: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    // Async detached: bot keeps running afterwards, no need to block.
+    // detached + stdio:ignore + unref is the standard pattern for
+    // "fire and forget". Note: NOT safe if caller calls process.exit()
+    // immediately after — use blockTelegram:true for those cases.
+    try {
+        const child = spawn("curl", curlArgs, { detached: true, stdio: "ignore" });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Emit a critical event across all configured channels.
+ *
+ * Synchronous-fast: file flag + osascript run inline (<60ms total typical).
+ * Telegram is detached so it doesn't block; we return true if it was
+ * scheduled (not whether it succeeded — that we can't know synchronously
+ * without blocking).
+ *
+ * Always safe to call. Never throws. Never blocks longer than ~3s
+ * (osascript timeout) in the worst case.
+ *
+ * Outcome of each tier is also logged to stderr so users can diagnose
+ * "why didn't I get the Telegram DM?" by reading their err.log.
+ */
+export function emitCritical(event, opts) {
+    if (isDisabled()) {
+        console.error("[critical-notify] skipped — opt-out via env var");
+        return { fileFlag: false, macos: false, telegram: false, reachedAtLeastOne: false };
+    }
+    // Tier 3 first — most durable, cheapest.
+    const fileFlag = writeFileFlag(event);
+    // Tier 2 — macOS user-facing.
+    const macos = macosNotification(event);
+    // Tier 1 — Telegram DM (sync if caller signaled exit, else detached).
+    const resolved = resolveOptions(opts);
+    const telegram = telegramAdminDM(event, { ...resolved, blockTelegram: opts?.blockTelegram });
+    // Diagnostics — written to stderr so even brake-context invocations
+    // leave a paper trail in err.log. The user previously hit a case
+    // where 1D fired the file flag and osascript but the Telegram DM
+    // seemingly never arrived — this log makes it obvious whether
+    // resolveOptions found a token + chat_id.
+    console.error(`[critical-notify] event="${event.category}" ` +
+        `file=${fileFlag ? "ok" : "fail"} ` +
+        `macos=${macos ? "ok" : "skip"} ` +
+        `telegram=${telegram ? "scheduled" : "skip"}` +
+        (telegram ? "" : ` (botToken=${resolved.botToken ? "set" : "missing"} adminChatId=${resolved.adminChatId ?? "missing"})`));
+    return {
+        fileFlag,
+        macos,
+        telegram,
+        reachedAtLeastOne: fileFlag || macos || telegram,
+    };
+}

package/dist/services/heartbeat-file.js

@@ -0,0 +1,65 @@
+/**
+ * Heartbeat-File Writer (Self-Preservation Phase 1, feature 2E).
+ *
+ * Writes a unix timestamp (seconds) to ~/.alvin-bot/heartbeat.txt every
+ * 60 seconds. An external launchd-managed dead-man watcher reads this
+ * file every 5 minutes — if the timestamp is older than 10 minutes,
+ * the bot is presumed frozen (event-loop deadlock, blocked I/O,
+ * unresponsive but alive process) and the watcher force-restarts via
+ * `launchctl kickstart -k`.
+ *
+ * This complements the in-process watchdog (src/services/watchdog.ts)
+ * which only catches process exits — it cannot catch "process alive
+ * but frozen" because that's exactly the state where the watchdog's
+ * own beacon writer also stops.
+ *
+ * Why a file + external watcher instead of an internal timer:
+ *   - An internal "I'm frozen" timer is a contradiction in terms.
+ *     If the event loop is dead, the timer doesn't fire either.
+ *   - The file-based external watcher is the only architecturally
+ *     sound way to detect this class of failure.
+ *
+ * Performance: file write of 11 bytes every 60s. CPU cost ~1ms/min,
+ * disk I/O ~0.7 KB/day. Truly negligible.
+ *
+ * Opt-out:
+ *   ALVIN_DISABLE_DEAD_MAN=true              → skip heartbeat writer
+ *   ALVIN_DISABLE_SELF_PRESERVATION=true     → skip all Phase-1
+ */
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const HEARTBEAT_PATH = join(homedir(), ".alvin-bot", "heartbeat.txt");
+const HEARTBEAT_INTERVAL_MS = 60_000;
+let heartbeatTimer = null;
+function writeHeartbeat() {
+    try {
+        mkdirSync(join(homedir(), ".alvin-bot"), { recursive: true });
+        // 11 bytes — Unix seconds + newline. Easy to parse from shell.
+        writeFileSync(HEARTBEAT_PATH, `${Math.floor(Date.now() / 1000)}\n`);
+    }
+    catch {
+        // Disk full or permissions — non-fatal. The dead-man watcher will
+        // see a stale file and kickstart, which is the right behaviour:
+        // a bot that can't write its heartbeat IS effectively stuck.
+    }
+}
+export function startHeartbeatWriter() {
+    if (process.env.ALVIN_DISABLE_DEAD_MAN === "true" ||
+        process.env.ALVIN_DISABLE_SELF_PRESERVATION === "true") {
+        return;
+    }
+    // Write immediately so the dead-man watcher doesn't see a stale file
+    // from the previous process incarnation.
+    writeHeartbeat();
+    heartbeatTimer = setInterval(writeHeartbeat, HEARTBEAT_INTERVAL_MS);
+    // Allow the process to exit without waiting for this timer.
+    if (heartbeatTimer.unref)
+        heartbeatTimer.unref();
+}
+export function stopHeartbeatWriter() {
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+    }
+}

package/dist/services/preflight.js

@@ -0,0 +1,292 @@
+/**
+ * Pre-Flight Sanity Check (Self-Preservation Phase 1, feature 1A).
+ *
+ * Runs in PARALLEL at startup, fire-and-forget: never blocks the bot's main
+ * startup sequence. Each check has a tight timeout. Results are logged with
+ * a severity classification (ok / warn / critical). Critical findings can
+ * optionally feed into the cross-channel notify pipeline (1D).
+ *
+ * Provider-agnostic: AI-provider check is routed through the active
+ * Provider's `isAvailable()` method, which every concrete provider
+ * implements — so the same check works for claude-sdk, codex-cli,
+ * groq, gemini, openai, openrouter, ollama (gemma), nvidia.
+ *
+ * Opt-out:
+ *   ALVIN_DISABLE_PREFLIGHT=true           → skip Pre-Flight specifically
+ *   ALVIN_DISABLE_SELF_PRESERVATION=true   → skip ALL Phase-1 features
+ *
+ * Performance budget (measured on Apple Silicon M-series):
+ *   - Telegram getMe: typical 150-400ms, timeout 3000ms
+ *   - AI Provider isAvailable: typical 50-800ms, timeout 5000ms
+ *   - SQLite PRAGMA quick_check: typical 5-50ms, timeout 10000ms
+ *   - df disk space: typical 5-15ms, timeout 2000ms
+ *   - Total wall-clock = max of all four (Promise.all) — typically <1s
+ */
+import { existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+function isDisabled() {
+    return (process.env.ALVIN_DISABLE_PREFLIGHT === "true" ||
+        process.env.ALVIN_DISABLE_SELF_PRESERVATION === "true");
+}
+/**
+ * Run a promise with a wall-clock timeout. Returns `fallback` if the
+ * promise doesn't settle in time. Never rejects.
+ */
+function withTimeout(promise, ms, fallback) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolve(fallback);
+            }
+        }, ms);
+        promise.then((value) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(value);
+            }
+        }, () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(fallback);
+            }
+        });
+    });
+}
+async function checkTelegram(botToken) {
+    const start = Date.now();
+    if (!botToken) {
+        return {
+            name: "telegram",
+            ok: true,
+            severity: "ok",
+            message: "skipped (WebUI-only mode, no BOT_TOKEN)",
+            durationMs: Date.now() - start,
+        };
+    }
+    const url = `https://api.telegram.org/bot${botToken}/getMe`;
+    const result = await withTimeout(fetch(url).then(async (r) => ({ ok: r.ok, status: r.status, body: await r.json().catch(() => null) })), 3000, null);
+    if (!result) {
+        return {
+            name: "telegram",
+            ok: false,
+            severity: "warn",
+            message: "getMe timed out (3s) — bot may have network / Telegram issues",
+            durationMs: Date.now() - start,
+        };
+    }
+    if (!result.ok) {
+        return {
+            name: "telegram",
+            ok: false,
+            severity: "critical",
+            message: `getMe HTTP ${result.status} — token may be invalid`,
+            durationMs: Date.now() - start,
+        };
+    }
+    const username = result.body?.result?.username;
+    return {
+        name: "telegram",
+        ok: true,
+        severity: "ok",
+        message: username ? `bot=@${username}` : "bot reachable",
+        durationMs: Date.now() - start,
+    };
+}
+async function checkAiProvider(registry) {
+    const start = Date.now();
+    if (!registry) {
+        return {
+            name: "ai-provider",
+            ok: false,
+            severity: "warn",
+            message: "no provider configured (AI features will be disabled)",
+            durationMs: Date.now() - start,
+        };
+    }
+    let provider;
+    let activeKey = "(unknown)";
+    try {
+        provider = registry.getActive();
+        activeKey = registry.getActiveKey();
+    }
+    catch {
+        return {
+            name: "ai-provider",
+            ok: false,
+            severity: "warn",
+            message: "no active provider in registry",
+            durationMs: Date.now() - start,
+        };
+    }
+    if (!provider) {
+        return {
+            name: "ai-provider",
+            ok: false,
+            severity: "warn",
+            message: "no active provider in registry",
+            durationMs: Date.now() - start,
+        };
+    }
+    const available = await withTimeout(provider.isAvailable(), 5000, false);
+    return {
+        name: "ai-provider",
+        ok: available,
+        severity: available ? "ok" : "warn",
+        message: available
+            ? `${activeKey} reachable`
+            : `${activeKey} not reachable / not configured — bot will degrade gracefully on AI calls`,
+        durationMs: Date.now() - start,
+    };
+}
+async function checkSqliteIntegrity() {
+    const start = Date.now();
+    const dbPath = join(homedir(), ".alvin-bot", "memory", ".embeddings.db");
+    if (!existsSync(dbPath)) {
+        return {
+            name: "sqlite",
+            ok: true,
+            severity: "ok",
+            message: "embeddings DB not yet created (lazily on first use)",
+            durationMs: Date.now() - start,
+        };
+    }
+    try {
+        const { createRequire } = await import("module");
+        const req = createRequire(import.meta.url);
+        const Database = req("better-sqlite3");
+        const db = new Database(dbPath, { readonly: true });
+        // PRAGMA quick_check is materially faster than integrity_check
+        // (catches the same classes of corruption but doesn't verify every
+        // page). For our purpose — "is the file readable + structurally
+        // sane?" — quick_check is the right tool.
+        const result = await withTimeout(Promise.resolve(db.prepare("PRAGMA quick_check").get()), 10_000, null);
+        db.close();
+        if (result === null) {
+            return {
+                name: "sqlite",
+                ok: false,
+                severity: "warn",
+                message: "PRAGMA quick_check timed out (>10s) — DB may be very large or locked",
+                durationMs: Date.now() - start,
+            };
+        }
+        const r = result;
+        const checkResult = r.quick_check || "(unknown)";
+        const ok = checkResult === "ok";
+        return {
+            name: "sqlite",
+            ok,
+            severity: ok ? "ok" : "critical",
+            message: ok ? "embeddings DB integrity ok" : `embeddings DB integrity FAILED: ${checkResult}`,
+            durationMs: Date.now() - start,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name: "sqlite",
+            ok: true,
+            severity: "ok",
+            message: `check skipped: ${message.split("\n")[0]}`,
+            durationMs: Date.now() - start,
+        };
+    }
+}
+async function checkDiskSpace() {
+    const start = Date.now();
+    try {
+        const { execSync } = await import("child_process");
+        const dataDir = join(homedir(), ".alvin-bot");
+        const out = execSync(`df -k "${dataDir}"`, { encoding: "utf-8", timeout: 2000 });
+        const lines = out.trim().split("\n");
+        const data = lines[lines.length - 1].split(/\s+/);
+        // df output: Filesystem 1024-blocks Used Available Capacity ...
+        const availableKB = parseInt(data[3], 10);
+        if (!Number.isFinite(availableKB)) {
+            return {
+                name: "disk",
+                ok: true,
+                severity: "ok",
+                message: "could not parse df output",
+                durationMs: Date.now() - start,
+            };
+        }
+        const availableGB = availableKB / 1024 / 1024;
+        const severity = availableKB < 512 * 1024 ? "critical" :
+            availableKB < 1024 * 1024 ? "warn" :
+                "ok";
+        return {
+            name: "disk",
+            ok: severity === "ok",
+            severity,
+            message: `${availableGB.toFixed(2)} GB free`,
+            durationMs: Date.now() - start,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name: "disk",
+            ok: true,
+            severity: "ok",
+            message: `check skipped: ${message.split("\n")[0]}`,
+            durationMs: Date.now() - start,
+        };
+    }
+}
+/**
+ * Run the full pre-flight suite in parallel. Always resolves (never
+ * throws). Returns a structured report so the caller can decide how
+ * to react.
+ */
+export async function runPreFlight(botToken, registry) {
+    if (isDisabled()) {
+        return {
+            results: [],
+            slowestMs: 0,
+            totalMs: 0,
+            anyCritical: false,
+            anyWarning: false,
+            skipped: true,
+        };
+    }
+    const start = Date.now();
+    const results = await Promise.all([
+        checkTelegram(botToken),
+        checkAiProvider(registry),
+        checkSqliteIntegrity(),
+        checkDiskSpace(),
+    ]);
+    return {
+        results,
+        slowestMs: Math.max(...results.map((r) => r.durationMs)),
+        totalMs: Date.now() - start,
+        anyCritical: results.some((r) => r.severity === "critical"),
+        anyWarning: results.some((r) => r.severity === "warn"),
+        skipped: false,
+    };
+}
+/**
+ * Format a PreFlightReport for console output. Compact, single line per
+ * check, clear severity icons.
+ */
+export function formatPreFlightReport(report) {
+    if (report.skipped) {
+        return "🩺 Pre-Flight: skipped (ALVIN_DISABLE_PREFLIGHT=true)";
+    }
+    const icons = { ok: "✓", warn: "⚠", critical: "❌" };
+    const headline = report.anyCritical
+        ? "❌ Pre-Flight: critical issues"
+        : report.anyWarning
+            ? "⚠️  Pre-Flight: warnings"
+            : "✅ Pre-Flight: all checks ok";
+    const lines = report.results.map((r) => {
+        return `   ${icons[r.severity]} ${r.name.padEnd(12)} ${r.message} (${r.durationMs}ms)`;
+    });
+    return `🩺 ${headline} — ${report.totalMs}ms total\n${lines.join("\n")}`;
+}