@s0nderlabs/anima-plugin-telegram 0.19.18 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s0nderlabs/anima-plugin-telegram",
-  "version": "0.19.18",
+  "version": "0.20.0",
   "type": "module",
   "description": "Telegram gateway plugin for anima — long-poll bot, debounced dispatch, reactions, allowlist",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@s0nderlabs/anima-core": "0.19.18",
+    "@s0nderlabs/anima-core": "0.20.0",
     "grammy": "^1.42.0",
     "zod": "^3.23.8"
   }

package/src/approval-resolution.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'bun:test'
+import { formatApprovalResolution } from './listener'
+
+/**
+ * Regression test for v0.19.19: every choice maps to a human-readable
+ * suffix so the post-click modal edit shows the operator what they tapped.
+ * v0.19.18 left modals visible after click because the listener only
+ * answered the popup but never edited the message body. v0.19.19 edits the
+ * text to append this suffix and removes the inline keyboard.
+ */
+describe('formatApprovalResolution', () => {
+  it('labels each choice distinctly with the clicker user id', () => {
+    expect(formatApprovalResolution('once', 42)).toBe('✅ Allowed once (by 42)')
+    expect(formatApprovalResolution('session', 42)).toBe('✅ Allowed for session (by 42)')
+    expect(formatApprovalResolution('always', 42)).toBe('✅ Always allowed (by 42)')
+    expect(formatApprovalResolution('deny', 42)).toBe('❌ Denied (by 42)')
+  })
+
+  it('uses ✅ for permitting choices and ❌ only for deny', () => {
+    for (const choice of ['once', 'session', 'always'] as const) {
+      expect(formatApprovalResolution(choice, 1)).toMatch(/^✅/)
+    }
+    expect(formatApprovalResolution('deny', 1)).toMatch(/^❌/)
+  })
+})

package/src/commands.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'bun:test'
+import { buildTelegramCommands } from './commands'
+
+describe('buildTelegramCommands', () => {
+  it('returns at least the v0.20.0 cross-surface commands', () => {
+    const out = buildTelegramCommands()
+    const names = out.map(c => c.command)
+    expect(names).toContain('yolo')
+    expect(names).toContain('perms')
+    expect(names).toContain('reset')
+  })
+
+  it('command names have no leading slash', () => {
+    for (const c of buildTelegramCommands()) {
+      expect(c.command.startsWith('/')).toBe(false)
+    }
+  })
+
+  it('every entry has a non-empty description', () => {
+    for (const c of buildTelegramCommands()) {
+      expect(c.description.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('argHint is folded into description for /perms', () => {
+    const perms = buildTelegramCommands().find(c => c.command === 'perms')
+    expect(perms).toBeDefined()
+    expect(perms!.description).toContain('off|prompt|strict')
+  })
+
+  it('respects Telegram length limits (32 / 256)', () => {
+    for (const c of buildTelegramCommands()) {
+      expect(c.command.length).toBeLessThanOrEqual(32)
+      expect(c.description.length).toBeLessThanOrEqual(256)
+    }
+  })
+
+  it('omits TUI-only commands', () => {
+    const names = buildTelegramCommands().map(c => c.command)
+    expect(names).not.toContain('sync')
+    expect(names).not.toContain('model')
+    expect(names).not.toContain('jobs')
+    expect(names).not.toContain('help')
+  })
+})

package/src/commands.ts

@@ -0,0 +1,28 @@
+/**
+ * Builds the Telegram BotCommand list registered via `bot.api.setMyCommands`.
+ * Sourced from the shared `@s0nderlabs/anima-core` registry, filtered to
+ * surfaces:['tg']. Telegram clips command names to 32 chars and descriptions
+ * to 256, so we trim defensively. Argument hints are folded into the
+ * description because grammY's BotCommand has no separate hint field.
+ */
+
+import { commandsForSurface } from '@s0nderlabs/anima-core'
+
+export interface TelegramBotCommand {
+  command: string
+  description: string
+}
+
+const NAME_LIMIT = 32
+const DESC_LIMIT = 256
+
+export function buildTelegramCommands(): TelegramBotCommand[] {
+  const out: TelegramBotCommand[] = []
+  for (const c of commandsForSurface('tg')) {
+    const name = c.name.slice(0, NAME_LIMIT)
+    const hint = c.argHint ? ` <${c.argHint}>` : ''
+    const description = `${c.description}${hint}`.slice(0, DESC_LIMIT)
+    out.push({ command: name, description })
+  }
+  return out
+}

package/src/index.ts

@@ -27,7 +27,12 @@ export type {
   TelegramToolEvent,
 } from './types'
 export { ProgressTracker, PROGRESS_EDIT_INTERVAL } from './progress'
-export { TelegramListener, TELEGRAM_ALLOWED_UPDATES, capForTelegram } from './listener'
+export {
+  TelegramListener,
+  TELEGRAM_ALLOWED_UPDATES,
+  capForTelegram,
+  formatApprovalResolution,
+} from './listener'
 export { buildSessionKey, sanitizeAgentName } from './session-key'
 export { formatTelegramChannel, formatInboundPreview } from './format'
 export { RateLimiter } from './limits'
@@ -39,7 +44,9 @@ export {
   parseBypassCommand,
   type ActiveSession,
   type BypassCommand,
+  type ParsedBypass,
 } from './session-state'
+export { buildTelegramCommands, type TelegramBotCommand } from './commands'
 export {
   type ApprovalChoice,
   APPROVAL_CALLBACK_PREFIX,

package/src/listener.ts

@@ -1,6 +1,7 @@
 import { Bot, type Context, GrammyError, HttpError } from 'grammy'
 import { type ApprovalChoice, parseCallbackData } from './approval-keyboard'
 import { escapeChunkSuffixForMarkdownV2, splitMessage } from './chunking'
+import { buildTelegramCommands } from './commands'
 import { DebounceBuffer, type FlushedBatch } from './debounce'
 import { formatTelegramChannel } from './format'
 import { RateLimiter } from './limits'
@@ -38,6 +39,23 @@ import { startTypingLoop } from './typing'
 const RETRY_INTERVAL_MS = 30_000
 const MAX_LOCK_RETRY_ATTEMPTS = 12
 
+/**
+ * Map an `ApprovalChoice` to the human-readable resolution label appended
+ * to the approval message after a click. Mirrors the keyboard labels so
+ * operators see the same wording in the resolved message that they tapped.
+ */
+export function formatApprovalResolution(choice: ApprovalChoice, byUserId: number): string {
+  const label =
+    choice === 'once'
+      ? '✅ Allowed once'
+      : choice === 'session'
+        ? '✅ Allowed for session'
+        : choice === 'always'
+          ? '✅ Always allowed'
+          : '❌ Denied'
+  return `${label} (by ${byUserId})`
+}
+
 /**
  * Update kinds we ask Telegram to deliver via long-poll.
  *
@@ -136,6 +154,24 @@ export class TelegramListener {
     } catch {
       /* ignore */
     }
+    // Resolve the modal visually: append the choice + drop the inline
+    // keyboard. Without this, every clicked approval message stays on
+    // screen with all four buttons, leaving operators unsure whether
+    // their tap registered. Best-effort — if the edit fails (rate
+    // limit, message age, deleted), the underlying approval is still
+    // resolved at the runtime level, so we swallow the error.
+    const originalText =
+      typeof q.message?.text === 'string' && q.message.text.length > 0 ? q.message.text : null
+    const suffix = formatApprovalResolution(parsed.choice, q.from.id)
+    try {
+      if (originalText) {
+        await ctx.editMessageText(`${originalText}\n\n${suffix}`, { reply_markup: undefined })
+      } else {
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined })
+      }
+    } catch {
+      /* ignore — modal was clicked, runtime already resolved; keyboard cleanup is cosmetic */
+    }
   }
 
   async start(): Promise<void> {
@@ -188,6 +224,19 @@ export class TelegramListener {
 
     await clearWebhookBeforePolling(this.bot)
 
+    // v0.20.0: register the bot command menu so Telegram clients show
+    // the autocomplete list when the operator types `/`. Sourced from the
+    // shared registry; safe to call repeatedly (Telegram dedupes).
+    try {
+      await this.bot.api.setMyCommands(buildTelegramCommands(), {
+        scope: { type: 'default' },
+      })
+    } catch (err) {
+      console.warn(
+        `[telegram] setMyCommands failed (non-fatal): ${(err as Error).message?.slice(0, 200) ?? 'unknown'}`,
+      )
+    }
+
     this.refreshTimer = setInterval(() => {
       if (this.tokenLock && !this.tokenLock.refresh()) {
         console.warn('[telegram] token lock lost - stopping listener')

package/src/session-state.test.ts

@@ -7,20 +7,33 @@ describe('parseBypassCommand', () => {
     expect(parseBypassCommand('what time is it')).toBeNull()
   })
 
-  it('matches each bypass command verbatim', () => {
+  it('matches each bypass command verbatim with empty args', () => {
     for (const cmd of BYPASS_COMMANDS) {
-      expect(parseBypassCommand(cmd)).toBe(cmd)
+      const r = parseBypassCommand(cmd)
+      expect(r).toEqual({ command: cmd, args: [] })
     }
   })
 
-  it('is case-insensitive', () => {
-    expect(parseBypassCommand('/STOP')).toBe('/stop')
-    expect(parseBypassCommand('/Reset')).toBe('/reset')
+  it('is case-insensitive on the command name', () => {
+    expect(parseBypassCommand('/STOP')?.command).toBe('/stop')
+    expect(parseBypassCommand('/Reset')?.command).toBe('/reset')
   })
 
-  it('ignores args after the command', () => {
-    expect(parseBypassCommand('/stop please')).toBe('/stop')
-    expect(parseBypassCommand('/new with arg')).toBe('/new')
+  it('captures whitespace-split args after the command', () => {
+    expect(parseBypassCommand('/stop please')).toEqual({ command: '/stop', args: ['please'] })
+    expect(parseBypassCommand('/new with arg')).toEqual({
+      command: '/new',
+      args: ['with', 'arg'],
+    })
+  })
+
+  it('parses /perms with mode arg', () => {
+    expect(parseBypassCommand('/perms strict')).toEqual({ command: '/perms', args: ['strict'] })
+    expect(parseBypassCommand('/perms')).toEqual({ command: '/perms', args: [] })
+  })
+
+  it('parses /yolo with no args', () => {
+    expect(parseBypassCommand('/yolo')).toEqual({ command: '/yolo', args: [] })
   })
 
   it('returns null for unknown slash commands', () => {
@@ -34,7 +47,7 @@ describe('parseBypassCommand', () => {
   })
 
   it('strips leading whitespace', () => {
-    expect(parseBypassCommand('   /stop')).toBe('/stop')
+    expect(parseBypassCommand('   /stop')?.command).toBe('/stop')
   })
 })
 

package/src/session-state.ts

@@ -4,10 +4,9 @@
 // dispatch is the load-bearing detail: without it, two messages in the same
 // event-loop tick can both pass the active-check and both spawn brain turns.
 //
-// Bypass commands (verbatim from hermes base.py:1430): /approve, /deny,
-// /status, /stop, /new, /reset, /background, /restart. These are dispatched
-// inline (skipping the active-session guard) so the operator can interrupt
-// or steer a turn that's already mid-flight from their phone.
+// Bypass commands: hermes-derived (/approve, /deny, /status, /stop, /new,
+// /reset, /background, /restart) plus v0.20.0 additions (/yolo, /perms) so
+// operators can flip permission mode from their phone without restarting.
 
 export const BYPASS_COMMANDS = [
   '/stop',
@@ -18,22 +17,32 @@ export const BYPASS_COMMANDS = [
   '/deny',
   '/background',
   '/restart',
+  '/yolo',
+  '/perms',
 ] as const
 
 export type BypassCommand = (typeof BYPASS_COMMANDS)[number]
 
+export interface ParsedBypass {
+  command: BypassCommand
+  args: string[]
+}
+
 /**
  * Detect a bypass command at the start of an inbound message. Returns the
- * canonical lowercase command if matched, else null. Args after the command
- * (e.g. `/stop please`) are ignored — only the leading slash-token matters.
+ * canonical lowercase command + whitespace-split args, or null when the
+ * message isn't a bypass command. v0.20.0 changed the return shape from
+ * `BypassCommand | null` to `ParsedBypass | null` so handlers (especially
+ * `/perms <mode>`) can read the args alongside the name.
  */
-export function parseBypassCommand(text: string): BypassCommand | null {
+export function parseBypassCommand(text: string): ParsedBypass | null {
   const trimmed = text.trim()
   if (!trimmed.startsWith('/')) return null
-  const head = trimmed.split(/\s+/)[0]?.toLowerCase()
+  const parts = trimmed.split(/\s+/)
+  const head = parts[0]?.toLowerCase()
   if (!head) return null
   if ((BYPASS_COMMANDS as readonly string[]).includes(head)) {
-    return head as BypassCommand
+    return { command: head as BypassCommand, args: parts.slice(1) }
   }
   return null
 }