loopengine 0.3.1 → 0.3.3

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/system-agents/workflow-planner.d.ts

@@ -1,5 +1,6 @@
 import type { ToolSchema } from '#core/agent-config.js';
 import type { WorkflowParameter } from '#core/workflows.js';
+import type { TriggerSender } from '#core/workflow-triggers.js';
 import type { ModelCall } from '#core/run-agent.js';
 import type { StarterTemplate, TemplateApp } from './templates.js';
 export type Decision = 'allow' | 'ask' | 'deny';
@@ -50,7 +51,8 @@ export interface WorkflowPlan {
     id: string;
     summary: string;
     trigger: {
-        kind: 'schedule' | 'on_request';
+        /** webhook: an outside service's events start runs (see `webhook`). */
+        kind: 'schedule' | 'on_request' | 'webhook';
         description: string;
         /** schedule only: "1h", "24h", "7d". */
         every?: string;
@@ -80,8 +82,13 @@ export interface WorkflowPlan {
     /** Values a run is given, filled into $name in the start message and
      * steps (core/workflows.ts). Empty when every run is the same. */
     parameters: Record<string, WorkflowParameter>;
-    /** Whether each scheduled run's result is sent to the person through
-     * the agent's messaging app, and why (shown on the review screen). */
+    /** A webhook that starts runs: set when the trigger is "webhook", and
+     * also when a scheduled workflow should run on an event too. Made on
+     * Create, turned off until the person adds the sender's signing secret. */
+    webhook?: PlannedWebhook;
+    /** Whether each scheduled or webhook-started run's result is sent to
+     * the person through the agent's messaging app, and why (shown on the
+     * review screen). */
     notify: {
         on: boolean;
         reason: string;
@@ -104,6 +111,25 @@ export interface WorkflowPlan {
      * use (filled in on Create, from mcpServers). */
     apps?: TemplateApp[];
 }
+export interface PlannedWebhook {
+    /** Whose events: the sender whose signature it checks. "custom" is the
+     * person's own app or any other service that signs the body. */
+    sender: TriggerSender;
+    /** "Stripe: new disputes". */
+    name: string;
+    /** custom only: the header the signature comes in, when known. */
+    header?: string;
+    /** Only these events start a run: a dot path into the payload and its values. */
+    filter?: {
+        path: string;
+        values: string[];
+    };
+    /** Workflow parameter → dot path into the payload. */
+    mapping?: Record<string, string>;
+    /** What to choose in the sender's own webhook settings, in plain words:
+     * "In Stripe, listen for charge.dispute.created." */
+    setup?: string;
+}
 export interface WorkflowPlannerTools {
     /** Every agent: its tools, installed abilities, rules and messaging. */
     listAgents(): Promise<unknown>;
@@ -125,13 +151,20 @@ export interface WorkflowPlannerTools {
     /** A server's tools, when it can be listed without a key (or with one already set). */
     mcpServerTools?(id: string): Promise<unknown>;
 }
-export declare const WORKFLOW_PLANNER_PROMPT = "You turn a workflow a person describes into a plan for a LoopEngine agent.\n\nLoopEngine agents call tools. Tools come from abilities (installable packages: public ones on npm, or the workspace's own private ones) or are built in. Each tool has a permission: allow (runs on its own), ask (waits for a person to approve, edit or deny it) or deny. When nobody is in Chat, questions and approvals go to the agent's messaging app (Slack, Telegram, Lark or email) and the run waits, for days if needed, then carries on.\n\nHow to plan:\n1. Look before you plan: list_agents (what exists, and what each agent's tools and rules are), list_workspace_abilities, search_public_abilities for each kind of step, ability_details for any ability you might use (its exact tool names and the settings it needs), and list_connections.\n2. Split the workflow into steps, in order. For each step:\n   - something to fetch or do: kind \"tool\", with the exact tool name and where it comes from. Pick the source in this order:\n     a. A tool the target agent already has (from list_agents): use it, nothing to install.\n     b. An ability: a workspace ability (list_workspace_abilities) or a public one (search_public_abilities, e.g. \"firecrawl\" or \"web search\" for searching and reading the web). Set \"ability\" to its install spec (the npm name, or a workspace ability's spec) and use the exact tool name from ability_details.\n     c. Only when no ability can do it, and search_mcp_servers is available: an app's MCP server. Search for the app (e.g. \"linear\", \"stripe\"), pick the app's own server (official), else a saved or verified one, then call mcp_server_tools. Set \"mcp\" to the server's id, and \"tool\" to its exact tool name when mcp_server_tools lists them (leave \"tool\" empty when it needs a key first, and say in \"detail\" what the step does). It's set up as a private ability when the workflow is created, which picks its tools and their permissions, so add no rules for MCP tools.\n   - the person chooses or answers (\"ask me which\", \"let me pick\"): kind \"ask\", tool \"system_ask_user\" (built in, no ability). Say what options are offered. It reaches them through the agent's messaging app by itself, so don't add a separate step to post to Slack or another chat first, and don't install a chat ability just to ask.\n   - the person reviews or approves before something happens (\"let me review it\", \"before it's sent\"): kind \"approval\", on the tool that does that thing; its rule becomes \"ask\".\n   - the agent's own work (writing, summarising, choosing): kind \"other\".\n   - nothing found can do it: set \"missing\" to what's needed, and add it to gaps.\n3. Rules: every tool the workflow uses gets one. Reading and searching: allow. Anything a person should see first (sending, publishing, paying, creating something others see): ask. Never set deny unless asked.\n4. Skill: the steps in order, as numbered instructions the agent follows, naming the tools and saying exactly when to stop and ask. Write it so the agent keeps going after each answer or decision.\n5. Trigger: a schedule (\"every Monday at 9\" is every \"7d\", at \"09:00\", weekday 1) or on_request (started from Chat or a message). startMessage is what the agent receives when it starts.\n6. Notify (scheduled workflows): whether each run's result is sent to the person through the agent's messaging app. true when the result is for them and no step already delivers it (\"tell me\", \"send me\", \"let me know\", a summary or findings that no step posts or emails). false when a step already sends it (posting to a channel, emailing a report): it would arrive twice. false when the work itself is the outcome (answering emails, filing tasks), where a message every run is noise; questions and approvals reach them either way. Say why in one short sentence.\n7. Parameters: if the job is about something that changes from run to run (an order, a ticket, an alert, a customer, a date range), declare it as a parameter: a short snake_case name, a one-line description, and required when a run makes no sense without it. Write $name wherever its value goes, in startMessage and in the skill (\"Check the refund request for order $order_number.\"). Apps and people fill them in when they start a run. A scheduled job that finds its own work (\"check the inbox every 10 minutes\", \"last week's sales\") needs none. Don't make fixed settings, such as the repository or the channel, parameters: write them into the skill.\n8. Target: an existing agent only when it already has (or can install) the tools, none of the workflow's rules would change a decision it already has, and the same people would approve. Otherwise a new agent, with a short lowercase-hyphenated name and a system prompt saying who it is and what it's for. Give the reason either way.\n9. keys: the setting names its abilities need that list_connections or the agents don't show as set (from ability_details settings). Not for MCP servers: their keys are asked for on the plan.\n\nThen call save_plan once, with the whole plan. Don't ask the person questions: if something is unclear, plan the most reasonable version and note the assumption in gaps.";
+export declare const WORKFLOW_PLANNER_PROMPT = "You turn a workflow a person describes into a plan for a LoopEngine agent.\n\nLoopEngine agents call tools. Tools come from abilities (installable packages: public ones on npm, or the workspace's own private ones) or are built in. Each tool has a permission: allow (runs on its own), ask (waits for a person to approve, edit or deny it) or deny. When nobody is in Chat, questions and approvals go to the agent's messaging app (Slack, Telegram, Lark or email) and the run waits, for days if needed, then carries on.\n\nHow to plan:\n1. Look before you plan: list_agents (what exists, and what each agent's tools and rules are), list_workspace_abilities, search_public_abilities for each kind of step, ability_details for any ability you might use (its exact tool names and the settings it needs), and list_connections.\n2. Split the workflow into steps, in order. For each step:\n   - something to fetch or do: kind \"tool\", with the exact tool name and where it comes from. Pick the source in this order:\n     a. A tool the target agent already has (from list_agents): use it, nothing to install.\n     b. An ability: a workspace ability (list_workspace_abilities) or a public one (search_public_abilities, e.g. \"firecrawl\" or \"web search\" for searching and reading the web). Set \"ability\" to its install spec (the npm name, or a workspace ability's spec) and use the exact tool name from ability_details.\n     c. Only when no ability can do it, and search_mcp_servers is available: an app's MCP server. Search for the app (e.g. \"linear\", \"stripe\"), pick the app's own server (official), else a saved or verified one, then call mcp_server_tools. Set \"mcp\" to the server's id, and \"tool\" to its exact tool name when mcp_server_tools lists them (leave \"tool\" empty when it needs a key first, and say in \"detail\" what the step does). It's set up as a private ability when the workflow is created, which picks its tools and their permissions, so add no rules for MCP tools.\n   - the person chooses or answers (\"ask me which\", \"let me pick\"): kind \"ask\", tool \"system_ask_user\" (built in, no ability). Say what options are offered. It reaches them through the agent's messaging app by itself, so don't add a separate step to post to Slack or another chat first, and don't install a chat ability just to ask.\n   - the person reviews or approves before something happens (\"let me review it\", \"before it's sent\"): kind \"approval\", on the tool that does that thing; its rule becomes \"ask\".\n   - the agent's own work (writing, summarising, choosing): kind \"other\".\n   - nothing found can do it: set \"missing\" to what's needed, and add it to gaps.\n3. Rules: every tool the workflow uses gets one. Reading and searching: allow. Anything a person should see first (sending, publishing, paying, creating something others see): ask. Never set deny unless asked.\n4. Skill: the steps in order, as numbered instructions the agent follows, naming the tools and saying exactly when to stop and ask. Write it so the agent keeps going after each answer or decision.\n5. Trigger: how a run starts. startMessage is what the agent receives when it starts.\n   - schedule: a time or interval (\"every Monday at 9\" is every \"7d\", at \"09:00\", weekday 1).\n   - webhook: when something happens in another service that can call a URL (\"when a Stripe dispute comes in\", \"when a GitHub issue is opened\", \"when a Shopify order is paid\", \"when our app sends a new signup\"). Fill in \"webhook\" (below). Prefer it over polling on a schedule whenever the service sends webhooks.\n   - on_request: started by a person, from Chat, a message, the Run button or an app's API call.\n   A workflow that runs on a schedule and on an event as well: trigger schedule, and fill in \"webhook\" too.\n   webhook: sender (\"stripe\", \"github\", \"shopify\", \"standard\" for Standard Webhooks senders such as Clerk, Resend or Svix, else \"custom\" for the person's own app or any other service); a short name (\"Stripe: new disputes\"); setup: one sentence on what to pick in the sender's webhook settings; filter: which events start a run; mapping: each parameter from a dot path in the payload. What senders send:\n   - Stripe: one endpoint can get many event types, so filter path \"type\", values the event names (charge.dispute.created, checkout.session.completed, invoice.payment_failed, customer.subscription.deleted). The object is at data.object: data.object.id, data.object.customer, data.object.amount, data.object.charge.\n   - GitHub: the event type is chosen in GitHub's settings (Issues, Pull requests, Pushes), so say it in setup; filter path \"action\", values such as opened, closed, created. Fields: issue.number, issue.title, pull_request.number, repository.full_name, sender.login.\n   - Shopify: one webhook per topic (orders/paid, orders/create, customers/create), chosen in Shopify, so say it in setup and use no filter. The body is the object itself: id, name (the order number, like #1001), email, total_price, financial_status.\n   - standard: filter path \"type\" (user.created, email.bounced); fields under data (data.id, data.email_addresses).\n   - custom: whatever the person's app sends; say in setup what to post (JSON with these fields) and use the paths you described. Set \"header\" when the person names the signature header.\n   Every required parameter should come from the payload through mapping; parameters are the only way event details reach the run.\n6. Notify (scheduled and webhook workflows): whether each run's result is sent to the person through the agent's messaging app. true when the result is for them and no step already delivers it (\"tell me\", \"send me\", \"let me know\", a summary or findings that no step posts or emails). false when a step already sends it (posting to a channel, emailing a report): it would arrive twice. false when the work itself is the outcome (answering emails, filing tasks), where a message every run is noise; questions and approvals reach them either way. Say why in one short sentence.\n7. Parameters: if the job is about something that changes from run to run (an order, a ticket, an alert, a customer, a date range), declare it as a parameter: a short snake_case name, a one-line description, and required when a run makes no sense without it. Write $name wherever its value goes, in startMessage and in the skill (\"Check the refund request for order $order_number.\"). Apps and people fill them in when they start a run. A scheduled job that finds its own work (\"check the inbox every 10 minutes\", \"last week's sales\") needs none. Don't make fixed settings, such as the repository or the channel, parameters: write them into the skill.\n8. Target: an existing agent only when it already has (or can install) the tools, none of the workflow's rules would change a decision it already has, and the same people would approve. Otherwise a new agent, with a short lowercase-hyphenated name and a system prompt saying who it is and what it's for. Give the reason either way.\n9. keys: the setting names its abilities need that list_connections or the agents don't show as set (from ability_details settings). Not for MCP servers: their keys are asked for on the plan.\n\nThen call save_plan once, with the whole plan. Don't ask the person questions: if something is unclear, plan the most reasonable version and note the assumption in gaps.";
 export declare function workflowPlannerTools(withMcp?: boolean): ToolSchema[];
 /** lowercase-hyphenated, 2–40 characters. */
 export declare function slugify(value: string, fallback?: string): string;
 /** A plan from the model's save_plan input, or undefined when it lacks a
  * name, steps, a skill or a new-agent prompt. Fills in what can be derived. */
 export declare function validateWorkflowPlan(raw: unknown): WorkflowPlan | undefined;
+/** A plan's webhook, tidied: a known sender, a filter with values, and a
+ * mapping only for parameters the workflow has. Undefined without a
+ * sender. Also used on a plan edited before Create. */
+export declare function planWebhook(raw: unknown, parameters: Record<string, WorkflowParameter>): PlannedWebhook | undefined;
+/** What the person should know about a planned webhook: required
+ * parameters nothing in the payload fills. */
+export declare function webhookNotes(webhook: PlannedWebhook, parameters: Record<string, WorkflowParameter>): string[];
 /** A plan's notify choice; off when the planner gave none. */
 export declare function planNotify(raw: unknown): WorkflowPlan['notify'];
 /** A plan's parameters, tidied: names made snake_case (or dropped), a