alvin-bot 5.6.1 → 5.6.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.6.2] — 2026-05-19
+
+### Long background-task results now reliably arrive in chat
+
+A background task that produced a long final answer could finish
+successfully and yet never be delivered — you would see nothing and
+have to ask for the status by hand. Alvin now recognises a finished
+background task no matter how long its result is, so the answer always
+lands in your chat the moment the task completes.
+
 ## [5.6.1] — 2026-05-18
 
 ### Background-task results stay in the chat

package/README.md

@@ -2,9 +2,9 @@
 
 > Your personal AI agent — on Telegram, WhatsApp, Discord, Slack, Signal, Terminal, and Web.
 
-Open-source, self-hosted, multi-model. Lives where you chat, has full shell + filesystem access, remembers across sessions, and dispatches detached sub-agents for long-running work. Built on the Claude Agent SDK with a provider-agnostic engine that also drives OpenAI, Groq, Gemini, NVIDIA NIM, OpenRouter, and Ollama.
+Alvin Bot is an open-source, MIT-licensed, self-hosted autonomous AI agent that runs on your own machine and answers you on Telegram, Slack, Discord, WhatsApp, Signal, a terminal TUI, and a web dashboard. It is built on the official Claude Agent SDK and runs a provider-agnostic engine that also drives OpenAI, Groq, Google Gemini, NVIDIA NIM, OpenRouter, and Ollama, with automatic failover after two consecutive provider failures and a heartbeat health check every five minutes. Unlike most personal AI agents, it ships a zero-config indexed memory store: with no embedding API key it falls back to a built-in SQLite FTS5 keyword index, so recall works out of the box. It dispatches detached sub-agents as independent `claude -p` subprocesses that keep running and deliver their result even if the parent conversation is aborted. It is local-first and telemetry-free — prompts and responses are never logged off-machine, secrets live in a chmod-0600 `.env`, and shell execution is allowlisted by default.
 
-> **What's new — v4.22 (May 2026):** Pluggable memory backends — Gemini · OpenAI · Ollama · **FTS5 keyword fallback (zero-config)**. Users without an embedding API key now get a working indexed memory store out of the box. Smart inject mode trims ~25 k tokens per turn off long system prompts. [Full changelog →](CHANGELOG.md)
+> **What's new — v5.6.2 (May 2026):** Background-task and scheduled-job results now land cleanly in chat — a tight header (what ran, duration, tokens, success) plus the answer, with very long output attached as a single file instead of a wall of messages. Built on v5.5's instant, honest ⛔ Stop and calmer, evidence-based health monitoring. Earlier in the 5.x line: a zero-config FTS5 keyword memory index (indexed recall with **no embedding API key**), automatic multi-provider failover with a 5-minute heartbeat monitor, and detached sub-agents that survive a parent abort. [Full changelog →](CHANGELOG.md)
 
 ---
 
@@ -47,6 +47,34 @@ Open-source, self-hosted, multi-model. Lives where you chat, has full shell + fi
 
 ---
 
+## ⚖️ How Alvin Bot compares
+
+Alvin Bot sits in the same category as **Hermes Agent** (Nous Research) and **OpenClaw** — self-hosted, open-source personal AI agents that live on your machine and reach you on the chat apps you already use. They optimize for different things. This table is intended to be fair: where Hermes or OpenClaw is the better tool, it says so.
+
+| Dimension | **Alvin Bot** | **Hermes Agent** | **OpenClaw** |
+|---|---|---|---|
+| License / hosting | MIT · self-hosted · local-first · zero telemetry | MIT · self-hosted · 7 execution backends | Open-source · self-hosted · bring-your-own-key |
+| Model providers | Claude Agent SDK + OpenAI · Groq · Gemini · NVIDIA NIM · OpenRouter · Ollama, with **automatic failover after 2 provider failures + a 5-min heartbeat monitor** | 200+ models | Bring-your-own model / key |
+| Sub-agents | **Detached `claude -p` subprocesses that survive a parent abort**; `readonly`/`research` toolset presets | Isolated subagents for parallel workstreams | Not a primary focus |
+| Browser automation | **4-tier escalation**: WebFetch → stealth Playwright → persistent-profile CDP → agent-browser CLI | Built-in browse / vision tools | Via tools |
+| Platforms | Telegram · Slack · Discord · WhatsApp · Signal · terminal TUI · Web (7) | 20+ platforms from one gateway | 25–50+ platforms · native mobile apps · voice activation |
+| Memory | Layered L0–L3; SQLite embeddings with a **zero-config FTS5 keyword fallback (works with no API key)**; smart prompt-injection trims ~25 k tokens/turn | SQLite + full-text search · agent-curated · Honcho user profiling | Transparent plain Markdown/YAML files you can grep and git-track |
+| Extensibility | Hot-reload skills + 6 plugins · self-modifying skills · hooks · MCP client | 40+ built-in tools · **autonomous self-improving skill loop** | Skills as files · very large ecosystem |
+| MCP | MCP **client** (connect any MCP server) | MCP client **and `hermes mcp serve`** (acts as an MCP server for Claude Desktop / Cursor / VS Code) | Tool integrations |
+| Self-healing | **Startup preflight · dead-man's-switch heartbeat · crash forensic bundles · AI self-diagnosis · crash-loop brake · trend anomaly detection** | Stable in practice; self-improving | Frequent updates can break running instances |
+| Security defaults | Exec **allowlist + shell-metachar filter on by default** · DM pairing · timing-safe webhook auth · 0600 file perms enforced · `alvin-bot audit` CLI · honestly documented threat model | Standard | Standard |
+| Maturity / community | Small, focused, single-maintainer; modest public adoption | Large community, Nous Research team | Large community + team, Nvidia NemoClaw fork |
+
+### Use the right tool for the job
+
+- **Use Alvin Bot when** you want one resilient, self-healing agent on your own box that keeps working when a provider rate-limits or fails, gives you indexed memory **without buying an embedding API key**, ships safe-by-default execution sandboxing, and is built directly on the official Claude Agent SDK — and you mainly live in Telegram / Slack / Discord / WhatsApp / Signal.
+- **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 -->
+
+---
+
 ## 🚀 Quick Start
 
 ```bash

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

@@ -68,6 +68,92 @@ export function parseAsyncLaunchedToolResult(raw) {
     return { agentId, outputFile };
 }
 const DEFAULT_TAIL_BYTES = 64 * 1024;
+/**
+ * Upper bound for the window-independent final-line read (see
+ * readLastCompleteLine). Generous — ~128× the tail window — so any
+ * realistic final report is captured, but bounded so a pathological
+ * single line can't blow up memory. Beyond this we fall back to the
+ * windowed / staleness logic unchanged.
+ */
+const MAX_LAST_LINE_BYTES = 8 * 1024 * 1024;
+/**
+ * Read the LAST complete newline-delimited record of the file, regardless
+ * of how large it is, by scanning backward from EOF in chunks.
+ *
+ * Why this exists: for `claude -p --output-format stream-json` the
+ * terminating `{"type":"result",...}` event is ALWAYS the final line, but
+ * that line embeds the entire final report and is frequently larger than
+ * DEFAULT_TAIL_BYTES (e.g. an agent that writes a long status report
+ * after an auto-declined AskUserQuestion). The windowed tail read drops
+ * such a line as a truncated head fragment, so completion was missed and
+ * the agent sat "running" until the 12 h timeout — never auto-delivered.
+ * Reading the true final line makes completion detection independent of
+ * the tail-window size.
+ *
+ * Returns the final record WITHOUT its trailing newline, or null if the
+ * file is empty, the final line is not newline-terminated (still being
+ * written), or the line exceeds MAX_LAST_LINE_BYTES. In every null case
+ * the caller falls through to the existing windowed/staleness logic with
+ * no behavior change.
+ */
+async function readLastCompleteLine(path, size) {
+    if (size <= 0)
+        return null;
+    let fh;
+    try {
+        fh = await fs.open(path, "r");
+        const chunkSize = 64 * 1024;
+        let pos = size;
+        let collected = Buffer.alloc(0);
+        while (pos > 0) {
+            if (size - pos > MAX_LAST_LINE_BYTES)
+                return null;
+            const readLen = Math.min(chunkSize, pos);
+            pos -= readLen;
+            const buf = Buffer.alloc(readLen);
+            await fh.read(buf, 0, readLen, pos);
+            collected = Buffer.concat([buf, collected]);
+            // Strip exactly one trailing newline (the file terminator) so we
+            // search for the delimiter BEFORE the final record, not after it.
+            let end = collected.length;
+            if (end > 0 && collected[end - 1] === 0x0a) {
+                end--;
+                if (end > 0 && collected[end - 1] === 0x0d)
+                    end--;
+            }
+            else {
+                // No terminating newline → final line still being written.
+                return null;
+            }
+            if (end <= 0) {
+                // File is just a newline (or empty after trim) — nothing usable.
+                if (pos === 0)
+                    return null;
+                continue;
+            }
+            const nl = collected.lastIndexOf(0x0a, end - 1);
+            if (nl >= 0) {
+                return collected.toString("utf-8", nl + 1, end);
+            }
+            if (pos === 0) {
+                // Whole file is a single (newline-terminated) record.
+                return collected.toString("utf-8", 0, end);
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            await fh?.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
 /**
  * v4.12.4 — Default staleness window for partial-output delivery.
  *
@@ -148,12 +234,67 @@ export async function parseOutputFileStatus(path, opts = {}) {
     const usable = lines
         .slice(headIncomplete, lines.length - (trailIncomplete > 0 ? trailIncomplete : 0))
         .filter((l) => l.length > 0);
+    // Window-independent completion check (regression fix). The terminating
+    // `{"type":"result",...}` event for `claude -p --output-format
+    // stream-json` is ALWAYS the final line, but it embeds the whole final
+    // report and is routinely larger than maxTailBytes — the windowed tail
+    // below would drop it as a truncated head fragment, leaving the agent
+    // mis-classified "running" until the 12 h timeout (so a completed
+    // sub-agent is never auto-delivered and the user must ask "status?").
+    // Inspect the TRUE final complete line directly so detection no longer
+    // depends on the tail-window size. Falls through unchanged when the
+    // last line is not a result event (running / killed mid-write / etc.).
+    const finalLine = await readLastCompleteLine(path, stat.size);
+    if (finalLine) {
+        let parsedFinal = null;
+        try {
+            parsedFinal = JSON.parse(finalLine);
+        }
+        catch {
+            parsedFinal = null;
+        }
+        if (parsedFinal && parsedFinal.type === "result") {
+            let output = typeof parsedFinal.result === "string" ? parsedFinal.result : "";
+            if (!output) {
+                // Same aggregation fallback as the windowed FIRST PASS: when the
+                // result event carries no `result` text, stitch together the
+                // assistant text blocks visible in the tail.
+                const fragments = [];
+                for (const line of usable) {
+                    let p;
+                    try {
+                        p = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (p.type === "assistant" && Array.isArray(p.message?.content)) {
+                        for (const c of p.message.content) {
+                            if (c?.type === "text" && typeof c.text === "string") {
+                                fragments.push(c.text);
+                            }
+                        }
+                    }
+                }
+                output = fragments.join("\n\n").trim();
+            }
+            const usage = parsedFinal.usage;
+            const tokensUsed = usage
+                ? {
+                    input: usage.input_tokens ?? 0,
+                    output: usage.output_tokens ?? 0,
+                }
+                : undefined;
+            return { state: "completed", output, tokensUsed };
+        }
+    }
     // v4.13 — FIRST PASS: look for a `{"type":"result"}` event anywhere in
     // the tail. This is the completion signal for `claude -p
     // --output-format stream-json` output (used by the v4.13 dispatch
     // mechanism). When present, the `result` field holds the authoritative
     // final text. If `result.result` is missing, aggregate from all
-    // assistant text blocks in the tail.
+    // assistant text blocks in the tail. (Retained as a defensive fallback
+    // for the rare case the result event is NOT the final line.)
     for (let i = usable.length - 1; i >= 0; i--) {
         let parsed;
         try {

package/llms.txt

@@ -0,0 +1,38 @@
+# Alvin Bot
+
+> Alvin Bot is an open-source, MIT-licensed, self-hosted autonomous AI agent that runs on your own machine and answers you on Telegram, Slack, Discord, WhatsApp, Signal, a terminal TUI, and a web dashboard. It is built on the official Claude Agent SDK and runs a provider-agnostic engine that also drives OpenAI, Groq, Google Gemini, NVIDIA NIM, OpenRouter, and Ollama, with automatic failover after two consecutive provider failures and a heartbeat health check every five minutes. It is local-first and telemetry-free: prompts and responses are never logged off-machine, secrets live in a chmod-0600 .env, and shell execution is allowlisted by default.
+
+Alvin Bot is in the same category as Hermes Agent (Nous Research) and OpenClaw: a self-hosted personal AI agent with persistent memory, scheduled tasks, real shell/filesystem access, and multi-platform chat delivery. It differentiates on resilience (automatic provider failover + a self-preservation subsystem), zero-config memory (indexed recall with no embedding API key), detached sub-agents that survive a parent abort, and safe-by-default security.
+
+## Key capabilities
+
+- Multi-provider engine: Claude Agent SDK + OpenAI, Groq, Google Gemini, NVIDIA NIM, OpenRouter, Ollama, any OpenAI-compatible API; automatic failover after 2 provider failures, 5-minute heartbeat health check, reorderable fallback chain.
+- Detached sub-agents: `alvin_dispatch_agent` spawns independent `claude -p` subprocesses that keep running and deliver their result even if the parent conversation is aborted; `readonly`/`research` toolset presets restrict their privileges.
+- Zero-config layered memory: SQLite embeddings store with a built-in FTS5 keyword fallback so indexed recall works with no embedding API key; smart prompt-injection mode trims ~25k tokens/turn once the store is populated.
+- 4-tier browser automation: WebFetch → stealth Playwright → persistent-profile Chromium over CDP → opt-in agent-browser CLI; handles login-walled and bot-protected pages.
+- Self-preservation subsystem: startup preflight, dead-man's-switch heartbeat, crash forensic bundles, AI self-diagnosis, crash-loop brake, daily trend anomaly detection — detects and recovers from its own failures unattended.
+- Multi-platform: Telegram, Slack (one channel = one isolated workspace), Discord, WhatsApp (owner-approval gate), Signal, terminal TUI, full web dashboard.
+- Cron / scheduled AI tasks in natural language (e.g. "check my email every morning"); MCP client (connect any Model Context Protocol server); hot-reload skills + 6 built-in plugins; hooks; per-channel context-isolated workspaces with shared memory.
+- Security defaults: exec allowlist + shell-metachar filter on by default, DM pairing, timing-safe webhook auth, enforced 0600 file permissions, `alvin-bot audit` CLI, an honestly documented threat model (prompt injection is acknowledged as unsolved, not pretended away).
+- Distribution: npm global install, from-source, one-line installer, Docker, macOS Electron .dmg with system tray; macOS launchd integration keeps the Claude Max OAuth token working across restarts.
+
+## When to use Alvin Bot
+
+- Use Alvin Bot when you want one resilient, self-healing personal agent on your own machine that keeps working when a provider fails, gives you indexed memory without buying an embedding API key, ships safe-by-default execution sandboxing, and is built directly on the official Claude Agent SDK.
+- Use Hermes Agent when you want a research-grade self-improving learning loop, need the agent to act as an MCP server for Claude Desktop / Cursor / VS Code, want 200+ model choice or many execution backends, or 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.
+
+## Documentation
+
+- [README](https://github.com/alvbln/Alvin-Bot/blob/main/README.md): full feature list, quick start, architecture, provider matrix, configuration.
+- [Handbook](https://github.com/alvbln/Alvin-Bot/blob/main/docs/HANDBOOK.md): complete standalone reference — providers, sub-agents, cron, plugins, MCP, platforms.
+- [Changelog](https://github.com/alvbln/Alvin-Bot/blob/main/CHANGELOG.md): per-release notes; current version 5.6.1.
+- [Security threat model](https://github.com/alvbln/Alvin-Bot/blob/main/docs/security.md): honest threat model and hardening guide.
+- [Alvin Bot vs Hermes vs OpenClaw](https://alvin.alev-b.com/vs/hermes-openclaw): fair, named head-to-head comparison and decision guide.
+- [npm package](https://www.npmjs.com/package/alvin-bot): `npm install -g alvin-bot`.
+- [GitHub repository](https://github.com/alvbln/Alvin-Bot): source, issues, releases.
+
+## Optional
+
+- [Multi-session workspaces](https://github.com/alvbln/Alvin-Bot/blob/main/README.md#-multi-session-workspaces-v4120): parallel per-channel context-isolated sessions with globally shared memory.
+- [Slack setup](https://github.com/alvbln/Alvin-Bot/releases/latest): copy-paste Slack App manifest + step-by-step guide.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "alvin-bot",
-  "version": "5.6.1",
-  "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
+  "version": "5.6.2",
+  "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",
   "bin": {
@@ -143,6 +143,8 @@
     "ai",
     "claude",
     "agent",
+    "ai-agent",
+    "autonomous-agent",
     "llm",
     "multi-model",
     "gpt",
@@ -150,14 +152,26 @@
     "nvidia",
     "self-hosted",
     "autonomous",
+    "personal-assistant",
     "whatsapp",
     "discord",
     "signal",
+    "slack",
     "openai",
     "groq",
+    "ollama",
+    "openrouter",
     "chatbot",
     "assistant",
-    "electron"
+    "electron",
+    "sub-agents",
+    "mcp",
+    "mcp-client",
+    "claude-agent-sdk",
+    "cron",
+    "skills",
+    "openclaw-alternative",
+    "hermes-alternative"
   ],
   "author": "alvbln",
   "license": "MIT",