@moxxy/plugin-telegram 0.27.0

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@moxxy/plugin-telegram",
+  "version": "0.27.0",
+  "description": "Telegram channel for moxxy via grammy. Treats Telegram chats as a bidirectional channel: prompts in, assistant + tool prompts out, inline-keyboard permission flow, QR deep-link chat pairing.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "channel",
+    "telegram",
+    "bot"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-telegram"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "cli"
+    },
+    "requirements": [
+      {
+        "kind": "plugin",
+        "name": "@moxxy/plugin-vault",
+        "hint": "telegram resolves the vault from the service registry for its bot token + pairing; @moxxy/plugin-vault must load first"
+      }
+    ],
+    "setup": {
+      "title": "Telegram bot",
+      "description": "Create a bot with @BotFather in Telegram (/newbot) and paste its token below. It goes into the encrypted vault. Pairing happens afterwards via QR (`moxxy telegram` → pair).",
+      "fields": [
+        {
+          "key": "botToken",
+          "label": "Bot token",
+          "kind": "secret",
+          "vaultKey": "telegram_bot_token",
+          "required": true,
+          "placeholder": "123456789:AA…",
+          "description": "From @BotFather → /newbot (or /token for an existing bot)."
+        }
+      ]
+    }
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "grammy": "^1.30.0",
+    "qrcode": "^1.5.4",
+    "@moxxy/config": "0.27.0",
+    "@moxxy/plugin-vault": "0.27.0",
+    "@moxxy/core": "0.27.0",
+    "@moxxy/sdk": "0.27.0",
+    "@moxxy/channel-kit": "0.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/qrcode": "^1.5.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/approval.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ApprovalRequest } from '@moxxy/sdk';
+import { TelegramApprovalResolver } from './approval.js';
+
+const req = (over: Partial<ApprovalRequest> = {}): ApprovalRequest => ({
+  title: 'Run plan?',
+  body: 'Details',
+  options: [
+    { id: 'approve', label: 'Approve' },
+    { id: 'cancel', label: 'Cancel' },
+  ],
+  defaultOptionId: 'approve',
+  ...over,
+});
+
+describe('TelegramApprovalResolver', () => {
+  it('falls back to defaultOptionId when no decider is attached', async () => {
+    const r = new TelegramApprovalResolver();
+    expect((await r.confirm(req())).optionId).toBe('approve');
+  });
+
+  it('falls back to options[0] then "approve" when no default is set', async () => {
+    const r = new TelegramApprovalResolver();
+    expect((await r.confirm(req({ defaultOptionId: undefined }))).optionId).toBe('approve');
+    const noOpts = await r.confirm(req({ defaultOptionId: undefined, options: [] }));
+    expect(noOpts.optionId).toBe('approve');
+    const firstWins = await r.confirm(
+      req({ defaultOptionId: undefined, options: [{ id: 'x', label: 'X' }] }),
+    );
+    expect(firstWins.optionId).toBe('x');
+  });
+
+  it('routes to the decider and resolves via resolvePending', async () => {
+    const r = new TelegramApprovalResolver();
+    r.setDecider(async () => {});
+    const promise = r.confirm(req());
+    // The pending id is appr_1 (nextId starts at 1).
+    expect(r.resolvePending('appr_1', 'cancel')).toBe(true);
+    expect(await promise).toEqual({ optionId: 'cancel' });
+    // Pending is removed; a second resolve is a no-op.
+    expect(r.resolvePending('appr_1', 'approve')).toBe(false);
+  });
+
+  it('resolvePendingWithText carries the follow-up text', async () => {
+    const r = new TelegramApprovalResolver();
+    r.setDecider(async () => {});
+    const promise = r.confirm(req());
+    expect(r.resolvePendingWithText('appr_1', 'approve', 'go ahead')).toBe(true);
+    expect(await promise).toEqual({ optionId: 'approve', text: 'go ahead' });
+  });
+
+  it('returns false for resolving an unknown id', () => {
+    const r = new TelegramApprovalResolver();
+    expect(r.resolvePending('nope', 'approve')).toBe(false);
+    expect(r.resolvePendingWithText('nope', 'approve', 'x')).toBe(false);
+  });
+
+  it('resolves with the default + error text when the decider rejects', async () => {
+    const r = new TelegramApprovalResolver();
+    r.setDecider(async () => {
+      throw new Error('render boom');
+    });
+    const decision = await r.confirm(req());
+    expect(decision.optionId).toBe('approve');
+    expect(decision.text).toContain('render boom');
+    // The failed pending is cleaned up.
+    expect(r.resolvePending('appr_1', 'cancel')).toBe(false);
+  });
+
+  it('decider rejection falls back to "cancel" when no default/options exist', async () => {
+    const r = new TelegramApprovalResolver();
+    r.setDecider(async () => {
+      throw new Error('x');
+    });
+    const decision = await r.confirm(req({ defaultOptionId: undefined, options: [] }));
+    expect(decision.optionId).toBe('cancel');
+  });
+
+  it('abortAll resolves every pending with the default and clears the map', async () => {
+    const r = new TelegramApprovalResolver();
+    r.setDecider(async () => {});
+    const a = r.confirm(req());
+    const b = r.confirm(req({ defaultOptionId: 'cancel' }));
+    r.abortAll('channel closed');
+    expect(await a).toEqual({ optionId: 'approve', text: 'channel closed' });
+    expect(await b).toEqual({ optionId: 'cancel', text: 'channel closed' });
+    // Map cleared: the previously-pending ids no longer resolve.
+    expect(r.resolvePending('appr_1', 'approve')).toBe(false);
+    expect(r.resolvePending('appr_2', 'approve')).toBe(false);
+  });
+
+  it('getPending returns the pending without resolving it', async () => {
+    const r = new TelegramApprovalResolver();
+    const decider = vi.fn(async () => {});
+    r.setDecider(decider);
+    const promise = r.confirm(req());
+    const pending = r.getPending('appr_1');
+    expect(pending?.request.title).toBe('Run plan?');
+    // Still pending — resolve it so the promise settles.
+    r.resolvePending('appr_1', 'approve');
+    await promise;
+  });
+});

package/src/approval.ts

@@ -0,0 +1,86 @@
+import type { ApprovalDecision, ApprovalRequest, ApprovalResolver } from '@moxxy/sdk';
+
+export interface PendingApproval {
+  readonly id: string;
+  readonly request: ApprovalRequest;
+  readonly resolve: (decision: ApprovalDecision) => void;
+}
+
+/**
+ * Generic approval resolver for the Telegram channel — counterpart to the
+ * TUI's ApprovalDialog. The channel renders the request as a message with
+ * an inline-keyboard option list and routes the user's button click (or
+ * follow-up text, for options with `requestsText: true`) back here via
+ * `resolvePending` / `resolvePendingWithText`.
+ *
+ * Mirrors TelegramPermissionResolver in shape: a Map<callId, pending>
+ * plus a `setDecider` callback the channel uses to actually render the
+ * UI. The strategy never knows whether the dialog is rendered as Ink
+ * components, inline keyboards, or a CLI prompt — it just awaits a
+ * promise.
+ */
+export class TelegramApprovalResolver implements ApprovalResolver {
+  readonly name = 'telegram-approval';
+  private readonly pending = new Map<string, PendingApproval>();
+  private deciderFn: ((id: string, request: ApprovalRequest) => Promise<void>) | null = null;
+  private nextId = 1;
+
+  setDecider(fn: (id: string, request: ApprovalRequest) => Promise<void>): void {
+    this.deciderFn = fn;
+  }
+
+  async confirm(request: ApprovalRequest): Promise<ApprovalDecision> {
+    if (!this.deciderFn) {
+      // No bot wired up — best fallback is the request's defaultOptionId.
+      // For plan-execute, the default is "approve" which preserves the
+      // headless behavior (run the plan as drafted).
+      return { optionId: request.defaultOptionId ?? request.options[0]?.id ?? 'approve' };
+    }
+    const id = `appr_${this.nextId++}`;
+    return new Promise<ApprovalDecision>((resolve) => {
+      this.pending.set(id, { id, request, resolve });
+      this.deciderFn!(id, request).catch((err) => {
+        this.pending.delete(id);
+        resolve({
+          optionId: request.defaultOptionId ?? request.options[0]?.id ?? 'cancel',
+          text: `decider failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+      });
+    });
+  }
+
+  /** Look up a pending approval without resolving it. Used by the channel
+   *  when the user clicks an option that needs text follow-up — we keep
+   *  the approval pending and capture the next message. */
+  getPending(id: string): PendingApproval | undefined {
+    return this.pending.get(id);
+  }
+
+  /** Resolve directly with an option id (no text). */
+  resolvePending(id: string, optionId: string): boolean {
+    const pending = this.pending.get(id);
+    if (!pending) return false;
+    this.pending.delete(id);
+    pending.resolve({ optionId });
+    return true;
+  }
+
+  /** Resolve with an option id AND a free-text follow-up. */
+  resolvePendingWithText(id: string, optionId: string, text: string): boolean {
+    const pending = this.pending.get(id);
+    if (!pending) return false;
+    this.pending.delete(id);
+    pending.resolve({ optionId, text });
+    return true;
+  }
+
+  abortAll(reason = 'channel closed'): void {
+    for (const pending of this.pending.values()) {
+      pending.resolve({
+        optionId: pending.request.defaultOptionId ?? pending.request.options[0]?.id ?? 'cancel',
+        text: reason,
+      });
+    }
+    this.pending.clear();
+  }
+}

package/src/channel/approval-prompt.ts

@@ -0,0 +1,46 @@
+import { type Bot, InlineKeyboard } from 'grammy';
+import type { ApprovalRequest } from '@moxxy/sdk';
+import type { TelegramApprovalResolver } from '../approval.js';
+import { truncate } from './html.js';
+
+export interface ApprovalPromptDeps {
+  readonly bot: Bot | null;
+  readonly chatId: number | null;
+  readonly resolver: TelegramApprovalResolver;
+  readonly logger?: { warn(msg: string, meta?: Record<string, unknown>): void };
+}
+
+/**
+ * Render an approval request (e.g. plan-execute "validate plan") as a
+ * message + inline-keyboard option list. Options with `requestsText`
+ * are still picked here; the callback handler then captures the user's
+ * NEXT message as the follow-up text via the channel's awaiting-text
+ * state.
+ */
+export async function askForApproval(
+  id: string,
+  request: ApprovalRequest,
+  deps: ApprovalPromptDeps,
+): Promise<void> {
+  if (!deps.bot || !deps.chatId) return;
+  const keyboard = new InlineKeyboard();
+  for (const opt of request.options) {
+    const label = `${opt.hotkey ? `[${opt.hotkey}] ` : ''}${opt.label}`;
+    keyboard.text(label, `appr:${id}:${opt.id}`).row();
+  }
+  // Telegram has a ~4096-char message limit; truncate the body so a
+  // verbose plan doesn't fail to send. The full plan is also in the
+  // chat scrollback (the assistant_message events get streamed in).
+  const bodySnippet = truncate(request.body, 3000);
+  const summary =
+    `📋 ${request.title}\n\n${bodySnippet}\n\n` +
+    `Pick an option below. Some options (e.g. Redraft) will prompt for follow-up text after you click.`;
+  try {
+    await deps.bot.api.sendMessage(deps.chatId, summary, { reply_markup: keyboard });
+  } catch (err) {
+    deps.logger?.warn('approval send failed', { err: String(err) });
+    // Default-resolve on send failure so the loop strategy doesn't hang.
+    const fallback = request.defaultOptionId ?? request.options[0]?.id ?? 'cancel';
+    deps.resolver.resolvePending(id, fallback);
+  }
+}

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

@@ -0,0 +1,188 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Context } from 'grammy';
+
+// The manifest writers (setCategoryDefault/setProviderModel) can reject on
+// disk/permission/lock. Mock them so we can drive the failure path.
+const setCategoryDefault = vi.fn(async () => {});
+const setProviderModel = vi.fn(async () => {});
+vi.mock('@moxxy/config', () => ({
+  setCategoryDefault: (...a: unknown[]) => setCategoryDefault(...a),
+  setProviderModel: (...a: unknown[]) => setProviderModel(...a),
+}));
+
+import { handleCallback, type CallbackState, type CallbackCallbacks } from './callback-handler.js';
+
+/**
+ * A46: the inline-keyboard callback path must enforce the SAME pairing gate
+ * the text/voice handlers do — button clicks resolve permission prompts and
+ * approvals, so an unpaired chat's clicks must be refused, not processed.
+ */
+
+const fakeCtx = (over: Partial<{ chatId: number | undefined; data: string }> = {}) => {
+  const answers: Array<{ text?: string }> = [];
+  const answerCallbackQuery = vi.fn(async (arg?: { text?: string }) => {
+    answers.push(arg ?? {});
+    return true;
+  });
+  const chat = over.chatId === undefined ? undefined : { id: over.chatId };
+  return {
+    ctx: {
+      chat,
+      callbackQuery: {
+        data: over.data ?? 'perm:call-1:allow',
+        message: chat ? { chat } : undefined,
+      },
+      answerCallbackQuery,
+      editMessageReplyMarkup: vi.fn(async () => true),
+    } as unknown as Context,
+    answers,
+    answerCallbackQuery,
+  };
+};
+
+const makeState = (over: Partial<CallbackState> = {}): { state: CallbackState; resolvePending: ReturnType<typeof vi.fn> } => {
+  const resolvePending = vi.fn(() => true);
+  const state: CallbackState = {
+    bot: null,
+    session: null,
+    chatId: null,
+    permissionResolver: { resolvePending } as never,
+    approvalResolver: { getPending: () => undefined, resolvePending: vi.fn() } as never,
+    pairing: { isAuthorized: () => true },
+    ...over,
+  };
+  return { state, resolvePending };
+};
+
+const cb: CallbackCallbacks = {
+  setAwaitingApprovalText: () => undefined,
+  setActiveModelOverride: () => undefined,
+};
+
+describe('handleCallback — pairing gate (A46)', () => {
+  it('refuses a callback from an unpaired chat without touching any resolver', async () => {
+    const { ctx, answers } = fakeCtx({ chatId: 666 });
+    const { state, resolvePending } = makeState({ pairing: { isAuthorized: (id) => id !== 666 } });
+    await handleCallback(ctx, state, cb);
+    expect(resolvePending).not.toHaveBeenCalled();
+    expect(answers.some((a) => /paired/i.test(a.text ?? ''))).toBe(true);
+  });
+
+  it('refuses a callback with no resolvable chat id (e.g. inline-message callbacks)', async () => {
+    const { ctx } = fakeCtx({ chatId: undefined });
+    const { state, resolvePending } = makeState({ pairing: { isAuthorized: () => true } });
+    await handleCallback(ctx, state, cb);
+    expect(resolvePending).not.toHaveBeenCalled();
+  });
+
+  it('processes a callback from the paired chat (perm: resolves the pending call)', async () => {
+    const { ctx } = fakeCtx({ chatId: 42, data: 'perm:call-1:allow' });
+    const { state, resolvePending } = makeState({ pairing: { isAuthorized: (id) => id === 42 } });
+    await handleCallback(ctx, state, cb);
+    expect(resolvePending).toHaveBeenCalledWith('call-1', { mode: 'allow' });
+  });
+
+  it('gates every dispatch prefix, not just perm:', async () => {
+    for (const data of ['appr:a1:opt', 'model:openai::gpt-x', 'mode:goal']) {
+      const { ctx, answerCallbackQuery } = fakeCtx({ chatId: 666, data });
+      const getPending = vi.fn();
+      const { state } = makeState({
+        pairing: { isAuthorized: () => false },
+        approvalResolver: { getPending, resolvePending: vi.fn() } as never,
+      });
+      await handleCallback(ctx, state, cb);
+      // The only reply is the refusal — the handlers behind the prefixes
+      // were never consulted.
+      expect(getPending).not.toHaveBeenCalled();
+      expect(answerCallbackQuery).toHaveBeenCalledTimes(1);
+    }
+  });
+});
+
+describe('handleCallback — model/mode persistence failure (u110-5)', () => {
+  const fakeSession = () =>
+    ({
+      readyProviders: new Set(['openai']),
+      providers: {
+        getActiveName: () => 'openai',
+        list: () => [{ name: 'openai' }],
+        replace: vi.fn(),
+        setActive: vi.fn(),
+      },
+      modes: {
+        setActive: vi.fn(),
+        list: () => [{ name: 'default' }, { name: 'goal' }],
+      },
+      credentialResolver: undefined,
+    }) as unknown as CallbackState['session'];
+
+  const ctxWithEdit = (data: string) => {
+    const editMessageText = vi.fn(async () => true);
+    const answerCallbackQuery = vi.fn(async () => true);
+    const chat = { id: 42 };
+    return {
+      ctx: {
+        chat,
+        callbackQuery: { data, message: { chat } },
+        answerCallbackQuery,
+        editMessageText,
+        editMessageReplyMarkup: vi.fn(async () => true),
+      } as unknown as Context,
+      editMessageText,
+      answerCallbackQuery,
+    };
+  };
+
+  const stateFor = (session: CallbackState['session']): CallbackState => ({
+    bot: null,
+    session,
+    chatId: null,
+    permissionResolver: { resolvePending: vi.fn() } as never,
+    approvalResolver: { getPending: () => undefined, resolvePending: vi.fn() } as never,
+    pairing: { isAuthorized: () => true },
+  });
+
+  it('does NOT claim "✓ switched" when the manifest write rejects (model)', async () => {
+    setCategoryDefault.mockReset();
+    setProviderModel.mockReset();
+    setCategoryDefault.mockRejectedValueOnce(new Error('EROFS'));
+    const { ctx, editMessageText, answerCallbackQuery } = ctxWithEdit('model:openai::gpt-x');
+    await handleCallback(ctx, stateFor(fakeSession()), cb);
+
+    expect(setCategoryDefault).toHaveBeenCalledWith('provider', 'openai');
+    // The success edit must NOT have fired; the failure surfaces via the toast.
+    const successEdits = editMessageText.mock.calls.filter((c) =>
+      String(c[0]).includes('✓ switched'),
+    );
+    expect(successEdits).toHaveLength(0);
+    expect(
+      answerCallbackQuery.mock.calls.some((c) => /failed/i.test(String((c[0] as { text?: string } | undefined)?.text))),
+    ).toBe(true);
+  });
+
+  it('does NOT claim "✓ mode →" when the manifest write rejects (mode)', async () => {
+    setCategoryDefault.mockReset();
+    setCategoryDefault.mockRejectedValueOnce(new Error('EROFS'));
+    const { ctx, editMessageText, answerCallbackQuery } = ctxWithEdit('mode:goal');
+    await handleCallback(ctx, stateFor(fakeSession()), cb);
+
+    expect(setCategoryDefault).toHaveBeenCalledWith('mode', 'goal');
+    const successEdits = editMessageText.mock.calls.filter((c) =>
+      String(c[0]).includes('✓ mode'),
+    );
+    expect(successEdits).toHaveLength(0);
+    expect(
+      answerCallbackQuery.mock.calls.some((c) => /failed/i.test(String((c[0] as { text?: string } | undefined)?.text))),
+    ).toBe(true);
+  });
+
+  it('persists and confirms success when the manifest writes resolve (model)', async () => {
+    setCategoryDefault.mockReset();
+    setProviderModel.mockReset();
+    const { ctx, editMessageText } = ctxWithEdit('model:openai::gpt-x');
+    await handleCallback(ctx, stateFor(fakeSession()), cb);
+    expect(
+      editMessageText.mock.calls.some((c) => String(c[0]).includes('✓ switched')),
+    ).toBe(true);
+  });
+});