@moxxy/plugin-telegram 0.41.2 → 0.42.0

package/src/channel/text-handler.ts

@@ -4,15 +4,14 @@ 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 { runSlash } from './slash-handler.js';
+import type { TelegramModel } from './model.js';
 import type { AwaitingApprovalText } from './callback-handler.js';
 import type { PairingHandler } from './pairing-handler.js';
 
 export interface TextHandlerState {
   readonly session: Session | null;
-  readonly model: string | undefined;
-  readonly activeModelOverride: string | null;
-  readonly yolo: boolean;
   readonly voiceReplies: boolean;
   readonly busy: boolean;
   readonly turnController: AbortController | null;
@@ -29,9 +28,13 @@ export interface TextHandlerDeps {
 
 export interface TextHandlerCallbacks {
   readonly setAwaitingApprovalText: (state: AwaitingApprovalText | null) => void;
-  readonly toggleYolo: () => boolean;
+  /** `/auto-approve` — switch the conversation's shared auto-approve. */
+  readonly toggleYolo: () => Promise<boolean>;
+  /** Drop the bot-local auto-approve flag (a `/new` conversation starts with it off). */
   readonly setYolo: (value: boolean) => void;
   readonly setVoiceReplies: (on: boolean) => Promise<void>;
+  /** This bot's own model (`/model`). */
+  readonly model: Pick<TelegramModel, 'run' | 'choices'>;
   readonly runUserTurn: (ctx: Context, chatId: number, text: string) => Promise<void>;
   /** Host-issued pairing fallback: try to pair an unauthorized chat whose message
    *  is the 6-digit code. Returns true when handled (so we skip the generic
@@ -95,16 +98,11 @@ export async function handleTextMessage(
     await runSlash(
       ctx,
       text,
-      {
-        session: state.session,
-        model: state.model,
-        activeModelOverride: state.activeModelOverride,
-        yolo: state.yolo,
-        voiceReplies: state.voiceReplies,
-      },
+      { session: state.session, voiceReplies: state.voiceReplies },
       {
         toggleYolo: cb.toggleYolo,
         setVoiceReplies: cb.setVoiceReplies,
+        model: cb.model,
         performSessionAction: (c, action, notice) =>
           performSessionAction(c, action, notice, state, deps, cb),
       },
@@ -121,10 +119,8 @@ export async function handleTextMessage(
 }
 
 /**
- * Channel-side handler for `session-action` outputs from registered
- * commands. The TUI does the same thing; both channels translate the
- * action into their own UI semantics (Telegram = reply text, Ink =
- * setState + exit).
+ * Channel-side handler for `session-action` outputs from registered commands
+ * (`applySessionAction` in @moxxy/channel-kit, shared with the other bots).
  */
 async function performSessionAction(
   ctx: Context,
@@ -134,41 +130,21 @@ async function performSessionAction(
   deps: TextHandlerDeps,
   cb: TextHandlerCallbacks,
 ): Promise<void> {
-  if (!state.session) return;
-  if (action === 'exit') {
-    await ctx.reply(notice ?? 'closing Telegram channel');
-    if (state.handle) await state.handle.stop('user /exit');
-    return;
-  }
-  if (action === 'clear') {
-    deps.framePump.resetRenderer();
-    if (notice) await ctx.reply(`✓ ${notice}`);
-    return;
-  }
-  if (action === 'new') {
-    if (state.turnController && !state.turnController.signal.aborted) {
-      state.turnController.abort('user reset');
-    }
-    deps.framePump.resetRenderer();
-    cb.setYolo(false);
-    cb.setAwaitingApprovalText(null);
-    deps.approvalResolver.abortAll('session reset');
-    deps.permissionResolver.abortAll('session reset');
-    // Wipe the history at its source. On a RemoteSession `reset()` asks the
-    // runner to clear its authoritative log (and persisted JSONL) and
-    // re-sync every attached mirror; on a local Session it clears the
-    // EventLog + truncates the sidecar. A mirror-only `log.clear()` would
-    // be cosmetic AND desync this client, so only claim success when the
-    // reset actually happened.
-    try {
-      if (typeof state.session.reset === 'function') await state.session.reset();
-      else state.session.log.clear();
-    } catch (err) {
-      await ctx.reply(
-        `⚠ /new failed: ${err instanceof Error ? err.message : String(err)} — history NOT cleared`,
-      );
-      return;
-    }
-    await ctx.reply(`✓ ${notice ?? 'new session — conversation history cleared'}`);
-  }
+  const reply = await applySessionAction(action, notice, {
+    session: state.session,
+    turnController: state.turnController,
+    handle: state.handle,
+    channelName: 'Telegram',
+    abortPending: (reason) => {
+      deps.approvalResolver.abortAll(reason);
+      deps.permissionResolver.abortAll(reason);
+    },
+    onReset: (kind) => {
+      deps.framePump.resetRenderer();
+      if (kind !== 'new') return;
+      cb.setYolo(false);
+      cb.setAwaitingApprovalText(null);
+    },
+  });
+  await ctx.reply(reply);
 }

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

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import { asTurnId, type MoxxyEvent, type RunTurnOptions } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { Context } from 'grammy';
+import { TELEGRAM_TURN_CONTEXT, TELEGRAM_VOICE_CONTEXT, runUserTurn } from './turn-runner.js';
+
+function recordingSession() {
+  const runs: RunTurnOptions[] = [];
+  const session = {
+    log: { subscribe: () => () => undefined },
+    runTurn: (_prompt: string, opts: RunTurnOptions) => {
+      runs.push(opts);
+      return (async function* () {
+        yield undefined as unknown as MoxxyEvent;
+      })();
+    },
+  } as unknown as Session;
+  return { session, runs };
+}
+
+const typing = { start: () => undefined, stop: () => undefined } as never;
+
+function pumpWith(body: string) {
+  return {
+    beginTurn: () => undefined,
+    endTurn: () => undefined,
+    scheduleEdit: () => undefined,
+    flush: async () => undefined,
+    renderState: { accept: () => ({ hasUpdate: false }), snapshot: () => ({ body }) },
+  } as never;
+}
+
+async function run(opts: { spoken?: boolean } = {}, spoken: string[] = []) {
+  const { session, runs } = recordingSession();
+  const deps = {
+    session,
+    bot: null,
+    framePump: pumpWith('Cześć!'),
+    typing,
+    speakReply: async (text: string) => {
+      spoken.push(text);
+    },
+  };
+  await runUserTurn({ reply: async () => undefined } as unknown as Context, deps, {
+    chatId: 42,
+    text: 'hi',
+    model: 'a-large',
+    controller: new AbortController(),
+    turnId: asTurnId('t1'),
+    ...opts,
+  });
+  return runs[0];
+}
+
+describe('a Telegram turn tells the model where it replies', () => {
+  it('passes the Telegram context with the model the bot runs', async () => {
+    const opts = await run();
+
+    expect(opts?.systemPrompt).toBe(TELEGRAM_TURN_CONTEXT);
+    expect(opts?.model).toBe('a-large');
+    expect(TELEGRAM_TURN_CONTEXT).toContain('`telegram_send_message` with `files:');
+  });
+
+  it('asks for a short spoken answer when the prompt was a voice message', async () => {
+    const opts = await run({ spoken: true });
+
+    expect(opts?.systemPrompt).toBe(`${TELEGRAM_TURN_CONTEXT}\n\n${TELEGRAM_VOICE_CONTEXT}`);
+    expect(TELEGRAM_VOICE_CONTEXT).toMatch(/voice message/);
+  });
+});
+
+describe('/voice decides whether a Telegram reply is spoken', () => {
+  it('sends the reply as a voice note while voice replies are on', async () => {
+    const spoken: string[] = [];
+    await run({ spoken: true }, spoken);
+    expect(spoken).toEqual(['Cześć!']);
+  });
+
+  it('answers in text only while voice replies are off, even to a voice message', async () => {
+    const spoken: string[] = [];
+    await run({}, spoken);
+    expect(spoken).toEqual([]);
+  });
+});

package/src/channel/turn-runner.ts

@@ -1,7 +1,7 @@
 import type { Bot, Context } from 'grammy';
 import type { newTurnId } from '@moxxy/core';
 import type { ClientSession as Session } from '@moxxy/sdk';
-import { driveTurn, subscribeTurn } from '@moxxy/channel-kit';
+import { channelTurnContext, driveTurn, subscribeTurn } from '@moxxy/channel-kit';
 import type { FramePump } from './frame-pump.js';
 import type { TypingIndicator } from './typing-indicator.js';
 
@@ -16,16 +16,32 @@ export interface TurnRunnerDeps {
   readonly typing: TypingIndicator;
   readonly logger?: TurnRunnerLogger;
   /**
-   * Called once with the FINAL assistant text after it has been flushed to the
-   * chat (so the text reply always lands first). Backs the optional voice
-   * reply. Best-effort — its failure is logged and never breaks the text turn.
+   * Sends the FINAL assistant text as a voice note after it has been flushed to
+   * the chat (so the text reply always lands first), on a `spoken` turn only.
+   * Best-effort — its failure is logged and never breaks the text turn.
    */
-  readonly onFinalReply?: (text: string) => Promise<void>;
+  readonly speakReply?: (text: string) => Promise<void>;
 }
 
+/** What the model must know about replying on Telegram (see channelTurnContext). */
+export const TELEGRAM_TURN_CONTEXT = channelTurnContext({
+  service: 'Telegram',
+  sendTool: 'telegram_send_message',
+  delivery: 'their Telegram chat with the bot',
+  uploadLimit: '50 MB per file',
+});
+
+/** Added while voice replies are on: the reply goes back as a voice message too. */
+export const TELEGRAM_VOICE_CONTEXT =
+  'Your reply will also be sent back as a voice message, read ' +
+  'aloud: answer briefly, in plain spoken sentences, without markdown, code blocks, tables or links. ' +
+  'Speak in the language of the request.';
+
 export interface TurnRunnerOptions {
   readonly chatId: number;
   readonly text: string;
+  /** Voice replies are on (`/voice`): the reply is also spoken back. */
+  readonly spoken?: boolean;
   readonly model: string | undefined;
   readonly controller: AbortController;
   /** turnId for this turn. The channel mints it so it can also record it as an
@@ -46,7 +62,7 @@ export async function runUserTurn(
   deps: TurnRunnerDeps,
   opts: TurnRunnerOptions,
 ): Promise<void> {
-  const { session, bot, framePump, typing, logger, onFinalReply } = deps;
+  const { session, bot, framePump, typing, logger, speakReply } = deps;
   const { chatId, text, model, controller, turnId } = opts;
 
   framePump.beginTurn(chatId);
@@ -68,16 +84,22 @@ export async function runUserTurn(
   });
 
   try {
-    await driveTurn(session, { turnId, prompt: text, model, signal: controller.signal });
+    await driveTurn(session, {
+      turnId,
+      prompt: text,
+      model,
+      systemPrompt: opts.spoken ? `${TELEGRAM_TURN_CONTEXT}\n\n${TELEGRAM_VOICE_CONTEXT}` : TELEGRAM_TURN_CONTEXT,
+      signal: controller.signal,
+    });
     await framePump.flush(true);
     // 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.
-    if (onFinalReply) {
+    if (opts.spoken && speakReply) {
       const finalText = framePump.renderState.snapshot().body;
       if (finalText.trim()) {
         try {
-          await onFinalReply(finalText);
+          await speakReply(finalText);
         } catch (err) {
           logger?.warn('telegram voice reply hook failed', {
             err: err instanceof Error ? err.message : String(err),

package/src/channel/voice-handler.ts

@@ -194,5 +194,7 @@ export async function handleVoiceMessage(
   // reply.
   await ctx.reply(`_heard:_ ${transcript}`, { parse_mode: 'Markdown' });
 
+  // The transcript is a prompt like any other: `/voice` decides whether the
+  // reply is spoken back.
   await cb.runUserTurn(ctx, chatId, transcript);
 }

package/src/channel/voice-reply.test.ts

@@ -8,6 +8,7 @@ import type { ClientSession as Session } from '@moxxy/sdk';
 import { loadVoiceReplies, saveVoiceReplies, TELEGRAM_VOICE_REPLIES_KEY } from '../keys.js';
 import { runSlash } from './slash-handler.js';
 import { runUserTurn } from './turn-runner.js';
+import { removeDir } from '@moxxy/vitest-preset/fs';
 
 describe('telegram voice-replies vault flag round-trip', () => {
   let tmp: string;
@@ -21,7 +22,7 @@ describe('telegram voice-replies vault flag round-trip', () => {
     });
   });
   afterEach(async () => {
-    await fs.rm(tmp, { recursive: true, force: true });
+    await removeDir(tmp);
   });
 
   it('defaults to off, persists on, then off', async () => {
@@ -52,7 +53,8 @@ function slashCtx(): { ctx: any; replies: string[] } {
 
 describe('/voice slash command', () => {
   const cbBase = {
-    toggleYolo: () => false,
+    toggleYolo: async () => false,
+    model: { run: async () => '', choices: async () => ({ current: null, options: [] }) },
     performSessionAction: async () => undefined,
   };
 
@@ -62,7 +64,7 @@ describe('/voice slash command', () => {
     await runSlash(
       ctx,
       '/voice on',
-      { session: slashSession({ synth: { name: 'fake' } }), model: undefined, activeModelOverride: null, yolo: false, voiceReplies: false },
+      { session: slashSession({ synth: { name: 'fake' } }), voiceReplies: false },
       { ...cbBase, setVoiceReplies: async (on: boolean) => void persisted.push(on) },
     );
     expect(persisted).toEqual([true]);
@@ -76,7 +78,7 @@ describe('/voice slash command', () => {
     await runSlash(
       ctx,
       '/voice on',
-      { session: slashSession(), model: undefined, activeModelOverride: null, yolo: false, voiceReplies: false },
+      { session: slashSession(), voiceReplies: false },
       { ...cbBase, setVoiceReplies: async (on: boolean) => void persisted.push(on) },
     );
     expect(persisted).toEqual([true]);
@@ -91,7 +93,7 @@ describe('/voice slash command', () => {
     await runSlash(
       off.ctx,
       '/voice',
-      { session: slashSession(), model: undefined, activeModelOverride: null, yolo: false, voiceReplies: true },
+      { session: slashSession(), voiceReplies: true },
       { ...cbBase, setVoiceReplies },
     );
     expect(persisted).toEqual([false]);
@@ -101,7 +103,7 @@ describe('/voice slash command', () => {
     await runSlash(
       status.ctx,
       '/voice status',
-      { session: slashSession(), model: undefined, activeModelOverride: null, yolo: false, voiceReplies: true },
+      { session: slashSession(), voiceReplies: true },
       { ...cbBase, setVoiceReplies },
     );
     // status did NOT persist anything new.
@@ -161,8 +163,8 @@ function fakeFramePump(): { framePump: any; flushedFinal: boolean[] } {
 
 const typingNoop = { start: () => {}, stop: () => {} } as any;
 
-describe('turn-runner onFinalReply seam (final assistant text)', () => {
-  it('calls onFinalReply with the final assistant body AFTER flushing the text', async () => {
+describe('turn-runner speakReply seam (final assistant text, voice replies on)', () => {
+  it('calls speakReply with the final assistant body AFTER flushing the text', async () => {
     const { framePump, flushedFinal } = fakeFramePump();
     const seen: string[] = [];
     const session = turnSession((emit) => {
@@ -176,9 +178,9 @@ describe('turn-runner onFinalReply seam (final assistant text)', () => {
         bot: null,
         framePump,
         typing: typingNoop,
-        onFinalReply: async (t) => void seen.push(t),
+        speakReply: async (t) => void seen.push(t),
       },
-      { chatId: 1, text: 'hi', model: undefined, controller: new AbortController(), turnId: asTurnId('t1') },
+      { chatId: 1, text: 'hi', model: undefined, controller: new AbortController(), turnId: asTurnId('t1'), spoken: true },
     );
     expect(flushedFinal).toContain(true);
     expect(seen).toEqual(['Hello there.']);
@@ -192,8 +194,8 @@ describe('turn-runner onFinalReply seam (final assistant text)', () => {
     });
     await runUserTurn(
       { reply: async () => {} } as any,
-      { session, bot: null, framePump, typing: typingNoop, onFinalReply: async (t) => void seen.push(t) },
-      { chatId: 1, text: 'hi', model: undefined, controller: new AbortController(), turnId: asTurnId('t2') },
+      { session, bot: null, framePump, typing: typingNoop, speakReply: async (t) => void seen.push(t) },
+      { chatId: 1, text: 'hi', model: undefined, controller: new AbortController(), turnId: asTurnId('t2'), spoken: true },
     );
     expect(seen).toEqual([]);
   });
@@ -210,11 +212,11 @@ describe('turn-runner onFinalReply seam (final assistant text)', () => {
           bot: null,
           framePump,
           typing: typingNoop,
-          onFinalReply: async () => {
+          speakReply: async () => {
             throw new Error('tts exploded');
           },
         },
-        { chatId: 1, text: 'hi', model: undefined, controller: new AbortController(), turnId: asTurnId('t3') },
+        { chatId: 1, text: 'hi', model: undefined, controller: new AbortController(), turnId: asTurnId('t3'), spoken: true },
       ),
     ).resolves.toBeUndefined();
     // No "Turn failed" reply — the hook failure was swallowed.

package/src/channel.ts

@@ -1,14 +1,20 @@
 import { Bot, GrammyError, HttpError, InputFile } from 'grammy';
 import type { Context } from 'grammy';
 import { newTurnId } from '@moxxy/core';
-import { TurnCoordinator, deliverVoiceReply, resolveSecret } from '@moxxy/channel-kit';
+import {
+  AutoApproveSwitch,
+  TurnCoordinator,
+  deliverVoiceReply,
+  resolveSecret,
+  type ForeignTurnMirror,
+  type MirrorTarget,
+} from '@moxxy/channel-kit';
 import type { ClientSession as Session } from '@moxxy/sdk';
 import type {
   ApprovalRequest,
   Channel,
   ChannelHandle,
   ChannelStartOptsBase,
-  MoxxyEvent,
   PendingToolCall,
   PermissionContext,
 } from '@moxxy/sdk';
@@ -29,6 +35,8 @@ import { runUserTurn } from './channel/turn-runner.js';
 import { handleTextMessage } from './channel/text-handler.js';
 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';
 
 const TOKEN_KEY = 'telegram_bot_token';
 
@@ -91,14 +99,15 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
   // re-publish the channel's status file. See `onConnectChange` on the handle.
   private readonly connectListeners = new Set<() => void>();
   private currentChatId: number | null = null;
-  // Last chat we ran a turn for — the target for mirroring turns this channel
-  // did NOT initiate (e.g. a web-surface action on a shared session).
-  private lastChatId: number | null = null;
+  // Turns another surface ran on this bot's session (the desktop's chat with
+  // the bot) shown here: into the chat we last served, else the paired chat.
+  private readonly mirror: ForeignTurnMirror<number>;
+  private readonly mirrorTarget: MirrorTarget<number>;
   private logUnsub: (() => void) | null = null;
   private session: Session | null = null;
   private model: string | undefined;
-  private activeModelOverride: string | null = null;
-  private yolo = false;
+  /** `/auto-approve` — the conversation's shared switch (see AutoApproveSwitch). */
+  private readonly autoApprove = new AutoApproveSwitch(() => this.session);
   // When true, the final assistant reply of each turn is also synthesized (via
   // the session's active Synthesizer) and sent as a voice note. Persisted per
   // paired chat in the vault (`telegram_voice_replies`), toggled with `/voice`.
@@ -137,6 +146,14 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
     // A completed pairing flips this channel's connect-state to "connected";
     // notify the host so it can swap the QR for a "✓ Connected" affordance.
     this.pairing.onPaired(() => this.notifyConnectChange());
+    const { mirror, target } = createTelegramMirror({
+      turns: this.turns,
+      api: () => this.bot?.api ?? null,
+      pairedChat: () => this.pairing.authorizedChatId(),
+      ...(opts.logger ? { logger: opts.logger } : {}),
+    });
+    this.mirror = mirror;
+    this.mirrorTarget = target;
   }
 
   /** This channel's connect value (see {@link Channel.requestUrl}): the resolved
@@ -219,11 +236,10 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
     // headless code paths after channel close don't see a stale handler.
     this.session.setApprovalResolver(this.approvalResolver);
 
-    // Mirror-to-both: when the session runs a turn this channel did NOT
-    // initiate (e.g. a user submitted a form on the co-attached web surface),
-    // post the assistant's prose into the last chat we served. Our OWN turns
-    // are rendered by the FramePump (gated by `busy`), so skip those.
-    this.logUnsub = this.session.log.subscribe((event) => this.mirrorForeignTurn(event));
+    // 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
+    // reply. Our OWN turns are rendered by the FramePump, so the mirror skips them.
+    this.logUnsub = this.session.log.subscribe((event) => this.mirror.accept(event));
 
     this.bot.command('start', (ctx) => this.pairing.handleStartCommand(ctx));
     this.bot.on('callback_query:data', (ctx) => this.dispatchCallback(ctx));
@@ -367,9 +383,6 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
       ctx,
       {
         session: this.session,
-        model: this.model,
-        activeModelOverride: this.activeModelOverride,
-        yolo: this.yolo,
         voiceReplies: this.voiceReplies,
         busy: this.turns.busy,
         turnController: this.turns.controller,
@@ -386,14 +399,10 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
         setAwaitingApprovalText: (state) => {
           this.awaitingApprovalText = state;
         },
-        toggleYolo: () => {
-          this.yolo = !this.yolo;
-          return this.yolo;
-        },
-        setYolo: (value) => {
-          this.yolo = value;
-        },
+        toggleYolo: () => this.autoApprove.toggle(),
+        setYolo: () => this.autoApprove.forgetLocal(),
         setVoiceReplies: (on) => this.setVoiceReplies(on),
+        model: this.pickerModel(),
         runUserTurn: (c, chatId, text) => this.runUserTurn(c, chatId, text),
         tryHostPair: (chatId, text) => this.tryHostPair(ctx, chatId, text),
       },
@@ -417,7 +426,7 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
    * unavailable), and deliver via grammy. The text reply already went out.
    */
   private async sendVoiceReply(chatId: number, text: string): Promise<void> {
-    if (!this.voiceReplies || !this.bot || !this.session) return;
+    if (!this.bot || !this.session) return;
     const bot = this.bot;
     const outcome = await deliverVoiceReply(this.session, text, {
       send: async (audio, meta) => {
@@ -464,25 +473,41 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
     });
   }
 
-  private async runUserTurn(ctx: Context, chatId: number, text: string): Promise<void> {
-    if (!this.session) throw new Error('TelegramChannel.start() must be called first');
+  /** `/model` and its picker, answering "not ready" before start(). */
+  private pickerModel(): Pick<TelegramModel, 'run' | 'choices'> {
+    return {
+      run: (arg) => this.botModel()?.run(arg) ?? Promise.resolve('Session is not ready yet.'),
+      choices: () => this.botModel()?.choices() ?? Promise.resolve({ current: null, options: [] }),
+    };
+  }
+
+  /** This bot's own model (see TelegramModel); null before start(). */
+  private botModel(): TelegramModel | null {
+    return this.session ? telegramModel({ session: this.session, vault: this.opts.vault }) : null;
+  }
+
+  private async runUserTurn(
+    ctx: Context,
+    chatId: number,
+    text: string,
+  ): Promise<void> {
+    const model = this.botModel();
+    if (!this.session || !model) throw new Error('TelegramChannel.start() must be called first');
     // Atomic single-flight guard: `begin` claims the slot synchronously BEFORE
     // any await so a second turn dispatched concurrently (the poll loop is no
     // longer parked on us) can't slip past the busy check in the text/voice
-    // handlers. If we are already busy, refuse rather than corrupt the
-    // single-instance per-turn state (framePump / currentChatId / controller).
-    // The turnId is minted here so the coordinator records it as an own-turn
-    // id — that's what mirrorForeignTurn filters on.
+    // handlers. The turnId is minted here so the coordinator records it as an
+    // own-turn id — that's what the mirror filters on.
     const lease = this.turns.begin(newTurnId());
     if (!lease) {
       await ctx.reply('I am still working on the previous prompt. Send /cancel to abort it.');
       return;
     }
     this.currentChatId = chatId;
-    this.lastChatId = chatId;
-    const effectiveModel = this.activeModelOverride ?? this.model;
-
+    this.mirrorTarget.remember(chatId);
     try {
+      const channelModel = await model.resolve();
+      if (channelModel.warning) await ctx.reply(channelModel.warning);
       await runUserTurn(
         ctx,
         {
@@ -491,9 +516,16 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
           framePump: this.framePump,
           typing: this.typing,
           ...(this.opts.logger ? { logger: this.opts.logger } : {}),
-          onFinalReply: (finalText) => this.sendVoiceReply(chatId, finalText),
+          speakReply: (finalText) => this.sendVoiceReply(chatId, finalText),
+        },
+        {
+          chatId,
+          text,
+          ...(this.voiceReplies ? { spoken: true } : {}),
+          model: channelModel.model ?? this.model,
+          controller: lease.controller,
+          turnId: lease.turnId,
         },
-        { chatId, text, model: effectiveModel, controller: lease.controller, turnId: lease.turnId },
       );
     } finally {
       lease.end();
@@ -501,32 +533,13 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
     }
   }
 
-  /**
-   * Post the assistant's prose for a turn this channel did not initiate. Gated
-   * by `!busy` (our own turns are rendered by the FramePump from the runUserTurn
-   * iterator) and by having served a chat at least once. Sent as plain text to
-   * avoid parse-mode pitfalls; the view itself lives on the web surface.
-   */
-  private mirrorForeignTurn(event: MoxxyEvent): void {
-    // The coordinator skips turns THIS channel initiated, by turnId — robust to
-    // events that arrive after `busy` flips false (async ordering /
-    // RemoteSession replay), which the `busy` flag alone could mis-mirror as
-    // foreign (invariant #8) — and yields the trimmed assistant prose.
-    const text = this.turns.mirrorText(event);
-    if (text == null) return;
-    if (!this.bot || this.lastChatId == null) return;
-    void this.bot.api.sendMessage(this.lastChatId, text).catch((err) => {
-      this.opts.logger?.warn('telegram mirror failed', { err: String(err) });
-    });
-  }
-
   private askForPermission(call: PendingToolCall, ctx: PermissionContext): Promise<void> {
     return askForPermission(call, ctx, {
       bot: this.bot,
       chatId: this.currentChatId,
       session: this.session,
       resolver: this.permissionResolver,
-      yolo: this.yolo,
+      yolo: this.autoApprove.enabled,
       ...(this.opts.logger ? { logger: this.opts.logger } : {}),
     });
   }
@@ -555,9 +568,7 @@ export class TelegramChannel implements Channel<TelegramStartOpts> {
         setAwaitingApprovalText: (state) => {
           this.awaitingApprovalText = state;
         },
-        setActiveModelOverride: (modelId) => {
-          this.activeModelOverride = modelId;
-        },
+        model: this.pickerModel(),
       },
     );
   }

package/src/format.ts

@@ -290,7 +290,7 @@ function isAllowedUrl(url: string): boolean {
   return ALLOWED_URL_SCHEMES.has((m[1] ?? '').toLowerCase());
 }
 
-function escapeHtml(s: string): string {
+export function escapeHtml(s: string): string {
   return s.replace(/[&<>]/g, (c) => (c === '&' ? '&amp;' : c === '<' ? '&lt;' : '&gt;'));
 }