@moxxy/plugin-telegram 0.27.0

package/src/channel/callback-handler.ts

@@ -0,0 +1,256 @@
+import type { Bot, Context } from 'grammy';
+import { setCategoryDefault, setProviderModel } from '@moxxy/config';
+import { isSelectableMode } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { PermissionDecision } from '@moxxy/sdk';
+import type { TelegramPermissionResolver } from '../permission.js';
+import type { TelegramApprovalResolver } from '../approval.js';
+
+export interface AwaitingApprovalText {
+  approvalId: string;
+  optionId: string;
+}
+
+export interface CallbackState {
+  readonly bot: Bot | null;
+  readonly session: Session | null;
+  readonly chatId: number | null;
+  readonly permissionResolver: TelegramPermissionResolver;
+  readonly approvalResolver: TelegramApprovalResolver;
+  /** Pairing gate — the same authorization check the text/voice handlers enforce. */
+  readonly pairing: { isAuthorized(chatId: number): boolean };
+}
+
+export interface CallbackCallbacks {
+  /** Latch an in-flight approval awaiting a text follow-up. */
+  setAwaitingApprovalText(state: AwaitingApprovalText | null): void;
+  setActiveModelOverride(modelId: string): void;
+}
+
+/** Inline-keyboard callback router. Dispatches by prefix:
+ *  - `perm:`   → permission resolver
+ *  - `appr:`   → approval resolver
+ *  - `model:`  → provider+model switch (with credential resolve)
+ *  - `mode:`   → mode switch
+ */
+export async function handleCallback(
+  ctx: Context,
+  state: CallbackState,
+  cb: CallbackCallbacks,
+): Promise<void> {
+  const data = ctx.callbackQuery?.data;
+  if (!data) return;
+
+  // Authorization gate — mirror the text/voice handlers. Button clicks can
+  // resolve permission prompts, approve plans, and switch provider/model/mode,
+  // so an unpaired chat's callbacks must be refused just like its messages
+  // (inline-keyboard messages can be forwarded to arbitrary chats).
+  const chatId = ctx.chat?.id ?? ctx.callbackQuery?.message?.chat?.id;
+  if (chatId === undefined || !state.pairing.isAuthorized(chatId)) {
+    try {
+      await ctx.answerCallbackQuery({ text: 'This bot is paired with a different chat.' });
+    } catch {
+      /* ignore */
+    }
+    return;
+  }
+
+  if (data.startsWith('perm:')) {
+    await handlePerm(ctx, data, state.permissionResolver);
+    return;
+  }
+  if (data.startsWith('appr:')) {
+    await handleAppr(ctx, data, state, cb);
+    return;
+  }
+  if (data.startsWith('model:')) {
+    await handleModel(ctx, data, state.session, cb);
+    return;
+  }
+  if (data.startsWith('mode:')) {
+    await handleMode(ctx, data, state.session);
+    return;
+  }
+}
+
+async function handlePerm(
+  ctx: Context,
+  data: string,
+  resolver: TelegramPermissionResolver,
+): Promise<void> {
+  const parts = data.split(':');
+  if (parts.length !== 3) return;
+  const [, callId, choice] = parts;
+  if (!callId || !choice) return;
+  const decision = mapChoice(choice);
+  const handled = resolver.resolvePending(callId, decision);
+  await ctx.answerCallbackQuery({ text: handled ? choice : 'no pending permission' });
+  if (handled && ctx.callbackQuery?.message) {
+    try {
+      await ctx.editMessageReplyMarkup({});
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+async function handleAppr(
+  ctx: Context,
+  data: string,
+  state: CallbackState,
+  cb: CallbackCallbacks,
+): Promise<void> {
+  // Format: appr:<approvalId>:<optionId>
+  const idx = data.indexOf(':', 5);
+  if (idx < 0) return;
+  const approvalId = data.slice(5, idx);
+  const optionId = data.slice(idx + 1);
+  const pending = state.approvalResolver.getPending(approvalId);
+  if (!pending) {
+    await ctx.answerCallbackQuery({ text: 'no pending approval' });
+    return;
+  }
+  const option = pending.request.options.find((o) => o.id === optionId);
+  if (!option) {
+    await ctx.answerCallbackQuery({ text: 'unknown option' });
+    return;
+  }
+  // Clear the inline keyboard so the user can't double-click.
+  if (ctx.callbackQuery?.message) {
+    try {
+      await ctx.editMessageReplyMarkup({});
+    } catch {
+      /* ignore */
+    }
+  }
+  if (option.requestsText) {
+    // Don't resolve yet — capture the user's next message as the
+    // follow-up text. Mirrors the TUI dialog's text-entry sub-mode.
+    cb.setAwaitingApprovalText({ approvalId, optionId });
+    await ctx.answerCallbackQuery({ text: option.label });
+    const prompt =
+      option.textPrompt ??
+      `Send your message — the next text you type becomes the ${optionId} input.`;
+    if (state.chatId && state.bot) {
+      try {
+        await state.bot.api.sendMessage(state.chatId, `✏️ ${prompt}`);
+      } catch {
+        /* ignore */
+      }
+    }
+    return;
+  }
+  state.approvalResolver.resolvePending(approvalId, optionId);
+  await ctx.answerCallbackQuery({ text: option.label });
+}
+
+async function handleModel(
+  ctx: Context,
+  data: string,
+  session: Session | null,
+  cb: CallbackCallbacks,
+): Promise<void> {
+  // Format: model:<providerName>::<modelId>
+  const payload = data.slice(6);
+  const [providerId, modelId] = payload.split('::');
+  if (!providerId || !modelId || !session) {
+    await ctx.answerCallbackQuery({ text: 'invalid model selection' });
+    return;
+  }
+  // Intercept switches to unconfigured providers — otherwise OAuth-
+  // backed providers (openai-codex) would surface a credential
+  // error on the next turn. Match the TUI's wording so the user
+  // sees the same setup command in both channels.
+  const ready = session.readyProviders ?? new Set<string>();
+  if (!ready.has(providerId)) {
+    const cmd =
+      providerId === 'openai-codex'
+        ? 'moxxy login openai-codex'
+        : `moxxy init   # (will prompt for ${providerId.toUpperCase()}_API_KEY)`;
+    await ctx.answerCallbackQuery({ text: `${providerId} not connected` });
+    if (ctx.callbackQuery?.message) {
+      try {
+        await ctx.editMessageText(
+          `${providerId} isn't connected.\n\nRun \`${cmd}\` then restart moxxy.`,
+          { parse_mode: 'Markdown' },
+        );
+      } catch {
+        /* ignore */
+      }
+    }
+    return;
+  }
+  try {
+    if (session.providers.getActiveName() !== providerId) {
+      // Resolve credentials and drop the cached instance, same as
+      // the TUI. Without this the new provider gets createClient({})
+      // and openai-codex throws "no OAuth credentials" on next turn.
+      const resolver = session.credentialResolver;
+      const cfg = resolver ? await resolver(providerId) : {};
+      const def = session.providers.list().find((p) => p.name === providerId);
+      if (def) session.providers.replace(def);
+      session.providers.setActive(providerId, cfg);
+    }
+    cb.setActiveModelOverride(modelId);
+    // Persist to the unified manifest for the next CLI run — same config the TUI
+    // writes. Await so a write failure (disk/permission/lock) is caught below and
+    // reported, instead of telling the user "✓ switched" while it never landed.
+    await setCategoryDefault('provider', providerId);
+    await setProviderModel(providerId, modelId);
+    await ctx.answerCallbackQuery({ text: `→ ${providerId}:${modelId}` });
+    if (ctx.callbackQuery?.message) {
+      try {
+        await ctx.editMessageText(`✓ switched to ${providerId}:${modelId}`);
+      } catch {
+        /* ignore */
+      }
+    }
+  } catch (err) {
+    await ctx.answerCallbackQuery({
+      text: `failed: ${err instanceof Error ? err.message : String(err)}`,
+    });
+  }
+}
+
+async function handleMode(
+  ctx: Context,
+  data: string,
+  session: Session | null,
+): Promise<void> {
+  const modeName = data.slice(5);
+  if (!modeName || !session) {
+    await ctx.answerCallbackQuery({ text: 'invalid mode' });
+    return;
+  }
+  // Refuse a special mode reached by name (e.g. a stale callback) — special
+  // modes are entered only via their own command. Mirrors the TUI guard.
+  const target = session.modes.list().find((m) => m.name === modeName);
+  if (target && !isSelectableMode(target)) {
+    await ctx.answerCallbackQuery({ text: `"${modeName}" is a special mode` });
+    return;
+  }
+  try {
+    session.modes.setActive(modeName);
+    // Await so a persistence failure is caught below (and reported) rather than
+    // claiming success while it silently never landed.
+    await setCategoryDefault('mode', modeName);
+    await ctx.answerCallbackQuery({ text: `mode → ${modeName}` });
+    if (ctx.callbackQuery?.message) {
+      try {
+        await ctx.editMessageText(`✓ mode → ${modeName}`);
+      } catch {
+        /* ignore */
+      }
+    }
+  } catch (err) {
+    await ctx.answerCallbackQuery({
+      text: `failed: ${err instanceof Error ? err.message : String(err)}`,
+    });
+  }
+}
+
+function mapChoice(choice: string): PermissionDecision {
+  if (choice === 'allow') return { mode: 'allow' };
+  if (choice === 'allow_session') return { mode: 'allow_session' };
+  return { mode: 'deny', reason: 'denied by user' };
+}

package/src/channel/frame-pump.ts

@@ -0,0 +1,176 @@
+import type { Bot } from 'grammy';
+import { GrammyError } from 'grammy';
+import { FramePump as StreamPump } from '@moxxy/channel-kit';
+import { TurnRenderer, splitForTelegram } from '../render.js';
+import { composeFrame, stripHtml } from './html.js';
+
+export interface FramePumpLogger {
+  warn(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface FramePumpOptions {
+  readonly editFrameMs: number;
+  readonly logger?: FramePumpLogger;
+}
+
+/**
+ * Drives the throttled "compose snapshot → send/edit one message" loop
+ * for a turn. Owns the renderer and the Telegram-specific delivery —
+ * HTML parse-mode fallback + 4096-char message splitting — while the
+ * throttle/send-once-then-edit mechanics live in `@moxxy/channel-kit`'s
+ * {@link StreamPump} (one instance per turn).
+ *
+ * Lifecycle per turn:
+ *   1. `beginTurn(chatId)` resets state.
+ *   2. Renderer updates schedule edits via `scheduleEdit()`.
+ *   3. `flush(final)` drains the latest snapshot to Telegram.
+ *   4. `endTurn()` clears timers + chat binding.
+ */
+export class FramePump {
+  private readonly editFrameMs: number;
+  private readonly logger?: FramePumpLogger;
+  private bot: Bot | null = null;
+  private renderer: TurnRenderer = new TurnRenderer();
+  private pump: StreamPump<number> | null = null;
+
+  constructor(opts: FramePumpOptions) {
+    this.editFrameMs = opts.editFrameMs;
+    if (opts.logger) this.logger = opts.logger;
+  }
+
+  attachBot(bot: Bot | null): void {
+    this.bot = bot;
+  }
+
+  /** Renderer the channel feeds events into. Owned here so reset/snapshot
+   *  cycles stay coordinated with the message-id state. */
+  get renderState(): TurnRenderer {
+    return this.renderer;
+  }
+
+  resetRenderer(): void {
+    this.renderer.reset();
+  }
+
+  beginTurn(chatId: number): void {
+    this.renderer.reset();
+    this.pump = new StreamPump<number>({
+      editFrameMs: this.editFrameMs,
+      // Only the FINAL frame collapses the activity trace into its expandable
+      // box — mid-stream frames keep it open so the user watches work land live.
+      frame: (final) => composeFrame(this.renderer.snapshot({ collapse: final })),
+      // The final flush must produce at least one message so the user isn't
+      // left with the typing indicator dangling.
+      emptyFinalText: '<i>(no output)</i>',
+      // The sink does final-only work (split-overflow tails below), so the
+      // final frame must reach it even when the text didn't change since the
+      // last streamed edit.
+      alwaysFlushFinal: true,
+      sink: {
+        send: (text, final) => this.sendFrame(chatId, text, final),
+        edit: (messageId, text, final) => this.editFrame(chatId, messageId, text, final),
+      },
+    });
+  }
+
+  endTurn(): void {
+    this.pump?.dispose();
+    this.pump = null;
+  }
+
+  scheduleEdit(): void {
+    this.pump?.scheduleEdit();
+  }
+
+  async flush(final: boolean): Promise<void> {
+    if (!this.bot || !this.pump) return;
+    await this.pump.flush(final);
+  }
+
+  /** First real content of this turn — send (don't edit a placeholder). On the
+   *  final frame, overflow beyond Telegram's message limit goes out as
+   *  follow-up messages. */
+  private async sendFrame(chatId: number, text: string, final: boolean): Promise<number | null> {
+    if (!this.bot) return null;
+    const parts = splitForTelegram(text);
+    const sent = await this.safeSend(chatId, parts[0]!);
+    if (final && parts.length > 1) {
+      for (const tail of parts.slice(1)) {
+        await this.safeSend(chatId, tail);
+      }
+    }
+    return sent;
+  }
+
+  private async editFrame(
+    chatId: number,
+    messageId: number,
+    text: string,
+    final: boolean,
+  ): Promise<void> {
+    if (!this.bot) return;
+    const parts = splitForTelegram(text);
+    await this.safeEdit(chatId, messageId, parts[0]!);
+    if (final && parts.length > 1) {
+      for (const tail of parts.slice(1)) {
+        await this.safeSend(chatId, tail);
+      }
+    }
+  }
+
+  /**
+   * `text` is already Telegram-flavored HTML (produced by
+   * `composeFrame`). Try HTML; on parse-entity errors, strip tags and
+   * send plain text so the message still lands instead of looping on
+   * the same edit forever.
+   */
+  async safeEdit(chatId: number, messageId: number, text: string): Promise<void> {
+    try {
+      await this.bot!.api.editMessageText(chatId, messageId, text, {
+        parse_mode: 'HTML',
+        link_preview_options: { is_disabled: true },
+      });
+      return;
+    } catch (err) {
+      if (err instanceof GrammyError && err.description?.includes('not modified')) return;
+      if (err instanceof GrammyError && /can't parse entities|Bad Request: can't parse/i.test(err.description ?? '')) {
+        try {
+          await this.bot!.api.editMessageText(chatId, messageId, stripHtml(text));
+          return;
+        } catch (plainErr) {
+          if (plainErr instanceof GrammyError && plainErr.description?.includes('not modified')) return;
+          this.logger?.warn('editMessageText plain-fallback failed', { err: String(plainErr) });
+          return;
+        }
+      }
+      this.logger?.warn('editMessageText failed', { err: String(err) });
+    }
+  }
+
+  /**
+   * Send a new message (first frame of a turn or split-tail).
+   * Returns the new message_id on success so callers can set
+   * messageId for future edits.
+   */
+  async safeSend(chatId: number, text: string): Promise<number | null> {
+    try {
+      const sent = await this.bot!.api.sendMessage(chatId, text, {
+        parse_mode: 'HTML',
+        link_preview_options: { is_disabled: true },
+      });
+      return sent.message_id;
+    } catch (err) {
+      if (err instanceof GrammyError && /can't parse entities|Bad Request: can't parse/i.test(err.description ?? '')) {
+        try {
+          const sent = await this.bot!.api.sendMessage(chatId, stripHtml(text));
+          return sent.message_id;
+        } catch (plainErr) {
+          this.logger?.warn('sendMessage plain-fallback failed', { err: String(plainErr) });
+          return null;
+        }
+      }
+      this.logger?.warn('sendMessage failed', { err: String(err) });
+      return null;
+    }
+  }
+}

package/src/channel/html.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { stripHtml, truncate } from './html.js';
+
+describe('stripHtml', () => {
+  it('strips tags and keeps text content', () => {
+    expect(stripHtml('<b>bold</b> and <code>code</code>')).toBe('bold and code');
+  });
+
+  it('decodes the four named entities', () => {
+    expect(stripHtml('a &lt; b &gt; c &amp; d &quot;e&quot;')).toBe('a < b > c & d "e"');
+  });
+
+  // u110-4: decoding &amp; LAST avoids double-decoding a literal escaped entity.
+  it('does not double-decode a literal escaped entity (&amp;lt;)', () => {
+    expect(stripHtml('a &amp;lt; b')).toBe('a &lt; b');
+  });
+
+  // u110-4: numeric/hex entities must be decoded, not leaked literally.
+  it('decodes numeric and hex entities (e.g. apostrophes)', () => {
+    expect(stripHtml('it&#39;s a &#x27;quote&#x27;')).toBe("it's a 'quote'");
+  });
+
+  it('combines tags, named, and numeric entities', () => {
+    expect(stripHtml('<i>x</i> &amp; &#39;y&#39; &lt;z&gt;')).toBe("x & 'y' <z>");
+  });
+
+  it('leaves an out-of-range numeric entity as empty rather than throwing', () => {
+    expect(() => stripHtml('&#999999999;')).not.toThrow();
+  });
+});
+
+describe('truncate', () => {
+  it('returns the string unchanged when within the limit', () => {
+    expect(truncate('hello', 10)).toBe('hello');
+  });
+
+  it('truncates and appends an ellipsis past the limit', () => {
+    expect(truncate('hello world', 5)).toBe('hello…');
+  });
+});

package/src/channel/html.ts

@@ -0,0 +1,60 @@
+import { markdownToTelegramHtml } from '../format.js';
+import type { RenderedFrame } from '../render.js';
+
+/**
+ * Compose one Telegram message string from the renderer's structured
+ * snapshot. The activity block is pre-formatted HTML (the renderer
+ * emits `<blockquote>`, `<code>`, `<b>`, `<i>` directly so it can
+ * style tool calls without going through the markdown converter). The
+ * assistant body is plain Markdown from the model — convert it through
+ * `markdownToTelegramHtml` so `**bold**`, `` `code` ``, ```code blocks```,
+ * `[links](…)`, and list bullets render natively in Telegram.
+ *
+ * The error line is also pre-formatted HTML (small, controlled).
+ */
+export function composeFrame(snap: RenderedFrame): string {
+  const parts: string[] = [];
+  if (snap.activityHtml) parts.push(snap.activityHtml);
+  if (snap.body) parts.push(markdownToTelegramHtml(snap.body));
+  // File-diff blocks are already Telegram HTML (summary line + a
+  // <pre><code class="language-diff"> fence), so they skip the markdown
+  // converter. Append after the body; the frame pump's `splitForTelegram`
+  // handles the 4000-char cap, sending overflow as follow-up messages.
+  if (snap.diffHtml) parts.push(snap.diffHtml);
+  if (snap.errorHtml) parts.push(snap.errorHtml);
+  return parts.join('\n\n');
+}
+
+/** Strip every HTML tag for plain-text fallback when Telegram rejects
+ *  our parse_mode=HTML payload (rare — usually a malformed entity in
+ *  user-supplied content). Keeps text content intact.
+ *
+ *  Entities are decoded in a single pass with `&amp;` LAST: decoding it first
+ *  would double-decode (`&amp;lt;` → `&lt;` → `<`). Numeric entities
+ *  (`&#39;`, `&#x27;`) are handled too, since escaped user/code content can
+ *  carry them and they'd otherwise leak literally into the fallback message. */
+export function stripHtml(html: string): string {
+  return html
+    .replace(/<\/?[a-z][^>]*>/gi, '')
+    .replace(/&#(\d+);/g, (_, dec: string) => safeFromCodePoint(parseInt(dec, 10)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex: string) => safeFromCodePoint(parseInt(hex, 16)))
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, '&');
+}
+
+/** Decode a numeric entity's code point, leaving an out-of-range/invalid value
+ *  untouched (return empty) rather than throwing. */
+function safeFromCodePoint(cp: number): string {
+  if (!Number.isFinite(cp) || cp < 0 || cp > 0x10ffff) return '';
+  try {
+    return String.fromCodePoint(cp);
+  } catch {
+    return '';
+  }
+}
+
+export function truncate(s: string, n: number): string {
+  return s.length <= n ? s : s.slice(0, n) + '…';
+}