switchroom 0.18.8 → 0.18.9

package/telegram-plugin/gateway/pending-state-stores.ts

@@ -0,0 +1,106 @@
+/**
+ * In-memory storage for the LONG-TAIL of gateway.ts pending-state Maps —
+ * the auth/vault-wizard, config-edit correlation, and transient capture Maps
+ * that PR #3008 deferred when it moved the four agent-initiated approval-card
+ * families behind `approval-card-stores.ts`. Phase 3 step 2 of the gateway
+ * decomposition (see #2996): STORAGE ONLY.
+ *
+ * Two shapes, mirroring the two shapes the long-tail Maps actually have:
+ *
+ *  - `createSweepableStore<T>(isExpired)` — a Map-compatible store whose
+ *    `sweep(now)` deletes every entry the caller's `isExpired(value, now)`
+ *    predicate reports as past its TTL. The predicate is supplied by the
+ *    gateway and CLOSES OVER the family's TTL constant, so the TTL and its
+ *    comparison DIRECTION stay verbatim in gateway.ts — different families use
+ *    `now - staged_at > TTL`, `now - startedAt > TTL`, `now - createdAt > TTL`,
+ *    or an absolute `now > expiresAt`, and each is preserved byte-identically.
+ *    `sweep` is a plain delete-past-TTL loop (no wake / side effects); it
+ *    replaces the identical open-coded reaper / standalone-sweep loops. The
+ *    delete-during-iteration is safe (JS Map iterators tolerate deleting the
+ *    current key) — exactly as the original loops relied on.
+ *
+ *  - `createPlainStore<T>()` — a Map-compatible store with NO sweep, for the
+ *    long-tail Maps whose lifetime is bounded by per-entry timers or an
+ *    LRU cap rather than a TTL sweep (`pendingAskUser`, `agentButtonMeta`).
+ *
+ * Why a Map-compatible surface (get/set/delete/has/size/keys/values/entries/
+ * forEach/iteration) rather than a bespoke API: every existing gateway call
+ * site used the raw Map directly. Preserving the exact Map method surface —
+ * and keeping the variable name unchanged — keeps those call sites
+ * BYTE-IDENTICAL. The store moves WHERE the Map is constructed and (for the
+ * sweepable shape) WHERE its sweep lives, nothing about how the gateway reads
+ * or writes it.
+ *
+ * The backing Map is the sole storage and backs every iterator, so mutation-
+ * during-iteration order/semantics are identical to the raw Map the gateway
+ * used before.
+ */
+
+export interface PlainStore<T> {
+  get(key: string): T | undefined
+  set(key: string, value: T): void
+  delete(key: string): boolean
+  has(key: string): boolean
+  clear(): void
+  readonly size: number
+  keys(): IterableIterator<string>
+  values(): IterableIterator<T>
+  entries(): IterableIterator<[string, T]>
+  forEach(cb: (value: T, key: string, map: Map<string, T>) => void): void
+  [Symbol.iterator](): IterableIterator<[string, T]>
+}
+
+export interface SweepableStore<T> extends PlainStore<T> {
+  /**
+   * Delete every entry past its TTL per the injected `isExpired` predicate.
+   * Plain delete-past-TTL, no wake — byte-identical to the open-coded reaper /
+   * standalone sweep loop it replaces.
+   */
+  sweep(now: number): void
+}
+
+// Build the shared Map surface onto `target` (a getter for `size`, so the
+// live Map size is read on every access — an object spread would freeze it).
+function attachMapSurface<T, S extends object>(target: S, map: Map<string, T>): S & PlainStore<T> {
+  return Object.defineProperties(target, {
+    get: { value: (key: string) => map.get(key), enumerable: true },
+    set: { value: (key: string, value: T) => void map.set(key, value), enumerable: true },
+    delete: { value: (key: string) => map.delete(key), enumerable: true },
+    has: { value: (key: string) => map.has(key), enumerable: true },
+    clear: { value: () => map.clear(), enumerable: true },
+    size: { get: () => map.size, enumerable: true },
+    keys: { value: () => map.keys(), enumerable: true },
+    values: { value: () => map.values(), enumerable: true },
+    entries: { value: () => map.entries(), enumerable: true },
+    forEach: {
+      value: (cb: (value: T, key: string, m: Map<string, T>) => void) => map.forEach(cb),
+      enumerable: true,
+    },
+    [Symbol.iterator]: { value: () => map[Symbol.iterator](), enumerable: true },
+  }) as S & PlainStore<T>
+}
+
+/**
+ * Create a Map-backed store with no automatic expiry. For long-tail Maps
+ * whose entries are removed by per-entry timers or an LRU cap, not a TTL sweep.
+ */
+export function createPlainStore<T>(): PlainStore<T> {
+  return attachMapSurface({}, new Map<string, T>())
+}
+
+/**
+ * Create a Map-backed, self-sweeping store for one long-tail pending-state
+ * family. `isExpired` closes over the family's TTL constant and encodes its
+ * exact comparison direction; `sweep(now)` deletes every entry it flags.
+ */
+export function createSweepableStore<T>(
+  isExpired: (value: T, now: number) => boolean,
+): SweepableStore<T> {
+  const map = new Map<string, T>()
+  const sweep = (now: number): void => {
+    for (const [k, v] of map) {
+      if (isExpired(v, now)) map.delete(k)
+    }
+  }
+  return attachMapSurface({ sweep }, map)
+}

package/telegram-plugin/gateway/register-bot-commands.ts

@@ -0,0 +1,30 @@
+import type { Bot } from 'grammy'
+import {
+  TELEGRAM_BASE_COMMANDS,
+  TELEGRAM_SWITCHROOM_COMMANDS,
+} from '../welcome-text.js'
+
+/**
+ * Register the bot's slash-command menu with Telegram (`setMyCommands`).
+ *
+ * Extracted verbatim from gateway.ts (#2996 Phase 5 leaf move). The `bot`
+ * singleton is injected rather than imported so this stays a pure leaf with
+ * no back-reference into the gateway module.
+ *
+ * Slash-menu is deliberately trimmed from the full command catalogue.
+ * See telegram-plugin/welcome-text.ts TELEGRAM_MENU_COMMANDS for the
+ * rationale (mobile UX focus; ops primitives stay typable but out of
+ * the autocomplete clutter). /commands surfaces the full list.
+ */
+export async function registerSwitchroomBotCommands(bot: Bot): Promise<void> {
+  await bot.api.setMyCommands(
+    [...TELEGRAM_BASE_COMMANDS, ...TELEGRAM_SWITCHROOM_COMMANDS],
+    { scope: { type: 'all_private_chats' } },
+  )
+  // Group chats don't support /start pairing, so only the switchroom
+  // commands are registered there.
+  await bot.api.setMyCommands(
+    TELEGRAM_SWITCHROOM_COMMANDS,
+    { scope: { type: 'all_group_chats' } },
+  )
+}

package/telegram-plugin/tests/approval-card-stores.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Race/ordering pins for the in-memory approval-card stores
+ * (gateway/approval-card-stores.ts) extracted in #2996 Phase 3 step 1.
+ *
+ * These lock the exact orderings the gateway's reaper + callback handlers +
+ * boot restore depend on, BEFORE the storage moved behind the store module:
+ *
+ *   1. verdict-during-sweep is single-shot — an operator tap (`.delete`) that
+ *      lands while the sweep is iterating fires the expiry synthetic AT MOST
+ *      once for a given card; a second sweep tick never double-wakes it.
+ *   2. verdict-during-restore is desync-free — a `.set` (restore) then a
+ *      `.delete` (tap) operate on one Map instance, so a tap can't resurrect a
+ *      restored entry nor a restore resurrect a tapped one.
+ *   3. sweep cadence/fault-isolation is byte-identical to the old inline
+ *      `sweepExpiredEntries(...)`: only past-TTL entries expire, and one
+ *      throwing expiry never skips the remaining entries.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createSweepableCardStore,
+  type SweepableCardStore,
+} from '../gateway/approval-card-stores.js'
+
+interface Card {
+  staged_at: number
+  agent: string
+}
+
+const TTL = 1000
+
+function makeStore(
+  expire: (stageId: string, v: Card, now: number) => void,
+  log: (msg: string) => void = () => {},
+): SweepableCardStore<Card> {
+  return createSweepableCardStore<Card>({
+    isExpired: (v, now) => now - v.staged_at > TTL,
+    expire: () => expire,
+    log: () => log,
+  })
+}
+
+describe('approval-card-stores: sweep cadence', () => {
+  it('expires only entries past TTL', () => {
+    const expired: string[] = []
+    const store = makeStore((id) => {
+      expired.push(id)
+      store.delete(id) // mirror the gateway's expire.remove()
+    })
+    store.set('fresh', { staged_at: 5000, agent: 'a' })
+    store.set('stale', { staged_at: 1000, agent: 'b' })
+    store.sweep(5000) // fresh: 0ms old, stale: 4000ms old > TTL
+    expect(expired).toEqual(['stale'])
+    expect(store.has('fresh')).toBe(true)
+    expect(store.has('stale')).toBe(false)
+  })
+
+  it('is single-shot across two reaper ticks (verdict-during-sweep safe)', () => {
+    const wakes: string[] = []
+    const store = makeStore((id) => {
+      // The pure expire core removes BEFORE the fallible wake; model that here.
+      store.delete(id)
+      wakes.push(id)
+    })
+    store.set('c1', { staged_at: 0, agent: 'a' })
+    store.sweep(5000)
+    store.sweep(5000) // second tick — entry already gone
+    expect(wakes).toEqual(['c1']) // exactly one wake, never two
+  })
+
+  it('a throwing expiry never skips the remaining entries', () => {
+    const seen: string[] = []
+    const store = makeStore((id) => {
+      seen.push(id)
+      if (id === 'boom') throw new Error('dead socket')
+      store.delete(id)
+    })
+    store.set('boom', { staged_at: 0, agent: 'a' })
+    store.set('ok', { staged_at: 0, agent: 'b' })
+    expect(() => store.sweep(5000)).not.toThrow()
+    expect(seen).toContain('boom')
+    expect(seen).toContain('ok')
+    expect(store.has('ok')).toBe(false) // 'ok' still expired despite 'boom' throwing
+  })
+})
+
+describe('approval-card-stores: verdict-during-restore desync-free', () => {
+  it('a tap after restore removes the restored entry (no resurrection)', () => {
+    const store = makeStore(() => {})
+    store.set('r1', { staged_at: 0, agent: 'a' }) // restore populates
+    expect(store.get('r1')).toBeDefined()
+    const removed = store.delete('r1') // operator tap resolves it
+    expect(removed).toBe(true)
+    expect(store.has('r1')).toBe(false)
+  })
+
+  it('a sweep after a tap on the same instance is a no-op for that card', () => {
+    const wakes: string[] = []
+    const store = makeStore((id) => {
+      store.delete(id)
+      wakes.push(id)
+    })
+    store.set('r2', { staged_at: 0, agent: 'a' })
+    store.delete('r2') // tap resolves before the reaper runs
+    store.sweep(5000)
+    expect(wakes).toEqual([]) // already resolved — no timeout wake
+  })
+})
+
+describe('approval-card-stores: Map surface parity', () => {
+  it('supports get/set/delete/has/size/iteration used by call sites', () => {
+    const store = makeStore(() => {})
+    store.set('a', { staged_at: 1, agent: 'x' })
+    store.set('b', { staged_at: 2, agent: 'y' })
+    expect(store.size).toBe(2)
+    expect(store.get('a')?.agent).toBe('x')
+    const seen: string[] = []
+    for (const [id] of store) seen.push(id)
+    expect(seen.sort()).toEqual(['a', 'b'])
+    expect([...store.values()].map((v) => v.agent).sort()).toEqual(['x', 'y'])
+    expect(store.delete('a')).toBe(true)
+    expect(store.has('a')).toBe(false)
+  })
+})