alvin-bot 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [5.3.0] — 2026-05-18
+
+### Talk to Alvin while it's working — no more interrupting yourself
+
+Until now, a message you sent while Alvin was busy had only two
+outcomes: it waited in line until the current task finished, or it
+threw the task away and started over. Now there's a third, much
+better one. Drop a quick *"btw, also check the other folder"* or
+*"actually, use the live data not the test data"* mid-task and Alvin
+takes it in **while keeping everything it has already done** — exactly
+like leaning over to a colleague who's already working and adding one
+more thing. No restart, no lost progress.
+
+### A quiet 📨 so you know it landed
+
+When your mid-task note is picked up, Alvin reacts with a 📨 on your
+message and, the first time per task, adds one short line so you know
+it was taken on board without derailing what it's doing. After that
+it's just the reaction — no chatter, no spam while it works.
+
+### Stop still always wins
+
+Steering never overrides stopping. The ⛔ Stop button, `/cancel` and
+`/stopall` behave exactly as before and always take precedence — a
+mid-task note can never bring back a task you've stopped. If you'd
+rather keep the old "queue it until done" behaviour, you can switch
+steering off with a single setting; it's on by default for everyone.
+
+Live steering works with the Claude engine; with other AI providers
+your message safely falls back to the previous queue behaviour, so
+nothing breaks. As always, this shipped only after a full end-to-end
+verification and a stress test on a clean separate machine.
+
 ## [5.2.0] — 2026-05-17
 
 ### Stop now actually means stop — instantly

package/dist/config.js

@@ -83,3 +83,11 @@ export const config = {
     // Exec Security
     execSecurity: (process.env.EXEC_SECURITY || "full"),
 };
+/**
+ * Feature flag: btw live-steering. Default ON — only "false" or "0" disables.
+ * Re-reads process.env each call so tests can override without module reloads.
+ */
+export function isSteeringEnabled() {
+    const v = process.env.STEERING_ENABLED;
+    return v !== "false" && v !== "0";
+}

package/dist/handlers/message.js

@@ -19,6 +19,8 @@ import { isHarmlessTelegramError } from "../util/telegram-error-filter.js";
 import { handleToolResultChunk } from "./async-agent-chunk-handler.js";
 import { createStuckTimer } from "./stuck-timer.js";
 import { shouldBypassQueue, shouldBypassSdkResume, waitUntilProcessingFalse, } from "./background-bypass.js";
+import { SteerChannel } from "../services/steer-channel.js";
+import { isSteeringEnabled } from "../config.js";
 /**
  * Stuck-only timeout — NO absolute cap.
  *
@@ -119,6 +121,29 @@ const TOOL_ICONS = {
     WebFetch: "📡",
     Task: "🤖",
 };
+// ── v5.2 live steering — pure routing helper ─────────────────────────────────
+/**
+ * Decide how a mid-task message (arriving while `session.isProcessing`) should
+ * be handled. Evaluated in the `if (session.isProcessing)` guard before any
+ * side-effects, so the caller can branch cleanly.
+ *
+ * Decision priority:
+ *   1. "bypass"  — background-agent bypass path (pre-existing Cycle-1 logic)
+ *   2. "steer"   — push into live SteerChannel (claude-sdk + steering on + channel open)
+ *   3. "queue"   — normal queue behavior (all other cases)
+ *
+ * Defensive: if `isProcessing` is false the helper is being called incorrectly;
+ * it returns "queue" so the caller falls through to existing behavior.
+ */
+export function decideMidTaskRouting(args) {
+    if (!args.isProcessing)
+        return "queue";
+    if (args.shouldBypass)
+        return "bypass";
+    if (args.providerIsClaudeSdk && args.steeringEnabled && args.hasSteerChannel)
+        return "steer";
+    return "queue";
+}
 /** React to a message with an emoji. Silently fails if reactions aren't supported. */
 async function react(ctx, emoji) {
     try {
@@ -172,11 +197,22 @@ export async function handleMessage(ctx) {
         // the new message gets processed immediately. The background task
         // itself continues in its detached subprocess; the async-agent watcher
         // delivers the result via subagent-delivery.ts when ready.
-        if (shouldBypassQueue({
+        //
+        // v5.2 — decideMidTaskRouting unifies bypass / steer / queue in one place.
+        const _midTaskBypass = shouldBypassQueue({
             isProcessing: session.isProcessing,
             pendingBackgroundCount: session.pendingBackgroundCount,
             abortController: session.abortController,
-        })) {
+        });
+        const _midTaskProviderIsSdk = getRegistry().getActive().config.type === "claude-sdk";
+        const _midTaskRoute = decideMidTaskRouting({
+            isProcessing: true,
+            providerIsClaudeSdk: _midTaskProviderIsSdk,
+            steeringEnabled: isSteeringEnabled(),
+            hasSteerChannel: !!session._steerChannel,
+            shouldBypass: _midTaskBypass,
+        });
+        if (_midTaskRoute === "bypass") {
             console.log(`[v4.12.3 bypass] aborting blocked query for ${sessionKey} — ` +
                 `${session.pendingBackgroundCount} background agent(s) pending`);
             // Mark the abort as a bypass so the old handler's error branch
@@ -194,6 +230,23 @@ export async function handleMessage(ctx) {
             await waitUntilProcessingFalse(session, 5000);
             // Fall through to start a fresh query below.
         }
+        else if (_midTaskRoute === "steer") {
+            // v5.2 — btw live steering: push mid-task message into the open
+            // SteerChannel so the running claude-sdk query picks it up as a
+            // streaming-input user message. No abort, no queue.
+            session._steerChannel.push(text);
+            await react(ctx, "📨");
+            if (!session._steerAckSentThisTurn) {
+                try {
+                    await ctx.reply(t("bot.steer.ack", session.language));
+                }
+                catch {
+                    /* harmless grammy race */
+                }
+                session._steerAckSentThisTurn = true;
+            }
+            return;
+        }
         else {
             // Normal queue behavior. v4.12.3 — emit a text reply in addition
             // to the reaction so the user actually sees that their message
@@ -459,6 +512,19 @@ export async function handleMessage(ctx) {
             // v5.1 — Store the SDK query handle so requestStop() can interrupt it.
             onQueryHandle: (q) => { session._qHandle = q; },
         };
+        // v5.2 — btw live steering: seed SteerChannel at turn start so mid-task
+        // user messages can be pushed in while this query is running. Only for
+        // claude-sdk (the only provider that supports streaming-input prompts).
+        // The initial bridged prompt is pushed first so the channel sequence is:
+        //   [bridgedPrompt, <any mid-task messages>, <close on finally>]
+        // queryOpts.steerChannel is set so the provider uses the channel as the
+        // prompt source. queryOpts.prompt is kept as-is for non-SDK fallback paths
+        // (providers that don't support steerChannel ignore it and use prompt).
+        if (isSDK && isSteeringEnabled()) {
+            session._steerChannel = new SteerChannel();
+            session._steerChannel.push(bridgedPrompt);
+            queryOpts.steerChannel = session._steerChannel;
+        }
         // Stream response from provider (with fallback)
         let lastBroadcastLen = 0;
         // Captured during tool_use chunks; consumed by tool_result chunks so
@@ -729,6 +795,13 @@ export async function handleMessage(ctx) {
         // v5.1 — Clear stop-hardening state so the next turn starts clean.
         session._qHandle = null;
         session._stopRequested = null;
+        // v5.2 — Close and clear the SteerChannel; reset per-turn ack flag.
+        try {
+            session._steerChannel?.close();
+        }
+        catch { /* ignore */ }
+        session._steerChannel = null;
+        session._steerAckSentThisTurn = false;
         // 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) {

package/dist/i18n.js

@@ -331,6 +331,13 @@ const strings = {
         es: "(externo, activo)",
         fr: "(externe, en cours)",
     },
+    // live steering ack (Task 4 — btw feature)
+    "bot.steer.ack": {
+        en: "📨 Noted — Alvin will factor that in without restarting.",
+        de: "📨 Mitgenommen — Alvin berücksichtigt das, ohne abzubrechen.",
+        es: "📨 Anotado — Alvin lo tendrá en cuenta sin reiniciar.",
+        fr: "📨 Noté — Alvin en tiendra compte sans redémarrer.",
+    },
     // /cancel
     "bot.cancel.cancelling": {
         en: "Cancelling request…",

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

@@ -174,7 +174,9 @@ export class ClaudeSDKProvider {
             const primaryIsHaiku = (modelOverride ?? "").toLowerCase().includes("haiku");
             const fallbackModel = primaryIsHaiku ? undefined : "haiku";
             const q = query({
-                prompt,
+                prompt: options.steerChannel
+                    ? options.steerChannel
+                    : prompt,
                 options: {
                     cwd: options.workingDir || process.cwd(),
                     abortController: internalAbortController,

package/dist/services/session-persistence.js

@@ -182,6 +182,8 @@ export function loadPersistedSessions() {
             abortController: null,
             _stopRequested: null,
             _qHandle: null,
+            _steerChannel: null,
+            _steerAckSentThisTurn: false,
             lastActivity: persisted.lastActivity ?? Date.now(),
             startedAt: persisted.startedAt ?? Date.now(),
             totalCost: persisted.totalCost ?? 0,

package/dist/services/session.js

@@ -82,6 +82,8 @@ export function getSession(key) {
             abortController: null,
             _stopRequested: null,
             _qHandle: null,
+            _steerChannel: null,
+            _steerAckSentThisTurn: false,
             lastActivity: Date.now(),
             startedAt: Date.now(),
             totalCost: 0,
@@ -114,6 +116,10 @@ export function getSession(key) {
         if (!session.sessionKey) {
             session.sessionKey = k;
         }
+        if (session._steerChannel === undefined)
+            session._steerChannel = null;
+        if (session._steerAckSentThisTurn === undefined)
+            session._steerAckSentThisTurn = false;
     }
     return session;
 }

package/dist/services/steer-channel.js

@@ -0,0 +1,41 @@
+const DEFAULT_CAP = 20;
+export class SteerChannel {
+    cap;
+    buf = [];
+    closed = false;
+    resolveNext = null;
+    constructor(cap = DEFAULT_CAP) {
+        this.cap = cap;
+    }
+    push(text) {
+        if (this.closed)
+            return;
+        if (this.buf.length >= this.cap) {
+            console.warn(`[steer-channel] cap ${this.cap} reached — dropping steer message`);
+            return;
+        }
+        this.buf.push({ type: "user", message: { role: "user", content: text }, parent_tool_use_id: null });
+        const r = this.resolveNext;
+        this.resolveNext = null;
+        r?.();
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const r = this.resolveNext;
+        this.resolveNext = null;
+        r?.();
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            if (this.buf.length > 0) {
+                yield this.buf.shift();
+                continue;
+            }
+            if (this.closed)
+                return;
+            await new Promise((res) => { this.resolveNext = res; });
+        }
+    }
+}

package/package.json

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