alvin-bot 4.12.3 → 4.12.4

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.12.4] — 2026-04-16
+
+### 🐛 Patch: recover partial output from interrupted background sub-agents
+
+**The bug Ali saw:** Two Telegram messages appeared hours apart: `⏱️ Background agent a5bf8c74 timeout · 720m 3s · 0 in / 0 out` and `... ab9372d4 timeout · 720m 1s · 0 in / 0 out`, both with `(empty output)`. Three more agents were still pending, all interrupted mid-execution with hundreds of KB of real work sitting on disk.
+
+**Root cause:** v4.12.3's bypass-abort calls `session.abortController.abort()`, which propagates through `claude-sdk-provider.ts`'s `internalAbortController` into the SDK's CLI subprocess, which in turn propagates into any in-flight `Agent(run_in_background: true)` tool executions. Evidence from the disk:
+
+- `agent-a03ce829...jsonl`: 116 lines, last event = literally `"[Request interrupted by user for tool use]"` mid-Bash-tool-use
+- `agent-af61fa6e...jsonl`: 81 lines, last assistant text = `"Ich habe jetzt genug Daten für den vollständigen Audit. Hier ist der Report:"` — interrupted while streaming the final report
+- `agent-ac47c4a2...jsonl`: 131 lines, last assistant text = `"## Perseus Audit — Ergebnis\n### Kritische Bugs"` — interrupted a few words into the payoff
+
+None of them reached `stop_reason: "end_turn"`. The pre-v4.12.4 `parseOutputFileStatus` only recognized `end_turn` as a completion signal, so these agents sat in the pending list for 12h until `giveUpAt` elapsed, then got delivered as `(empty output)` while their real work was still on disk.
+
+**The fix:** `parseOutputFileStatus` now has a staleness fallback. When no `end_turn` is present BUT the outputFile hasn't been written to in `stalenessMs` (default 5 min, configurable via `ALVIN_SUBAGENT_STALENESS_MS`) AND there is usable assistant text content in the tail, the parser:
+
+1. Aggregates ALL text blocks across all assistant turns in the tail (not just the last one — bias toward delivering more context)
+2. Prepends a clear banner: `⚠️ _Sub-Agent wurde unterbrochen — hier ist der partielle Output:_`
+3. Returns `state: "completed"` so the watcher delivers it instead of continuing to poll
+
+Result: on the next `pollOnce()` after v4.12.4 ships, the three stuck agents get delivered with their real partial output (combined ~1.2MB of text across the three). Future interrupts recover within 5 minutes instead of hanging 12 hours.
+
+### Behavioral notes
+
+- **Clean `end_turn` sub-agents are unchanged** — the staleness fallback is a *fallback only*. The existing strict path runs first and takes precedence.
+- **`stalenessMs: 0` disables the fallback entirely** — strict end_turn-only mode for callers that prefer it.
+- **Thinking blocks are still filtered out** of the partial delivery — same as with clean completion.
+- **Files with no assistant text at all** (only tool_use) stay in `running` state — nothing useful to deliver.
+- **Tokens are surfaced when available** — the last assistant event's `usage.input_tokens`/`output_tokens` flow through to the delivery banner.
+
+### Known limitations (carried over from v4.12.3, deferred to v4.13)
+
+- The bypass-abort mechanism in `message.ts` still propagates to the SDK subprocess and kills in-flight sub-agents. v4.12.4 works around this at the delivery layer (recovering partial output); a true fix requires either architectural replacement of the SDK's `Task` tool with our own detached-subprocess dispatch, or SDK support for per-task-branch abort signals. Tracked for v4.13.
+- Users may still experience the bot's "typing…" indicator when Claude is thinking in the main turn (before dispatching any background agent). Bypass only fires once `pendingBackgroundCount > 0`. For interrupt before dispatch, use `/cancel`.
+
+### Testing
+
+- **Baseline**: 436 tests (v4.12.3)
+- **New**: `test/async-agent-parser-staleness.test.ts` — 11 tests covering: clean `end_turn` still wins over staleness, fresh-interrupted file stays running, stale-interrupted file delivers partial with banner, no-text file stays running, `stalenessMs: 0` disables, aggregation across multiple turns, thinking-block filtering, token extraction, interrupt-only file with no useful content, and ordering preservation.
+- **Total**: 447 tests, all green, TSC clean.
+
+### Files changed
+
+- **Modified**: `src/services/async-agent-parser.ts` — staleness fallback in `parseOutputFileStatus`, `DEFAULT_STALENESS_MS` constant, `INTERRUPTED_BANNER` prefix.
+- **NEW tests**: `test/async-agent-parser-staleness.test.ts`.
+- **Version**: `package.json` 4.12.3 → 4.12.4.
+
+---
+
 ## [4.12.3] — 2026-04-15
 
 ### 🐛 Patch: Background sub-agent no longer blocks the main Telegram session

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

@@ -68,14 +68,45 @@ export function parseAsyncLaunchedToolResult(raw) {
     return { agentId, outputFile };
 }
 const DEFAULT_TAIL_BYTES = 64 * 1024;
+/**
+ * v4.12.4 — Default staleness window for partial-output delivery.
+ *
+ * If an outputFile has not been written to for at least this long AND
+ * there is usable assistant text content in it, treat it as "completed
+ * with partial output" rather than leaving it to time out at 12h with
+ * an empty banner. 5 minutes is a balance between:
+ *   - Fast enough to unblock interrupted agents (most useful work is
+ *     done within a few minutes)
+ *   - Slow enough to avoid false-positives on slow-but-alive agents
+ *     (typical tool_use gaps are under 30s)
+ *
+ * Override per call via opts.stalenessMs, or globally via the
+ * ALVIN_SUBAGENT_STALENESS_MS env var. `0` disables the fallback
+ * entirely (strict end_turn-only completion detection).
+ */
+const DEFAULT_STALENESS_MS = Number(process.env.ALVIN_SUBAGENT_STALENESS_MS) || 5 * 60 * 1000;
+/**
+ * Banner prepended to partial-output deliveries so the user knows the
+ * sub-agent was interrupted and this isn't a clean completion.
+ */
+const INTERRUPTED_BANNER = "⚠️ _Sub-Agent wurde unterbrochen — hier ist der partielle Output:_\n\n";
 /**
  * Read the tail of an SDK background-agent outputFile and decide what
  * state the sub-agent is in. See spec doc for the JSONL format. We only
  * read the last `maxTailBytes` of the file because long-running agents
  * (SEO audits etc.) can produce hundreds of KB of intermediate JSONL.
+ *
+ * v4.12.4 adds staleness-based partial-output delivery. When no
+ * `end_turn` marker is present, the parser checks file mtime: if the
+ * file hasn't grown in `stalenessMs` AND there is text content in the
+ * assistant turns, aggregate the text across all turns (not just the
+ * last), prepend an "interrupted" banner, and return "completed". This
+ * recovers real work from agents killed mid-execution (e.g. by the
+ * v4.12.3 bypass abort propagating through the SDK subprocess).
  */
 export async function parseOutputFileStatus(path, opts = {}) {
     const maxTailBytes = opts.maxTailBytes ?? DEFAULT_TAIL_BYTES;
+    const stalenessMs = opts.stalenessMs ?? DEFAULT_STALENESS_MS;
     let stat;
     try {
         stat = await fs.stat(path);
@@ -147,6 +178,50 @@ export async function parseOutputFileStatus(path, opts = {}) {
             };
         }
     }
-    // No completion marker found — still running.
+    // v4.12.4 — No clean end_turn. Check for staleness + partial text.
+    if (stalenessMs > 0) {
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs >= stalenessMs) {
+            // Aggregate ALL assistant text blocks across the tail, in order.
+            // We parse forward now (not backward like the end_turn scan) so
+            // the delivered text preserves the natural reading order.
+            const textFragments = [];
+            let lastUsage;
+            for (const line of usable) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (parsed.type === "assistant" &&
+                    Array.isArray(parsed.message?.content)) {
+                    for (const c of parsed.message.content) {
+                        if (c?.type === "text" && typeof c.text === "string") {
+                            textFragments.push(c.text);
+                        }
+                    }
+                    if (parsed.message?.usage) {
+                        lastUsage = {
+                            input: parsed.message.usage.input_tokens ?? 0,
+                            output: parsed.message.usage.output_tokens ?? 0,
+                        };
+                    }
+                }
+            }
+            if (textFragments.length > 0) {
+                const aggregated = textFragments.join("\n\n").trim();
+                if (aggregated.length > 0) {
+                    return {
+                        state: "completed",
+                        output: INTERRUPTED_BANNER + aggregated,
+                        tokensUsed: lastUsage,
+                    };
+                }
+            }
+        }
+    }
+    // No completion marker found and not stale (or no text) — still running.
     return { state: "running", size: stat.size };
 }

package/package.json

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

package/test/async-agent-parser-staleness.test.ts

@@ -0,0 +1,412 @@
+/**
+ * v4.12.4 — parseOutputFileStatus staleness detection.
+ *
+ * Problem this fixes: when a background sub-agent is interrupted (e.g. by
+ * v4.12.3's bypass-abort propagating through the SDK subprocess), its
+ * outputFile is left with partial JSONL — real work, real text — but
+ * without the `stop_reason: "end_turn"` marker the pre-v4.12.4 parser
+ * required for "completed" state.
+ *
+ * Real-world evidence (2026-04-16):
+ *   - Three agents (a03ce829, af61fa6e, ac47c4a2) pending in state file
+ *   - Each outputFile has 81-131 lines of REAL work (WebSearch, tool_use,
+ *     partial reports like "Here's the summary:\n\n## Critical Bugs")
+ *   - Last event is either "[Request interrupted by user for tool use]"
+ *     or a mid-streaming assistant text that never got end_turn
+ *   - Watcher polls forever, hits 12h giveUpAt, delivers "empty output"
+ *   - User sees useless "720m timeout · 0 in / 0 out · (empty output)"
+ *     messages hours later, while the actual work is sitting on disk
+ *
+ * Fix behavior:
+ *   - If no end_turn is found, check mtime/size of the file
+ *   - If file hasn't been touched for `stalenessMs` (default 5 min) AND
+ *     there's usable text content in the tail, mark as "completed"
+ *     with the partial output PREFIXED by an "⚠️ interrupted, partial
+ *     output" header so the user knows it's not a clean finish
+ *   - If file IS fresh or has no text content, stay in "running" state
+ *     (normal polling continues)
+ *
+ * This deliberately biases toward delivering SOMETHING rather than
+ * nothing. Worst case: an agent that's still alive but genuinely idle
+ * for >5 min gets its partial text delivered early. Best case: dozens
+ * of stuck interrupted agents get their real work back to the user.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+import { parseOutputFileStatus } from "../src/services/async-agent-parser.js";
+
+const TMP_BASE = resolve(os.tmpdir(), `alvin-parser-stale-${process.pid}`);
+
+beforeEach(() => {
+  fs.mkdirSync(TMP_BASE, { recursive: true });
+});
+afterEach(() => {
+  try {
+    fs.rmSync(TMP_BASE, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+});
+
+/**
+ * Write a JSONL file with a mid-execution interrupted state. No end_turn,
+ * but contains real assistant text + tool calls. Last line is the
+ * "Request interrupted" marker.
+ */
+function writeInterruptedJsonl(name: string): string {
+  const path = resolve(TMP_BASE, name);
+  const lines = [
+    JSON.stringify({
+      type: "user",
+      isSidechain: true,
+      agentId: "x",
+      message: { role: "user", content: "do a report" },
+    }),
+    JSON.stringify({
+      type: "assistant",
+      isSidechain: true,
+      agentId: "x",
+      message: {
+        role: "assistant",
+        content: [{ type: "text", text: "Starting research..." }],
+        stop_reason: "tool_use",
+      },
+    }),
+    JSON.stringify({
+      type: "assistant",
+      isSidechain: true,
+      agentId: "x",
+      message: {
+        role: "assistant",
+        content: [
+          {
+            type: "text",
+            text:
+              "Here's what I found:\n\n## Key Findings\n- Finding A\n- Finding B\n- Finding C",
+          },
+        ],
+        stop_reason: "tool_use",
+      },
+    }),
+    JSON.stringify({
+      type: "user",
+      isSidechain: true,
+      agentId: "x",
+      message: {
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            content: "[Request interrupted by user for tool use]",
+          },
+        ],
+      },
+    }),
+  ];
+  fs.writeFileSync(path, lines.join("\n") + "\n", "utf-8");
+  return path;
+}
+
+/** Set file mtime to N ms in the past. */
+function setStale(path: string, ageMs: number): void {
+  const target = Date.now() - ageMs;
+  fs.utimesSync(path, target / 1000, target / 1000);
+}
+
+describe("parseOutputFileStatus — staleness detection (v4.12.4)", () => {
+  it("still returns 'completed' when end_turn is present (staleness is a fallback only)", async () => {
+    const path = resolve(TMP_BASE, "complete.jsonl");
+    fs.writeFileSync(
+      path,
+      JSON.stringify({
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [{ type: "text", text: "clean end" }],
+          stop_reason: "end_turn",
+        },
+      }) + "\n",
+      "utf-8",
+    );
+    setStale(path, 3600_000); // 1h old
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000,
+    });
+    expect(status.state).toBe("completed");
+    if (status.state === "completed") {
+      expect(status.output).toContain("clean end");
+      // No interrupted banner for clean end_turn
+      expect(status.output).not.toMatch(/interrupt/i);
+    }
+  });
+
+  it("returns 'running' when file is fresh and no end_turn (normal polling)", async () => {
+    const path = writeInterruptedJsonl("fresh-interrupted.jsonl");
+    // File is fresh (just written)
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000,
+    });
+    expect(status.state).toBe("running");
+  });
+
+  it("returns 'completed' (partial) when file is stale AND has text content", async () => {
+    const path = writeInterruptedJsonl("stale-interrupted.jsonl");
+    setStale(path, 600_000); // 10 min old
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000, // 5 min threshold
+    });
+    expect(status.state).toBe("completed");
+    if (status.state === "completed") {
+      // Should contain the real report content
+      expect(status.output).toContain("Key Findings");
+      expect(status.output).toContain("Finding A");
+      // Should be prefixed with an interrupted banner so user knows
+      // (German "unterbrochen" / "partielle" OR English "interrupted"/"partial")
+      expect(status.output).toMatch(/interrupt|partial|unterbroch|partiell|⚠️/i);
+    }
+  });
+
+  it("returns 'running' when file is stale but has NO text content (nothing to deliver)", async () => {
+    // Only tool-use events, no text. Delivery would be useless.
+    const path = resolve(TMP_BASE, "no-text.jsonl");
+    fs.writeFileSync(
+      path,
+      [
+        JSON.stringify({
+          type: "user",
+          agentId: "x",
+          message: { role: "user", content: "go" },
+        }),
+        JSON.stringify({
+          type: "assistant",
+          agentId: "x",
+          message: {
+            content: [
+              { type: "tool_use", name: "Bash", input: { command: "ls" } },
+            ],
+            stop_reason: "tool_use",
+          },
+        }),
+      ].join("\n") + "\n",
+      "utf-8",
+    );
+    setStale(path, 600_000);
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000,
+    });
+    expect(status.state).toBe("running");
+  });
+
+  it("default stalenessMs is applied when not provided (no crashes on legacy callers)", async () => {
+    const path = writeInterruptedJsonl("default-cfg.jsonl");
+    setStale(path, 24 * 3600_000); // 24h old — very stale
+    const status = await parseOutputFileStatus(path);
+    // Whatever the default is, 24h should definitely exceed it
+    expect(status.state).toBe("completed");
+  });
+
+  it("stalenessMs: 0 disables the staleness fallback entirely", async () => {
+    const path = writeInterruptedJsonl("disabled.jsonl");
+    setStale(path, 24 * 3600_000);
+    const status = await parseOutputFileStatus(path, { stalenessMs: 0 });
+    // With staleness disabled, we're back to strict end_turn requirement
+    expect(status.state).toBe("running");
+  });
+
+  it("aggregates ALL text blocks from ALL assistant turns when delivering partial", async () => {
+    const path = resolve(TMP_BASE, "multi-turn-interrupted.jsonl");
+    const lines = [
+      { type: "user", agentId: "x", message: { role: "user", content: "go" } },
+      {
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [{ type: "text", text: "First thought." }],
+          stop_reason: "tool_use",
+        },
+      },
+      {
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [{ type: "text", text: "Second thought." }],
+          stop_reason: "tool_use",
+        },
+      },
+      {
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [{ type: "text", text: "Final partial report." }],
+          stop_reason: "tool_use",
+        },
+      },
+    ];
+    fs.writeFileSync(
+      path,
+      lines.map((l) => JSON.stringify(l)).join("\n") + "\n",
+      "utf-8",
+    );
+    setStale(path, 600_000);
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000,
+    });
+    expect(status.state).toBe("completed");
+    if (status.state === "completed") {
+      // Should contain text from all three turns (bias toward delivering more)
+      expect(status.output).toContain("First thought");
+      expect(status.output).toContain("Second thought");
+      expect(status.output).toContain("Final partial report");
+    }
+  });
+
+  it("ignores thinking blocks in partial delivery (user doesn't want Claude's scratchpad)", async () => {
+    const path = resolve(TMP_BASE, "thinking-filter.jsonl");
+    const lines = [
+      {
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [
+            { type: "thinking", text: "internal reasoning nobody should see" },
+            { type: "text", text: "Actual output text." },
+          ],
+          stop_reason: "tool_use",
+        },
+      },
+    ];
+    fs.writeFileSync(
+      path,
+      lines.map((l) => JSON.stringify(l)).join("\n") + "\n",
+      "utf-8",
+    );
+    setStale(path, 600_000);
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000,
+    });
+    expect(status.state).toBe("completed");
+    if (status.state === "completed") {
+      expect(status.output).toContain("Actual output text");
+      expect(status.output).not.toContain("internal reasoning");
+    }
+  });
+
+  it("extracts usage tokens from the last assistant event when available", async () => {
+    const path = resolve(TMP_BASE, "tokens-partial.jsonl");
+    const lines = [
+      {
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [{ type: "text", text: "partial text" }],
+          stop_reason: "tool_use",
+          usage: { input_tokens: 500, output_tokens: 200 },
+        },
+      },
+    ];
+    fs.writeFileSync(
+      path,
+      lines.map((l) => JSON.stringify(l)).join("\n") + "\n",
+      "utf-8",
+    );
+    setStale(path, 600_000);
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000,
+    });
+    expect(status.state).toBe("completed");
+    if (status.state === "completed") {
+      expect(status.tokensUsed).toEqual({ input: 500, output: 200 });
+    }
+  });
+
+  it("handles file that only has the interruption marker (nothing useful to deliver)", async () => {
+    // Edge case: only interruption, no prior text
+    const path = resolve(TMP_BASE, "only-interrupt.jsonl");
+    const lines = [
+      {
+        type: "user",
+        agentId: "x",
+        message: {
+          role: "user",
+          content: [
+            {
+              type: "tool_result",
+              content: "[Request interrupted by user for tool use]",
+            },
+          ],
+        },
+      },
+    ];
+    fs.writeFileSync(
+      path,
+      lines.map((l) => JSON.stringify(l)).join("\n") + "\n",
+      "utf-8",
+    );
+    setStale(path, 600_000);
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000,
+    });
+    // No assistant text content at all → still running (nothing useful)
+    expect(status.state).toBe("running");
+  });
+
+  it("preserves ordering of text across turns (earlier text first, later text last)", async () => {
+    const path = resolve(TMP_BASE, "order.jsonl");
+    const lines = [
+      {
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [{ type: "text", text: "ALPHA" }],
+          stop_reason: "tool_use",
+        },
+      },
+      {
+        type: "user",
+        agentId: "x",
+        message: { content: [{ type: "tool_result", content: "..." }] },
+      },
+      {
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [{ type: "text", text: "BETA" }],
+          stop_reason: "tool_use",
+        },
+      },
+      {
+        type: "user",
+        agentId: "x",
+        message: { content: [{ type: "tool_result", content: "..." }] },
+      },
+      {
+        type: "assistant",
+        agentId: "x",
+        message: {
+          content: [{ type: "text", text: "GAMMA" }],
+          stop_reason: "tool_use",
+        },
+      },
+    ];
+    fs.writeFileSync(
+      path,
+      lines.map((l) => JSON.stringify(l)).join("\n") + "\n",
+      "utf-8",
+    );
+    setStale(path, 600_000);
+    const status = await parseOutputFileStatus(path, {
+      stalenessMs: 300_000,
+    });
+    expect(status.state).toBe("completed");
+    if (status.state === "completed") {
+      const alphaIdx = status.output.indexOf("ALPHA");
+      const betaIdx = status.output.indexOf("BETA");
+      const gammaIdx = status.output.indexOf("GAMMA");
+      expect(alphaIdx).toBeGreaterThan(-1);
+      expect(betaIdx).toBeGreaterThan(alphaIdx);
+      expect(gammaIdx).toBeGreaterThan(betaIdx);
+    }
+  });
+});