alvin-bot 5.3.0 → 5.5.0

package/dist/services/cron.js

@@ -17,13 +17,113 @@ import { prepareForExecution, handleStartupCatchup, calculateNextRunFrom, } from
 import { resolveJobByNameOrId } from "./cron-resolver.js";
 import { bootWasExpectedRestart } from "./watchdog.js";
 // ── Storage ─────────────────────────────────────────────
+/** Allowed job types — must stay in sync with the JobType union above. */
+const ALLOWED_JOB_TYPES = new Set(["reminder", "shell", "ai-query", "http", "message"]);
+/**
+ * M4: Per-entry structural validation for a raw parsed cron-jobs.json entry.
+ *
+ * Rules:
+ *   - Must be a non-null object
+ *   - `id`, `name`, `schedule`, `createdBy` must be non-empty strings
+ *   - `type` must be one of the allowed JobType values
+ *   - `payload` must be an object (not null)
+ *   - `target` must be an object with `platform` (string) and `chatId` (string)
+ *   - `enabled` must be a boolean
+ *   - `createdAt`, `runCount` must be numbers
+ *   - `oneShot` must be a boolean
+ *   - Nullable fields (lastRunAt, lastResult, lastError, nextRunAt) can be
+ *     null or their expected types — lenient check, just must not be undefined
+ *
+ * Returns a validated CronJob (cast) on success, null on failure.
+ * Logs a calm warning for every skipped entry.
+ */
+function validateCronJobEntry(raw, index) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        console.warn(`[cron] skipping entry #${index}: not an object`);
+        return null;
+    }
+    const e = raw;
+    if (typeof e.id !== "string" || !e.id) {
+        console.warn(`[cron] skipping entry #${index}: missing or invalid 'id'`);
+        return null;
+    }
+    if (typeof e.name !== "string" || !e.name) {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): missing or invalid 'name'`);
+        return null;
+    }
+    if (typeof e.type !== "string" || !ALLOWED_JOB_TYPES.has(e.type)) {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): unknown or missing job type '${e.type}'`);
+        return null;
+    }
+    if (typeof e.schedule !== "string" || !e.schedule) {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): missing or invalid 'schedule'`);
+        return null;
+    }
+    if (!e.payload || typeof e.payload !== "object" || Array.isArray(e.payload)) {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): 'payload' must be an object`);
+        return null;
+    }
+    if (!e.target || typeof e.target !== "object" || Array.isArray(e.target)) {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): 'target' must be an object`);
+        return null;
+    }
+    const t = e.target;
+    if (typeof t.platform !== "string" || typeof t.chatId !== "string") {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): 'target.platform' and 'target.chatId' must be strings`);
+        return null;
+    }
+    if (typeof e.enabled !== "boolean") {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): 'enabled' must be a boolean`);
+        return null;
+    }
+    if (typeof e.createdAt !== "number") {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): 'createdAt' must be a number`);
+        return null;
+    }
+    if (typeof e.runCount !== "number") {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): 'runCount' must be a number`);
+        return null;
+    }
+    if (typeof e.oneShot !== "boolean") {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): 'oneShot' must be a boolean`);
+        return null;
+    }
+    // Lenient nullable fields
+    if (e.createdBy !== undefined && typeof e.createdBy !== "string") {
+        console.warn(`[cron] skipping entry #${index} (id=${e.id}): 'createdBy' must be a string`);
+        return null;
+    }
+    return raw;
+}
 function loadJobs() {
+    let raw;
     try {
-        return JSON.parse(fs.readFileSync(CRON_FILE, "utf-8"));
+        raw = fs.readFileSync(CRON_FILE, "utf-8");
     }
     catch {
         return [];
     }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        console.warn("[cron] cron-jobs.json is not valid JSON — starting with empty job list:", err instanceof Error ? err.message : String(err));
+        return [];
+    }
+    if (!Array.isArray(parsed)) {
+        console.warn("[cron] cron-jobs.json root is not an array — starting with empty job list");
+        return [];
+    }
+    // M4: Per-entry validation — one bad entry must NOT crash the whole list
+    const jobs = [];
+    for (let i = 0; i < parsed.length; i++) {
+        const validated = validateCronJobEntry(parsed[i], i);
+        if (validated !== null) {
+            jobs.push(validated);
+        }
+    }
+    return jobs;
 }
 function saveJobs(jobs) {
     const dir = dirname(CRON_FILE);
@@ -54,27 +154,87 @@ function nextCronRun(expression, after = new Date()) {
     if (parts.length !== 5)
         return null;
     const [minExpr, hourExpr, dayExpr, monthExpr, weekdayExpr] = parts;
-    function parseField(expr, min, max) {
-        if (expr === "*")
-            return Array.from({ length: max - min + 1 }, (_, i) => i + min);
-        if (expr.includes("/")) {
-            const [, step] = expr.split("/");
-            const s = parseInt(step);
-            return Array.from({ length: max - min + 1 }, (_, i) => i + min).filter(v => v % s === 0);
+    /**
+     * Parse a single cron field token (no commas — commas handled by parseField).
+     * Supports: `*`, `a`, `a-b`, `a-b/s`, `*\/s`, `a/s`.
+     * Returns null for invalid/garbage tokens.
+     */
+    function parseFieldToken(token, min, max) {
+        const fullRange = () => Array.from({ length: max - min + 1 }, (_, i) => i + min);
+        if (token.includes("/")) {
+            const slashIdx = token.indexOf("/");
+            const basePart = token.slice(0, slashIdx);
+            const stepPart = token.slice(slashIdx + 1);
+            const step = parseInt(stepPart, 10);
+            if (!Number.isFinite(step) || step <= 0)
+                return null;
+            let base;
+            if (basePart === "*") {
+                base = fullRange();
+            }
+            else if (basePart.includes("-")) {
+                const dashParts = basePart.split("-");
+                if (dashParts.length !== 2)
+                    return null;
+                const a = parseInt(dashParts[0], 10);
+                const b = parseInt(dashParts[1], 10);
+                if (!Number.isFinite(a) || !Number.isFinite(b) || a > b || a < min || b > max)
+                    return null;
+                base = Array.from({ length: b - a + 1 }, (_, i) => i + a);
+            }
+            else {
+                const a = parseInt(basePart, 10);
+                if (!Number.isFinite(a) || a < min || a > max)
+                    return null;
+                base = [a];
+            }
+            const baseStart = base[0];
+            return base.filter((v) => (v - baseStart) % step === 0);
         }
-        if (expr.includes(","))
-            return expr.split(",").map(Number);
-        if (expr.includes("-")) {
-            const [a, b] = expr.split("-").map(Number);
+        if (token === "*")
+            return fullRange();
+        if (token.includes("-")) {
+            const dashParts = token.split("-");
+            if (dashParts.length !== 2)
+                return null;
+            const a = parseInt(dashParts[0], 10);
+            const b = parseInt(dashParts[1], 10);
+            if (!Number.isFinite(a) || !Number.isFinite(b) || a > b || a < min || b > max)
+                return null;
             return Array.from({ length: b - a + 1 }, (_, i) => i + a);
         }
-        return [parseInt(expr)];
+        const v = parseInt(token, 10);
+        if (!Number.isFinite(v) || v < min || v > max)
+            return null;
+        return [v];
+    }
+    /**
+     * Parse a cron field expression (may contain commas) into a sorted array of valid integers.
+     * Returns null if any token is invalid/garbage (the expression is rejected).
+     */
+    function parseField(expr, min, max) {
+        const tokens = expr.split(",").filter((t) => t.length > 0);
+        if (tokens.length === 0)
+            return null;
+        const result = new Set();
+        for (const token of tokens) {
+            const vals = parseFieldToken(token, min, max);
+            if (vals === null)
+                return null;
+            for (const v of vals)
+                result.add(v);
+        }
+        const arr = [...result].sort((a, b) => a - b);
+        return arr.length > 0 ? arr : null;
     }
     const minutes = parseField(minExpr, 0, 59);
     const hours = parseField(hourExpr, 0, 23);
     const days = parseField(dayExpr, 1, 31);
     const months = parseField(monthExpr, 1, 12);
     const weekdays = parseField(weekdayExpr, 0, 6); // 0=Sun
+    // Any field returning null means the expression is invalid — reject it
+    if (!minutes || !hours || !days || !months || !weekdays)
+        return null;
     // Search forward up to 366 days
     const candidate = new Date(after);
     candidate.setSeconds(0, 0);
@@ -112,6 +272,10 @@ let notifyCallback = null;
 export function setNotifyCallback(fn) {
     notifyCallback = fn;
 }
+/** @internal exported for unit-test use only */
+export async function runJob(job) {
+    return executeJob(job);
+}
 async function executeJob(job) {
     try {
         switch (job.type) {
@@ -162,11 +326,36 @@ async function executeJob(job) {
                 const url = job.payload.url || "";
                 const method = job.payload.method || "GET";
                 const headers = job.payload.headers || {};
-                const fetchOpts = { method, headers };
+                // M1: SSRF guard — reject private/internal destinations before fetching.
+                // Runs even when EXEC_SECURITY=deny (it's a separate, independent control).
+                // We validate EVERY redirect hop manually (redirect:"manual") so a
+                // public host cannot 302 us into an internal address (post-redirect SSRF).
+                const { assertSsrfSafe, SsrfBlockedError: SsrfBlockedErrorCron } = await import("./ssrf-guard.js");
+                await assertSsrfSafe(url);
+                const baseOpts = { method, headers };
                 if (job.payload.body && method !== "GET") {
-                    fetchOpts.body = job.payload.body;
+                    baseOpts.body = job.payload.body;
+                }
+                const MAX_CRON_REDIRECTS = 10;
+                let currentUrl = url;
+                let res;
+                for (let hop = 0;; hop++) {
+                    res = await fetch(currentUrl, { ...baseOpts, redirect: "manual" });
+                    // Not a redirect — we have the final response
+                    if (res.status < 300 || res.status >= 400)
+                        break;
+                    const loc = res.headers.get("location");
+                    if (!loc)
+                        break; // no Location header — treat as final response
+                    if (hop >= MAX_CRON_REDIRECTS) {
+                        throw new SsrfBlockedErrorCron(url, `too many redirects (> ${MAX_CRON_REDIRECTS})`);
+                    }
+                    const next = new URL(loc, currentUrl).href;
+                    // Re-validate each redirect target before following — closes the
+                    // post-redirect SSRF bypass.
+                    await assertSsrfSafe(next);
+                    currentUrl = next;
                 }
-                const res = await fetch(url, fetchOpts);
                 const text = await res.text();
                 const output = `HTTP ${res.status}: ${text.slice(0, 2000)}`;
                 if (notifyCallback) {

package/dist/services/delivery-queue.js

@@ -10,6 +10,9 @@ import crypto from "crypto";
 import { DELIVERY_QUEUE_FILE } from "../paths.js";
 // ── State ───────────────────────────────────────────────
 let senders = {};
+/** Re-entrancy guard: prevents overlapping processQueue() invocations.
+ *  Mirrors the `runningJobs` Set pattern used by cron.ts. */
+let inFlight = false;
 // ── File I/O ────────────────────────────────────────────
 function readQueue() {
     try {
@@ -67,8 +70,24 @@ export function enqueue(channel, chatId, content, options) {
  * Process all pending entries in the queue.
  * Respects exponential backoff and max attempts.
  * Returns counts of delivered, failed, and still-pending entries.
+ *
+ * Re-entrancy guard: if a prior processQueue() call is still in-flight
+ * (e.g. a slow sender blocks beyond the 30s tick), the second invocation
+ * returns immediately with zero counts.  Mirrors the runningJobs Set
+ * pattern used by cron.ts to guard overlapping job executions.
  */
 export async function processQueue() {
+    if (inFlight)
+        return { delivered: 0, failed: 0, pending: 0 };
+    inFlight = true;
+    try {
+        return await _processQueueInner();
+    }
+    finally {
+        inFlight = false;
+    }
+}
+async function _processQueueInner() {
     const queue = readQueue();
     const now = Date.now();
     let delivered = 0;

package/dist/services/embeddings/index.js

@@ -40,11 +40,8 @@ function loadSqlite() {
     }
     catch (err) {
         sqliteLoadError = err instanceof Error ? err : new Error(String(err));
-        console.warn("⚠️ better-sqlite3 native binary unavailable — embeddings disabled. " +
-            "Bot continues without semantic memory search. Fix: rebuild deps with " +
-            "`cd $(npm root -g)/alvin-bot && npm rebuild better-sqlite3` or reinstall " +
-            "alvin-bot. Underlying error: " +
-            sqliteLoadError.message);
+        console.log("ℹ️ Semantic memory (better-sqlite3) unavailable — using keyword search (FTS5). " +
+            "Reinstall or run `npm rebuild better-sqlite3` to enable.");
         return null;
     }
 }

package/dist/services/env-file.js

@@ -26,6 +26,10 @@ export function readEnv() {
 }
 /** Upsert a key=value pair in the env file, preserving all other lines. */
 export function writeEnvVar(key, value) {
+    // M6 (centralized): reject values containing newline characters — they allow
+    // injecting extra .env lines (e.g. value="good\nEVIL=injected").
+    if (/[\n\r]/.test(value))
+        throw new Error("env value must not contain newline characters");
     let content = fs.existsSync(ENV_FILE) ? fs.readFileSync(ENV_FILE, "utf-8") : "";
     const regex = new RegExp(`^${key}=.*$`, "m");
     if (regex.test(content)) {

package/dist/services/personality.js

@@ -35,7 +35,7 @@ try {
     soulContent = readFileSync(SOUL_FILE, "utf-8");
 }
 catch {
-    console.warn("SOUL.md not found — using default personality");
+    console.log("ℹ️ soul.md not found — using built-in default personality. Create ~/.alvin-bot/soul.md to customize.");
 }
 loadStandingOrders();
 /** Base system prompt — adapts to user language */
@@ -49,9 +49,14 @@ const SDK_ADDON = `When you run commands or edit files, briefly explain what you
 /**
  * Stage 1 of Fix #17 — async sub-agents.
  *
- * Tells Claude to use the SDK's `run_in_background` flag for long-running
- * Agent tool calls so the main Telegram session doesn't stay locked for
- * 10+ minutes while sub-agents crawl the web, run audits, or build reports.
+ * Tells Claude that `mcp__alvin__dispatch_agent` is the ONLY sanctioned
+ * path for long-running work on chat platforms.  The built-in Task/Agent
+ * tool is explicitly disallowed for anything that takes more than ~30 s
+ * because it blocks the session: isProcessing stays true, the typing
+ * indicator keeps firing, and the user cannot send a new message until
+ * the sub-agent finishes.  Path A (mcp__alvin__dispatch_agent) spawns a
+ * truly detached subprocess and returns in milliseconds so the session
+ * is freed immediately.
  *
  * Only injected into the prompt when isSDK === true (non-SDK providers
  * have no Agent tool). The bot's async-agent-watcher (Stage 2) picks up
@@ -63,34 +68,29 @@ const SDK_ADDON = `When you run commands or edit files, briefly explain what you
  */
 const BACKGROUND_SUBAGENT_HINT = `## ⚠️ CRITICAL: Background Sub-Agents on Telegram/WhatsApp/Slack
 
-**THE RULE (v4.13 update)**: For ANY long-running work (research,
-audits, multi-step analysis, >30 seconds), you MUST prefer the
-\`mcp__alvin__dispatch_agent\` tool over the built-in \`Task\` tool.
+**THE RULE**: For ANY long-running work (research, audits, multi-step
+analysis, >30 seconds), you MUST use \`mcp__alvin__dispatch_agent\`.
+The built-in \`Task\`/\`Agent\` tool is BANNED for long work on chat
+platforms (Telegram/WhatsApp/Slack/Discord). Do not use it for anything
+that takes more than ~30 seconds.
 
-**Why alvin_dispatch over Task(run_in_background: true)?**
+**Why mcp__alvin__dispatch_agent is the ONLY background path:**
 
-The built-in Task tool (even with \`run_in_background: true\`) keeps
-the sub-agent tied to THIS session's CLI subprocess. If the user sends
-me a new message mid-work, aborting this session would kill the
-sub-agent half-way through and leave garbage partial output. Alvin
-learned this the hard way (v4.12.1–v4.12.3 all got this wrong).
+The built-in Task/Agent tool — even with \`run_in_background: true\` —
+keeps the sub-agent tied to THIS session's CLI subprocess. The session
+stays blocked: \`isProcessing\` remains true, the typing indicator
+keeps firing, and the user's next message is queued until the
+synchronous Task finishes. There is no way to free the session while a
+built-in Task is running — that is a hard platform constraint.
 
 \`mcp__alvin__dispatch_agent\` spawns a COMPLETELY INDEPENDENT
 \`claude -p\` subprocess with its own PID, own process group. It
-survives ANY abort of this session. The user can interrupt me freely
-and keep chatting while the sub-agent finishes cleanly. The bot
-delivers the result as a separate message when ready.
+returns in milliseconds, the session is freed immediately, and the user
+can keep chatting. The bot delivers the result as a separate message
+when ready.
 
 **THIS IS THE SINGLE MOST IMPORTANT RULE FOR USER RESPONSIVENESS.**
 
-**Why it matters**: During a synchronous Agent tool call the parent
-session has no way to know the sub-agent is still working. It appears
-hung. After a long silence the session can be aborted, destroying the
-work. Using \`run_in_background: true\` solves this: the tool returns
-an \`agentId\` + \`outputFile\` path IMMEDIATELY, your turn ends in
-seconds, the user can keep chatting with me, and the bot automatically
-delivers the sub-agent's final result as a separate message when ready.
-
 **Decision tree** (apply every time you consider any sub-agent tool):
 
   Does the task involve ANY of the following?
@@ -103,16 +103,11 @@ delivers the sub-agent's final result as a separate message when ready.
     • Crawling, scraping, or fetching multiple resources
     • Research across multiple sources or domains
 
-  YES → use \`mcp__alvin__dispatch_agent\` (truly detached, preferred)
+  YES → use \`mcp__alvin__dispatch_agent\` (the ONLY sanctioned path)
   NO  → foreground is fine (single quick sub-query under 30s, answer
         yourself if possible)
 
-NOTE: The built-in Task tool with run_in_background: true still works
-but is now deprecated on Telegram/Slack/Discord/WhatsApp because it
-ties sub-agent lifetime to this session. Only use Task directly when
-you explicitly need the sub-agent's result IN THIS SAME TURN (rare).
-
-**Examples where you MUST use \`run_in_background: true\`:**
+**Examples where you MUST use \`mcp__alvin__dispatch_agent\`:**
 - ANY audit (SEO, security, code quality, performance, accessibility, GEO)
 - Research visiting more than 1-2 web pages
 - Code reviews on more than a single file
@@ -122,12 +117,12 @@ you explicitly need the sub-agent's result IN THIS SAME TURN (rare).
 - Long data-processing jobs
 - Anything involving the word "analyze", "audit", "review", "scan", "research"
 
-**Examples where foreground is fine:**
+**Examples where foreground is fine (no sub-agent needed):**
 - "Read this file and summarize it" (single file, <10s)
 - "What's 2+2?" (no sub-agent needed — answer yourself)
 - "Check if package.json has foo" (one quick tool call)
 
-**After launching a background agent (either tool), you MUST:**
+**After calling \`mcp__alvin__dispatch_agent\` you MUST:**
 1. Tell the user in ONE short sentence what you kicked off.
    Example: "Starting SEO audit for example.com in the background —
    I'll send the report when it's done."
@@ -135,6 +130,14 @@ you explicitly need the sub-agent's result IN THIS SAME TURN (rare).
 3. The bot will deliver the result as a separate message when ready.
    You don't need to poll the outputFile proactively.
 
+Only say "running in the background — you can keep chatting" if you
+actually called \`mcp__alvin__dispatch_agent\` in this turn. If the
+task ran inline (foreground tool calls, no dispatch), it blocked the
+session and the user could NOT chat during it — do NOT claim otherwise.
+If a task was too long for foreground but you didn't dispatch it, tell
+the user truthfully: "That ran inline and took a while. Your messages
+were queued until it finished."
+
 **For PARALLEL dispatch** (e.g. user says "research X and Y in parallel"):
 Call \`mcp__alvin__dispatch_agent\` multiple times in the SAME assistant
 turn, once per sub-task. Each returns its own agentId immediately. Your
@@ -145,10 +148,10 @@ If the user asks "is it done yet?" before the bot delivers the result,
 you MAY read the agent's \`outputFile\` (from the original tool result)
 using the Read tool to peek at progress — but don't block on it.
 
-**Never** call the Agent/Task tool without \`run_in_background: true\`
-for anything you're not 100% sure completes in under 30 seconds. The
-cost of unnecessary background mode is zero. The cost of blocking the
-Telegram user for 20 minutes on a synchronous call is very high.`;
+**Never** call the built-in Agent/Task tool for anything you're not
+100% sure completes in under 30 seconds. The cost of dispatch is zero.
+The cost of blocking the chat user for 20 minutes on a synchronous
+inline Task is very high.`;
 /**
  * Self-Awareness Core — Dynamic introspection block.
  *

package/dist/services/session-persistence.js

@@ -142,6 +142,12 @@ export function loadPersistedSessions() {
     if (!raw_parsed || typeof raw_parsed !== "object")
         return 0;
     // v4.12.0 — Detect envelope format vs legacy v4.11.0 flat format
+    // M4: Validate the top-level shape before trusting any field.
+    if (Array.isArray(raw_parsed)) {
+        // An array at root is not a valid sessions file
+        console.warn("⚠️ session-persistence: sessions file contains an array at root, starting fresh");
+        return 0;
+    }
     let parsed;
     let tgWorkspaces = {};
     if (raw_parsed &&
@@ -149,11 +155,22 @@ export function loadPersistedSessions() {
         "version" in raw_parsed &&
         "sessions" in raw_parsed) {
         const env = raw_parsed;
-        parsed = env.sessions ?? {};
-        tgWorkspaces = env.telegramWorkspaces ?? {};
+        // M4: sessions field must be a non-null object; degrade gracefully if tampered
+        if (!env.sessions || typeof env.sessions !== "object" || Array.isArray(env.sessions)) {
+            console.warn("⚠️ session-persistence: 'sessions' field is not an object, starting fresh");
+            return 0;
+        }
+        parsed = env.sessions;
+        tgWorkspaces = (env.telegramWorkspaces && typeof env.telegramWorkspaces === "object" && !Array.isArray(env.telegramWorkspaces))
+            ? env.telegramWorkspaces
+            : {};
     }
     else {
-        // Legacy flat format (v4.11.0)
+        // Legacy flat format (v4.11.0) — must also be an object
+        if (!raw_parsed || typeof raw_parsed !== "object") {
+            console.warn("⚠️ session-persistence: sessions file is not a valid object, starting fresh");
+            return 0;
+        }
         parsed = raw_parsed;
     }
     // Rehydrate Telegram workspace map
@@ -184,6 +201,7 @@ export function loadPersistedSessions() {
             _qHandle: null,
             _steerChannel: null,
             _steerAckSentThisTurn: false,
+            _turnId: null,
             lastActivity: persisted.lastActivity ?? Date.now(),
             startedAt: persisted.startedAt ?? Date.now(),
             totalCost: persisted.totalCost ?? 0,

package/dist/services/session.js

@@ -84,6 +84,7 @@ export function getSession(key) {
             _qHandle: null,
             _steerChannel: null,
             _steerAckSentThisTurn: false,
+            _turnId: null,
             lastActivity: Date.now(),
             startedAt: Date.now(),
             totalCost: 0,
@@ -120,6 +121,8 @@ export function getSession(key) {
             session._steerChannel = null;
         if (session._steerAckSentThisTurn === undefined)
             session._steerAckSentThisTurn = false;
+        if (session._turnId === undefined)
+            session._turnId = null;
     }
     return session;
 }