alvin-bot 5.6.2 → 5.7.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.7.0] — 2026-05-19
+
+### Background-task results now arrive the instant the task finishes, and survive a restart
+
+Detached background-task results were delivered by a 15-second polling
+loop whose in-memory state could diverge across a bot restart, so a task
+that finished around a restart could keep its result undelivered with
+nothing shown in chat. Delivery is now pushed the moment the task's
+process exits — through an always-on local callback guarded by a
+per-boot token — and a startup reconciliation pass drains anything that
+completed while the bot was down. An atomic deliver-once marker
+guarantees the push, the polling backstop, and reconciliation never
+double-deliver, and a cancelled task can no longer be resurrected. The
+polling loop is kept only as a backstop for timeouts and stalled tasks.
+No configuration is required and nothing changes for existing setups.
+
 ## [5.6.2] — 2026-05-19
 
 ### Long background-task results now reliably arrive in chat

package/README.md

@@ -71,7 +71,7 @@ Alvin Bot sits in the same category as **Hermes Agent** (Nous Research) and **Op
 - **Use Hermes Agent when** you want a research-grade self-improving agent, need it to act as an **MCP server** for Claude Desktop / Cursor / VS Code, want 200+ model choice or many execution backends, and value a large community.
 - **Use OpenClaw when** you want the **widest messaging reach** (25–50+ channels) plus native mobile apps and voice activation, fully transparent plain-file memory you can git-track, and the largest ecosystem.
 
-<!-- comparison-page link intentionally deferred until the landing page is live (HTTP 200); re-enabled in a separate commit per docs/positioning/05-SHIP-CHECKLIST.md Step 5 -->
+A longer head-to-head with FAQ and decision guide: **[Alvin Bot vs Hermes vs OpenClaw](https://alvin.alev-b.com/vs/hermes-openclaw)**.
 
 ---
 

package/dist/services/alvin-dispatch.js

@@ -35,6 +35,40 @@ import { SUBAGENTS_DIR } from "../paths.js";
 function generateAgentId() {
     return "alvin-" + crypto.randomBytes(12).toString("hex");
 }
+/**
+ * v5.7.0 — Best-effort push: tell the bot a detached sub-agent just
+ * exited so it can read the jsonl and deliver immediately instead of
+ * waiting for the next 15s poll tick. An in-process self-call to the
+ * always-on loopback route. Any failure (bot mid-restart, port race,
+ * network) is swallowed — startup reconciliation and the poll backstop
+ * are the safety nets. Never throws, always resolves.
+ */
+export async function postSubagentExit(agentId, exitCode) {
+    try {
+        const { getWebPort, getInternalToken } = await import("../web/server.js");
+        const port = getWebPort();
+        const token = getInternalToken();
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 4000);
+        try {
+            await fetch(`http://127.0.0.1:${port}/internal/subagent-exit`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify({ agentId, exitCode }),
+                signal: ac.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    catch {
+        /* best-effort — reconciliation/poll backstop cover any miss */
+    }
+}
 /**
  * Dispatch a detached sub-agent. Returns synchronously — the subprocess
  * runs in the background. Throws if spawn fails. On success:
@@ -96,6 +130,16 @@ export function dispatchDetachedAgent(input) {
     catch {
         /* ignore */
     }
+    // v5.7.0 — Push: deliver the result the instant the subprocess exits,
+    // instead of waiting for the next 15s poll tick. `exit` fires after
+    // the OS has reaped the process and flushed its inherited stdout FD,
+    // so the terminating result line is fully on disk before the handler
+    // reads it (race-safe). Best-effort: startup reconciliation + the poll
+    // backstop cover a missed push (bot restarted mid-run, port race).
+    // Attached before unref() so the listener is registered on the handle.
+    child.on("exit", (code) => {
+        void postSubagentExit(agentId, code);
+    });
     // Detach from parent Node's event loop so parent exit doesn't wait.
     child.unref();
     // Register with watcher so it polls the output file and delivers.

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

@@ -23,9 +23,10 @@
  * for the JSONL format details.
  */
 import fs from "fs";
-import { dirname } from "path";
+import { dirname, resolve } from "path";
 import { parseOutputFileStatus } from "./async-agent-parser.js";
-import { ASYNC_AGENTS_STATE_FILE } from "../paths.js";
+import { claimDelivery, markDelivered, isDelivered, cleanupAgentFiles, } from "./subagent-dedup.js";
+import { ASYNC_AGENTS_STATE_FILE, SUBAGENTS_DIR } from "../paths.js";
 import { getAllSessions } from "./session.js";
 /**
  * B3 — Detect a permanent "target chat does not exist" delivery failure
@@ -191,12 +192,133 @@ function decrementPendingCount(sessionKey) {
 export function listPendingAgents() {
     return [...pending.values()];
 }
-/** Start the polling loop. Idempotent. Loads any persisted state from disk. */
+/**
+ * v5.7.0 push entry point — called by POST /internal/subagent-exit when
+ * a detached subprocess exits. Looks the agent up, classifies its jsonl,
+ * and delivers immediately (claim-gated, so push / the poll backstop /
+ * reconciliation never double-deliver). Returns a coarse status for the
+ * HTTP layer:
+ *
+ *  - "unknown"   → no matching pending entry (cancelled, already
+ *                  delivered, or never tracked). HTTP 404. No side effect.
+ *  - "delivered" → terminal jsonl found and delivered (or the claim was
+ *                  lost to another path — either way it is handled and
+ *                  the entry is dropped). HTTP 200.
+ *  - "pending"   → exit fired but the jsonl is not yet terminal (rare
+ *                  flush race). Left to the poll backstop. HTTP 202.
+ */
+export async function deliverByAgentId(agentId) {
+    const entry = pending.get(agentId);
+    if (!entry)
+        return "unknown";
+    const status = await parseOutputFileStatus(entry.outputFile);
+    if (status.state === "completed") {
+        // Invariant: the path that WINS the claim owns removal of the
+        // shared pending entry. A claim-loser must not mutate shared state
+        // — the winner (this push, the poll backstop, or reconcile) removes
+        // it. If a winner ever crashes mid-delivery the next poll tick
+        // self-heals: claimDelivery() is false there too, so it skips
+        // re-delivery but still drops the entry. Either way "delivered".
+        if (claimDelivery(agentId)) {
+            await deliverAsCompleted(entry, status.output, status.tokensUsed);
+            pending.delete(agentId);
+            saveToDisk();
+        }
+        return "delivered";
+    }
+    if (status.state === "failed") {
+        if (claimDelivery(agentId)) {
+            await deliverAsFailure(entry, "error", status.error);
+            pending.delete(agentId);
+            saveToDisk();
+        }
+        return "delivered";
+    }
+    // running / missing → not yet flushed; the 15s poll backstop will get it.
+    return "pending";
+}
+/**
+ * v5.7.0 — Startup reconciliation. Runs once inside startWatcher() after
+ * loadFromDisk(). Two passes:
+ *
+ *  Pass A — immediate terminal drain. For every entry already in the
+ *  pending map (full delivery metadata present, restored by
+ *  loadFromDisk), check its jsonl ONCE: if terminal, deliver immediately
+ *  at startup instead of waiting up to 15s for the first poll tick. This
+ *  is what removes the post-restart latency the BACKLOG observed and
+ *  works even if the poll loop were disabled. Claim-gated.
+ *
+ *  Pass B — disk hygiene, never delivers. Walk SUBAGENTS_DIR: skip
+ *  delivered/tombstoned agents, age-cap-clean ancient files, and leave
+ *  fresh orphans (jsonl with no persisted state entry → no delivery
+ *  target) untouched for a later age-cap. We never fabricate a target.
+ *
+ * Idempotent (re-runnable), dedup-guarded by the .delivered marker.
+ */
+async function reconcileOnStartup() {
+    // Pass A — drain pending entries with full metadata.
+    for (const entry of [...pending.values()]) {
+        try {
+            if (isDelivered(entry.agentId)) {
+                pending.delete(entry.agentId);
+                continue;
+            }
+            const status = await parseOutputFileStatus(entry.outputFile);
+            if (status.state === "completed" && claimDelivery(entry.agentId)) {
+                await deliverAsCompleted(entry, status.output, status.tokensUsed);
+                pending.delete(entry.agentId);
+            }
+            else if (status.state === "failed" && claimDelivery(entry.agentId)) {
+                await deliverAsFailure(entry, "error", status.error);
+                pending.delete(entry.agentId);
+            }
+        }
+        catch (err) {
+            console.error(`[async-watcher] reconcile passA ${entry.agentId}:`, err);
+        }
+    }
+    saveToDisk();
+    // Pass B — disk hygiene. Never delivers.
+    let files;
+    try {
+        files = fs.readdirSync(SUBAGENTS_DIR);
+    }
+    catch {
+        return; // no subagents dir yet — nothing to reconcile
+    }
+    const now = Date.now();
+    for (const f of files) {
+        if (!f.endsWith(".jsonl"))
+            continue;
+        const agentId = f.slice(0, -".jsonl".length);
+        if (isDelivered(agentId))
+            continue; // delivered or cancel-tombstone
+        if (pending.has(agentId))
+            continue; // Pass A / poll / push own it
+        const jsonlPath = resolve(SUBAGENTS_DIR, f);
+        try {
+            const st = fs.statSync(jsonlPath);
+            if (now - st.mtimeMs > MAX_AGENT_AGE_MS) {
+                cleanupAgentFiles(agentId); // ancient orphan → clean
+            }
+            // else: orphan within age, no persisted target → cannot deliver;
+            // leave it (age-cap cleans it on a later boot). No spam, no
+            // fabricated delivery target.
+        }
+        catch {
+            /* stat race — ignore */
+        }
+    }
+}
+/** Start the polling loop. Idempotent. Loads any persisted state from
+ *  disk, then runs startup reconciliation (immediate terminal drain +
+ *  disk hygiene) before the 15s poll backstop begins. */
 export function startWatcher() {
     if (started)
         return;
     started = true;
     loadFromDisk();
+    void reconcileOnStartup().catch((err) => console.error("[async-watcher] reconcile failed:", err));
     pollTimer = setInterval(() => {
         pollOnce().catch((err) => console.error("[async-watcher] poll cycle failed:", err));
     }, POLL_INTERVAL_MS);
@@ -235,21 +357,31 @@ export async function pollOnce() {
         entry.lastCheckedAt = now;
         // Timeout check first — if the agent is past its giveUpAt, give up
         // regardless of whether the file shows progress.
+        // v5.7.0 — every terminal delivery is claim-gated so push,
+        // this poll backstop, and startup reconciliation never
+        // double-deliver. A lost claim means another path already
+        // handled it: just drop the entry without re-delivering.
         if (now >= entry.giveUpAt) {
-            const outcome = await deliverAsFailure(entry, "timeout", "Agent ran longer than 12h — giving up");
-            abandonIfInvalidTarget(entry, outcome);
+            if (claimDelivery(entry.agentId)) {
+                const outcome = await deliverAsFailure(entry, "timeout", "Agent ran longer than 12h — giving up");
+                abandonIfInvalidTarget(entry, outcome);
+            }
             toRemove.push(entry.agentId);
             continue;
         }
         const status = await parseOutputFileStatus(entry.outputFile);
         if (status.state === "completed") {
-            const outcome = await deliverAsCompleted(entry, status.output, status.tokensUsed);
-            abandonIfInvalidTarget(entry, outcome);
+            if (claimDelivery(entry.agentId)) {
+                const outcome = await deliverAsCompleted(entry, status.output, status.tokensUsed);
+                abandonIfInvalidTarget(entry, outcome);
+            }
             toRemove.push(entry.agentId);
         }
         else if (status.state === "failed") {
-            const outcome = await deliverAsFailure(entry, "error", status.error);
-            abandonIfInvalidTarget(entry, outcome);
+            if (claimDelivery(entry.agentId)) {
+                const outcome = await deliverAsFailure(entry, "error", status.error);
+                abandonIfInvalidTarget(entry, outcome);
+            }
             toRemove.push(entry.agentId);
         }
         else if (status.state === "missing" &&
@@ -257,8 +389,10 @@ export async function pollOnce() {
             // v4.14.2 — Zombie guard: the subprocess never created its
             // output file within `missingFileFailureMs` (default 10 min).
             // Declare failed instead of polling until the 12h giveUpAt.
-            const outcome = await deliverAsFailure(entry, "error", `Dispatched subprocess never wrote its output file (${Math.round((now - entry.startedAt) / 60_000)}m after start). Likely crashed before initializing, or the file was removed externally.`);
-            abandonIfInvalidTarget(entry, outcome);
+            if (claimDelivery(entry.agentId)) {
+                const outcome = await deliverAsFailure(entry, "error", `Dispatched subprocess never wrote its output file (${Math.round((now - entry.startedAt) / 60_000)}m after start). Likely crashed before initializing, or the file was removed externally.`);
+                abandonIfInvalidTarget(entry, outcome);
+            }
             toRemove.push(entry.agentId);
         }
         // running / missing-but-young → keep polling next cycle
@@ -424,6 +558,12 @@ export function cancelPendingForSession(sessionKey) {
     let changed = false;
     for (const [id, entry] of pending.entries()) {
         if (entry.sessionKey === sessionKey) {
+            // v5.7.0 — tombstone before removal: a cancelled agent's
+            // subprocess may still exit later and POST, or its leftover jsonl
+            // may be rediscovered by reconciliation on a future boot. The
+            // .delivered marker makes "cancelled" authoritative and
+            // restart-proof so neither path can resurrect it.
+            markDelivered(entry.agentId);
             pending.delete(id);
             changed = true;
         }

package/dist/services/subagent-dedup.js

@@ -0,0 +1,86 @@
+/**
+ * Atomic deliver-once primitive for detached sub-agents (v5.7.0).
+ *
+ * The single source of truth for "has this agent's result already been
+ * delivered (or been cancel-tombstoned)?" — shared by all three delivery
+ * paths: the exit-push endpoint, the 15s poll backstop, and startup
+ * reconciliation. The marker is an empty `<agentId>.delivered` file in
+ * SUBAGENTS_DIR; `claimDelivery` creates it with O_EXCL ("wx") so exactly
+ * one caller wins the race. Crash-safe and restart-safe (it is on disk),
+ * which the in-memory pending map alone cannot be.
+ */
+import fs from "fs";
+import { resolve } from "path";
+import { SUBAGENTS_DIR } from "../paths.js";
+function markerPath(agentId) {
+    return resolve(SUBAGENTS_DIR, `${agentId}.delivered`);
+}
+function ensureDir() {
+    try {
+        fs.mkdirSync(SUBAGENTS_DIR, { recursive: true });
+    }
+    catch {
+        /* race-safe — a concurrent create is fine */
+    }
+}
+/**
+ * Attempt to claim delivery for `agentId`. Returns true exactly once
+ * (the caller that atomically created the marker) and false for every
+ * subsequent call. On an unexpected fs error other than EEXIST we return
+ * true: a rare double-delivery (a duplicate message) is strictly
+ * preferable to silently losing a result — the exact bug this whole
+ * feature exists to fix.
+ */
+export function claimDelivery(agentId) {
+    ensureDir();
+    try {
+        const fd = fs.openSync(markerPath(agentId), "wx");
+        fs.closeSync(fd);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        return true; // prefer a possible duplicate over a lost delivery
+    }
+}
+/**
+ * Write the marker if absent, ignore if already present. Used as a
+ * cancel tombstone (claim-without-deliver) so a cancelled agent can
+ * never be resurrected by push or reconciliation. Idempotent; never
+ * throws.
+ */
+export function markDelivered(agentId) {
+    ensureDir();
+    try {
+        const fd = fs.openSync(markerPath(agentId), "wx");
+        fs.closeSync(fd);
+    }
+    catch {
+        /* EEXIST or fs error — tombstone already effective / best-effort */
+    }
+}
+/** True if a delivered/tombstone marker exists for this agent. */
+export function isDelivered(agentId) {
+    try {
+        return fs.existsSync(markerPath(agentId));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Best-effort removal of every on-disk artifact for an aged-out agent
+ * (jsonl + err + delivered marker). Used by reconciliation's age-cap so
+ * ancient files don't accumulate. Never throws.
+ */
+export function cleanupAgentFiles(agentId) {
+    for (const ext of [".jsonl", ".err", ".delivered"]) {
+        try {
+            fs.unlinkSync(resolve(SUBAGENTS_DIR, `${agentId}${ext}`));
+        }
+        catch {
+            /* ignore — already gone or never existed */
+        }
+    }
+}

package/dist/web/server.js

@@ -12,6 +12,7 @@ import fs from "fs";
 import path from "path";
 import { resolve } from "path";
 import { execSync } from "child_process";
+import crypto from "crypto";
 import { WebSocketServer, WebSocket } from "ws";
 import { getRegistry } from "../engine.js";
 import { getSession, resetSession, getAllSessions } from "../services/session.js";
@@ -51,6 +52,18 @@ let bindRetryTimer = null;
  *  this and exits silently if set, so stop is truly terminal. */
 let stopRequested = false;
 const WEB_PASSWORD = process.env.WEB_PASSWORD || "";
+/**
+ * v5.7.0 — Per-boot random token guarding POST /internal/subagent-exit.
+ * Generated once at module load; never persisted, never logged. The
+ * detached-agent exit hook reads it in-process via getInternalToken().
+ * The route is loopback-bound by default; this token additionally
+ * defends the opt-in WEB_HOST=0.0.0.0 (LAN-exposed) case. 48 hex chars.
+ */
+const INTERNAL_TOKEN = crypto.randomBytes(24).toString("hex");
+/** In-process accessor for the per-boot internal-route token. */
+export function getInternalToken() {
+    return INTERNAL_TOKEN;
+}
 /** The actual port the Web UI is running on (may differ from WEB_PORT if busy). */
 let actualWebPort = WEB_PORT;
 // ── MIME Types ──────────────────────────────────────────
@@ -154,6 +167,56 @@ async function handleAPI(req, res, urlPath, body) {
         }
         return;
     }
+    // POST /internal/subagent-exit — detached sub-agent exit push (v5.7.0).
+    // Always available (NO WEBHOOK_ENABLED dependency, so it works for every
+    // install with zero config); loopback-bound by default; per-boot bearer
+    // token. Reads the agent's jsonl, classifies, delivers immediately
+    // (claim-gated). Idempotent — a repeat POST is a 404 no-op.
+    if (urlPath === "/internal/subagent-exit" && req.method === "POST") {
+        // The legitimate payload is ~80 bytes ({agentId, exitCode}). Reject
+        // anything absurd before the auth compare so an unauthenticated
+        // caller (only reachable at all under the opt-in WEB_HOST=0.0.0.0)
+        // cannot push large bodies through this always-on route. (A deeper
+        // streaming cap on the shared body accumulator — also used by
+        // /api/ and /v1/ — is a separate pre-existing hardening item.)
+        if (body.length > 8 * 1024) {
+            res.statusCode = 413;
+            res.end(JSON.stringify({ error: "Payload too large" }));
+            return;
+        }
+        if (!timingSafeBearerMatch(req.headers.authorization, INTERNAL_TOKEN)) {
+            res.statusCode = 401;
+            res.end(JSON.stringify({ error: "Unauthorized" }));
+            return;
+        }
+        let agentId;
+        try {
+            const payload = JSON.parse(body);
+            agentId = typeof payload.agentId === "string" ? payload.agentId : "";
+        }
+        catch {
+            res.statusCode = 400;
+            res.end(JSON.stringify({ error: "Invalid JSON body" }));
+            return;
+        }
+        if (!agentId) {
+            res.statusCode = 400;
+            res.end(JSON.stringify({ error: "Missing agentId" }));
+            return;
+        }
+        try {
+            const { deliverByAgentId } = await import("../services/async-agent-watcher.js");
+            const outcome = await deliverByAgentId(agentId);
+            res.statusCode = outcome === "unknown" ? 404 : outcome === "pending" ? 202 : 200;
+            res.end(JSON.stringify({ ok: outcome !== "unknown", outcome }));
+        }
+        catch (err) {
+            res.statusCode = 500;
+            res.end(JSON.stringify({ error: "delivery failed" }));
+            console.error("[internal/subagent-exit] delivery error:", err);
+        }
+        return;
+    }
     // Auth check for all other API routes
     if (!checkAuth(req)) {
         res.statusCode = 401;
@@ -1580,6 +1643,14 @@ function handleWebRequest(req, res) {
             handleAPI(req, res, urlPath, body);
             return;
         }
+        // v5.7.0 — internal bot-to-bot routes (detached sub-agent exit
+        // push). Dispatched through handleAPI, which bearer-auths it and
+        // returns before the cookie-auth gate. Kept off the /api/ prefix so
+        // it is never surfaced in the Web UI route surface.
+        if (urlPath.startsWith("/internal/")) {
+            handleAPI(req, res, urlPath, body);
+            return;
+        }
         // Auth page (if password set and not authenticated)
         if (WEB_PASSWORD && !checkAuth(req) && urlPath !== "/login.html") {
             res.writeHead(302, { Location: "/login.html" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "5.6.2",
+  "version": "5.7.0",
   "description": "Alvin Bot — open-source, self-hosted autonomous AI agent on Telegram, Slack, Discord, WhatsApp, Signal, terminal & web. Built on the Claude Agent SDK with a multi-provider engine (OpenAI, Groq, Gemini, NVIDIA NIM, OpenRouter, Ollama) and automatic failover, detached sub-agents that survive a parent abort, zero-config indexed memory (no embedding key needed), 4-tier browser automation, cron tasks, MCP client and a self-preservation subsystem. Local-first, telemetry-free. An OpenClaw / Hermes Agent alternative.",
   "type": "module",
   "main": "dist/index.js",