switchroom 0.12.26 → 0.12.27

package/telegram-plugin/gateway/gateway.ts

@@ -261,6 +261,7 @@ import { chatKey, chatKeyWithSuffix } from './chat-key.js'
 // effects.
 import { shadowEmit } from './inbound-delivery-machine-shadow.js'
 import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
+import { dispatchEffects, isDispatchEnabled } from './inbound-delivery-machine-dispatch.js'
 import {
   buildVaultGrantApprovedInbound,
   buildVaultGrantDeniedInbound,
@@ -3204,50 +3205,59 @@ const ipcServer: IpcServer = createIpcServer({
     // causing the shadow state to read `bridge_dead` even when the
     // real bridge was healthy, because every recall.py connect+disconnect
     // would flip the state.
-    if (client.agentName != null) {
-      shadowEmit({ kind: 'bridgeUp', at: Date.now() })
-    }
+    const bridgeUpEffects = client.agentName != null
+      ? shadowEmit({ kind: 'bridgeUp', at: Date.now() })
+      : []
     client.send({ type: 'status', status: 'agent_connected' })
 
-    // #1150: drain any synthetic inbounds queued for this agent while
-    // the bridge was offline. Done BEFORE the boot-card path below so
-    // the agent wakes up to its missed wake-ups first, even if the
-    // boot card edit happens to be slow. Skip drain when agentName is
-    // null (pre-handshake / anonymous client) — those clients are
-    // bridges that never registered an identity and can't have
-    // accumulated buffered inbounds keyed by name.
+    // Phase 2b PR 3a — bridgeUp cutover. The state machine's `bridgeUp`
+    // transition returns `redeliverPersistedPermVerdicts`, `drainBuffer`,
+    // and `logTrace` effects. The dispatcher executes them in order:
+    // the perm-verdict drain unblocks any claude turn suspended inside
+    // an MCP permission call; the inbound drain flushes synthetic
+    // inbounds queued while the bridge was offline (#1150) so the agent
+    // wakes up to missed wake-ups before the boot-card path below runs.
+    // Lossless: `redeliverBufferedInbound` re-buffers per-message misses
+    // and `spool.ack` tombstones confirmed deliveries. Skipped when
+    // agentName is null (pre-handshake / anonymous client — those
+    // bridges never registered an identity and can't have accumulated
+    // buffered inbounds keyed by name).
     if (client.agentName != null) {
-      const pending = pendingInboundBuffer.drain(client.agentName)
-      for (const msg of pending) {
-        try {
-          client.send(msg)
-          // Confirmed delivery to the just-registered live bridge →
-          // tombstone the durable spool entry so it isn't boot-replayed
-          // again. A throw below leaves it spooled (un-acked) so the
-          // idle-drain / escalation path still recovers it — strictly
-          // safer than the old log-and-drop.
-          inboundSpool?.ack(msg)
-        } catch (err) {
-          process.stderr.write(
-            `telegram gateway: pending-inbound drain failed agent=${client.agentName} ` +
-            `source=${msg.meta?.source ?? '-'}: ${(err as Error).message}\n`,
-          )
+      if (isDispatchEnabled()) {
+        dispatchEffects(bridgeUpEffects, {
+          selfAgent: client.agentName,
+          ipcServer,
+          pendingInboundBuffer,
+          inboundSpool: inboundSpool ?? null,
+          pendingPermissionBuffer,
+          client,
+        })
+      } else {
+        // Kill-switch fallback: imperative drain (parity with pre-cutover
+        // behavior). Kept for SWITCHROOM_DELIVERY_MACHINE_CUTOVER=0
+        // rollback safety; deleted in PR 4 once the cutover bakes.
+        const pending = pendingInboundBuffer.drain(client.agentName)
+        for (const msg of pending) {
+          try {
+            client.send(msg)
+            inboundSpool?.ack(msg)
+          } catch (err) {
+            process.stderr.write(
+              `telegram gateway: pending-inbound drain failed agent=${client.agentName} ` +
+              `source=${msg.meta?.source ?? '-'}: ${(err as Error).message}\n`,
+            )
+          }
         }
-      }
-      // PR-3: drain permission verdicts missed while the bridge was
-      // offline. A claude turn suspended inside the MCP permission call
-      // is unblocked the moment the reconnecting bridge relays the
-      // verdict; without this the verdict (incl. the TTL auto-deny) was
-      // lost and the turn stayed silent forever.
-      const pendingVerdicts = pendingPermissionBuffer.drain(client.agentName)
-      for (const ev of pendingVerdicts) {
-        try {
-          client.send(ev)
-        } catch (err) {
-          process.stderr.write(
-            `telegram gateway: pending-permission drain failed agent=${client.agentName} ` +
-            `request=${ev.requestId} behavior=${ev.behavior}: ${(err as Error).message}\n`,
-          )
+        const pendingVerdicts = pendingPermissionBuffer.drain(client.agentName)
+        for (const ev of pendingVerdicts) {
+          try {
+            client.send(ev)
+          } catch (err) {
+            process.stderr.write(
+              `telegram gateway: pending-permission drain failed agent=${client.agentName} ` +
+              `request=${ev.requestId} behavior=${ev.behavior}: ${(err as Error).message}\n`,
+            )
+          }
         }
       }
     }

package/telegram-plugin/gateway/inbound-delivery-machine-dispatch.ts

@@ -0,0 +1,188 @@
+/**
+ * InboundDeliveryStateMachine — DISPATCH (Phase 2b PR 3a, bridgeUp cutover).
+ *
+ * Per RFC `docs/rfcs/inbound-delivery-state-machine.md`, the state
+ * machine is pure: `transition(state, event) → { state', effects[] }`.
+ * The gateway's job is to (a) emit events at the right moments and
+ * (b) execute the returned effects against real I/O. This module owns
+ * step (b) for the cutover.
+ *
+ * Scope of THIS PR — bridgeUp only:
+ *   - drainBuffer                       → executed
+ *   - redeliverPersistedPermVerdicts    → executed
+ *   - logTrace                          → executed
+ *
+ * Other effects (deliverToBridge, bufferInbound, persistInbound,
+ * setTurnStarted, clearTurnStarted, noteOutbound, firePoke,
+ * deliverPermVerdict, persistPermVerdict) still flow through their
+ * existing imperative paths in `gateway.ts`. The dispatcher logs them
+ * as `not-yet-cutover` so a future PR can wire them without grep-and-
+ * pray. NEVER silently no-op: the trace is the gate.
+ *
+ * Kill switch: `SWITCHROOM_DELIVERY_MACHINE_CUTOVER=0` disables
+ * dispatcher execution and the gateway falls back to imperative-only.
+ * Default is ON — this PR is the cutover.
+ */
+
+import type {
+  Effect,
+  InboundMessage as MachineInboundMessage,
+} from './inbound-delivery-machine.js'
+import type { IpcServer, IpcClient } from './ipc-server.js'
+import type { InboundMessage } from './ipc-protocol.js'
+import type { PendingInboundBuffer } from './pending-inbound-buffer.js'
+import { redeliverBufferedInbound } from './pending-inbound-buffer.js'
+import type { InboundSpool } from './inbound-spool.js'
+import type { PendingPermissionBuffer } from './pending-permission-decisions.js'
+
+export interface DispatchCtx {
+  readonly selfAgent: string
+  readonly ipcServer: IpcServer
+  readonly pendingInboundBuffer: PendingInboundBuffer
+  readonly inboundSpool: InboundSpool | null
+  readonly pendingPermissionBuffer: PendingPermissionBuffer
+  /** Optional: when set, prefer sending direct to this client (bridgeUp path). */
+  readonly client?: IpcClient
+  /** Optional log sink — default stderr. Test hook. */
+  readonly log?: (line: string) => void
+}
+
+const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_CUTOVER !== '0'
+
+export function isDispatchEnabled(): boolean {
+  return enabled
+}
+
+/**
+ * Execute the effects returned by `transition()`. Pure imperative
+ * driver: side-effects only, no machine state held here.
+ *
+ * Effects are dispatched in the order returned by the machine. The
+ * machine guarantees a sensible order (e.g., `setTurnStarted` before
+ * `deliverToBridge` so a downstream observer sees the turn marker
+ * already up).
+ */
+export function dispatchEffects(effects: readonly Effect[], ctx: DispatchCtx): void {
+  if (!enabled) return
+  for (const effect of effects) {
+    dispatchOne(effect, ctx)
+  }
+}
+
+function dispatchOne(effect: Effect, ctx: DispatchCtx): void {
+  const log = ctx.log ?? ((line: string) => process.stderr.write(line))
+  switch (effect.kind) {
+    case 'drainBuffer': {
+      // The bridgeUp drain: flush any synthetic inbounds queued for
+      // this agent while the bridge was offline. Mirrors what
+      // onClientRegistered did inline pre-cutover (gateway.ts:3219-3236).
+      // Lossless: redeliverBufferedInbound re-buffers any per-message
+      // miss and tombstones the durable spool entry on confirmed
+      // delivery.
+      const send = (msg: InboundMessage): boolean => {
+        // Prefer the just-registered client when present (bridgeUp
+        // path) — that's a direct send. Fall back to ipcServer
+        // lookup for non-client-bound drains (turn-complete flush
+        // from a future PR).
+        if (ctx.client) {
+          try {
+            ctx.client.send(msg)
+            return true
+          } catch (err) {
+            log(
+              `telegram gateway: dispatch drainBuffer client.send threw agent=${ctx.selfAgent} ` +
+                `source=${msg.meta?.source ?? '-'}: ${(err as Error).message}\n`,
+            )
+            return false
+          }
+        }
+        return ctx.ipcServer.sendToAgent(ctx.selfAgent, msg)
+      }
+      const result = redeliverBufferedInbound(
+        ctx.pendingInboundBuffer,
+        ctx.selfAgent,
+        send,
+        ctx.inboundSpool ?? undefined,
+      )
+      if (result.drained > 0) {
+        log(
+          `telegram gateway: dispatch drainBuffer agent=${ctx.selfAgent} ` +
+            `drained=${result.drained} redelivered=${result.redelivered} ` +
+            `rebuffered=${result.rebuffered}\n`,
+        )
+      }
+      return
+    }
+
+    case 'redeliverPersistedPermVerdicts': {
+      // Drain permission verdicts missed while the bridge was offline.
+      // A claude turn suspended inside the MCP permission call is
+      // unblocked the moment the reconnecting bridge relays the
+      // verdict. Mirrors the pre-cutover loop at gateway.ts:3242-3252.
+      const pending = ctx.pendingPermissionBuffer.drain(ctx.selfAgent)
+      let delivered = 0
+      let failed = 0
+      for (const ev of pending) {
+        try {
+          if (ctx.client) {
+            ctx.client.send(ev)
+          } else {
+            ctx.ipcServer.sendToAgent(ctx.selfAgent, ev)
+          }
+          delivered++
+        } catch (err) {
+          failed++
+          log(
+            `telegram gateway: dispatch redeliverPerm send threw agent=${ctx.selfAgent} ` +
+              `request=${ev.requestId} behavior=${ev.behavior}: ${(err as Error).message}\n`,
+          )
+        }
+      }
+      if (pending.length > 0) {
+        log(
+          `telegram gateway: dispatch redeliverPerm agent=${ctx.selfAgent} ` +
+            `delivered=${delivered} failed=${failed}\n`,
+        )
+      }
+      return
+    }
+
+    case 'logTrace': {
+      const keyPart = effect.key ? ` key=${effect.key}` : ''
+      const metaPart = effect.metadata
+        ? ' ' + Object.entries(effect.metadata).map(([k, v]) => `${k}=${String(v)}`).join(' ')
+        : ''
+      log(`gw-trace dispatch stage=${effect.stage}${keyPart}${metaPart}\n`)
+      return
+    }
+
+    // The cases below are KNOWN effect kinds that this PR does NOT
+    // cut over. The imperative paths still run for them; the
+    // dispatcher logs the event so future cutover PRs can grep for
+    // exactly the call sites to migrate.
+    case 'deliverToBridge':
+    case 'bufferInbound':
+    case 'persistInbound':
+    case 'setTurnStarted':
+    case 'clearTurnStarted':
+    case 'noteOutbound':
+    case 'firePoke':
+    case 'deliverPermVerdict':
+    case 'persistPermVerdict': {
+      log(`gw-trace dispatch not-yet-cutover effect=${effect.kind}\n`)
+      return
+    }
+  }
+}
+
+/**
+ * Test hook: invoke the per-effect dispatcher directly so unit tests
+ * can drive individual effects against mocks without constructing a
+ * full effects array.
+ */
+export function __dispatchOneForTests(effect: Effect, ctx: DispatchCtx): void {
+  dispatchOne(effect, ctx)
+}
+
+/** Type re-export — convenience for test fixtures. */
+export type { MachineInboundMessage }

package/telegram-plugin/tests/inbound-delivery-machine-dispatch.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Unit tests for `inbound-delivery-machine-dispatch.ts`.
+ *
+ * Per RFC PR 3 cutover: the dispatcher executes effects against real
+ * primitives. These tests pin the contract per effect kind — which
+ * primitive gets called, with what args, exactly once. The gate that
+ * catches a double-drain regression at the imperative call sites.
+ *
+ * Scope of THIS file matches the PR's scope: bridgeUp's three effects
+ * (drainBuffer, redeliverPersistedPermVerdicts, logTrace) are wired
+ * and tested end-to-end. Other effect kinds are asserted to log a
+ * `not-yet-cutover` trace without throwing — those are the future
+ * cutover seam.
+ */
+
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import {
+  __dispatchOneForTests,
+  dispatchEffects,
+  isDispatchEnabled,
+} from '../gateway/inbound-delivery-machine-dispatch'
+import type { DispatchCtx } from '../gateway/inbound-delivery-machine-dispatch'
+import { createPendingInboundBuffer } from '../gateway/pending-inbound-buffer'
+import { createPendingPermissionBuffer } from '../gateway/pending-permission-decisions'
+import type { Effect } from '../gateway/inbound-delivery-machine'
+
+function makeCtx(overrides?: Partial<DispatchCtx>): {
+  ctx: DispatchCtx
+  logs: string[]
+  sendToAgent: ReturnType<typeof vi.fn>
+  clientSend: ReturnType<typeof vi.fn>
+  inbound: ReturnType<typeof createPendingInboundBuffer>
+  perm: ReturnType<typeof createPendingPermissionBuffer>
+} {
+  const logs: string[] = []
+  const sendToAgent = vi.fn(() => true)
+  const clientSend = vi.fn()
+  const inbound = createPendingInboundBuffer()
+  const perm = createPendingPermissionBuffer()
+  const ctx: DispatchCtx = {
+    selfAgent: 'test-agent',
+    ipcServer: { sendToAgent } as never,
+    pendingInboundBuffer: inbound,
+    inboundSpool: null,
+    pendingPermissionBuffer: perm,
+    client: { send: clientSend, agentName: 'test-agent', id: 'c1' } as never,
+    log: (line: string) => logs.push(line),
+    ...overrides,
+  }
+  return { ctx, logs, sendToAgent, clientSend, inbound, perm }
+}
+
+describe('isDispatchEnabled', () => {
+  it('defaults to true when the kill-switch env-var is unset', () => {
+    expect(isDispatchEnabled()).toBe(true)
+  })
+})
+
+describe('dispatchEffects — drainBuffer', () => {
+  it('redelivers buffered inbound to the registered client', () => {
+    const { ctx, clientSend, inbound } = makeCtx()
+    const msg1 = { type: 'inbound' as const, id: 'm1', chat_id: '1', text: 'hello', meta: { source: 'telegram' } }
+    const msg2 = { type: 'inbound' as const, id: 'm2', chat_id: '1', text: 'world', meta: { source: 'cron' } }
+    inbound.push('test-agent', msg1 as never)
+    inbound.push('test-agent', msg2 as never)
+    expect(inbound.depth('test-agent')).toBe(2)
+
+    dispatchEffects([{ kind: 'drainBuffer' }], ctx)
+
+    expect(clientSend).toHaveBeenCalledTimes(2)
+    expect(clientSend).toHaveBeenNthCalledWith(1, msg1)
+    expect(clientSend).toHaveBeenNthCalledWith(2, msg2)
+    expect(inbound.depth('test-agent')).toBe(0)
+  })
+
+  it('no-ops on empty buffer (no log, no send)', () => {
+    const { ctx, clientSend, logs, inbound } = makeCtx()
+    expect(inbound.depth('test-agent')).toBe(0)
+
+    dispatchEffects([{ kind: 'drainBuffer' }], ctx)
+
+    expect(clientSend).not.toHaveBeenCalled()
+    expect(logs.filter((l) => l.includes('drainBuffer'))).toHaveLength(0)
+  })
+
+  it('falls back to ipcServer.sendToAgent when no client is set', () => {
+    const { ctx, sendToAgent, clientSend, inbound } = makeCtx({ client: undefined })
+    const msg = { type: 'inbound' as const, id: 'm1', chat_id: '1', text: 'hi', meta: { source: 'cron' } }
+    inbound.push('test-agent', msg as never)
+
+    dispatchEffects([{ kind: 'drainBuffer' }], ctx)
+
+    expect(clientSend).not.toHaveBeenCalled()
+    expect(sendToAgent).toHaveBeenCalledTimes(1)
+    expect(sendToAgent).toHaveBeenCalledWith('test-agent', msg)
+  })
+})
+
+describe('dispatchEffects — redeliverPersistedPermVerdicts', () => {
+  it('drains pendingPermissionBuffer to the client', () => {
+    const { ctx, clientSend, perm } = makeCtx()
+    const v1 = {
+      type: 'permission_decision' as const,
+      requestId: 'r1',
+      behavior: 'allow' as const,
+      updatedInput: {},
+      timestamp: 0,
+    }
+    const v2 = {
+      type: 'permission_decision' as const,
+      requestId: 'r2',
+      behavior: 'deny' as const,
+      updatedInput: {},
+      timestamp: 0,
+    }
+    perm.push('test-agent', v1 as never)
+    perm.push('test-agent', v2 as never)
+
+    dispatchEffects([{ kind: 'redeliverPersistedPermVerdicts' }], ctx)
+
+    expect(clientSend).toHaveBeenCalledTimes(2)
+    expect(clientSend).toHaveBeenNthCalledWith(1, v1)
+    expect(clientSend).toHaveBeenNthCalledWith(2, v2)
+  })
+
+  it('no-ops on empty perm buffer', () => {
+    const { ctx, clientSend, logs } = makeCtx()
+    dispatchEffects([{ kind: 'redeliverPersistedPermVerdicts' }], ctx)
+    expect(clientSend).not.toHaveBeenCalled()
+    expect(logs.filter((l) => l.includes('redeliverPerm'))).toHaveLength(0)
+  })
+})
+
+describe('dispatchEffects — logTrace', () => {
+  it('writes a single grep-friendly line', () => {
+    const { ctx, logs } = makeCtx()
+    dispatchEffects(
+      [{ kind: 'logTrace', stage: 'bridge_recover', metadata: { foo: 'bar' } }],
+      ctx,
+    )
+    expect(logs).toHaveLength(1)
+    expect(logs[0]).toContain('gw-trace dispatch stage=bridge_recover')
+    expect(logs[0]).toContain('foo=bar')
+  })
+})
+
+describe('dispatchEffects — bridgeUp composite (all three effects in order)', () => {
+  it('drains perm verdicts THEN inbound buffer THEN logs', () => {
+    const { ctx, clientSend, inbound, perm, logs } = makeCtx()
+    const verdict = {
+      type: 'permission_decision' as const,
+      requestId: 'rA',
+      behavior: 'allow' as const,
+      updatedInput: {},
+      timestamp: 0,
+    }
+    const inMsg = { type: 'inbound' as const, id: 'mB', chat_id: '1', text: 't', meta: { source: 'cron' } }
+    perm.push('test-agent', verdict as never)
+    inbound.push('test-agent', inMsg as never)
+
+    // Effects in the order the machine returns them for bridgeUp.
+    dispatchEffects(
+      [
+        { kind: 'redeliverPersistedPermVerdicts' },
+        { kind: 'drainBuffer' },
+        { kind: 'logTrace', stage: 'bridge_recover' },
+      ],
+      ctx,
+    )
+
+    expect(clientSend).toHaveBeenCalledTimes(2)
+    expect(clientSend).toHaveBeenNthCalledWith(1, verdict)
+    expect(clientSend).toHaveBeenNthCalledWith(2, inMsg)
+    expect(logs.some((l) => l.includes('stage=bridge_recover'))).toBe(true)
+  })
+})
+
+describe('dispatchEffects — kill switch', () => {
+  // The kill switch is checked at module-load time so we can't toggle
+  // it inside the test process easily. We validate the contract that
+  // the helper exists and respects the env-var — see isDispatchEnabled.
+  it('exposes the kill-switch check', () => {
+    expect(typeof isDispatchEnabled()).toBe('boolean')
+  })
+})
+
+describe('dispatchOne — not-yet-cutover effects log without throwing', () => {
+  const notYet: Effect['kind'][] = [
+    'deliverToBridge',
+    'bufferInbound',
+    'persistInbound',
+    'setTurnStarted',
+    'clearTurnStarted',
+    'noteOutbound',
+    'firePoke',
+    'deliverPermVerdict',
+    'persistPermVerdict',
+  ]
+
+  for (const kind of notYet) {
+    it(`'${kind}' logs not-yet-cutover and does NOT touch primitives`, () => {
+      const { ctx, sendToAgent, clientSend, logs } = makeCtx()
+      // Construct a minimal valid effect for each kind. Most carry a
+      // payload that the dispatcher ignores in this PR.
+      const effect = synthesizeNotYetCutoverEffect(kind)
+      expect(() => __dispatchOneForTests(effect, ctx)).not.toThrow()
+      expect(sendToAgent).not.toHaveBeenCalled()
+      expect(clientSend).not.toHaveBeenCalled()
+      expect(logs.some((l) => l.includes(`not-yet-cutover effect=${kind}`))).toBe(true)
+    })
+  }
+})
+
+function synthesizeNotYetCutoverEffect(kind: Effect['kind']): Effect {
+  const k = 'c1:_' as never
+  const msg = { msgId: 1, isSteering: false, payload: null } as never
+  const verdict = { requestId: 'r', behavior: 'allow' as const, payload: null } as never
+  switch (kind) {
+    case 'deliverToBridge':
+      return { kind, key: k, msg }
+    case 'bufferInbound':
+      return { kind, key: k, msg }
+    case 'persistInbound':
+      return { kind, key: k, msg }
+    case 'setTurnStarted':
+      return { kind, key: k, at: 0 }
+    case 'clearTurnStarted':
+      return { kind, key: k }
+    case 'noteOutbound':
+      return { kind, key: k, at: 0 }
+    case 'firePoke':
+      return { kind, key: k, level: 'fallback' }
+    case 'deliverPermVerdict':
+      return { kind, verdict }
+    case 'persistPermVerdict':
+      return { kind, verdict }
+    default:
+      throw new Error(`unreachable: ${kind}`)
+  }
+}