switchroom 0.5.0

package/telegram-plugin/two-zone-card.ts

@@ -0,0 +1,249 @@
+/**
+ * P1 of #662 — `renderTwoZoneCard` pure renderer.
+ *
+ * Two-zone status card: PARENT bullets + FLEET rows. Replaces the v1
+ * expandable-blockquote-per-sub-agent layout (still live behind the
+ * default codepath; gated on `TWO_ZONE_CARD=1` for now).
+ *
+ * Pure: no IO, no globals, no clock except the caller-supplied `now`.
+ * All sanitisation happens upstream in `fleet-state.ts`; this module
+ * only formats already-sanitised values.
+ *
+ * Spec: `reference/status-card-design.md` (PR #661).
+ */
+
+import type { FleetMember, FleetStatus } from './fleet-state.js'
+import { cap } from './fleet-state.js'
+import type { ProgressCardState, RenderOptions, TaskNum } from './progress-card.js'
+import { escapeHtml, formatDuration } from './card-format.js'
+
+const PARENT_BULLET_CAP = 8
+const FLEET_ROW_CAP = 5
+const STUCK_IDLE_MS = 60_000
+
+export interface TwoZoneCardInput {
+  state: ProgressCardState
+  fleet: ReadonlyMap<string, FleetMember>
+  now: number
+  taskNum?: TaskNum
+  opts?: RenderOptions
+}
+
+export interface PhaseResolution {
+  icon: string
+  label: string
+}
+
+// ─── Public entry point ─────────────────────────────────────────────────────
+
+export function renderTwoZoneCard(input: TwoZoneCardInput): string {
+  const { state, fleet, now, opts } = input
+  if (state.turnStartedAt === 0) {
+    return '⏳ Waiting…'
+  }
+  const phase = phaseFor(state, fleet, now, opts as Record<string, unknown> | undefined)
+  const elapsedMs = Math.max(0, now - state.turnStartedAt)
+  const totalTools = countTotalTools(state, fleet)
+  const subCount = fleet.size
+  const lines: string[] = []
+  lines.push(renderHeader(phase, elapsedMs, totalTools, subCount, input.taskNum))
+  const parentZone = renderParentZone(state)
+  if (parentZone) {
+    lines.push('')
+    lines.push(parentZone)
+  }
+  const fleetZone = renderFleetZone(fleet, now)
+  if (fleetZone) {
+    lines.push('')
+    lines.push(fleetZone)
+  }
+  return lines.join('\n')
+}
+
+// ─── Phase resolver ─────────────────────────────────────────────────────────
+
+/**
+ * Maps (parent state, fleet, opts) to a single header phase. Truth
+ * table from `reference/status-card-design.md` §Header. Precedence:
+ * forced-close > silent-end (gated on parent terminal) > stalled >
+ * background > done > working.
+ *
+ * SilentEnd is lifted ABOVE the background/done checks so that a fleet
+ * still running can't suppress the silent-end label once the parent has
+ * terminated without a reply. It IS gated on `parentDone || stage===done`
+ * to prevent firing prematurely while the parent is still in flight.
+ */
+export function phaseFor(
+  state: ProgressCardState,
+  fleet: ReadonlyMap<string, FleetMember>,
+  now: number,
+  opts?: Record<string, unknown>,
+): PhaseResolution {
+  const stalledClose = opts?.stalledClose === true
+  const silentEnd = opts?.silentEnd === true
+  const parentDone = opts?.parentDone === true || state.stage === 'done'
+
+  if (stalledClose) return { icon: '⚠', label: 'Forced close' }
+
+  const fleetRunning = anyFleetActive(fleet)
+  const fleetAllStuck = fleet.size > 0 && [...fleet.values()].filter((m) => m.status === 'running' || m.status === 'stuck').every((m) => isStuck(m, now))
+
+  // SilentEnd: parent terminated without a reply. Lifted above the
+  // background/done branches so a still-running fleet can't mask it,
+  // but gated on parentDone so we don't fire while parent is in flight.
+  if (silentEnd && parentDone) {
+    return { icon: '🙊', label: 'Ended without reply' }
+  }
+
+  // Stalled: every running-or-stuck member is past the idle threshold.
+  // Members already terminal (done/failed) are excluded from this check —
+  // a fleet of [done, stuck] still surfaces as Stalled because the only
+  // member that could still make progress is no longer doing so.
+  if (fleet.size > 0 && fleetAllStuck && !parentDone) {
+    return { icon: '⚠', label: 'Stalled' }
+  }
+
+  // Background: parentDone but at least one fleet member still running
+  if (parentDone && fleetRunning) {
+    return { icon: '⏸', label: 'Background' }
+  }
+
+  // Done: parent terminal + no fleet still running
+  if (parentDone && !fleetRunning) {
+    return { icon: '✅', label: 'Done' }
+  }
+
+  // Default: active work
+  return { icon: '⚙️', label: 'Working…' }
+}
+
+function anyFleetActive(fleet: ReadonlyMap<string, FleetMember>): boolean {
+  for (const m of fleet.values()) {
+    if (m.status === 'running' || m.status === 'background' || m.status === 'stuck') return true
+  }
+  return false
+}
+
+function isStuck(m: FleetMember, now: number): boolean {
+  if (m.status === 'stuck') return true
+  return m.status === 'running' && now - m.lastActivityAt > STUCK_IDLE_MS
+}
+
+// ─── Header ─────────────────────────────────────────────────────────────────
+
+function renderHeader(
+  phase: PhaseResolution,
+  elapsedMs: number,
+  totalTools: number,
+  subCount: number,
+  taskNum?: TaskNum,
+): string {
+  const tools = totalTools >= 100 ? '99+' : String(totalTools)
+  const elapsed = formatDuration(elapsedMs)
+  const parts = [`${phase.icon} <b>${escapeHtml(phase.label)}</b>`, `⏱ ${elapsed}`, `🔧 ${tools}`]
+  if (subCount > 0) parts.push(`🤖 ${subCount}`)
+  if (taskNum && taskNum.total > 1) parts.push(`#${taskNum.index}/${taskNum.total}`)
+  return parts.join(' · ')
+}
+
+// ─── Parent zone ────────────────────────────────────────────────────────────
+
+function renderParentZone(state: ProgressCardState): string {
+  const items = state.items
+  if (items.length === 0) return ''
+  const lines: string[] = ['<b>PARENT</b>']
+  const visible = items.slice(-PARENT_BULLET_CAP)
+  const earlier = items.length - visible.length
+  if (earlier > 0) lines.push(`(+${earlier} earlier)`)
+  const inFlight = state.stage !== 'done'
+  const lastIdx = visible.length - 1
+  for (let i = 0; i < visible.length; i++) {
+    const it = visible[i]
+    const tool = escapeHtml(it.tool || '')
+    const label = it.label ? ` <code>${escapeHtml(truncate(it.label, 80))}</code>` : ''
+    if (inFlight && i === lastIdx) {
+      lines.push(`◉ <b>${tool}</b>${label}`)
+    } else {
+      lines.push(`● ${tool}${label}`)
+    }
+  }
+  return lines.join('\n')
+}
+
+// ─── Fleet zone ─────────────────────────────────────────────────────────────
+
+export function renderFleetZone(fleet: ReadonlyMap<string, FleetMember>, now: number): string {
+  if (fleet.size === 0) return ''
+  const all = [...fleet.values()]
+  const { visible, hidden } = cap(all, FLEET_ROW_CAP)
+  const lines: string[] = [`<b>FLEET (${fleet.size})</b>`]
+  for (const m of visible) lines.push(renderFleetRow(m, now))
+  if (hidden > 0) lines.push(`+ ${hidden} more`)
+  return lines.join('\n')
+}
+
+export function renderFleetRow(m: FleetMember, now: number): string {
+  const glyph = glyphForFleetStatus(m.status)
+  const role = escapeHtml(truncate(m.role || 'agent', 30))
+  const id6 = escapeHtml(m.agentId.slice(0, 6))
+  const tools = `${m.toolCount}t`
+  const activity = formatLastActivity(m, now)
+  return `${glyph} ${role} <code>${id6}</code> · ${tools} · ${activity}`
+}
+
+export function formatLastActivity(m: FleetMember, now: number): string {
+  // Terminal states show "<status> <relative-time>"
+  if (m.terminalAt != null) {
+    const age = formatRelativeTime(Math.max(0, now - m.terminalAt))
+    return `${escapeHtml(m.status)} ${age}`
+  }
+  // Stuck — show idle duration
+  if (m.status === 'stuck') {
+    const idle = formatRelativeTime(Math.max(0, now - m.lastActivityAt))
+    return `idle ${idle}`
+  }
+  // Running — show last tool + age
+  if (m.lastTool == null) {
+    const age = formatRelativeTime(Math.max(0, now - m.lastActivityAt))
+    return `started ${age}`
+  }
+  const age = formatRelativeTime(Math.max(0, now - m.lastActivityAt))
+  const arg = m.lastTool.sanitisedArg
+    ? ` <code>${escapeHtml(truncate(m.lastTool.sanitisedArg, 60))}</code>`
+    : ''
+  return `${escapeHtml(m.lastTool.name)}${arg} (${age})`
+}
+
+export function glyphForFleetStatus(status: FleetStatus): string {
+  switch (status) {
+    case 'running': return '↻'
+    case 'background': return '⏸'
+    case 'done': return '✓'
+    case 'failed': return '✗'
+    case 'stuck': return '⚠'
+    case 'killed': return '✗'
+    case 'capped': return '⚠'
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+export function formatRelativeTime(ms: number): string {
+  const s = Math.floor(ms / 1000)
+  if (s < 60) return `${s}s ago`
+  const m = Math.floor(s / 60)
+  const r = s % 60
+  if (r === 0) return `${m}m ago`
+  return `${m}m${r}s ago`
+}
+
+function truncate(s: string, n: number): string {
+  if (s.length <= n) return s
+  return s.slice(0, n - 1) + '…'
+}
+
+function countTotalTools(state: ProgressCardState, fleet: ReadonlyMap<string, FleetMember>): number {
+  let n = state.items.length
+  for (const m of fleet.values()) n += m.toolCount
+  return n
+}

package/telegram-plugin/typing-wrap.ts

@@ -0,0 +1,92 @@
+// Auto-wrap tool dispatch with a Telegram typing-indicator loop so the user
+// sees a live "agent is working" signal during the 3–30s gap where the
+// progress card is deliberately suppressed (its initialDelayMs is 3s).
+// The first tool call on a given chat fires the typing loop immediately so
+// there's no silent dead window before the progress card appears. Subsequent
+// calls on the same chat honour the debounce to avoid churn.
+// Surface tools own their own loop — see isSurfaceTool.
+
+export interface TypingWrapperDeps {
+  startTypingLoop: (chatId: string) => void
+  stopTypingLoop: (chatId: string) => void
+  isSurfaceTool: (toolName: string) => boolean
+  debounceMs?: number
+}
+
+export interface TypingWrapper {
+  onToolUse: (toolUseId: string, chatId: string, toolName: string) => void
+  onToolResult: (toolUseId: string) => void
+  drainAll: () => void
+}
+
+interface Entry {
+  chatId: string
+  timer: ReturnType<typeof setTimeout>
+  started: boolean
+}
+
+export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
+  const debounceMs = deps.debounceMs ?? 500
+  const pending = new Map<string, Entry>()
+  // Track chats that already have an active typing loop so the first
+  // tool call fires immediately while subsequent calls use the debounce.
+  const activeChats = new Set<string>()
+
+  return {
+    onToolUse(toolUseId, chatId, toolName) {
+      if (!toolUseId) return
+      if (deps.isSurfaceTool(toolName)) return
+      // Replace any pre-existing entry for the same id defensively.
+      const prior = pending.get(toolUseId)
+      if (prior) {
+        clearTimeout(prior.timer)
+        if (prior.started) deps.stopTypingLoop(prior.chatId)
+        pending.delete(toolUseId)
+      }
+      // First tool on this chat: fire immediately rather than waiting for
+      // the debounce — this closes the silent dead window before the first
+      // progress card appears.
+      if (!activeChats.has(chatId)) {
+        deps.startTypingLoop(chatId)
+        activeChats.add(chatId)
+        const entry: Entry = {
+          chatId,
+          started: true,
+          timer: setTimeout(() => {}, 0), // no-op sentinel
+        }
+        pending.set(toolUseId, entry)
+        return
+      }
+      const entry: Entry = {
+        chatId,
+        started: false,
+        timer: setTimeout(() => {
+          deps.startTypingLoop(chatId)
+          entry.started = true
+        }, debounceMs),
+      }
+      pending.set(toolUseId, entry)
+    },
+
+    onToolResult(toolUseId) {
+      if (!toolUseId) return
+      const entry = pending.get(toolUseId)
+      if (!entry) return
+      clearTimeout(entry.timer)
+      if (entry.started) {
+        deps.stopTypingLoop(entry.chatId)
+        activeChats.delete(entry.chatId)
+      }
+      pending.delete(toolUseId)
+    },
+
+    drainAll() {
+      for (const entry of pending.values()) {
+        clearTimeout(entry.timer)
+        if (entry.started) deps.stopTypingLoop(entry.chatId)
+      }
+      pending.clear()
+      activeChats.clear()
+    },
+  }
+}

package/telegram-plugin/voice-transcribe.ts

@@ -0,0 +1,166 @@
+/**
+ * Voice-message transcription via OpenAI Whisper (#578 spike).
+ *
+ * Closes the inbound side of `talk-to-agents-from-anywhere`'s
+ * voice path. The user sends a voice message from their phone; the
+ * gateway:
+ *   1. Downloads the audio bytes from Telegram.
+ *   2. POSTs them to OpenAI's Whisper API.
+ *   3. Surfaces the transcript as the user's inbound text — same
+ *      pipeline a typed message goes through.
+ *
+ * Spike scope (#578): OpenAI provider only. The
+ * Groq/Deepgram/local-whisper-cli fallback chain is a follow-up;
+ * we want to validate the UX before committing to a multi-provider
+ * abstraction.
+ *
+ * Pure helper module — runs the API call but takes API key + audio
+ * bytes as args. No env reads, no file I/O. Unit-testable against a
+ * mocked fetch; the gateway-side wiring is the impure part.
+ */
+
+const OPENAI_TRANSCRIBE_URL = 'https://api.openai.com/v1/audio/transcriptions'
+
+export interface TranscribeResult {
+  ok: true
+  text: string
+  /** Provider-reported language (e.g. 'en'). Useful for telemetry +
+   *  for the agent to know whether to reply in the same language. */
+  language?: string
+  /** Wall-clock duration of the API call. Operator-facing telemetry. */
+  durationMs: number
+  /** Approximate audio length the provider transcribed, in seconds.
+   *  null when the provider doesn't include it in the response shape. */
+  audioSeconds: number | null
+}
+
+export interface TranscribeError {
+  ok: false
+  /** One of:
+   *   - 'no-api-key'           — config / vault missing
+   *   - 'audio-too-large'      — exceeds OpenAI's 25MB limit
+   *   - 'audio-too-short'      — shorter than 0.1s, Whisper rejects
+   *   - 'http-<n>'             — non-2xx HTTP status code
+   *   - 'fetch-failed'         — network error before getting any response
+   *   - 'malformed-response'   — 200 but body wasn't the expected JSON
+   *   - 'timeout'              — exceeded the operator-set timeout */
+  reason: string
+  /** Body (truncated) for operator stderr logs only. NEVER returned to
+   *  the user — error messages may leak token-shaped strings. */
+  detail?: string
+}
+
+export type TranscribeOutcome = TranscribeResult | TranscribeError
+
+export interface TranscribeArgs {
+  apiKey: string
+  audio: Uint8Array
+  /** Filename hint for the multipart body. Whisper uses the extension
+   *  to pick a decoder ('voice.ogg', 'audio.mp3', etc). Pass an
+   *  extension matching the actual content. */
+  filename: string
+  /** Optional: ISO-639-1 language hint to skip detection. */
+  language?: string
+  /** Per-call timeout in ms. Default 30s — Whisper is fast, but a
+   *  60s voice memo on a slow link can run long. */
+  timeoutMs?: number
+  /** Override fetch for tests. */
+  fetchImpl?: typeof fetch
+}
+
+/** OpenAI Whisper accepts up to 25 MB. Reject before the round-trip. */
+export const OPENAI_WHISPER_MAX_BYTES = 25 * 1024 * 1024
+
+/**
+ * Run a single transcription. Resolves to a TranscribeOutcome — the
+ * caller branches on `.ok`. Never throws (every error becomes a
+ * structured `{ ok: false, reason, detail }`).
+ */
+export async function transcribeViaWhisper(
+  args: TranscribeArgs,
+): Promise<TranscribeOutcome> {
+  if (!args.apiKey || args.apiKey.length === 0) {
+    return { ok: false, reason: 'no-api-key' }
+  }
+  if (args.audio.length === 0) {
+    return { ok: false, reason: 'audio-too-short' }
+  }
+  if (args.audio.length > OPENAI_WHISPER_MAX_BYTES) {
+    return {
+      ok: false,
+      reason: 'audio-too-large',
+      detail: `${args.audio.length} bytes (limit ${OPENAI_WHISPER_MAX_BYTES})`,
+    }
+  }
+
+  const fetchFn = args.fetchImpl ?? fetch
+  const timeoutMs = args.timeoutMs ?? 30_000
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+
+  // Multipart body. OpenAI's API requires `model` and `file`; we
+  // include `response_format=verbose_json` to get language back.
+  const form = new FormData()
+  // Bun's FormData accepts Blob via globalThis.Blob; Node 22+ same.
+  // Construct the Blob from the Uint8Array.
+  const blob = new Blob([args.audio as unknown as BlobPart])
+  form.append('file', blob, args.filename)
+  form.append('model', 'whisper-1')
+  form.append('response_format', 'verbose_json')
+  if (args.language) form.append('language', args.language)
+
+  const startedAt = Date.now()
+  let res: Response
+  try {
+    res = await fetchFn(OPENAI_TRANSCRIBE_URL, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${args.apiKey}` },
+      body: form,
+      signal: controller.signal,
+    })
+  } catch (err) {
+    clearTimeout(timer)
+    const msg = err instanceof Error ? err.message : String(err)
+    if (msg.includes('aborted') || /timeout/i.test(msg)) {
+      return { ok: false, reason: 'timeout', detail: msg }
+    }
+    return { ok: false, reason: 'fetch-failed', detail: msg }
+  }
+  clearTimeout(timer)
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    return {
+      ok: false,
+      reason: `http-${res.status}`,
+      detail: body.slice(0, 200),
+    }
+  }
+
+  let parsed: { text?: unknown; language?: unknown; duration?: unknown }
+  try {
+    parsed = await res.json() as typeof parsed
+  } catch (err) {
+    return {
+      ok: false,
+      reason: 'malformed-response',
+      detail: err instanceof Error ? err.message : String(err),
+    }
+  }
+
+  if (typeof parsed.text !== 'string') {
+    return {
+      ok: false,
+      reason: 'malformed-response',
+      detail: 'response missing `text` field',
+    }
+  }
+
+  return {
+    ok: true,
+    text: parsed.text,
+    language: typeof parsed.language === 'string' ? parsed.language : undefined,
+    durationMs: Date.now() - startedAt,
+    audioSeconds: typeof parsed.duration === 'number' ? parsed.duration : null,
+  }
+}