switchroom 0.18.3 → 0.18.7

package/telegram-plugin/tests/pending-card-durability-wiring.test.ts

@@ -0,0 +1,202 @@
+/**
+ * Source-text wiring pins for the agent-initiated approval-card durability fix.
+ *
+ * gateway.ts has top-level side effects and isn't unit-importable; the pure
+ * primitives are unit-tested in pending-card-store.test.ts and
+ * approval-timeout-inbound-builders.test.ts. These pins lock the wiring that
+ * connects them so the two failure modes can't silently regress:
+ *
+ *   Defect A — pending card state was in-memory only; a gateway restart lost it
+ *     and a later tap hit the "Card expired" tombstone (agent parked forever).
+ *   Defect B — no wake on TTL expiry; an unanswered card left the agent parked
+ *     forever (the sweeps were lazy and never woke the agent).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const read = (p: string) => readFileSync(resolve(__dirname, '..', p), 'utf8')
+const GATEWAY = read('gateway/gateway.ts')
+
+function slice(src: string, header: string, span = 3000): string {
+  const start = src.indexOf(header)
+  expect(start, `expected to find ${header}`).toBeGreaterThan(-1)
+  return src.slice(start, start + span)
+}
+
+// ─── Store instantiation ──────────────────────────────────────────────────
+
+describe('pending-card-store wiring', () => {
+  it('imports and instantiates the durable pending-card store', () => {
+    expect(GATEWAY).toMatch(/from '\.\/pending-card-store\.js'/)
+    expect(GATEWAY).toMatch(/const pendingCardStore = createPendingCardStore\(STATE_DIR\)/)
+  })
+
+  it('imports the four timeout inbound builders', () => {
+    expect(GATEWAY).toMatch(/from '\.\/approval-timeout-inbound-builders\.js'/)
+    for (const b of [
+      'buildVaultAccessTimeoutInbound',
+      'buildVaultSaveTimeoutInbound',
+      'buildSecretRequestTimeoutInbound',
+      'buildMentalModelProposeTimeoutInbound',
+    ]) {
+      expect(GATEWAY).toContain(b)
+    }
+  })
+})
+
+// ─── Defect A part 1: persistence at staging ──────────────────────────────
+
+describe('staging persists card metadata (Defect A)', () => {
+  it('vault_request_access stages into the durable store', () => {
+    const fn = slice(GATEWAY, 'async function executeVaultRequestAccess', 6000)
+    expect(fn).toMatch(/pendingCardStore\.add\(\{[\s\S]*family: 'vault_request_access'/)
+  })
+
+  it('request_secret stages into the durable store', () => {
+    const fn = slice(GATEWAY, 'async function executeRequestSecret', 3000)
+    expect(fn).toMatch(/pendingCardStore\.add\(\{[\s\S]*family: 'request_secret'/)
+  })
+
+  it('mental_model_propose stages into the durable store', () => {
+    const fn = slice(GATEWAY, 'async function executeMentalModelPropose', 6000)
+    expect(fn).toMatch(/pendingCardStore\.add\(\{[\s\S]*family: 'mental_model_propose'/)
+  })
+
+  it('vault_request_save stages metadata but NEVER the secret value (hygiene)', () => {
+    const fn = slice(GATEWAY, 'async function executeVaultRequestSave', 6000)
+    const addBlock = slice(fn, "pendingCardStore.add({", 700)
+    expect(addBlock).toMatch(/family: 'vault_request_save'/)
+    // The staged secret `value` must NOT be copied into the persisted record.
+    expect(addBlock).not.toMatch(/value:/)
+  })
+})
+
+// ─── Defect A part 2: boot restore ────────────────────────────────────────
+
+describe('boot restore (Defect A)', () => {
+  it('defines restorePendingApprovalCards and calls it at boot', () => {
+    expect(GATEWAY).toMatch(/function restorePendingApprovalCards\(\)/)
+    expect(GATEWAY).toMatch(/restorePendingApprovalCards\(\)/g)
+  })
+
+  it('restored vault_request_save has no value + is flagged restoredWithoutValue', () => {
+    const fn = slice(GATEWAY, 'function restorePendingApprovalCards', 4000)
+    expect(fn).toMatch(/value: '',/)
+    expect(fn).toMatch(/restoredWithoutValue: true/)
+  })
+
+  it('a Save tap on a restored (valueless) card degrades gracefully instead of writing empty', () => {
+    const fn = slice(GATEWAY, 'async function handleVaultRequestSaveCallback', 9000)
+    expect(fn).toMatch(/pending\.restoredWithoutValue \|\| pending\.value\.length === 0/)
+    expect(fn).toMatch(/lost to a gateway restart/)
+    expect(fn).toMatch(/buildVaultSaveFailedInbound/)
+  })
+})
+
+// ─── Defect A part 3: removal on resolution ───────────────────────────────
+
+describe('resolution clears the durable store (Defect A)', () => {
+  it('vault access approve/deny remove from the store', () => {
+    // deny path
+    const deny = slice(GATEWAY, 'async function handleVaultRequestAccessCallback', 4000)
+    expect(deny).toMatch(/pendingCardStore\.remove\(stageId\)/)
+    // approve path (performVaultAccessApproval) removes on every terminal branch
+    const approve = slice(GATEWAY, 'async function performVaultAccessApproval', 9000)
+    expect(approve).toMatch(/pendingCardStore\.remove\(stageId\)/)
+  })
+
+  it('vault save resolution paths remove from the store', () => {
+    const fn = slice(GATEWAY, 'async function handleVaultRequestSaveCallback', 12000)
+    // discard / write-fail / success / passphrase-missing all clear the store.
+    const count = (fn.match(/pendingCardStore\.remove\(stageId\)/g) ?? []).length
+    expect(count).toBeGreaterThanOrEqual(3)
+  })
+
+  it('secret request provide/decline remove from the store', () => {
+    // capture (provide → value arrives) removes via armed.stageId
+    expect(GATEWAY).toMatch(/pendingCardStore\.remove\(armed\.stageId\)/)
+    const decline = slice(GATEWAY, 'async function handleSecretRequestCallback', 3000)
+    expect(decline).toMatch(/pendingCardStore\.remove\(stageId\)/)
+  })
+
+  it('mental model resolve removes from the store', () => {
+    const fn = slice(GATEWAY, 'async function handleMentalModelProposeCallback', 4000)
+    expect(fn).toMatch(/pendingCardStore\.remove\(stageId\)/)
+  })
+})
+
+// ─── Defect B: TTL expiry wakes the parked agent ──────────────────────────
+
+describe('TTL expiry wakes the parked agent (Defect B)', () => {
+  it('the periodic reaper runs the approval-card expiry sweep inside try/catch', () => {
+    const reaper = slice(GATEWAY, 'const pendingStateReaper = setInterval', 12000)
+    // The sweep call must be guarded like the sibling sweepStaleTurnActiveMarker:
+    // an escaped throw inside this setInterval callback reaches uncaughtException
+    // and takes the whole gateway down.
+    expect(reaper).toMatch(/try\s*\{\s*sweepExpiredApprovalCards\(now\)\s*\}\s*catch/)
+  })
+
+  it('sweepExpiredApprovalCards runs all four family sweeps', () => {
+    const fn = slice(GATEWAY, 'function sweepExpiredApprovalCards', 600)
+    expect(fn).toMatch(/sweepPendingVaultRequestAccesses\(now\)/)
+    expect(fn).toMatch(/sweepPendingVaultRequestSaves\(now\)/)
+    expect(fn).toMatch(/sweepPendingMentalModelProposes\(now\)/)
+    expect(fn).toMatch(/sweepSecretRequests\(now\)/)
+  })
+
+  it('each expire* helper routes through the guarded expirePendingCard core', () => {
+    for (const [fnName, builder] of [
+      ['function expireVaultAccessCard', 'buildVaultAccessTimeoutInbound'],
+      ['function expireVaultSaveCard', 'buildVaultSaveTimeoutInbound'],
+      ['function expireSecretRequestCard', 'buildSecretRequestTimeoutInbound'],
+      ['function expireMentalModelProposeCard', 'buildMentalModelProposeTimeoutInbound'],
+    ] as const) {
+      const fn = slice(GATEWAY, fnName, 2400)
+      // The pure core owns ordering + fault isolation (delete-before-deliver,
+      // recordMiss-before-deliver, guarded deliver) — pinned BEHAVIORALLY in
+      // pending-card-expiry.test.ts. Here we pin that the gateway routes each
+      // family through it with the right dependencies.
+      expect(fn, fnName).toMatch(/expirePendingCard\(\{/)
+      expect(fn, fnName).toMatch(new RegExp(builder))
+      // turn-safe injection gate
+      expect(fn, fnName).toMatch(/deliverResumeSyntheticOrBuffer\(/)
+      // re-offered when the operator returns
+      expect(fn, fnName).toMatch(/recordMissedApproval\(/)
+      // card edited to expired + store cleared
+      expect(fn, fnName).toMatch(/editCardExpired\(/)
+      expect(fn, fnName).toMatch(/pendingCardStore\.remove\(stageId\)/)
+    }
+  })
+
+  it('each family sweep is per-entry guarded via sweepExpiredEntries', () => {
+    for (const fnName of [
+      'function sweepPendingVaultRequestAccesses',
+      'function sweepPendingVaultRequestSaves',
+      'function sweepPendingMentalModelProposes',
+      'function sweepSecretRequests',
+    ]) {
+      const fn = slice(GATEWAY, fnName, 500)
+      expect(fn, fnName).toMatch(/sweepExpiredEntries\(/)
+    }
+  })
+
+  it('recordMissedApproval writes to the missed-approvals store (re-offer path)', () => {
+    const fn = slice(GATEWAY, 'function recordMissedApproval', 700)
+    expect(fn).toMatch(/missedApprovalsStore\.add\(/)
+    expect(fn).toMatch(/MISSED_APPROVAL_REOFFER_ENABLED/)
+  })
+})
+
+// ─── Copy-bug fix: derive the timeout window from the real TTL ─────────────
+
+describe('vault_request_access copy derives the window from the real TTL', () => {
+  it('no hard-coded "10 min" claim; uses VAULT_REQUEST_ACCESS_TTL_MS', () => {
+    const fn = slice(GATEWAY, 'async function executeVaultRequestAccess', 12000)
+    expect(fn).not.toMatch(/times out \(10 min\)/)
+    expect(fn).toMatch(/Math\.round\(VAULT_REQUEST_ACCESS_TTL_MS \/ 60000\)/)
+  })
+})

package/telegram-plugin/tests/pending-card-expiry.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Behavioral pins for the pure approval-card expiry core
+ * (gateway/pending-card-expiry.ts) — the ordering + fault-isolation contract
+ * the gateway's reaper relies on:
+ *
+ *   - single-shot: two reaper ticks fire exactly ONE synthetic per expired card
+ *     (delete-before-deliver, pinned behaviorally, not by regex),
+ *   - a throwing deliver (half-dead IPC socket) never loses the
+ *     missed-approvals re-offer and never escapes to the caller,
+ *   - one throwing expiry never skips the remaining entries in a sweep.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+import {
+  expirePendingCard,
+  sweepExpiredEntries,
+  type ExpireCardDeps,
+} from '../gateway/pending-card-expiry.js'
+
+const INBOUND: InboundMessage = {
+  type: 'inbound',
+  chatId: '1',
+  messageId: 1,
+  user: 'vault-broker',
+  userId: 0,
+  ts: 1,
+  text: 'timeout',
+}
+
+function makeDeps(overrides: Partial<ExpireCardDeps> = {}): ExpireCardDeps & {
+  calls: string[]
+} {
+  const calls: string[] = []
+  return {
+    calls,
+    remove: () => calls.push('remove'),
+    editCard: () => calls.push('editCard'),
+    buildInbound: () => {
+      calls.push('buildInbound')
+      return INBOUND
+    },
+    deliver: () => {
+      calls.push('deliver')
+      return true
+    },
+    recordMiss: () => calls.push('recordMiss'),
+    log: () => {},
+    ...overrides,
+  }
+}
+
+describe('expirePendingCard — ordering contract', () => {
+  it('runs remove FIRST, then editCard, then recordMiss BEFORE deliver', () => {
+    const deps = makeDeps()
+    const { delivered } = expirePendingCard(deps)
+    expect(delivered).toBe(true)
+    expect(deps.calls).toEqual(['remove', 'editCard', 'recordMiss', 'buildInbound', 'deliver'])
+  })
+
+  it('a throwing deliver returns delivered=false, never throws, and the re-offer is already recorded', () => {
+    const log = vi.fn()
+    const deps = makeDeps({
+      deliver: () => {
+        throw new Error('EPIPE: half-dead socket')
+      },
+      log,
+    })
+    const { delivered } = expirePendingCard(deps)
+    expect(delivered).toBe(false)
+    // recordMiss ran BEFORE the deliver attempt — the missed-approvals entry
+    // survives the failed wake (the operator's return re-offers it).
+    expect(deps.calls).toContain('recordMiss')
+    expect(deps.calls.indexOf('recordMiss')).toBeLessThan(deps.calls.indexOf('buildInbound'))
+    expect(log).toHaveBeenCalledWith(expect.stringContaining('delivery failed'))
+  })
+
+  it('a throwing editCard still records the miss and delivers the wake', () => {
+    const deps = makeDeps({
+      editCard: () => {
+        throw new Error('telegram edit failed')
+      },
+    })
+    const { delivered } = expirePendingCard(deps)
+    expect(delivered).toBe(true)
+    expect(deps.calls).toEqual(['remove', 'recordMiss', 'buildInbound', 'deliver'])
+  })
+
+  it('a throwing recordMiss still delivers the wake', () => {
+    const deps = makeDeps({
+      recordMiss: () => {
+        throw new Error('store write failed')
+      },
+    })
+    const { delivered } = expirePendingCard(deps)
+    expect(delivered).toBe(true)
+    expect(deps.calls).toContain('deliver')
+  })
+})
+
+describe('sweepExpiredEntries — single-shot across ticks', () => {
+  interface Entry {
+    staged_at: number
+  }
+  const TTL = 60_000
+
+  function makeSweepWorld() {
+    const map = new Map<string, Entry>()
+    const synthetics: string[] = []
+    const expire = (stageId: string, _v: Entry, _now: number) => {
+      // Mirrors the gateway wiring: expirePendingCard with remove-from-map
+      // FIRST and the synthetic recorded on deliver.
+      expirePendingCard({
+        remove: () => map.delete(stageId),
+        editCard: () => {},
+        buildInbound: () => INBOUND,
+        deliver: () => {
+          synthetics.push(stageId)
+          return true
+        },
+        recordMiss: () => {},
+        log: () => {},
+      })
+    }
+    const tick = (now: number) =>
+      sweepExpiredEntries(map, (v, n) => v.staged_at < n - TTL, expire, now, () => {})
+    return { map, synthetics, tick }
+  }
+
+  it('two reaper ticks fire exactly ONE synthetic per expired card', () => {
+    const { map, synthetics, tick } = makeSweepWorld()
+    map.set('s1', { staged_at: 0 })
+    map.set('s2', { staged_at: 0 })
+    map.set('fresh', { staged_at: 150_000 }) // still inside TTL at both ticks
+
+    tick(120_000) // both s1+s2 expired; fresh is not
+    tick(180_000) // second tick — expired entries are GONE from the map
+
+    expect(synthetics.sort()).toEqual(['s1', 's2'])
+    expect(map.has('fresh')).toBe(true)
+    expect(map.size).toBe(1)
+  })
+
+  it('delete-before-deliver: the map entry is gone by the time the synthetic fires', () => {
+    const map = new Map<string, Entry>()
+    map.set('s1', { staged_at: 0 })
+    let presentAtDeliver: boolean | null = null
+    sweepExpiredEntries(
+      map,
+      (v, n) => v.staged_at < n - TTL,
+      (stageId) => {
+        expirePendingCard({
+          remove: () => map.delete(stageId),
+          editCard: () => {},
+          buildInbound: () => INBOUND,
+          deliver: () => {
+            presentAtDeliver = map.has(stageId)
+            return true
+          },
+          recordMiss: () => {},
+          log: () => {},
+        })
+      },
+      120_000,
+      () => {},
+    )
+    expect(presentAtDeliver).toBe(false)
+  })
+
+  it('one throwing expiry does not skip the remaining entries', () => {
+    const map = new Map<string, Entry>()
+    map.set('boom', { staged_at: 0 })
+    map.set('ok', { staged_at: 0 })
+    const expired: string[] = []
+    const log = vi.fn()
+    sweepExpiredEntries(
+      map,
+      (v, n) => v.staged_at < n - TTL,
+      (stageId) => {
+        if (stageId === 'boom') throw new Error('dead socket at the worst layer')
+        map.delete(stageId)
+        expired.push(stageId)
+      },
+      120_000,
+      log,
+    )
+    expect(expired).toEqual(['ok'])
+    expect(log).toHaveBeenCalledWith(expect.stringContaining('boom'))
+  })
+})

package/telegram-plugin/tests/pending-card-store.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Durable store for the four AGENT-INITIATED approval-card families
+ * (vault_request_access / vault_request_save / request_secret /
+ * mental_model_propose). Mirrors permission-card-store.test.ts.
+ *
+ * The load-bearing extra invariant here (beyond plain persistence): NO SECRET
+ * VALUE ever lands on disk. The file is written unencrypted; a vault_request_save
+ * stages the secret value in gateway memory only, and this store must persist
+ * just its key/metadata. The "no value field" test is the regression guard for
+ * that hygiene rule.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import {
+  createPendingCardStore,
+  type PersistedApprovalCard,
+} from '../gateway/pending-card-store.js'
+
+function makeTmpDir() {
+  return mkdtempSync(join(tmpdir(), 'pending-card-store-test-'))
+}
+
+const ACCESS: PersistedApprovalCard = {
+  family: 'vault_request_access',
+  stageId: 'a1b2c3d4',
+  agent: 'gymbro',
+  chatId: '10001',
+  cardMessageId: 555,
+  key: 'fatsecret/credentials',
+  scope: 'read',
+  reason: 'needs the API for the daily log',
+  ttlSeconds: 30 * 86400,
+  stagedAt: 1_700_000_000_000,
+}
+
+const SAVE: PersistedApprovalCard = {
+  family: 'vault_request_save',
+  stageId: 'e5f6a7b8',
+  agent: 'marko',
+  chatId: '10002',
+  cardMessageId: 556,
+  key: 'brevo/api-key',
+  kind: 'string',
+  why: 'store the campaign key',
+  stagedAt: 1_700_000_000_000,
+}
+
+const SECRET: PersistedApprovalCard = {
+  family: 'request_secret',
+  stageId: 'c9d0e1f2',
+  agent: 'gymbro',
+  chatId: '10003',
+  cardMessageId: 557,
+  key: 'openai/token',
+  reason: 'the model call needs it',
+  stagedAt: 1_700_000_000_000,
+}
+
+const MMP: PersistedApprovalCard = {
+  family: 'mental_model_propose',
+  stageId: 'aabbccdd',
+  agent: 'gymbro',
+  chatId: '10004',
+  cardMessageId: 558,
+  spec: { name: 'training-plan-state', source_query: 'the user current training plan' },
+  stagedAt: 1_700_000_000_000,
+}
+
+describe('createPendingCardStore', () => {
+  let dir: string
+  beforeEach(() => { dir = makeTmpDir() })
+  afterEach(() => { rmSync(dir, { recursive: true, force: true }) })
+
+  it('starts empty', () => {
+    expect(createPendingCardStore(dir).loadAll()).toEqual([])
+  })
+
+  it('add + loadAll round-trips each family', () => {
+    const store = createPendingCardStore(dir)
+    store.add(ACCESS)
+    store.add(SAVE)
+    store.add(SECRET)
+    store.add(MMP)
+    const all = store.loadAll()
+    expect(all.length).toBe(4)
+    expect(new Set(all.map(e => e.family))).toEqual(
+      new Set(['vault_request_access', 'vault_request_save', 'request_secret', 'mental_model_propose']),
+    )
+  })
+
+  it('add is idempotent on stageId (replaces in place)', () => {
+    const store = createPendingCardStore(dir)
+    store.add(SAVE)
+    store.add({ ...SAVE, cardMessageId: 999 })
+    const all = store.loadAll()
+    expect(all.length).toBe(1)
+    expect((all[0] as { cardMessageId?: number }).cardMessageId).toBe(999)
+  })
+
+  it('remove drops only the matching stageId', () => {
+    const store = createPendingCardStore(dir)
+    store.add(ACCESS)
+    store.add(SAVE)
+    store.remove(ACCESS.stageId)
+    const all = store.loadAll()
+    expect(all.length).toBe(1)
+    expect(all[0].stageId).toBe(SAVE.stageId)
+  })
+
+  it('remove is idempotent when the entry is absent', () => {
+    const store = createPendingCardStore(dir)
+    expect(() => store.remove('nope')).not.toThrow()
+  })
+
+  it('clear empties the store', () => {
+    const store = createPendingCardStore(dir)
+    store.add(ACCESS)
+    store.clear()
+    expect(store.loadAll()).toEqual([])
+  })
+
+  it('survives re-instantiation (data persists across gateway restart)', () => {
+    createPendingCardStore(dir).add(ACCESS)
+    const all = createPendingCardStore(dir).loadAll()
+    expect(all.length).toBe(1)
+    expect(all[0].stageId).toBe(ACCESS.stageId)
+    // The restored access card carries everything a post-restart tap needs to
+    // mint the grant: agent, key, scope, ttl, chat, card message id.
+    const restored = all[0] as Extract<PersistedApprovalCard, { family: 'vault_request_access' }>
+    expect(restored.agent).toBe('gymbro')
+    expect(restored.key).toBe('fatsecret/credentials')
+    expect(restored.scope).toBe('read')
+    expect(restored.ttlSeconds).toBe(30 * 86400)
+    expect(restored.cardMessageId).toBe(555)
+  })
+
+  // ── Secrets hygiene — the whole reason this store persists metadata only ──
+  it('a vault_request_save record has NO `value` field (type + runtime)', () => {
+    // Type-level: PersistedVaultSaveCard has no `value` member, so this object
+    // literal wouldn't compile with one. Runtime-level: assert it's absent.
+    expect('value' in SAVE).toBe(false)
+  })
+
+  it('the on-disk JSON contains NO secret value for a saved card', () => {
+    const store = createPendingCardStore(dir)
+    // Simulate the gateway callsite: it builds the persisted record from the
+    // pending entry WITHOUT copying `value`. Even if a caller mistakenly spread
+    // a value in, the type wouldn't allow it — but assert the file is clean.
+    store.add(SAVE)
+    const raw = readFileSync(join(dir, 'pending-approval-cards.json'), 'utf-8')
+    const SECRET_SENTINEL = 'super-secret-brevo-value'
+    expect(raw).not.toContain(SECRET_SENTINEL)
+    expect(raw).not.toContain('"value"')
+    // The key/metadata we DO need is present.
+    expect(raw).toContain('brevo/api-key')
+    expect(raw).toContain('vault_request_save')
+  })
+
+  it('the file ends up 0600 even when it pre-existed with lax perms', () => {
+    // writeFileSync's `mode` only applies on CREATE — a pre-existing
+    // world-readable file would keep its perms without the explicit chmod
+    // the store does on every write.
+    const filePath = join(dir, 'pending-approval-cards.json')
+    writeFileSync(filePath, '[]', { mode: 0o644 })
+    const store = createPendingCardStore(dir)
+    store.add(ACCESS)
+    expect(statSync(filePath).mode & 0o777).toBe(0o600)
+    expect(createPendingCardStore(dir).loadAll().length).toBe(1)
+  })
+})