@moxxy/plugin-telegram 0.27.0

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

@@ -0,0 +1,222 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Context } from 'grammy';
+import type { ChannelHandle } from '@moxxy/sdk';
+import { Session } from '@moxxy/core';
+import {
+  handleTextMessage,
+  type TextHandlerCallbacks,
+  type TextHandlerDeps,
+  type TextHandlerState,
+} from './text-handler.js';
+import type { AwaitingApprovalText } from './callback-handler.js';
+
+/**
+ * Worst-case regression coverage for the text-handler — the primary inbound
+ * path. Since the fire-and-track dispatch change (grammy poll loop no longer
+ * parked on a turn), the load-bearing invariants this handler enforces are:
+ *
+ *  - an unpaired chat's text is refused (authorization gate),
+ *  - `/cancel` aborts the live per-turn controller EVEN while busy (the whole
+ *    point of the deadlock fix — without it /cancel sat undelivered),
+ *  - a plain prompt is refused while a turn is in flight (single-flight guard),
+ *  - awaiting-approval-text is captured BEFORE the busy guard (so the user can
+ *    answer a plan-execute "Redraft" prompt while the strategy is still
+ *    technically mid-turn, pending on us),
+ *  - a stale approval-text submission degrades to a clear reply, not a throw.
+ */
+
+const makeSession = (): Session => new Session({ cwd: '/tmp', silent: true });
+
+const fakeCtx = (over: { chatId?: number; text?: string } = {}) => {
+  const replies: string[] = [];
+  const reply = vi.fn(async (text: string) => {
+    replies.push(text);
+  });
+  return {
+    ctx: {
+      chat: { id: over.chatId ?? 42 },
+      message: { text: over.text ?? 'hello' },
+      reply,
+    } as unknown as Context,
+    replies,
+  };
+};
+
+interface Harness {
+  state: TextHandlerState;
+  deps: TextHandlerDeps;
+  cb: TextHandlerCallbacks;
+  runUserTurn: ReturnType<typeof vi.fn>;
+  resolvePendingWithText: ReturnType<typeof vi.fn>;
+  setAwaitingApprovalText: ReturnType<typeof vi.fn>;
+}
+
+const makeHarness = (over: Partial<TextHandlerState> = {}): Harness => {
+  const runUserTurn = vi.fn(async () => {});
+  const resolvePendingWithText = vi.fn(() => true);
+  const setAwaitingApprovalText = vi.fn();
+  const state: TextHandlerState = {
+    session: makeSession(),
+    model: undefined,
+    activeModelOverride: null,
+    yolo: false,
+    busy: false,
+    turnController: null,
+    awaitingApprovalText: null,
+    handle: null,
+    ...over,
+  };
+  const deps: TextHandlerDeps = {
+    pairing: { isAuthorized: () => true } as never,
+    approvalResolver: {
+      resolvePendingWithText,
+      abortAll: vi.fn(),
+    } as never,
+    permissionResolver: { abortAll: vi.fn() } as never,
+    framePump: { resetRenderer: vi.fn() } as never,
+  };
+  const tryHostPair = vi.fn(async () => false);
+  const cb: TextHandlerCallbacks = {
+    setAwaitingApprovalText,
+    toggleYolo: () => false,
+    setYolo: () => undefined,
+    runUserTurn,
+    tryHostPair,
+  };
+  return { state, deps, cb, runUserTurn, resolvePendingWithText, setAwaitingApprovalText, tryHostPair };
+};
+
+describe('handleTextMessage — authorization gate', () => {
+  it('refuses an unpaired chat without running a turn', async () => {
+    const { ctx, replies } = fakeCtx({ chatId: 666, text: 'do a thing' });
+    const h = makeHarness();
+    h.deps = { ...h.deps, pairing: { isAuthorized: (id: number) => id !== 666 } as never };
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(h.runUserTurn).not.toHaveBeenCalled();
+    expect(replies.some((r) => /paired/i.test(r))).toBe(true);
+  });
+
+  it('ignores a message with no chat id or no text (degrade, never throw)', async () => {
+    const h = makeHarness();
+    const noChat = { message: { text: 'hi' }, reply: vi.fn() } as unknown as Context;
+    await expect(handleTextMessage(noChat, h.state, h.deps, h.cb)).resolves.toBeUndefined();
+    const noText = { chat: { id: 1 }, message: {}, reply: vi.fn() } as unknown as Context;
+    await expect(handleTextMessage(noText, h.state, h.deps, h.cb)).resolves.toBeUndefined();
+    expect(h.runUserTurn).not.toHaveBeenCalled();
+  });
+});
+
+describe('handleTextMessage — /cancel (interrupt while busy)', () => {
+  it('aborts the live per-turn controller even while a turn is in flight', async () => {
+    const controller = new AbortController();
+    const { ctx, replies } = fakeCtx({ text: '/cancel' });
+    const h = makeHarness({ busy: true, turnController: controller });
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(controller.signal.aborted).toBe(true);
+    expect(replies.some((r) => /cancel/i.test(r))).toBe(true);
+    // /cancel must not start a new turn.
+    expect(h.runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('replies "nothing to cancel" when no turn is running', async () => {
+    const { ctx, replies } = fakeCtx({ text: '/cancel' });
+    const h = makeHarness({ busy: false, turnController: null });
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(replies.some((r) => /nothing to cancel/i.test(r))).toBe(true);
+  });
+
+  it('does not re-abort an already-aborted controller', async () => {
+    const controller = new AbortController();
+    controller.abort('earlier');
+    const spy = vi.spyOn(controller, 'abort');
+    const { ctx, replies } = fakeCtx({ text: '/cancel' });
+    const h = makeHarness({ busy: true, turnController: controller });
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(spy).not.toHaveBeenCalled();
+    expect(replies.some((r) => /nothing to cancel/i.test(r))).toBe(true);
+  });
+});
+
+describe('handleTextMessage — single-flight busy guard', () => {
+  it('refuses a plain prompt while a turn is in flight (no second turn)', async () => {
+    const { ctx, replies } = fakeCtx({ text: 'another prompt' });
+    const h = makeHarness({ busy: true });
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(h.runUserTurn).not.toHaveBeenCalled();
+    expect(replies.some((r) => /still working/i.test(r))).toBe(true);
+  });
+
+  it('runs a turn when idle', async () => {
+    const { ctx } = fakeCtx({ text: 'do the thing' });
+    const h = makeHarness({ busy: false });
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(h.runUserTurn).toHaveBeenCalledTimes(1);
+    expect(h.runUserTurn).toHaveBeenCalledWith(ctx, 42, 'do the thing');
+  });
+});
+
+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' };
+    const { ctx, replies } = fakeCtx({ text: 'please tighten the plan' });
+    // busy:true with no controller — the awaiting branch must win BEFORE the
+    // busy refusal so the user can actually answer the prompt.
+    const h = makeHarness({ busy: true, awaitingApprovalText: awaiting });
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    // Latch cleared first (so a thrown resolver can't re-enter it).
+    expect(h.setAwaitingApprovalText).toHaveBeenCalledWith(null);
+    expect(h.resolvePendingWithText).toHaveBeenCalledWith(
+      'appr_1',
+      'redraft',
+      'please tighten the plan',
+    );
+    expect(h.runUserTurn).not.toHaveBeenCalled();
+    expect(replies.some((r) => /submitted/i.test(r))).toBe(true);
+  });
+
+  it('replies gracefully when the awaited approval is no longer pending', async () => {
+    const awaiting: AwaitingApprovalText = { approvalId: 'appr_old', optionId: 'redraft' };
+    const { ctx, replies } = fakeCtx({ text: 'late text' });
+    const h = makeHarness({ awaitingApprovalText: awaiting });
+    h.resolvePendingWithText.mockReturnValueOnce(false);
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(replies.some((r) => /no longer pending/i.test(r))).toBe(true);
+    expect(h.runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('does NOT treat /cancel as approval text — the awaiting latch is cleared and /cancel still cancels', async () => {
+    // A user who clicked a text-requesting option but then types /cancel: the
+    // approval text capture consumes the message (it is the awaited follow-up),
+    // so /cancel becomes the redraft text rather than a turn cancel. We assert
+    // the documented behaviour: awaiting-text wins, the latch is cleared, and
+    // no turn is started — so the channel can't be left in a corrupt state.
+    const awaiting: AwaitingApprovalText = { approvalId: 'appr_2', optionId: 'redraft' };
+    const { ctx } = fakeCtx({ text: '/cancel' });
+    const h = makeHarness({ awaitingApprovalText: awaiting });
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(h.setAwaitingApprovalText).toHaveBeenCalledWith(null);
+    expect(h.resolvePendingWithText).toHaveBeenCalledWith('appr_2', 'redraft', '/cancel');
+    expect(h.runUserTurn).not.toHaveBeenCalled();
+  });
+});
+
+describe('handleTextMessage — /exit teardown', () => {
+  it('routes /exit through the registry and stops the channel handle', async () => {
+    const stop = vi.fn(async () => {});
+    const handle = { running: Promise.resolve(), stop } as unknown as ChannelHandle;
+    const session = makeSession();
+    // Register an /exit command that yields a session-action the handler maps
+    // to handle.stop — the real teardown path.
+    session.commands.register({
+      name: 'exit',
+      description: 'close',
+      channels: ['telegram'],
+      handler: async () => ({ kind: 'session-action', action: 'exit', notice: 'bye' }),
+    });
+    const { ctx, replies } = fakeCtx({ text: '/exit' });
+    const h = makeHarness({ session, handle });
+    await handleTextMessage(ctx, h.state, h.deps, h.cb);
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(replies.some((r) => /bye/i.test(r))).toBe(true);
+  });
+});

package/src/channel/text-handler.ts

@@ -0,0 +1,174 @@
+import type { Context } from 'grammy';
+import type { ClientSession as Session } from '@moxxy/sdk';
+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 { runSlash } from './slash-handler.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;
+  readonly awaitingApprovalText: AwaitingApprovalText | null;
+  readonly handle: ChannelHandle | null;
+}
+
+export interface TextHandlerDeps {
+  readonly pairing: PairingHandler;
+  readonly approvalResolver: TelegramApprovalResolver;
+  readonly permissionResolver: TelegramPermissionResolver;
+  readonly framePump: FramePump;
+}
+
+export interface TextHandlerCallbacks {
+  readonly setAwaitingApprovalText: (state: AwaitingApprovalText | null) => void;
+  readonly toggleYolo: () => boolean;
+  readonly setYolo: (value: boolean) => void;
+  readonly setVoiceReplies: (on: boolean) => Promise<void>;
+  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
+   *  "not paired" reply). See {@link TelegramChannel.tryHostPair}. */
+  readonly tryHostPair: (chatId: number, text: string) => Promise<boolean>;
+}
+
+/**
+ * Top-level dispatch for inbound text messages: authorization gate,
+ * awaiting-approval-text capture, /cancel, slash routing, and finally
+ * the user-turn path.
+ */
+export async function handleTextMessage(
+  ctx: Context,
+  state: TextHandlerState,
+  deps: TextHandlerDeps,
+  cb: TextHandlerCallbacks,
+): Promise<void> {
+  const chatId = ctx.chat?.id;
+  const text = ctx.message?.text;
+  if (!chatId || !text) return;
+
+  if (!deps.pairing.isAuthorized(chatId)) {
+    // Host-issued pairing: a bare 6-digit message from an unpaired chat may be
+    // the code presented back to us. If so, pair and stop here.
+    if (await cb.tryHostPair(chatId, text)) return;
+    await ctx.reply(
+      'This bot is paired with a different chat (or not paired yet). Run `moxxy telegram pair` to (re-)pair.',
+    );
+    return;
+  }
+
+  // Capture awaiting-text BEFORE the busy guard so the user can answer
+  // an approval text prompt even while the strategy is technically
+  // still mid-turn (it's pending on us).
+  if (state.awaitingApprovalText) {
+    const { approvalId, optionId } = state.awaitingApprovalText;
+    cb.setAwaitingApprovalText(null);
+    const handled = deps.approvalResolver.resolvePendingWithText(approvalId, optionId, text);
+    if (handled) {
+      await ctx.reply(`✓ submitted (${optionId})`);
+    } else {
+      await ctx.reply('that approval is no longer pending');
+    }
+    return;
+  }
+
+  // /cancel works even while busy; everything else routes through
+  // runSlash or the user-turn path.
+  if (text === '/cancel') {
+    if (state.turnController && !state.turnController.signal.aborted) {
+      state.turnController.abort('user cancel');
+      await ctx.reply('cancelling current turn…');
+    } else {
+      await ctx.reply('nothing to cancel.');
+    }
+    return;
+  }
+
+  if (text.startsWith('/')) {
+    await runSlash(
+      ctx,
+      text,
+      {
+        session: state.session,
+        model: state.model,
+        activeModelOverride: state.activeModelOverride,
+        yolo: state.yolo,
+        voiceReplies: state.voiceReplies,
+      },
+      {
+        toggleYolo: cb.toggleYolo,
+        setVoiceReplies: cb.setVoiceReplies,
+        performSessionAction: (c, action, notice) =>
+          performSessionAction(c, action, notice, state, deps, cb),
+      },
+    );
+    return;
+  }
+
+  if (state.busy) {
+    await ctx.reply('I am still working on the previous prompt. Send /cancel to abort it.');
+    return;
+  }
+
+  await cb.runUserTurn(ctx, chatId, text);
+}
+
+/**
+ * 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).
+ */
+async function performSessionAction(
+  ctx: Context,
+  action: 'new' | 'clear' | 'exit',
+  notice: string | undefined,
+  state: TextHandlerState,
+  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'}`);
+  }
+}

package/src/channel/turn-runner.ts

@@ -0,0 +1,102 @@
+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 type { FramePump } from './frame-pump.js';
+import type { TypingIndicator } from './typing-indicator.js';
+
+export interface TurnRunnerLogger {
+  warn(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface TurnRunnerDeps {
+  readonly session: Session;
+  readonly bot: Bot | null;
+  readonly framePump: FramePump;
+  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.
+   */
+  readonly onFinalReply?: (text: string) => Promise<void>;
+}
+
+export interface TurnRunnerOptions {
+  readonly chatId: number;
+  readonly text: string;
+  readonly model: string | undefined;
+  readonly controller: AbortController;
+  /** turnId for this turn. The channel mints it so it can also record it as an
+   *  own-turn id (mirrorForeignTurn filters on those). */
+  readonly turnId: ReturnType<typeof newTurnId>;
+}
+
+/**
+ * Drive a single user turn end-to-end: kick off typing, subscribe the
+ * frame pump to session events, run the turn through `runTurn`, flush
+ * the final frame, and unwind state in `finally`.
+ *
+ * The controller is owned by the caller so /cancel can abort just this
+ * turn without poisoning the session-level signal.
+ */
+export async function runUserTurn(
+  ctx: Context,
+  deps: TurnRunnerDeps,
+  opts: TurnRunnerOptions,
+): Promise<void> {
+  const { session, bot, framePump, typing, logger, onFinalReply } = deps;
+  const { chatId, text, model, controller, turnId } = opts;
+
+  framePump.beginTurn(chatId);
+  // Kick off "typing…" right away so the user gets immediate feedback.
+  // Don't send an ellipsis placeholder message — the typing indicator
+  // IS the placeholder. The frame pump lazily sends the first real
+  // frame when there's content to display, then edits that message for
+  // every subsequent frame.
+  typing.start(bot, chatId);
+
+  // turnId is minted by the caller (the channel records it as an own-turn id).
+  // The frame-pump subscriber filters by it: `session.log` fans out to every
+  // listener; without this a concurrent turn driven by another channel
+  // (HTTP/runner) on the same Session would render into THIS chat. (AGENTS.md:
+  // filter event-log subscribers by turnId.)
+  const unsubscribe = subscribeTurn(session, turnId, (event) => {
+    const frame = framePump.renderState.accept(event);
+    if (frame.hasUpdate) framePump.scheduleEdit();
+  });
+
+  try {
+    await driveTurn(session, { turnId, prompt: text, model, 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) {
+      const finalText = framePump.renderState.snapshot().body;
+      if (finalText.trim()) {
+        try {
+          await onFinalReply(finalText);
+        } catch (err) {
+          logger?.warn('telegram voice reply hook failed', {
+            err: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+  } catch (err) {
+    logger?.warn('telegram turn failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    try {
+      await ctx.reply(`Turn failed: ${err instanceof Error ? err.message : String(err)}`);
+    } catch {
+      /* ignore */
+    }
+  } finally {
+    typing.stop();
+    unsubscribe();
+    framePump.endTurn();
+  }
+}

package/src/channel/typing-indicator.ts

@@ -0,0 +1,31 @@
+import type { Bot } from 'grammy';
+
+/**
+ * Show a "typing…" indicator in the chat for the lifetime of a turn.
+ * Telegram clears the indicator ~5s after the last sendChatAction, so
+ * we re-fire every 4s. Best-effort — a single failure shouldn't crash
+ * the turn (we keep the interval going so transient network blips
+ * recover on the next tick).
+ */
+export class TypingIndicator {
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  start(bot: Bot | null, chatId: number): void {
+    if (!bot) return;
+    this.stop();
+    const fire = (): void => {
+      bot.api.sendChatAction(chatId, 'typing').catch(() => {
+        /* best-effort */
+      });
+    };
+    fire();
+    this.timer = setInterval(fire, 4_000);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}