alvin-bot 5.1.8 → 5.2.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.2.0] — 2026-05-17
+
+### Stop now actually means stop — instantly
+
+You could always type `/cancel`, but it rarely felt like anything
+happened: the bot kept "thinking" for a while and the answer often
+still arrived. That's fixed. When you stop a task, the bot now bails
+out immediately instead of quietly trying its backup brains one after
+another in the background. Press stop — it stops.
+
+### A one-tap ⛔ Stop button on every running task
+
+No more remembering or typing a command mid-thought. While Alvin is
+working you'll see a ⛔ Stop button right there on the status message.
+One tap, the task ends, the button flips to "⛔ Gestoppt". Mistyped
+your request or changed your mind? It's one thumb away — and it works
+the same in Telegram, Slack, Discord and WhatsApp.
+
+### New `/stopall` — pull the plug on everything
+
+`/cancel` (and the button) stop the task you're watching but let
+already-running background helpers finish and report back later. When
+you want a hard reset — *"forget all of it"* — use the new `/stopall`:
+it stops the current task, terminates the background sub-agents it
+spawned, and clears anything queued behind it. Nothing comes back to
+surprise you afterwards.
+
+Under the hood this was a careful, well-tested hardening of the whole
+stop path — verified end-to-end on a clean second machine before
+shipping. No setup or config needed; it just works.
+
 ## [5.1.8] — 2026-05-17
 
 ### Interrupted jobs auto-resume after a controlled restart

package/dist/handlers/commands.js

@@ -2,7 +2,7 @@ import { InlineKeyboard, InputFile } from "grammy";
 import fs from "fs";
 import path, { resolve } from "path";
 import os from "os";
-import { getSession, resetSession, markSessionDirty, getTelegramWorkspace, setTelegramWorkspace } from "../services/session.js";
+import { getSession, buildSessionKey, resetSession, markSessionDirty, getTelegramWorkspace, setTelegramWorkspace } from "../services/session.js";
 import { listWorkspaces, getWorkspace } from "../services/workspaces.js";
 import { getRegistry } from "../engine.js";
 import { reloadSoul } from "../services/personality.js";
@@ -32,6 +32,8 @@ import { getReleaseHighlights } from "../services/release-highlights.js";
 import { runCleanup, getCleanupPolicy } from "../services/disk-cleanup.js";
 import { getHealthStatus, isFailedOver } from "../services/heartbeat.js";
 import { t, LOCALE_NAMES, LOCALE_FLAGS } from "../i18n.js";
+import { requestStop, interruptQuery } from "../services/stop-controller.js";
+import { killSessionDetachedAgents, cancelPendingForSession } from "../services/async-agent-watcher.js";
 // Kick off auto-update loop on module load if the persistent flag is set.
 // Doing this as a module side-effect avoids touching the bot entry point.
 if (getAutoUpdate()) {
@@ -1896,18 +1898,66 @@ export function registerCommands(bot) {
         }
         await ctx.answerCallbackQuery();
     });
+    /** Build StopDeps for a session — wires the three stop side-effects. */
+    function buildStopDeps(session) {
+        return {
+            interruptQuery: () => interruptQuery(session),
+            killDetachedAgents: () => killSessionDetachedAgents(session),
+            clearPendingForSession: (k) => cancelPendingForSession(k),
+        };
+    }
     bot.command("cancel", async (ctx) => {
         const userId = ctx.from.id;
-        const session = getSession(userId);
+        // Use buildSessionKey so the resolved session is always the SAME object
+        // that message.ts created (and that registered pending agents under this key).
+        // In per-user mode this equals String(userId); in per-channel modes it
+        // incorporates chatId — matching the key used for the ⛔ button payload.
+        const sessionKey = buildSessionKey("telegram", ctx.chat.id, userId);
+        const session = getSession(sessionKey);
         const lang = session.language;
-        if (session.isProcessing && session.abortController) {
-            session.abortController.abort();
+        if (session.isProcessing) {
+            requestStop(session, "soft", buildStopDeps(session));
             await ctx.reply(t("bot.cancel.cancelling", lang));
         }
         else {
             await ctx.reply(t("bot.cancel.noRunning", lang));
         }
     });
+    // /stopall — hard stop: interrupt query + kill detached agents + clear queue + cancel pending.
+    bot.command("stopall", async (ctx) => {
+        const userId = ctx.from.id;
+        // Same canonical-key resolution as /cancel above — must match message.ts.
+        const sessionKey = buildSessionKey("telegram", ctx.chat.id, userId);
+        const session = getSession(sessionKey);
+        const lang = session.language;
+        if (session.isProcessing) {
+            requestStop(session, "hard", buildStopDeps(session));
+            await ctx.reply(t("bot.cancel.stoppedAll", lang));
+        }
+        else {
+            await ctx.reply(t("bot.cancel.noRunning", lang));
+        }
+    });
+    // stop: inline keyboard callback — soft stop triggered from the ⛔ button
+    // sent alongside the processing indicator in the message handler.
+    // Payload format: "stop:<sessionKey>" where sessionKey = String(userId) in
+    // default per-user mode (mirrors buildSessionKey used in message.ts).
+    bot.callbackQuery(/^stop:(.+)$/, async (ctx) => {
+        const sessionKey = ctx.match[1];
+        const session = getSession(sessionKey);
+        const lang = session.language;
+        if (session.isProcessing) {
+            requestStop(session, "soft", buildStopDeps(session));
+        }
+        try {
+            await ctx.answerCallbackQuery({ text: t("bot.cancel.stoppedToast", lang) });
+        }
+        catch { /* harmless grammy race */ }
+        try {
+            await ctx.editMessageReplyMarkup({});
+        }
+        catch { /* harmless grammy race — message may already be gone */ }
+    });
     // /restart — trigger a PM2-managed restart by exiting the process.
     // The PM2 supervisor picks up the exit and respawns with --update-env.
     bot.command("restart", async (ctx) => {

package/dist/handlers/message.js

@@ -1,4 +1,4 @@
-import { InputFile } from "grammy";
+import { InputFile, InlineKeyboard } from "grammy";
 import fs from "fs";
 import { getSession, addToHistory, trackProviderUsage, buildSessionKey, getTelegramWorkspace, markSessionDirty } from "../services/session.js";
 import { resolveWorkspaceOrDefault, getWorkspace } from "../services/workspaces.js";
@@ -229,6 +229,18 @@ export async function handleMessage(ctx) {
     // for the rest of this function (it's mutated from the bypass path in
     // another handler invocation, so the type stays `boolean | undefined`).
     delete session._bypassAbortFired;
+    // v5.1 — Send a lightweight control message with an inline ⛔ Stop button.
+    // Payload "stop:<sessionKey>" matches the callbackQuery handler in commands.ts.
+    // Cleaned up (deleted) in the finally block regardless of how the turn ends.
+    // One message only — do NOT send if the chat can't receive replies.
+    let stopMsgId = null;
+    try {
+        const stopMsg = await ctx.reply("⏳", {
+            reply_markup: new InlineKeyboard().text("⛔ Stop", `stop:${sessionKey}`),
+        });
+        stopMsgId = stopMsg.message_id;
+    }
+    catch { /* harmless — typing indicator remains, button is best-effort */ }
     const streamer = new TelegramStreamer(ctx.chat.id, ctx.api, ctx.message?.message_id);
     let finalText = "";
     let timedOut = false;
@@ -444,6 +456,8 @@ export async function handleMessage(ctx) {
                 userId,
                 sessionKey,
             } : undefined,
+            // v5.1 — Store the SDK query handle so requestStop() can interrupt it.
+            onQueryHandle: (q) => { session._qHandle = q; },
         };
         // Stream response from provider (with fallback)
         let lastBroadcastLen = 0;
@@ -459,6 +473,11 @@ export async function handleMessage(ctx) {
         // This is the second half of the empty-stream-loop fix.
         let sessionResetInStream = false;
         for await (const chunk of registry.queryWithFallback(queryOpts, workspace.provider)) {
+            // v5.1 — Bail as soon as requestStop() marks the session. The registry's
+            // outer loop already guards against new provider attempts; this guard
+            // drains the current generator's remaining chunks immediately.
+            if (session._stopRequested)
+                break;
             // v4.12.1 — Update pending-sync-task state FIRST so the timer's
             // next reset picks up the new state. This ordering is load-bearing:
             // reversing it means the timer rearms with stale state. A sync
@@ -625,6 +644,14 @@ export async function handleMessage(ctx) {
                     break;
             }
         }
+        // v5.1 stop: user stopped this query — do NOT finalize partial output
+        // as a successful answer, no 👍, no history commit. The stop trigger
+        // (/cancel | /stopall | ⛔ button) already acknowledged to the user.
+        // The `finally` still runs (clears isProcessing/_qHandle/_stopRequested
+        // + typing indicator).
+        if (session._stopRequested) {
+            return;
+        }
         if (bypassAborted) {
             // v4.12.3 — Bypass path took over; don't finalize, don't react 👍.
             // Just clean up and return. The finally block still fires.
@@ -699,6 +726,17 @@ export async function handleMessage(ctx) {
         clearInterval(typingInterval);
         session.isProcessing = false;
         session.abortController = null;
+        // v5.1 — Clear stop-hardening state so the next turn starts clean.
+        session._qHandle = null;
+        session._stopRequested = null;
+        // v5.1 — Remove the ⛔ Stop control message (sent at processing start).
+        // Best-effort: if it was already deleted or the bot lacks permission, ignore.
+        if (stopMsgId !== null) {
+            try {
+                await ctx.api.deleteMessage(ctx.chat.id, stopMsgId);
+            }
+            catch { /* harmless grammy race */ }
+        }
         // Check for queued messages — they'll be prepended to the next real message
         // Queue stays in session and gets consumed on next handleMessage call
     }

package/dist/i18n.js

@@ -344,6 +344,18 @@ const strings = {
         es: "No hay ninguna solicitud en curso.",
         fr: "Aucune requête en cours.",
     },
+    "bot.cancel.stoppedAll": {
+        en: "⛔ Stopped everything — running task, sub-agents and queue cancelled.",
+        de: "⛔ Alles gestoppt — laufende Aufgabe, Sub-Agents und Warteschlange abgebrochen.",
+        es: "⛔ Todo detenido — tarea en curso, sub-agentes y cola cancelados.",
+        fr: "⛔ Tout arrêté — tâche en cours, sous-agents et file annulés.",
+    },
+    "bot.cancel.stoppedToast": {
+        en: "⛔ Stopped",
+        de: "⛔ Gestoppt",
+        es: "⛔ Detenido",
+        fr: "⛔ Arrêté",
+    },
     // /model
     "bot.model.chooseHeader": {
         en: "🤖 *Choose model:*",

package/dist/providers/claude-sdk-provider.js

@@ -206,10 +206,24 @@ export class ClaudeSDKProvider {
                     ...(fallbackModel ? { fallbackModel } : {}),
                 },
             });
+            // v5.1 — Expose the SDK query handle to the caller so requestStop()
+            // can interrupt it via q.interrupt() + transport.process.kill().
+            try {
+                options.onQueryHandle?.(q);
+            }
+            catch { /* non-fatal */ }
             let accumulatedText = "";
             let capturedSessionId = options.sessionId || "";
             let localToolUseCount = 0;
             for await (const message of q) {
+                // v5.1 — Bail immediately if the caller set abortSignal while iterating.
+                if (options.abortSignal?.aborted) {
+                    try {
+                        q.return?.();
+                    }
+                    catch { /* ignore */ }
+                    break;
+                }
                 // System init — capture session ID
                 if (message.type === "system" && "subtype" in message && message.subtype === "init") {
                     const sysMsg = message;

package/dist/providers/registry.js

@@ -123,6 +123,12 @@ export class ProviderRegistry {
         }
         const errors = [];
         for (const key of chain) {
+            // v5.1 PRIMARY FIX — bail before attempting any provider if the caller
+            // has already aborted. Without this guard, the outer fallback loop kept
+            // trying successive providers (e.g. Ollama) even after abort(), leaving
+            // the typing indicator on and wasting resources.
+            if (options.abortSignal?.aborted)
+                break;
             const provider = this.providers.get(key);
             if (!provider)
                 continue;
@@ -234,6 +240,12 @@ export class ProviderRegistry {
             // If we got here without done or error, something's off
             return;
         }
+        // v5.1 stop: clean user cancellation — the outer loop broke on an
+        // aborted signal with nothing attempted. Don't surface a misleading
+        // "no provider" error; end the generator quietly (the consumer's
+        // _stopRequested handling owns the user-facing acknowledgement).
+        if (options.abortSignal?.aborted)
+            return;
         // All providers failed — show specific errors
         const errorDetail = errors.map(e => `  ${e.key}: ${e.error}`).join("\n");
         yield {

package/dist/services/alvin-dispatch.js

@@ -99,6 +99,9 @@ export function dispatchDetachedAgent(input) {
     // 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.
+    // child.pid is captured here (before unref) so killSessionDetachedAgents
+    // can send SIGTERM to the process. child.pid may be undefined if the OS
+    // failed to assign a PID (extremely rare); registerPendingAgent tolerates it.
     registerPendingAgent({
         agentId,
         outputFile,
@@ -109,6 +112,7 @@ export function dispatchDetachedAgent(input) {
         toolUseId: null,
         sessionKey: input.sessionKey,
         platform: input.platform,
+        pid: child.pid,
     });
     // Increment the session's pendingBackgroundCount so the main handler
     // knows a background task is in flight (same signal path as SDK's

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

@@ -131,6 +131,7 @@ export function registerPendingAgent(input) {
         toolUseId: input.toolUseId,
         sessionKey: input.sessionKey,
         platform: input.platform,
+        pid: input.pid,
     };
     enforcePendingCap();
     pending.set(input.agentId, entry);
@@ -281,6 +282,66 @@ async function deliverAsFailure(entry, status, error) {
     decrementPendingCount(entry.sessionKey);
 }
 // ── Test helpers ──────────────────────────────────────────────────
+/**
+ * v5.1 — Kill detached sub-agent processes scoped to a session.
+ *
+ * Reads the canonical session key from `session.sessionKey` (stamped by
+ * getSession() / loadPersistedSessions() — always a real string, never null
+ * after the v5.1.x fix). Iterates watcher entries whose `sessionKey` matches
+ * and calls `killFn(entry.pid)` for entries that have a pid.
+ *
+ * The function accepts an injectable `killFn` for testability. The default
+ * implementation sends SIGTERM; callers in tests pass a spy.
+ *
+ * Never throws — all per-entry errors are swallowed.
+ */
+export function killSessionDetachedAgents(session, killFn = (p) => {
+    try {
+        process.kill(p, "SIGTERM");
+    }
+    catch { /* already gone */ }
+}) {
+    // Use session.sessionKey — the real canonical key stamped by getSession().
+    // Before v5.1.x this field did not exist on UserSession, causing a silent
+    // no-op; the fix in session.ts guarantees it is always a non-empty string.
+    const key = session.sessionKey ?? null;
+    if (key === null)
+        return;
+    for (const entry of pending.values()) {
+        if (entry.sessionKey !== key)
+            continue;
+        if (typeof entry.pid === "number") {
+            try {
+                killFn(entry.pid);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+}
+/**
+ * v5.1 — Mark/remove all pending watcher entries for a session so the
+ * watcher does NOT deliver them after a hard stop.
+ *
+ * Mirrors the pattern used in pollOnce(): remove from the in-memory map
+ * and persist immediately. This is a remove-not-flag approach because
+ * there is no `cancelled` flag on PendingAsyncAgent and adding one would
+ * require touching all poll-cycle delivery paths.
+ *
+ * Scoped strictly to entries whose `sessionKey` matches — never global,
+ * never name-based. Never throws.
+ */
+export function cancelPendingForSession(sessionKey) {
+    let changed = false;
+    for (const [id, entry] of pending.entries()) {
+        if (entry.sessionKey === sessionKey) {
+            pending.delete(id);
+            changed = true;
+        }
+    }
+    if (changed) {
+        saveToDisk();
+    }
+}
 /** Test-only: drop in-memory state. Doesn't touch disk. */
 export function __resetForTest() {
     pending.clear();

package/dist/services/session-persistence.js

@@ -171,11 +171,17 @@ export function loadPersistedSessions() {
         // Build a UserSession from the persisted shape, filling defaults for any
         // fields added in newer schema versions.
         const restored = {
+            // v5.1.x — Canonical registry key stamped so stop-controller and watcher
+            // helpers can read session.sessionKey regardless of how the session was
+            // created (direct access or rehydrated from disk).
+            sessionKey: key,
             sessionId: persisted.sessionId ?? null,
             workingDir: persisted.workingDir ?? process.cwd(),
             workspaceName: persisted.workspaceName ?? null,
             isProcessing: false,
             abortController: null,
+            _stopRequested: null,
+            _qHandle: null,
             lastActivity: persisted.lastActivity ?? Date.now(),
             startedAt: persisted.startedAt ?? Date.now(),
             totalCost: persisted.totalCost ?? 0,

package/dist/services/session.js

@@ -74,11 +74,14 @@ export function getSession(key) {
     let session = sessions.get(k);
     if (!session) {
         session = {
+            sessionKey: k,
             sessionId: null,
             workingDir: config.defaultWorkingDir,
             workspaceName: null,
             isProcessing: false,
             abortController: null,
+            _stopRequested: null,
+            _qHandle: null,
             lastActivity: Date.now(),
             startedAt: Date.now(),
             totalCost: 0,
@@ -106,6 +109,11 @@ export function getSession(key) {
         // Touch lastActivity on every access so the cleanup interval
         // never kills a session that's still being interacted with.
         session.lastActivity = Date.now();
+        // Idempotent: stamp sessionKey on existing sessions that predate this field
+        // (e.g. sessions loaded from persistence before the field existed).
+        if (!session.sessionKey) {
+            session.sessionKey = k;
+        }
     }
     return session;
 }

package/dist/services/stop-controller.js

@@ -0,0 +1,52 @@
+/** Teeth: interrupt the running SDK query. SDK hides the pid, so we use
+ *  its own interrupt() control-message + transport process kill fallback.
+ *  Both best-effort; never throws. */
+export function interruptQuery(session) {
+    try {
+        session._qHandle?.interrupt?.();
+    }
+    catch { /* already finished */ }
+    try {
+        session._qHandle?.transport?.process?.kill?.();
+    }
+    catch { /* n/a */ }
+}
+/**
+ * Single shared stop primitive. Synchronous, idempotent, NEVER throws into
+ * the caller. soft = abort + interrupt running query + reset JS state.
+ * hard = soft + kill detached sub-agents + clear queue + cancel pending.
+ *
+ * Post Task-1: the SDK hides the subprocess PID, so the teeth are
+ * q.interrupt() (via deps.interruptQuery), NOT a process-group SIGKILL.
+ */
+export function requestStop(session, tier, deps) {
+    // 1. Signal abort (best-effort; already fast per Task-1 evidence).
+    try {
+        session.abortController?.abort();
+    }
+    catch { /* idempotent */ }
+    // 2. Teeth — interrupt the running SDK query.
+    try {
+        deps.interruptQuery();
+    }
+    catch { /* already finished / never throw */ }
+    // 3. Mark stop so consumer loop + provider + registry fallback bail.
+    session._stopRequested = tier;
+    // 4. Hard tier extras.
+    if (tier === "hard") {
+        try {
+            deps.killDetachedAgents();
+        }
+        catch { /* best-effort */ }
+        if (Array.isArray(session.messageQueue))
+            session.messageQueue.length = 0;
+        try {
+            deps.clearPendingForSession(session.sessionKey);
+        }
+        catch { /* best-effort */ }
+    }
+    // 5. Deterministic JS-state teardown.
+    session.isProcessing = false;
+    session.abortController = null;
+    session._qHandle = null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "5.1.8",
+  "version": "5.2.0",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",