@mono-agent/agent-app 0.4.0 → 0.4.1

package/dist/channels.js

@@ -1,50 +1,241 @@
-import { resolve } from "node:path";
-import { A2AConsumerError, A2AProviderError, startA2AProvider, } from "@mono-agent/a2a-adapter";
-import { loadA2AAdapterConfig } from "@mono-agent/a2a-adapter";
-import { CronAdapterError, loadCronAdapterConfig, startCronAdapter } from "@mono-agent/cron-adapter";
-import { loadOpenAIApiAdapterConfig, OpenAIApiAdapterError, startOpenAIApiAdapter, } from "@mono-agent/openai-api-adapter";
-import { loadSlackAdapterConfig, SlackAdapterConfigError, startSlackAdapter, } from "@mono-agent/slack-adapter";
-import { loadTelegramAdapterConfig, startTelegramAdapter, TelegramAdapterConfigError, } from "@mono-agent/telegram-adapter";
-import { loadWebhookAdapterConfig, startWebhookAdapter, WebhookAdapterError, } from "@mono-agent/webhook-adapter";
-import { loadWhatsAppAdapterConfig, startWhatsAppAdapter, WhatsAppAdapterConfigError, } from "@mono-agent/whatsapp-adapter";
+import { NOTHING_TO_REPORT_SENTINEL } from "@mono-agent/agent-contracts";
+import { describeRunFailureKind } from "@mono-agent/observability";
+import { discoverLocalProviderModels, modelReferenceKey, parseMonoRuntimeModelReference, resolveModelEffortLevels, } from "@mono-agent/runtime-adapter";
+import { isAdapterSendToolAllowed } from "./adapter-send-tools.js";
+import { isChannelConfigured } from "./channel-gate.js";
+import { buildChannelConfigView } from "./channel-config-view.js";
+import { resolveConfiguredChannelPlugins, } from "./channel-plugins.js";
+import { findTriggerOverrideIssues } from "./trigger-overrides.js";
+import { appendPostedMessage, lookupProducingConversation } from "./posted-message-index.js";
+/** The channel ids this app can drive from config (third-party drivers add their own). */
+export const BUILTIN_CHANNEL_IDS = [
+    "telegram",
+    "slack",
+    "webhook",
+    "openai-api",
+    "cron",
+    "tui",
+    "live",
+];
+let telegramModule;
+let slackModule;
+let webhookModule;
+let openaiApiModule;
+let cronModule;
+let tuiModule;
+const loadTelegramModule = async () => (telegramModule ??= await import("@mono-agent/telegram-adapter"));
+const loadSlackModule = async () => (slackModule ??= await import("@mono-agent/slack-adapter"));
+const loadWebhookModule = async () => (webhookModule ??= await import("@mono-agent/webhook-adapter"));
+const loadOpenAIApiModule = async () => (openaiApiModule ??= await import("@mono-agent/openai-api-adapter"));
+const loadCronModule = async () => (cronModule ??= await import("@mono-agent/cron-adapter"));
+const loadTuiModule = async () => (tuiModule ??= await import("@mono-agent/operator-adapter"));
+let liveModule;
+const loadLiveModule = async () => (liveModule ??= await import("@mono-agent/operator-adapter"));
+const TELEGRAM_GATE = { jsonKey: "telegram", envPrefix: "MONO_AGENT_TELEGRAM_" };
+const SLACK_GATE = { jsonKey: "slack", envPrefix: "MONO_AGENT_SLACK_" };
+const WEBHOOK_GATE = { jsonKey: "webhook", envPrefix: "MONO_AGENT_WEBHOOK_", dir: "webhook" };
+const OPENAI_API_GATE = { jsonKey: "openaiApi", envPrefix: "MONO_AGENT_OPENAI_API_" };
+const CRON_GATE = { jsonKey: "cron", envPrefix: "MONO_AGENT_CRON_", dir: "cron" };
+const UNCONFIGURED_TELEGRAM_CONFIG = {
+    enabled: false,
+    botToken: "",
+    allowedChatIds: [],
+    allowAllChats: false,
+};
+const UNCONFIGURED_SLACK_CONFIG = {
+    enabled: false,
+    botToken: "",
+    appToken: "",
+    allowedChannelIds: [],
+    allowAllChannels: false,
+    botUserIds: [],
+    mentionTextAliases: [],
+    stripMentionText: false,
+    shortcuts: [],
+    homeTab: { enabled: false, buttons: [] },
+};
+const UNCONFIGURED_WEBHOOK_CONFIG = {
+    enabled: false,
+    host: "127.0.0.1",
+    port: 0,
+    allowNonLoopback: false,
+    retentionMs: 300_000,
+    maxStoredRequests: 100,
+    endpoints: [{ name: "default", path: "/webhook/invoke", mode: "sync", enabled: true }],
+    path: "/webhook/invoke",
+    defaultMode: "sync",
+};
+const UNCONFIGURED_OPENAI_API_CONFIG = {
+    enabled: false,
+    host: "127.0.0.1",
+    port: 0,
+    basePath: "/v1",
+    allowNonLoopback: false,
+    modelId: "agent",
+};
+const UNCONFIGURED_CRON_CONFIG = { jobs: [] };
+/** Config-view section for a channel the gate found no intent for (no fields to annotate). */
+function unconfiguredChannelView(id, label) {
+    return { id, label, status: "disabled", fields: [] };
+}
 export function createTelegramChannelDriver(overrides = {}) {
     return {
         id: "telegram",
         label: "Telegram",
+        async configView(input) {
+            if (!(await isChannelConfigured(input, TELEGRAM_GATE))) {
+                return unconfiguredChannelView("telegram", "Telegram");
+            }
+            const adapter = await loadTelegramModule();
+            return await buildChannelConfigView(this, adapter.TELEGRAM_CONFIG_FIELDS, input);
+        },
         async loadConfig(input) {
-            return await loadTelegramAdapterConfig({ env: input.env, jsonPath: input.configPath });
+            if (!(await isChannelConfigured(input, TELEGRAM_GATE))) {
+                return UNCONFIGURED_TELEGRAM_CONFIG;
+            }
+            const adapter = await loadTelegramModule();
+            return await adapter.loadTelegramAdapterConfig({ env: input.env, jsonPath: input.configPath });
         },
         isConfigError(error) {
-            return error instanceof TelegramAdapterConfigError;
+            return telegramModule !== undefined && error instanceof telegramModule.TelegramAdapterConfigError;
         },
         disabledReason(config) {
             return config.enabled ? undefined : "Telegram is disabled.";
         },
         async start(input) {
-            const startAdapter = overrides.startAdapter ?? startTelegramAdapter;
+            const adapter = await loadTelegramModule();
+            const startAdapter = overrides.startAdapter ?? adapter.startTelegramAdapter;
             const result = await startAdapter(telegramStartOptions(input, overrides));
+            // Register this channel's interaction sink so the host bridge can post
+            // ask_user questions and tool-progress status lines into Telegram chats.
+            // The sink enforces the adapter allowlist: a tool-supplied conversation
+            // can never reach a chat the operator never allowlisted.
+            input.interaction?.registerSink("telegram", {
+                postQuestion: async (conversationId, text) => {
+                    await result.post(requireAllowedTelegramChat(conversationId, input), text);
+                },
+                postStatus: async (conversationId, text, statusOptions) => {
+                    await result.postStatus(requireAllowedTelegramChat(conversationId, input), text, statusOptions);
+                },
+            });
             return {
                 summary: {},
                 stop: () => result.stop(),
+                // Push delivery: a proactive nudge to telegram:<chat> runs as a turn on
+                // this chat's own harness and is delivered through the normal stream.
+                // Enforces the adapter allowlist so a payload-supplied destination cannot
+                // reach a chat the operator never allowlisted.
+                notify: async ({ conversationId, text, verbatim }) => {
+                    const chatId = telegramChatIdFromConversation(conversationId);
+                    if (chatId === undefined) {
+                        input.logger?.warn?.("Telegram proactive notify skipped: unparseable destination.", { conversationId });
+                        return { delivered: false, reason: "unparseable telegram destination" };
+                    }
+                    if (!input.config.allowAllChats && !input.config.allowedChatIds.includes(String(chatId))) {
+                        input.logger?.warn?.("Telegram proactive notify skipped: destination not in allowlist.", { conversationId });
+                        return { delivered: false, reason: "telegram chat is not in the adapter allowlist" };
+                    }
+                    // During configured quiet hours, deliver silently (disable_notification)
+                    // so an overnight cron/webhook result lands without a push sound.
+                    const silent = input.config.quietHours !== undefined &&
+                        adapter.isWithinQuietHours(new Date(), input.config.quietHours);
+                    const notifyOptions = verbatim === undefined && !silent
+                        ? undefined
+                        : {
+                            ...(verbatim === undefined ? {} : { verbatim }),
+                            ...(silent ? { silent: true } : {}),
+                        };
+                    return await result.notify(chatId, text, notifyOptions);
+                },
             };
         },
     };
 }
+/**
+ * Download-path attachment options from config (`maxUploadBytes` stays with the
+ * send tools, which reload the config themselves).
+ */
+function telegramAttachmentOptions(config) {
+    const attachments = config.attachments;
+    if (attachments?.maxBytes === undefined && attachments?.downloadTimeoutMs === undefined) {
+        return undefined;
+    }
+    return {
+        ...(attachments.maxBytes === undefined ? {} : { maxBytes: attachments.maxBytes }),
+        ...(attachments.downloadTimeoutMs === undefined ? {} : { downloadTimeoutMs: attachments.downloadTimeoutMs }),
+    };
+}
+/** Resolve + allowlist-check a `telegram:<chat>` destination for interaction-sink posts. */
+function requireAllowedTelegramChat(conversationId, input) {
+    const chatId = telegramChatIdFromConversation(conversationId);
+    if (chatId === undefined) {
+        throw new Error(`unparseable telegram destination: ${conversationId}`);
+    }
+    if (!input.config.allowAllChats && !input.config.allowedChatIds.includes(String(chatId))) {
+        throw new Error("telegram chat is not in the adapter allowlist.");
+    }
+    return chatId;
+}
+/** Extract the Telegram chat id from a `telegram:<chat>` conversationId (numeric ids become numbers; a rollover #bucket suffix is stripped). */
+export function telegramChatIdFromConversation(conversationId) {
+    const prefix = "telegram:";
+    if (!conversationId.startsWith(prefix)) {
+        return undefined;
+    }
+    const raw = conversationId.slice(prefix.length).split("#", 1)[0]?.trim();
+    if (raw === undefined || raw.length === 0) {
+        return undefined;
+    }
+    return /^-?\d+$/u.test(raw) ? Number(raw) : raw;
+}
 export function createSlackChannelDriver(overrides = {}) {
     return {
         id: "slack",
         label: "Slack",
+        async configView(input) {
+            if (!(await isChannelConfigured(input, SLACK_GATE))) {
+                return unconfiguredChannelView("slack", "Slack");
+            }
+            const adapter = await loadSlackModule();
+            return await buildChannelConfigView(this, adapter.SLACK_CONFIG_FIELDS, input);
+        },
         async loadConfig(input) {
-            return await loadSlackAdapterConfig({ env: input.env, jsonPath: input.configPath });
+            if (!(await isChannelConfigured(input, SLACK_GATE))) {
+                return UNCONFIGURED_SLACK_CONFIG;
+            }
+            const adapter = await loadSlackModule();
+            return await adapter.loadSlackAdapterConfig({ env: input.env, jsonPath: input.configPath });
         },
         isConfigError(error) {
-            return error instanceof SlackAdapterConfigError;
+            return slackModule !== undefined && error instanceof slackModule.SlackAdapterConfigError;
         },
         disabledReason(config) {
             return config.enabled ? undefined : "Slack is disabled.";
         },
         async start(input) {
-            const startAdapter = overrides.startAdapter ?? startSlackAdapter;
+            const adapter = await loadSlackModule();
+            const startAdapter = overrides.startAdapter ?? adapter.startSlackAdapter;
+            // Link posted messages to their producing conversation so an in-thread reply
+            // resumes that conversation instead of a fresh, history-less slack: thread.
+            const indexPath = input.postedMessageIndexPath;
+            // Forward the operator's optional Socket Mode resilience tuning; omitting a
+            // field lets the runner apply its own default.
+            const reconnect = {};
+            if (input.config.reconnectInitialBackoffMs !== undefined)
+                reconnect.initialMs = input.config.reconnectInitialBackoffMs;
+            if (input.config.reconnectMaxBackoffMs !== undefined)
+                reconnect.maxMs = input.config.reconnectMaxBackoffMs;
+            if (input.config.reconnectStabilityMs !== undefined)
+                reconnect.stabilityMs = input.config.reconnectStabilityMs;
+            if (input.config.reconnectStartupGraceMs !== undefined)
+                reconnect.startupGraceMs = input.config.reconnectStartupGraceMs;
+            if (input.config.drainDeadlineMs !== undefined)
+                reconnect.drainDeadlineMs = input.config.drainDeadlineMs;
+            const heartbeat = {};
+            if (input.config.heartbeatIntervalMs !== undefined)
+                heartbeat.intervalMs = input.config.heartbeatIntervalMs;
+            if (input.config.heartbeatTimeoutMs !== undefined)
+                heartbeat.timeoutMs = input.config.heartbeatTimeoutMs;
             const result = await startAdapter({
                 botToken: input.config.botToken,
                 appToken: input.config.appToken,
@@ -53,84 +244,122 @@ export function createSlackChannelDriver(overrides = {}) {
                 botUserIds: input.config.botUserIds,
                 mentionTextAliases: input.config.mentionTextAliases,
                 stripMentionText: input.config.stripMentionText,
+                shortcuts: input.config.shortcuts,
+                homeTab: input.config.homeTab,
                 responder: input.responder,
+                // A Socket Mode drop is recoverable by construction (the runner always
+                // reconnects with backoff), so report it as DEGRADED — keep the responder/
+                // harness alive — rather than fatal. onConnectionRestored flips the channel
+                // back to running once a reconnect stays up past the stability window.
+                onConnectionLost: (reason) => input.onDegraded?.(reason),
+                onConnectionRestored: () => input.onRecovered?.(),
+                ...(Object.keys(reconnect).length === 0 ? {} : { reconnect }),
+                ...(Object.keys(heartbeat).length === 0 ? {} : { heartbeat }),
                 ...(input.logger === undefined ? {} : { logger: input.logger }),
+                ...(indexPath === undefined
+                    ? {}
+                    : {
+                        resolvePostIndex: (channelId, ts) => lookupProducingConversation(indexPath, channelId, ts),
+                        recordPostedMessage: (channelId, ts, conversationId) => {
+                            void appendPostedMessage(indexPath, { channelId, ts, conversationId });
+                        },
+                    }),
                 ...(overrides.createApi === undefined ? {} : { createApi: overrides.createApi }),
                 ...(overrides.webSocketFactory === undefined ? {} : { webSocketFactory: overrides.webSocketFactory }),
             });
             return {
                 summary: {},
                 stop: () => result.stop(),
+                // Push delivery: a proactive nudge to slack:<ch>[:<thread>] runs as a turn
+                // on that conversation's own harness and is delivered through the stream.
+                // Enforces the adapter allowlist so a payload-supplied destination cannot
+                // reach a channel the operator never allowlisted.
+                notify: async ({ conversationId, text, verbatim }) => {
+                    const target = slackTargetFromConversation(conversationId);
+                    if (target === undefined) {
+                        input.logger?.warn?.("Slack proactive notify skipped: unparseable destination.", { conversationId });
+                        return { delivered: false, reason: "unparseable slack destination" };
+                    }
+                    const normalized = target.channelId.trim().toLowerCase();
+                    const allowed = input.config.allowAllChannels ||
+                        input.config.allowedChannelIds.some((id) => id.trim().toLowerCase() === normalized);
+                    if (!allowed) {
+                        input.logger?.warn?.("Slack proactive notify skipped: destination not in allowlist.", { conversationId });
+                        return { delivered: false, reason: "slack channel is not in the adapter allowlist" };
+                    }
+                    return await result.adapter.notify(target.channelId, target.threadTs, text, verbatim === undefined ? undefined : { verbatim });
+                },
             };
         },
     };
 }
-export function createA2AChannelDriver(overrides = {}) {
-    return {
-        id: "a2a",
-        label: "A2A",
-        async loadConfig(input) {
-            return await loadA2AAdapterConfig({ env: input.env, jsonPath: input.configPath });
-        },
-        isConfigError(error) {
-            return error instanceof A2AProviderError || error instanceof A2AConsumerError;
-        },
-        disabledReason(config) {
-            return config.provider.enabled ? undefined : "A2A provider is disabled.";
-        },
-        waitingReason(config) {
-            if (config.agent === undefined || config.skill === undefined) {
-                return "A2A provider requires agent and skill configuration.";
-            }
+/** Extract `{channelId, threadTs?}` from a `slack:<ch>[:<thread>]` conversationId (a rollover #bucket suffix is stripped). */
+export function slackTargetFromConversation(conversationId) {
+    const prefix = "slack:";
+    if (!conversationId.startsWith(prefix)) {
+        return undefined;
+    }
+    const rest = conversationId.slice(prefix.length).split("#", 1)[0];
+    if (rest === undefined || rest.length === 0) {
+        return undefined;
+    }
+    const colon = rest.indexOf(":");
+    if (colon < 0) {
+        const channelId = rest.trim();
+        if (channelId.length === 0) {
             return undefined;
-        },
-        async start(input) {
-            const config = input.config;
-            if (config.agent === undefined || config.skill === undefined) {
-                throw new A2AProviderError("missing_required_config", "A2A provider requires agent and skill configuration.");
-            }
-            const providerFactory = overrides.providerFactory ?? startA2AProvider;
-            const provider = await providerFactory({
-                host: config.provider.host,
-                port: config.provider.port,
-                ...(config.provider.publicBaseUrl === undefined ? {} : { publicBaseUrl: config.provider.publicBaseUrl }),
-                allowNonLoopback: config.provider.allowNonLoopback,
-                requireBearer: config.provider.requireBearer,
-                ...(config.provider.bearerToken === undefined ? {} : { bearerToken: config.provider.bearerToken }),
-                responder: input.responder,
-                agent: {
-                    name: config.agent.name,
-                    description: config.agent.description,
-                    version: config.agent.version,
-                    ...(config.agent.providerOrganization === undefined || config.agent.providerUrl === undefined
-                        ? {}
-                        : {
-                            provider: {
-                                organization: config.agent.providerOrganization,
-                                url: config.agent.providerUrl,
-                            },
-                        }),
-                },
-                skill: config.skill,
-                ...(input.logger === undefined ? {} : { logger: input.logger }),
-            });
-            return {
-                summary: { agentCardUrl: provider.agentCardUrl },
-                stop: () => provider.stop(),
-            };
-        },
-    };
+        }
+        return { channelId };
+    }
+    const channelId = rest.slice(0, colon).trim();
+    const threadTs = rest.slice(colon + 1).trim();
+    if (channelId.length === 0) {
+        return undefined;
+    }
+    if (threadTs.length === 0) {
+        return { channelId };
+    }
+    // A canonical Slack threadTs (e.g. 1718800000.123456) never contains a colon, so a
+    // stray/double colon is an operator typo — reject it so the driver warns + skips
+    // cleanly rather than posting to the Slack API with a malformed thread_ts.
+    if (threadTs.includes(":")) {
+        return undefined;
+    }
+    return { channelId, threadTs };
 }
+// Default wall-clock bound for a webhook run, reclaiming a hung slot. Mirrors
+// {@link DEFAULT_CRON_MAX_RUN_MS}; an operator can override via webhook.maxRunMs.
+const DEFAULT_WEBHOOK_MAX_RUN_MS = 20 * 60 * 1000;
 export function createWebhookChannelDriver(overrides = {}) {
     return {
         id: "webhook",
         label: "Webhook",
+        async configView(input) {
+            if (!(await isChannelConfigured(input, WEBHOOK_GATE))) {
+                return unconfiguredChannelView("webhook", "Webhook");
+            }
+            const adapter = await loadWebhookModule();
+            return await buildChannelConfigView(this, adapter.WEBHOOK_CONFIG_FIELDS, input);
+        },
+        configIssues(config) {
+            return findTriggerOverrideIssues(config.endpoints
+                .filter((endpoint) => endpoint.enabled)
+                .map((endpoint) => ({
+                name: `webhook endpoint "${endpoint.name}"`,
+                ...(endpoint.model === undefined ? {} : { model: endpoint.model }),
+                ...(endpoint.effort === undefined ? {} : { effort: endpoint.effort }),
+            })));
+        },
         async loadConfig(input) {
+            if (!(await isChannelConfigured(input, WEBHOOK_GATE))) {
+                return UNCONFIGURED_WEBHOOK_CONFIG;
+            }
+            const adapter = await loadWebhookModule();
             // cwd is required so `webhook/*.md` endpoint files are discovered.
-            return await loadWebhookAdapterConfig({ env: input.env, jsonPath: input.configPath, cwd: input.cwd });
+            return await adapter.loadWebhookAdapterConfig({ env: input.env, jsonPath: input.configPath, cwd: input.cwd });
         },
         isConfigError(error) {
-            return error instanceof WebhookAdapterError;
+            return webhookModule !== undefined && error instanceof webhookModule.WebhookAdapterError;
         },
         disabledReason(config) {
             return config.enabled ? undefined : "Webhook adapter is disabled.";
@@ -141,7 +370,10 @@ export function createWebhookChannelDriver(overrides = {}) {
                 : "Webhook adapter has no enabled endpoints.";
         },
         async start(input) {
-            const adapterFactory = overrides.adapterFactory ?? startWebhookAdapter;
+            const endpoints = input.config.endpoints.filter((endpoint) => endpoint.enabled);
+            const endpointByName = new Map(endpoints.map((endpoint) => [endpoint.name, endpoint]));
+            const adapterModule = await loadWebhookModule();
+            const adapterFactory = overrides.adapterFactory ?? adapterModule.startWebhookAdapter;
             const adapter = await adapterFactory({
                 host: input.config.host,
                 port: input.config.port,
@@ -149,15 +381,31 @@ export function createWebhookChannelDriver(overrides = {}) {
                 defaultMode: input.config.defaultMode,
                 retentionMs: input.config.retentionMs,
                 maxStoredRequests: input.config.maxStoredRequests,
-                endpoints: input.config.endpoints
-                    .filter((endpoint) => endpoint.enabled)
+                // Default-on max-run bound so a hung (esp. async) webhook can't hold a
+                // conversation slot forever; mirrors the cron adapter's 20-min default.
+                maxRunMs: input.config.maxRunMs ?? DEFAULT_WEBHOOK_MAX_RUN_MS,
+                endpoints: endpoints
                     .map((endpoint) => ({
                     name: endpoint.name,
                     path: endpoint.path,
                     mode: endpoint.mode,
                     ...(endpoint.prompt === undefined ? {} : { prompt: endpoint.prompt }),
+                    ...(endpoint.notify === undefined ? {} : { notify: endpoint.notify }),
+                    ...(endpoint.notifyConversationId === undefined ? {} : { notifyConversationId: endpoint.notifyConversationId }),
+                    ...(endpoint.model === undefined ? {} : { model: endpoint.model }),
+                    ...(endpoint.effort === undefined ? {} : { effort: endpoint.effort }),
                 })),
                 responder: input.responder,
+                onResult: (status, request) => {
+                    void deliverNativeWebhookNotification({
+                        endpoint: endpointByName.get(request.metadata.webhook.endpointName),
+                        status,
+                        request,
+                        ...(input.notifyDestination === undefined ? {} : { notifyDestination: input.notifyDestination }),
+                        ...(input.listNotifyDestinations === undefined ? {} : { listNotifyDestinations: input.listNotifyDestinations }),
+                        ...(input.logger === undefined ? {} : { logger: input.logger }),
+                    });
+                },
                 ...(input.logger === undefined ? {} : { logger: input.logger }),
             });
             return {
@@ -175,17 +423,29 @@ export function createOpenAIApiChannelDriver(overrides = {}) {
     return {
         id: "openai-api",
         label: "OpenAI API",
+        async configView(input) {
+            if (!(await isChannelConfigured(input, OPENAI_API_GATE))) {
+                return unconfiguredChannelView("openai-api", "OpenAI API");
+            }
+            const adapter = await loadOpenAIApiModule();
+            return await buildChannelConfigView(this, adapter.OPENAI_API_CONFIG_FIELDS, input, { jsonKey: "openaiApi" });
+        },
         async loadConfig(input) {
-            return await loadOpenAIApiAdapterConfig({ env: input.env, jsonPath: input.configPath });
+            if (!(await isChannelConfigured(input, OPENAI_API_GATE))) {
+                return UNCONFIGURED_OPENAI_API_CONFIG;
+            }
+            const adapter = await loadOpenAIApiModule();
+            return await adapter.loadOpenAIApiAdapterConfig({ env: input.env, jsonPath: input.configPath });
         },
         isConfigError(error) {
-            return error instanceof OpenAIApiAdapterError;
+            return openaiApiModule !== undefined && error instanceof openaiApiModule.OpenAIApiAdapterError;
         },
         disabledReason(config) {
             return config.enabled ? undefined : "OpenAI API adapter is disabled.";
         },
         async start(input) {
-            const adapterFactory = overrides.adapterFactory ?? startOpenAIApiAdapter;
+            const adapterModule = await loadOpenAIApiModule();
+            const adapterFactory = overrides.adapterFactory ?? adapterModule.startOpenAIApiAdapter;
             const adapter = await adapterFactory({
                 host: input.config.host,
                 port: input.config.port,
@@ -203,15 +463,231 @@ export function createOpenAIApiChannelDriver(overrides = {}) {
         },
     };
 }
+/**
+ * `/v1/info` re-runs local-provider discovery at most this often; the TUI
+ * fetches info on connect + agent switch (not per turn), so this just bounds
+ * how often a flaky/slow local endpoint gets probed rather than affecting
+ * perceived freshness in practice.
+ */
+const LOCAL_MODEL_DISCOVERY_TTL_MS = 30_000;
+/**
+ * The TUI stream endpoint deviates from the channels-off convention: with no
+ * `tui` section and no `MONO_AGENT_TUI_*` env it is ENABLED on loopback with
+ * an ephemeral port, so `mono-agent tui` can reach any running agent without a
+ * per-agent config edit. There is consequently no isChannelConfigured gate and
+ * no synthetic UNCONFIGURED constant — the real loader always answers (its
+ * empty-input output is `enabled: true` + defaults). `"tui": {"enabled": false}`
+ * opts out.
+ */
+export function createTuiChannelDriver(overrides = {}) {
+    return {
+        id: "tui",
+        label: "TUI",
+        async configView(input) {
+            const adapter = await loadTuiModule();
+            return await buildChannelConfigView(this, adapter.TUI_CONFIG_FIELDS, input, { jsonKey: "tui" });
+        },
+        async loadConfig(input) {
+            const adapter = await loadTuiModule();
+            return await adapter.loadTuiAdapterConfig({ env: input.env, jsonPath: input.configPath });
+        },
+        isConfigError(error) {
+            return tuiModule !== undefined && error instanceof tuiModule.TuiAdapterError;
+        },
+        disabledReason(config) {
+            return config.enabled ? undefined : "TUI stream endpoint is disabled.";
+        },
+        async start(input) {
+            const adapterModule = await loadTuiModule();
+            const adapterFactory = overrides.adapterFactory ?? adapterModule.startTuiAdapter;
+            const discoverModels = overrides.discoverModels ?? discoverLocalProviderModels;
+            const localProviders = input.coreConfig.providers?.local;
+            // The statically configured candidate models: the primary first, then
+            // each configured fallback, as canonical `modelReferenceKey` strings,
+            // de-duplicated (a fallback redundantly naming the primary collapses away).
+            const configModelKeys = [];
+            for (const ref of [input.coreConfig.runtime.model, ...(input.coreConfig.runtime.fallbackModels ?? [])]) {
+                const key = modelReferenceKey(ref);
+                if (!configModelKeys.includes(key)) {
+                    configModelKeys.push(key);
+                }
+            }
+            // Local-provider discovery is async and its result can change after
+            // startup (an endpoint started later, a model loaded/unloaded) — so
+            // `info` is a PROVIDER the adapter re-invokes on every GET /v1/info,
+            // rather than a value snapshotted once at channel composition. A short
+            // TTL cache keeps a flaky/slow endpoint from being hammered; the TUI
+            // only calls /v1/info on connect + agent switch, not per turn, so 30s
+            // of staleness there is unnoticeable in practice.
+            let discoveryCache;
+            const discoverModelsCached = async () => {
+                const now = Date.now();
+                if (discoveryCache !== undefined && now < discoveryCache.expiresAt) {
+                    return discoveryCache.models;
+                }
+                const models = await discoverModels(localProviders);
+                discoveryCache = { expiresAt: now + LOCAL_MODEL_DISCOVERY_TTL_MS, models };
+                return models;
+            };
+            const buildInfo = async () => {
+                const discovered = await discoverModelsCached();
+                const labelByRef = new Map(discovered.map((model) => [model.ref, model.label]));
+                const models = [...configModelKeys];
+                for (const model of discovered) {
+                    if (!models.includes(model.ref)) {
+                        models.push(model.ref);
+                    }
+                }
+                const modelOptions = {};
+                for (const ref of models) {
+                    let parsedRef;
+                    try {
+                        parsedRef = parseMonoRuntimeModelReference(ref);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const resolved = resolveModelEffortLevels(parsedRef, localProviders);
+                    const label = labelByRef.get(ref);
+                    const entry = {
+                        ...(resolved.effortLevels === undefined ? {} : { effortLevels: resolved.effortLevels }),
+                        reasoning: resolved.reasoning,
+                        ...(resolved.reasoningMode === undefined ? {} : { reasoningMode: resolved.reasoningMode }),
+                        ...(label === undefined ? {} : { label }),
+                    };
+                    if (Object.keys(entry).length > 0) {
+                        modelOptions[ref] = entry;
+                    }
+                }
+                return {
+                    model: modelReferenceKey(input.coreConfig.runtime.model),
+                    ...(input.coreConfig.runtime.effort === undefined ? {} : { effort: input.coreConfig.runtime.effort }),
+                    models,
+                    ...(Object.keys(modelOptions).length === 0 ? {} : { modelOptions }),
+                };
+            };
+            const adapter = await adapterFactory({
+                host: input.config.host,
+                port: input.config.port,
+                basePath: input.config.basePath,
+                allowNonLoopback: input.config.allowNonLoopback,
+                ...(input.config.apiKey === undefined ? {} : { apiKey: input.config.apiKey }),
+                responder: input.responder,
+                info: buildInfo,
+                // A dead endpoint must flip the channel to failed, not serve nothing
+                // silently — the TUI's only discovery signal is this channel's status.
+                onServerError: (reason) => input.onFailure(reason),
+                ...(input.logger === undefined ? {} : { logger: input.logger }),
+            });
+            return {
+                summary: { baseUrl: adapter.baseUrl },
+                stop: () => adapter.stop(),
+            };
+        },
+    };
+}
+/**
+ * The live event relay, like the TUI endpoint, deviates from the channels-off
+ * convention: it is ENABLED by default on loopback with an ephemeral port so
+ * `mono-agent web` can observe any running agent without a per-agent config edit.
+ * It is passive and read-only — it relays the host's in-process run-event bus over
+ * SSE and never drives a turn. `"live": {"enabled": false}` opts out.
+ */
+export function createLiveChannelDriver(overrides = {}) {
+    return {
+        id: "live",
+        label: "Live",
+        async configView(input) {
+            const adapter = await loadLiveModule();
+            return await buildChannelConfigView(this, adapter.LIVE_CONFIG_FIELDS, input, { jsonKey: "live" });
+        },
+        async loadConfig(input) {
+            const adapter = await loadLiveModule();
+            return await adapter.loadLiveAdapterConfig({ env: input.env, jsonPath: input.configPath });
+        },
+        isConfigError(error) {
+            return liveModule !== undefined && error instanceof liveModule.LiveAdapterError;
+        },
+        disabledReason(config) {
+            return config.enabled ? undefined : "Live event relay is disabled.";
+        },
+        async start(input) {
+            const adapterModule = await loadLiveModule();
+            const adapterFactory = overrides.adapterFactory ?? adapterModule.startLiveAdapter;
+            // The host feeds the shared run-event bus (via the broadcast recorder). If it
+            // has none, still serve an (empty) stream rather than failing the channel.
+            const bus = input.liveEventBus ?? adapterModule.createLiveEventBus();
+            const adapter = await adapterFactory({
+                bus,
+                host: input.config.host,
+                port: input.config.port,
+                basePath: input.config.basePath,
+                allowNonLoopback: input.config.allowNonLoopback,
+                ...(input.config.apiKey === undefined ? {} : { apiKey: input.config.apiKey }),
+                // A dead endpoint must flip the channel to failed, not serve nothing
+                // silently — the web surface's only per-agent live signal is this status.
+                onServerError: (reason) => input.onFailure(reason),
+                ...(input.logger === undefined ? {} : { logger: input.logger }),
+            });
+            return {
+                summary: { baseUrl: adapter.baseUrl },
+                stop: () => adapter.stop(),
+            };
+        },
+    };
+}
+/**
+ * 20 minutes — comfortably above any real briefing/scan (observed max ~6.5 min) yet bounded, so a
+ * hung run is reclaimed rather than blocking the job indefinitely.
+ */
+const DEFAULT_CRON_MAX_RUN_MS = 20 * 60 * 1000;
+const DEFAULT_CRON_FAILURE_NOTICE_COOLDOWN_HOURS = 6;
+const MAX_CRON_FAILURE_NOTICE_ERROR_CHARS = 180;
+/**
+ * Whether a notify-enabled turn's final text should suppress delivery: empty /
+ * whitespace-only (the agent chose to stay silent) or exactly the
+ * {@link NOTHING_TO_REPORT_SENTINEL} token. Matched trimmed and
+ * case-insensitively; never substring-matched, so a digest that merely mentions
+ * the phrase is still delivered.
+ */
+function suppressesNotification(text) {
+    const trimmed = text?.trim() ?? "";
+    return trimmed.length === 0 || trimmed.toUpperCase() === NOTHING_TO_REPORT_SENTINEL;
+}
+/** A conversationId a verbatim notification can be delivered to (a push channel with a notify hook). */
+function isDeliverableConversation(conversationId) {
+    return conversationId.startsWith("telegram:") || conversationId.startsWith("slack:");
+}
 export function createCronChannelDriver(overrides = {}) {
+    const failureNoticeLastSentMsByJobId = new Map();
     return {
         id: "cron",
         label: "Cron",
+        async configView(input) {
+            if (!(await isChannelConfigured(input, CRON_GATE))) {
+                return unconfiguredChannelView("cron", "Cron");
+            }
+            const adapter = await loadCronModule();
+            return await buildChannelConfigView(this, adapter.CRON_CONFIG_FIELDS, input);
+        },
+        configIssues(config) {
+            return findTriggerOverrideIssues(config.jobs
+                .filter((job) => job.enabled)
+                .map((job) => ({
+                name: `cron job "${job.id}"`,
+                ...(job.model === undefined ? {} : { model: job.model }),
+                ...(job.effort === undefined ? {} : { effort: job.effort }),
+            })));
+        },
         async loadConfig(input) {
-            return await loadCronAdapterConfig({ env: input.env, jsonPath: input.configPath, cwd: input.cwd });
+            if (!(await isChannelConfigured(input, CRON_GATE))) {
+                return UNCONFIGURED_CRON_CONFIG;
+            }
+            const adapter = await loadCronModule();
+            return await adapter.loadCronAdapterConfig({ env: input.env, jsonPath: input.configPath, cwd: input.cwd });
         },
         isConfigError(error) {
-            return error instanceof CronAdapterError;
+            return cronModule !== undefined && error instanceof cronModule.CronAdapterError;
         },
         disabledReason(config) {
             const enabledJobs = config.jobs.filter((job) => job.enabled);
@@ -219,25 +695,51 @@ export function createCronChannelDriver(overrides = {}) {
         },
         async start(input) {
             const jobs = input.config.jobs.filter((job) => job.enabled);
-            const adapterFactory = overrides.adapterFactory ?? startCronAdapter;
+            const jobById = new Map(jobs.map((job) => [job.id, job]));
+            const adapterModule = await loadCronModule();
+            const adapterFactory = overrides.adapterFactory ?? adapterModule.startCronAdapter;
             const adapter = adapterFactory({
                 responder: input.responder,
                 // Skip overlapping firings (a job still running when its next tick fires)
                 // — the legacy/default app behavior. This avoids the scheduler's
                 // unbounded "queue" default retaining stale ticks in memory when a job
                 // runs longer than its interval. (Queue/replace remain available to
-                // programmatic callers of startCronAdapter.)
+                // programmatic callers of startCronAdapter.) The watchdog below is what
+                // keeps "skip" safe: a hung run no longer pins the slot forever.
                 overlap: "skip",
+                // Reclaim a run whose responder never settles, so a single wedged run can't
+                // permanently skip every future firing of the job.
+                maxRunMs: overrides.maxRunMs ?? DEFAULT_CRON_MAX_RUN_MS,
                 jobs: jobs.map((job) => ({
                     id: job.id,
                     expression: job.expression,
                     timezone: job.timezone,
                     prompt: job.prompt,
                     ...(job.conversationId === undefined ? {} : { conversationId: job.conversationId }),
+                    ...(job.maxRunMs === undefined ? {} : { maxRunMs: job.maxRunMs }),
+                    ...(job.notify === undefined ? {} : { notify: job.notify }),
+                    ...(job.notifyConversationId === undefined ? {} : { notifyConversationId: job.notifyConversationId }),
+                    ...(job.model === undefined ? {} : { model: job.model }),
+                    ...(job.effort === undefined ? {} : { effort: job.effort }),
                 })),
                 onResult: (result) => {
                     const level = result.kind === "failed" ? "error" : result.kind === "skipped" ? "warn" : "info";
                     input.logger?.[level]?.("Cron job finished.", { result });
+                    void deliverCronModelExhaustionFailureNotice({
+                        job: jobById.get(result.jobId),
+                        result,
+                        cooldowns: failureNoticeLastSentMsByJobId,
+                        now: overrides.now ?? (() => new Date()),
+                        ...(input.notifyDestination === undefined ? {} : { notifyDestination: input.notifyDestination }),
+                        ...(input.logger === undefined ? {} : { logger: input.logger }),
+                    });
+                    void deliverNativeCronNotification({
+                        job: jobById.get(result.jobId),
+                        result,
+                        ...(input.notifyDestination === undefined ? {} : { notifyDestination: input.notifyDestination }),
+                        ...(input.listNotifyDestinations === undefined ? {} : { listNotifyDestinations: input.listNotifyDestinations }),
+                        ...(input.logger === undefined ? {} : { logger: input.logger }),
+                    });
                 },
                 ...(input.logger === undefined ? {} : { logger: input.logger }),
             });
@@ -250,57 +752,238 @@ export function createCronChannelDriver(overrides = {}) {
         },
     };
 }
-export function createWhatsAppChannelDriver(overrides = {}) {
-    return {
-        id: "whatsapp",
-        label: "WhatsApp",
-        async loadConfig(input) {
-            return await loadWhatsAppAdapterConfig({ env: input.env, jsonPath: input.configPath });
-        },
-        isConfigError(error) {
-            return error instanceof WhatsAppAdapterConfigError;
-        },
-        disabledReason(config) {
-            return config.enabled ? undefined : "WhatsApp is disabled.";
-        },
-        async start(input) {
-            const startAdapter = overrides.startAdapter ?? startWhatsAppAdapter;
-            const result = await startAdapter({
-                authDir: overrides.authDir ?? resolve(input.cwd, ".mono-agent", "whatsapp-auth"),
-                config: input.config,
-                responder: input.responder,
-                ...(input.logger === undefined ? {} : { logger: input.logger }),
-                onQr: (qr) => {
-                    input.logger?.info?.("WhatsApp login QR code received; scan it with the WhatsApp app.", { qr });
-                },
-                ...(overrides.socketFactory === undefined ? {} : { createSocket: overrides.socketFactory }),
+async function deliverCronModelExhaustionFailureNotice(input) {
+    const job = input.job;
+    if (job?.notify !== true ||
+        input.result.kind !== "failed" ||
+        input.result.failureKind !== "provider_unavailable_exhausted") {
+        return;
+    }
+    if (job.notifyConversationId === undefined) {
+        input.logger?.warn?.("Cron failure notice skipped: notifyConversationId is required.", { jobId: job.id });
+        return;
+    }
+    if (input.notifyDestination === undefined) {
+        input.logger?.warn?.("Cron failure notice skipped: no delivery hook is available.", { jobId: job.id });
+        return;
+    }
+    const nowMs = input.now().getTime();
+    const cooldownHours = job.notifyFailureCooldownHours ?? DEFAULT_CRON_FAILURE_NOTICE_COOLDOWN_HOURS;
+    const cooldownMs = cooldownHours * 60 * 60 * 1000;
+    const lastSentMs = input.cooldowns.get(job.id);
+    if (lastSentMs !== undefined && nowMs - lastSentMs < cooldownMs) {
+        input.logger?.info?.("Cron failure notice skipped: cooldown is active.", {
+            jobId: job.id,
+            cooldownHours,
+        });
+        return;
+    }
+    const destination = job.notifyConversationId;
+    const text = buildCronModelExhaustionFailureNotice(job, input.result);
+    input.cooldowns.set(job.id, nowMs);
+    try {
+        const delivery = await input.notifyDestination(destination, text, { verbatim: true });
+        if (!delivery.delivered) {
+            input.logger?.warn?.("Cron failure notice was not delivered.", {
+                jobId: job.id,
+                conversationId: destination,
+                ...(delivery.reason === undefined ? {} : { reason: delivery.reason }),
             });
-            return {
-                summary: {},
-                stop: () => result.stop(),
-            };
-        },
-    };
+            return;
+        }
+        input.logger?.info?.("Cron failure notice delivered.", { jobId: job.id, conversationId: destination });
+    }
+    catch (error) {
+        input.logger?.warn?.("Cron failure notice failed.", {
+            jobId: job.id,
+            conversationId: destination,
+            reason: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function buildCronModelExhaustionFailureNotice(job, result) {
+    const jobId = oneLine(job.id);
+    const latestError = truncateOneLine(result.error, MAX_CRON_FAILURE_NOTICE_ERROR_CHARS);
+    const prefix = `Cron job "${jobId}" failed: all configured models failed.`;
+    return latestError.length === 0 ? prefix : `${prefix} Latest error: ${latestError}`;
+}
+function truncateOneLine(value, maxChars) {
+    const collapsed = oneLine(value);
+    if (collapsed.length <= maxChars) {
+        return collapsed;
+    }
+    return `${collapsed.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+function oneLine(value) {
+    return value.replace(/\s+/gu, " ").trim();
+}
+async function deliverNativeCronNotification(input) {
+    const job = input.job;
+    if (job?.notify !== true || input.result.kind !== "succeeded") {
+        return;
+    }
+    const text = input.result.text;
+    // The agent stays silent by producing no final answer or the explicit sentinel.
+    if (text === undefined || suppressesNotification(text)) {
+        return;
+    }
+    try {
+        if (input.notifyDestination === undefined) {
+            input.logger?.warn?.("Native cron notification skipped: no delivery hook is available.", { jobId: job.id });
+            return;
+        }
+        const destination = await resolveNativeCronNotifyDestination({
+            job,
+            ...(input.listNotifyDestinations === undefined ? {} : { listNotifyDestinations: input.listNotifyDestinations }),
+            ...(input.logger === undefined ? {} : { logger: input.logger }),
+        });
+        if (destination === undefined) {
+            return;
+        }
+        const delivery = await input.notifyDestination(destination, text, { verbatim: true });
+        if (!delivery.delivered) {
+            input.logger?.warn?.("Native cron notification was not delivered.", {
+                jobId: job.id,
+                conversationId: destination,
+                ...(delivery.reason === undefined ? {} : { reason: delivery.reason }),
+            });
+        }
+    }
+    catch (error) {
+        input.logger?.warn?.("Native cron notification failed.", {
+            jobId: job.id,
+            reason: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+async function resolveNativeCronNotifyDestination(input) {
+    if (input.job.notifyConversationId !== undefined) {
+        return input.job.notifyConversationId;
+    }
+    if (input.listNotifyDestinations === undefined) {
+        input.logger?.warn?.("Native cron notification skipped: no destination is configured and no destination resolver is available.", {
+            jobId: input.job.id,
+        });
+        return undefined;
+    }
+    const destinations = await input.listNotifyDestinations();
+    if (destinations.length !== 1) {
+        input.logger?.warn?.("Native cron notification skipped: destination inference requires exactly one candidate.", {
+            jobId: input.job.id,
+            destinationCount: destinations.length,
+        });
+        return undefined;
+    }
+    return destinations[0]?.conversationId;
+}
+async function deliverNativeWebhookNotification(input) {
+    const endpoint = input.endpoint;
+    if (endpoint?.notify !== true || input.status.status !== "succeeded") {
+        return;
+    }
+    const text = input.status.text;
+    // The agent stays silent by producing no final answer or the explicit sentinel.
+    if (text === undefined || suppressesNotification(text)) {
+        return;
+    }
+    const source = { endpointName: input.request.metadata.webhook.endpointName };
+    try {
+        if (input.notifyDestination === undefined) {
+            input.logger?.warn?.("Native webhook notification skipped: no delivery hook is available.", source);
+            return;
+        }
+        const destination = await resolveNativeWebhookNotifyDestination({
+            endpoint,
+            source,
+            requestConversationId: input.request.conversationId,
+            ...(input.listNotifyDestinations === undefined ? {} : { listNotifyDestinations: input.listNotifyDestinations }),
+            ...(input.logger === undefined ? {} : { logger: input.logger }),
+        });
+        if (destination === undefined) {
+            return;
+        }
+        const delivery = await input.notifyDestination(destination, text, { verbatim: true });
+        if (!delivery.delivered) {
+            input.logger?.warn?.("Native webhook notification was not delivered.", {
+                ...source,
+                conversationId: destination,
+                ...(delivery.reason === undefined ? {} : { reason: delivery.reason }),
+            });
+        }
+    }
+    catch (error) {
+        input.logger?.warn?.("Native webhook notification failed.", {
+            ...source,
+            reason: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+async function resolveNativeWebhookNotifyDestination(input) {
+    if (input.endpoint.notifyConversationId !== undefined) {
+        return input.endpoint.notifyConversationId;
+    }
+    // Async-callback pattern: when the inbound payload names a deliverable chat
+    // (e.g. the service posts back the originating `telegram:`/`slack:` id), deliver
+    // the answer there. The owning channel's allowlist still bounds it.
+    if (input.requestConversationId !== undefined && isDeliverableConversation(input.requestConversationId)) {
+        return input.requestConversationId;
+    }
+    if (input.listNotifyDestinations === undefined) {
+        input.logger?.warn?.("Native webhook notification skipped: no destination is configured and no destination resolver is available.", input.source);
+        return undefined;
+    }
+    const destinations = await input.listNotifyDestinations();
+    if (destinations.length !== 1) {
+        input.logger?.warn?.("Native webhook notification skipped: destination inference requires exactly one candidate.", {
+            ...input.source,
+            destinationCount: destinations.length,
+        });
+        return undefined;
+    }
+    return destinations[0]?.conversationId;
 }
 /** Every channel the app can drive, in startup/status display order. */
 export function defaultChannelDrivers(overrides = {}) {
     return [
         createTelegramChannelDriver(overrides.telegram),
         createSlackChannelDriver(overrides.slack),
-        createA2AChannelDriver(overrides.a2a),
         createWebhookChannelDriver(overrides.webhook),
         createOpenAIApiChannelDriver(overrides.openaiApi),
         createCronChannelDriver(overrides.cron),
-        createWhatsAppChannelDriver(overrides.whatsapp),
+        createTuiChannelDriver(overrides.tui),
+        createLiveChannelDriver(overrides.live),
     ];
 }
+export async function resolveChannelDrivers(input, overrides = {}) {
+    const drivers = [...defaultChannelDrivers(overrides)];
+    const plugins = await resolveConfiguredChannelPlugins(input, { reservedIds: BUILTIN_CHANNEL_IDS });
+    for (const plugin of plugins) {
+        const existing = drivers.findIndex((driver) => driver.id === plugin.id);
+        if (existing >= 0) {
+            drivers[existing] = plugin;
+        }
+        else {
+            drivers.push(plugin);
+        }
+    }
+    return drivers;
+}
 function telegramStartOptions(input, overrides) {
+    // Subscribe to (and handle) inline-keyboard taps only when the `telegram_ask`
+    // tool is permitted by the tool policy — so enabling the tool is the single
+    // switch that turns on the whole ask/answer round-trip. Without it the bot
+    // stays message-only and never registers the callback handler.
+    const callbacksEnabled = isAdapterSendToolAllowed("telegram_ask", {
+        allowedTools: input.coreConfig.tools.allowedTools,
+        disallowedTools: input.coreConfig.tools.disallowedTools,
+    });
     return {
         botToken: input.config.botToken,
         allowedChatIds: [...input.config.allowedChatIds],
         allowAllChats: input.config.allowAllChats,
         responder: input.responder,
-        allowedUpdates: ["message"],
+        allowedUpdates: callbacksEnabled ? ["message", "callback_query"] : ["message"],
+        ...(callbacksEnabled ? { callbacksEnabled: true } : {}),
         deleteWebhookOnStart: true,
         stream: {
             initialStatusText: "Agent is thinking...",
@@ -316,9 +999,30 @@ function telegramStartOptions(input, overrides) {
             unauthorizedText: "This chat is not allowlisted for this agent.",
             errorText: telegramErrorText,
         },
-        // A polling crash after a successful start must flip the channel to failed,
-        // not leave it reported as running.
-        onPollingError: (error) => input.onFailure(error instanceof Error ? error.message : String(error)),
+        // A polling crash is recoverable by construction: the adapter always schedules
+        // a backoff restart (it never gives up on its own), so report it as DEGRADED
+        // (keep the responder/harness alive) rather than fatal. onPollingRecovered flips
+        // the channel back to running once a restarted runner stays up.
+        onPollingError: (error) => input.onDegraded?.(error instanceof Error ? error.message : String(error)),
+        onPollingRecovered: () => input.onRecovered?.(),
+        ...(input.config.apiRoot === undefined ? {} : { apiRoot: input.config.apiRoot }),
+        ...(telegramAttachmentOptions(input.config) === undefined
+            ? {}
+            : { attachments: telegramAttachmentOptions(input.config) }),
+        ...(input.interaction === undefined
+            ? {}
+            : {
+                pendingAsks: {
+                    tryResolve: (conversationId, answer) => input.interaction.tryResolveAsk(conversationId, answer),
+                    cancel: (conversationId) => {
+                        input.interaction.cancelAsks(conversationId);
+                    },
+                },
+            }),
+        ...(input.config.ipFamily === undefined ? {} : { transport: { ipFamily: input.config.ipFamily } }),
+        ...(input.config.pollWatchdogMs === undefined ? {} : { pollWatchdogMs: input.config.pollWatchdogMs }),
+        ...(input.config.commands === undefined ? {} : { commands: [...input.config.commands] }),
+        ...(input.config.reactions === undefined ? {} : { reactions: input.config.reactions }),
         ...(input.logger === undefined ? {} : { logger: input.logger }),
         ...(overrides.botFactory === undefined ? {} : { botFactory: overrides.botFactory }),
         ...(overrides.runnerFactory === undefined ? {} : { runnerFactory: overrides.runnerFactory }),
@@ -326,21 +1030,24 @@ function telegramStartOptions(input, overrides) {
 }
 function telegramErrorText(input) {
     const failure = failureFromUnknown(input.error);
-    if (failure?.kind === "usage_limit") {
-        const maxTurns = nestedNumber(failure.details, ["diagnostics", "max_turns"]);
-        return [
-            `I hit the runtime turn limit${maxTurns === undefined ? "" : ` (${maxTurns} turns)`} before I could finish.`,
-            "Send a narrower follow-up, or check the local artifact summary for the incomplete run.",
-        ].join(" ");
-    }
-    if (failure?.kind === "cancelled") {
-        return "Cancelled.";
+    if (failure?.kind !== undefined) {
+        const description = describeRunFailureKind({ failureKind: failure.kind });
+        if (description.known || failure.message === undefined || failure.message.trim().length === 0) {
+            const explanation = failure.kind === "usage_limit"
+                ? usageLimitExplanation(description.explanation, failure.details)
+                : description.explanation;
+            return `${explanation} ${description.nextStep}`;
+        }
     }
     if (failure?.message !== undefined && failure.message.trim().length > 0) {
         return `I could not complete that message: ${failure.message}`;
     }
     return "I could not complete that message. Check the local artifact summary for details.";
 }
+function usageLimitExplanation(explanation, details) {
+    const maxTurns = nestedNumber(details, ["diagnostics", "max_turns"]);
+    return maxTurns === undefined ? explanation : `${explanation} Configured turn cap: ${maxTurns} turns.`;
+}
 function failureFromUnknown(error) {
     if (!isRecord(error)) {
         return undefined;