loopengine 0.1.95 → 0.1.98

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

@@ -0,0 +1,71 @@
+// 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).
+//
+// 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.
+import { randomUUID } from 'node:crypto';
+import { decidePath } from '../approval-links.js';
+import { publicBaseUrl } from './webhook.js';
+// Telegram's limit for one message's text.
+const MAX_TEXT = 4096;
+async function sendTelegramMessage(botToken, chatId, text) {
+    try {
+        const res = await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ chat_id: chatId, text: text.length > MAX_TEXT ? text.slice(0, MAX_TEXT - 1) + '…' : text, disable_web_page_preview: true }),
+        });
+        const body = (await res.json().catch(() => ({})));
+        return body.ok ? { ok: true, status: res.status } : { ok: false, status: res.status, error: body.description || `HTTP ${res.status}` };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** The Messaging tab's Send test. */
+export function sendTestTelegramMessage(botToken, chatId, text) {
+    return sendTelegramMessage(botToken, chatId, text);
+}
+export class TelegramNotifier {
+    botToken;
+    chatId;
+    publicUrl;
+    /** `publicUrl`: same meaning as SlackNotifier's — each message links to
+     * the decision page when the server's address is known. */
+    constructor(options) {
+        this.botToken = options.botToken;
+        this.chatId = options.chatId;
+        this.publicUrl = options.publicUrl;
+    }
+    decideLine(pendingId, kind) {
+        const base = publicBaseUrl(this.publicUrl);
+        return base ? `\n\n${kind === 'approval' ? 'Approve or deny' : '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);
+        });
+    }
+    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}'`);
+        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}'`);
+        return { pendingId };
+    }
+    /** A plain announcement (run started/finished, a scheduled task's
+     * result), with nothing to decide. */
+    postMessage(text) {
+        this.send(text, 'an announcement');
+    }
+}

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

@@ -22,10 +22,10 @@ export declare class WebhookNotifier implements DurableApprover, DurableQuestion
         retryDelaysMs?: number[];
         publicUrl?: string;
     });
-    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string, pendingId?: string): {
         pendingId: string;
     };
-    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined, pendingId?: string): {
         pendingId: string;
     };
 }

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

@@ -104,8 +104,7 @@ export class WebhookNotifier {
         this.retryDelaysMs = options.retryDelaysMs ?? RETRY_DELAYS_MS;
         this.publicUrl = options.publicUrl;
     }
-    requestDurableApproval(tool, args, scope, reason) {
-        const pendingId = randomUUID();
+    requestDurableApproval(tool, args, scope, reason, pendingId = randomUUID()) {
         const requestedAt = new Date().toISOString();
         const resolvePath = `/pending-approvals/${pendingId}/resolve`;
         const decide = decidePath(pendingId, 'approval');
@@ -119,8 +118,7 @@ export class WebhookNotifier {
         void deliver(this.webhookUrl, body, { 'X-Actauth-Signature': sign(body, this.signingSecret) }, { agent: scope.agent, kind: 'approval', pendingId }, this.retryDelaysMs);
         return { pendingId };
     }
-    notifyPendingQuestion(question, options, agent, sessionId) {
-        const pendingId = randomUUID();
+    notifyPendingQuestion(question, options, agent, sessionId, pendingId = randomUUID()) {
         const requestedAt = new Date().toISOString();
         const answerPath = `/pending-questions/${pendingId}/answer`;
         const decide = decidePath(pendingId, 'question');

package/dist/core/model-calls/meta-model-call.d.ts

@@ -0,0 +1,15 @@
+import OpenAI from 'openai';
+import type { ModelCall } from '#core/run-agent.js';
+export interface MetaModelCallOptions {
+    /** Defaults to the META_API_KEY env var. */
+    apiKey?: string;
+    /** No hardcoded default — same reasoning as OpenAIModelCallOptions.model:
+     * pass the one you actually want. */
+    model: string;
+    maxTokens?: number;
+    /** Defaults to Meta's own Model API — override to point at a proxy/mirror. */
+    baseURL?: string;
+    /** Inject a pre-configured client instead of building one from apiKey/baseURL — e.g. to pass a custom `fetch` in tests. */
+    client?: OpenAI;
+}
+export declare function createMetaModelCall(options: MetaModelCallOptions): ModelCall;

package/dist/core/model-calls/meta-model-call.js

@@ -0,0 +1,48 @@
+// An eighth real ModelCall implementation, for Meta's Muse models
+// (muse-spark-1.3 and later) through the Meta Model API. Its
+// /chat/completions endpoint is OpenAI-compatible, function calling
+// included, so this reuses openai-model-call.ts's translation verbatim via
+// the real `openai` SDK client pointed at https://api.meta.ai/v1, same
+// pattern deepseek/kimi/glm/gemini-model-call.ts established.
+//
+// META_API_KEY is the name LiteLLM uses; Meta's own examples read a
+// generic MODEL_API_KEY, too vague next to the other providers' keys.
+// Uses `max_completion_tokens`: Meta accepts `max_tokens` only as a
+// deprecated alias. The Model API was a US-only public preview when this
+// was written.
+import OpenAI from 'openai';
+import { toMessageParams, toModelResponse } from './openai-model-call.js';
+export function createMetaModelCall(options) {
+    if (!options.client && !options.apiKey && !process.env.META_API_KEY) {
+        // Fails here, with a Meta-specific message, rather than letting the
+        // OpenAI SDK's own constructor validation reject it — that error says
+        // "set OPENAI_API_KEY", which would send someone who never touched
+        // that variable chasing the wrong fix.
+        throw new Error('createMetaModelCall: no apiKey given and META_API_KEY is not set.');
+    }
+    const client = options.client ??
+        new OpenAI({
+            // Explicitly null, not undefined, if neither is set — see
+            // kimi-model-call.ts's comment for why this matters even
+            // though the guard above already rules out reaching here with no
+            // key at all.
+            apiKey: options.apiKey ?? process.env.META_API_KEY ?? null,
+            baseURL: options.baseURL ?? 'https://api.meta.ai/v1',
+        });
+    const maxTokens = options.maxTokens ?? 4096;
+    return async (messages, system, tools) => {
+        const response = await client.chat.completions.create({
+            model: options.model,
+            max_completion_tokens: maxTokens,
+            messages: [{ role: 'system', content: system }, ...messages.flatMap(toMessageParams)],
+            tools: tools.length
+                ? tools.map((t) => ({
+                    type: 'function',
+                    function: { name: t.name, description: t.description, parameters: t.input_schema },
+                }))
+                : undefined,
+        });
+        const usage = response.usage ? { input_tokens: response.usage.prompt_tokens, output_tokens: response.usage.completion_tokens } : undefined;
+        return { ...toModelResponse(response.choices[0]), usage };
+    };
+}

package/dist/core/model-calls/openai-model-call.d.ts

@@ -22,6 +22,11 @@ export interface OpenAIModelCallOptions {
     /** Inject a pre-configured client instead of building one from apiKey — e.g. to pass a custom `fetch` in tests. */
     client?: OpenAI;
 }
+/** A tool call's arguments. Some OpenAI-compatible models now and then
+ * add something after the JSON object (a second copy, a stray character):
+ * the first complete object is used then. Arguments cut off part-way still
+ * throw, so the caller can ask again. */
+export declare function parseToolArguments(raw: string): Record<string, unknown>;
 export declare function toMessageParams(message: Message): ChatMessage[];
 export declare function toStopReason(finishReason: string): string;
 export declare function toModelResponse(choice: OpenAI.Chat.Completions.ChatCompletion.Choice): ModelResponse;

package/dist/core/model-calls/openai-model-call.js

@@ -25,6 +25,52 @@
 // limit field name, which is only decided at the request-building call
 // site below, not in these shared translation functions.
 import OpenAI from 'openai';
+/** A tool call's arguments. Some OpenAI-compatible models now and then
+ * add something after the JSON object (a second copy, a stray character):
+ * the first complete object is used then. Arguments cut off part-way still
+ * throw, so the caller can ask again. */
+export function parseToolArguments(raw) {
+    const text = (raw ?? '').trim();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        const end = firstObjectEnd(text);
+        if (end > 0 && end < text.length)
+            return JSON.parse(text.slice(0, end));
+        throw err;
+    }
+}
+/** Where the first top-level JSON object in `text` ends (after its closing
+ * brace), or -1 when it doesn't close. */
+function firstObjectEnd(text) {
+    if (text[0] !== '{')
+        return -1;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (c === '\\')
+                escaped = true;
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '"')
+            inString = true;
+        else if (c === '{')
+            depth++;
+        else if (c === '}' && --depth === 0)
+            return i + 1;
+    }
+    return -1;
+}
 export function toMessageParams(message) {
     if (typeof message.content === 'string') {
         return [{ role: message.role === 'assistant' ? 'assistant' : 'user', content: message.content }];
@@ -101,7 +147,7 @@ export function toModelResponse(choice) {
             type: 'tool_use',
             id: call.id,
             name: call.function.name,
-            input: JSON.parse(call.function.arguments),
+            input: parseToolArguments(call.function.arguments),
         });
     }
     return { stop_reason: toStopReason(choice.finish_reason), content };

package/dist/core/model-calls/xai-model-call.d.ts

@@ -0,0 +1,15 @@
+import OpenAI from 'openai';
+import type { ModelCall } from '#core/run-agent.js';
+export interface XaiModelCallOptions {
+    /** Defaults to the XAI_API_KEY env var. */
+    apiKey?: string;
+    /** No hardcoded default — same reasoning as OpenAIModelCallOptions.model:
+     * pass the one you actually want. */
+    model: string;
+    maxTokens?: number;
+    /** Defaults to xAI's own API — override to point at a proxy/mirror. */
+    baseURL?: string;
+    /** Inject a pre-configured client instead of building one from apiKey/baseURL — e.g. to pass a custom `fetch` in tests. */
+    client?: OpenAI;
+}
+export declare function createXaiModelCall(options: XaiModelCallOptions): ModelCall;

package/dist/core/model-calls/xai-model-call.js

@@ -0,0 +1,45 @@
+// A seventh real ModelCall implementation. xAI's API (Grok models) is
+// OpenAI-compatible: its own docs (docs.x.ai) point the OpenAI SDK at
+// https://api.x.ai/v1 with an xAI key, same messages/tools/tool_choice
+// request shape and tool_calls response shape. So this reuses
+// openai-model-call.ts's translation verbatim via the real `openai` SDK
+// client, same pattern deepseek/kimi/glm/gemini-model-call.ts established.
+//
+// Uses `max_completion_tokens`: xAI documents `max_tokens` as deprecated,
+// as OpenAI does.
+import OpenAI from 'openai';
+import { toMessageParams, toModelResponse } from './openai-model-call.js';
+export function createXaiModelCall(options) {
+    if (!options.client && !options.apiKey && !process.env.XAI_API_KEY) {
+        // Fails here, with a xAI-specific message, rather than letting the
+        // OpenAI SDK's own constructor validation reject it — that error says
+        // "set OPENAI_API_KEY", which would send someone who never touched
+        // that variable chasing the wrong fix.
+        throw new Error('createXaiModelCall: no apiKey given and XAI_API_KEY is not set.');
+    }
+    const client = options.client ??
+        new OpenAI({
+            // Explicitly null, not undefined, if neither is set — see
+            // kimi-model-call.ts's comment for why this matters even
+            // though the guard above already rules out reaching here with no
+            // key at all.
+            apiKey: options.apiKey ?? process.env.XAI_API_KEY ?? null,
+            baseURL: options.baseURL ?? 'https://api.x.ai/v1',
+        });
+    const maxTokens = options.maxTokens ?? 4096;
+    return async (messages, system, tools) => {
+        const response = await client.chat.completions.create({
+            model: options.model,
+            max_completion_tokens: maxTokens,
+            messages: [{ role: 'system', content: system }, ...messages.flatMap(toMessageParams)],
+            tools: tools.length
+                ? tools.map((t) => ({
+                    type: 'function',
+                    function: { name: t.name, description: t.description, parameters: t.input_schema },
+                }))
+                : undefined,
+        });
+        const usage = response.usage ? { input_tokens: response.usage.prompt_tokens, output_tokens: response.usage.completion_tokens } : undefined;
+        return { ...toModelResponse(response.choices[0]), usage };
+    };
+}

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

@@ -1,6 +1,6 @@
 import type { AgentEnv, HttpNotifierConfig, HttpNotifierEvent } from '#core/agent-config.js';
 import { type EmailProvider } from '#core/email-senders.js';
-export type NotifierFileChannel = 'webhook' | 'slack' | 'lark' | 'email';
+export type NotifierFileChannel = 'webhook' | 'telegram' | 'slack' | 'lark' | 'email';
 export interface NotifierFile {
     channel: NotifierFileChannel;
     events: HttpNotifierEvent[];
@@ -8,7 +8,8 @@ export interface NotifierFile {
     url?: string;
     /** slack: channel to post into. */
     channelId?: string;
-    /** lark: app id and chat to post into. */
+    /** lark: app id and chat to post into. telegram: the chat to post
+     * into (a numeric id like -1001234567890, or @channelname). */
     appId?: string;
     chatId?: string;
     /** email: who receives requests (comma-separated), who they come from
@@ -40,6 +41,12 @@ 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";
+/** In the order the Messaging tab lists them: the messaging apps, then
+ * the webhook. */
+export declare const NOTIFIER_CHANNELS: NotifierFileChannel[];
+/** The apps that take turns as primary. The webhook isn't one: it always
+ * sends once set up. */
+export declare const PRIMARY_CHANNELS: NotifierFileChannel[];
 export declare class NotifierFileError extends Error {
 }
 /** The older single-connection file, still read when messaging.yml is absent. */
@@ -47,11 +54,38 @@ export declare function notifierFilePath(dir: string): string;
 export declare function messagingFilePath(dir: string): string;
 /** Throws NotifierFileError naming the first problem. */
 export declare function validateNotifierFile(input: unknown): NotifierFile;
-/** The agent's connection: messaging.yml's first, else the older
- * notifier.yml's; undefined when it has neither. */
+export interface MessagingConnections {
+    /** At most one per app, in the order saved. */
+    connections: NotifierFile[];
+    /** The messaging app in use, if any (never the webhook). */
+    primary?: NotifierFileChannel;
+}
+/** Every saved connection and which messaging app is primary:
+ * messaging.yml's, else the older notifier.yml's one connection. */
+export declare function readMessagingConnections(dir: string): MessagingConnections;
+/** The connections that send: the webhook when one is set up, then the
+ * primary messaging app. */
+export declare function readActiveConnections(dir: string): NotifierFile[];
+/** The agent's main connection: the primary messaging app, else the
+ * webhook; undefined when neither is set up. It's the one the console
+ * reports, and the one Slack's replies and approvers go by. Use
+ * readActiveConnections for everything that sends. */
 export declare function readNotifierFile(dir: string): NotifierFile | undefined;
-/** Writes messaging.yml (and drops an older notifier.yml it replaces). */
-export declare function writeNotifierFile(dir: string, input: unknown): NotifierFile;
+/** Saves one app's connection, replacing that app's earlier one and
+ * keeping the others. The first messaging app saved becomes primary;
+ * `makePrimary` makes this one primary too (a webhook never is: it
+ * always sends). Writes messaging.yml (and drops an older notifier.yml
+ * it replaces). */
+export declare function writeNotifierFile(dir: string, input: unknown, options?: {
+    makePrimary?: boolean;
+}): NotifierFile;
+/** Makes a saved connection the one in use. */
+export declare function setPrimaryConnection(dir: string, channel: string): void;
+/** Removes one app's connection. Removing the primary leaves no
+ * messaging app primary, rather than quietly moving requests to another
+ * one. */
+export declare function removeMessagingConnection(dir: string, channel: string): void;
+/** Removes every connection. */
 export declare function removeNotifierFile(dir: string): void;
 /** The HttpNotifierConfig a connection describes, with its secret read
  * from `env` — or which secret is missing, so nothing is sent unsigned

package/dist/core/notifier-file.js

@@ -4,21 +4,31 @@
 // in code. Only consulted when the agent's own AgentConfig.httpNotifier
 // is unset; code always wins.
 //
-// The file holds a list of connections, though only the first is used
-// for now:
+// The file holds at most one connection per app, set up independently
+// from the tab's own section for each. A webhook always sends once it's
+// set up. Of the messaging apps (Telegram, Slack, Lark, email), only the
+// primary one does: requests, announcements and Slack's replies go
+// through it, and the others stay saved but idle until made primary. So
+// a request can go to the webhook and the primary app both, under one
+// request id.
 //
+//   primary: slack
 //   connections:
 //     - app: slack
 //       channelId: C0123456
 //       events: [approval, question]
 //       conversations: true
+//     - app: telegram
+//       chatId: "-1001234567890"
+//       events: [approval, question]
 //
-// An older agents/<name>/notifier.yml (one connection, `channel:` for
-// `app:`) is still read; saving from the console replaces it with
-// messaging.yml.
+// A file without `primary:` (written before there was one) uses its
+// first messaging app; `primary:` left empty means none is. An older
+// agents/<name>/notifier.yml (one connection, `channel:` for `app:`) is
+// still read; saving from the console replaces it with messaging.yml.
 //
 // The file holds only non-secret settings. The one secret each channel
-// needs (a webhook signing secret, a Slack bot token, a Lark app secret, an email provider's API key)
+// needs (a webhook signing secret, a Slack or Telegram bot token, a Lark app secret, an email provider's API key)
 // lives in the agent's own env (agents/<name>/.env by default, through
 // core/secret-store.ts) under a fixed name, so it's never written into a
 // file that might get committed.
@@ -29,6 +39,7 @@ import { EMAIL_PROVIDERS, createProviderSendEmail, parseAddress, parseRecipients
 /** The env var each channel's secret is read from, per agent. */
 export const NOTIFIER_SECRET_VARS = {
     webhook: 'LOOPENGINE_NOTIFIER_WEBHOOK_SECRET',
+    telegram: 'LOOPENGINE_NOTIFIER_TELEGRAM_BOT_TOKEN',
     slack: 'LOOPENGINE_NOTIFIER_SLACK_BOT_TOKEN',
     lark: 'LOOPENGINE_NOTIFIER_LARK_APP_SECRET',
     email: 'LOOPENGINE_NOTIFIER_EMAIL_API_KEY',
@@ -37,7 +48,14 @@ 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';
-const CHANNELS = ['webhook', 'slack', 'lark', 'email'];
+/** In the order the Messaging tab lists them: the messaging apps, then
+ * the webhook. */
+export const NOTIFIER_CHANNELS = ['slack', 'telegram', 'lark', 'email', 'webhook'];
+/** The apps that take turns as primary. The webhook isn't one: it always
+ * sends once set up. */
+export const PRIMARY_CHANNELS = ['telegram', 'slack', 'lark', 'email'];
+const canBePrimary = (channel) => PRIMARY_CHANNELS.includes(channel);
+const CHANNELS = NOTIFIER_CHANNELS;
 const EVENTS = ['approval', 'question', 'run_start', 'run_finish'];
 export class NotifierFileError extends Error {
 }
@@ -101,6 +119,14 @@ export function validateNotifierFile(input) {
             throw new NotifierFileError('channelId is required for slack');
         file.channelId = channelId;
     }
+    else if (channel === 'telegram') {
+        // Strings even when numeric: YAML would read -1001234567890 as a
+        // number, so it's quoted when written and accepted either way.
+        const chatId = typeof raw.chatId === 'number' ? String(raw.chatId) : str('chatId');
+        if (!chatId || !/^(-?[0-9]{1,20}|@[A-Za-z0-9_]{4,64})$/.test(chatId))
+            throw new NotifierFileError('chatId must be a Telegram chat id, like -1001234567890, or @channelname');
+        file.chatId = chatId;
+    }
     else if (channel === 'lark') {
         const appId = str('appId');
         const chatId = str('chatId');
@@ -126,38 +152,103 @@ export function validateNotifierFile(input) {
     }
     return file;
 }
-/** The agent's connection: messaging.yml's first, else the older
- * notifier.yml's; undefined when it has neither. */
-export function readNotifierFile(dir) {
+/** Every saved connection and which messaging app is primary:
+ * messaging.yml's, else the older notifier.yml's one connection. */
+export function readMessagingConnections(dir) {
     const messagingPath = messagingFilePath(dir);
     if (existsSync(messagingPath)) {
         const parsed = parseYaml(readFileSync(messagingPath, 'utf8'));
         if (parsed?.connections !== undefined && !Array.isArray(parsed.connections))
             throw new NotifierFileError('connections must be a list');
-        const first = parsed?.connections?.[0];
-        if (first === undefined)
-            return undefined;
-        if (!first || typeof first !== 'object')
-            throw new NotifierFileError('each connection must be an object');
-        const { app, ...rest } = first;
-        return validateNotifierFile({ channel: app, ...rest });
+        const connections = [];
+        for (const entry of parsed?.connections ?? []) {
+            if (!entry || typeof entry !== 'object')
+                throw new NotifierFileError('each connection must be an object');
+            const { app, ...rest } = entry;
+            const file = validateNotifierFile({ channel: app, ...rest });
+            if (!connections.some((c) => c.channel === file.channel))
+                connections.push(file);
+        }
+        // No `primary:` at all is a file from before there was one: its first
+        // messaging app was the one used, so it still is.
+        const hasPrimaryKey = parsed !== null && typeof parsed === 'object' && 'primary' in parsed;
+        const named = hasPrimaryKey ? parsed.primary : connections.find((c) => canBePrimary(c.channel))?.channel;
+        const primary = canBePrimary(named) ? connections.find((c) => c.channel === named)?.channel : undefined;
+        return primary ? { connections, primary } : { connections };
     }
     const path = notifierFilePath(dir);
     if (!existsSync(path))
-        return undefined;
-    return validateNotifierFile(parseYaml(readFileSync(path, 'utf8')));
+        return { connections: [] };
+    const file = validateNotifierFile(parseYaml(readFileSync(path, 'utf8')));
+    return canBePrimary(file.channel) ? { connections: [file], primary: file.channel } : { connections: [file] };
 }
-/** Writes messaging.yml (and drops an older notifier.yml it replaces). */
-export function writeNotifierFile(dir, input) {
-    const file = validateNotifierFile(input);
-    const { channel, ...rest } = file;
+/** The connections that send: the webhook when one is set up, then the
+ * primary messaging app. */
+export function readActiveConnections(dir) {
+    const { connections, primary } = readMessagingConnections(dir);
+    const webhook = connections.find((c) => c.channel === 'webhook');
+    const app = connections.find((c) => c.channel === primary);
+    return [...(webhook ? [webhook] : []), ...(app ? [app] : [])];
+}
+/** The agent's main connection: the primary messaging app, else the
+ * webhook; undefined when neither is set up. It's the one the console
+ * reports, and the one Slack's replies and approvers go by. Use
+ * readActiveConnections for everything that sends. */
+export function readNotifierFile(dir) {
+    const { connections, primary } = readMessagingConnections(dir);
+    return connections.find((c) => c.channel === primary) ?? connections.find((c) => c.channel === 'webhook');
+}
+function writeMessagingConnections(dir, { connections, primary }) {
+    if (!connections.length) {
+        removeNotifierFile(dir);
+        return;
+    }
     const header = '# Where this agent sends approval requests and questions when it is called over HTTP,\n' +
         '# and whether it answers replies there. Edited from the console (Messaging tab).\n' +
-        `# The secret lives in this agent's env as ${NOTIFIER_SECRET_VARS[channel]}.\n`;
-    writeFileSync(messagingFilePath(dir), header + stringifyYaml({ connections: [{ app: channel, ...rest }] }));
+        '# A webhook always sends; of the messaging apps, only the primary one does.\n' +
+        '# Each secret lives in this agent\'s env: ' + connections.map((c) => NOTIFIER_SECRET_VARS[c.channel]).join(', ') + '.\n';
+    const body = { primary: primary ?? null, connections: connections.map(({ channel, ...rest }) => ({ app: channel, ...rest })) };
+    writeFileSync(messagingFilePath(dir), header + stringifyYaml(body));
     rmSync(notifierFilePath(dir), { force: true });
+}
+/** Saves one app's connection, replacing that app's earlier one and
+ * keeping the others. The first messaging app saved becomes primary;
+ * `makePrimary` makes this one primary too (a webhook never is: it
+ * always sends). Writes messaging.yml (and drops an older notifier.yml
+ * it replaces). */
+export function writeNotifierFile(dir, input, options = {}) {
+    const file = validateNotifierFile(input);
+    const current = readMessagingConnections(dir);
+    const index = current.connections.findIndex((c) => c.channel === file.channel);
+    const connections = [...current.connections];
+    if (index === -1)
+        connections.push(file);
+    else
+        connections[index] = file;
+    const primary = canBePrimary(file.channel) && (options.makePrimary || !current.primary) ? file.channel : current.primary;
+    writeMessagingConnections(dir, { connections, primary });
     return file;
 }
+/** Makes a saved connection the one in use. */
+export function setPrimaryConnection(dir, channel) {
+    if (!canBePrimary(channel))
+        throw new NotifierFileError(`Only a messaging app (${PRIMARY_CHANNELS.join(', ')}) can be primary; a webhook always sends once set up`);
+    const current = readMessagingConnections(dir);
+    if (!current.connections.some((c) => c.channel === channel))
+        throw new NotifierFileError(`Set up ${channel} before making it primary`);
+    writeMessagingConnections(dir, { ...current, primary: channel });
+}
+/** Removes one app's connection. Removing the primary leaves no
+ * messaging app primary, rather than quietly moving requests to another
+ * one. */
+export function removeMessagingConnection(dir, channel) {
+    const current = readMessagingConnections(dir);
+    writeMessagingConnections(dir, {
+        connections: current.connections.filter((c) => c.channel !== channel),
+        primary: current.primary === channel ? undefined : current.primary,
+    });
+}
+/** Removes every connection. */
 export function removeNotifierFile(dir) {
     rmSync(messagingFilePath(dir), { force: true });
     rmSync(notifierFilePath(dir), { force: true });
@@ -196,6 +287,9 @@ 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 'email':
             // Links to the decision page, like Lark without buttons; the secret
             // is the provider's API key.