@moxxy/plugin-telegram 0.43.0 → 0.45.0

package/src/channel/callback-handler.ts

@@ -7,6 +7,7 @@ import type { TelegramPermissionResolver } from '../permission.js';
 import type { TelegramApprovalResolver } from '../approval.js';
 import type { TelegramModel } from './model.js';
 import { PROVIDER_PREFIX, modelScreen, providerScreen } from './model-picker.js';
+import { QUESTION_BUTTON_PREFIX, type ChatQuestions } from '@moxxy/channel-kit';
 
 export interface AwaitingApprovalText {
   approvalId: string;
@@ -21,6 +22,8 @@ export interface CallbackState {
   readonly approvalResolver: TelegramApprovalResolver;
   /** Pairing gate — the same authorization check the text/voice handlers enforce. */
   readonly pairing: { isAuthorized(chatId: number): boolean };
+  /** The conversation's open Questions, answered by their buttons. */
+  readonly questions: Pick<ChatQuestions, 'press'>;
 }
 
 export interface CallbackCallbacks {
@@ -33,6 +36,7 @@ export interface CallbackCallbacks {
 /** Inline-keyboard callback router. Dispatches by prefix:
  *  - `perm:`   → permission resolver
  *  - `appr:`   → approval resolver
+ *  - `q:`      → a Question's answer buttons
  *  - `mprov:`  → the model picker's screens (a provider's models, or back)
  *  - `model:`  → this bot's model (`provider::model` or `default`)
  *  - `mode:`   → mode switch
@@ -69,6 +73,12 @@ export async function handleCallback(
     await handleAppr(ctx, data, state, cb);
     return;
   }
+  if (data.startsWith(QUESTION_BUTTON_PREFIX)) {
+    // Answer the click at once (the card itself shows what changed).
+    await ctx.answerCallbackQuery();
+    await state.questions.press(data);
+    return;
+  }
   if (data.startsWith(PROVIDER_PREFIX)) {
     await showPickerScreen(ctx, data.slice(PROVIDER_PREFIX.length), cb);
     return;

package/src/channel/frame-pump.ts

@@ -12,6 +12,8 @@ export interface FramePumpLogger {
 export interface FramePumpOptions {
   readonly editFrameMs: number;
   readonly logger?: FramePumpLogger;
+  /** The name of the agent of the session's active agent connection ("Codex"), read when a frame is drawn. */
+  readonly agentName?: () => string | undefined;
 }
 
 /**
@@ -31,12 +33,13 @@ export class FramePump {
   private readonly editFrameMs: number;
   private readonly logger?: FramePumpLogger;
   private bot: Bot | null = null;
-  private renderer: TurnRenderer = new TurnRenderer();
+  private readonly renderer: TurnRenderer;
   private pump: StreamPump<number> | null = null;
 
   constructor(opts: FramePumpOptions) {
     this.editFrameMs = opts.editFrameMs;
     if (opts.logger) this.logger = opts.logger;
+    this.renderer = new TurnRenderer(opts.agentName ? { agentName: opts.agentName } : {});
   }
 
   attachBot(bot: Bot | null): void {
@@ -59,7 +62,7 @@ export class FramePump {
       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 })),
+      frame: (final) => composeFrame(this.renderer.snapshot({ 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>',

package/src/channel/mirror.ts

@@ -4,7 +4,7 @@ import { sendMarkdown, type TelegramSender } from './send-rich.js';
 export type { TelegramSender } from './send-rich.js';
 
 export interface TelegramMirrorOptions {
-  readonly turns: Pick<TurnCoordinator, 'mirrorPrompt' | 'mirrorText'>;
+  readonly turns: Pick<TurnCoordinator, 'mirrorPrompt' | 'mirrorText' | 'mirrorAgentTurn' | 'mirrorHelperAnswer' | 'mirrorNoReply'>;
   /** The running bot's API, or null while it is stopped. */
   readonly api: () => TelegramSender | null;
   /** The paired chat, or null while unpaired. */
@@ -30,6 +30,7 @@ export function createTelegramMirror(opts: TelegramMirrorOptions): {
       if (api) await sendMarkdown(api, chatId, text);
     },
     formatPrompt: (prompt) => `_typed in moxxy:_ ${prompt}`,
+    formatAgentTurn: (name) => `_agent continued:_ ${name}`,
     onError: (err) => opts.logger?.warn('telegram mirror failed', { err: String(err) }),
   });
   return { mirror, target };

package/src/channel/question-cards.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Question cards in Telegram: a card goes out with an inline keyboard, picks
+ * edit it in place, and a closed question loses its buttons. The Bot API is
+ * the boundary, so it is the one thing faked here.
+ */
+import { describe, expect, it } from 'vitest';
+import type { QuestionCard } from '@moxxy/channel-kit';
+import { TelegramQuestionCards, type QuestionCardApi } from './question-cards.js';
+
+function fakeApi() {
+  const calls: Array<{ method: string; chatId: number; messageId?: number; text: string; keyboard: unknown }> = [];
+  const api: QuestionCardApi = {
+    sendMessage: async (chatId, text, other) => {
+      calls.push({ method: 'send', chatId, text, keyboard: other?.reply_markup?.inline_keyboard });
+      return { message_id: 41 + calls.length };
+    },
+    editMessageText: async (chatId, messageId, text, other) => {
+      calls.push({ method: 'edit', chatId, messageId, text, keyboard: other?.reply_markup?.inline_keyboard });
+      return true;
+    },
+  };
+  return { api, calls };
+}
+
+const card = (text: string, rows: QuestionCard['rows']): QuestionCard => ({ questionId: 'qa', text, rows });
+const red = { kind: 'answer' as const, label: 'Red', data: 'q:qa:0:0', chosen: false };
+
+describe('TelegramQuestionCards', () => {
+  it('sends a new card with its buttons, edits it on a pick and drops the buttons once it closes', async () => {
+    const { api, calls } = fakeApi();
+    const cards = new TelegramQuestionCards({ api: () => api, chatId: () => 7 });
+
+    await cards.render({ kind: 'show', card: card('❓ Question', [[red]]) });
+    await cards.render({ kind: 'refresh', card: card('❓ Question', [[{ ...red, label: '✓ Red', chosen: true }]]) });
+    await cards.render({ kind: 'closed', card: card('✓ Answered: Red', []) });
+
+    expect(calls).toEqual([
+      { method: 'send', chatId: 7, text: '❓ Question', keyboard: [[{ text: 'Red', callback_data: 'q:qa:0:0' }]] },
+      { method: 'edit', chatId: 7, messageId: 42, text: '❓ Question', keyboard: [[{ text: '✓ Red', callback_data: 'q:qa:0:0' }]] },
+      { method: 'edit', chatId: 7, messageId: 42, text: '✓ Answered: Red', keyboard: [] },
+    ]);
+  });
+
+  it('says why a reply did not go out in a message of its own', async () => {
+    const { api, calls } = fakeApi();
+    const cards = new TelegramQuestionCards({ api: () => api, chatId: () => 7 });
+
+    await cards.render({ kind: 'problem', text: 'This question is no longer open.' });
+
+    expect(calls).toEqual([{ method: 'send', chatId: 7, text: 'This question is no longer open.', keyboard: undefined }]);
+  });
+
+  it('draws nothing before a chat is paired', async () => {
+    const { api, calls } = fakeApi();
+    const cards = new TelegramQuestionCards({ api: () => api, chatId: () => null });
+
+    await cards.render({ kind: 'show', card: card('❓ Question', [[red]]) });
+
+    expect(calls).toEqual([]);
+  });
+});

package/src/channel/question-cards.ts

@@ -0,0 +1,70 @@
+import type { QuestionCard, QuestionUpdate } from '@moxxy/channel-kit';
+import { truncate } from './html.js';
+
+// Mutable arrays: the shape grammy's `bot.api` takes.
+interface InlineKeyboardMarkup {
+  inline_keyboard: Array<Array<{ text: string; callback_data: string }>>;
+}
+
+/** The two Bot API calls a Question card needs (grammy's `bot.api` has both). */
+export interface QuestionCardApi {
+  sendMessage(
+    chatId: number,
+    text: string,
+    other?: { readonly reply_markup?: InlineKeyboardMarkup },
+  ): Promise<{ readonly message_id: number }>;
+  editMessageText(
+    chatId: number,
+    messageId: number,
+    text: string,
+    other?: { readonly reply_markup?: InlineKeyboardMarkup },
+  ): Promise<unknown>;
+}
+
+/** Telegram allows 4096 characters a message; a card stays well under it. */
+const CARD_LIMIT = 3500;
+
+/**
+ * Draws the Questions `ChatQuestions` hands over as Telegram messages: a card
+ * with an inline keyboard, edited in place as picks change and stripped of
+ * its buttons once the question closes.
+ */
+export class TelegramQuestionCards {
+  private readonly messages = new Map<string, number>();
+
+  constructor(
+    private readonly deps: {
+      readonly api: () => QuestionCardApi | null;
+      readonly chatId: () => number | null;
+      readonly logger?: { warn(msg: string, meta?: Record<string, unknown>): void };
+    },
+  ) {}
+
+  async render(update: QuestionUpdate): Promise<void> {
+    const api = this.deps.api();
+    const chatId = this.deps.chatId();
+    if (!api || chatId === null) return;
+    try {
+      if (update.kind === 'problem') {
+        await api.sendMessage(chatId, update.text);
+        return;
+      }
+      const text = truncate(update.card.text, CARD_LIMIT);
+      const markup = keyboard(update.card);
+      const messageId = this.messages.get(update.card.questionId);
+      if (update.kind === 'show' || messageId === undefined) {
+        const sent = await api.sendMessage(chatId, text, { reply_markup: markup });
+        this.messages.set(update.card.questionId, sent.message_id);
+      } else {
+        await api.editMessageText(chatId, messageId, text, { reply_markup: markup });
+      }
+      if (update.kind === 'closed') this.messages.delete(update.card.questionId);
+    } catch (err) {
+      this.deps.logger?.warn('telegram question card failed', { err: String(err) });
+    }
+  }
+}
+
+function keyboard(card: QuestionCard): InlineKeyboardMarkup {
+  return { inline_keyboard: card.rows.map((row) => row.map((button) => ({ text: button.label, callback_data: button.data }))) };
+}

package/src/channel/send-images.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import type { InputFile } from 'grammy';
+import { sendToolImages, type TelegramImageSender } from './send-images.js';
+
+function recordingApi(): { api: TelegramImageSender; calls: string[] } {
+  const calls: string[] = [];
+  const api: TelegramImageSender = {
+    sendPhoto: async (_chatId, photo) => {
+      calls.push(`photo ${photo.filename}`);
+    },
+    sendDocument: async (_chatId, document) => {
+      calls.push(`document ${document.filename}`);
+    },
+    sendMediaGroup: async (_chatId, media) => {
+      calls.push(`album ${media.map((item) => (item.media as InputFile).filename).join(',')}`);
+    },
+    sendMessage: async (_chatId, text) => {
+      calls.push(`text ${text}`);
+    },
+  };
+  return { api, calls };
+}
+
+const png = { mediaType: 'image/png', base64: Buffer.from('a').toString('base64') };
+const jpeg = { mediaType: 'image/jpeg', base64: Buffer.from('b').toString('base64') };
+
+describe('sendToolImages', () => {
+  it('sends one image as a photo', async () => {
+    const { api, calls } = recordingApi();
+    await sendToolImages(api, 1, [png]);
+    expect(calls).toEqual(['photo image-1.png']);
+  });
+
+  it('sends several images as one album', async () => {
+    const { api, calls } = recordingApi();
+    await sendToolImages(api, 1, [png, jpeg]);
+    expect(calls).toEqual(['album image-1.png,image-2.jpg']);
+  });
+
+  it('sends an image Telegram does not show as a photo as a file', async () => {
+    const { api, calls } = recordingApi();
+    await sendToolImages(api, 1, [png, { mediaType: 'image/gif', base64: 'AAAA' }]);
+    expect(calls).toEqual(['photo image-1.png', 'document image-2.gif']);
+  });
+
+  it('says how many images were left out', async () => {
+    const { api, calls } = recordingApi();
+    const many = Array.from({ length: 12 }, (_, i) => ({ mediaType: 'image/png', base64: Buffer.from(`i${i}`).toString('base64') }));
+    await sendToolImages(api, 1, many);
+    expect(calls).toHaveLength(2);
+    expect(calls[1]).toBe('text <i>2 more images not sent (too many or too large).</i>');
+  });
+
+  it('logs a failed upload and goes on', async () => {
+    const { api, calls } = recordingApi();
+    const warnings: string[] = [];
+    await sendToolImages(
+      { ...api, sendMediaGroup: async () => Promise.reject(new Error('flood')) },
+      1,
+      [png, jpeg],
+      { warn: (msg) => warnings.push(msg) },
+    );
+    expect(calls).toEqual([]);
+    expect(warnings).toEqual(['telegram image upload failed']);
+  });
+});

package/src/channel/send-images.ts

@@ -0,0 +1,75 @@
+import { InputFile } from 'grammy';
+import { imageUploads, type ImageUpload, type ImageUploadLimits } from '@moxxy/channel-kit';
+import type { ToolImage } from '@moxxy/sdk';
+
+/** The slice of grammy's `Api` sending a turn's images needs (the real client satisfies it). */
+export interface TelegramImageSender {
+  sendPhoto(chatId: number, photo: InputFile): Promise<unknown>;
+  sendDocument(chatId: number, document: InputFile): Promise<unknown>;
+  sendMediaGroup(chatId: number, media: ReadonlyArray<{ type: 'photo'; media: InputFile }>): Promise<unknown>;
+  sendMessage(chatId: number, text: string, opts?: { parse_mode?: 'HTML' }): Promise<unknown>;
+}
+
+/**
+ * An album holds 10 photos and a photo may be 10 MB; a turn sends its latest
+ * 10 images. Bot API uploads are capped at 50 MB per request.
+ */
+export const TELEGRAM_IMAGE_LIMITS: ImageUploadLimits = {
+  perMessage: 10,
+  maxMessageBytes: 50_000_000,
+  maxFileBytes: 10_000_000,
+  maxImages: 10,
+};
+
+/** Types Telegram shows as a photo; any other image goes out as a file. */
+const PHOTO_TYPES = new Set(['image/png', 'image/jpeg', 'image/jpg', 'image/webp']);
+
+export interface SendImagesLogger {
+  warn(msg: string, meta?: Record<string, unknown>): void;
+}
+
+/**
+ * Send the images tools returned in a turn under its reply: one as a photo,
+ * several as an album, an image Telegram cannot show as a photo as a file.
+ * A failed upload is logged and the rest still go; images left out (too many,
+ * too large) are counted in one line.
+ */
+export async function sendToolImages(
+  api: TelegramImageSender,
+  chatId: number,
+  images: ReadonlyArray<ToolImage>,
+  logger?: SendImagesLogger,
+): Promise<void> {
+  const { batches, left } = imageUploads(images, TELEGRAM_IMAGE_LIMITS);
+  for (const batch of batches) {
+    try {
+      if (batch.length > 1 && batch.every(isPhoto)) {
+        await api.sendMediaGroup(chatId, batch.map((file) => ({ type: 'photo' as const, media: inputFile(file) })));
+      } else {
+        for (const file of batch) {
+          if (isPhoto(file)) await api.sendPhoto(chatId, inputFile(file));
+          else await api.sendDocument(chatId, inputFile(file));
+        }
+      }
+    } catch (err) {
+      logger?.warn('telegram image upload failed', { err: String(err) });
+    }
+  }
+  if (left > 0) {
+    try {
+      await api.sendMessage(chatId, `<i>${left} more image${left === 1 ? '' : 's'} not sent (too many or too large).</i>`, {
+        parse_mode: 'HTML',
+      });
+    } catch (err) {
+      logger?.warn('telegram image note failed', { err: String(err) });
+    }
+  }
+}
+
+function isPhoto(file: ImageUpload): boolean {
+  return PHOTO_TYPES.has(file.mediaType);
+}
+
+function inputFile(file: ImageUpload): InputFile {
+  return new InputFile(file.bytes, file.name);
+}

package/src/channel/slash-handler.ts

@@ -158,7 +158,7 @@ async function renderModelPicker(ctx: Context, model: Pick<TelegramModel, 'choic
 }
 
 async function renderModePicker(ctx: Context, session: Session): Promise<void> {
-  // Special modes (e.g. collaborative, entered via /collab) are hidden from the
+  // Special modes 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) {

package/src/channel/text-handler.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, it, vi } from 'vitest';
 import type { Context } from 'grammy';
 import type { ChannelHandle } from '@moxxy/sdk';
 import { Session } from '@moxxy/core';
+import { ChatQuestions } from '@moxxy/channel-kit';
+import { defineTool, z, type QuestionOutcome } from '@moxxy/sdk';
 import {
   handleTextMessage,
   type TextHandlerCallbacks,
@@ -72,6 +74,7 @@ const makeHarness = (over: Partial<TextHandlerState> = {}): Harness => {
     } as never,
     permissionResolver: { abortAll: vi.fn() } as never,
     framePump: { resetRenderer: vi.fn() } as never,
+    questions: new ChatQuestions(() => state.session),
   };
   const tryHostPair = vi.fn(async () => false);
   const cb: TextHandlerCallbacks = {
@@ -155,6 +158,37 @@ describe('handleTextMessage — single-flight busy guard', () => {
   });
 });
 
+describe('handleTextMessage — a reply to an open Question', () => {
+  it('answers the Question with the reply, even while the turn that asked runs', async () => {
+    const h = makeHarness({ busy: true });
+    const session = h.state.session;
+    if (!session) throw new Error('expected a session');
+    session.tools.register(
+      defineTool({
+        name: 'asks',
+        description: 'Asks the person.',
+        inputSchema: z.object({}),
+        handler: async (_input, ctx) =>
+          ctx.ask
+            ? ctx.ask([
+                { id: 'q1', question: 'Which colour?', options: [{ id: 'red', label: 'Red' }], multiSelect: false, allowOther: true },
+              ])
+            : 'no ask',
+      }),
+    );
+    h.deps.questions.attach(() => undefined);
+    const asked = session.tools.execute('asks', {}, new AbortController().signal, { turnId: 't1' }) as Promise<QuestionOutcome>;
+    await new Promise((resolve) => setImmediate(resolve));
+    const { ctx, replies } = fakeCtx({ text: 'Teal' });
+
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+
+    await expect(asked).resolves.toEqual({ kind: 'answered', answers: { q1: { selected: [], other: 'Teal' } } });
+    expect(h.runUserTurn).not.toHaveBeenCalled();
+    expect(replies).toEqual([]);
+  });
+});
+
 describe('handleTextMessage — awaiting approval text (captured BEFORE busy)', () => {
   it('captures the next message as approval text even while busy, and clears the latch', async () => {
     const awaiting: AwaitingApprovalText = { approvalId: 'appr_1', optionId: 'redraft' };

package/src/channel/text-handler.ts

@@ -4,7 +4,7 @@ import type { TelegramApprovalResolver } from '../approval.js';
 import type { TelegramPermissionResolver } from '../permission.js';
 import type { ChannelHandle } from '@moxxy/sdk';
 import type { FramePump } from './frame-pump.js';
-import { applySessionAction } from '@moxxy/channel-kit';
+import { applySessionAction, type ChatQuestions } from '@moxxy/channel-kit';
 import { runSlash } from './slash-handler.js';
 import type { TelegramModel } from './model.js';
 import type { AwaitingApprovalText } from './callback-handler.js';
@@ -24,6 +24,8 @@ export interface TextHandlerDeps {
   readonly approvalResolver: TelegramApprovalResolver;
   readonly permissionResolver: TelegramPermissionResolver;
   readonly framePump: FramePump;
+  /** The conversation's open Questions; a plain reply answers the latest one. */
+  readonly questions: Pick<ChatQuestions, 'typed'>;
 }
 
 export interface TextHandlerCallbacks {
@@ -44,7 +46,7 @@ export interface TextHandlerCallbacks {
 
 /**
  * Top-level dispatch for inbound text messages: authorization gate,
- * awaiting-approval-text capture, /cancel, slash routing, and finally
+ * awaiting-approval-text capture, a reply to an open Question, /cancel, slash routing, and finally
  * the user-turn path.
  */
 export async function handleTextMessage(
@@ -82,6 +84,10 @@ export async function handleTextMessage(
     return;
   }
 
+  // A reply to an open Question answers it; the turn that asked waits on it,
+  // so this too comes before the busy guard.
+  if (!text.startsWith('/') && (await deps.questions.typed(text))) return;
+
   // /cancel works even while busy; everything else routes through
   // runSlash or the user-turn path.
   if (text === '/cancel') {

package/src/channel/turn-runner.test.ts

@@ -20,13 +20,15 @@ function recordingSession() {
 
 const typing = { start: () => undefined, stop: () => undefined } as never;
 
-function pumpWith(body: string) {
+function pumpWith(body: string, images: ReadonlyArray<{ mediaType: string; base64: string }> = [], order: string[] = []) {
   return {
     beginTurn: () => undefined,
     endTurn: () => undefined,
     scheduleEdit: () => undefined,
-    flush: async () => undefined,
-    renderState: { accept: () => ({ hasUpdate: false }), snapshot: () => ({ body }) },
+    flush: async (final: boolean) => {
+      if (final) order.push('reply');
+    },
+    renderState: { accept: () => ({ hasUpdate: false }), snapshot: () => ({ body }), images: () => images },
   } as never;
 }
 
@@ -82,3 +84,24 @@ describe('/voice decides whether a Telegram reply is spoken', () => {
     expect(spoken).toEqual([]);
   });
 });
+
+describe('images tools returned in a Telegram turn', () => {
+  it('go out as photos after the reply', async () => {
+    const { session } = recordingSession();
+    const order: string[] = [];
+    const png = { mediaType: 'image/png', base64: Buffer.from('png').toString('base64') };
+    const bot = {
+      api: {
+        sendPhoto: async (chatId: number) => {
+          order.push(`photo to ${chatId}`);
+        },
+      },
+    } as never;
+    await runUserTurn(
+      { reply: async () => undefined } as unknown as Context,
+      { session, bot, framePump: pumpWith('Here it is.', [png], order), typing },
+      { chatId: 42, text: 'hi', model: undefined, controller: new AbortController(), turnId: asTurnId('t2') },
+    );
+    expect(order).toEqual(['reply', 'photo to 42']);
+  });
+});

package/src/channel/turn-runner.ts

@@ -4,6 +4,7 @@ import type { ClientSession as Session } from '@moxxy/sdk';
 import { channelTurnContext, driveTurn, subscribeTurn } from '@moxxy/channel-kit';
 import type { FramePump } from './frame-pump.js';
 import type { TypingIndicator } from './typing-indicator.js';
+import { sendToolImages } from './send-images.js';
 
 export interface TurnRunnerLogger {
   warn(msg: string, meta?: Record<string, unknown>): void;
@@ -92,6 +93,8 @@ export async function runUserTurn(
       signal: controller.signal,
     });
     await framePump.flush(true);
+    // The images tools returned go out under the reply.
+    if (bot) await sendToolImages(bot.api, chatId, framePump.renderState.images(), logger);
     // The text reply is now out. Speak the final assistant body if a voice
     // reply is wired — isolated so a synth/transcode/transport failure can
     // never break (or re-report) the already-delivered text turn.

package/src/channel.ts

@@ -3,6 +3,8 @@ import type { Context } from 'grammy';
 import { newTurnId } from '@moxxy/core';
 import {
   AutoApproveSwitch,
+  activeAgentName,
+  ChatQuestions,
   TurnCoordinator,
   deliverVoiceReply,
   resolveSecret,
@@ -37,6 +39,7 @@ import { handleVoiceMessage } from './channel/voice-handler.js';
 import { loadVoiceReplies, saveVoiceReplies } from './keys.js';
 import { createTelegramMirror } from './channel/mirror.js';
 import { telegramModel, type TelegramModel } from './channel/model.js';
+import { TelegramQuestionCards } from './channel/question-cards.js';
 
 const TOKEN_KEY = 'telegram_bot_token';
 
@@ -130,13 +133,24 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
   private readonly framePump: FramePump;
   private readonly typing = new TypingIndicator();
   private readonly pairing: PairingHandler;
+  // The conversation's Questions, drawn as cards with answer buttons.
+  private readonly questions = new ChatQuestions(() => this.session);
+  private readonly questionCards: TelegramQuestionCards;
+  private detachQuestions: (() => void) | null = null;
 
   constructor(opts: TelegramChannelOptions) {
     this.opts = opts;
     this.permissionResolver = new TelegramPermissionResolver();
     this.approvalResolver = new TelegramApprovalResolver();
+    this.questionCards = new TelegramQuestionCards({
+      api: () => (this.bot ? this.bot.api : null),
+      chatId: () => this.currentChatId,
+      ...(opts.logger ? { logger: opts.logger } : {}),
+    });
     this.framePump = new FramePump({
       editFrameMs: opts.editFrameMs ?? 1000,
+      // The agent's name comes from the session, so every surface names the same agent.
+      agentName: () => (this.session ? activeAgentName(this.session.getInfo()) : undefined),
       ...(opts.logger ? { logger: opts.logger } : {}),
     });
     this.pairing = new PairingHandler({
@@ -235,6 +249,7 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
     // this channel. setApprovalResolver(null) on stop tears it down so
     // headless code paths after channel close don't see a stale handler.
     this.session.setApprovalResolver(this.approvalResolver);
+    this.detachQuestions = this.questions.attach((update) => void this.questionCards.render(update));
 
     // Mirror-to-both: a turn this channel did NOT initiate (a message written
     // in the desktop's chat with this bot) shows here — its prompt, then its
@@ -334,6 +349,8 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
         this.approvalResolver.abortAll(reason);
         this.logUnsub?.();
         this.logUnsub = null;
+        this.detachQuestions?.();
+        this.detachQuestions = null;
         if (this.session) this.session.setApprovalResolver(null);
         this.framePump.endTurn();
         this.typing.stop();
@@ -394,6 +411,7 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
         approvalResolver: this.approvalResolver,
         permissionResolver: this.permissionResolver,
         framePump: this.framePump,
+        questions: this.questions,
       },
       {
         setAwaitingApprovalText: (state) => {
@@ -563,6 +581,7 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
         permissionResolver: this.permissionResolver,
         approvalResolver: this.approvalResolver,
         pairing: this.pairing,
+        questions: this.questions,
       },
       {
         setAwaitingApprovalText: (state) => {

package/src/permission.test.ts

@@ -34,6 +34,25 @@ describe('TelegramPermissionResolver', () => {
     expect(decider).toHaveBeenCalledTimes(1);
   });
 
+  // Allowing Safari for the session must not let a later request for Terminal through.
+  it('remembers allow_session only for the same request when the tool narrows it', async () => {
+    const r = new TelegramPermissionResolver();
+    const decider = vi.fn(async () => {});
+    r.setDecider(decider);
+    const narrowed = { ...ctx, toolPermission: { action: 'prompt' as const, sessionScope: { inputKeys: ['apps'] } } };
+    const access = (apps: string[], id: string) => ({ callId: asToolCallId(id), name: 'computer_request_access', input: { apps } });
+
+    const first = r.check(access(['Safari'], 'a1'), narrowed);
+    r.resolvePending('a1', { mode: 'allow_session' });
+    await first;
+    await r.check(access(['Safari'], 'a2'), narrowed);
+    expect(decider).toHaveBeenCalledTimes(1);
+
+    void r.check(access(['Terminal'], 'a3'), narrowed);
+    await vi.waitFor(() => expect(decider).toHaveBeenCalledTimes(2));
+    r.abortAll();
+  });
+
   it('abortAll resolves pending checks as deny', async () => {
     const r = new TelegramPermissionResolver();
     r.setDecider(async () => {});

package/src/permission.ts

@@ -1,3 +1,4 @@
+import { createSessionGrants } from '@moxxy/sdk';
 import type { PendingToolCall, PermissionContext, PermissionDecision, PermissionResolver } from '@moxxy/sdk';
 
 export interface PendingPermission {
@@ -16,7 +17,8 @@ export interface PendingPermission {
 export class TelegramPermissionResolver implements PermissionResolver {
   readonly name = 'telegram';
   private readonly pending = new Map<string, PendingPermission>();
-  private readonly sessionAllows = new Set<string>();
+  // Same rules as the desktop: a tool that narrows its grant is remembered per request.
+  private readonly grants = createSessionGrants();
   private deciderFn:
     | ((call: PendingToolCall, ctx: PermissionContext) => Promise<void>)
     | null = null;
@@ -26,7 +28,7 @@ export class TelegramPermissionResolver implements PermissionResolver {
   }
 
   async check(call: PendingToolCall, ctx: PermissionContext): Promise<PermissionDecision> {
-    if (this.sessionAllows.has(call.name)) {
+    if (this.grants.covers(call)) {
       return { mode: 'allow_session', reason: 'allow_session previously granted' };
     }
     if (!this.deciderFn) {
@@ -40,7 +42,7 @@ export class TelegramPermissionResolver implements PermissionResolver {
         resolve({ mode: 'deny', reason: err instanceof Error ? err.message : String(err) });
       });
     });
-    if (decision.mode === 'allow_session') this.sessionAllows.add(call.name);
+    if (decision.mode === 'allow_session') this.grants.remember(call, decision, ctx);
     return decision;
   }