alvin-bot 5.6.0 → 5.6.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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
+
+Results from scheduled and background tasks now appear directly in
+the chat as before. Only an output long enough to span more than two
+messages comes as a single attached file instead — keeping your chat
+tidy without ever splitting a result across a wall of messages. No
+"shortened" notices on normal-sized results; you stay in control of
+when something gets saved as a file.
+
+As always, verified with a fresh-install + stress test on a clean
+separate machine.
+
 ## [5.6.0] — 2026-05-18
 
 ### Background-task reports are now clean and to the point

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/paths.js

@@ -19,8 +19,13 @@ export const DATA_DIR = resolve(process.env.ALVIN_DATA_DIR || resolve(os.homedir
 export const PUBLIC_DIR = resolve(BOT_ROOT, "web", "public");
 /** plugins/ — Plugin directory */
 export const PLUGINS_DIR = resolve(BOT_ROOT, "plugins");
-/** skills/ — Skill definitions */
-export const SKILLS_DIR = resolve(BOT_ROOT, "skills");
+/** skills/ — Skill definitions.
+ *  Defaults to BOT_ROOT/skills (repo). Override with ALVIN_SKILLS_DIR so
+ *  tests can redirect skill writes into a throwaway sandbox instead of
+ *  polluting the real repo. Default (no env) is byte-identical to before. */
+export const SKILLS_DIR = process.env.ALVIN_SKILLS_DIR
+    ? resolve(process.env.ALVIN_SKILLS_DIR)
+    : resolve(BOT_ROOT, "skills");
 /** User skills directory (custom, outside repo) */
 export const USER_SKILLS_DIR = resolve(DATA_DIR, "skills");
 /** Example/template files (always in repo) */

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/dist/services/subagent-delivery.js

@@ -56,52 +56,39 @@ async function sendWithMarkdownFallback(api, chatId, text) {
     }
 }
 const MAX_TG_CHUNK = 3800; // below Telegram's 4096 limit with headroom
-// V56-T2 honesty fix — the .md file attachment is no longer gated on a
-// separate 20k threshold. It now triggers whenever the cap actually
-// truncates (isTruncated → body.length > BODY_CAP), so every truncated
-// delivery carries the full output as a file and the marker is honest.
-// (The prior 20k-only behavior is fully subsumed by isTruncated.)
 /**
- * V56-T2 (Layer-2) — honest hard cap on the INLINE delivered body.
+ * Post-v5.6.0 delivery routing — by message count, NOT by a truncating
+ * cap.
  *
- * V56-T1 made delivery carry the SDK final result instead of the whole
- * transcript, but a final result can itself occasionally be very long.
- * This bounds the inline-message body so a single agent answer can't
- * flood the chat, while staying HONEST.
+ * v5.6.0 introduced an inline body cap (1800 chars + a
+ * "…(truncated for chat — full output attached)" marker) that ALWAYS
+ * attached the full body as a `.md` file whenever it truncated. The
+ * effect was that even a small ~4 KB result got truncated + filed,
+ * which the user disliked. That cap is removed entirely.
  *
- * Honesty contract (fixed after a review found a self-defeating
- * regression): whenever `capBody` actually truncates — i.e. the body is
- * non-empty AND longer than BODY_CAP — the delivery ALSO attaches the
- * COMPLETE uncapped output as a `.md` file via the same upload
- * mechanism the old >20000-char path already used. The marker
- * therefore truthfully says the full output is *attached*, instead of
- * the previous wording that pointed at a `~/.alvin-bot/logs/` file the
- * cap path never actually wrote. Net effect: any truncated delivery =
- * bounded inline message + full `.md` attachment; no lossy inline-only
- * range remains. The old >20000 path is unchanged (it already attached
- * the full body); this just extends "attach the full file" down to
- * "whenever the cap truncated".
+ * V56-T1 ("deliver the final result, not the transcript") is kept — a
+ * normal final result is usually short and now simply appears inline
+ * like it did before v5.6.0.
  *
- * This is a pure bounded slice + a fixed marker — NOT a structure-
- * guessing heuristic. It no-ops on empty/whitespace so the
- * `(empty output)` truncated-run signal keeps working (and no spurious
- * file is attached for it).
- */
-const BODY_CAP = 1800;
-const TRUNCATION_MARKER = "…(truncated for chat — full output attached)";
-/**
- * True when `capBody` would actually truncate this body — the single
- * source of truth for "did we drop content, so the full output must be
- * attached as a file". Mirrors the `length > BODY_CAP` test in capBody.
+ * The body is routed by how many Telegram messages it would need
+ * (MAX_TG_CHUNK = 3800):
+ *   - body ≤ 1×MAX_TG_CHUNK            → ONE inline message
+ *   - 1×MAX_TG_CHUNK < body ≤ 2×       → inline across exactly 2
+ *                                         messages (no marker, no file)
+ *   - body > 2×MAX_TG_CHUNK (≥3 chunks)→ do NOT spam 3+ messages: send
+ *                                         the compact header + ONE
+ *                                         short neutral note + the FULL
+ *                                         (uncapped, complete) body as a
+ *                                         `.md` file attachment
+ *
+ * The `(empty output)` truncated-run signal (~14 chars) is tier-1, so
+ * it stays a single inline message with no note and no file.
+ *
+ * The file in the ≥3-chunk case is the COMPLETE body — nothing is cut,
+ * so the note must NOT say "truncated". It is a minimal neutral line.
  */
-function isTruncated(body) {
-    return body.length > BODY_CAP;
-}
-function capBody(body) {
-    if (body.length <= BODY_CAP)
-        return body;
-    return `${body.slice(0, BODY_CAP)}\n\n${TRUNCATION_MARKER}`;
-}
+const FILE_THRESHOLD = MAX_TG_CHUNK * 2; // > this ⇒ would need ≥3 messages
+const FULL_RESULT_NOTE = "📎 Full result attached (too long for chat).";
 let injectedApi = null;
 let runtimeApi = null;
 /** Test-only hook for injecting a fake bot API. Production code must NEVER call this. */
@@ -346,56 +333,40 @@ export async function deliverSubAgentResult(info, result, opts = {}) {
     }
     const banner = buildBanner(info, result);
     const body = result.output?.trim() || `(empty output)`;
-    // V56-T2 — bounded variant for the INLINE message path. Whenever this
-    // actually truncates (isTruncated), the FULL uncapped `body` is also
-    // attached as a .md file below, so the cap never costs the user
-    // access to the complete result and the marker stays truthful.
-    const inlineBody = capBody(body);
     try {
-        // Truncated → honest delivery: short banner + bounded inline body
-        // (with the truthful "full output attached" marker) + the COMPLETE
-        // uncapped body as a .md file. This single branch covers the whole
-        // truncated range (mid-size AND the old > 20000-char range): there
-        // is no lossy inline-only range anymore. (The old >20000 behavior
-        // is unchanged — it already attached the full body; the change is
-        // that mid-size now also attaches it and the marker no longer
-        // points at a logs file that was never written.)
-        if (isTruncated(body)) {
+        // Tier 3: body would need ≥3 Telegram messages → don't spam the
+        // chat. Send the compact header + ONE short neutral note + the FULL
+        // (uncapped, COMPLETE) body as a single `.md` file. Nothing is cut,
+        // so the note says nothing about truncation.
+        if (body.length > FILE_THRESHOLD) {
             await sendWithMarkdownFallback(api, tgChatId, banner);
-            // The bounded inline body fits in one message (BODY_CAP=1800 plus
-            // the short marker is well under MAX_TG_CHUNK); send it as plain
-            // text so an unbalanced markdown slice can't crash the send.
-            await api.sendMessage(tgChatId, inlineBody.slice(0, MAX_TG_CHUNK));
+            await api.sendMessage(tgChatId, FULL_RESULT_NOTE);
             try {
                 const { InputFile } = await import("grammy");
                 const buf = Buffer.from(body, "utf-8");
                 await api.sendDocument(tgChatId, new InputFile(buf, `${info.name}.md`));
             }
             catch (err) {
-                // Upload failed → the bounded inline body was already delivered
-                // above, so the user still has something honest (banner + capped
-                // text + marker). The marker slightly over-promises here (file
-                // didn't attach) but this is the rare failure path, not the
-                // normal one, and there is no silent data loss.
+                // Upload failed → the user still has the banner + the note, so
+                // they know a result exists and is large. Rare failure path,
+                // no silent data loss (nothing was promised inline).
                 console.error(`[subagent-delivery] file upload failed:`, err);
             }
             return OK;
         }
-        // Not truncated (body ≤ BODY_CAP) → unchanged passthrough.
-        // inlineBody === body here (capBody is a no-op), no marker, no file.
-        // Case A: fits in a single message → banner + body joined
-        if (inlineBody.length + banner.length + 2 <= MAX_TG_CHUNK) {
-            await sendWithMarkdownFallback(api, tgChatId, `${banner}\n\n${inlineBody}`);
+        // Tier 1: body fits with the banner in a single message → join.
+        if (body.length + banner.length + 2 <= MAX_TG_CHUNK) {
+            await sendWithMarkdownFallback(api, tgChatId, `${banner}\n\n${body}`);
             return OK;
         }
-        // Case B: defensive — a ≤1800-char body still under-runs MAX_TG_CHUNK
-        // with the banner, but keep the banner-then-chunk fallback for
-        // safety against an unusually long banner.
+        // Tier 1/2: body alone needs 1 or 2 messages (≤ 2×MAX_TG_CHUNK).
+        // Send the banner, then the body chunked across at most 2 messages.
+        // No marker, no file — this is the pre-v5.6.0 inline behavior.
         await sendWithMarkdownFallback(api, tgChatId, banner);
-        for (let i = 0; i < inlineBody.length; i += MAX_TG_CHUNK) {
+        for (let i = 0; i < body.length; i += MAX_TG_CHUNK) {
             // Body chunks are always sent as plain text — markdown across
             // arbitrary chunk boundaries would be inconsistent anyway.
-            await api.sendMessage(tgChatId, inlineBody.slice(i, i + MAX_TG_CHUNK));
+            await api.sendMessage(tgChatId, body.slice(i, i + MAX_TG_CHUNK));
         }
         return OK;
     }
@@ -428,25 +399,16 @@ async function deliverViaRegistry(platform, info, result) {
     const chatId = info.parentChatId;
     const banner = buildBannerPlain(info, result);
     const body = result.output?.trim() || `(empty output)`;
-    // V56-T2 — same honest contract as the Telegram path. Whenever the
-    // cap truncates, the FULL uncapped `body` is attached as a .md file
-    // (if the adapter supports uploads) so the marker stays truthful and
-    // the complete output remains accessible.
-    const inlineBody = capBody(body);
-    const NON_TG_CHUNK = 3800;
+    const NON_TG_CHUNK = MAX_TG_CHUNK; // same conservative 3800 cap
     try {
-        // Truncated → honest delivery: banner + bounded inline body (with
-        // the truthful "full output attached" marker) + the COMPLETE
-        // uncapped body as a .md file. Covers the whole truncated range
-        // (mid-size AND > the old 20k threshold) — no lossy inline-only
-        // range remains. If the adapter has no sendDocument or the upload
-        // fails, the bounded inline body still went out (honest, just no
-        // file) — no silent data loss.
-        if (isTruncated(body)) {
+        // Tier 3: body would need ≥3 messages → don't spam the channel.
+        // Send the banner + ONE short neutral note + the FULL (uncapped,
+        // COMPLETE) body as a `.md` file (if the adapter supports uploads).
+        // Mirrors the Telegram path exactly. No truncation — the file is
+        // the complete result.
+        if (body.length > FILE_THRESHOLD) {
             await adapter.sendText(chatId, banner);
-            for (let i = 0; i < inlineBody.length; i += NON_TG_CHUNK) {
-                await adapter.sendText(chatId, inlineBody.slice(i, i + NON_TG_CHUNK));
-            }
+            await adapter.sendText(chatId, FULL_RESULT_NOTE);
             if (adapter.sendDocument) {
                 try {
                     await adapter.sendDocument(chatId, Buffer.from(body, "utf-8"), `${info.name}.md`);
@@ -457,16 +419,16 @@ async function deliverViaRegistry(platform, info, result) {
             }
             return;
         }
-        // Not truncated (body ≤ BODY_CAP) → unchanged passthrough.
-        // inlineBody === body here, no marker, no file.
-        if (inlineBody.length + banner.length + 2 <= NON_TG_CHUNK) {
-            await adapter.sendText(chatId, `${banner}\n\n${inlineBody}`);
+        // Tier 1: body + banner fit in one message → join.
+        if (body.length + banner.length + 2 <= NON_TG_CHUNK) {
+            await adapter.sendText(chatId, `${banner}\n\n${body}`);
             return;
         }
-        // Defensive banner-then-chunk fallback (e.g. unusually long banner).
+        // Tier 1/2: banner, then body chunked across at most 2 messages.
+        // No marker, no file.
         await adapter.sendText(chatId, banner);
-        for (let i = 0; i < inlineBody.length; i += NON_TG_CHUNK) {
-            await adapter.sendText(chatId, inlineBody.slice(i, i + NON_TG_CHUNK));
+        for (let i = 0; i < body.length; i += NON_TG_CHUNK) {
+            await adapter.sendText(chatId, body.slice(i, i + NON_TG_CHUNK));
         }
     }
     catch (err) {

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.0",
-  "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",