@s0nderlabs/anima-plugin-telegram 0.19.19 → 0.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s0nderlabs/anima-plugin-telegram",
-  "version": "0.19.19",
+  "version": "0.20.1",
   "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.19",
+    "@s0nderlabs/anima-core": "0.20.1",
     "grammy": "^1.42.0",
     "zod": "^3.23.8"
   }

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

@@ -44,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'
@@ -223,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
 }