switchroom 0.14.39 → 0.14.41

package/telegram-plugin/gateway/inbound-delivery-confirm.ts

@@ -0,0 +1,160 @@
+/**
+ * Reliable inbound delivery: deliver-until-acked (the marko drop-wedge).
+ *
+ * Delivering an inbound to claude is fire-and-forget: the gateway calls
+ * `sendToAgent`, the bridge turns it into an MCP channel notification, and
+ * the unmodified CLI appends the text into its composer and auto-submits
+ * ONLY when the composer is empty + idle. If the message lands while claude
+ * is still finalizing the prior turn, the auto-submit races turn-completion
+ * and the text strands unsubmitted — claude never starts the turn, so the
+ * gateway eventually drops the message at the 300s silence-poke. Observed
+ * recurring on `marko` (supergroup topic + DMs alike).
+ *
+ * This is the queue that makes delivery reliable. The contract is the whole
+ * idea, and it is deliberately small:
+ *
+ *   1. A delivered inbound is ACKED only when claude actually starts the
+ *      turn — the `enqueue` session-event (the one signal that claude truly
+ *      picked the message up). NOT when `sendToAgent` returns true.
+ *   2. Until acked, the message stays tracked. If it hasn't been acked
+ *      within `timeoutMs`, it stranded: re-deliver it (the gateway re-clears
+ *      the composer and re-sends).
+ *   3. Re-deliver as many times as it takes. We never drop the message and
+ *      never give up — a reliable queue keeps the message until it lands.
+ *
+ * Keyed per `chatKey(chatId, threadId)`, so DMs and supergroup forum topics
+ * are handled identically (the key is opaque here). The #1556 gate
+ * serialises delivery per key, so at most one delivery per key is in flight.
+ *
+ * Pure bookkeeping only — the gateway does the actual composer-clear and
+ * re-send for whatever `sweep` returns. Unit-tested in isolation.
+ */
+
+export interface PendingDelivery<M> {
+  /** chatKey(chatId, threadId) — opaque to this module. */
+  readonly key: string
+  /** The exact inbound to re-send until claude acks it. */
+  readonly inbound: M
+  /**
+   * Source message id of the tracked inbound (stringified Telegram
+   * `message_id`), or null if unknown. The `enqueue` ack matches on THIS so a
+   * synthetic-source turn (cron / resume / vault / reaction) that shares the
+   * chatKey can't false-ack — and silently drop — a real user message still
+   * waiting to land. See ackDelivery.
+   */
+  readonly messageId: string | null
+  /** When the latest delivery attempt was made (unix-ms). */
+  lastAttemptAt: number
+}
+
+export interface DeliveryQueue<M> {
+  readonly pending: Map<string, PendingDelivery<M>>
+}
+
+export function createDeliveryQueue<M>(): DeliveryQueue<M> {
+  return { pending: new Map() }
+}
+
+/**
+ * Track a freshly-delivered inbound, awaiting claude's `enqueue` ack.
+ * Overwrites any prior pending for the key — the #1556 gate serialises per
+ * key, so a later inbound supersedes an earlier un-acked one for that key.
+ * `messageId` (stringified Telegram message_id) lets the ack match only the
+ * enqueue that belongs to THIS message; pass null when unknown.
+ */
+export function trackDelivery<M>(
+  q: DeliveryQueue<M>,
+  key: string,
+  inbound: M,
+  now: number,
+  messageId: string | null = null,
+): void {
+  q.pending.set(key, { key, inbound, messageId, lastAttemptAt: now })
+}
+
+/**
+ * Ack a delivery — call from the `enqueue` session-event (claude started a
+ * turn). `enqueue` fires for EVERY turn start regardless of source (user
+ * inbound, cron, subagent-handback, vault-resume, restart-marker), so acking
+ * purely by chatKey would let a synthetic-source turn clear — and thus
+ * silently drop — a real user message still waiting under the same key. So
+ * ack ONLY when the enqueue's source message id matches the tracked one.
+ *
+ * Matching rule: if we recorded a messageId for the pending entry, require the
+ * enqueue's `enqueueMessageId` to equal it. If we never recorded one (legacy /
+ * defensive null), fall back to key-only ack. Returns true if an entry was
+ * cleared.
+ */
+export function ackDelivery<M>(
+  q: DeliveryQueue<M>,
+  key: string,
+  enqueueMessageId: string | null = null,
+): boolean {
+  const entry = q.pending.get(key)
+  if (!entry) return false
+  // A different message started this turn — don't ack ours (it may still be
+  // waiting to land; the sweep will re-deliver it if it stranded).
+  if (entry.messageId != null && entry.messageId !== enqueueMessageId) return false
+  q.pending.delete(key)
+  return true
+}
+
+/**
+ * Return the inbounds that stranded (no ack within `timeoutMs`) and should be
+ * re-delivered now. Resets each returned entry's clock so the next sweep
+ * waits another full `timeoutMs` — the gateway re-sends them. Entries still
+ * within the window are left untouched (claude may yet be picking them up).
+ */
+export function sweep<M>(
+  q: DeliveryQueue<M>,
+  now: number,
+  timeoutMs: number,
+): PendingDelivery<M>[] {
+  const redeliver: PendingDelivery<M>[] = []
+  for (const entry of q.pending.values()) {
+    if (now - entry.lastAttemptAt < timeoutMs) continue
+    entry.lastAttemptAt = now
+    redeliver.push(entry)
+  }
+  return redeliver
+}
+
+/** Forget a key without acking (e.g. the bridge went offline and the message
+ *  was handed back to the offline buffer, which owns it now). */
+export function forgetDelivery<M>(q: DeliveryQueue<M>, key: string): void {
+  q.pending.delete(key)
+}
+
+/**
+ * Should this delivered inbound be tracked for ack/re-delivery?
+ *
+ * Track a delivery iff it is a fresh user turn that will produce exactly one
+ * `enqueue` to ack against. Everything that does NOT enqueue must be excluded,
+ * or the sweep re-delivers it forever (re-clearing the composer every cycle):
+ *
+ *   - `isSteering` / `isInterrupt` — the #1556 gate's carve-outs: delivered
+ *     mid-turn to AMEND the running turn, so they never start a fresh turn and
+ *     never emit `enqueue`.
+ *   - `hasSource` — synthetic inbounds (cron / vault-resume / subagent-handback
+ *     / reaction) carry a `meta.source`; they enqueue under their own semantics
+ *     and must never be tracked as if they were a queued user turn.
+ *   - empty `effectiveText` — an empty body (e.g. `/queue` with no text) is
+ *     silently dropped by claude's auto-submit and never enqueues, so tracking
+ *     it is a pure re-delivery loop (a self-inflicted DoS on the queue).
+ *
+ * Mirror the gate's carve-outs here so tracking is exactly the set of messages
+ * that produce an `enqueue`.
+ */
+export function shouldTrackDelivery(input: {
+  isSteering: boolean
+  isInterrupt: boolean
+  hasSource?: boolean
+  effectiveText?: string
+}): boolean {
+  if (input.isSteering || input.isInterrupt) return false
+  if (input.hasSource) return false
+  // Gate on empty text only when the caller actually provided it (undefined =
+  // "not supplied", left untracked-gated so existing callers keep their behaviour).
+  if (input.effectiveText !== undefined && input.effectiveText.trim().length === 0) return false
+  return true
+}

package/telegram-plugin/tests/inbound-delivery-confirm.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  ackDelivery,
+  createDeliveryQueue,
+  forgetDelivery,
+  shouldTrackDelivery,
+  sweep,
+  trackDelivery,
+  type DeliveryQueue,
+} from '../gateway/inbound-delivery-confirm.js'
+
+/**
+ * Regression coverage for the marko drop-wedge.
+ *
+ * An inbound delivered to claude's TUI composer strands unsubmitted when the
+ * auto-submit races turn-completion. claude never emits `enqueue`, so the
+ * gateway used to sit "typing…" for 300s then DROP the message.
+ *
+ * The queue's contract: a delivered inbound is acked ONLY by `enqueue`; until
+ * then it is re-delivered every `timeoutMs`, forever, never dropped — and an
+ * acked delivery never re-fires (no duplicate turns).
+ */
+type Msg = { text: string }
+const TIMEOUT = 15_000
+
+function fresh(): DeliveryQueue<Msg> {
+  return createDeliveryQueue<Msg>()
+}
+
+describe('inbound-delivery-confirm (reliable deliver-until-acked queue)', () => {
+  it('an acked delivery is never re-delivered (happy path — no duplicate turns)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'hi' }, 1_000)
+    expect(ackDelivery(q, 'chat:_')).toBe(true) // enqueue arrived
+    expect(sweep(q, 1_000 + 999_999, TIMEOUT)).toHaveLength(0)
+    expect(q.pending.size).toBe(0)
+  })
+
+  it('within the timeout, an un-acked delivery is left alone (claude may still be picking it up)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'hi' }, 1_000)
+    expect(sweep(q, 1_000 + 14_999, TIMEOUT)).toHaveLength(0)
+    expect(q.pending.size).toBe(1)
+  })
+
+  it('a strand (no ack) is re-delivered after the timeout, and the clock resets', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'draft nurture email' }, 1_000)
+    const r = sweep(q, 1_000 + 15_000, TIMEOUT)
+    expect(r).toHaveLength(1)
+    expect(r[0]!.inbound.text).toBe('draft nurture email')
+    expect(r[0]!.lastAttemptAt).toBe(1_000 + 15_000) // clock reset
+    // not re-swept until another full timeout elapses
+    expect(sweep(q, 1_000 + 15_000 + 14_999, TIMEOUT)).toHaveLength(0)
+  })
+
+  it('keeps re-delivering forever until acked — never drops (the reliability invariant)', () => {
+    const q = fresh()
+    let t = 0
+    trackDelivery(q, 'chat:_', { text: 'x' }, t)
+    for (let i = 0; i < 50; i++) {
+      t += 15_000
+      expect(sweep(q, t, TIMEOUT)).toHaveLength(1) // still trying after 50 strands
+    }
+    expect(q.pending.size).toBe(1) // never dropped
+    // claude finally picks it up → acked → stops.
+    expect(ackDelivery(q, 'chat:_')).toBe(true)
+    expect(sweep(q, t + 999_999, TIMEOUT)).toHaveLength(0)
+  })
+
+  it('an ack that lands right after a re-delivery stops further re-delivery (no duplicate turns)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'x' }, 0)
+    sweep(q, 15_000, TIMEOUT) // strand → re-delivered
+    expect(ackDelivery(q, 'chat:_')).toBe(true) // the re-delivered copy landed
+    expect(sweep(q, 999_999, TIMEOUT)).toHaveLength(0)
+    expect(q.pending.size).toBe(0)
+  })
+
+  it('keys are independent — a strand on one topic does not affect another (DM + supergroup topics)', () => {
+    const q = fresh()
+    trackDelivery(q, '-100:4', { text: 'crm topic msg' }, 0) // supergroup CRM topic
+    trackDelivery(q, '555:_', { text: 'dm msg' }, 0) // a DM
+    ackDelivery(q, '555:_') // the DM submits fine
+    const r = sweep(q, 15_000, TIMEOUT)
+    expect(r).toHaveLength(1)
+    expect(r[0]!.key).toBe('-100:4') // only the stranded topic re-delivers
+  })
+
+  it('tracking the same key twice keeps only the latest inbound (gate serialises per key)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'first' }, 0)
+    trackDelivery(q, 'chat:_', { text: 'second' }, 100)
+    expect(q.pending.size).toBe(1)
+    expect(sweep(q, 100 + 15_000, TIMEOUT)[0]!.inbound.text).toBe('second')
+  })
+
+  it('ack on an unknown key is a harmless no-op', () => {
+    expect(ackDelivery(fresh(), 'never-tracked')).toBe(false)
+  })
+
+  it('forgetDelivery clears without acking or re-delivering (bridge went offline)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'x' }, 0)
+    forgetDelivery(q, 'chat:_')
+    expect(q.pending.size).toBe(0)
+    expect(sweep(q, 999_999, TIMEOUT)).toHaveLength(0)
+  })
+})
+
+// Regression for the cross-source ACK collision (silent drop): `enqueue` fires
+// for EVERY turn start regardless of source. A synthetic-source turn (cron /
+// resume / vault / reaction) that shares the chatKey of a real user message
+// still waiting to land would, with a key-only ack, clear — and silently drop
+// — that user message. The ack must match on the tracked message id.
+describe('ackDelivery — message-id-matched (cross-source false-ack guard)', () => {
+  it('acks when the enqueue message id matches the tracked one', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'real user msg' }, 0, '5001')
+    expect(ackDelivery(q, 'chat:_', '5001')).toBe(true)
+    expect(q.pending.size).toBe(0)
+  })
+
+  it('does NOT ack when a different (synthetic-source) turn enqueues under the same key', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'real user msg' }, 0, '5001')
+    // a cron / resume turn for the same chat enqueues first, with its own id
+    expect(ackDelivery(q, 'chat:_', '1716123456789')).toBe(false)
+    // the user message is still tracked — it strands → gets re-delivered, not dropped
+    expect(q.pending.size).toBe(1)
+    expect(sweep(q, 15_000, TIMEOUT)).toHaveLength(1)
+    // and its own enqueue (matching id) later acks it cleanly
+    expect(ackDelivery(q, 'chat:_', '5001')).toBe(true)
+    expect(q.pending.size).toBe(0)
+  })
+
+  it('does NOT ack when the enqueue carries no message id but the tracked one has one', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'real user msg' }, 0, '5001')
+    expect(ackDelivery(q, 'chat:_', null)).toBe(false)
+    expect(q.pending.size).toBe(1)
+  })
+
+  it('falls back to key-only ack when no message id was recorded (legacy/defensive)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'x' }, 0) // no messageId
+    expect(ackDelivery(q, 'chat:_', '5001')).toBe(true)
+    expect(q.pending.size).toBe(0)
+  })
+})
+
+// Regression for the steer/interrupt re-delivery loop: steering and `!`
+// interrupt inbounds amend the running turn and never emit `enqueue`, so they
+// must NOT be tracked (else the sweep re-delivers them forever). Only
+// fresh-turn messages — which DO enqueue — are tracked.
+describe('shouldTrackDelivery — only fresh-turn messages are tracked', () => {
+  it('tracks a normal (non-steering, non-interrupt) message', () => {
+    expect(shouldTrackDelivery({ isSteering: false, isInterrupt: false })).toBe(true)
+  })
+  it('does NOT track a /steer message (amends the turn — never acks)', () => {
+    expect(shouldTrackDelivery({ isSteering: true, isInterrupt: false })).toBe(false)
+  })
+  it('does NOT track a ! interrupt message (amends the turn — never acks)', () => {
+    expect(shouldTrackDelivery({ isSteering: false, isInterrupt: true })).toBe(false)
+  })
+  it('does NOT track when both flags set (defensive)', () => {
+    expect(shouldTrackDelivery({ isSteering: true, isInterrupt: true })).toBe(false)
+  })
+  it('does NOT track a synthetic (meta.source) inbound — cron/resume/vault/reaction enqueue under their own semantics', () => {
+    expect(shouldTrackDelivery({ isSteering: false, isInterrupt: false, hasSource: true })).toBe(false)
+  })
+  it('does NOT track an empty-body message (e.g. `/queue` with no text) — never enqueues, would re-deliver forever', () => {
+    expect(shouldTrackDelivery({ isSteering: false, isInterrupt: false, effectiveText: '' })).toBe(false)
+    expect(shouldTrackDelivery({ isSteering: false, isInterrupt: false, effectiveText: '   ' })).toBe(false)
+  })
+  it('tracks a normal message when effectiveText is provided and non-empty', () => {
+    expect(shouldTrackDelivery({ isSteering: false, isInterrupt: false, effectiveText: 'draft the email' })).toBe(true)
+  })
+})

package/telegram-plugin/uat/scenarios/inbound-no-drop-rapid-fire-dm.test.ts

@@ -0,0 +1,64 @@
+/**
+ * E2E regression — inbound is NEVER dropped under rapid fire (the drop-wedge).
+ *
+ * The bug: a Telegram inbound reaches claude as an MCP channel notification
+ * the unmodified CLI appends to its composer and auto-submits only when the
+ * composer is empty + idle. A message arriving the instant the prior turn
+ * completes races that auto-submit and strands unsubmitted — claude never
+ * starts the turn, the gateway sits "typing…", and the 300s silence-poke
+ * DROPS the message. Observed recurring on `marko` (supergroup topics + DMs).
+ *
+ * This scenario drives the exact failure timing: it fires each message the
+ * instant the prior reply lands (i.e. right at turn-completion, the strand
+ * window) and asserts EVERY message gets its own unique token back. With the
+ * deliver-until-acked queue (inbound-delivery-confirm.ts) a strand self-heals
+ * via re-delivery; without it, a stranded message yields NO reply within the
+ * timeout and this test fails on exactly the message that was swallowed.
+ *
+ * Each message carries a random token and the assertion matches THAT token,
+ * so a reply to message N-1 can never be mistaken for message N's reply — the
+ * test proves every distinct message was actually processed, not merely that
+ * "some replies came back".
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+
+describe("uat: rapid-fire inbound — no message is ever dropped (drop-wedge)", () => {
+  it(
+    "every back-to-back message gets its own reply (delivery never strands)",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        const N = 8;
+        const dropped: number[] = [];
+        for (let i = 1; i <= N; i++) {
+          const token = `acktok-${i}-${Math.random().toString(36).slice(2, 8)}`;
+          await sc.sendDM(
+            `Reply with exactly this token and nothing else: ${token}`,
+          );
+          try {
+            const reply = await sc.expectMessage((m) => m.text.includes(token), {
+              from: "bot",
+              timeout: 75_000,
+            });
+            expect(reply.text).toContain(token);
+          } catch {
+            // The message stranded — no reply carrying its token arrived.
+            dropped.push(i);
+          }
+          // Deliberately NO delay: fire the next message the instant this
+          // reply lands, so it arrives in the turn-completion strand window.
+        }
+        expect(
+          dropped,
+          `messages dropped (no reply within timeout): ${dropped.join(", ")} of ${N}`,
+        ).toEqual([]);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    // N messages × (turn + up to one ~15-20s strand recovery) — generous.
+    900_000,
+  );
+});

package/telegram-plugin/uat/scenarios/jtbd-rapid-followup-dm.test.ts

@@ -55,8 +55,15 @@ describe("uat: rapid follow-ups — steering vs queued classification", () => {
           (m) => {
             const txt = m.text;
             const mentionsMd5 = /\bmd5\b/i.test(txt);
+            // Steer narration: the agent acknowledges amending the in-flight
+            // task. Accept the phrasings the model actually uses — including
+            // "Switched to MD5 per your update/follow-up" (the 2026-06-02
+            // canary reply that the old regex wrongly rejected). Anchored on
+            // "per your <qualifier>" / continuation language so it stays
+            // distinct from the QUEUED path (a fresh answer with no such
+            // course-correction narration).
             const narratesSteer =
-              /↪️|\bsteer(ing)?\b|continuing the (prior|original|in-flight) task|amendment|course[- ]correct/i.test(
+              /↪️|\bsteer(ing)?\b|switch(?:ed|ing)? to \w+ per your (?:update|follow-?up|guidance|request|steer)|continuing the (prior|original|in-flight) task|amendment|course[- ]correct/i.test(
                 txt,
               );
             return mentionsMd5 && narratesSteer;