switchroom 0.18.7 → 0.18.8

package/telegram-plugin/tests/voice-send.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Telegram file_id reuse for the on-demand '🔊 Listen' send path.
+ *
+ * gateway.ts is a 25k-line module with import-time side effects, so the send
+ * decision core lives in ../voice-send.ts (imported by the gateway). These
+ * tests drive the real orchestrator + cache primitive with a mocked bot api,
+ * proving the observable contract the gateway wires up:
+ *
+ *   (a) FIRST tap (no stored id) uploads via InputFile and captures the
+ *       returned file_id onto the cache entry;
+ *   (b) SECOND tap sends BY the file_id string — no disk read, no InputFile;
+ *   (c) a file_id send REJECTED as stale (400) falls back to a re-upload and
+ *       refreshes the stored id, so a dead id never permanently breaks Listen.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  sendVoiceReusingFileId,
+  extractVoiceFileId,
+  isInvalidTelegramFileIdError,
+  isHttp400Error,
+  type SentVoiceMessage,
+} from '../voice-send.js'
+import { VoiceOnDemandCache } from '../voice-ondemand.js'
+
+/** A minimal grammy-shaped 400 error (duck-typed the way the gateway sees it). */
+function grammy400(description: string): Error {
+  return Object.assign(new Error(description), { error_code: 400, description })
+}
+
+/** Sent-message stub echoing a file_id, as Telegram returns from sendVoice. */
+function sentWithFileId(fileId: string): SentVoiceMessage {
+  return { voice: { file_id: fileId } }
+}
+
+const OGG = new Uint8Array([0x4f, 0x67, 0x67, 0x53]) // OggS magic
+
+describe('sendVoiceReusingFileId — file_id reuse contract', () => {
+  it('(a) first tap: no stored id → uploads via InputFile, captures the id', async () => {
+    const calls: string[] = []
+    let byFileId = 0
+    let uploaded = 0
+    let captured: string | null = null
+
+    const res = await sendVoiceReusingFileId({
+      fileId: null,
+      sendByFileId: async () => {
+        byFileId++
+        return null
+      },
+      loadAudio: async () => {
+        calls.push('loadAudio')
+        return OGG
+      },
+      sendByUpload: async (audio) => {
+        uploaded++
+        expect(audio).toBe(OGG)
+        return sentWithFileId('FILE_ID_1')
+      },
+      onFileId: (id) => {
+        captured = id
+      },
+    })
+
+    expect(res).toEqual({ ok: true, path: 'upload', refreshed: false })
+    expect(byFileId).toBe(0) // never tried the id path — none stored
+    expect(uploaded).toBe(1) // exactly one upload
+    expect(calls).toEqual(['loadAudio']) // audio WAS loaded on the first tap
+    expect(captured).toBe('FILE_ID_1') // id captured for reuse
+  })
+
+  it('(b) second tap: stored id → sends by file_id string, no disk read, no InputFile', async () => {
+    let loadAudioCalls = 0
+    let uploadCalls = 0
+    let sentId: string | null = null
+
+    const res = await sendVoiceReusingFileId({
+      fileId: 'FILE_ID_1',
+      sendByFileId: async (fid) => {
+        sentId = fid
+        return sentWithFileId('FILE_ID_1') // Telegram echoes the same id
+      },
+      loadAudio: async () => {
+        loadAudioCalls++ // MUST NOT happen — proves no disk read
+        return OGG
+      },
+      sendByUpload: async () => {
+        uploadCalls++ // MUST NOT happen — proves no re-upload
+        return null
+      },
+      onFileId: () => {},
+    })
+
+    expect(res).toEqual({ ok: true, path: 'file_id', refreshed: false })
+    expect(sentId).toBe('FILE_ID_1') // sent BY the string id
+    expect(loadAudioCalls).toBe(0) // no disk read
+    expect(uploadCalls).toBe(0) // no InputFile upload
+  })
+
+  it('(c) stale id (400): falls back to re-upload and refreshes the stored id', async () => {
+    let byFileId = 0
+    let uploaded = 0
+    let refreshedTo: string | null = null
+
+    const res = await sendVoiceReusingFileId({
+      fileId: 'STALE_ID',
+      sendByFileId: async () => {
+        byFileId++
+        throw grammy400('Bad Request: wrong file identifier/HTTP URL specified')
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        return sentWithFileId('FRESH_ID')
+      },
+      onFileId: (id) => {
+        refreshedTo = id
+      },
+    })
+
+    expect(res).toEqual({ ok: true, path: 'upload', refreshed: true })
+    expect(byFileId).toBe(1) // tried the stale id once
+    expect(uploaded).toBe(1) // then re-uploaded
+    expect(refreshedTo).toBe('FRESH_ID') // stored id refreshed, not left stale
+  })
+
+  it('a NON-stale send error is a real failure — no silent re-upload', async () => {
+    let uploaded = 0
+    const res = await sendVoiceReusingFileId({
+      fileId: 'FILE_ID_1',
+      sendByFileId: async () => {
+        throw Object.assign(new Error('forbidden'), { error_code: 403 })
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        return null
+      },
+      onFileId: () => {},
+    })
+    expect(res.ok).toBe(false)
+    expect(uploaded).toBe(0) // did NOT paper over a 403 with an upload
+  })
+
+  it('(C1) UNKNOWN-wording 400: re-uploads + refreshes id even outside the stale-id substrings', async () => {
+    // A 400 whose text is NOT in isInvalidTelegramFileIdError's substring set.
+    // Pre-tweak (substring-gated) this classified as send-failed and never
+    // refreshed the id; post-tweak ANY 400 recovers via re-upload.
+    let byFileId = 0
+    let uploaded = 0
+    let refreshedTo: string | null = null
+
+    const err400 = grammy400('Bad Request: some brand-new file rejection wording')
+    expect(isInvalidTelegramFileIdError(err400)).toBe(false) // guard: outside old substrings
+    expect(isHttp400Error(err400)).toBe(true) // but IS a 400 → now re-uploadable
+
+    const res = await sendVoiceReusingFileId({
+      fileId: 'STALE_ID',
+      sendByFileId: async () => {
+        byFileId++
+        throw err400
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        return sentWithFileId('FRESH_ID')
+      },
+      onFileId: (id) => {
+        refreshedTo = id
+      },
+    })
+
+    expect(res).toEqual({ ok: true, path: 'upload', refreshed: true })
+    expect(byFileId).toBe(1) // tried the id once
+    expect(uploaded).toBe(1) // then re-uploaded on the unknown 400
+    expect(refreshedTo).toBe('FRESH_ID') // stored id refreshed, not left stale
+  })
+
+  it('(C1) a network error (no error_code) still does NOT re-upload', async () => {
+    let uploaded = 0
+    const res = await sendVoiceReusingFileId({
+      fileId: 'FILE_ID_1',
+      sendByFileId: async () => {
+        throw new Error('ECONNRESET') // no error_code → not a 400
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        return null
+      },
+      onFileId: () => {},
+    })
+    expect(res.ok).toBe(false)
+    expect(uploaded).toBe(0) // transient network error is a real failure, not a re-upload
+  })
+
+  it('(C1) re-upload after a 400 ALSO fails → returns failure, no second re-upload', async () => {
+    let byFileId = 0
+    let uploaded = 0
+    let refreshed: string | null = null
+
+    const res = await sendVoiceReusingFileId({
+      fileId: 'STALE_ID',
+      sendByFileId: async () => {
+        byFileId++
+        throw grammy400('Bad Request: totally unfamiliar 400 wording')
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        throw grammy400('Bad Request: upload also rejected') // recovery send fails too
+      },
+      onFileId: (id) => {
+        refreshed = id
+      },
+    })
+
+    expect(res.ok).toBe(false)
+    if (!res.ok) expect(res.reason).toBe('send-failed')
+    expect(byFileId).toBe(1) // id tried once
+    expect(uploaded).toBe(1) // re-uploaded exactly once — NO second attempt / loop
+    expect(refreshed).toBeNull() // failed upload never refreshed the id
+  })
+
+  it('no-audio on the upload path returns { ok:false, reason:"no-audio" }', async () => {
+    const res = await sendVoiceReusingFileId({
+      fileId: null,
+      sendByFileId: async () => null,
+      loadAudio: async () => null, // swept + synth unavailable
+      sendByUpload: async () => {
+        throw new Error('should not be called')
+      },
+      onFileId: () => {},
+    })
+    expect(res).toEqual({ ok: false, reason: 'no-audio' })
+  })
+})
+
+describe('extractVoiceFileId / isInvalidTelegramFileIdError', () => {
+  it('extracts a present file_id, ignores missing/empty', () => {
+    expect(extractVoiceFileId({ voice: { file_id: 'abc' } })).toBe('abc')
+    expect(extractVoiceFileId({ voice: {} })).toBeUndefined()
+    expect(extractVoiceFileId({ voice: { file_id: '' } })).toBeUndefined()
+    expect(extractVoiceFileId(null)).toBeUndefined()
+    expect(extractVoiceFileId(undefined)).toBeUndefined()
+  })
+
+  it('classifies a 400 wrong-file-identifier as stale, others as not', () => {
+    expect(
+      isInvalidTelegramFileIdError(grammy400('Bad Request: wrong file identifier/HTTP URL specified')),
+    ).toBe(true)
+    expect(isInvalidTelegramFileIdError(grammy400('Bad Request: wrong remote file identifier'))).toBe(
+      true,
+    )
+    // Not a file_id problem — genuine failures the caller must surface.
+    expect(isInvalidTelegramFileIdError(grammy400('Bad Request: chat not found'))).toBe(false)
+    expect(
+      isInvalidTelegramFileIdError(Object.assign(new Error('forbidden'), { error_code: 403 })),
+    ).toBe(false)
+    expect(isInvalidTelegramFileIdError(new Error('network'))).toBe(false)
+    expect(isInvalidTelegramFileIdError(null)).toBe(false)
+  })
+
+  it('isHttp400Error: true only for error_code 400, wording-agnostic', () => {
+    expect(isHttp400Error(grammy400('any wording at all'))).toBe(true)
+    expect(isHttp400Error(grammy400('Bad Request: chat not found'))).toBe(true) // 400 regardless of text
+    expect(isHttp400Error(Object.assign(new Error('x'), { error_code: 403 }))).toBe(false)
+    expect(isHttp400Error(Object.assign(new Error('x'), { error_code: 500 }))).toBe(false)
+    expect(isHttp400Error(new Error('network'))).toBe(false) // no error_code
+    expect(isHttp400Error(null)).toBe(false)
+    expect(isHttp400Error(undefined)).toBe(false)
+  })
+})
+
+describe('VoiceOnDemandCache.setTelegramFileId — capture + sweep drop', () => {
+  it('stores an id on a live entry and returns it via get()', () => {
+    const cache = new VoiceOnDemandCache()
+    cache.put('tok', { text: 'hi', speed: 1.1 })
+    cache.setTelegramFileId('tok', 'FILE_ID_1')
+    expect(cache.get('tok')?.telegramFileId).toBe('FILE_ID_1')
+  })
+
+  it('ignores an empty id and unknown/evicted tokens', () => {
+    const cache = new VoiceOnDemandCache()
+    cache.put('tok', { text: 'hi', speed: 1.1 })
+    cache.setTelegramFileId('tok', '') // ignored
+    expect(cache.get('tok')?.telegramFileId).toBeUndefined()
+    cache.setTelegramFileId('missing', 'X') // no-op, no throw
+    expect(cache.get('missing')).toBeNull()
+  })
+
+  it('drops the stored id when the 7-day sweep prunes the entry — no resurrection', () => {
+    const cache = new VoiceOnDemandCache()
+    cache.put('tok', { text: 'hi', speed: 1.1 })
+    cache.setTelegramFileId('tok', 'FILE_ID_1')
+    cache.prune(['tok']) // sweep deleted the on-disk file for this token
+    expect(cache.get('tok')).toBeNull() // entry AND its file_id are gone
+  })
+
+  it('does not store an id on an already-expired entry', () => {
+    let t = 1000
+    const cache = new VoiceOnDemandCache({ ttlMs: 100, now: () => t })
+    cache.put('tok', { text: 'hi', speed: 1.1 })
+    t = 2000 // past TTL
+    cache.setTelegramFileId('tok', 'FILE_ID_1') // no-op on expired entry
+    expect(cache.get('tok')).toBeNull()
+  })
+})

package/telegram-plugin/tests/worker-pin-reaper.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+import {
+  decideWorkerPinReaps,
+  workerAgentIdOfPinKey,
+  WORKER_PIN_TTL_MS_DEFAULT,
+  type WorkerPinCandidate,
+} from "../gateway/worker-pin-reaper.js";
+
+const NOW = 1_750_000_000_000;
+const TTL = WORKER_PIN_TTL_MS_DEFAULT;
+
+function pin(over: Partial<WorkerPinCandidate> = {}): WorkerPinCandidate {
+  return { pinKey: "wk:agent-1", chatId: "123", pinnedAt: NOW - 60_000, ...over };
+}
+
+describe("workerAgentIdOfPinKey", () => {
+  it("extracts the agentId from a wk: key", () => {
+    expect(workerAgentIdOfPinKey("wk:abc123")).toBe("abc123");
+  });
+  it("returns null for non-worker keys (fg:/banner:/tool:) and empty ids", () => {
+    expect(workerAgentIdOfPinKey("fg:123:5")).toBeNull();
+    expect(workerAgentIdOfPinKey("banner:owner")).toBeNull();
+    expect(workerAgentIdOfPinKey("tool:123:9")).toBeNull();
+    expect(workerAgentIdOfPinKey("wk:")).toBeNull();
+  });
+});
+
+describe("decideWorkerPinReaps (#3001 mid-session wk: sweep)", () => {
+  it("reaps a pin whose worker is terminal, however young the pin is", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ pinnedAt: NOW - 1_000 })],
+      statusOf: () => 'terminal' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(1);
+    expect(reaps[0].reason).toBe("terminal");
+    expect(reaps[0].pinKey).toBe("wk:agent-1");
+  });
+
+  it("reaps a non-terminal pin once it exceeds the TTL", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ pinnedAt: NOW - TTL })],
+      statusOf: () => 'unknown' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(1);
+    expect(reaps[0].reason).toBe("ttl");
+  });
+
+  it("NEVER touches a pin younger than the TTL when the registry cannot vouch (unknown)", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ pinnedAt: NOW - TTL + 1 })],
+      statusOf: () => 'unknown' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+
+  it("ignores non-worker keys entirely (fg:/banner:/tool: are not its job)", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [
+        pin({ pinKey: "fg:123:5", pinnedAt: NOW - 10 * TTL }),
+        pin({ pinKey: "banner:owner", pinnedAt: NOW - 10 * TTL }),
+        pin({ pinKey: "tool:123:9", pinnedAt: NOW - 10 * TTL }),
+      ],
+      statusOf: () => 'terminal' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+
+  it("skips a candidate with no chat id (cannot unpin without one)", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ chatId: "", pinnedAt: NOW - 10 * TTL })],
+      statusOf: () => 'terminal' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+
+  it("a registry-confirmed RUNNING worker keeps its pin PAST the TTL (no unpin/re-pin churn on healthy long workers)", () => {
+    const reaps = decideWorkerPinReaps({
+      pins: [pin({ pinnedAt: NOW - 10 * TTL })],
+      statusOf: () => 'running' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+
+  it("status is consulted per-agent: terminal reaps young, running exempts old, unknown falls to the TTL gate", () => {
+    const seen: string[] = [];
+    const reaps = decideWorkerPinReaps({
+      pins: [
+        pin({ pinKey: "wk:done", pinnedAt: NOW - 1_000 }),
+        pin({ pinKey: "wk:running-old", pinnedAt: NOW - TTL - 1 }),
+        pin({ pinKey: "wk:unknown-young", pinnedAt: NOW - 1_000 }),
+        pin({ pinKey: "wk:unknown-old", pinnedAt: NOW - TTL - 1 }),
+      ],
+      statusOf: (agentId) => {
+        seen.push(agentId);
+        if (agentId === "done") return "terminal";
+        if (agentId === "running-old") return "running";
+        return "unknown";
+      },
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(seen).toEqual(["done", "running-old", "unknown-young", "unknown-old"]);
+    expect(reaps.map((r) => [r.pinKey, r.reason])).toEqual([
+      ["wk:done", "terminal"],
+      ["wk:unknown-old", "ttl"],
+    ]);
+  });
+
+  it("registry hiccup ('unknown') never unpins a young pin — the caller's contract on statusOf degrade", () => {
+    // The gateway wraps its DB lookup and degrades to 'unknown'. This pins the
+    // pure module's side of the contract: unknown + young pin = untouched.
+    const reaps = decideWorkerPinReaps({
+      pins: [pin()],
+      statusOf: () => 'unknown' as const,
+      ttlMs: TTL,
+      now: NOW,
+    });
+    expect(reaps).toHaveLength(0);
+  });
+});

package/telegram-plugin/uat/scenarios/jtbd-deliberate-restart-resumes-dm.test.ts

@@ -0,0 +1,118 @@
+/**
+ * JTBD scenario named by `reference/jobs/survive-reboots-and-real-life.md`
+ * § Prove it — "Deliberate restart resumes, bounded (DM)".
+ *
+ * Contract under test (#2988): a DELIBERATE restart (operator
+ * `switchroom agent restart`, i.e. a clean SIGTERM shutdown with a
+ * clean-shutdown marker) that lands MID-TURN resumes the interrupted turn
+ * like a crash-class interruption. The quota-saving suppression applies only
+ * when nothing was in flight — it never swallows mid-turn work. And the
+ * resume is bounded: AT MOST ONCE per interruption (the loop-guard caps the
+ * resume chain), so we also assert no second resume-framed turn fires after
+ * the first completes.
+ *
+ * Sibling: `jtbd-interrupted-turn-resumes-dm.test.ts` (same interruption
+ * mechanics; this scenario adds the deliberate-restart class + the
+ * at-most-once bound). Decision-level twin: `decideBootResumeKind` cases in
+ * `tests/resume-inbound-builder.test.ts` (BOUNDED CHAIN) and
+ * `shouldSuppressBootResume` in `tests/gateway-clean-shutdown-marker.test.ts`.
+ *
+ * Self-skips green without NOPASSWD sudo.
+ */
+
+import { describe, it, expect } from "vitest";
+import { execSync, spawn } from "node:child_process";
+import { spinUp } from "../harness.js";
+
+const AGENT = "test-harness";
+const MID_TURN_MS = 10_000;        // let the turn get in-flight before the bounce
+const RESUME_BUDGET_MS = 180_000;  // boot + resume + reply
+const QUIET_WINDOW_MS = 90_000;    // after the resume completes, no second resume may fire
+// Messages landing within this window of the FIRST resume-framed reply are
+// treated as the same resumed turn (e.g. a progress line plus the final
+// answer of one turn) — only a resume-framed message AFTER it counts as a
+// second resume for the at-most-once bound.
+const SAME_TURN_GRACE_MS = 20_000;
+
+const RESUME_FRAMING = /resum|picking .*back|interrupted|cut off|just restarted/i;
+
+function canShellSudo(): boolean {
+  try {
+    execSync("sudo -n true", { stdio: "ignore", timeout: 2_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function kickRestartDetached(name: string): void {
+  // A deliberate operator restart: clean SIGTERM path, clean-shutdown marker
+  // written — the exact class #2988 makes resume in-flight work through.
+  const child = spawn(
+    "sudo",
+    ["-n", "env", `PATH=${process.env.PATH}`, `HOME=${process.env.HOME}`,
+      "switchroom", "agent", "restart", name, "--force"],
+    { detached: true, stdio: "ignore" },
+  );
+  child.unref();
+}
+
+const sudoOk = canShellSudo();
+
+(sudoOk ? describe : describe.skip)(
+  "uat: deliberate restart mid-turn resumes exactly once (DM, #2988)",
+  () => {
+    it(
+      "an operator restart mid-turn resumes the work once, and never a second time",
+      async () => {
+        const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+        try {
+          // A task long enough to still be in flight at MID_TURN_MS.
+          await sc.sendDM(
+            `Please write a thorough, detailed ~300-word explanation of how a ` +
+            `player piano's pneumatic action reads a music roll, step by step. ` +
+            `Take your time and be complete.`,
+          );
+
+          await new Promise((r) => setTimeout(r, MID_TURN_MS));
+          kickRestartDetached(AGENT);
+
+          // 1. In-flight work resumes: quota-saving suppression must NOT
+          //    swallow a turn that was mid-flight at the bounce. Edits are
+          //    excluded — a progress-card edit must not satisfy this; only
+          //    a genuinely NEW message from the resumed turn counts.
+          const reply = await sc.expectMessage(
+            (m) => !m.edited && RESUME_FRAMING.test(m.text),
+            { from: "bot", timeout: RESUME_BUDGET_MS },
+          );
+          expect(reply.text).toMatch(RESUME_FRAMING);
+          expect(reply.text.length).toBeGreaterThan(40);
+
+          // 2. Bounded chain: with the interruption resolved, no SECOND
+          //    resume-framed turn may fire (at-most-once per interruption).
+          //    Edits are excluded, and messages within SAME_TURN_GRACE_MS of
+          //    the first reply are deduped as part of the SAME resumed turn
+          //    (two resume-ish lines in one turn are not a second resume).
+          const firstReplyAt = reply.date.getTime();
+          let second: unknown = null;
+          try {
+            second = await sc.expectMessage(
+              (m) =>
+                !m.edited &&
+                m.messageId !== reply.messageId &&
+                m.date.getTime() > firstReplyAt + SAME_TURN_GRACE_MS &&
+                RESUME_FRAMING.test(m.text),
+              { from: "bot", timeout: QUIET_WINDOW_MS },
+            );
+          } catch {
+            // timeout is the PASS: no repeat resume.
+          }
+          expect(second).toBeNull();
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      RESUME_BUDGET_MS + QUIET_WINDOW_MS + 120_000,
+    );
+  },
+);