@odience-network/paperclip-plugin-telegram-enhanced 0.2.0

package/dist/worker.js

@@ -0,0 +1,1520 @@
+import { definePlugin, runWorker, } from "@paperclipai/plugin-sdk";
+import { sendMessage, sendDocument, editMessage, answerCallbackQuery, setMyCommands, escapeMarkdownV2, isForum, GENERAL_TOPIC_THREAD_ID, } from "./telegram-api.js";
+import { resolveTelegramFileDestination, getTelegramFileRouteSaveErrors, } from "./file-routing.js";
+import { formatIssueCreated, formatIssueDone, formatIssueAssigned, formatApprovalCreated, formatAgentError, formatAgentRunStarted, formatAgentRunFinished, formatIssueBlocked, formatBoardMention, formatResolvedDecision, } from "./formatters.js";
+import { handleCommand, resolveNotificationThreadId, BOT_COMMANDS } from "./commands.js";
+import { routeMessageToAgent, handleHandoffToolCall, handleDiscussToolCall, handleHandoffApproval, handleHandoffRejection, setupAcpOutputListener, } from "./acp-bridge.js";
+import { handleMediaMessage } from "./media-pipeline.js";
+import { getPersistedTelegramUpdateOffset, persistTelegramUpdateOffset, processTelegramUpdateBatch, } from "./polling-offset.js";
+import { handleCommandsCommand, tryCustomCommand } from "./command-registry.js";
+import { handleRegisterWatch, checkWatches } from "./watch-registry.js";
+import { AGENT_ERROR_DEDUPLICATION_WINDOW_MS, METRIC_NAMES } from "./constants.js";
+import { EscalationManager } from "./escalation.js";
+import { isTelegramUpdateAllowed, validateTelegramAllowlists } from "./allowlist.js";
+import { validateSecretRefFields } from "./secret-ref-validation.js";
+import { shouldNotifyApproval } from "./approval-routing.js";
+import { buildDeliveryKey, withIdempotentDelivery } from "./interaction-delivery.js";
+import { shouldNotifyIssueBlocked, shouldNotifyBoardMention, parseBoardUsernames, } from "./notification-filters.js";
+import { buildPaperclipAuthHeaders, fetchPaperclipApi, isAlreadyResolvedConflict, } from "./paperclip-api.js";
+const TELEGRAM_API = "https://api.telegram.org";
+const BOARD_ACCESS_SCOPE = {
+    scopeKind: "instance",
+    stateKey: "telegram.board-access.v1",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function normalizeBoardAccessState(value) {
+    const record = isRecord(value) ? value : {};
+    return {
+        paperclipBoardApiTokenRef: asNonEmptyString(record.paperclipBoardApiTokenRef),
+        identity: asNonEmptyString(record.identity),
+        companyId: asNonEmptyString(record.companyId),
+        updatedAt: asNonEmptyString(record.updatedAt),
+    };
+}
+async function loadBoardAccessState(ctx) {
+    return normalizeBoardAccessState(await ctx.state.get(BOARD_ACCESS_SCOPE));
+}
+async function persistBoardAccessState(ctx, state) {
+    const nextState = normalizeBoardAccessState(state);
+    await ctx.state.set(BOARD_ACCESS_SCOPE, nextState);
+    return {
+        ...nextState,
+        configured: Boolean(nextState.paperclipBoardApiTokenRef),
+    };
+}
+function getBoardAccessRegistration(state) {
+    return {
+        ...state,
+        configured: Boolean(state.paperclipBoardApiTokenRef),
+    };
+}
+async function resolveBoardApiToken(ctx, config, companyId) {
+    const boardAccessState = await loadBoardAccessState(ctx);
+    const candidates = [];
+    if (boardAccessState.paperclipBoardApiTokenRef &&
+        (!companyId || !boardAccessState.companyId || boardAccessState.companyId === companyId)) {
+        candidates.push({
+            source: "board-access",
+            ref: boardAccessState.paperclipBoardApiTokenRef,
+        });
+    }
+    if (config.paperclipBoardApiTokenRef) {
+        candidates.push({
+            source: "config",
+            ref: config.paperclipBoardApiTokenRef,
+        });
+    }
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (seen.has(candidate.ref))
+            continue;
+        seen.add(candidate.ref);
+        try {
+            return await ctx.secrets.resolve(candidate.ref);
+        }
+        catch (err) {
+            ctx.logger.warn("Failed to resolve board API token secret", {
+                source: candidate.source,
+                companyId,
+                error: String(err),
+            });
+        }
+    }
+    return undefined;
+}
+async function resolveCallbackCompanyId(ctx, query) {
+    const chatId = query.message?.chat.id ? String(query.message.chat.id) : null;
+    const messageId = query.message?.message_id;
+    if (!chatId || !messageId)
+        return null;
+    const mapping = await ctx.state.get({
+        scopeKind: "instance",
+        stateKey: `msg_${chatId}_${messageId}`,
+    });
+    return mapping?.companyId ?? null;
+}
+/**
+ * Shared 5s sliding-window dedupe for issue.updated handlers.
+ *
+ * Paperclip's core can emit duplicate `issue.updated` plugin events for a
+ * single PATCH (the route's logActivity plus side-effects from heartbeat
+ * reconciliation), so handlers must dedupe to avoid sending the same
+ * Telegram message twice.
+ */
+function makeUpdateDedupe(windowMs = 5_000, maxEntries = 500) {
+    const seen = new Map();
+    return (key) => {
+        const now = Date.now();
+        const last = seen.get(key);
+        if (last !== undefined && now - last < windowMs)
+            return false;
+        seen.set(key, now);
+        if (seen.size > maxEntries) {
+            const cutoff = now - windowMs;
+            for (const [k, ts] of seen) {
+                if (ts < cutoff)
+                    seen.delete(k);
+            }
+        }
+        return true;
+    };
+}
+function normalizeAgentErrorMessage(input) {
+    return String(input ?? "Unknown error")
+        .trim()
+        .replace(/\s+/g, " ")
+        .slice(0, 500);
+}
+async function resolveChat(ctx, companyId, fallback) {
+    const override = await ctx.state.get({
+        scopeKind: "company",
+        scopeId: companyId,
+        stateKey: "telegram-chat",
+    });
+    return override ?? fallback ?? null;
+}
+function parseTopicId(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    return Number(trimmed);
+}
+function validateConfiguredTopicIds(config) {
+    const errors = [];
+    for (const key of ["approvalsTopicId", "errorsTopicId", "digestTopicId"]) {
+        const value = config[key];
+        if (value === undefined || value === null || value === "")
+            continue;
+        if (typeof value !== "string" || !parseTopicId(value)) {
+            errors.push(`${key} must be a numeric Telegram forum topic ID string.`);
+        }
+    }
+    return errors;
+}
+async function resolveDigestThreadId(ctx, token, chatId, configuredTopicId) {
+    const configured = parseTopicId(configuredTopicId);
+    if (configured)
+        return configured;
+    return await isForum(ctx, token, chatId) ? GENERAL_TOPIC_THREAD_ID : undefined;
+}
+async function resolveCompanyId(ctx, chatId) {
+    const mapping = await ctx.state.get({
+        scopeKind: "instance",
+        stateKey: `chat_${chatId}`,
+    });
+    return mapping?.companyId ?? mapping?.companyName ?? chatId;
+}
+// --- Agent file-send action (ant013 TEL-8 / TEL-23) ---
+// Ported from ant013/paperclip-plugin-telegram: agent-callable "send to
+// Telegram" action with native markdown upload plus project-key file routing.
+const MAX_OUTBOUND_MARKDOWN_BYTES = 256 * 1024;
+const MAX_MARKDOWN_CAPTION_BYTES = 1024;
+const DEFAULT_MARKDOWN_FILENAME = "paperclip-message.md";
+const SECRET_FILENAME_TOKENS = /(?:^|[^0-9A-Za-z])(?:secret|token|credential|password|private\-key)(?:$|[^0-9A-Za-z])/i;
+const UNSAFE_FILENAME_CHARS = /[\\/\u0000-\u001F\u007F]/;
+const FORBIDDEN_MARKDOWN_SOURCE_FIELDS = new Set([
+    "filePath",
+    "path",
+    "fileUrl",
+    "url",
+    "fileURL",
+    "fileUri",
+    "file_uri",
+    "uri",
+    "telegramFileId",
+    "telegram_file_id",
+    "file_id",
+    "file",
+    "files",
+    "binary",
+    "binaryContent",
+    "fileContent",
+    "content",
+]);
+function validateOutboundThreadId(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 1)
+        return "invalid";
+    return value;
+}
+function validateMarkdownFilename(name) {
+    if (!name.toLowerCase().endsWith(".md")) {
+        return { ok: false, code: "non_markdown_file", message: "Markdown file uploads must use a .md extension." };
+    }
+    if (/^[A-Za-z]:/.test(name)) {
+        return { ok: false, code: "invalid_markdown_filename", message: "Markdown filename must be a safe basename." };
+    }
+    if (name.includes("/") || name.includes("\\") || name.includes("..")) {
+        return { ok: false, code: "invalid_markdown_filename", message: "Markdown filename must be a safe basename." };
+    }
+    if (UNSAFE_FILENAME_CHARS.test(name) || name.startsWith(".") || SECRET_FILENAME_TOKENS.test(name)) {
+        return { ok: false, code: "unsafe_filename", message: "Markdown filename is considered unsafe." };
+    }
+    return { ok: true };
+}
+function findUnsupportedMarkdownSourceField(params) {
+    for (const key of FORBIDDEN_MARKDOWN_SOURCE_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(params, key) && params[key] !== undefined) {
+            return key;
+        }
+    }
+    return null;
+}
+function makeTelegramToolError(code, message, metadata = {}) {
+    return { ok: false, code, message, ...metadata };
+}
+async function resolveIssueIdentifierForFileRoute(ctx, companyId, issueId) {
+    try {
+        const issue = await ctx.issues.get(issueId, companyId);
+        if (!issue)
+            return null;
+        const issueCompanyId = issue.companyId;
+        if (typeof issueCompanyId === "string" && issueCompanyId !== companyId)
+            return null;
+        return typeof issue.identifier === "string" ? issue.identifier : null;
+    }
+    catch {
+        return null;
+    }
+}
+// A route counts as enabled unless it is explicitly disabled (enabled === false).
+// Legacy/hand-edited config that omits the flag is treated as enabled.
+function routeEnabled(value) {
+    return value !== false;
+}
+export function resolveTelegramOpsDestination(routes, companyId, companyName) {
+    if (!Array.isArray(routes))
+        return null;
+    const normalizedCompanyName = asNonEmptyString(companyName)?.toLowerCase() ?? null;
+    for (const route of routes) {
+        if (!isRecord(route) || !routeEnabled(route.enabled))
+            continue;
+        const chatId = asNonEmptyString(route.chatId);
+        if (!chatId)
+            continue;
+        const routeCompanyId = asNonEmptyString(route.companyId);
+        const routeCompanyName = asNonEmptyString(route.companyName)?.toLowerCase() ?? null;
+        const matchesCompanyId = Boolean(routeCompanyId && routeCompanyId === companyId);
+        const matchesCompanyName = Boolean(routeCompanyName && normalizedCompanyName && routeCompanyName === normalizedCompanyName);
+        if (!matchesCompanyId && !matchesCompanyName)
+            continue;
+        return {
+            chatId,
+            topicId: asNonEmptyString(route.topicId) ?? undefined,
+            routeName: asNonEmptyString(route.name) ?? undefined,
+        };
+    }
+    return null;
+}
+export async function resolveOpsDestinationForEvent(ctx, config, event) {
+    // First try the cheap path: direct companyId match needs no extra lookup.
+    const direct = resolveTelegramOpsDestination(config.opsRoutes, event.companyId);
+    if (direct)
+        return direct;
+    // Fall back to companyName matching (routes configured by name), resolving the
+    // company lazily so we never pay the lookup when no name-based route exists.
+    if (!Array.isArray(config.opsRoutes) || config.opsRoutes.length === 0)
+        return null;
+    try {
+        const company = await ctx.companies.get(event.companyId);
+        return resolveTelegramOpsDestination(config.opsRoutes, event.companyId, company?.name ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+async function logSendToTelegramAttempt(ctx, runCtx, details) {
+    ctx.logger.info("Telegram agent send routing decision", {
+        companyId: runCtx.companyId,
+        agentId: runCtx.agentId,
+        issueId: asNonEmptyString(details.params.issueId) ?? undefined,
+        issueIdentifier: details.issueIdentifier ?? asNonEmptyString(details.params.issueIdentifier) ?? undefined,
+        projectKey: details.projectKey ?? asNonEmptyString(details.params.projectKey) ?? undefined,
+        routeSource: details.routeSource,
+        routeName: details.routeName,
+        chatId: details.chatId,
+        topicId: details.threadId,
+        contentMode: details.mode,
+        errorCode: details.errorCode,
+    });
+}
+export async function sendToTelegramTool(ctx, token, config, params, runCtx) {
+    const p = isRecord(params) ? params : {};
+    if (findUnsupportedMarkdownSourceField(p)) {
+        const result = makeTelegramToolError("unsupported_file_source", "Only text and markdownContent are supported.");
+        return { content: JSON.stringify(result), data: result };
+    }
+    const text = asNonEmptyString(p.text);
+    const markdownContent = asNonEmptyString(p.markdownContent);
+    if (!text && !markdownContent) {
+        const result = makeTelegramToolError("missing_content", "At least one of text or markdownContent is required.");
+        return { content: JSON.stringify(result), data: result };
+    }
+    const explicitChatId = asNonEmptyString(p.chatId);
+    const threadId = validateOutboundThreadId(p.threadId);
+    if (threadId === "invalid") {
+        const result = makeTelegramToolError("invalid_thread", "threadId must be a positive integer.");
+        return { content: JSON.stringify(result), data: result };
+    }
+    const replyToMessageId = validateOutboundThreadId(p.replyToMessageId);
+    if (replyToMessageId === "invalid") {
+        const result = makeTelegramToolError("invalid_thread", "replyToMessageId must be a positive integer.");
+        return { content: JSON.stringify(result), data: result };
+    }
+    const parseMode = p.parseMode === "MarkdownV2" || p.parseMode === "HTML" ? p.parseMode : undefined;
+    const requestedMarkdownFileName = asNonEmptyString(p.markdownFileName) ?? DEFAULT_MARKDOWN_FILENAME;
+    const sessionId = asNonEmptyString(p.sessionId);
+    if (markdownContent && Buffer.byteLength(markdownContent, "utf-8") > MAX_OUTBOUND_MARKDOWN_BYTES) {
+        const result = makeTelegramToolError("markdown_too_large", "Markdown content exceeds size limits.");
+        return { content: JSON.stringify(result), data: result };
+    }
+    if (markdownContent && text && Buffer.byteLength(text, "utf-8") > MAX_MARKDOWN_CAPTION_BYTES) {
+        const result = makeTelegramToolError("caption_too_large", "Caption exceeds Telegram caption size limits.");
+        return { content: JSON.stringify(result), data: result };
+    }
+    if (markdownContent) {
+        const markdownFileValidation = validateMarkdownFilename(requestedMarkdownFileName);
+        if (!markdownFileValidation.ok) {
+            const result = makeTelegramToolError(markdownFileValidation.code, markdownFileValidation.message);
+            return { content: JSON.stringify(result), data: result };
+        }
+    }
+    const destination = markdownContent
+        ? await resolveTelegramFileDestination(config.fileRoutes, {
+            explicitChatId,
+            explicitThreadId: typeof threadId === "number" ? threadId : undefined,
+            issueId: asNonEmptyString(p.issueId),
+            issueIdentifier: asNonEmptyString(p.issueIdentifier),
+            projectKey: asNonEmptyString(p.projectKey),
+            lookupIssueIdentifier: (issueId) => resolveIssueIdentifierForFileRoute(ctx, runCtx.companyId, issueId),
+        })
+        : null;
+    if (destination && !destination.ok) {
+        const result = makeTelegramToolError(destination.code, destination.message, {
+            projectKey: destination.projectKey,
+            issueIdentifier: destination.issueIdentifier,
+        });
+        await logSendToTelegramAttempt(ctx, runCtx, {
+            params: p,
+            mode: markdownContent ? "document" : "message",
+            routeSource: "file_route",
+            projectKey: destination.projectKey,
+            issueIdentifier: destination.issueIdentifier,
+            errorCode: destination.code,
+        });
+        return { content: JSON.stringify(result), data: result };
+    }
+    const routeSource = destination?.ok ? destination.source : explicitChatId ? "explicit" : "legacy_fallback";
+    const chatId = destination?.ok && destination.source === "file_route"
+        ? destination.chatId
+        : explicitChatId ?? await resolveChat(ctx, runCtx.companyId, config.defaultChatId);
+    if (!chatId) {
+        const result = makeTelegramToolError("disallowed_chat", "No Telegram chat configured.");
+        return { content: JSON.stringify(result), data: result };
+    }
+    const allowedChatIds = Array.isArray(config.allowedTelegramChatIds)
+        ? config.allowedTelegramChatIds.map(String).filter(Boolean)
+        : [];
+    if (explicitChatId) {
+        if (allowedChatIds.length === 0) {
+            const result = makeTelegramToolError("disallowed_chat", "Explicit Telegram chat IDs are not allowed.");
+            return { content: JSON.stringify(result), data: result };
+        }
+        if (!allowedChatIds.includes(explicitChatId)) {
+            const result = makeTelegramToolError("disallowed_chat", "Telegram chat is not allowed for agent outbound delivery.");
+            return { content: JSON.stringify(result), data: result };
+        }
+    }
+    const outboundThreadId = destination?.ok && destination.source === "file_route"
+        ? destination.topicId
+        : threadId;
+    const result = markdownContent
+        ? await sendDocument(ctx, token, chatId, markdownContent, {
+            filename: requestedMarkdownFileName,
+            caption: text ?? undefined,
+            parseMode,
+            messageThreadId: outboundThreadId,
+            replyToMessageId: typeof replyToMessageId === "number" ? replyToMessageId : undefined,
+            disableNotification: p.silent === true,
+        }).then((messageId) => {
+            if (!messageId) {
+                return makeTelegramToolError("telegram_send_failed", "Telegram send failed.");
+            }
+            return {
+                ok: true,
+                mode: "document",
+                chatId,
+                threadId: outboundThreadId,
+                messageId,
+                routeSource,
+                routeName: destination?.ok ? destination.routeName : undefined,
+                projectKey: destination?.ok ? destination.projectKey : undefined,
+                issueIdentifier: destination?.ok ? destination.issueIdentifier : undefined,
+            };
+        })
+        : await sendMessage(ctx, token, chatId, text, {
+            parseMode,
+            messageThreadId: outboundThreadId,
+            replyToMessageId: typeof replyToMessageId === "number" ? replyToMessageId : undefined,
+            disableNotification: p.silent === true,
+        }).then((messageId) => {
+            if (!messageId) {
+                return makeTelegramToolError("telegram_send_failed", "Telegram send failed.");
+            }
+            return {
+                ok: true,
+                mode: "message",
+                chatId,
+                threadId: outboundThreadId,
+                messageId,
+                routeSource,
+            };
+        });
+    if (!result.ok) {
+        await logSendToTelegramAttempt(ctx, runCtx, {
+            params: p,
+            mode: markdownContent ? "document" : "message",
+            chatId,
+            threadId: outboundThreadId,
+            routeSource,
+            routeName: destination?.ok ? destination.routeName : undefined,
+            projectKey: destination?.ok ? destination.projectKey : undefined,
+            issueIdentifier: destination?.ok ? destination.issueIdentifier : undefined,
+            errorCode: result.code,
+        });
+        return { content: JSON.stringify(result), data: result };
+    }
+    if (sessionId) {
+        await ctx.state.set({ scopeKind: "instance", stateKey: `agent_msg_${chatId}_${result.messageId}` }, { sessionId });
+    }
+    await ctx.activity.log({
+        companyId: runCtx.companyId,
+        message: "Agent sent content to Telegram",
+        entityType: "agent",
+        entityId: runCtx.agentId,
+        metadata: {
+            chatId,
+            threadId: outboundThreadId,
+            mode: result.mode,
+            messageId: result.messageId,
+            routeSource: result.routeSource,
+            routeName: destination?.ok ? destination.routeName : undefined,
+            projectKey: destination?.ok ? destination.projectKey : undefined,
+            issueId: asNonEmptyString(p.issueId) ?? undefined,
+            issueIdentifier: destination?.ok ? destination.issueIdentifier : asNonEmptyString(p.issueIdentifier) ?? undefined,
+        },
+    });
+    return { content: JSON.stringify(result), data: result };
+}
+const plugin = definePlugin({
+    async setup(ctx) {
+        const rawConfig = await ctx.config.get();
+        ctx.logger.info("Telegram plugin config loaded");
+        const config = rawConfig;
+        const baseUrl = config.paperclipBaseUrl || "http://localhost:3100";
+        const publicUrl = config.paperclipPublicUrl || baseUrl;
+        ctx.data.register("board-access.read", async () => getBoardAccessRegistration(await loadBoardAccessState(ctx)));
+        ctx.actions.register("board-access.update", async (params) => {
+            const record = isRecord(params) ? params : {};
+            const paperclipBoardApiTokenRef = asNonEmptyString(record.paperclipBoardApiTokenRef);
+            const identity = asNonEmptyString(record.identity);
+            const companyId = asNonEmptyString(record.companyId);
+            const now = new Date().toISOString();
+            return persistBoardAccessState(ctx, {
+                paperclipBoardApiTokenRef,
+                identity,
+                companyId,
+                updatedAt: now,
+            });
+        });
+        if (!config.telegramBotTokenRef) {
+            ctx.logger.warn("No telegramBotTokenRef configured, plugin disabled");
+            return;
+        }
+        const token = await ctx.secrets.resolve(config.telegramBotTokenRef);
+        // --- Agent file-send action (ant013 TEL-8 / TEL-23) ---
+        // Expose the send tool as a directly-invokable action so non-tool callers
+        // (smoke checks, other plugins) can route text/markdown to Telegram.
+        const runActionContext = (params) => ({
+            companyId: asNonEmptyString(params.companyId) ?? "system",
+            agentId: asNonEmptyString(params.agentId) ?? "system",
+        });
+        const invokeSendToTelegramAction = async (params) => {
+            const runCtx = runActionContext(params);
+            const result = await sendToTelegramTool(ctx, token, config, params, runCtx);
+            return { content: result.content, data: result.data };
+        };
+        ctx.actions.register("send_to_telegram", (params) => invokeSendToTelegramAction(params));
+        ctx.actions.register("send_file_to_telegram", (params) => invokeSendToTelegramAction(params));
+        // --- Register bot commands with Telegram ---
+        if (config.enableCommands) {
+            const allCommands = [
+                ...BOT_COMMANDS,
+                { command: "commands", description: "Manage custom workflow commands" },
+            ];
+            // Non-blocking init: don't hold up worker initialize on external API.
+            // The host's worker-init RPC timeout is 15s; if api.telegram.org is
+            // slow/unreachable, awaiting this call causes the worker to be SIGKILLed
+            // before setup() completes. Fire-and-forget matches pollUpdates() below.
+            setMyCommands(ctx, token, allCommands)
+                .then((registered) => {
+                if (registered) {
+                    ctx.logger.info("Bot commands registered with Telegram");
+                }
+            })
+                .catch((err) => {
+                ctx.logger.error("Failed to register bot commands", {
+                    error: String(err),
+                });
+            });
+        }
+        // --- Long polling for inbound messages ---
+        let pollingActive = true;
+        let lastUpdateId = await getPersistedTelegramUpdateOffset(ctx);
+        async function pollUpdates() {
+            while (pollingActive) {
+                try {
+                    const res = await ctx.http.fetch(`${TELEGRAM_API}/bot${token}/getUpdates?offset=${lastUpdateId + 1}&timeout=10&allowed_updates=["message","callback_query"]`, { method: "GET" });
+                    const data = (await res.json());
+                    if (data.ok && data.result) {
+                        lastUpdateId = await processTelegramUpdateBatch({
+                            updates: data.result,
+                            lastUpdateId,
+                            handleUpdate: (update) => handleUpdate(ctx, token, config, update, baseUrl, publicUrl),
+                            persistOffset: (updateId) => persistTelegramUpdateOffset(ctx, updateId),
+                            logger: ctx.logger,
+                        });
+                    }
+                }
+                catch (err) {
+                    ctx.logger.error("Telegram polling error", { error: String(err) });
+                    await new Promise((r) => setTimeout(r, 5000));
+                }
+            }
+        }
+        if (config.enableCommands || config.enableInbound) {
+            pollUpdates().catch((err) => ctx.logger.error("Polling loop crashed", { error: String(err) }));
+        }
+        ctx.events.on("plugin.stopping", async () => {
+            pollingActive = false;
+        });
+        // --- Phase 2: ACP output listener (cross-plugin events) ---
+        setupAcpOutputListener(ctx, token);
+        // --- Event subscriptions ---
+        const issuePrefixCache = new Map();
+        async function resolveIssueLinksOpts(companyId) {
+            let prefix = issuePrefixCache.get(companyId);
+            if (!prefix) {
+                const company = await ctx.companies.get(companyId);
+                prefix = company?.issuePrefix ?? "";
+                if (prefix)
+                    issuePrefixCache.set(companyId, prefix);
+            }
+            return { baseUrl: publicUrl, issuePrefix: prefix || undefined };
+        }
+        const notify = async (event, formatter, overrideChatId, overrideTopicId, deliveryKey) => {
+            const chatId = await resolveChat(ctx, event.companyId, overrideChatId || config.defaultChatId);
+            if (!chatId)
+                return;
+            const linksOpts = await resolveIssueLinksOpts(event.companyId);
+            const msg = formatter(event, linksOpts);
+            let messageThreadId = parseTopicId(overrideTopicId);
+            if (!messageThreadId) {
+                messageThreadId = await resolveNotificationThreadId(ctx, chatId, event, config.topicRouting);
+            }
+            if (messageThreadId) {
+                msg.options.messageThreadId = messageThreadId;
+            }
+            // Issue threading — if we've already sent a message for this entity in this
+            // chat+topic, reply to that anchor so all updates about a single entity stack
+            // as one Telegram thread on mobile (created → comments → done).
+            const anchorKey = event.entityId
+                ? `anchor_${chatId}_${event.entityType}_${event.entityId}`
+                : null;
+            if (anchorKey) {
+                const anchor = (await ctx.state.get({
+                    scopeKind: "instance",
+                    stateKey: anchorKey,
+                }));
+                // Only thread when targeting the same topic — Telegram rejects cross-topic replies.
+                if (anchor?.messageId && anchor.messageThreadId === messageThreadId) {
+                    msg.options.replyToMessageId = anchor.messageId;
+                }
+            }
+            // Durable idempotency guard: claim a delivery slot before sending so a
+            // duplicate event re-emission or a retried worker run cannot send the
+            // same notification twice. A failed send releases the claim so a later
+            // retry can re-attempt. Keyed by chat+topic+logical-event so the same
+            // entity notified in different chats/topics is not falsely suppressed.
+            const effectiveDeliveryKey = buildDeliveryKey(chatId, messageThreadId ?? "", deliveryKey ?? `${event.eventType}:${event.entityId ?? event.eventId}`);
+            const messageId = await withIdempotentDelivery(ctx, effectiveDeliveryKey, () => sendMessage(ctx, token, chatId, msg.text, msg.options));
+            if (messageId) {
+                await ctx.state.set({
+                    scopeKind: "instance",
+                    stateKey: `msg_${chatId}_${messageId}`,
+                }, {
+                    entityId: event.entityId,
+                    entityType: event.entityType,
+                    companyId: event.companyId,
+                    eventType: event.eventType,
+                });
+                await ctx.activity.log({
+                    companyId: event.companyId,
+                    message: `Forwarded ${event.eventType} to Telegram`,
+                    entityType: "plugin",
+                    entityId: event.entityId,
+                });
+                // First-message-per-entity: store the anchor so future notifications about the
+                // same entity reply to this one. Never overwritten — the first message stays root.
+                if (anchorKey) {
+                    const existing = (await ctx.state.get({
+                        scopeKind: "instance",
+                        stateKey: anchorKey,
+                    }));
+                    if (!existing) {
+                        await ctx.state.set({ scopeKind: "instance", stateKey: anchorKey }, { messageId, messageThreadId });
+                    }
+                }
+            }
+        };
+        if (config.notifyOnIssueCreated) {
+            ctx.events.on("issue.created", (event) => notify(event, formatIssueCreated));
+        }
+        if (config.notifyOnIssueDone) {
+            const doneDedupe = makeUpdateDedupe();
+            ctx.events.on("issue.updated", async (event) => {
+                const payload = event.payload;
+                if (payload.status !== "done")
+                    return;
+                if (!doneDedupe(`done|${event.entityId}`))
+                    return;
+                // Enrich with title if missing (issue.updated events often omit it)
+                if (!payload.title && event.entityId) {
+                    try {
+                        const issue = await ctx.issues.get(event.entityId, event.companyId);
+                        if (issue)
+                            payload.title = issue.title;
+                    }
+                    catch { /* best effort */ }
+                }
+                // Enrich with latest comment (completion summary)
+                if (!payload.comment && event.entityId) {
+                    try {
+                        const comments = await ctx.issues.listComments(event.entityId, event.companyId);
+                        if (comments.length > 0) {
+                            const latest = comments.reduce((a, b) => new Date(a.createdAt) > new Date(b.createdAt) ? a : b);
+                            payload.comment = latest.body;
+                        }
+                    }
+                    catch { /* best effort */ }
+                }
+                await notify(event, formatIssueDone, undefined, undefined, `done|${event.entityId}`);
+            });
+        }
+        if (config.notifyOnIssueAssigned) {
+            const assignmentDedupe = makeUpdateDedupe();
+            ctx.events.on("issue.updated", async (event) => {
+                const payload = event.payload;
+                const prev = payload._previous ?? {};
+                const userChanged = "assigneeUserId" in payload && payload.assigneeUserId !== prev.assigneeUserId;
+                const agentChanged = "assigneeAgentId" in payload && payload.assigneeAgentId !== prev.assigneeAgentId;
+                if (!userChanged && !agentChanged)
+                    return;
+                if (config.onlyNotifyIfAssignedTo && payload.assigneeUserId !== config.onlyNotifyIfAssignedTo) {
+                    return;
+                }
+                const dedupeKey = [
+                    "assigned",
+                    event.entityId,
+                    String(prev.assigneeUserId ?? ""),
+                    String(payload.assigneeUserId ?? ""),
+                    String(prev.assigneeAgentId ?? ""),
+                    String(payload.assigneeAgentId ?? ""),
+                ].join("|");
+                if (!assignmentDedupe(dedupeKey))
+                    return;
+                if ((!payload.title || !payload.assigneeName) && event.entityId) {
+                    try {
+                        const issue = await ctx.issues.get(event.entityId, event.companyId);
+                        if (issue) {
+                            payload.title ??= issue.title;
+                            const name = issue.assigneeName;
+                            if (name)
+                                payload.assigneeName ??= name;
+                        }
+                    }
+                    catch { /* best effort */ }
+                }
+                await notify(event, formatIssueAssigned, undefined, undefined, dedupeKey);
+            });
+        }
+        if (config.notifyOnApprovalCreated) {
+            ctx.events.on("approval.created", async (event) => {
+                if (!shouldNotifyApproval(event, config.onlyNotifyBoardApprovals))
+                    return;
+                const payload = event.payload;
+                // Enrich with linked issue details (event only has issueIds)
+                const issueIds = Array.isArray(payload.issueIds) ? payload.issueIds : [];
+                if (issueIds.length > 0 && !payload.linkedIssues) {
+                    try {
+                        const issues = await Promise.all(issueIds.slice(0, 5).map((id) => ctx.issues.get(id, event.companyId)));
+                        payload.linkedIssues = issues
+                            .filter(Boolean)
+                            .map((i) => ({
+                            identifier: i.identifier,
+                            title: i.title,
+                            status: i.status,
+                            priority: i.priority,
+                        }));
+                        // Use first issue's title as the approval title if missing
+                        if (!payload.title && issues[0]) {
+                            payload.title = issues[0].identifier
+                                ? `${issues[0].identifier}: ${issues[0].title}`
+                                : issues[0].title;
+                        }
+                    }
+                    catch { /* best effort */ }
+                }
+                // Enrich agent name
+                if (payload.agentId && !payload.agentName) {
+                    try {
+                        const agent = await ctx.agents.get(String(payload.agentId), event.companyId);
+                        if (agent)
+                            payload.agentName = agent.name;
+                    }
+                    catch { /* best effort */ }
+                }
+                // Build a meaningful title if still missing
+                if (!payload.title || payload.title === "Approval Requested") {
+                    const approvalType = String(payload.type ?? "unknown").replace(/_/g, " ");
+                    const agentLabel = payload.agentName ? String(payload.agentName) : null;
+                    payload.title = agentLabel
+                        ? `${approvalType} — ${agentLabel}`
+                        : approvalType;
+                }
+                await notify(event, formatApprovalCreated, config.approvalsChatId, config.approvalsTopicId);
+            });
+        }
+        if (config.notifyOnAgentError) {
+            const agentErrorDedupe = makeUpdateDedupe(AGENT_ERROR_DEDUPLICATION_WINDOW_MS, 1000);
+            ctx.events.on("agent.run.failed", async (event) => {
+                const payload = event.payload;
+                const agentId = String(payload.agentId ?? event.entityId);
+                if (payload.agentId && !payload.agentName) {
+                    try {
+                        const agent = await ctx.agents.get(String(payload.agentId), event.companyId);
+                        if (agent)
+                            payload.agentName = agent.name;
+                    }
+                    catch { /* best effort */ }
+                }
+                if (!payload.companyName) {
+                    try {
+                        const company = await ctx.companies.get(event.companyId);
+                        if (company?.name)
+                            payload.companyName = company.name;
+                    }
+                    catch { /* best effort */ }
+                }
+                if (payload.issueId && (!payload.issueIdentifier || !payload.issueTitle)) {
+                    try {
+                        const issue = await ctx.issues.get(String(payload.issueId), event.companyId);
+                        if (issue) {
+                            payload.issueIdentifier ??= issue.identifier;
+                            payload.issueTitle ??= issue.title;
+                        }
+                    }
+                    catch { /* best effort */ }
+                }
+                const errorMessage = normalizeAgentErrorMessage(payload.error ?? payload.message);
+                const dedupeKey = ["agent.run.failed", event.companyId, agentId, errorMessage].join(":");
+                if (!agentErrorDedupe(dedupeKey))
+                    return;
+                await notify(event, formatAgentError, config.errorsChatId, config.errorsTopicId, dedupeKey);
+            });
+        }
+        const enrichAgentName = async (event) => {
+            const payload = event.payload;
+            if (payload.agentId && !payload.agentName) {
+                try {
+                    const agent = await ctx.agents.get(String(payload.agentId), event.companyId);
+                    if (agent)
+                        payload.agentName = agent.name;
+                }
+                catch { /* best effort */ }
+            }
+        };
+        // Ops events route to a dedicated ops chat when an ops route matches the
+        // company; otherwise they fall back to the normal default-chat routing.
+        const notifyOps = async (event, formatter) => {
+            const opsDestination = await resolveOpsDestinationForEvent(ctx, config, event);
+            if (opsDestination) {
+                ctx.logger.info("Telegram ops notification routed", {
+                    eventType: event.eventType,
+                    companyId: event.companyId,
+                    routeName: opsDestination.routeName,
+                    chatId: opsDestination.chatId,
+                    topicId: opsDestination.topicId,
+                });
+            }
+            await notify(event, formatter, opsDestination?.chatId, opsDestination?.topicId);
+        };
+        if (config.notifyOnAgentRunStarted) {
+            ctx.events.on("agent.run.started", async (event) => {
+                await enrichAgentName(event);
+                await notifyOps(event, formatAgentRunStarted);
+            });
+        }
+        if (config.notifyOnAgentRunFinished) {
+            ctx.events.on("agent.run.finished", async (event) => {
+                await enrichAgentName(event);
+                await notifyOps(event, formatAgentRunFinished);
+            });
+        }
+        // --- Anti-flood filters (TWB-94, tue-Jonas/paperclip-plugin-telegram @03b6e99) ---
+        // Forward issue.updated as a "blocked" notification only when the issue is
+        // genuinely blocked AND a human/board user owns it (assigneeUserId non-null).
+        if (config.notifyOnIssueBlocked) {
+            const blockedDedupe = makeUpdateDedupe();
+            ctx.events.on("issue.updated", async (event) => {
+                const payload = event.payload;
+                // Cheap pre-gate so we never fetch the issue for non-blocked updates.
+                if (payload.status !== "blocked")
+                    return;
+                if (!blockedDedupe(`blocked|${event.entityId}`))
+                    return;
+                // issue.updated payloads frequently omit assignee/title, so enrich from
+                // the issue record before deciding whether a human/board user owns it.
+                if (event.entityId) {
+                    try {
+                        const issue = await ctx.issues.get(event.entityId, event.companyId);
+                        if (issue) {
+                            const anyIssue = issue;
+                            if (payload.assigneeUserId == null && anyIssue.assigneeUserId != null) {
+                                payload.assigneeUserId = anyIssue.assigneeUserId;
+                            }
+                            if (!payload.assigneeName && anyIssue.assigneeName) {
+                                payload.assigneeName = anyIssue.assigneeName;
+                            }
+                            if (!payload.title && issue.title)
+                                payload.title = issue.title;
+                        }
+                    }
+                    catch { /* best effort */ }
+                }
+                // Skip agent-only blocks (no human/board assignee). The rule itself lives
+                // in shouldNotifyIssueBlocked and now sees the enriched assigneeUserId.
+                if (!shouldNotifyIssueBlocked(event, true))
+                    return;
+                // Enrich with latest comment (likely the blocker reason)
+                if (!payload.comment && event.entityId) {
+                    try {
+                        const comments = await ctx.issues.listComments(event.entityId, event.companyId);
+                        if (comments.length > 0) {
+                            const latest = comments.reduce((a, b) => new Date(a.createdAt) > new Date(b.createdAt) ? a : b);
+                            payload.comment = latest.body;
+                        }
+                    }
+                    catch { /* best effort */ }
+                }
+                await notify(event, formatIssueBlocked);
+            });
+        }
+        // Forward issue.comment.created only when a configured board username is
+        // @-mentioned (word-boundary aware, case-insensitive).
+        const boardUsernames = parseBoardUsernames(config.boardUsernames);
+        if (config.notifyOnBoardMention && boardUsernames.length > 0) {
+            ctx.events.on("issue.comment.created", async (event) => {
+                if (!shouldNotifyBoardMention(event, true, boardUsernames))
+                    return;
+                const payload = event.payload;
+                // Enrich with issue identifier/title for a useful link + heading
+                const issueId = payload.issueId ??
+                    payload.issueIdentifier ??
+                    undefined;
+                if (issueId && (!payload.identifier || !payload.title)) {
+                    try {
+                        const issue = await ctx.issues.get(String(issueId), event.companyId);
+                        if (issue) {
+                            payload.identifier ??= issue.identifier;
+                            payload.title ??= issue.title;
+                        }
+                    }
+                    catch { /* best effort */ }
+                }
+                await notify(event, formatBoardMention);
+            });
+        }
+        // --- Per-company chat overrides ---
+        ctx.data.register("chat-mapping", async (params) => {
+            const companyId = String(params.companyId);
+            const saved = await ctx.state.get({
+                scopeKind: "company",
+                scopeId: companyId,
+                stateKey: "telegram-chat",
+            });
+            return { chatId: saved ?? config.defaultChatId };
+        });
+        ctx.actions.register("set-chat", async (params) => {
+            const companyId = String(params.companyId);
+            const chatId = String(params.chatId);
+            await ctx.state.set({ scopeKind: "company", scopeId: companyId, stateKey: "telegram-chat" }, chatId);
+            ctx.logger.info("Updated Telegram chat mapping", { companyId, chatId });
+            return { ok: true };
+        });
+        // --- Daily digest job ---
+        // Support legacy dailyDigestEnabled boolean
+        const effectiveDigestMode = config.dailyDigestEnabled === true && config.digestMode === "off"
+            ? "daily"
+            : config.digestMode ?? "off";
+        if (effectiveDigestMode !== "off") {
+            ctx.jobs.register("telegram-daily-digest", async () => {
+                // Check if current UTC hour matches a configured digest time
+                const nowHour = new Date().getUTCHours();
+                const nowMin = new Date().getUTCMinutes();
+                if (nowMin >= 5)
+                    return; // only fire within first 5 min of the hour
+                const parseHour = (t) => {
+                    const [h] = (t || "").split(":");
+                    return parseInt(h ?? "", 10);
+                };
+                const firstHour = parseHour(config.dailyDigestTime);
+                const secondHour = parseHour(config.bidailySecondTime);
+                const tridailyHours = (config.tridailyTimes || "07:00,13:00,19:00")
+                    .split(",")
+                    .map((t) => parseHour(t.trim()));
+                let shouldSend = false;
+                if (effectiveDigestMode === "daily") {
+                    shouldSend = nowHour === firstHour;
+                }
+                else if (effectiveDigestMode === "bidaily") {
+                    shouldSend = nowHour === firstHour || nowHour === secondHour;
+                }
+                else if (effectiveDigestMode === "tridaily") {
+                    shouldSend = tridailyHours.includes(nowHour);
+                }
+                if (!shouldSend)
+                    return;
+                const companies = await ctx.companies.list();
+                for (const company of companies) {
+                    const chatId = await resolveChat(ctx, company.id, config.digestChatId || config.defaultChatId);
+                    if (!chatId)
+                        continue;
+                    try {
+                        const agents = await ctx.agents.list({ companyId: company.id });
+                        const activeAgents = agents.filter((a) => a.status === "active");
+                        const issues = await ctx.issues.list({ companyId: company.id, limit: 50 });
+                        const now = Date.now();
+                        const oneDayMs = 24 * 60 * 60 * 1000;
+                        const completedToday = issues.filter((i) => i.status === "done" && i.completedAt && (now - new Date(i.completedAt).getTime()) < oneDayMs);
+                        const createdToday = issues.filter((i) => (now - new Date(i.createdAt).getTime()) < oneDayMs);
+                        const issuePrefix = company.issuePrefix;
+                        const inProgress = issues.filter((i) => i.status === "in_progress");
+                        const inReview = issues.filter((i) => i.status === "in_review");
+                        const blocked = issues.filter((i) => i.status === "blocked");
+                        const dateStr = new Date().toISOString().split("T")[0];
+                        const companyLabel = company.name ? ` \\- ${escapeMarkdownV2(company.name)}` : "";
+                        const digestLabel = effectiveDigestMode === "bidaily" ? "Digest" : "Daily Digest";
+                        const lines = [
+                            escapeMarkdownV2("\ud83d\udcca") + ` *${escapeMarkdownV2(digestLabel)}${companyLabel} \\- ${escapeMarkdownV2(dateStr)}*`,
+                            "",
+                            `${escapeMarkdownV2("\u2705")} Tasks completed: *${completedToday.length}*`,
+                            `${escapeMarkdownV2("\ud83d\udccb")} Tasks created: *${createdToday.length}*`,
+                            `${escapeMarkdownV2("\ud83e\udd16")} Active agents: *${activeAgents.length}*/${escapeMarkdownV2(String(agents.length))}`,
+                        ];
+                        if (activeAgents.length > 0) {
+                            const topAgent = activeAgents[0].name;
+                            lines.push(`${escapeMarkdownV2("\u2b50")} Top performer: *${escapeMarkdownV2(topAgent)}*`);
+                        }
+                        const formatIssueItem = (i) => {
+                            const id = i.identifier ?? i.id;
+                            const idText = issuePrefix
+                                ? `[${escapeMarkdownV2(id)}](${publicUrl}/${issuePrefix}/issues/${id})`
+                                : escapeMarkdownV2(id);
+                            return `  ${idText} \\- ${escapeMarkdownV2(i.title)}`;
+                        };
+                        if (inProgress.length > 0) {
+                            lines.push("", `${escapeMarkdownV2("\ud83d\udd04")} *In Progress \\(${inProgress.length}\\)*`);
+                            for (const i of inProgress.slice(0, 10))
+                                lines.push(formatIssueItem(i));
+                        }
+                        if (inReview.length > 0) {
+                            lines.push("", `${escapeMarkdownV2("\ud83d\udd0d")} *In Review \\(${inReview.length}\\)*`);
+                            for (const i of inReview.slice(0, 10))
+                                lines.push(formatIssueItem(i));
+                        }
+                        if (blocked.length > 0) {
+                            lines.push("", `${escapeMarkdownV2("\ud83d\udeab")} *Blocked \\(${blocked.length}\\)*`);
+                            for (const i of blocked.slice(0, 10))
+                                lines.push(formatIssueItem(i));
+                        }
+                        const digestThreadId = await resolveDigestThreadId(ctx, token, chatId, config.digestTopicId);
+                        await sendMessage(ctx, token, chatId, lines.join("\n"), {
+                            parseMode: "MarkdownV2",
+                            messageThreadId: digestThreadId,
+                        });
+                    }
+                    catch (err) {
+                        ctx.logger.error("Daily digest failed for company", { companyId: company.id, error: String(err) });
+                        const text = [
+                            escapeMarkdownV2("\ud83d\udcca") + " *Daily Digest*",
+                            "",
+                            escapeMarkdownV2("Could not generate digest. Check plugin logs for details."),
+                        ].join("\n");
+                        const errorThreadId = await resolveDigestThreadId(ctx, token, chatId, config.errorsTopicId || config.digestTopicId);
+                        await sendMessage(ctx, token, chatId, text, {
+                            parseMode: "MarkdownV2",
+                            messageThreadId: errorThreadId,
+                        });
+                    }
+                }
+            });
+        }
+        // --- Phase 1: Escalation support ---
+        const escalationManager = new EscalationManager();
+        // Register escalate_to_human tool - 3-arg signature with ToolRunContext
+        ctx.tools.register("escalate_to_human", {
+            displayName: "Escalate to Human",
+            description: "Escalate a conversation to a human when you cannot handle it confidently",
+            parametersSchema: {
+                type: "object",
+                properties: {
+                    reason: {
+                        type: "string",
+                        enum: ["low_confidence", "explicit_request", "policy_violation", "unknown_intent"],
+                        description: "Why this conversation needs human attention",
+                    },
+                    conversationSummary: {
+                        type: "string",
+                        description: "Brief summary of the conversation context and what the user needs",
+                    },
+                    suggestedActions: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Suggested actions the human responder could take",
+                    },
+                    suggestedReply: {
+                        type: "string",
+                        description: "A draft reply the human can send or modify",
+                    },
+                    confidenceScore: {
+                        type: "number",
+                        minimum: 0,
+                        maximum: 1,
+                        description: "How confident the agent is (0-1). Lower values indicate greater need for human help",
+                    },
+                    originChatId: { type: "string" },
+                    originThreadId: { type: "string" },
+                    originMessageId: { type: "string" },
+                    sessionId: { type: "string", description: "Session ID for routing reply back" },
+                    transport: { type: "string", enum: ["native", "acp"], description: "Transport type for reply routing" },
+                },
+                required: ["reason", "conversationSummary"],
+            },
+        }, async (params, runCtx) => {
+            const p = params;
+            const escalationId = crypto.randomUUID();
+            const timeoutMs = config.escalationTimeoutMs || 900000;
+            const defaultAction = config.escalationDefaultAction || "defer";
+            const resolvedEscalationChatId = await resolveChat(ctx, runCtx.companyId, config.escalationChatId);
+            if (!resolvedEscalationChatId) {
+                ctx.logger.warn("Escalation received but no escalationChatId configured");
+                return { error: "No escalation channel configured" };
+            }
+            const escalationEvent = {
+                escalationId,
+                agentId: runCtx.agentId,
+                companyId: runCtx.companyId,
+                reason: p.reason,
+                context: {
+                    conversationHistory: [],
+                    agentReasoning: String(p.conversationSummary ?? ""),
+                    suggestedActions: p.suggestedActions ?? [],
+                    suggestedReply: p.suggestedReply ? String(p.suggestedReply) : undefined,
+                    confidenceScore: typeof p.confidenceScore === "number" ? p.confidenceScore : undefined,
+                },
+                timeout: {
+                    durationMs: timeoutMs,
+                    defaultAction,
+                },
+                originChatId: p.originChatId ? String(p.originChatId) : undefined,
+                originThreadId: p.originThreadId ? String(p.originThreadId) : undefined,
+                originMessageId: p.originMessageId ? String(p.originMessageId) : undefined,
+                transport: p.transport,
+                sessionId: p.sessionId ? String(p.sessionId) : undefined,
+            };
+            await escalationManager.create(ctx, token, escalationEvent, resolvedEscalationChatId);
+            // Send hold message to the originating chat if configured
+            if (config.escalationHoldMessage && escalationEvent.originChatId) {
+                const holdText = escapeMarkdownV2(config.escalationHoldMessage);
+                await sendMessage(ctx, token, escalationEvent.originChatId, holdText, {
+                    parseMode: "MarkdownV2",
+                    messageThreadId: escalationEvent.originThreadId ? Number(escalationEvent.originThreadId) : undefined,
+                    replyToMessageId: escalationEvent.originMessageId ? Number(escalationEvent.originMessageId) : undefined,
+                });
+            }
+            return { content: JSON.stringify({ status: "escalated", escalationId }) };
+        });
+        // --- Phase 2: Register handoff_to_agent tool ---
+        ctx.tools.register("handoff_to_agent", {
+            displayName: "Handoff to Agent",
+            description: "Hand off work to another agent in this thread",
+            parametersSchema: {
+                type: "object",
+                properties: {
+                    targetAgent: { type: "string", description: "Name of agent to hand off to" },
+                    reason: { type: "string", description: "Why you're handing off" },
+                    contextSummary: { type: "string", description: "Summary for the target agent" },
+                    requiresApproval: { type: "boolean", default: true, description: "Wait for human approval before target starts" },
+                    chatId: { type: "string", description: "Telegram chat ID" },
+                    threadId: { type: "number", description: "Telegram thread ID" },
+                },
+                required: ["targetAgent", "reason", "contextSummary"],
+            },
+        }, async (params, runCtx) => {
+            return handleHandoffToolCall(ctx, token, params, runCtx.companyId, runCtx.agentId);
+        });
+        // --- Phase 2: Register discuss_with_agent tool ---
+        ctx.tools.register("discuss_with_agent", {
+            displayName: "Discuss with Agent",
+            description: "Start a back-and-forth conversation with another agent",
+            parametersSchema: {
+                type: "object",
+                properties: {
+                    targetAgent: { type: "string", description: "Name of agent to discuss with" },
+                    topic: { type: "string", description: "Discussion topic" },
+                    initialMessage: { type: "string", description: "First message to send" },
+                    maxTurns: { type: "number", default: 10, description: "Maximum conversation turns" },
+                    humanCheckpointAt: { type: "number", description: "Pause for human approval at this turn" },
+                    chatId: { type: "string", description: "Telegram chat ID" },
+                    threadId: { type: "number", description: "Telegram thread ID" },
+                },
+                required: ["targetAgent", "topic", "initialMessage"],
+            },
+        }, async (params, runCtx) => {
+            return handleDiscussToolCall(ctx, token, params, runCtx.companyId, runCtx.agentId);
+        });
+        // --- Agent file-send tool (ant013 TEL-8 / TEL-23) ---
+        const sendToTelegram = (params, runCtx) => sendToTelegramTool(ctx, token, config, params, runCtx);
+        const sendToTelegramParametersSchema = {
+            type: "object",
+            properties: {
+                chatId: {
+                    type: "string",
+                    description: "Telegram chat ID. Defaults to the configured company chat when omitted.",
+                },
+                threadId: {
+                    type: "number",
+                    description: "Optional Telegram forum topic ID.",
+                },
+                text: {
+                    type: "string",
+                    description: "Text message or Markdown caption if markdownContent is used.",
+                },
+                markdownContent: {
+                    type: "string",
+                    description: "Markdown document content for upload.",
+                },
+                markdownFileName: {
+                    type: "string",
+                    description: "Optional .md filename when markdownContent is provided.",
+                },
+                projectKey: {
+                    type: "string",
+                    description: "Optional Paperclip project key for Markdown document file routing, such as TEL.",
+                },
+                issueIdentifier: {
+                    type: "string",
+                    description: "Optional Paperclip issue key for Markdown document file routing, such as TEL-8.",
+                },
+                issueId: {
+                    type: "string",
+                    description: "Optional Paperclip issue ID used to resolve a project-key file route.",
+                },
+                parseMode: {
+                    type: "string",
+                    enum: ["MarkdownV2", "HTML"],
+                    description: "Optional parse mode for text/caption.",
+                },
+                replyToMessageId: {
+                    type: "number",
+                    description: "Optional Telegram message ID to reply to.",
+                },
+                silent: {
+                    type: "boolean",
+                    description: "Send without notification.",
+                },
+                sessionId: {
+                    type: "string",
+                    description: "Optional Paperclip session ID for routing Telegram replies back to the agent session.",
+                },
+            },
+            anyOf: [{ required: ["text"] }, { required: ["markdownContent"] }],
+        };
+        ctx.tools.register("send_to_telegram", {
+            displayName: "Send Telegram Message",
+            description: "Send text and Markdown content to Telegram.",
+            parametersSchema: sendToTelegramParametersSchema,
+        }, (params, runCtx) => sendToTelegram(params, runCtx));
+        // Keep the previous tool name as a compatibility alias.
+        ctx.tools.register("send_file_to_telegram", {
+            displayName: "Send File to Telegram",
+            description: "Deprecated: send text and Markdown content to Telegram.",
+            parametersSchema: sendToTelegramParametersSchema,
+        }, (params, runCtx) => sendToTelegram(params, runCtx));
+        // --- Phase 5: Register register_watch tool ---
+        ctx.tools.register("register_watch", {
+            displayName: "Register Watch",
+            description: "Register a proactive watch that monitors entities and sends suggestions",
+            parametersSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Name of the watch" },
+                    description: { type: "string", description: "What this watch monitors" },
+                    entityType: { type: "string", enum: ["issue", "agent", "company", "custom"], description: "Type of entity to watch" },
+                    conditions: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                field: { type: "string" },
+                                operator: { type: "string", enum: ["gt", "lt", "eq", "ne", "contains", "exists"] },
+                                value: {},
+                            },
+                            required: ["field", "operator", "value"],
+                        },
+                        description: "Conditions that trigger the watch",
+                    },
+                    template: { type: "string", description: "Message template with {{field}} placeholders" },
+                    builtinTemplate: { type: "string", enum: ["invoice-overdue", "lead-stale"], description: "Use a built-in template instead" },
+                    chatId: { type: "string", description: "Telegram chat ID for suggestions" },
+                    threadId: { type: "number", description: "Telegram thread ID for suggestions" },
+                },
+                required: ["chatId"],
+            },
+        }, async (params, runCtx) => {
+            return handleRegisterWatch(ctx, params, runCtx.companyId);
+        });
+        // --- Phase 1: Escalation timeout checker job ---
+        ctx.jobs.register("check-escalation-timeouts", async () => {
+            try {
+                await escalationManager.checkTimeouts(ctx, token);
+            }
+            catch (err) {
+                ctx.logger.error("Escalation timeout check failed", { error: String(err) });
+            }
+        });
+        // --- Phase 5: Watch checker job ---
+        ctx.jobs.register("check-watches", async () => {
+            try {
+                await checkWatches(ctx, token, {
+                    maxSuggestionsPerHourPerCompany: config.maxSuggestionsPerHourPerCompany ?? 10,
+                    watchDeduplicationWindowMs: config.watchDeduplicationWindowMs ?? 86400000,
+                });
+            }
+            catch (err) {
+                ctx.logger.error("Watch check failed", { error: String(err) });
+            }
+        });
+        ctx.logger.info("Telegram bot plugin started (Chat OS v2 - all 5 phases)");
+    },
+    async onValidateConfig(config) {
+        const secretRefErrors = validateSecretRefFields(config);
+        if (secretRefErrors.length > 0) {
+            return { ok: false, errors: secretRefErrors };
+        }
+        const allowlistErrors = validateTelegramAllowlists(config);
+        if (allowlistErrors.length > 0) {
+            return { ok: false, errors: allowlistErrors };
+        }
+        const topicErrors = validateConfiguredTopicIds(config);
+        if (topicErrors.length > 0) {
+            return { ok: false, errors: topicErrors };
+        }
+        const fileRouteErrors = getTelegramFileRouteSaveErrors(config.fileRoutes);
+        if (fileRouteErrors.length > 0) {
+            return { ok: false, errors: fileRouteErrors };
+        }
+        return { ok: true };
+    },
+    async onHealth() {
+        return { status: "ok" };
+    },
+});
+async function handleUpdate(ctx, token, config, update, baseUrl, publicUrl, boardApiToken) {
+    if (!isTelegramUpdateAllowed(config, update)) {
+        const fromId = update.message?.from?.id ?? update.callback_query?.from.id;
+        const chatId = update.message?.chat.id ?? update.callback_query?.message?.chat.id;
+        ctx.logger.warn("Blocked unauthorized Telegram update", {
+            updateId: update.update_id,
+            fromId,
+            chatId,
+        });
+        return;
+    }
+    if (update.callback_query) {
+        const companyId = await resolveCallbackCompanyId(ctx, update.callback_query);
+        const boardApiToken = await resolveBoardApiToken(ctx, config, companyId);
+        await handleCallbackQuery(ctx, token, update.callback_query, baseUrl, boardApiToken);
+        return;
+    }
+    const msg = update.message;
+    if (!msg)
+        return;
+    const chatId = String(msg.chat.id);
+    const threadId = msg.message_thread_id;
+    // Phase 3: Handle media messages
+    const hasMedia = !!(msg.voice || msg.audio || msg.video_note || msg.document || msg.photo);
+    if (hasMedia) {
+        const companyId = await resolveCompanyId(ctx, chatId);
+        const handled = await handleMediaMessage(ctx, token, msg, {
+            briefAgentId: config.briefAgentId ?? "",
+            briefAgentChatIds: config.briefAgentChatIds ?? [],
+            transcriptionApiKeyRef: config.transcriptionApiKeyRef ?? "",
+            publicUrl,
+        }, companyId);
+        if (handled)
+            return;
+    }
+    if (!msg.text)
+        return;
+    const text = msg.text;
+    // Route thread messages to agent sessions
+    if (threadId) {
+        const isCommand = text.startsWith("/");
+        if (!isCommand) {
+            const companyId = await resolveCompanyId(ctx, chatId);
+            const replyToId = msg.reply_to_message?.message_id;
+            const routed = await routeMessageToAgent(ctx, token, chatId, threadId, text, replyToId, companyId);
+            if (routed)
+                return;
+        }
+    }
+    const botCommand = msg.entities?.find((e) => e.type === "bot_command" && e.offset === 0);
+    if (botCommand && config.enableCommands) {
+        const fullCommand = text.slice(botCommand.offset, botCommand.offset + botCommand.length);
+        const command = fullCommand.replace(/^\//, "").replace(/@.*$/, "");
+        const args = text.slice(botCommand.offset + botCommand.length).trim();
+        const companyId = await resolveCompanyId(ctx, chatId);
+        // Phase 4: Check custom commands first
+        if (command === "commands") {
+            await handleCommandsCommand(ctx, token, chatId, args, threadId, companyId);
+            return;
+        }
+        const handledCustom = await tryCustomCommand(ctx, token, chatId, command, args, threadId, companyId);
+        if (handledCustom)
+            return;
+        // Built-in commands
+        const boardApiToken = command === "approve" ? await resolveBoardApiToken(ctx, config, companyId) : undefined;
+        await handleCommand(ctx, token, chatId, command, args, threadId, baseUrl, publicUrl, companyId, boardApiToken, config.maxAgentsPerThread);
+        return;
+    }
+    if (config.enableInbound && msg.reply_to_message?.from?.is_bot) {
+        const replyToId = msg.reply_to_message.message_id;
+        const mapping = await ctx.state.get({
+            scopeKind: "instance",
+            stateKey: `msg_${chatId}_${replyToId}`,
+        });
+        if (mapping && mapping.entityType === "escalation") {
+            const escalationManager = new EscalationManager();
+            const responderId = `telegram:${msg.from?.username ?? msg.from?.id ?? chatId}`;
+            await escalationManager.respond(ctx, token, mapping.entityId, {
+                escalationId: mapping.entityId,
+                responderId,
+                responseText: text,
+                action: "reply_to_customer",
+            });
+            await ctx.metrics.write(METRIC_NAMES.inboundRouted, 1);
+            ctx.logger.info("Routed Telegram reply to escalation", {
+                escalationId: mapping.entityId,
+                from: msg.from?.username,
+            });
+        }
+        else if (mapping && mapping.entityType === "issue") {
+            try {
+                // Use the SDK (not ctx.http.fetch) because the plugin sandbox blocks
+                // outbound fetches to private IPs like 127.0.0.1 for SSRF protection.
+                // The SDK's createComment goes through the plugin RPC bridge instead.
+                await ctx.issues.createComment(mapping.entityId, text, mapping.companyId);
+                await ctx.metrics.write(METRIC_NAMES.inboundRouted, 1);
+                ctx.logger.info("Routed Telegram reply to issue comment", {
+                    issueId: mapping.entityId,
+                    from: msg.from?.username,
+                });
+            }
+            catch (err) {
+                ctx.logger.error("Failed to route inbound message", {
+                    issueId: mapping.entityId,
+                    error: String(err),
+                });
+            }
+        }
+    }
+}
+/**
+ * Graceful fallback for a decision-button callback whose underlying approval is
+ * no longer actionable (TWX-328: stale inline-button presses). When the failure
+ * is an "already resolved/decided" conflict — the approval was decided through
+ * another channel, expired, or already resolved in the opposite direction — we
+ * acknowledge it quietly and update the card instead of surfacing a raw API
+ * error string to the board member. Any other error still surfaces as a failure.
+ */
+async function handleDecisionCallbackError(ctx, token, query, chatId, messageId, decision, err) {
+    if (isAlreadyResolvedConflict(err)) {
+        ctx.logger.info("Ignored stale Telegram decision callback", {
+            kind: decision.kind,
+            id: decision.id,
+            actor: decision.actor,
+        });
+        await answerCallbackQuery(ctx, token, query.id, "Already resolved");
+        if (chatId && messageId) {
+            await editMessage(ctx, token, chatId, messageId, escapeMarkdownV2("This decision was already resolved."), { parseMode: "MarkdownV2" });
+        }
+        return;
+    }
+    await answerCallbackQuery(ctx, token, query.id, `Failed: ${String(err)}`);
+}
+export async function handleCallbackQuery(ctx, token, query, baseUrl, boardApiToken) {
+    const data = query.data;
+    if (!data)
+        return;
+    const actor = query.from.username ?? query.from.first_name ?? String(query.from.id);
+    const chatId = query.message?.chat.id ? String(query.message.chat.id) : null;
+    const messageId = query.message?.message_id;
+    if (data.startsWith("approve_")) {
+        const approvalId = data.replace("approve_", "");
+        ctx.logger.info("Approval button clicked", { approvalId, actor });
+        try {
+            await fetchPaperclipApi(ctx, `${baseUrl}/api/approvals/${approvalId}/approve`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...buildPaperclipAuthHeaders(boardApiToken),
+                },
+                body: JSON.stringify({ decidedByUserId: `telegram:${actor}` }),
+            });
+            await answerCallbackQuery(ctx, token, query.id, "Approved");
+            if (chatId && messageId) {
+                await editMessage(ctx, token, chatId, messageId, formatResolvedDecision(query.message?.text, "approved", actor), { parseMode: "MarkdownV2" });
+            }
+        }
+        catch (err) {
+            await handleDecisionCallbackError(ctx, token, query, chatId, messageId, { kind: "approval_approve", id: approvalId, actor }, err);
+        }
+        return;
+    }
+    if (data.startsWith("esc_")) {
+        const parts = data.split("_");
+        const action = parts[1] ?? "";
+        const escalationId = parts.slice(2).join("_");
+        const escalationManager = new EscalationManager();
+        await escalationManager.handleCallback(ctx, token, action, escalationId, actor, query.id, chatId, messageId);
+        await answerCallbackQuery(ctx, token, query.id, `Escalation: ${action}`);
+        return;
+    }
+    if (data.startsWith("reject_")) {
+        const approvalId = data.replace("reject_", "");
+        ctx.logger.info("Rejection button clicked", { approvalId, actor });
+        try {
+            await fetchPaperclipApi(ctx, `${baseUrl}/api/approvals/${approvalId}/reject`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...buildPaperclipAuthHeaders(boardApiToken),
+                },
+                body: JSON.stringify({ decidedByUserId: `telegram:${actor}` }),
+            });
+            await answerCallbackQuery(ctx, token, query.id, "Rejected");
+            if (chatId && messageId) {
+                await editMessage(ctx, token, chatId, messageId, formatResolvedDecision(query.message?.text, "rejected", actor), { parseMode: "MarkdownV2" });
+            }
+        }
+        catch (err) {
+            await handleDecisionCallbackError(ctx, token, query, chatId, messageId, { kind: "approval_reject", id: approvalId, actor }, err);
+        }
+        return;
+    }
+    if (data.startsWith("handoff_approve_")) {
+        const handoffId = data.replace("handoff_approve_", "");
+        await handleHandoffApproval(ctx, token, handoffId, actor, query.id, chatId, messageId);
+        await answerCallbackQuery(ctx, token, query.id, "Handoff approved");
+        return;
+    }
+    if (data.startsWith("handoff_reject_")) {
+        const handoffId = data.replace("handoff_reject_", "");
+        await handleHandoffRejection(ctx, token, handoffId, actor, query.id, chatId, messageId);
+        await answerCallbackQuery(ctx, token, query.id, "Handoff rejected");
+        return;
+    }
+    await answerCallbackQuery(ctx, token, query.id, "Unknown action");
+}
+runWorker(plugin, import.meta.url);
+//# sourceMappingURL=worker.js.map