@moxxy/plugin-telegram 0.27.0

package/src/channel/pairing-handler.ts

@@ -0,0 +1,181 @@
+import type { Bot, Context } from 'grammy';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import {
+  beginHostIssuedPairing,
+  clearPairing,
+  createPairingState,
+  handleStart,
+  isAuthorized,
+  submitChatCode,
+  type PairingDecision,
+  type PairingState,
+} from '../pairing.js';
+import { parseChatId, TELEGRAM_AUTHORIZED_CHAT_KEY } from '../keys.js';
+
+const AUTHORIZED_CHAT_KEY = TELEGRAM_AUTHORIZED_CHAT_KEY;
+
+/** Result returned by `confirmChatCode`. */
+export type PairingConfirmResult =
+  | { ok: true; chatId: number }
+  | { ok: false; reason: 'mismatch' | 'expired' | 'not-pending' | 'no-window'; message: string };
+
+export interface PairingHandlerOptions {
+  readonly vault: VaultStore;
+  readonly logger?: {
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+  };
+}
+
+/**
+ * Owns the pairing state machine + the bot-side `/start` handler for the
+ * host-issued QR pairing flow (see {@link beginHostWindow}). Keeps the bot
+ * reference (re-)settable so the TelegramChannel can wire it up after
+ * construction.
+ */
+export class PairingHandler {
+  private state: PairingState = createPairingState();
+  private bot: Bot | null = null;
+  private readonly opts: PairingHandlerOptions;
+  private readonly pairedListeners = new Set<(chatId: number) => void>();
+
+  constructor(opts: PairingHandlerOptions) {
+    this.opts = opts;
+  }
+
+  attachBot(bot: Bot | null): void {
+    this.bot = bot;
+  }
+
+  async loadAuthorized(): Promise<void> {
+    const authorizedRaw = await this.opts.vault.get(AUTHORIZED_CHAT_KEY);
+    const authorizedChatId = parseChatId(authorizedRaw);
+    if (authorizedChatId == null && authorizedRaw) {
+      this.opts.logger?.warn('telegram pairing: stored chat id is not a number — treating as unpaired', {
+        raw: authorizedRaw,
+      });
+    }
+    this.state = createPairingState({ authorizedChatId });
+  }
+
+  isAuthorized(chatId: number): boolean {
+    return isAuthorized(this.state, chatId);
+  }
+
+  phase(): PairingState['phase'] {
+    return this.state.phase;
+  }
+
+  /**
+   * Open a host-issued pairing window and return the code to embed in the
+   * `t.me/<bot>?start=<code>` deep link / QR the control surface renders. The
+   * user proves ownership by presenting THIS code back to the bot (deep-link tap
+   * or a plain message), which `handleStartCommand` / `confirmChatCode`
+   * validate. Returns the generated code.
+   */
+  beginHostWindow(): string {
+    const { state, code } = beginHostIssuedPairing(this.state);
+    this.state = state;
+    return code;
+  }
+
+  unpair(): void {
+    this.state = clearPairing(this.state);
+  }
+
+  /**
+   * Subscribe to "a chat just became authorized" — fires once each time pairing
+   * completes. The channel uses this to publish its "connected" connect-state so
+   * a watching control surface can swap the QR for a "✓ Connected" affordance,
+   * and the `pair` terminal command uses it to know pairing finished. Returns an
+   * unsubscribe function.
+   */
+  onPaired(listener: (chatId: number) => void): () => void {
+    this.pairedListeners.add(listener);
+    return () => this.pairedListeners.delete(listener);
+  }
+
+  /**
+   * A chat presented a code (deep-link `/start <code>` payload or a plain 6-digit
+   * message). On match the chat is authorized, persisted to the vault, and
+   * greeted. Returns a structured result the caller can branch on.
+   */
+  async confirmChatCode(chatId: number, rawCode: string): Promise<PairingConfirmResult> {
+    const decision = submitChatCode(this.state, chatId, rawCode);
+    return this.applyConfirmDecision(decision);
+  }
+
+  /** Persist + greet + notify on a 'paired' decision; map every decision kind to
+   *  a {@link PairingConfirmResult}. */
+  private async applyConfirmDecision(decision: PairingDecision): Promise<PairingConfirmResult> {
+    this.state = decision.state;
+    const action = decision.action;
+    if (action.kind === 'paired') {
+      await this.opts.vault.set(AUTHORIZED_CHAT_KEY, String(action.chatId));
+      // Greet the chat that just got authorized so the user has a confirmation
+      // on the Telegram side too — symmetric with the success the surface shows.
+      if (this.bot) {
+        try {
+          await this.bot.api.sendMessage(
+            action.chatId,
+            '✅ Paired with moxxy. Send a prompt to begin.',
+          );
+        } catch (err) {
+          this.opts.logger?.warn('pairing: greeting send failed', { err: String(err) });
+        }
+      }
+      this.emitPaired(action.chatId);
+      return { ok: true, chatId: action.chatId };
+    }
+    if (action.kind === 'still-paired') return { ok: true, chatId: action.chatId };
+    if (action.kind === 'mismatch') return { ok: false, reason: 'mismatch', message: action.message };
+    if (action.kind === 'expired') return { ok: false, reason: 'expired', message: action.message };
+    if (action.kind === 'not-pending') return { ok: false, reason: 'not-pending', message: action.message };
+    if (action.kind === 'reject') return { ok: false, reason: 'not-pending', message: action.message };
+    return { ok: false, reason: 'mismatch', message: 'unexpected pairing state' };
+  }
+
+  private emitPaired(chatId: number): void {
+    for (const listener of this.pairedListeners) {
+      try {
+        listener(chatId);
+      } catch (err) {
+        this.opts.logger?.warn('pairing paired-listener threw', { err: String(err) });
+      }
+    }
+  }
+
+  /** Bot-side `/start` handler. */
+  async handleStartCommand(ctx: Context): Promise<void> {
+    const chatId = ctx.chat?.id;
+    if (!chatId) return;
+
+    // Host-issued direction: the deep link the user scanned carries the code as
+    // the /start payload (grammy exposes it as `ctx.match`). Validate it here so
+    // "scan QR → tap START → paired" needs no typing. A bare /start (no payload —
+    // e.g. the user opened the chat manually) falls through to `handleStart`,
+    // which nudges them to use the link or send the digits (the message handler
+    // also accepts a bare 6-digit code).
+    if (this.state.phase === 'awaiting-host-code') {
+      const payload = typeof ctx.match === 'string' ? ctx.match.trim() : '';
+      if (payload) {
+        const result = await this.confirmChatCode(chatId, payload);
+        if (!result.ok && result.reason !== 'not-pending') {
+          await ctx.reply(result.message);
+        }
+        return;
+      }
+    }
+
+    const decision: PairingDecision = handleStart(this.state, chatId);
+    this.state = decision.state;
+    const action = decision.action;
+    if (action.kind === 'still-paired') {
+      await ctx.reply('Welcome back! Send me a prompt.');
+      return;
+    }
+    if (action.kind === 'reject' || action.kind === 'expired') {
+      await ctx.reply(action.message);
+    }
+  }
+}

package/src/channel/permission-prompt.ts

@@ -0,0 +1,51 @@
+import { type Bot, InlineKeyboard } from 'grammy';
+import type { PendingToolCall, PermissionContext } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { TelegramPermissionResolver } from '../permission.js';
+import { truncate } from './html.js';
+
+export interface PermissionPromptDeps {
+  readonly bot: Bot | null;
+  readonly chatId: number | null;
+  readonly session: Session | null;
+  readonly resolver: TelegramPermissionResolver;
+  readonly yolo: boolean;
+  readonly logger?: { warn(msg: string, meta?: Record<string, unknown>): void };
+}
+
+/**
+ * Render an inline-keyboard permission prompt for a pending tool call.
+ * The decider promise resolves when the user clicks a button (routed
+ * back via the callback handler) or when the resolver aborts on stop.
+ */
+export async function askForPermission(
+  call: PendingToolCall,
+  ctx: PermissionContext,
+  deps: PermissionPromptDeps,
+): Promise<void> {
+  if (!deps.bot || !deps.chatId || !deps.session) return;
+  void ctx;
+  // YOLO short-circuit: resolve immediately without rendering a prompt.
+  // Mirrors the TUI's `/yolo` flag — once set, every tool call passes.
+  if (deps.yolo) {
+    deps.resolver.resolvePending(call.callId, { mode: 'allow', reason: 'yolo mode' });
+    return;
+  }
+  const keyboard = new InlineKeyboard()
+    .text('Allow once', `perm:${call.callId}:allow`)
+    .text('Allow session', `perm:${call.callId}:allow_session`)
+    .row()
+    .text('Deny', `perm:${call.callId}:deny`);
+  const description = deps.session.tools.get(call.name)?.description ?? '';
+  const summary =
+    `🔐 Tool permission requested\n` +
+    `Tool: ${call.name}\n` +
+    (description ? `Desc: ${description}\n` : '') +
+    `Input: ${truncate(JSON.stringify(call.input), 300)}`;
+  try {
+    await deps.bot.api.sendMessage(deps.chatId, summary, { reply_markup: keyboard });
+  } catch (err) {
+    deps.logger?.warn('permission send failed', { err: String(err) });
+    deps.resolver.resolvePending(call.callId, { mode: 'deny', reason: 'unable to render prompt' });
+  }
+}

package/src/channel/slash-handler.ts

@@ -0,0 +1,259 @@
+import { type Bot, type Context, InlineKeyboard } from 'grammy';
+import { isSelectableMode } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { resolveVoiceToggle } from '@moxxy/channel-kit';
+
+/**
+ * Install guidance shown when enabling `/voice` with no active synthesizer —
+ * mirrors the voice-handler's transcriber guidance wording, pointing at the TTS
+ * plugin instead of the STT one.
+ */
+export const VOICE_NO_SYNTH_HINT =
+  'No text-to-speech backend is configured yet, so replies stay text-only. Install one with `moxxy plugins install tts-openai` and run `moxxy login openai` (or set OPENAI_API_KEY) to enable spoken replies.';
+
+export interface SlashState {
+  readonly session: Session | null;
+  readonly model: string | undefined;
+  readonly activeModelOverride: string | null;
+  readonly yolo: boolean;
+  /** Whether voice replies are currently enabled (backs `/voice status`). */
+  readonly voiceReplies: boolean;
+}
+
+export interface SlashCallbacks {
+  /** Toggle yolo and return its new value (so we can echo the right message). */
+  toggleYolo(): boolean;
+  /** Persist + apply the voice-replies preference (backs `/voice on|off`). */
+  setVoiceReplies(on: boolean): Promise<void>;
+  /** Apply a `session-action` result emitted from a registered command. */
+  performSessionAction(
+    ctx: Context,
+    action: 'new' | 'clear' | 'exit',
+    notice: string | undefined,
+  ): Promise<void>;
+}
+
+/**
+ * Slash-command dispatcher for the Telegram channel.
+ *
+ * First tries the shared `session.commands` registry — this is where
+ * the universal commands (/info, /clear, /new, /exit, /help) live, so
+ * Telegram gets them for free alongside any plugin-contributed
+ * commands without needing a switch case here.
+ *
+ * Falls through to channel-local cases for Telegram-specific UI
+ * (model/loop pickers as inline keyboards, /yolo toggle, /tools and
+ * /skills as text dumps).
+ */
+export async function runSlash(
+  ctx: Context,
+  text: string,
+  state: SlashState,
+  cb: SlashCallbacks,
+): Promise<void> {
+  const session = state.session;
+  if (!session) return;
+  const [head, ...rest] = text.split(/\s+/);
+  const name = head!.slice(1);
+  const args = rest.join(' ');
+
+  // 1) Shared registry dispatch.
+  const registered = session.commands.get(name);
+  if (registered) {
+    try {
+      const result = await registered.handler({
+        channel: 'telegram',
+        sessionId: session.id,
+        args,
+        session,
+      });
+      if (result.kind === 'text') {
+        await ctx.reply(result.text);
+      } else if (result.kind === 'session-action') {
+        await cb.performSessionAction(ctx, result.action, result.notice);
+      } else if (result.kind === 'error') {
+        await ctx.reply(`error: ${result.message}`);
+      }
+    } catch (err) {
+      await ctx.reply(
+        `command /${name} failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    return;
+  }
+
+  // 2) Channel-local cases.
+  switch (head) {
+    case '/model':
+      await renderModelPicker(ctx, session, state, args);
+      return;
+    case '/mode':
+      await renderModePicker(ctx, session);
+      return;
+    case '/yolo': {
+      const enabled = cb.toggleYolo();
+      await ctx.reply(
+        enabled
+          ? '⚠ yolo mode ON — tool calls auto-approved for the rest of this session'
+          : 'yolo mode OFF — tool prompts will resume',
+      );
+      return;
+    }
+    case '/voice': {
+      const result = resolveVoiceToggle({
+        arg: args,
+        enabled: state.voiceReplies,
+        hasSynthesizer: session.synthesizers.tryGetActive() != null,
+        delivery: 'a voice note',
+        noSynthesizerHint: VOICE_NO_SYNTH_HINT,
+      });
+      if (result.persist) await cb.setVoiceReplies(result.enabled);
+      await ctx.reply(result.reply);
+      return;
+    }
+    case '/tools': {
+      const list = session.tools
+        .list()
+        .map((t) => `${t.name} — ${t.description}`)
+        .join('\n');
+      await ctx.reply(list || '(no tools registered)');
+      return;
+    }
+    case '/skills': {
+      const list = session.skills
+        .list()
+        .map((s) => {
+          const triggers = s.frontmatter.triggers ?? [];
+          const triggerLine = triggers.length
+            ? `\n   triggers: ${triggers.map((t) => `"${t}"`).join(', ')}`
+            : '';
+          return `${s.frontmatter.name} — ${s.frontmatter.description}${triggerLine}`;
+        })
+        .join('\n');
+      await ctx.reply(list || '(no skills discovered)');
+      return;
+    }
+    default:
+      await ctx.reply(`unknown command: ${head} (try /help)`);
+  }
+}
+
+/** Telegram inline keyboards get unwieldy past this many rows; cap the picker. */
+const MODEL_PICKER_CAP = 30;
+
+async function renderModelPicker(
+  ctx: Context,
+  session: Session,
+  state: SlashState,
+  filter = '',
+): Promise<void> {
+  const providers = session.providers.list();
+  if (providers.length === 0) {
+    await ctx.reply('no providers registered');
+    return;
+  }
+  const keyboard = new InlineKeyboard();
+  const providerName = session.providers.getActiveName() ?? '';
+  const activeModel = state.activeModelOverride ?? state.model ?? '';
+  // Same boot-time readiness set the TUI uses to flag unconfigured
+  // providers — set by `@moxxy/cli` at setup time. Providers that
+  // failed credential resolution get a "(not connected)" suffix
+  // and a tap on them surfaces the right setup command instead of
+  // a no-op switch.
+  const ready = session.readyProviders ?? new Set<string>();
+  // `/model <substring>` narrows the list so a model that sorts past the
+  // keyboard cap is still reachable from chat (the cap below would otherwise
+  // silently hide it with no fallback).
+  const needle = filter.trim().toLowerCase();
+  // Flatten so we can both apply the substring filter and report how many the
+  // cap hides (vs. how many the filter excluded).
+  const all = providers.flatMap((p) =>
+    p.models.map((m) => ({ provider: p.name, model: m.id })),
+  );
+  const matched = needle
+    ? all.filter((e) => `${e.provider}::${e.model}`.toLowerCase().includes(needle))
+    : all;
+  if (matched.length === 0) {
+    await ctx.reply(`no model matches "${filter.trim()}" — try /model with no argument.`);
+    return;
+  }
+  const shown = matched.slice(0, MODEL_PICKER_CAP);
+  for (const e of shown) {
+    const isCurrent = providerName === e.provider && activeModel === e.model;
+    const connected = ready.has(e.provider);
+    const label =
+      `${isCurrent ? '• ' : ''}${e.provider}: ${e.model}` +
+      (connected ? '' : ' (not connected)');
+    keyboard.text(label, `model:${e.provider}::${e.model}`).row();
+  }
+  const hidden = matched.length - shown.length;
+  const prompt =
+    hidden > 0
+      ? `Pick a model (${hidden} more not shown — narrow with /model <text>):`
+      : 'Pick a model:';
+  await ctx.reply(prompt, { reply_markup: keyboard });
+}
+
+async function renderModePicker(ctx: Context, session: Session): Promise<void> {
+  // Special modes (e.g. collaborative, entered via /collab) are hidden from the
+  // picker the same way they are in the TUI. See ModeDef.special.
+  const modes = session.modes.list().filter(isSelectableMode);
+  if (modes.length === 0) {
+    await ctx.reply('no modes registered');
+    return;
+  }
+  const keyboard = new InlineKeyboard();
+  const activeModeName = (() => {
+    try {
+      return session.modes.getActive().name;
+    } catch {
+      return '';
+    }
+  })();
+  for (const s of modes) {
+    const isCurrent = s.name === activeModeName;
+    keyboard.text(`${isCurrent ? '• ' : ''}${s.name}`, `mode:${s.name}`).row();
+  }
+  await ctx.reply('Pick a mode:', { reply_markup: keyboard });
+}
+
+/**
+ * Push the union of registry commands + Telegram-local commands to
+ * Telegram so they appear in the chat's command menu (the "/" picker
+ * the official client shows). Best-effort: a network failure here
+ * doesn't block channel startup, the commands still work via text.
+ */
+export async function publishBotCommands(
+  bot: Bot | null,
+  session: Session | null,
+  logger?: { warn?(msg: string, meta?: Record<string, unknown>): void },
+): Promise<void> {
+  if (!session || !bot) return;
+  const LOCAL: Array<{ command: string; description: string }> = [
+    { command: 'model', description: 'Switch provider + model (inline keyboard)' },
+    { command: 'mode', description: 'Switch mode' },
+    { command: 'yolo', description: 'Toggle auto-approve mode' },
+    { command: 'voice', description: 'Toggle spoken voice replies' },
+    { command: 'tools', description: 'List the tools the active session can call' },
+    { command: 'skills', description: 'List the discovered skills' },
+    { command: 'cancel', description: 'Abort the current turn' },
+  ];
+  const shared = session.commands
+    .listForChannel('telegram')
+    .map((c) => ({ command: c.name, description: c.description }));
+  const seen = new Set(shared.map((c) => c.command));
+  const merged = [...shared, ...LOCAL.filter((c) => !seen.has(c.command))]
+    .sort((a, b) => a.command.localeCompare(b.command))
+    // Telegram caps descriptions at 256 chars and rejects empties.
+    .map((c) => ({
+      command: c.command,
+      description: (c.description || c.command).slice(0, 256),
+    }));
+  try {
+    await bot.api.setMyCommands(merged);
+  } catch (err) {
+    logger?.warn?.('telegram setMyCommands failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+  }
+}