switchroom 0.18.31 → 0.18.33

package/telegram-plugin/gateway/bot-commands-model-effort.ts

@@ -0,0 +1,209 @@
+/**
+ * `/model` and `/effort` slash commands extracted verbatim from gateway.ts
+ * (switchroom#2996 P6 bot.command drain).
+ *
+ * Pure-logic helpers (parse/plan/menu/handle from model-command.ts,
+ * effort-command.ts, pending-session-command.ts) are imported directly;
+ * every gateway-local surface (busy resolver, deps factories, reply/queue
+ * plumbing, history recording) is injected via `deps` (repo factory-deps
+ * precedent, same shape as registerOpsInfoCommands). `bot` is injected so
+ * grammy registration order is preserved at the original call site.
+ */
+
+import type { Bot, Context, InlineKeyboard } from 'grammy'
+import { richMessage } from '../rich-send.js'
+import { hardenCardBreaks } from '../format.js'
+import { escapeHtmlForTg } from '../shared/bot-runtime.js'
+import {
+  parseModelCommand,
+  planModelCommand,
+  buildModelMenu,
+  handleModelCommand,
+  modelCommandReceiptLine,
+  type ModelMenuDeps,
+  type ModelCommandDeps,
+  type ModelMenuReply,
+  type ParsedModelCommand,
+} from './model-command.js'
+import {
+  parseEffortCommand,
+  handleEffortCommand,
+  buildEffortMenu,
+  type EffortCommandDeps,
+  type EffortMenuReply,
+} from './effort-command.js'
+import {
+  ackText as pendingCmdAckText,
+  type PendingSessionCommand,
+} from './pending-session-command.js'
+
+export interface ModelEffortCommandDeps {
+  isAuthorizedSender: (ctx: Context) => boolean
+  getMyAgentName: () => string
+  resolveThreadId: (chat_id: string, explicit?: string | number | null) => number | undefined
+  /** Stale-aware busy resolver (#3262) shared by /model and /effort. */
+  resolveModelEffortBusy: () => { currentTurnActive: boolean; turnInFlight: boolean }
+  historyEnabled: boolean
+  recordInbound: (args: {
+    chat_id: string
+    thread_id: number | null
+    message_id: number
+    user: string | null
+    user_id: string | null
+    ts: number
+    text: string
+  }) => void
+  buildModelDeps: (restartCtx?: { chatId: string; threadId: number | undefined }) => ModelMenuDeps & ModelCommandDeps
+  buildEffortDeps: () => EffortCommandDeps
+  modelMenuReplyMarkup: (reply: ModelMenuReply) => InlineKeyboard | undefined
+  effortMenuReplyMarkup: (reply: EffortMenuReply) => InlineKeyboard | undefined
+  enqueueSessionCommand: (cmd: PendingSessionCommand) => void
+  switchroomReply: (
+    ctx: Context,
+    text: string,
+    options?: { html?: boolean; reply_markup?: InlineKeyboard },
+  ) => Promise<void>
+  modelMenuEnabled: () => boolean
+  /** stderr log sink. */
+  log: (line: string) => void
+}
+
+export function registerModelEffortCommands(bot: Bot, deps: ModelEffortCommandDeps): void {
+  const {
+    isAuthorizedSender,
+    getMyAgentName,
+    resolveThreadId,
+    resolveModelEffortBusy,
+    historyEnabled,
+    recordInbound,
+    buildModelDeps,
+    buildEffortDeps,
+    modelMenuReplyMarkup,
+    effortMenuReplyMarkup,
+    enqueueSessionCommand,
+    switchroomReply,
+    modelMenuEnabled,
+    log,
+  } = deps
+
+  bot.command('model', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    const text = ctx.message?.text ?? ctx.channelPost?.text ?? ''
+    const parsed: ParsedModelCommand = parseModelCommand(text) ?? { kind: 'show' as const }
+    const chatId = String(ctx.chat!.id)
+    const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
+    // #3177 — durable receipt FIRST. A typed /model must NEVER be invisible: even
+    // if every downstream reply is shed/dropped, or the session is in a
+    // phantom-idle window (turn atom cleared while claude is still busy), the
+    // command leaves a greppable log line + a history row before any branch. This
+    // is the fix for the finn 2026-07-12 zero-trace swallow (no log, no reply, no
+    // ack, no deferred apply). `busyNow` folds BOTH busy signals (turn atom AND
+    // the authoritative delivery-machine/approval gate) — but a STALE atom or a
+    // wedged approval older than the hard TTL is discounted as idle (#3262), so a
+    // phantom "active turn" on an idle session no longer blocks the switch. Resolve
+    // once (it may clear a dangling atom) and reuse for both the receipt log and
+    // the routing disposition.
+    const modelBusy = resolveModelEffortBusy()
+    const busyNow = modelBusy.currentTurnActive || modelBusy.turnInFlight
+    log(modelCommandReceiptLine(getMyAgentName(), parsed, busyNow) + '\n')
+    if (historyEnabled && ctx.message?.message_id != null) {
+      try {
+        recordInbound({
+          chat_id: chatId,
+          thread_id: threadId ?? null,
+          message_id: ctx.message.message_id,
+          user: ctx.from?.username ?? (ctx.from?.id != null ? String(ctx.from.id) : null),
+          user_id: ctx.from?.id != null ? String(ctx.from.id) : null,
+          ts: ctx.message.date ?? Math.floor(Date.now() / 1000),
+          text,
+        })
+      } catch (err) {
+        log(`telegram gateway: /model recordInbound failed: ${(err as Error)?.message ?? String(err)}\n`)
+      }
+    }
+    const cmdDeps = buildModelDeps({ chatId, threadId })
+    // Route on a pure disposition (#3177) that folds BOTH busy signals so a
+    // session busy by EITHER measure ack+queues instead of silently injecting
+    // into a busy pane. Every branch below produces a visible action.
+    const disposition = planModelCommand(parsed, {
+      currentTurnActive: modelBusy.currentTurnActive,
+      turnInFlight: modelBusy.turnInFlight,
+      menuEnabled: modelMenuEnabled(),
+    })
+    if (disposition.kind === 'menu') {
+      const menu = await buildModelMenu(cmdDeps)
+      await switchroomReply(ctx, menu.text, { html: true, reply_markup: modelMenuReplyMarkup(menu) })
+      return
+    }
+    // Mid-turn (by either busy signal): instead of dead-ending ("Try again in a
+    // moment") or silently injecting into a busy pane, ACK + QUEUE + apply-on-idle
+    // + confirm (#3017/#3177). The typed set path either injects into claude's
+    // input box or triggers a carrier restart — both unsafe while busy.
+    if (disposition.kind === 'queue') {
+      const target = disposition.target
+      const sent = await ctx.replyWithRichMessage(
+        richMessage(hardenCardBreaks(pendingCmdAckText('model', target, escapeHtmlForTg))),
+        threadId != null ? { message_thread_id: threadId } : {},
+      )
+      enqueueSessionCommand({
+        kind: 'model',
+        origin: 'typed',
+        arg: target,
+        targetLabel: target,
+        chatId,
+        threadId,
+        ackChatId: chatId,
+        ackMessageId: (sent as { message_id: number }).message_id,
+        requestedAt: Date.now(),
+      })
+      return
+    }
+    // Rev 5: the handler relaunches through the carrier and owns every side effect
+    // (override write, carrier, premium-recovery clear). There is no post-hoc
+    // recording — /status is reconciled at boot from `.active-session-model`, so
+    // an unapplied switch can never be optimistically recorded here.
+    const reply = await handleModelCommand(parsed, cmdDeps)
+    await switchroomReply(ctx, reply.text, { html: reply.html })
+  })
+  bot.command('effort', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    const text = ctx.message?.text ?? ctx.channelPost?.text ?? ''
+    const parsed = parseEffortCommand(text) ?? { kind: 'show' as const }
+    const cmdDeps = buildEffortDeps()
+    if (parsed.kind === 'show') {
+      const menu = buildEffortMenu(cmdDeps)
+      await switchroomReply(ctx, menu.text, { html: true, reply_markup: effortMenuReplyMarkup(menu) })
+      return
+    }
+    // Mid-turn: ACK + QUEUE + apply-on-idle + confirm (#3017) — parity with
+    // /model. `applyEffort` mid-turn silently maybe-failed ("couldn't confirm it
+    // applied") before this gate existed. Use the SAME stale-aware busy resolver
+    // as /model (#3262) so a dangling turn atom older than the hard TTL is
+    // discounted as idle and the switch applies instead of queuing forever on an
+    // idle session.
+    const effortBusy = resolveModelEffortBusy()
+    if ((parsed.kind === 'set' || parsed.kind === 'default') && effortBusy.currentTurnActive) {
+      const requestedLevel = parsed.kind === 'set' ? parsed.level : 'default'
+      const chatId = String(ctx.chat!.id)
+      const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
+      const sent = await ctx.replyWithRichMessage(
+        richMessage(hardenCardBreaks(pendingCmdAckText('effort', requestedLevel, escapeHtmlForTg))),
+        threadId != null ? { message_thread_id: threadId } : {},
+      )
+      enqueueSessionCommand({
+        kind: 'effort',
+        origin: 'typed',
+        arg: requestedLevel,
+        targetLabel: requestedLevel,
+        chatId,
+        threadId,
+        ackChatId: chatId,
+        ackMessageId: (sent as { message_id: number }).message_id,
+        requestedAt: Date.now(),
+      })
+      return
+    }
+    const reply = await handleEffortCommand(parsed, cmdDeps)
+    await switchroomReply(ctx, reply.text, { html: reply.html })
+  })
+}

package/telegram-plugin/gateway/bot-commands-start-info.ts

@@ -0,0 +1,108 @@
+/**
+ * Basic info slash commands extracted verbatim from gateway.ts
+ * (switchroom#2996 P6 bot.command drain): `/start`, `/help`, `/status`,
+ * `/agents`.
+ *
+ * Pure read-only info surfaces (welcome/help text, pairing status, agent
+ * list) with no send-path or turn-lifecycle coupling. Every gateway-local
+ * helper they close over is passed in via `deps` (repo factory-deps
+ * precedent, same shape as registerOpsInfoCommands) so the module never
+ * back-references the gateway singleton. `bot` is injected so grammy
+ * registration order is preserved at the original call site.
+ */
+
+import type { Bot, Context } from 'grammy'
+import { richMessage } from '../rich-send.js'
+import {
+  startText as buildStartText,
+  helpText as buildHelpText,
+  statusPairedText as buildStatusPairedText,
+  statusPendingText as buildStatusPendingText,
+  statusUnpairedText as buildStatusUnpairedText,
+  type AgentMetadata,
+} from '../welcome-text.js'
+import { escapeHtmlForTg } from '../shared/bot-runtime.js'
+import type { Access } from './gateway.js'
+
+export interface StartInfoCommandDeps {
+  /** #894 backport gate: silent drop on disabled / non-allowlisted senders. */
+  dmCommandGate: (ctx: Context) => { access: Access; senderId: string } | null
+  isAuthorizedSender: (ctx: Context) => boolean
+  getMyAgentName: () => string
+  getCommandArgs: (ctx: Context) => string
+  hasDemoFlag: (args: string) => boolean
+  buildAgentMetadata: (agentName: string) => Promise<AgentMetadata>
+  runSwitchroomCommandFormatted: (
+    ctx: Context,
+    args: string[],
+    label: string,
+    formatter: () => string | null,
+  ) => Promise<void>
+  switchroomExecJson: <T = unknown>(args: string[]) => T | null
+  statusIcon: (status: string) => string
+}
+
+export function registerStartInfoCommands(bot: Bot, deps: StartInfoCommandDeps): void {
+  const {
+    dmCommandGate,
+    isAuthorizedSender,
+    getMyAgentName,
+    getCommandArgs,
+    hasDemoFlag,
+    buildAgentMetadata,
+    runSwitchroomCommandFormatted,
+    switchroomExecJson,
+    statusIcon,
+  } = deps
+
+  bot.command('start', async ctx => {
+    // dmCommandGate (#894 backport): silent drop on disabled or
+    // non-allowlisted senders so the bot doesn't leak its existence.
+    const gated = dmCommandGate(ctx)
+    if (!gated) return
+    const disabled = gated.access.dmPolicy === 'disabled'
+    await ctx.replyWithRichMessage(richMessage(buildStartText(getMyAgentName(), disabled)))
+  })
+  bot.command('help', async ctx => {
+    if (!dmCommandGate(ctx)) return
+    await ctx.replyWithRichMessage(richMessage(buildHelpText(getMyAgentName())))
+  })
+  bot.command('status', async ctx => {
+    // dmCommandGate (#894 backport) drops disabled / non-allowlisted in
+    // allowlist mode. Pairing-mode users still fall through to either
+    // the pending-code branch or the unpaired branch.
+    const gated = dmCommandGate(ctx)
+    if (!gated) return
+    const { access, senderId } = gated
+    const from = ctx.from!
+    if (access.allowFrom.includes(senderId)) {
+      const demo = hasDemoFlag(getCommandArgs(ctx))
+      const userTag = from.username ? `@${from.username}` : senderId
+      const meta = await buildAgentMetadata(getMyAgentName())
+      await ctx.replyWithRichMessage(richMessage(buildStatusPairedText({ user: userTag, meta, demo })))
+      return
+    }
+    for (const [code, p] of Object.entries(access.pending)) {
+      if (p.senderId === senderId) {
+        await ctx.replyWithRichMessage(richMessage(buildStatusPendingText(code)))
+        return
+      }
+    }
+    await ctx.reply(buildStatusUnpairedText())
+  })
+  bot.command('agents', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    await runSwitchroomCommandFormatted(ctx, ['agent', 'list'], 'agent list', () => {
+      type AgentListResp = { agents: Array<{ name: string; status: string; uptime: string; template: string; topic_name: string; topic_emoji?: string }> }
+      const data = switchroomExecJson<AgentListResp>(['agent', 'list'])
+      if (!data) return null
+      if (data.agents.length === 0) return '_No agents defined_'
+      const lines = ['**Agents**']
+      for (const a of data.agents) {
+        lines.push(`${statusIcon(a.status)} **${escapeHtmlForTg(a.name)}** · ${escapeHtmlForTg(a.status)} · ${escapeHtmlForTg(a.uptime)}`)
+        lines.push(`    _${escapeHtmlForTg(a.template)} → ${escapeHtmlForTg(a.topic_name)}${a.topic_emoji ? ' ' + a.topic_emoji : ''}_`)
+      }
+      return lines.join('\n')
+    })
+  })
+}

package/telegram-plugin/gateway/callback-query-handlers.ts

@@ -226,6 +226,38 @@ export interface PendingVaultRequestSave {
   restoredWithoutValue?: boolean
 }
 
+/**
+ * #2045 `request_secret` — agent asks the operator to PROVIDE a secret it does
+ * NOT have. No `value` is staged (unlike PendingVaultRequestSave): the value
+ * arrives via secure capture (the operator's next message after they tap
+ * [Provide securely]). Only request metadata lives here — nothing sensitive.
+ */
+export interface PendingSecretRequest {
+  agent: string
+  chat_id: string
+  key: string
+  reason?: string
+  staged_at: number
+  card_message_id?: number
+  /** Supergroup forum topic the agent was working in — carried into the
+   *  provide/decline/fail outcome inbounds so the resumed reply lands back
+   *  in that topic, not General. */
+  threadId?: number
+}
+
+/**
+ * The armed capture for a `request_secret` card: after [Provide securely] is
+ * tapped, the operator's NEXT message in `chat_id` is the value for `key`.
+ * Transient post-tap window (never persisted).
+ */
+export interface ArmedSecretCapture {
+  key: string
+  agent: string
+  stageId: string
+  armed_at: number
+  threadId?: number
+}
+
 /**
  * Issue #1012 — agent-initiated vault ACL request. The agent calls
  * `vault_request_access` when it hits VAULT-BROKER-DENIED (or
@@ -367,6 +399,10 @@ export interface CallbackQueryHandlersDeps {
   // Pending-state stores (consolidated surfaces from #3008/#3011).
   pendingVaultRequestAccesses: SweepableCardStore<PendingVaultRequestAccess>
   pendingVaultRequestSaves: SweepableCardStore<PendingVaultRequestSave>
+  /** Agent-initiated `request_secret` cards awaiting an operator tap (`vsp:`). */
+  pendingSecretRequests: SweepableCardStore<PendingSecretRequest>
+  /** Post-[Provide securely] armed captures, keyed by chat_id. */
+  armedSecretCaptures: SweepableStore<ArmedSecretCapture>
   pendingMentalModelProposes: SweepableCardStore<PendingMentalModelPropose>
   pendingCardStore: { remove(stageId: string): void }
   pendingMentalModelCorrelations: SweepableStore<{
@@ -431,6 +467,8 @@ export function createCallbackQueryHandlers(deps: CallbackQueryHandlersDeps) {
     swallowingApiCall,
     pendingVaultRequestAccesses,
     pendingVaultRequestSaves,
+    pendingSecretRequests,
+    armedSecretCaptures,
     pendingMentalModelProposes,
     pendingCardStore,
     pendingMentalModelCorrelations,
@@ -1676,6 +1714,91 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
   await ctx.answerCallbackQuery({ text: 'Unknown action' }).catch(() => {})
 }
 
+/**
+ * `vsp:` callbacks — agent-requested-secret card (#2045).
+ *   vsp:provide:<stageId>  — arm capture: operator's next message is the value
+ *   vsp:decline:<stageId>  — drop the request; tell the agent it was declined
+ *
+ * Extracted verbatim from gateway.ts (#2996 P5) — behavior-preserving. The
+ * `pendingSecretRequests` / `armedSecretCaptures` stores are the SAME singleton
+ * instances gateway.ts constructs (injected via deps, never re-`new`ed here).
+ */
+async function handleSecretRequestCallback(ctx: Context, data: string): Promise<void> {
+  const senderId = String(ctx.from?.id ?? '')
+  const access = loadAccess()
+  if (!access.allowFrom.includes(senderId)) {
+    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
+    return
+  }
+  const parts = data.split(':')
+  const action = parts[1]
+  const stageId = parts[2] ?? ''
+  const pending = pendingSecretRequests.get(stageId)
+  if (!pending) {
+    await ctx.answerCallbackQuery({ text: 'This request expired.' }).catch(() => {})
+    return
+  }
+
+  if (action === 'provide') {
+    armedSecretCaptures.set(pending.chat_id, {
+      key: pending.key,
+      agent: pending.agent,
+      stageId,
+      armed_at: Date.now(),
+      ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+    })
+    await ctx.answerCallbackQuery({ text: 'Send the value now — it auto-deletes.' }).catch(() => {})
+    if (pending.card_message_id != null) {
+      await ctx.api
+        .editMessageText(
+          pending.chat_id,
+          pending.card_message_id,
+          richMessage(`🔐 Send the value for \`${pending.key}\` as your next message — a single message, exactly as-is (don't add other text). I’ll delete it instantly and store it in the vault.`),
+          { reply_markup: { inline_keyboard: [] } },
+        )
+        .catch(() => {})
+    }
+    return
+  }
+
+  if (action === 'decline') {
+    pendingSecretRequests.delete(stageId)
+    pendingCardStore.remove(stageId)
+    armedSecretCaptures.delete(pending.chat_id)
+    await ctx.answerCallbackQuery({ text: 'Declined.' }).catch(() => {})
+    if (pending.card_message_id != null) {
+      await ctx.api
+        .editMessageText(pending.chat_id, pending.card_message_id, richMessage(`🚫 Declined — \`${pending.key}\` not provided.`), {
+          reply_markup: { inline_keyboard: [] },
+        })
+        .catch(() => {})
+    }
+    // Tell the agent so it stops waiting.
+    const ts = Date.now()
+    const synthetic: InboundMessage = {
+      type: 'inbound',
+      chatId: pending.chat_id,
+      ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+      messageId: ts,
+      user: 'vault-broker',
+      userId: 0,
+      ts,
+      text: `🚫 Operator declined your request for \`vault:${pending.key}\`. Proceed without it or ask how they'd like to handle the task.`,
+      meta: {
+        source: 'secret_declined',
+        agent: pending.agent,
+        ...(pending.threadId != null ? { message_thread_id: String(pending.threadId) } : {}),
+        key: pending.key,
+        stage_id: stageId,
+      },
+    }
+    deliverResumeSyntheticOrBuffer(pending.agent, synthetic)
+    return
+  }
+
+  await ctx.answerCallbackQuery().catch(() => {})
+}
+
 async function handleVaultDeferCallback(ctx: Context, data: string): Promise<void> {
   const senderId = String(ctx.from?.id ?? '')
   const access = loadAccess()
@@ -2734,6 +2857,7 @@ async function handleAuthDashboardCallback(ctx: Context): Promise<void> {
     handleMentalModelProposeCallback,
     handleVaultRequestAccessCallback,
     handleVaultRequestSaveCallback,
+    handleSecretRequestCallback,
     handleVaultDeferCallback,
     parseGrantDuration,
     formatGrantExpiry,