loopengine 0.3.0 → 0.3.2

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

@@ -0,0 +1,69 @@
+// What Telegram won't tell us later: the Bot API has no way to read a
+// chat's history, so the messages in the agent's threads are kept here as
+// they pass through, in agents/<name>/.messaging/telegram.jsonl, along
+// with the people seen (for names in replies and the approver picker).
+//
+// Telegram has no threads either. A "thread" here is a chain of replies:
+// its first message's id is the thread id, and each later message that
+// replies into it (a person's reply, or the agent's) is recorded with
+// that root, so a reply to any message in the chain finds its thread.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// Past this, the file is cut to its newer half on the next write.
+const MAX_BYTES = 4 * 1024 * 1024;
+function storeFile(agentDir) {
+    return join(agentDir, '.messaging', 'telegram.jsonl');
+}
+function readEntries(agentDir) {
+    const path = storeFile(agentDir);
+    if (!existsSync(path))
+        return [];
+    const entries = [];
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        if (!line)
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch { }
+    }
+    return entries;
+}
+/** Never throws: a message that can't be kept only loses its context. */
+export function recordTelegramMessage(agentDir, entry) {
+    try {
+        mkdirSync(join(agentDir, '.messaging'), { recursive: true });
+        const path = storeFile(agentDir);
+        if (existsSync(path) && statSync(path).size > MAX_BYTES) {
+            const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+            writeFileSync(path, lines.slice(Math.floor(lines.length / 2)).join('\n') + '\n');
+        }
+        appendFileSync(path, JSON.stringify({ ...entry, text: entry.text.slice(0, 4000), at: new Date().toISOString() }) + '\n');
+    }
+    catch (err) {
+        console.error('[loopengine] could not keep the Telegram message:', err instanceof Error ? err.message : err);
+    }
+}
+/** The thread a message belongs to: its recorded root, else the message
+ * itself. */
+export function telegramRootOf(agentDir, chat, id) {
+    return readEntries(agentDir).find((e) => e.chat === chat && e.id === id)?.root ?? id;
+}
+/** A thread's messages, oldest first, at most the latest 100. */
+export function readTelegramThread(agentDir, chat, root) {
+    return readEntries(agentDir)
+        .filter((e) => e.chat === chat && e.root === root)
+        .slice(-100)
+        .map((e) => ({ ...(e.user ? { user: e.user } : {}), fromBot: e.fromBot, text: e.text, ts: e.id }));
+}
+/** Everyone who has written to the agent, newest first, optionally in
+ * one chat only. */
+export function telegramPeople(agentDir, chat) {
+    const people = new Map();
+    for (const e of readEntries(agentDir).reverse()) {
+        if (!e.user || people.has(e.user) || (chat && e.chat !== chat))
+            continue;
+        people.set(e.user, { id: e.user, name: e.name || (e.username ? `@${e.username}` : e.user), ...(e.username ? { username: e.username } : {}) });
+    }
+    return [...people.values()];
+}

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

@@ -0,0 +1,40 @@
+import type { InboundMessage, MessagingAction } from '../../connector.js';
+export declare function verifyTelegramRequest(header: string | undefined, secret: string): boolean;
+export type TelegramButton = {
+    type: 'decide';
+    decision: 'approve' | 'deny';
+} | {
+    type: 'answer_option';
+    index: number;
+} | {
+    type: 'action';
+    action: Exclude<MessagingAction, 'deny'>;
+};
+/** The callback_data for a button. */
+export declare function telegramCallbackData(button: TelegramButton, pendingId: string): string;
+export type TelegramUpdate = ({
+    type: 'message';
+    username?: string;
+} & InboundMessage) | {
+    type: 'click';
+    /** answerCallbackQuery takes it, to stop the button's spinner. */
+    callbackId: string;
+    conversation: string;
+    /** The message the button is on. */
+    messageId: string;
+    user: string;
+    userName?: string;
+    username?: string;
+    button: TelegramButton;
+    pendingId: string;
+} | {
+    type: 'ignore';
+};
+/** Reads an Update. Only people's new text messages and clicks on the
+ * agent's buttons come through. `botUsername` (without @) is how a
+ * mention is spotted; `rootOf` finds the thread a replied-to message is
+ * in (./store.ts). */
+export declare function parseTelegramUpdate(rawBody: string, options: {
+    botUsername?: string;
+    rootOf: (chat: string, id: string) => string;
+}): TelegramUpdate;

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

@@ -0,0 +1,112 @@
+// Reading what Telegram sends to POST /hooks/telegram/<agent>: checking
+// it came from Telegram, and turning an Update into a person's message or
+// a button click.
+//
+// Telegram signs nothing; instead setWebhook is given a secret_token that
+// Telegram sends back in X-Telegram-Bot-Api-Secret-Token with every
+// update (./setup.ts makes one per agent).
+//
+// Buttons carry `<code>:<pendingId>` as callback_data, which Telegram
+// caps at 64 bytes (a pendingId is a 36-character UUID): a/d for a
+// request's Approve/Deny, q<n> for a question's n-th option, and the
+// engine's own thread buttons (core/messaging/engine.ts).
+import { timingSafeEqual } from 'node:crypto';
+export function verifyTelegramRequest(header, secret) {
+    if (!header)
+        return false;
+    const expected = Buffer.from(secret);
+    const actual = Buffer.from(header);
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+const ACTION_CODES = {
+    approve_edited: 'ae',
+    keep_original: 'ko',
+    confirm: 'c',
+    cancel_confirm: 'cc',
+};
+/** The callback_data for a button. */
+export function telegramCallbackData(button, pendingId) {
+    const code = button.type === 'decide' ? (button.decision === 'approve' ? 'a' : 'd') : button.type === 'answer_option' ? `q${button.index}` : ACTION_CODES[button.action];
+    return `${code}:${pendingId}`;
+}
+function readCallbackData(data) {
+    const match = /^([a-z]+)(\d*):(.+)$/.exec(data);
+    if (!match)
+        return undefined;
+    const [, code, index, pendingId] = match;
+    if (code === 'a' && !index)
+        return { button: { type: 'decide', decision: 'approve' }, pendingId };
+    if (code === 'd' && !index)
+        return { button: { type: 'decide', decision: 'deny' }, pendingId };
+    if (code === 'q' && index)
+        return { button: { type: 'answer_option', index: Number(index) }, pendingId };
+    const action = Object.keys(ACTION_CODES).find((a) => ACTION_CODES[a] === code);
+    return action && !index ? { button: { type: 'action', action }, pendingId } : undefined;
+}
+const nameOf = (u) => [u.first_name, u.last_name].filter(Boolean).join(' ') || undefined;
+/** Reads an Update. Only people's new text messages and clicks on the
+ * agent's buttons come through. `botUsername` (without @) is how a
+ * mention is spotted; `rootOf` finds the thread a replied-to message is
+ * in (./store.ts). */
+export function parseTelegramUpdate(rawBody, options) {
+    let update;
+    try {
+        update = JSON.parse(rawBody);
+    }
+    catch {
+        return { type: 'ignore' };
+    }
+    const click = update.callback_query;
+    if (click) {
+        const parsed = click.data ? readCallbackData(click.data) : undefined;
+        if (!parsed || !click.id || !click.from?.id || click.message?.message_id === undefined || click.message.chat?.id === undefined)
+            return { type: 'ignore' };
+        return {
+            type: 'click',
+            callbackId: click.id,
+            conversation: String(click.message.chat.id),
+            messageId: String(click.message.message_id),
+            user: String(click.from.id),
+            ...(nameOf(click.from) ? { userName: nameOf(click.from) } : {}),
+            ...(click.from.username ? { username: click.from.username } : {}),
+            ...parsed,
+        };
+    }
+    const message = update.message;
+    if (update.update_id === undefined || !message || message.message_id === undefined || message.chat?.id === undefined)
+        return { type: 'ignore' };
+    if (!message.from?.id || message.from.is_bot || typeof message.text !== 'string')
+        return { type: 'ignore' };
+    const chat = String(message.chat.id);
+    const bot = options.botUsername?.toLowerCase();
+    let text = message.text;
+    let mentioned = false;
+    if (bot) {
+        // @bot as a mention entity, or a command addressed to it (/do@bot).
+        for (const entity of message.entities ?? []) {
+            const part = text.slice(entity.offset ?? 0, (entity.offset ?? 0) + (entity.length ?? 0)).toLowerCase();
+            if ((entity.type === 'mention' && part === `@${bot}`) || (entity.type === 'bot_command' && part.endsWith(`@${bot}`)))
+                mentioned = true;
+        }
+        if (mentioned)
+            text = text.replace(new RegExp(`@${bot}\\b`, 'ig'), '').trim();
+    }
+    // Opening a chat with a bot sends /start; it isn't a job.
+    if (/^\/start(\s|$)/.test(text))
+        text = text.replace(/^\/start\s*/, '');
+    const replyTo = message.reply_to_message?.message_id;
+    return {
+        type: 'message',
+        app: 'telegram',
+        eventId: String(update.update_id),
+        conversation: chat,
+        user: String(message.from.id),
+        text,
+        ts: String(message.message_id),
+        ...(replyTo !== undefined ? { threadTs: options.rootOf(chat, String(replyTo)) } : {}),
+        ...(message.chat.type === 'private' ? { direct: true } : {}),
+        ...(mentioned ? { mentioned: true } : {}),
+        ...(nameOf(message.from) ? { userName: nameOf(message.from) } : {}),
+        ...(message.from.username ? { username: message.from.username } : {}),
+    };
+}

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

@@ -0,0 +1,44 @@
+import type { InboundMessage, MessagingConnector } from './connector.js';
+import { type JobThread } from './threads.js';
+export type JobTurn = {
+    kind: 'done';
+    text: string;
+} | {
+    kind: 'pending';
+    items: Array<{
+        pendingId: string;
+        kind: 'approval' | 'question';
+        tool: string;
+        question?: string;
+    }>;
+};
+export interface JobDeps {
+    agentName: string;
+    agentDir: string;
+    connector: MessagingConnector;
+    plan?: string;
+    /** Whether this person may start a job, or continue one, here. */
+    allowed(message: InboundMessage): {
+        allowed: boolean;
+        message?: string;
+    };
+    /** One agent turn in `sessionId` with the person's message. */
+    runTurn(sessionId: string, text: string): Promise<JobTurn>;
+    /** The decision page for a pending item, when the server's address is known. */
+    decideLink?(pendingId: string, kind: 'approval' | 'question'): string | undefined;
+}
+/** A session id for a job thread, from the app's own ids: one per thread
+ * in a channel, one per DM (so a DM keeps its context from one message to
+ * the next). Only characters a session id can hold. */
+export declare function jobSessionId(message: Pick<InboundMessage, 'app' | 'conversation' | 'direct'>, threadTs: string): string;
+/** The job thread a message continues, if any: the thread it's in, or,
+ * in a DM, the DM itself. */
+export declare function findJobFor(agentDir: string, message: InboundMessage): JobThread | undefined;
+/** Whether a message starts or continues a job: a DM, a mention, or any
+ * message in a job's thread. */
+export declare function isJobMessage(agentDir: string, message: InboundMessage): boolean;
+/** Runs the agent on a job message and answers in its thread. */
+export declare function handleJobMessage(message: InboundMessage, deps: JobDeps): Promise<void>;
+/** Posts a resumed run's outcome in the job thread it came from, if it
+ * came from one. */
+export declare function settleJobThread(deps: Pick<JobDeps, 'agentDir' | 'connector' | 'decideLink'>, sessionId: string, turn: JobTurn): Promise<void>;

package/dist/core/messaging/jobs.js

@@ -0,0 +1,100 @@
+import { findJobThread, findJobThreadBySession, recordJobThread, recordThread } from './threads.js';
+/** A session id for a job thread, from the app's own ids: one per thread
+ * in a channel, one per DM (so a DM keeps its context from one message to
+ * the next). Only characters a session id can hold. */
+export function jobSessionId(message, threadTs) {
+    const safe = (s) => s.replace(/[^A-Za-z0-9_-]/g, '_');
+    return message.direct ? `${message.app}-dm-${safe(message.conversation)}` : `${message.app}-${safe(message.conversation)}-${safe(threadTs)}`;
+}
+/** The job thread a message continues, if any: the thread it's in, or,
+ * in a DM, the DM itself. */
+export function findJobFor(agentDir, message) {
+    const threadTs = message.threadTs ?? message.ts;
+    const inThread = findJobThread(agentDir, message.app, message.conversation, threadTs);
+    if (inThread)
+        return inThread;
+    if (!message.direct)
+        return undefined;
+    const sessionId = jobSessionId(message, threadTs);
+    return findJobThreadBySession(agentDir, sessionId);
+}
+/** Whether a message starts or continues a job: a DM, a mention, or any
+ * message in a job's thread. */
+export function isJobMessage(agentDir, message) {
+    return Boolean(message.direct || message.mentioned || findJobFor(agentDir, message));
+}
+// One turn at a time per session: a second message waits for the first's
+// answer rather than racing it.
+const sessionLocks = new Map();
+function inSession(key, fn) {
+    const previous = sessionLocks.get(key) ?? Promise.resolve();
+    const next = previous.then(fn, fn);
+    const settled = next.catch(() => { });
+    sessionLocks.set(key, settled);
+    void settled.then(() => {
+        if (sessionLocks.get(key) === settled)
+            sessionLocks.delete(key);
+    });
+    return next;
+}
+/** Runs the agent on a job message and answers in its thread. */
+export async function handleJobMessage(message, deps) {
+    const { connector } = deps;
+    const threadTs = message.threadTs ?? message.ts;
+    const say = (text) => connector.postInThread(message.conversation, threadTs, text);
+    if (deps.plan === 'free') {
+        await say(`Starting jobs from ${connector.name} needs LoopEngine Pro.`);
+        return;
+    }
+    const gate = deps.allowed(message);
+    if (!gate.allowed) {
+        await say(gate.message ?? `You can't start jobs for ${deps.agentName} here.`);
+        return;
+    }
+    const text = message.text.trim();
+    if (!text) {
+        await say('What should I do? Write the job in the same message.');
+        return;
+    }
+    const sessionId = findJobFor(deps.agentDir, message)?.sessionId ?? jobSessionId(message, threadTs);
+    // Recorded per message, so a resumed run answers in the thread of the
+    // message that started it.
+    recordJobThread(deps.agentDir, { app: message.app, conversation: message.conversation, ts: threadTs, sessionId });
+    await inSession(`${deps.agentName}:${sessionId}`, async () => {
+        let turn;
+        try {
+            turn = await deps.runTurn(sessionId, text);
+        }
+        catch (err) {
+            await say(`That didn't work: ${connector.escape(err instanceof Error ? err.message : String(err))}`);
+            return;
+        }
+        await postTurn(deps, { app: message.app, conversation: message.conversation, ts: threadTs, sessionId }, turn);
+    });
+}
+async function postTurn(deps, job, turn) {
+    const say = (text) => deps.connector.postInThread(job.conversation, job.ts, text);
+    if (turn.kind === 'done') {
+        await say(turn.text.trim() || 'Done.');
+        return;
+    }
+    for (const item of turn.items) {
+        // The thread is linked to the request, so a reply here can ask about
+        // it or decide it (core/messaging/engine.ts).
+        recordThread(deps.agentDir, { app: job.app, conversation: job.conversation, ts: job.ts, pendingId: item.pendingId, kind: item.kind });
+        const link = deps.decideLink?.(item.pendingId, item.kind);
+        const head = item.kind === 'approval'
+            ? `This needs approval before it runs \`${item.tool}\`.`
+            : `A question before I go on: ${deps.connector.escape(item.question ?? '')}`;
+        const how = item.kind === 'approval' ? 'An approver can reply here to approve or deny it' : 'Reply here to answer it';
+        await say(`${head}\n${how}${link ? `, or [open the request](${link})` : ''}. I'll carry on in this thread once it's decided.`);
+    }
+}
+/** Posts a resumed run's outcome in the job thread it came from, if it
+ * came from one. */
+export async function settleJobThread(deps, sessionId, turn) {
+    const job = findJobThreadBySession(deps.agentDir, sessionId);
+    if (!job || job.app !== deps.connector.app)
+        return;
+    await postTurn(deps, job, turn);
+}

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

@@ -22,3 +22,15 @@ export declare function recordThread(agentDir: string, link: ThreadLink): void;
 export declare function findThreadByPending(agentDir: string, pendingId: string): ThreadLink | undefined;
 /** The request a thread belongs to, or undefined for any other thread. */
 export declare function findThread(agentDir: string, app: string, conversation: string, ts: string): ThreadLink | undefined;
+export interface JobThread {
+    app: string;
+    conversation: string;
+    /** The thread's first message id. */
+    ts: string;
+    sessionId: string;
+}
+/** Never throws, like recordThread. */
+export declare function recordJobThread(agentDir: string, job: JobThread): void;
+export declare function findJobThread(agentDir: string, app: string, conversation: string, ts: string): JobThread | undefined;
+/** The session's latest job thread: where its last message came from. */
+export declare function findJobThreadBySession(agentDir: string, sessionId: string): JobThread | undefined;

package/dist/core/messaging/threads.js

@@ -42,3 +42,39 @@ function readLinks(agentDir) {
 export function findThread(agentDir, app, conversation, ts) {
     return readLinks(agentDir).filter((link) => link.app === app && link.conversation === conversation && link.ts === ts).at(-1);
 }
+function jobsFile(agentDir) {
+    return join(agentDir, '.messaging', 'jobs.jsonl');
+}
+function readJobs(agentDir) {
+    const path = jobsFile(agentDir);
+    if (!existsSync(path))
+        return [];
+    const jobs = [];
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        if (!line)
+            continue;
+        try {
+            jobs.push(JSON.parse(line));
+        }
+        catch { }
+    }
+    return jobs;
+}
+/** Never throws, like recordThread. */
+export function recordJobThread(agentDir, job) {
+    try {
+        mkdirSync(join(agentDir, '.messaging'), { recursive: true });
+        const { app, conversation, ts, sessionId } = job;
+        appendFileSync(jobsFile(agentDir), JSON.stringify({ app, conversation, ts, sessionId, at: new Date().toISOString() }) + '\n');
+    }
+    catch (err) {
+        console.error('[loopengine] could not record the job thread:', err instanceof Error ? err.message : err);
+    }
+}
+export function findJobThread(agentDir, app, conversation, ts) {
+    return readJobs(agentDir).filter((job) => job.app === app && job.conversation === conversation && job.ts === ts).at(-1);
+}
+/** The session's latest job thread: where its last message came from. */
+export function findJobThreadBySession(agentDir, sessionId) {
+    return readJobs(agentDir).filter((job) => job.sessionId === sessionId).at(-1);
+}

package/dist/core/notifier-file.d.ts

@@ -22,15 +22,18 @@ export interface NotifierFile {
      * remembered from the console's own address when saving.
      * LOOPENGINE_PUBLIC_URL, when set, wins over it. */
     publicUrl?: string;
-    /** slack: answer replies in a request's thread (core/messaging/).
-     * Unset counts as on. */
+    /** slack, telegram: answer replies in a request's thread
+     * (core/messaging/). Unset counts as on. */
     conversations?: boolean;
-    /** slack: the people who can decide a request by replying in its
-     * thread, and whose button clicks count once any are listed. */
+    /** slack, telegram: the people who can decide a request by replying in
+     * its thread, and whose button clicks count once any are listed. */
     approvers?: MessagingApprover[];
+    /** slack, telegram: a DM to the bot, or a mention of it, starts a job
+     * (core/messaging/jobs.ts). Unset counts as off. */
+    jobs?: boolean;
 }
 export interface MessagingApprover {
-    /** The app's id for the person (Slack: U0123ABC). */
+    /** The app's id for the person (Slack: U0123ABC; Telegram: 123456789). */
     user: string;
     /** Their name when they were added, for the console. */
     name?: string;
@@ -41,6 +44,11 @@ export declare const NOTIFIER_SECRET_VARS: Record<NotifierFileChannel, string>;
  * Approve/Deny buttons in Slack, handled by the server itself at
  * POST /hooks/slack/<agent>; unset, messages carry only the decision link. */
 export declare const NOTIFIER_SLACK_SIGNING_SECRET_VAR = "LOOPENGINE_NOTIFIER_SLACK_SIGNING_SECRET";
+/** A secret LoopEngine makes when it points a Telegram bot's webhook at
+ * POST /hooks/telegram/<agent>; Telegram sends it back with every update.
+ * Set, requests get Approve/Deny buttons and replies reach the agent;
+ * unset, messages carry only the decision link. */
+export declare const NOTIFIER_TELEGRAM_WEBHOOK_SECRET_VAR = "LOOPENGINE_NOTIFIER_TELEGRAM_WEBHOOK_SECRET";
 /** In the order the Messaging tab lists them: the messaging apps, then
  * the webhook. */
 export declare const NOTIFIER_CHANNELS: NotifierFileChannel[];

package/dist/core/notifier-file.js

@@ -48,6 +48,13 @@ export const NOTIFIER_SECRET_VARS = {
  * Approve/Deny buttons in Slack, handled by the server itself at
  * POST /hooks/slack/<agent>; unset, messages carry only the decision link. */
 export const NOTIFIER_SLACK_SIGNING_SECRET_VAR = 'LOOPENGINE_NOTIFIER_SLACK_SIGNING_SECRET';
+/** A secret LoopEngine makes when it points a Telegram bot's webhook at
+ * POST /hooks/telegram/<agent>; Telegram sends it back with every update.
+ * Set, requests get Approve/Deny buttons and replies reach the agent;
+ * unset, messages carry only the decision link. */
+export const NOTIFIER_TELEGRAM_WEBHOOK_SECRET_VAR = 'LOOPENGINE_NOTIFIER_TELEGRAM_WEBHOOK_SECRET';
+/** The apps whose people can talk to the agent there (core/messaging/). */
+const TWO_WAY = ['slack', 'telegram'];
 /** In the order the Messaging tab lists them: the messaging apps, then
  * the webhook. */
 export const NOTIFIER_CHANNELS = ['slack', 'telegram', 'lark', 'email', 'webhook'];
@@ -83,17 +90,30 @@ export function validateNotifierFile(input) {
     if (raw.conversations !== undefined) {
         if (typeof raw.conversations !== 'boolean')
             throw new NotifierFileError('conversations must be true or false');
-        if (channel === 'slack')
+        if (TWO_WAY.includes(channel))
             file.conversations = raw.conversations;
     }
-    if (raw.approvers !== undefined && channel === 'slack') {
+    if (raw.jobs !== undefined) {
+        if (typeof raw.jobs !== 'boolean')
+            throw new NotifierFileError('jobs must be true or false');
+        if (TWO_WAY.includes(channel) && raw.jobs)
+            file.jobs = true;
+    }
+    if (raw.approvers !== undefined && TWO_WAY.includes(channel)) {
         if (!Array.isArray(raw.approvers))
             throw new NotifierFileError('approvers must be a list');
         const approvers = [];
         for (const a of raw.approvers) {
+            // Telegram ids are numbers; YAML may read one back as a number.
             const entry = a;
-            if (!entry || typeof entry.user !== 'string' || !/^[A-Z0-9]{2,32}$/.test(entry.user))
+            if (entry && channel === 'telegram' && typeof entry.user === 'number')
+                entry.user = String(entry.user);
+            if (channel === 'slack' && (!entry || typeof entry.user !== 'string' || !/^[A-Z0-9]{2,32}$/.test(entry.user)))
                 throw new NotifierFileError('each approver needs a Slack user id, like U0123ABC');
+            if (channel === 'telegram' && (!entry || typeof entry.user !== 'string' || !/^[0-9]{1,20}$/.test(entry.user)))
+                throw new NotifierFileError('each approver needs a Telegram user id, like 123456789');
+            if (!entry || typeof entry.user !== 'string')
+                continue;
             if (approvers.some((x) => x.user === entry.user))
                 continue;
             approvers.push({ user: entry.user, ...(typeof entry.name === 'string' && entry.name.trim() ? { name: entry.name.trim().slice(0, 80) } : {}) });
@@ -287,9 +307,24 @@ export function notifierConfigFromFile(file, env, agentName = '') {
             // No card buttons: nothing built in handles Lark's card callbacks yet,
             // so a console-configured Lark notifier relies on the decision link.
             return { config: { channel: 'lark', config: { appId: file.appId, appSecret: secret, chatId: file.chatId, publicUrl: file.publicUrl, buttons: false }, events: file.events } };
-        case 'telegram':
-            // Links to the decision page, like Lark without buttons.
-            return { config: { channel: 'telegram', config: { botToken: secret, chatId: file.chatId, publicUrl: file.publicUrl }, events: file.events } };
+        case 'telegram': {
+            // Buttons once the bot's webhook points at /hooks/telegram/<agent>
+            // (the secret is made then); otherwise the decision link does the job.
+            const webhook = Boolean(env.get(NOTIFIER_TELEGRAM_WEBHOOK_SECRET_VAR));
+            return {
+                config: {
+                    channel: 'telegram',
+                    config: {
+                        botToken: secret,
+                        chatId: file.chatId,
+                        publicUrl: file.publicUrl,
+                        buttons: webhook,
+                        replyHint: webhook && file.conversations !== false && process.env.LOOPENGINE_PLAN !== 'free',
+                    },
+                    events: file.events,
+                },
+            };
+        }
         case 'email':
             // Links to the decision page, like Lark without buttons; the secret
             // is the provider's API key.

package/dist/core/run-callbacks.d.ts

@@ -0,0 +1,39 @@
+export declare class CallbackUrlError extends Error {
+}
+export type RunCallbackEvent = 'run.done' | 'run.failed' | 'run.awaiting_approval';
+/** Whether an IP address is private, loopback, link-local or otherwise
+ * not on the public internet. */
+export declare function isPrivateAddress(address: string): boolean;
+/** Checks a callback URL as given; returns it normalised. Throws
+ * CallbackUrlError saying what's wrong. */
+export declare function checkCallbackUrl(raw: unknown): string;
+/** The workspace's callback secret: LOOPENGINE_CALLBACK_SECRET, or one
+ * made once and kept in the scheduler's folder. */
+export declare function callbackSecret(): string;
+/** The signature header for a body sent at `timestamp` (unix seconds). */
+export declare function signCallback(body: string, timestamp: number, secret?: string): string;
+export interface CallbackDelivery {
+    event: RunCallbackEvent;
+    delivered: boolean;
+    attempts: number;
+    status_code?: number;
+    error?: string;
+    at: string;
+}
+export interface DeliverOptions {
+    /** Waits between attempts, in ms; its length + 1 is the attempts made. */
+    backoffMs?: number[];
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/** Posts `payload` to `url` for `event`, retrying a failed attempt (an
+ * error, or a status other than 2xx) after each wait in backoffMs. The
+ * host is looked up first, and a private address is refused (unless
+ * local callbacks are allowed), so a public name can't lead inward. */
+export declare function deliverCallback(url: string, event: RunCallbackEvent, payload: unknown, options?: DeliverOptions): Promise<CallbackDelivery>;
+/** What a run's callback carries: the event and the run's record, without
+ * its session id, its first message or past callback deliveries. */
+export declare function runCallbackPayload(event: RunCallbackEvent, run: object): {
+    event: RunCallbackEvent;
+    run: Record<string, unknown>;
+};