alvin-bot 4.18.2 → 4.18.4

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.18.4] — 2026-04-23
+
+### 🐛 Critical fix: detect Anthropic quota-exhausted responses
+
+**Problem:** When a Claude Max subscription runs out of weekly limit or extra-usage credits, Anthropic's gateway responds to every query with a short text chunk like *"You're out of extra usage · resets 9pm (Europe/Berlin)"* — delivered as `output_tokens=0`. The SDK surfaces it as a normal assistant text message. The bot has no way to distinguish it from a real Claude response, so one of two things happens:
+
+1. The text passes through unchanged and the user sees the raw quota message as if it were Claude's reply.
+2. The text is filtered downstream (some legacy paths) and the user sees `"(Keine Antwort)"` with zero explanation.
+
+Both outcomes hide the real cause (credits) and every retry attempt wastes more credits on nothing.
+
+**Symptoms observed on 2026-04-23:**
+- User activates `/extra-usage`, sends query → `(Keine Antwort)` or raw limit text.
+- Assumes bot / workspace / token is broken, spends hours debugging.
+- Actual cause: extra-usage quota silently exhausted mid-debug-session.
+
+**Fix** (`src/providers/claude-sdk-provider.ts`):
+
+- New `isQuotaLimitOutput(text)` detects the Anthropic-gateway quota signatures (multiple English/German variants: "out of extra usage", "weekly usage limit", "rate limit exceeded", "quota exceeded", etc.).
+- In the SDK stream loop: when the first text chunk matches this pattern, rewrite it as a clear actionable hint (*"⚠️ …Top up the plan or wait for the reset…"*) AND invalidate the availability cache so the next heartbeat re-probes — but do NOT yield an `error` chunk (that would trigger fallback-cascade to Ollama and waste more credits on retries).
+- In `isAvailable()`: the heartbeat probe now treats quota-exhausted output as "unavailable" in the same way it treats auth errors. Provider is marked unhealthy, bot stops trying until the next probe succeeds.
+
+**Net effect:** bot no longer silently wastes credits after a quota limit is hit. Users see a plain, actionable message pointing at the right fix.
+
+## [4.18.3] — 2026-04-23
+
+### 🐛 Hotfix: 4.18.2 triggered unwanted failover to Ollama
+
+**Bug in 4.18.2:** The empty-stream detector yielded an `error` chunk, which the registry's `queryWithFallback()` interprets as "primary provider failed" and immediately switches to the fallback (Ollama/Gemma 4). User saw `⚡ Claude (Agent SDK) unavailable — switching to Gemma 4 E4B` after every token rotation — the opposite of the intended behavior.
+
+**Fix:** yield a `text` chunk instead of `error`. Same user-visible message, same cache-invalidation, but no failover cascade. The next CLI subprocess spawns with the fresh Keychain token automatically, and claude-sdk stays selected.
+
 ## [4.18.2] — 2026-04-23
 
 ### 🐛 Fix: silent empty-stream after OAuth-token rotation

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

@@ -25,6 +25,34 @@ export function isAuthErrorOutput(text) {
         return false;
     return /^\s*not logged in\b/i.test(text);
 }
+/**
+ * Detects Anthropic's rate-limit / quota-exhausted gateway responses.
+ * These are NOT model outputs — they come back as a single text chunk with
+ * output_tokens = 0 before the model even sees the prompt. Without this
+ * detection, the bot would forward the gateway message as if it were the
+ * assistant's reply ("(Keine Antwort)" or the raw quota text), masking the
+ * real cause and wasting more calls on retries.
+ *
+ * Covers the observed variants:
+ *   - "You're out of extra usage · resets 9pm (Europe/Berlin)"
+ *   - "You've reached your weekly usage limit. …"
+ *   - "Rate limit exceeded"
+ *   - Claude Max / Pro quota messages in both EN/DE
+ */
+export function isQuotaLimitOutput(text) {
+    if (!text)
+        return false;
+    const t = text.trim();
+    if (t.length === 0)
+        return false;
+    return (/you['’]re out of extra usage/i.test(t) ||
+        /reached (your |the )?(weekly |monthly |daily )?(usage|rate) limit/i.test(t) ||
+        /rate[- ]?limit(ed)? (exceeded|reached)/i.test(t) ||
+        /quota exceeded/i.test(t) ||
+        /usage limit reached/i.test(t) ||
+        /limit (reached|hit) for (this|your) (week|month|day)/i.test(t) ||
+        /resets? \d{1,2}(am|pm|:)/i.test(t) && /usage|limit/i.test(t));
+}
 const BOT_PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 // Load CLAUDE.md once at startup
 let botClaudeMd = "";
@@ -198,6 +226,24 @@ export class ClaudeSDKProvider {
                                     };
                                     return;
                                 }
+                                // v4.18.4 — Guard against Anthropic rate-limit / quota-exhausted
+                                // gateway messages that also arrive as a single text chunk (with
+                                // output_tokens = 0). Pass them through as a friendly text chunk
+                                // (NOT an error — would trigger fallback cascade to Ollama) and
+                                // mark the provider as degraded so the next heartbeat re-checks.
+                                if (!accumulatedText && isQuotaLimitOutput(block.text)) {
+                                    const hint = "⚠️ " + block.text.trim() +
+                                        "\n\nTop up the plan or wait for the reset. No message was sent to Claude.";
+                                    this.invalidateAvailabilityCache();
+                                    yield {
+                                        type: "text",
+                                        text: hint,
+                                        delta: hint,
+                                        sessionId: capturedSessionId,
+                                    };
+                                    accumulatedText = hint;
+                                    continue;
+                                }
                                 accumulatedText += block.text;
                                 yield {
                                     type: "text",
@@ -309,33 +355,40 @@ export class ClaudeSDKProvider {
                         ? (usage.input_tokens || 0) + (usage.cache_creation_input_tokens || 0) + (usage.cache_read_input_tokens || 0)
                         : 0;
                     const outputTok = usage?.output_tokens || 0;
-                    // v4.18.2 — Silent-empty-stream detection.
+                    // v4.18.3 — Silent-empty-stream detection (replaces 4.18.2 approach).
                     //
                     // If the stream terminated cleanly but produced ZERO text chunks,
-                    // something went wrong that the SDK didn't surface as an error:
-                    // most commonly a stale OAuth token after /extra-usage or /login
-                    // rotated the Keychain entry while our in-memory SDK client was
-                    // still holding the old one. The CLI subprocess silently gets a
-                    // 401, emits no text, and we complete the stream with
-                    // accumulatedText === "". The user sees "(Keine Antwort)".
+                    // something went wrong that the SDK didn't surface as an error.
+                    // Most common cause: the OAuth token in the Keychain was rotated
+                    // (e.g. right after /extra-usage or /login) while our in-memory
+                    // SDK client still held the old one — the CLI subprocess silently
+                    // gets a 401, emits no text, and we complete with
+                    // accumulatedText === "".
                     //
-                    // We flip this from silent failure to explicit error. Clearing
-                    // the availability cache forces the next heartbeat probe to
-                    // re-check `claude auth status` with a fresh subprocess (which
-                    // reads the current Keychain entry).
+                    // CRITICAL: we must NOT yield an "error" chunk here — the registry's
+                    // queryWithFallback() treats that as "primary failed" and kicks off
+                    // a full failover to the next provider (Ollama). That's exactly
+                    // wrong: the next CLI subprocess would have picked up the fresh
+                    // token by itself. Instead we:
+                    //   1. Invalidate the availability cache so the next heartbeat
+                    //      re-probes `claude auth status` with a fresh subprocess.
+                    //   2. Return a friendly "text" chunk explaining what happened,
+                    //      so the user sees a clear message (not "(Keine Antwort)")
+                    //      and knows to resend — without tripping the failover.
                     if (accumulatedText === "" && outputTok === 0) {
                         this.invalidateAvailabilityCache();
+                        const hint = "⚠️ Claude antwortete mit leerem Stream (meist nach /extra-usage, /login oder Token-Refresh). " +
+                            "Der SDK-Token-Cache wurde geleert — bitte schick die Nachricht einfach nochmal.";
                         yield {
-                            type: "error",
-                            error: "Claude returned an empty response. " +
-                                "This can happen right after /extra-usage, /login, or a token refresh — " +
-                                "the SDK held a stale auth token. I've invalidated the cache; please resend your message.",
+                            type: "text",
+                            text: hint,
+                            delta: hint,
+                            sessionId: resultMsg.session_id || capturedSessionId,
                         };
-                        return;
                     }
                     yield {
                         type: "done",
-                        text: accumulatedText,
+                        text: accumulatedText || "",
                         sessionId: resultMsg.session_id || capturedSessionId,
                         costUsd: "total_cost_usd" in resultMsg ? resultMsg.total_cost_usd : 0,
                         inputTokens: inputTok,
@@ -404,7 +457,9 @@ export class ClaudeSDKProvider {
                 // sniff-stdout approach for backward compat.
                 try {
                     const { stdout: probeOut } = await execFileAsync(claudePath, ["-p", "ping", "--output-format", "text"], { timeout: 15000 });
-                    return cache(!isAuthErrorOutput(probeOut));
+                    // v4.18.4 — treat quota-exhausted as "unavailable" so heartbeat
+                    // surfaces it and stops wasting extra-usage credits on retries.
+                    return cache(!isAuthErrorOutput(probeOut) && !isQuotaLimitOutput(probeOut));
                 }
                 catch {
                     // Both checks failed — treat as unavailable

package/package.json

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