switchroom 0.5.0

package/telegram-plugin/draft-transport.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared draft-transport helpers for answer-stream and draft-stream.
+ *
+ * Extracted from answer-stream.ts so both the narrative answer-lane and the
+ * model-driven stream_reply lane can share the same regex constants and
+ * fallback logic without duplicating them.
+ *
+ * answer-stream.ts re-exports these symbols so existing callers (including
+ * tests that import directly from answer-stream.ts) continue to work.
+ */
+
+// Error patterns matching OpenClaw's shouldFallbackFromDraftTransport.
+// Exported for tests.
+export const DRAFT_METHOD_UNAVAILABLE_RE =
+  /(unknown method|method .*not (found|available|supported)|unsupported)/i
+export const DRAFT_CHAT_UNSUPPORTED_RE = /(can't be used|can be used only)/i
+
+/**
+ * Returns true when a sendMessageDraft rejection means "this API is not
+ * available" rather than a transient network error.
+ */
+export function shouldFallbackFromDraftTransport(err: unknown): boolean {
+  const text =
+    typeof err === 'string'
+      ? err
+      : err instanceof Error
+        ? err.message
+        : typeof err === 'object' && err != null && 'description' in err
+          ? typeof (err as { description: unknown }).description === 'string'
+            ? (err as { description: string }).description
+            : ''
+          : ''
+  if (!/sendMessageDraft/i.test(text)) return false
+  return DRAFT_METHOD_UNAVAILABLE_RE.test(text) || DRAFT_CHAT_UNSUPPORTED_RE.test(text)
+}
+
+/**
+ * Symbol-keyed shared counter for draft-id allocation across concurrent
+ * streams (mirrors openclaw's getDraftStreamState). Using Symbol.for ensures
+ * the same counter is shared even if this module is loaded multiple times
+ * (e.g. from different bundle chunks).
+ */
+const DRAFT_STREAM_STATE_KEY = Symbol.for('switchroom.draftStreamState')
+
+interface DraftStreamState {
+  nextDraftId: number
+}
+
+function getDraftStreamState(): DraftStreamState {
+  const g = globalThis as Record<PropertyKey, unknown>
+  let state = g[DRAFT_STREAM_STATE_KEY] as DraftStreamState | undefined
+  if (!state) {
+    state = { nextDraftId: 0 }
+    g[DRAFT_STREAM_STATE_KEY] = state
+  }
+  return state
+}
+
+/**
+ * Allocate a unique draft ID, wrapping at 2_147_483_647 (Telegram's int32
+ * max for draft_id). IDs start at 1 and cycle.
+ */
+export function allocateDraftId(): number {
+  const state = getDraftStreamState()
+  state.nextDraftId = state.nextDraftId >= 2_147_483_647 ? 1 : state.nextDraftId + 1
+  return state.nextDraftId
+}
+
+/** Reset the shared draft-id counter — for tests only. */
+export function __resetDraftIdForTests(): void {
+  getDraftStreamState().nextDraftId = 0
+}

package/telegram-plugin/first-paint.ts

@@ -0,0 +1,246 @@
+/**
+ * First-paint seam (Phase 1 of #545).
+ *
+ * Pure function extracted from gateway.ts `handleInbound` for the
+ * status-reaction + progress-card-startTurn slice. Production behavior is
+ * unchanged: gateway.ts calls this with its module-level singletons. The
+ * seam exists so the waiting-UX harness can drive the real first-paint
+ * code path with fakes and assert wall-clock call timing of
+ *   - bot.api.setMessageReaction (the 👀 ack)
+ *   - progressDriver.startTurn (the progress card)
+ *
+ * Scope is deliberately narrow:
+ *   - status-reaction setup (cancel-prior + setQueued, or 🤝/👀 for
+ *     steer/queued mid-turn)
+ *   - progressDriver.startTurn for fresh turns
+ * Out of scope (stays inline in gateway.ts):
+ *   - draft pre-allocation, forum-topic placeholder, heartbeat scheduling
+ *
+ * The motivation for the narrow scope: pre-alloc/heartbeat code touches
+ * 6 more module-scoped maps + functions and would balloon this seam
+ * without making F2/F3 (no instant draft / late card) any more testable
+ * — those are about the FIRST visible signal (👀 + card.startTurn).
+ */
+
+import type { ReactionTypeEmoji } from 'grammy/types'
+import { StatusReactionController } from './status-reactions.js'
+import type { DraftStreamHandle } from './draft-stream.js'
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface FirstPaintBotApi {
+  setMessageReaction(
+    chatId: string | number,
+    messageId: number,
+    reactions: Array<{ type: 'emoji'; emoji: ReactionTypeEmoji['emoji'] }>,
+  ): Promise<unknown>
+}
+
+export interface FirstPaintProgressDriver {
+  startTurn(args: {
+    chatId: string
+    threadId?: string
+    userText: string
+    replyToMessageId?: number
+  }): void
+}
+
+export interface FirstPaintAccess {
+  /** When false, all status-reaction posting is suppressed. */
+  statusReactions?: boolean
+  /** Optional alternate ack emoji used when statusReactions is suppressed. */
+  ackReaction?: string
+}
+
+export interface FirstPaintCtx {
+  chatId: string
+  messageId: number | undefined
+  messageThreadId: number | undefined
+  isSteerPrefix: boolean
+  effectiveText: string
+  /** ms epoch — used for the inbound_ack metric delta. */
+  inboundReceivedAt: number
+  access: FirstPaintAccess
+}
+
+export interface FirstPaintDeps {
+  bot: { api: FirstPaintBotApi }
+  progressDriver: FirstPaintProgressDriver | undefined
+  activeStatusReactions: Map<string, StatusReactionController>
+  activeReactionMsgIds: Map<string, { chatId: string; messageId: number }>
+  activeTurnStartedAt: Map<string, number>
+  progressUpdateTurnCount: Map<string, number>
+  activeDraftStreams: Map<string, DraftStreamHandle>
+  activeDraftParseModes: Map<string, 'HTML' | 'MarkdownV2' | undefined>
+  suppressPtyPreview: Set<string>
+  /** Compute the status/stream key. Production uses `${chatId}:${threadId ?? '_'}`. */
+  statusKey: (chatId: string, threadId?: number) => string
+  streamKey: (chatId: string, threadId?: number) => string
+  /** Wipes activeReactionMsgIds + activeTurnStartedAt for the key. */
+  purgeReactionTracking: (key: string) => void
+  /** Records signal emission (issue #203 metrics). */
+  signalTracker: {
+    noteSignal: (key: string, ts: number) => void
+    reset: (key: string, ts: number) => void
+  }
+  /** Side-channel for active-reactions disk persistence. */
+  resolveAgentDirFromEnv: () => string | null | undefined
+  addActiveReaction: (
+    agentDir: string,
+    entry: { chatId: string; messageId: number; threadId: number | null; reactedAt: number },
+  ) => void
+  /** Streaming-metrics emitter (#203). */
+  logStreamingEvent: (ev: { kind: 'inbound_ack'; chatId: string; messageId: number; ackDelayMs: number }) => void
+  /** Clock — defaults to Date.now in production; tests inject fake. */
+  now?: () => number
+  /**
+   * Factory for the per-turn StatusReactionController. Defaults to constructing
+   * a real `StatusReactionController(cb)`. Tests inject a recording stub so
+   * the harness can decouple from the real controller's internal scheduling.
+   */
+  controllerFactory?: (cb: (emoji: string) => Promise<void>) => StatusReactionController
+  /**
+   * #542 fix: per-chat allowed-reactions filter sourced from getChat probe.
+   * Optional — when omitted, the controller is constructed without a filter
+   * (current behavior, possibly buggy if the chat restricts reactions).
+   * The default `controllerFactory` consults this getter; custom factories
+   * (e.g. test harnesses) may ignore it.
+   */
+  getAllowedReactions?: (chatId: string) => Set<string> | null
+  /**
+   * Sink for stderr-style error reporting from the seam. Defaults to writing
+   * to `process.stderr`. Tests inject a recorder.
+   */
+  logError?: (msg: string) => void
+}
+
+export interface FirstPaintResult {
+  isSteering: boolean
+  priorTurnStartedAt: number | undefined
+}
+
+// ─── Seam ────────────────────────────────────────────────────────────────
+
+/**
+ * Run the first-paint slice for an inbound user message. Mirrors lines
+ * 3973-4072 of gateway.ts as of `waiting-ux-harness` head. Returns the
+ * `isSteering` and `priorTurnStartedAt` signals the caller needs to gate
+ * downstream pre-alloc behavior.
+ *
+ * Behavior is identical to inline production:
+ *   - missing msgId → nothing happens (no reaction, no card)
+ *   - prior turn in flight + steer prefix → 🤝 on inbound, no new turn
+ *   - prior turn in flight (queued mid-turn) → 👀 on inbound, no new turn
+ *   - fresh turn → cancel any stale controller, start a new one, setQueued,
+ *     reset signal tracker, persist active-reaction to disk, then
+ *     progressDriver.startTurn
+ *   - access.statusReactions === false + access.ackReaction → custom ack
+ *     emoji on inbound; no controller; no startTurn
+ */
+export async function firstPaintTurn(
+  deps: FirstPaintDeps,
+  ctx: FirstPaintCtx,
+): Promise<FirstPaintResult> {
+  const now = deps.now ?? Date.now
+  const { chatId, messageId: msgId, messageThreadId, isSteerPrefix, effectiveText, inboundReceivedAt, access } = ctx
+
+  let isSteering = false
+  let priorTurnStartedAt: number | undefined
+
+  if (msgId != null) {
+    const key = deps.statusKey(chatId, messageThreadId)
+    const priorActive = deps.activeStatusReactions.get(key)
+    const priorTurnInFlight = priorActive != null
+    isSteering = priorTurnInFlight && isSteerPrefix
+    if (priorTurnInFlight) priorTurnStartedAt = deps.activeTurnStartedAt.get(key)
+
+    if (access.statusReactions !== false) {
+      if (isSteering) {
+        void deps.bot.api
+          .setMessageReaction(chatId, msgId, [{ type: 'emoji', emoji: '🤝' as ReactionTypeEmoji['emoji'] }])
+          .catch(() => {})
+      } else if (priorTurnInFlight) {
+        void deps.bot.api
+          .setMessageReaction(chatId, msgId, [{ type: 'emoji', emoji: '👀' as ReactionTypeEmoji['emoji'] }])
+          .catch(() => {})
+        deps.logStreamingEvent({
+          kind: 'inbound_ack',
+          chatId,
+          messageId: msgId,
+          ackDelayMs: now() - inboundReceivedAt,
+        })
+      } else {
+        // Fresh turn — `priorTurnInFlight` is false here, so `priorActive`
+        // is provably undefined (priorTurnInFlight = priorActive != null).
+        // The earlier `if (priorActive)` block was dead code; removed.
+        const sKey = deps.streamKey(chatId, messageThreadId)
+        const priorStream = deps.activeDraftStreams.get(sKey)
+        if (priorStream && !priorStream.isFinal()) {
+          deps.activeDraftStreams.delete(sKey)
+          deps.activeDraftParseModes.delete(sKey)
+          await priorStream.finalize().catch(() => {})
+        }
+        deps.suppressPtyPreview.delete(sKey)
+
+        const allowed = deps.getAllowedReactions?.(chatId) ?? null
+        const makeCtrl = deps.controllerFactory ?? ((cb) => new StatusReactionController(cb, allowed))
+        const ctrl = makeCtrl(async (emoji) => {
+          await deps.bot.api.setMessageReaction(chatId, msgId, [
+            { type: 'emoji', emoji: emoji as ReactionTypeEmoji['emoji'] },
+          ])
+          deps.signalTracker.noteSignal(key, now())
+        })
+        deps.activeStatusReactions.set(key, ctrl)
+        deps.activeReactionMsgIds.set(key, { chatId, messageId: msgId })
+        deps.activeTurnStartedAt.set(key, now())
+        deps.progressUpdateTurnCount.set(key, 0)
+        ctrl.setQueued()
+        deps.logStreamingEvent({
+          kind: 'inbound_ack',
+          chatId,
+          messageId: msgId,
+          ackDelayMs: now() - inboundReceivedAt,
+        })
+        deps.signalTracker.reset(deps.statusKey(chatId, messageThreadId), now())
+        const agentDir = deps.resolveAgentDirFromEnv()
+        if (agentDir != null) {
+          deps.addActiveReaction(agentDir, {
+            chatId,
+            messageId: msgId,
+            threadId: messageThreadId ?? null,
+            reactedAt: now(),
+          })
+        }
+      }
+    } else if (access.ackReaction) {
+      void deps.bot.api
+        .setMessageReaction(chatId, msgId, [
+          { type: 'emoji', emoji: access.ackReaction as ReactionTypeEmoji['emoji'] },
+        ])
+        .catch(() => {})
+      deps.logStreamingEvent({
+        kind: 'inbound_ack',
+        chatId,
+        messageId: msgId,
+        ackDelayMs: now() - inboundReceivedAt,
+      })
+    }
+  }
+
+  // Start a new progress card only for fresh turns (no prior turn in flight).
+  if (!isSteering && priorTurnStartedAt == null) {
+    try {
+      deps.progressDriver?.startTurn({
+        chatId,
+        threadId: messageThreadId != null ? String(messageThreadId) : undefined,
+        userText: effectiveText,
+        replyToMessageId: msgId != null ? msgId : undefined,
+      })
+    } catch (err) {
+      const log = deps.logError ?? ((m: string) => process.stderr.write(m))
+      log(`telegram gateway: progress-card startTurn failed: ${(err as Error).message}\n`)
+    }
+  }
+
+  return { isSteering, priorTurnStartedAt }
+}

package/telegram-plugin/fleet-state.ts

@@ -0,0 +1,246 @@
+/**
+ * P0 of #662 — fleet state struct + pure transition functions.
+ *
+ * `FleetMember` is the per-sub-agent unit the v2 two-zone status card
+ * (P1) will render. This module is pure data plumbing: the driver
+ * shadows a `Map<agentId, FleetMember>` alongside the legacy
+ * `chatState.subAgents` map and updates it through the reducers below
+ * at the same sites the legacy map is mutated. No render code, no
+ * timers, no globals — clocks and IDs are caller-supplied so tests can
+ * drive deterministic transitions.
+ *
+ * Status derivation (verified in #662): `session-tail.ts:101` defines
+ * `sub_agent_turn_end` as `{kind, agentId}` with NO terminal-status
+ * field, so failure must be derived: any `sub_agent_tool_result` with
+ * `isError=true` accumulates into `errorSeen`, and `applyTurnEnd` flips
+ * `status` to `failed` if any error was seen, else `done`.
+ */
+
+const ROLE_FALLBACK_LEN = 20
+const SANITISE_MAX_LEN = 120
+
+export type FleetStatus = 'running' | 'background' | 'done' | 'failed' | 'stuck' | 'killed' | 'capped'
+
+export interface FleetMember {
+  agentId: string
+  /** Display label: description / subagentType / first-prompt slice / 'agent'. */
+  role: string
+  /** ms epoch when this member was registered (driver snapshot of `now()`). */
+  startedAt: number
+  toolCount: number
+  /** ms epoch of the most recent tool_use / tool_result for this member. */
+  lastActivityAt: number
+  /** Most recent tool call observed (name + sanitised arg for display). */
+  lastTool: { name: string; sanitisedArg: string } | null
+  status: FleetStatus
+  /** ms epoch when status became terminal (done/failed/killed); null otherwise. */
+  terminalAt: number | null
+  /** True if any sub_agent_tool_result with isError=true has been observed. */
+  errorSeen: boolean
+  /** Snapshot of driver's currentTurnKey at sub_agent_started. Stable across turns. */
+  originatingTurnKey: string
+}
+
+export interface CreateFleetMemberArgs {
+  agentId: string
+  role: string
+  startedAt: number
+  originatingTurnKey: string
+}
+
+export function createFleetMember(args: CreateFleetMemberArgs): FleetMember {
+  return {
+    agentId: args.agentId,
+    role: args.role,
+    startedAt: args.startedAt,
+    toolCount: 0,
+    lastActivityAt: args.startedAt,
+    lastTool: null,
+    status: 'running',
+    terminalAt: null,
+    errorSeen: false,
+    originatingTurnKey: args.originatingTurnKey,
+  }
+}
+
+export function applyToolUse(
+  member: FleetMember,
+  toolName: string,
+  input: Record<string, unknown> | undefined,
+  now: number,
+): FleetMember {
+  // P3 of #662 — recovery from stuck. A live tool event proves the
+  // sub-agent is alive again, so flip status back to running. Terminal
+  // statuses (done/failed/killed) are sticky and never reset here.
+  const status: FleetStatus = member.status === 'stuck' ? 'running' : member.status
+  return {
+    ...member,
+    status,
+    toolCount: member.toolCount + 1,
+    lastActivityAt: now,
+    lastTool: { name: toolName, sanitisedArg: sanitiseToolArg(toolName, input ?? {}) },
+  }
+}
+
+export function applyToolResult(member: FleetMember, isError: boolean | undefined): FleetMember {
+  if (!isError) return member
+  if (member.errorSeen) return member
+  return { ...member, errorSeen: true }
+}
+
+export function applyTurnEnd(member: FleetMember, now: number): FleetMember {
+  // Idempotent — if already terminal, do nothing.
+  if (member.terminalAt != null) return member
+  return {
+    ...member,
+    status: member.errorSeen ? 'failed' : 'done',
+    terminalAt: now,
+    lastActivityAt: now,
+  }
+}
+
+/**
+ * Transition a fleet member to `capped` terminal state.
+ *
+ * Called when session-tail detects a truncated sub-agent transcript:
+ * >= CAP_TOOL_USE_THRESHOLD tool_uses recorded with no `type:result` /
+ * `subtype:end` / `type:final` terminal record. The sub-agent was killed
+ * mid-flight (parent restart, watchdog SIGTERM, etc.) before it could
+ * write its completion record. Idempotent — already-terminal members
+ * are left unchanged.
+ */
+export function applyCapped(member: FleetMember, now: number): FleetMember {
+  if (member.terminalAt != null) return member
+  return {
+    ...member,
+    status: 'capped',
+    terminalAt: now,
+    lastActivityAt: now,
+  }
+}
+
+export function markStuck(member: FleetMember, now: number, idleMs: number = 60_000): FleetMember {
+  if (member.status !== 'running') return member
+  if (now - member.lastActivityAt < idleMs) return member
+  return { ...member, status: 'stuck' }
+}
+
+/**
+ * P2 of #662 / fixes #64 — true if any fleet member is in
+ * `status: 'background'` AND has not yet reached terminal state. Used by
+ * the driver's dispose path to keep a PerChatState alive past parent
+ * turn_end while background sub-agents are still running, and by the v2
+ * renderer's phase resolver to choose ⏸ Background vs ✅ Done.
+ */
+export function hasLiveBackground(fleet: ReadonlyMap<string, FleetMember>): boolean {
+  for (const m of fleet.values()) {
+    if (m.status === 'background' && m.terminalAt == null) return true
+  }
+  return false
+}
+
+export function cap(
+  members: readonly FleetMember[],
+  n: number = 5,
+): { visible: FleetMember[]; hidden: number } {
+  const sorted = [...members].sort((a, b) => b.lastActivityAt - a.lastActivityAt)
+  if (sorted.length <= n) return { visible: sorted, hidden: 0 }
+  return { visible: sorted.slice(0, n), hidden: sorted.length - n }
+}
+
+/**
+ * Sanitise a tool input for display on the fleet row.
+ *
+ * - Path-bearing tools (Read/Edit/Write/NotebookEdit) → basename only,
+ *   so absolute paths under `/etc/secrets/` etc. don't leak into the
+ *   pinned card.
+ * - Bash/command-bearing tools → the command, but with bearer-token-
+ *   shaped substrings replaced with `[redacted]`.
+ * - Anything else → empty string. Renderer falls back to tool name only.
+ *
+ * Hard-capped at 120 chars; the fleet row is one line and Telegram caps
+ * the whole card at ~4096 bytes.
+ */
+export function sanitiseToolArg(name: string, raw: Record<string, unknown>): string {
+  let out = ''
+  switch (name) {
+    case 'Read':
+    case 'Edit':
+    case 'Write':
+    case 'NotebookEdit': {
+      const fp = raw.file_path
+      if (typeof fp === 'string' && fp.length > 0) out = basename(fp)
+      break
+    }
+    case 'Bash': {
+      const cmd = raw.command
+      if (typeof cmd === 'string') out = redactSecrets(cmd)
+      break
+    }
+    case 'Grep':
+    case 'Glob': {
+      const pat = raw.pattern
+      if (typeof pat === 'string') out = pat
+      break
+    }
+    case 'WebFetch':
+    case 'WebSearch': {
+      const url = raw.url ?? raw.query
+      if (typeof url === 'string') out = redactSecrets(url)
+      break
+    }
+    default: {
+      // Generic best-effort: the first string-valued field.
+      for (const v of Object.values(raw)) {
+        if (typeof v === 'string' && v.length > 0) {
+          out = redactSecrets(v)
+          break
+        }
+      }
+    }
+  }
+  if (out.length > SANITISE_MAX_LEN) out = out.slice(0, SANITISE_MAX_LEN - 1) + '…'
+  return out
+}
+
+function basename(p: string): string {
+  const idx = p.lastIndexOf('/')
+  return idx === -1 ? p : p.slice(idx + 1)
+}
+
+// Bearer / sk-/secret-shaped tokens (>= 16 chars of base64-ish run). The pattern
+// is intentionally conservative — we'd rather miss a token than blow away
+// legitimate command text. The renderer's job is to be readable; secret
+// scanning lives elsewhere.
+const SECRET_PATTERNS: ReadonlyArray<RegExp> = [
+  /Bearer\s+[A-Za-z0-9._\-+/=]{16,}/g,
+  /sk-[A-Za-z0-9_\-]{16,}/g,
+  /\b[A-Fa-f0-9]{32,}\b/g, // long hex (e.g. API keys)
+]
+
+function redactSecrets(text: string): string {
+  let out = text
+  for (const re of SECRET_PATTERNS) out = out.replace(re, '[redacted]')
+  return out
+}
+
+/**
+ * Resolve the fleet-row label for a freshly-dispatched sub-agent.
+ *
+ * Fallback chain (per #662 P0 spec): description → subagentType →
+ * first 20 chars of firstPromptText → "agent". `description` comes
+ * from the parent's Agent/Task tool_use input; `subagentType` is
+ * Claude Code's slot label (e.g. "general-purpose"); the prompt slice
+ * is the last-resort handle for ad-hoc dispatches that omit both.
+ */
+export function roleFromDispatch(
+  description: string | undefined,
+  subagentType: string | undefined,
+  firstPromptText: string,
+): string {
+  if (description != null && description.trim().length > 0) return description.trim()
+  if (subagentType != null && subagentType.trim().length > 0) return subagentType.trim()
+  const slice = firstPromptText.slice(0, ROLE_FALLBACK_LEN).trim()
+  if (slice.length > 0) return firstPromptText.slice(0, ROLE_FALLBACK_LEN)
+  return 'agent'
+}