loopengine 0.3.1 → 0.3.2

package/dist/core/agent-config.d.ts

@@ -225,6 +225,8 @@ export type HttpNotifierConfig = {
         botToken: string;
         chatId: string;
         publicUrl?: string;
+        buttons?: boolean;
+        replyHint?: boolean;
     };
     events: HttpNotifierEvent[];
 } | {

package/dist/core/http-notifier.js

@@ -8,6 +8,7 @@ import { RedisQueueApprover } from './http-notify-triggers/redis.js';
 import { agentDirFor, createAgentEnv } from './agent-env.js';
 import { notifierConfigFromFile, readActiveConnections, readNotifierFile } from './notifier-file.js';
 import { recordThread } from './messaging/threads.js';
+import { recordTelegramMessage } from './messaging/connectors/telegram/store.js';
 const EMPTY = {};
 // Keyed by the AgentConfig object itself, not its httpNotifier field
 // alone — resolveHttpNotifier is called on every runAgent()/resumeAgent()
@@ -129,7 +130,7 @@ function combineResolved(list) {
             f(context); } : undefined,
     };
 }
-/** `agentDir`: where a Slack request's thread is recorded, so replies in
+/** `agentDir`: where a Slack or Telegram request's thread is recorded, so replies in
  * it reach the agent (core/messaging/). */
 function buildResolved(httpNotifier, agentDir) {
     const events = new Set(httpNotifier.events);
@@ -178,8 +179,18 @@ function buildResolved(httpNotifier, agentDir) {
             break;
         }
         case 'telegram': {
-            const { botToken, chatId, publicUrl } = httpNotifier.config;
-            const telegram = new TelegramNotifier({ botToken, chatId, publicUrl });
+            const { botToken, chatId, publicUrl, buttons, replyHint } = httpNotifier.config;
+            // Each message starts a thread of its own (Telegram has none, see
+            // core/messaging/connectors/telegram/store.ts); a request's is
+            // linked to it, so replies to it reach the agent.
+            const telegram = new TelegramNotifier({
+                botToken, chatId, publicUrl, buttons, replyHint,
+                onPosted: ({ chat, messageId, text, pendingId, kind }) => {
+                    recordTelegramMessage(agentDir, { chat, id: messageId, root: messageId, fromBot: true, text });
+                    if (pendingId && kind)
+                        recordThread(agentDir, { app: 'telegram', conversation: chat, ts: messageId, pendingId, kind });
+                },
+            });
             return {
                 approver: events.has('approval') ? telegram : undefined,
                 questionHandler: events.has('question') ? telegram : undefined,

package/dist/core/http-notify-triggers/telegram.d.ts

@@ -3,16 +3,35 @@ import type { DurableQuestionHandler } from '../agent-config.js';
 import { type DeliveryResult } from './webhook.js';
 /** The Messaging tab's Send test. */
 export declare function sendTestTelegramMessage(botToken: string, chatId: string, text: string): Promise<DeliveryResult>;
+/** Where a message landed, and which request it is when it's one. */
+export interface TelegramPosted {
+    chat: string;
+    messageId: string;
+    /** The Markdown it was built from, for the thread's record. */
+    text: string;
+    pendingId?: string;
+    kind?: 'approval' | 'question';
+}
 export declare class TelegramNotifier implements DurableApprover, DurableQuestionHandler {
     private readonly botToken;
     private readonly chatId;
     private readonly publicUrl?;
+    private readonly buttons;
+    private readonly replyHint;
+    private readonly onPosted?;
     /** `publicUrl`: same meaning as SlackNotifier's — each message links to
-     * the decision page when the server's address is known. */
+     * the decision page when the server's address is known. `buttons`:
+     * add inline buttons, which only work once the bot's webhook points at
+     * this server; default false. `replyHint`: say replies are answered.
+     * `onPosted`: told where each message landed, so replies to it can be
+     * matched to its request (core/messaging/threads.ts). */
     constructor(options: {
         botToken: string;
         chatId: string;
         publicUrl?: string;
+        buttons?: boolean;
+        replyHint?: boolean;
+        onPosted?: (posted: TelegramPosted) => void;
     });
     private decideLine;
     private send;

package/dist/core/http-notify-triggers/telegram.js

@@ -1,17 +1,22 @@
 // The sending half of a Telegram-backed DurableApprover/DurableQuestionHandler,
 // so AgentConfig.httpNotifier (core/http-notifier.ts) can construct one
-// for `channel: 'telegram'`, the way it does for Slack and Lark (read
-// ./lark.ts first; this mirrors it).
+// for `channel: 'telegram'`, the way it does for Slack (read ./slack.ts
+// first; this mirrors it).
 //
 // Posts through the Bot API's sendMessage (core.telegram.org/bots/api)
 // to one chat: a group, a channel the bot can post in, or a person who
-// has started the bot. Like a console-configured Lark notifier, each
-// request carries a link to the decision page rather than buttons:
-// inline-keyboard callbacks would need a webhook this server receives
-// and verifies, which nothing here sets up yet. Plain text, no
-// parse_mode, so tool names and arguments never need escaping.
+// has started the bot. Each request links to the decision page; with
+// `buttons` (the bot's webhook points at this server, see
+// core/messaging/connectors/telegram/) it also gets Approve/Deny or a
+// question's options as inline buttons, handled at
+// POST /hooks/telegram/<agent>. Messages are HTML (parse_mode), built
+// from Markdown with everything the agent wrote escaped.
 import { randomUUID } from 'node:crypto';
 import { decidePath } from '../approval-links.js';
+import { formatArgs } from '../messaging/format-args.js';
+import { callTelegram } from '../messaging/connectors/telegram/index.js';
+import { telegramEscape, toTelegramHtml } from '../messaging/connectors/telegram/format.js';
+import { telegramCallbackData } from '../messaging/connectors/telegram/updates.js';
 import { publicBaseUrl } from './webhook.js';
 // Telegram's limit for one message's text.
 const MAX_TEXT = 4096;
@@ -37,35 +42,76 @@ export class TelegramNotifier {
     botToken;
     chatId;
     publicUrl;
+    buttons;
+    replyHint;
+    onPosted;
     /** `publicUrl`: same meaning as SlackNotifier's — each message links to
-     * the decision page when the server's address is known. */
+     * the decision page when the server's address is known. `buttons`:
+     * add inline buttons, which only work once the bot's webhook points at
+     * this server; default false. `replyHint`: say replies are answered.
+     * `onPosted`: told where each message landed, so replies to it can be
+     * matched to its request (core/messaging/threads.ts). */
     constructor(options) {
         this.botToken = options.botToken;
         this.chatId = options.chatId;
         this.publicUrl = options.publicUrl;
+        this.buttons = options.buttons ?? false;
+        this.replyHint = options.replyHint ?? false;
+        this.onPosted = options.onPosted;
     }
     decideLine(pendingId, kind) {
         const base = publicBaseUrl(this.publicUrl);
-        return base ? `\n\n${kind === 'approval' ? 'Approve or deny' : 'Answer'}: ${base}${decidePath(pendingId, kind)}` : '';
+        return base ? `[${kind === 'approval' ? 'Open to approve or deny' : 'Open to answer'}](${base}${decidePath(pendingId, kind)})` : '';
     }
-    send(text, label) {
-        void sendTelegramMessage(this.botToken, this.chatId, text).then((result) => {
-            if (!result.ok)
-                console.error(`[loopengine] TelegramNotifier: send message failed for ${label}:`, result.error);
+    send(markdown, label, keyboard, request) {
+        // Not awaited, by DurableApprover's contract; a failure is logged.
+        void callTelegram(this.botToken, 'sendMessage', {
+            chat_id: this.chatId,
+            text: toTelegramHtml(markdown),
+            parse_mode: 'HTML',
+            link_preview_options: { is_disabled: true },
+            ...(keyboard?.length ? { reply_markup: { inline_keyboard: keyboard } } : {}),
+        }).then((sent) => {
+            if (!sent.ok || !sent.result) {
+                console.error(`[loopengine] TelegramNotifier: send message failed for ${label}:`, sent.description);
+                return;
+            }
+            this.onPosted?.({ chat: String(sent.result.chat?.id ?? this.chatId), messageId: String(sent.result.message_id), text: markdown, ...(request ?? {}) });
         });
     }
     requestDurableApproval(tool, args, scope, reason, pendingId = randomUUID()) {
-        this.send(`Approval requested\n\ntool: ${tool}\nargs: ${JSON.stringify(args)}\nscope: ${scope.tenant}/${scope.environment}/${scope.agent}\nreason: ${reason}${this.decideLine(pendingId, 'approval')}`, `pendingId '${pendingId}'`);
+        const lines = [
+            `**Approval requested:** \`${tool}\``,
+            formatArgs(args, telegramEscape),
+            `**Why:** ${telegramEscape(reason)}`,
+            this.decideLine(pendingId, 'approval'),
+            telegramEscape(`${scope.agent} · ${scope.tenant}/${scope.environment}`),
+            this.replyHint ? 'Reply to this message to ask about it.' : '',
+        ];
+        const keyboard = this.buttons
+            ? [[
+                    { text: 'Approve', callback_data: telegramCallbackData({ type: 'decide', decision: 'approve' }, pendingId) },
+                    { text: 'Deny', callback_data: telegramCallbackData({ type: 'decide', decision: 'deny' }, pendingId) },
+                ]]
+            : undefined;
+        this.send(lines.filter(Boolean).join('\n'), `pendingId '${pendingId}'`, keyboard, { pendingId, kind: 'approval' });
         return { pendingId };
     }
     notifyPendingQuestion(question, options, agent, sessionId, pendingId = randomUUID()) {
-        const choices = options?.length ? `\n\nOptions: ${options.join(' / ')}` : '';
-        this.send(`Question from ${agent}\n\n${question}${choices}${sessionId ? `\n(session ${sessionId})` : ''}${this.decideLine(pendingId, 'question')}`, `pendingId '${pendingId}'`);
+        const lines = [
+            `**Question from ${telegramEscape(agent)}${sessionId ? ` (session ${telegramEscape(sessionId)})` : ''}:**`,
+            telegramEscape(question),
+            this.decideLine(pendingId, 'question'),
+            this.replyHint ? (options?.length ? 'Or reply to this message with another answer.' : 'Reply to this message to answer.') : '',
+        ];
+        // One option per row: a long option would squeeze its neighbours.
+        const keyboard = this.buttons ? (options ?? []).slice(0, 20).map((option, i) => [{ text: option.slice(0, 64), callback_data: telegramCallbackData({ type: 'answer_option', index: i }, pendingId) }]) : undefined;
+        this.send(lines.filter(Boolean).join('\n'), `pendingId '${pendingId}'`, keyboard, { pendingId, kind: 'question' });
         return { pendingId };
     }
     /** A plain announcement (run started/finished, a scheduled task's
      * result), with nothing to decide. */
     postMessage(text) {
-        this.send(text, 'an announcement');
+        this.send(telegramEscape(text), 'an announcement');
     }
 }

package/dist/core/messaging/connector.d.ts

@@ -13,6 +13,13 @@ export interface InboundMessage {
     ts: string;
     /** Set for a reply in a thread: the thread's first message id. */
     threadTs?: string;
+    /** Sent to the agent alone: a DM, or a private chat with the bot. */
+    direct?: boolean;
+    /** Names the agent: an @mention of its bot. */
+    mentioned?: boolean;
+    /** The person's name, when the app says it, for the console's
+     * approver picker. */
+    userName?: string;
 }
 /** One message of a thread, as the connector reads it back. */
 export interface ThreadMessage {

package/dist/core/messaging/connector.js

@@ -2,7 +2,7 @@
 // there (core/messaging/engine.ts). The engine owns everything about
 // requests, decisions and safety; a connector only turns the app's own
 // payloads into these shapes and posts back. One per app, under
-// ./connectors/ — Slack today, Telegram and Lark next.
+// ./connectors/ — Slack and Telegram today, Lark next.
 //
 // Verifying an incoming request and parsing it stay with the connector's
 // own module (each app signs and shapes its payloads differently), and

package/dist/core/messaging/connectors/slack/events.d.ts

@@ -9,6 +9,7 @@ export type SlackEvent = {
 };
 /** Reads an Events API body. Only people's new messages come through;
  * edits, deletions, joins and every bot's messages (this agent's own
- * included) are `ignore`. */
+ * included) are `ignore`. A DM is `direct`; an app_mention is
+ * `mentioned`, with the leading @mention of the bot taken off its text. */
 export declare function parseSlackEvent(rawBody: string): SlackEvent;
 export declare function createSlackConnector(botToken: string): MessagingConnector;

package/dist/core/messaging/connectors/slack/events.js

@@ -1,7 +1,8 @@
 import { slackEscape, toSlackMrkdwn } from './format.js';
 /** Reads an Events API body. Only people's new messages come through;
  * edits, deletions, joins and every bot's messages (this agent's own
- * included) are `ignore`. */
+ * included) are `ignore`. A DM is `direct`; an app_mention is
+ * `mentioned`, with the leading @mention of the bot taken off its text. */
 export function parseSlackEvent(rawBody) {
     let body;
     try {
@@ -19,15 +20,18 @@ export function parseSlackEvent(rawBody) {
         return { type: 'ignore' };
     if (!event.user || !event.channel || !event.ts || typeof event.text !== 'string')
         return { type: 'ignore' };
+    const mentioned = event.type === 'app_mention';
     return {
         type: 'message',
         app: 'slack',
         eventId: body.event_id,
         conversation: event.channel,
         user: event.user,
-        text: event.text,
+        text: mentioned ? event.text.replace(/^(\s*<@[A-Z0-9]+>)+\s*/, '') : event.text,
         ts: event.ts,
         ...(event.thread_ts && event.thread_ts !== event.ts ? { threadTs: event.thread_ts } : {}),
+        ...(event.channel_type === 'im' ? { direct: true } : {}),
+        ...(mentioned ? { mentioned: true } : {}),
     };
 }
 /** The engine's buttons as Slack buttons: action_id is the action (deny

package/dist/core/messaging/connectors/slack/setup.d.ts

@@ -17,7 +17,8 @@ export interface SlackMember {
  * users:read for their names. */
 export declare function listSlackChannelMembers(botToken: string, channel: string): Promise<SlackMember[]>;
 /** A Slack app manifest for one agent's notifier: a bot that can post,
- * read the channel list and read replies in its requests' threads, with
+ * read the channel list, read replies in its requests' threads, and take
+ * DMs and @mentions that start jobs (core/messaging/jobs.ts), with
  * interactivity pointed at this server and events at <that URL>/events
  * (core/messaging/). Paste it into api.slack.com/apps →
  * Create New App → From a manifest. */

package/dist/core/messaging/connectors/slack/setup.js

@@ -75,18 +75,23 @@ function slackSetupError(error) {
     return reasons[error ?? ''] ?? `Slack said: ${error}`;
 }
 /** A Slack app manifest for one agent's notifier: a bot that can post,
- * read the channel list and read replies in its requests' threads, with
+ * read the channel list, read replies in its requests' threads, and take
+ * DMs and @mentions that start jobs (core/messaging/jobs.ts), with
  * interactivity pointed at this server and events at <that URL>/events
  * (core/messaging/). Paste it into api.slack.com/apps →
  * Create New App → From a manifest. */
 export function slackAppManifest(options) {
     const name = `LoopEngine ${options.agentName}`.slice(0, 35);
     return {
-        display_information: { name, description: `Approval requests and questions from the ${options.agentName} agent` },
-        features: { bot_user: { display_name: name, always_online: true } },
-        oauth_config: { scopes: { bot: ['chat:write', 'channels:read', 'groups:read', 'channels:history', 'groups:history', 'users:read'] } },
+        display_information: { name, description: `Jobs, approval requests and questions from the ${options.agentName} agent` },
+        features: {
+            bot_user: { display_name: name, always_online: true },
+            // A Messages tab, so people can DM the agent a job.
+            app_home: { home_tab_enabled: false, messages_tab_enabled: true, messages_tab_read_only_enabled: false },
+        },
+        oauth_config: { scopes: { bot: ['chat:write', 'channels:read', 'groups:read', 'channels:history', 'groups:history', 'users:read', 'app_mentions:read', 'im:history'] } },
         settings: {
-            event_subscriptions: { request_url: `${options.interactivityUrl}/events`, bot_events: ['message.channels', 'message.groups'] },
+            event_subscriptions: { request_url: `${options.interactivityUrl}/events`, bot_events: ['message.channels', 'message.groups', 'message.im', 'app_mention'] },
             interactivity: { is_enabled: true, request_url: options.interactivityUrl },
             org_deploy_enabled: false,
             socket_mode_enabled: false,

package/dist/core/messaging/connectors/telegram/format.d.ts

@@ -0,0 +1,6 @@
+/** Marks text that isn't ours, so toTelegramHtml escapes it and leaves it
+ * as plain text. */
+export declare function telegramEscape(text: string): string;
+export declare function toTelegramHtml(markdown: string): string;
+/** A call's arguments as Telegram HTML (core/messaging/format-args.ts). */
+export declare function telegramArgs(args: Record<string, unknown>, schema?: Record<string, unknown>): string;

package/dist/core/messaging/connectors/telegram/format.js

@@ -0,0 +1,57 @@
+// Telegram's side of formatting: messages go out with parse_mode HTML,
+// so the Markdown the engine and the model write is turned into the few
+// tags Telegram knows (b, i, s, code, pre, a). Everything else is
+// HTML-escaped, so no text can become a tag. Text that isn't ours
+// (telegramEscape) is escaped too but never turned into formatting or a
+// link.
+import { formatArgs } from '../../format-args.js';
+const OPEN = '\u0001';
+const CLOSE = '\u0002';
+const KEEP = /(```[\s\S]*?```|`[^`\n]*`|\u0001[\s\S]*?\u0002)/;
+// Telegram's limit is 4096 characters of text after the tags are read;
+// cutting the Markdown well short of it keeps the tags whole.
+const MAX_MARKDOWN = 3800;
+function html(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** Marks text that isn't ours, so toTelegramHtml escapes it and leaves it
+ * as plain text. */
+export function telegramEscape(text) {
+    return OPEN + text.replace(/[\u0001\u0002]/g, '') + CLOSE;
+}
+export function toTelegramHtml(markdown) {
+    const cut = markdown.length > MAX_MARKDOWN ? markdown.slice(0, MAX_MARKDOWN).trimEnd() + '\n…' : markdown;
+    return cut
+        .split(KEEP)
+        .map((part, i) => {
+        if (i % 2 === 0)
+            return convertProse(part);
+        const plain = part.replace(/[\u0001\u0002]/g, '');
+        if (part.startsWith(OPEN))
+            return html(plain);
+        if (part.startsWith('```'))
+            return `<pre>${html(plain.slice(3, -3).replace(/^[\w-]*\n/, ''))}</pre>`;
+        return `<code>${html(plain.slice(1, -1))}</code>`;
+    })
+        .join('')
+        .replace(/[\u0001\u0002]/g, '');
+}
+function convertProse(text) {
+    return html(text)
+        // # Heading -> bold
+        .replace(/^#{1,6}[ \t]+(.+?)[ \t]*#*[ \t]*$/gm, '<b>$1</b>')
+        // - item / * item -> • item
+        .replace(/^([ \t]*)[-*+][ \t]+/gm, '$1• ')
+        .replace(/\*\*(?=\S)([\s\S]*?\S)\*\*/g, '<b>$1</b>')
+        .replace(/__(?=\S)([\s\S]*?\S)__/g, '<b>$1</b>')
+        .replace(/(^|[^\w*])\*(?=\S)([^*\n]*?\S)\*(?![\w*])/g, '$1<i>$2</i>')
+        .replace(/(^|[^\w])_(?=\S)([^_\n]*?\S)_(?!\w)/g, '$1<i>$2</i>')
+        .replace(/~~(?=\S)([\s\S]*?\S)~~/g, '<s>$1</s>')
+        // [text](url): the URL was escaped with the rest, which is what an
+        // attribute needs, and can't hold a quote.
+        .replace(/\[([^\]\n]+)\]\((https?:\/\/[^\s)"]+)\)/g, '<a href="$2">$1</a>');
+}
+/** A call's arguments as Telegram HTML (core/messaging/format-args.ts). */
+export function telegramArgs(args, schema) {
+    return toTelegramHtml(formatArgs(args, telegramEscape, schema));
+}

package/dist/core/messaging/connectors/telegram/index.d.ts

@@ -0,0 +1,39 @@
+import type { MessagingConnector } from '../../connector.js';
+export { telegramArgs, telegramEscape, toTelegramHtml } from './format.js';
+export { readTelegramThread, recordTelegramMessage, telegramPeople, telegramRootOf, type TelegramPerson } from './store.js';
+export { parseTelegramUpdate, telegramCallbackData, verifyTelegramRequest, type TelegramButton, type TelegramUpdate } from './updates.js';
+export interface TelegramResult<T = unknown> {
+    ok: boolean;
+    result?: T;
+    description?: string;
+}
+/** One Bot API call. Never throws: a network failure reads as not ok. */
+export declare function callTelegram<T = unknown>(botToken: string, method: string, body: Record<string, unknown>): Promise<TelegramResult<T>>;
+/** A reply under `replyTo` that still goes out if that message is gone. */
+export declare function replyTo(messageId: string): Record<string, unknown>;
+export type InlineButton = {
+    text: string;
+    callback_data: string;
+};
+export declare function createTelegramConnector(botToken: string, agentDir: string): MessagingConnector;
+/** Stops a clicked button's spinner, with a short note when there's one. */
+export declare function answerTelegramClick(botToken: string, callbackId: string, text?: string): Promise<void>;
+/** Replaces a message's text and takes its buttons away. */
+export declare function editTelegramMessage(botToken: string, chat: string, messageId: string, text: string): Promise<void>;
+/** The bot's @username (without @), asked once an hour per token; how a
+ * mention of it is spotted. */
+export declare function telegramBotUsername(botToken: string): Promise<string | undefined>;
+/** Points the bot's updates at `url` with `secret` as the secret_token
+ * (./updates.ts checks it). Only messages and button clicks are sent. */
+export declare function setTelegramWebhook(botToken: string, url: string, secret: string): Promise<{
+    ok: boolean;
+    error?: string;
+    botUsername?: string;
+}>;
+/** Where the bot's updates go now, and the last delivery error Telegram saw. */
+export declare function telegramWebhookInfo(botToken: string): Promise<{
+    ok: boolean;
+    url?: string;
+    lastError?: string;
+    error?: string;
+}>;

package/dist/core/messaging/connectors/telegram/index.js

@@ -0,0 +1,136 @@
+import { telegramEscape, toTelegramHtml } from './format.js';
+import { readTelegramThread, recordTelegramMessage, telegramPeople } from './store.js';
+import { telegramCallbackData } from './updates.js';
+export { telegramArgs, telegramEscape, toTelegramHtml } from './format.js';
+export { readTelegramThread, recordTelegramMessage, telegramPeople, telegramRootOf } from './store.js';
+export { parseTelegramUpdate, telegramCallbackData, verifyTelegramRequest } from './updates.js';
+/** One Bot API call. Never throws: a network failure reads as not ok. */
+export async function callTelegram(botToken, method, body) {
+    try {
+        const res = await fetch(`https://api.telegram.org/bot${botToken}/${method}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        const parsed = (await res.json().catch(() => ({})));
+        return parsed.ok ? parsed : { ok: false, description: parsed.description || `HTTP ${res.status}` };
+    }
+    catch (err) {
+        return { ok: false, description: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** A reply under `replyTo` that still goes out if that message is gone. */
+export function replyTo(messageId) {
+    return { reply_parameters: { message_id: Number(messageId), allow_sending_without_reply: true } };
+}
+/** The engine's buttons as one row of Telegram inline buttons. */
+function choiceKeyboard(choices) {
+    return [
+        choices.map((choice) => ({
+            text: choice.label,
+            callback_data: telegramCallbackData(choice.action === 'deny' ? { type: 'decide', decision: 'deny' } : { type: 'action', action: choice.action }, choice.pendingId),
+        })),
+    ];
+}
+/** How a person shows in a message: their @username (which Telegram
+ * links), else their name. */
+function personLabel(agentDir, user) {
+    const person = telegramPeople(agentDir).find((p) => p.id === user);
+    if (person?.username)
+        return `@${person.username}`;
+    return (person?.name ?? `user ${user}`).replace(/[*_~`[\]<>]/g, '');
+}
+export function createTelegramConnector(botToken, agentDir) {
+    const send = async (conversation, threadTs, text, keyboard) => {
+        const sent = await callTelegram(botToken, 'sendMessage', {
+            chat_id: conversation,
+            text: toTelegramHtml(text),
+            parse_mode: 'HTML',
+            link_preview_options: { is_disabled: true },
+            ...replyTo(threadTs),
+            ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
+        });
+        if (!sent.ok || !sent.result) {
+            console.error('[loopengine] Telegram sendMessage (thread reply) failed:', sent.description);
+            return undefined;
+        }
+        const id = String(sent.result.message_id);
+        recordTelegramMessage(agentDir, { chat: conversation, id, root: threadTs, fromBot: true, text });
+        return id;
+    };
+    return {
+        app: 'telegram',
+        name: 'Telegram',
+        mention: (user) => personLabel(agentDir, user),
+        escape: telegramEscape,
+        async fetchThread(conversation, threadTs) {
+            // Without telegramEscape's markers, which are for formatting only.
+            return readTelegramThread(agentDir, conversation, threadTs).map((m) => ({ ...m, text: m.text.replace(/[\u0001\u0002]/g, '') }));
+        },
+        async postInThread(conversation, threadTs, text) {
+            await send(conversation, threadTs, text);
+        },
+        async postChoice(conversation, threadTs, text, choices) {
+            return send(conversation, threadTs, text, choiceKeyboard(choices));
+        },
+        async replaceMessage(conversation, ts, text) {
+            // Editing without reply_markup also takes the buttons away.
+            const edited = await callTelegram(botToken, 'editMessageText', {
+                chat_id: conversation,
+                message_id: Number(ts),
+                text: toTelegramHtml(text),
+                parse_mode: 'HTML',
+                link_preview_options: { is_disabled: true },
+            });
+            if (!edited.ok)
+                console.error('[loopengine] Telegram editMessageText failed:', edited.description);
+        },
+    };
+}
+/** Stops a clicked button's spinner, with a short note when there's one. */
+export async function answerTelegramClick(botToken, callbackId, text) {
+    const answered = await callTelegram(botToken, 'answerCallbackQuery', { callback_query_id: callbackId, ...(text ? { text: text.slice(0, 200) } : {}) });
+    if (!answered.ok)
+        console.error('[loopengine] Telegram answerCallbackQuery failed:', answered.description);
+}
+/** Replaces a message's text and takes its buttons away. */
+export async function editTelegramMessage(botToken, chat, messageId, text) {
+    const edited = await callTelegram(botToken, 'editMessageText', { chat_id: chat, message_id: Number(messageId), text: toTelegramHtml(text), parse_mode: 'HTML', link_preview_options: { is_disabled: true } });
+    if (!edited.ok)
+        console.error('[loopengine] Telegram editMessageText failed:', edited.description);
+}
+const botNames = new Map();
+/** The bot's @username (without @), asked once an hour per token; how a
+ * mention of it is spotted. */
+export async function telegramBotUsername(botToken) {
+    const cached = botNames.get(botToken);
+    if (cached && Date.now() - cached.at < 60 * 60 * 1000)
+        return cached.username;
+    const me = await callTelegram(botToken, 'getMe', {});
+    if (!me.ok || !me.result?.username)
+        return cached?.username;
+    botNames.set(botToken, { username: me.result.username, at: Date.now() });
+    return me.result.username;
+}
+/** Points the bot's updates at `url` with `secret` as the secret_token
+ * (./updates.ts checks it). Only messages and button clicks are sent. */
+export async function setTelegramWebhook(botToken, url, secret) {
+    const set = await callTelegram(botToken, 'setWebhook', { url, secret_token: secret, allowed_updates: ['message', 'callback_query'] });
+    if (!set.ok)
+        return { ok: false, error: telegramSetupError(set.description) };
+    return { ok: true, botUsername: await telegramBotUsername(botToken) };
+}
+/** Where the bot's updates go now, and the last delivery error Telegram saw. */
+export async function telegramWebhookInfo(botToken) {
+    const info = await callTelegram(botToken, 'getWebhookInfo', {});
+    if (!info.ok)
+        return { ok: false, error: telegramSetupError(info.description) };
+    return { ok: true, url: info.result?.url || undefined, ...(info.result?.last_error_message ? { lastError: info.result.last_error_message } : {}) };
+}
+function telegramSetupError(description) {
+    if (/unauthorized|not found/i.test(description ?? ''))
+        return 'Telegram rejected the bot token; copy it from @BotFather again';
+    if (/https/i.test(description ?? ''))
+        return 'Telegram only sends updates to an https address; set LOOPENGINE_PUBLIC_URL to this server\'s https address';
+    return `Telegram said: ${description ?? 'no answer'}`;
+}

package/dist/core/messaging/connectors/telegram/store.d.ts

@@ -0,0 +1,31 @@
+import type { ThreadMessage } from '../../connector.js';
+export interface TelegramEntry {
+    chat: string;
+    /** The message's own id. */
+    id: string;
+    /** The first message of its thread (itself when it starts one). */
+    root: string;
+    /** A person's id; unset for the agent's own messages. */
+    user?: string;
+    fromBot: boolean;
+    text: string;
+    /** A person's name and @username, when Telegram sent them. */
+    name?: string;
+    username?: string;
+    at: string;
+}
+/** Never throws: a message that can't be kept only loses its context. */
+export declare function recordTelegramMessage(agentDir: string, entry: Omit<TelegramEntry, 'at'>): void;
+/** The thread a message belongs to: its recorded root, else the message
+ * itself. */
+export declare function telegramRootOf(agentDir: string, chat: string, id: string): string;
+/** A thread's messages, oldest first, at most the latest 100. */
+export declare function readTelegramThread(agentDir: string, chat: string, root: string): ThreadMessage[];
+export interface TelegramPerson {
+    id: string;
+    name: string;
+    username?: string;
+}
+/** Everyone who has written to the agent, newest first, optionally in
+ * one chat only. */
+export declare function telegramPeople(agentDir: string, chat?: string): TelegramPerson[];