@moxxy/plugin-telegram 0.41.2 → 0.42.0

package/src/index.ts

@@ -1,9 +1,7 @@
 import { defineChannel, defineTool, definePlugin, z, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
 import type { VaultStore } from '@moxxy/plugin-vault';
-import { Api, GrammyError } from 'grammy';
-import { markdownToTelegramHtml } from './format.js';
-import { stripHtml } from './channel/html.js';
 import { TelegramChannel } from './channel.js';
+import { buildTelegramSendMessageTool } from './tools/send-message.js';
 import { TELEGRAM_AUTHORIZED_CHAT_KEY, TELEGRAM_TOKEN_KEY, parseChatId } from './keys.js';
 import { runTelegramWizard } from './setup-wizard.js';
 import { runPairFlow } from './pair-flow.js';
@@ -34,7 +32,12 @@ export interface BuildTelegramPluginOptions {
   readonly vault: VaultStore;
 }
 
-export { TELEGRAM_TOKEN_KEY, TELEGRAM_AUTHORIZED_CHAT_KEY, TELEGRAM_TOKEN_RE } from './keys.js';
+export {
+  TELEGRAM_TOKEN_KEY,
+  TELEGRAM_AUTHORIZED_CHAT_KEY,
+  TELEGRAM_MODEL_KEY,
+  TELEGRAM_TOKEN_RE,
+} from './keys.js';
 
 // Backwards-compat aliases for the existing call sites in this file.
 const TOKEN_KEY = TELEGRAM_TOKEN_KEY;
@@ -251,77 +254,7 @@ function makeTelegramPlugin(getVault: () => VaultStore, hooks?: LifecycleHooks):
           };
         },
       }),
-      defineTool({
-        name: 'telegram_send_message',
-        description:
-          'Push a one-off message to the currently authorized Telegram chat. Use this from a ' +
-          'scheduled prompt to deliver results without an interactive channel running. By ' +
-          'default the text is rendered with the same rich Markdown→Telegram formatting as ' +
-          'interactive replies (bold, code, `> [!type]` callouts, `||spoilers||`, etc.); pass ' +
-          'an explicit `parseMode` to send the raw text under that parse mode instead. Requires ' +
-          'a stored bot token + a paired chat (run `moxxy channels telegram pair` once).',
-        inputSchema: z.object({
-          text: z.string().min(1).max(4096),
-          /** Optional override; defaults to the vault-paired chat id. */
-          chatId: z.number().int().optional(),
-          /**
-           * Force a specific Telegram parse mode and send `text` verbatim under
-           * it. Omit to get the default Markdown→HTML rendering (recommended).
-           */
-          parseMode: z.enum(['MarkdownV2', 'Markdown', 'HTML']).optional(),
-        }),
-        permission: { action: 'prompt' },
-        isolation: {
-          capabilities: {
-            fs: { read: ['~/.moxxy/vault.*'] },
-            net: { mode: 'allowlist', hosts: ['api.telegram.org'] },
-            env: ['MOXXY_TELEGRAM_TOKEN'],
-            timeMs: 60_000,
-          },
-        },
-        handler: async ({ text, chatId, parseMode }) => {
-          const token = process.env.MOXXY_TELEGRAM_TOKEN ?? (await getVault().get(TOKEN_KEY));
-          if (!token) {
-            throw new Error(
-              'no Telegram bot token configured (set MOXXY_TELEGRAM_TOKEN or run `moxxy init` to store one)',
-            );
-          }
-          const targetChat =
-            chatId ?? parseChatId(await getVault().get(AUTHORIZED_CHAT_KEY));
-          if (!targetChat) {
-            throw new Error(
-              'no authorized chat — run `moxxy channels telegram pair` first or pass `chatId` explicitly',
-            );
-          }
-          // Use grammy's lightweight `Api` client directly rather than a full
-          // `Bot` (which builds a polling-capable instance + lazily resolves
-          // bot info). This is a one-off send — no long-polling — so the Bot
-          // wrapper was pure overhead per invocation.
-          const api = new Api(token);
-          if (parseMode) {
-            // Explicit mode → caller owns the markup; send text verbatim.
-            await api.sendMessage(targetChat, text, { parse_mode: parseMode });
-          } else {
-            // Default → render Markdown to Telegram HTML for the same rich look
-            // as interactive replies, falling back to plain text if the model's
-            // text produced an entity Telegram can't parse (rare).
-            const html = markdownToTelegramHtml(text);
-            try {
-              await api.sendMessage(targetChat, html, {
-                parse_mode: 'HTML',
-                link_preview_options: { is_disabled: true },
-              });
-            } catch (err) {
-              if (err instanceof GrammyError && /can't parse entities|Bad Request: can't parse/i.test(err.description ?? '')) {
-                await api.sendMessage(targetChat, stripHtml(html));
-              } else {
-                throw err;
-              }
-            }
-          }
-          return { delivered: true, chatId: targetChat, length: text.length };
-        },
-      }),
+      buildTelegramSendMessageTool({ getVault }),
       defineTool({
         name: 'telegram_unpair',
         description: 'Forget the currently authorized Telegram chat. The next /start will start a fresh pairing.',

package/src/keys.ts

@@ -50,3 +50,7 @@ export function parseChatId(raw: string | null | undefined): number | null {
   const n = Number(raw);
   return Number.isFinite(n) ? n : null;
 }
+
+/** Vault key for this bot's model (`provider::model`); absent = the default model.
+ *  The desktop's Channels panel writes the same key. */
+export const TELEGRAM_MODEL_KEY = 'telegram_model';

package/src/pair-flow.ts

@@ -1,6 +1,6 @@
 import { log, outro, spinner } from '@clack/prompts';
 import QRCode from 'qrcode';
-import { exitAfterPairRequested, type ChannelSubcommandContext } from '@moxxy/sdk';
+import { finishPairing, type ChannelSubcommandContext } from '@moxxy/sdk';
 import type { VaultStore } from '@moxxy/plugin-vault';
 import { TelegramChannel } from './channel.js';
 
@@ -21,7 +21,8 @@ const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
  *   4. Render that deep link as a scannable QR (+ the plain link).
  *   5. The user scans / opens the link and taps START (or sends the 6 digits);
  *      the bot authorizes that chat and `onPaired` fires.
- *   6. Hand off SIGINT to keep the bot running until the user Ctrl-Cs.
+ *   6. Stop the pairing bot (it ran on the provider-less probe session) and
+ *      start the channel for real with the configured model (`finishPairing`).
  */
 export async function runPairFlow(ctx: ChannelSubcommandContext): Promise<number> {
   const session = ctx.session;
@@ -78,7 +79,7 @@ export async function runPairFlow(ctx: ChannelSubcommandContext): Promise<number
   await printPairQr(url);
   log.info('Scan the QR with your phone (or open the link and tap START) — your chat pairs automatically.');
 
-  // Graceful Ctrl-C while waiting (or once running): stop the bot and exit.
+  // Graceful Ctrl-C while waiting for the pairing: stop the bot and exit.
   let stopping = false;
   const shutdown = async (): Promise<void> => {
     if (stopping) return;
@@ -96,26 +97,11 @@ export async function runPairFlow(ctx: ChannelSubcommandContext): Promise<number
   const chatId = await paired;
   spin.stop(`Paired ✓ — chat ${chatId} is authorized.`);
 
-  if (exitAfterPairRequested(ctx)) {
-    // Orchestrated pairing (`moxxy onboard`): hand control back — the caller
-    // starts the bot under its own service afterwards. Our SIGINT handlers
-    // would `process.exit` the orchestrator, so drop them first.
-    process.removeListener('SIGINT', onSignal);
-    process.removeListener('SIGTERM', onSignal);
-    await stopBot();
-    return 0;
-  }
-
-  log.info('Bot is running. Press Ctrl+C to stop.');
-  try {
-    // Only reached if the bot stops on its own (a signal path exits via
-    // shutdown()); remove our handlers so they don't outlive this flow.
-    await handle.running;
-    return 0;
-  } finally {
-    process.removeListener('SIGINT', onSignal);
-    process.removeListener('SIGTERM', onSignal);
-  }
+  // Drop the pairing-only Ctrl+C handlers first: their `process.exit` would
+  // otherwise cut the real channel (or an orchestrator) short.
+  process.removeListener('SIGINT', onSignal);
+  process.removeListener('SIGTERM', onSignal);
+  return finishPairing(ctx, stopBot);
 }
 
 /** Render the pairing deep link as a scannable terminal QR + the plain link. */

package/src/subcommands.test.ts

@@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { VaultStore, createStaticKeySource, deriveKey, generateSalt } from '@moxxy/plugin-vault';
 import type { ChannelDef } from '@moxxy/sdk';
 import { buildTelegramPlugin } from './index.js';
+import { removeDir } from '@moxxy/vitest-preset/fs';
 
 let tmp: string;
 let vault: VaultStore;
@@ -37,7 +38,7 @@ beforeEach(async () => {
 });
 
 afterEach(async () => {
-  await fs.rm(tmp, { recursive: true, force: true });
+  await removeDir(tmp);
   process.stdout.write = origStdoutWrite;
   process.stderr.write = origStderrWrite;
 });

package/src/tools/send-message.test.ts

@@ -0,0 +1,118 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { InputFile } from 'grammy';
+import { VaultStore, createStaticKeySource, deriveKey, generateSalt } from '@moxxy/plugin-vault';
+import type { ToolContext } from '@moxxy/sdk';
+import { TELEGRAM_AUTHORIZED_CHAT_KEY, TELEGRAM_TOKEN_KEY } from '../keys.js';
+import { buildTelegramSendMessageTool, type TelegramSendApi } from './send-message.js';
+import { removeDir } from '@moxxy/vitest-preset/fs';
+
+let tmp: string;
+let vault: VaultStore;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-tg-send-'));
+  vault = new VaultStore({
+    filePath: path.join(tmp, 'vault.json'),
+    keySource: createStaticKeySource(deriveKey('test', generateSalt())),
+  });
+  await vault.set(TELEGRAM_TOKEN_KEY, '123456:ABCDEFGHIJKLMNOPQRSTUVWXYZ');
+  await vault.set(TELEGRAM_AUTHORIZED_CHAT_KEY, '42');
+});
+
+afterEach(async () => {
+  await removeDir(tmp);
+});
+
+type Call =
+  | { kind: 'message'; chatId: number; text: string; parseMode?: string }
+  | { kind: 'document'; chatId: number; name: string | undefined };
+
+function fakeApi() {
+  const calls: Call[] = [];
+  const tokens: string[] = [];
+  const api: TelegramSendApi = {
+    sendMessage: async (chatId, text, opts) => {
+      calls.push({ kind: 'message', chatId, text, ...(opts?.parse_mode ? { parseMode: opts.parse_mode } : {}) });
+      return undefined;
+    },
+    sendDocument: async (chatId, file: InputFile) => {
+      calls.push({ kind: 'document', chatId, name: file.filename });
+      return undefined;
+    },
+  };
+  const tool = buildTelegramSendMessageTool({
+    getVault: () => vault,
+    createApi: (token) => {
+      tokens.push(token);
+      return api;
+    },
+  });
+  return { calls, tokens, tool };
+}
+
+const ctx = () => ({ cwd: tmp }) as unknown as ToolContext;
+
+describe('telegram_send_message', () => {
+  it('sends the text to the paired chat, formatted like the bot replies', async () => {
+    const { calls, tokens, tool } = fakeApi();
+
+    const out = await tool.handler({ text: 'Build **done**.' }, ctx());
+
+    expect(tokens).toEqual(['123456:ABCDEFGHIJKLMNOPQRSTUVWXYZ']);
+    expect(calls).toEqual([{ kind: 'message', chatId: 42, text: 'Build <b>done</b>.', parseMode: 'HTML' }]);
+    expect(out).toMatchObject({ delivered: true, chatId: 42 });
+  });
+
+  it('sends the files the owner asked for as documents under the text', async () => {
+    await fs.writeFile(path.join(tmp, 'report.pdf'), 'pdf');
+    await fs.writeFile(path.join(tmp, 'photo.png'), 'png');
+    const { calls, tool } = fakeApi();
+
+    const out = await tool.handler({ text: 'Here you go', files: ['report.pdf', path.join(tmp, 'photo.png')] }, ctx());
+
+    expect(calls).toEqual([
+      { kind: 'message', chatId: 42, text: 'Here you go', parseMode: 'HTML' },
+      { kind: 'document', chatId: 42, name: 'report.pdf' },
+      { kind: 'document', chatId: 42, name: 'photo.png' },
+    ]);
+    expect(out).toMatchObject({ files: ['report.pdf', 'photo.png'] });
+  });
+
+  it('refuses files larger than a bot may upload before sending anything', async () => {
+    const big = path.join(tmp, 'film.mp4');
+    await fs.writeFile(big, '');
+    await fs.truncate(big, 51 * 1024 * 1024);
+    const { calls, tool } = fakeApi();
+
+    await expect(tool.handler({ text: 'film', files: [big] }, ctx())).rejects.toThrow(/Telegram accepts at most 50 MB/);
+    expect(calls).toEqual([]);
+  });
+
+  it('splits a long text into several messages, in order', async () => {
+    const { calls, tool } = fakeApi();
+
+    await tool.handler({ text: `${'a'.repeat(4000)}\n${'b'.repeat(4000)}` }, ctx());
+
+    const texts = calls.map((c) => (c.kind === 'message' ? c.text : ''));
+    expect(texts.length).toBeGreaterThan(1);
+    expect(texts.join('').replace(/\s/g, '')).toBe(`${'a'.repeat(4000)}${'b'.repeat(4000)}`);
+  });
+
+  it('keeps an explicit parse mode verbatim', async () => {
+    const { calls, tool } = fakeApi();
+
+    await tool.handler({ text: '*raw*', parseMode: 'MarkdownV2' }, ctx());
+
+    expect(calls).toEqual([{ kind: 'message', chatId: 42, text: '*raw*', parseMode: 'MarkdownV2' }]);
+  });
+
+  it('says to pair first when no chat is paired', async () => {
+    await vault.delete(TELEGRAM_AUTHORIZED_CHAT_KEY);
+    const { tool } = fakeApi();
+
+    await expect(tool.handler({ text: 'hi' }, ctx())).rejects.toThrow(/no authorized chat/);
+  });
+});

package/src/tools/send-message.ts

@@ -0,0 +1,97 @@
+import { Api, InputFile } from 'grammy';
+import { defineTool, z, type ToolDef } from '@moxxy/sdk';
+import { readLocalFiles, resolveSecret } from '@moxxy/channel-kit';
+import { TELEGRAM_AUTHORIZED_CHAT_KEY, TELEGRAM_TOKEN_KEY, parseChatId } from '../keys.js';
+import { sendMarkdown, type TelegramSender } from '../channel/send-rich.js';
+
+/** The slice of grammy's `Api` this tool uses (the real client satisfies it). */
+export interface TelegramSendApi extends TelegramSender {
+  sendDocument(chatId: number, document: InputFile): Promise<unknown>;
+}
+
+export interface TelegramSendMessageToolDeps {
+  readonly getVault: () => { get(name: string): Promise<string | null> };
+  /** Build the API client for a token. Defaults to grammy's lightweight `Api`. */
+  readonly createApi?: (token: string) => TelegramSendApi;
+}
+
+const TOKEN_ENV = 'MOXXY_TELEGRAM_TOKEN';
+/** Cap on one push — a couple of Telegram messages once split. */
+const MAX_TEXT_CHARS = 8_000;
+/** The Bot API accepts uploads up to 50 MB. */
+const MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+const MAX_FILES = 10;
+
+/**
+ * `telegram_send_message` — push a message (and files) to the paired chat from
+ * ANY session (desktop, goal mode, a scheduled prompt) without the Telegram
+ * channel running. A one-off `Api` rather than a full `Bot`: no long-polling.
+ */
+export function buildTelegramSendMessageTool(deps: TelegramSendMessageToolDeps): ToolDef {
+  const createApi = deps.createApi ?? ((token: string) => new Api(token));
+  return defineTool({
+    name: 'telegram_send_message',
+    description:
+      'Push a message to the paired Telegram chat. Use it to proactively report progress, a finished ' +
+      'task, or a blocker that needs their decision — e.g. from a long goal-mode run or a scheduled ' +
+      'prompt — without the Telegram channel running. The text is rendered with the same rich ' +
+      'Markdown→Telegram formatting as interactive replies (bold, code, `> [!type]` callouts, ' +
+      '`||spoilers||`); pass an explicit `parseMode` to send the raw text under that parse mode ' +
+      'instead. Long text is split into several messages. Pass `files` (local paths) to send files ' +
+      'the owner asked for as documents — up to 10 files, 50 MB in total. Requires a stored bot ' +
+      'token + a paired chat (run `moxxy channels telegram pair` once).',
+    inputSchema: z.object({
+      text: z.string().trim().min(1).max(MAX_TEXT_CHARS),
+      files: z.array(z.string().min(1).max(4096)).max(MAX_FILES).optional(),
+      /** Optional override; defaults to the vault-paired chat id. */
+      chatId: z.number().int().optional(),
+      /** Force a Telegram parse mode and send `text` verbatim under it. */
+      parseMode: z.enum(['MarkdownV2', 'Markdown', 'HTML']).optional(),
+    }),
+    permission: { action: 'prompt' },
+    isolation: {
+      capabilities: {
+        // Attachments are whatever local file the owner asked for; the
+        // permission prompt shows the paths before anything is read or sent.
+        fs: { read: ['~/.moxxy/vault.*', '~/**', '$cwd/**', '/tmp/**'] },
+        net: { mode: 'allowlist', hosts: ['api.telegram.org'] },
+        env: [TOKEN_ENV],
+        timeMs: 120_000,
+      },
+    },
+    handler: async ({ text, files: filePaths, chatId, parseMode }, ctx) => {
+      const vault = deps.getVault();
+      const token = await resolveSecret(vault, { envVar: TOKEN_ENV, vaultKey: TELEGRAM_TOKEN_KEY });
+      if (!token) {
+        throw new Error(
+          `no Telegram bot token configured (set ${TOKEN_ENV} or run \`moxxy channels telegram setup\`)`,
+        );
+      }
+      const target = chatId ?? parseChatId(await vault.get(TELEGRAM_AUTHORIZED_CHAT_KEY));
+      if (!target) {
+        throw new Error('no authorized chat — run `moxxy channels telegram pair` first or pass `chatId` explicitly');
+      }
+      const files = await readLocalFiles(filePaths ?? [], {
+        cwd: ctx.cwd,
+        maxTotalBytes: MAX_UPLOAD_BYTES,
+        service: 'Telegram',
+        limitLabel: '50 MB per upload',
+      });
+
+      const api = createApi(token);
+      let parts = 1;
+      // An explicit mode means the caller owns the markup: send it verbatim.
+      if (parseMode) await api.sendMessage(target, text, { parse_mode: parseMode });
+      else parts = await sendMarkdown(api, target, text);
+      // Files go under the text that introduces them, in order.
+      for (const file of files) await api.sendDocument(target, new InputFile(file.data, file.name));
+      return {
+        delivered: true,
+        chatId: target,
+        parts,
+        length: text.length,
+        ...(files.length > 0 ? { files: files.map((f) => f.name) } : {}),
+      };
+    },
+  });
+}