comisai 1.0.36 → 1.0.40

package/node_modules/@comis/channels/dist/telegram/telegram-adapter/telegram-outbound.js

@@ -0,0 +1,360 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: Telegram SDK boundary throws; consumed by adapter try/catch + inbound-pipeline catch.
+/**
+ * Telegram outbound dispatch.
+ *
+ * State-first wrappers around every outbound operation that the adapter
+ * handle exposes:
+ *   - sendMessage / editMessage / reactToMessage / removeReaction
+ *     / deleteMessage / fetchMessages / sendAttachment
+ *   - platformAction (the big switch covering pin/unpin/poll/sticker/
+ *     chat_info/member_count/get_admins/sendTyping/set_title/
+ *     set_description/ban/unban/promote/createForumTopic/
+ *     editForumTopic/closeForumTopic/reopenForumTopic).
+ *
+ * State-first protocol: every helper takes `state: TelegramAdapterState`
+ * as its FIRST positional parameter, `deps: TelegramAdapterDeps` as
+ * SECOND, then per-call args.
+ *
+ * @module
+ */
+import { InputFile } from "grammy";
+import { ok, err } from "@comis/shared";
+import { systemNowMs } from "@comis/core";
+import { renderTelegramButtons, renderTelegramCards } from "../rich-renderer.js";
+import { buildTypingThreadParams, resolveOutboundThreadParams, } from "../thread-context.js";
+import { createTelegramVoiceSender } from "../voice-sender.js";
+import { isTelegramHtmlParseError, sanitizeTelegramHtml, sendWithThreadFallback, } from "./telegram-webhook.js";
+// ---------------------------------------------------------------------------
+// sendMessage
+// ---------------------------------------------------------------------------
+export async function sendMessage(state, deps, chatId, text, options) {
+    try {
+        // Apply effects
+        const isSpoiler = options?.effects?.includes("spoiler");
+        const isSilent = options?.effects?.includes("silent");
+        // Render cards as HTML if present (prepend to text)
+        let finalText = text;
+        if (options?.cards && options.cards.length > 0) {
+            const cardHtml = renderTelegramCards(options.cards);
+            finalText = cardHtml + (text ? "\n\n" + text : "");
+            deps.logger.debug({ channelType: "telegram", cardsRendered: options.cards.length }, "Rich cards rendered as HTML");
+        }
+        // Apply spoiler effect
+        if (isSpoiler) {
+            finalText = `<tg-spoiler>${finalText}</tg-spoiler>`;
+        }
+        // Log effects if any are applied
+        if (options?.effects && options.effects.length > 0) {
+            deps.logger.debug({ channelType: "telegram", effectsRendered: options.effects }, "Rich effects applied");
+        }
+        // Log buttons if present
+        if (options?.buttons && options.buttons.length > 0) {
+            deps.logger.debug({ channelType: "telegram", buttonsRendered: options.buttons.length }, "Rich buttons rendered");
+        }
+        const baseOpts = {
+            ...(options?.replyTo
+                ? { reply_parameters: { message_id: Number(options.replyTo) } }
+                : {}),
+            ...(options?.disableLinkPreview ? { link_preview_options: { is_disabled: true } } : {}),
+            ...(isSilent ? { disable_notification: true } : {}),
+            ...(options?.buttons && options.buttons.length > 0
+                ? { reply_markup: renderTelegramButtons(options.buttons) }
+                : {}),
+        };
+        // Sanitize bare `<` that aren't valid Telegram HTML tags (e.g. `<5%`)
+        finalText = sanitizeTelegramHtml(finalText);
+        const threadParams = resolveOutboundThreadParams(options);
+        const doSend = async (tp) => {
+            const opts = { ...baseOpts, ...(tp ?? {}) };
+            try {
+                return await state.bot.api.sendMessage(Number(chatId), finalText, { parse_mode: "HTML", ...opts });
+            }
+            catch (htmlErr) {
+                if (isTelegramHtmlParseError(htmlErr)) {
+                    deps.logger.warn({ channelType: "telegram", chatId, err: htmlErr instanceof Error ? htmlErr : new Error(String(htmlErr)), hint: "HTML parse failed, retrying as plain text", errorKind: "platform" }, "HTML parse fallback triggered");
+                    return await state.bot.api.sendMessage(Number(chatId), finalText, opts);
+                }
+                throw htmlErr;
+            }
+        };
+        const sent = await sendWithThreadFallback(doSend, threadParams, deps.logger);
+        state.lastMessageAt = systemNowMs();
+        state.lastError = undefined;
+        deps.logger.debug({ channelType: "telegram", messageId: String(sent.message_id), chatId, preview: finalText.slice(0, 1500) }, "Outbound message");
+        return ok(String(sent.message_id));
+    }
+    catch (error) {
+        const sendErr = error instanceof Error ? error : new Error(String(error));
+        state.lastError = sendErr.message;
+        deps.logger.warn({
+            channelType: "telegram",
+            chatId,
+            err: sendErr,
+            hint: "Check Telegram bot token permissions and chat accessibility",
+            errorKind: "platform",
+        }, "Send message failed");
+        return err(new Error(`Failed to send message: ${sendErr.message}`));
+    }
+}
+// ---------------------------------------------------------------------------
+// editMessage
+// ---------------------------------------------------------------------------
+export async function editMessage(state, deps, chatId, messageId, text) {
+    try {
+        const sanitizedText = sanitizeTelegramHtml(text);
+        try {
+            await state.bot.api.editMessageText(Number(chatId), Number(messageId), sanitizedText, {
+                parse_mode: "HTML",
+            });
+        }
+        catch (htmlErr) {
+            if (isTelegramHtmlParseError(htmlErr)) {
+                deps.logger.warn({ channelType: "telegram", chatId, messageId, err: htmlErr instanceof Error ? htmlErr : new Error(String(htmlErr)), hint: "HTML parse failed on edit, retrying as plain text", errorKind: "platform" }, "HTML parse fallback triggered (edit)");
+                await state.bot.api.editMessageText(Number(chatId), Number(messageId), text);
+            }
+            else {
+                throw htmlErr;
+            }
+        }
+        deps.logger.debug({ channelType: "telegram", messageId, chatId, preview: text.slice(0, 1500) }, "Outbound message");
+        return ok(undefined);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return err(new Error(`Failed to edit message: ${message}`));
+    }
+}
+// ---------------------------------------------------------------------------
+// reactToMessage / removeReaction / deleteMessage / fetchMessages
+// ---------------------------------------------------------------------------
+export async function reactToMessage(state, _deps, chatId, messageId, emoji) {
+    try {
+        await state.bot.api.setMessageReaction(Number(chatId), Number(messageId), [
+            { type: "emoji", emoji },
+        ]);
+        return ok(undefined);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return err(new Error(`Failed to react to message: ${message}`));
+    }
+}
+export async function removeReaction(state, _deps, chatId, messageId, _emoji) {
+    try {
+        await state.bot.api.setMessageReaction(Number(chatId), Number(messageId), []);
+        return ok(undefined);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return err(new Error(`Failed to remove reaction: ${message}`));
+    }
+}
+export async function deleteMessage(state, _deps, chatId, messageId) {
+    try {
+        await state.bot.api.deleteMessage(Number(chatId), Number(messageId));
+        return ok(undefined);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return err(new Error(`Failed to delete message: ${message}`));
+    }
+}
+export async function fetchMessages(_state, _deps, _channelId, _options) {
+    return err(new Error("Fetching message history is not supported on Telegram. Bots can only see messages they receive in real-time."));
+}
+// ---------------------------------------------------------------------------
+// sendAttachment
+// ---------------------------------------------------------------------------
+export async function sendAttachment(state, deps, chatId, attachment, options) {
+    // Voice note dispatch: use voice-specific API for native voice bubbles
+    if (attachment.isVoiceNote && attachment.type === "audio") {
+        const voiceSender = createTelegramVoiceSender({ bot: state.bot, logger: deps.logger });
+        const threadParams = resolveOutboundThreadParams(options);
+        return voiceSender.sendVoice(chatId, attachment.url, attachment.durationSecs ?? 0, {
+            replyTo: options?.replyTo,
+            threadParams,
+        });
+    }
+    try {
+        const isLocalPath = !attachment.url.includes("://");
+        const file = isLocalPath
+            ? new InputFile(attachment.url)
+            : new InputFile(new URL(attachment.url));
+        const replyParams = options?.replyTo
+            ? { reply_parameters: { message_id: Number(options.replyTo) } }
+            : {};
+        const threadParams = resolveOutboundThreadParams(options);
+        const doSend = async (tp) => {
+            const opts = { caption: attachment.caption, ...replyParams, ...(tp ?? {}) };
+            switch (attachment.type) {
+                case "image": return state.bot.api.sendPhoto(Number(chatId), file, opts);
+                case "audio": return state.bot.api.sendAudio(Number(chatId), file, opts);
+                case "video": return state.bot.api.sendVideo(Number(chatId), file, opts);
+                default: return state.bot.api.sendDocument(Number(chatId), file, opts);
+            }
+        };
+        const sent = await sendWithThreadFallback(doSend, threadParams, deps.logger);
+        if (isLocalPath) {
+            deps.logger.info({ channelType: "telegram", messageId: String(sent.message_id), chatId, fileName: attachment.fileName }, "Local file attachment sent");
+        }
+        deps.logger.debug({ channelType: "telegram", messageId: String(sent.message_id), chatId, preview: (attachment.caption ?? attachment.fileName ?? "").slice(0, 1500) }, "Outbound attachment");
+        return ok(String(sent.message_id));
+    }
+    catch (error) {
+        const sendErr = error instanceof Error ? error : new Error(String(error));
+        deps.logger.warn({
+            channelType: "telegram",
+            chatId,
+            err: sendErr,
+            hint: "Check Telegram bot token permissions and file accessibility",
+            errorKind: "platform",
+        }, "Send attachment failed");
+        return err(new Error(`Failed to send attachment: ${sendErr.message}`));
+    }
+}
+// ---------------------------------------------------------------------------
+// platformAction
+// ---------------------------------------------------------------------------
+export async function platformAction(state, deps, action, params) {
+    try {
+        // Telegram chat IDs can be numeric or string; convert appropriately
+        const resolveChatId = (raw) => {
+            const s = String(raw);
+            return /^-?\d+$/.test(s) ? Number(s) : s;
+        };
+        switch (action) {
+            case "pin": {
+                const chatId = resolveChatId(params.chat_id);
+                const messageId = Number(params.message_id);
+                await state.bot.api.pinChatMessage(chatId, messageId);
+                return ok({ pinned: true });
+            }
+            case "unpin": {
+                const chatId = resolveChatId(params.chat_id);
+                const messageId = params.message_id ? Number(params.message_id) : undefined;
+                await state.bot.api.unpinChatMessage(chatId, messageId);
+                return ok({ unpinned: true });
+            }
+            case "poll": {
+                const chatId = resolveChatId(params.chat_id);
+                const question = String(params.question);
+                const options = params.options;
+                const result = await state.bot.api.sendPoll(chatId, question, options);
+                return ok({ pollSent: true, chatId, messageId: result.message_id });
+            }
+            case "sticker": {
+                const chatId = resolveChatId(params.chat_id);
+                const stickerId = String(params.sticker_id);
+                await state.bot.api.sendSticker(chatId, stickerId);
+                return ok({ stickerSent: true, chatId });
+            }
+            case "chat_info": {
+                const chatId = resolveChatId(params.chat_id);
+                const chat = await state.bot.api.getChat(chatId);
+                return ok(chat);
+            }
+            case "member_count": {
+                const chatId = resolveChatId(params.chat_id);
+                const count = await state.bot.api.getChatMemberCount(chatId);
+                return ok({ count });
+            }
+            case "get_admins": {
+                const chatId = resolveChatId(params.chat_id);
+                const admins = await state.bot.api.getChatAdministrators(chatId);
+                return ok({
+                    admins: admins.map((a) => ({
+                        userId: a.user.id,
+                        firstName: a.user.first_name,
+                        isBot: a.user.is_bot,
+                        status: a.status,
+                    })),
+                });
+            }
+            case "sendTyping": {
+                const chatId = resolveChatId(params.chatId ?? params.chat_id);
+                const threadId = params.threadId != null ? Number(params.threadId) : undefined;
+                const typingParams = buildTypingThreadParams(threadId);
+                await state.bot.api.sendChatAction(chatId, "typing", typingParams ?? {});
+                return ok({ typing: true });
+            }
+            case "set_title": {
+                const chatId = resolveChatId(params.chat_id);
+                const title = String(params.title);
+                await state.bot.api.setChatTitle(chatId, title);
+                return ok({ titleSet: true });
+            }
+            case "set_description": {
+                const chatId = resolveChatId(params.chat_id);
+                const description = String(params.description);
+                await state.bot.api.setChatDescription(chatId, description);
+                return ok({ descriptionSet: true });
+            }
+            case "ban": {
+                const chatId = resolveChatId(params.chat_id);
+                const userId = Number(params.user_id);
+                await state.bot.api.banChatMember(chatId, userId);
+                return ok({ banned: true, chatId, userId });
+            }
+            case "unban": {
+                const chatId = resolveChatId(params.chat_id);
+                const userId = Number(params.user_id);
+                await state.bot.api.unbanChatMember(chatId, userId, { only_if_banned: true });
+                return ok({ unbanned: true });
+            }
+            case "promote": {
+                const chatId = resolveChatId(params.chat_id);
+                const userId = Number(params.user_id);
+                const rights = params.rights ?? {};
+                await state.bot.api.promoteChatMember(chatId, userId, rights);
+                return ok({ promoted: true });
+            }
+            case "createForumTopic": {
+                const chatId = resolveChatId(params.chat_id);
+                const name = String(params.name);
+                const iconColor = params.icon_color != null ? Number(params.icon_color) : undefined;
+                const iconCustomEmojiId = params.icon_custom_emoji_id ? String(params.icon_custom_emoji_id) : undefined;
+                const result = await state.bot.api.createForumTopic(chatId, name, {
+                    icon_color: iconColor,
+                    icon_custom_emoji_id: iconCustomEmojiId,
+                });
+                return ok({ topicId: result.message_thread_id, name: result.name });
+            }
+            case "editForumTopic": {
+                const chatId = resolveChatId(params.chat_id);
+                const threadId = Number(params.message_thread_id);
+                await state.bot.api.editForumTopic(chatId, threadId, {
+                    name: params.name ? String(params.name) : undefined,
+                    icon_custom_emoji_id: params.icon_custom_emoji_id ? String(params.icon_custom_emoji_id) : undefined,
+                });
+                return ok({ edited: true });
+            }
+            case "closeForumTopic": {
+                const chatId = resolveChatId(params.chat_id);
+                const threadId = Number(params.message_thread_id);
+                await state.bot.api.closeForumTopic(chatId, threadId);
+                return ok({ closed: true });
+            }
+            case "reopenForumTopic": {
+                const chatId = resolveChatId(params.chat_id);
+                const threadId = Number(params.message_thread_id);
+                await state.bot.api.reopenForumTopic(chatId, threadId);
+                return ok({ reopened: true });
+            }
+            default: {
+                const unsupportedErr = new Error(`Unsupported action: ${action} on telegram`);
+                deps.logger.warn({
+                    channelType: "telegram",
+                    err: unsupportedErr,
+                    hint: `Action '${action}' is not supported by the Telegram adapter`,
+                    errorKind: "validation",
+                }, "Unsupported platform action");
+                return err(unsupportedErr);
+            }
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return err(new Error(`Telegram action '${action}' failed: ${message}`));
+    }
+}

package/node_modules/@comis/channels/dist/telegram/telegram-adapter/telegram-webhook.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Telegram webhook + HTML helpers.
+ *
+ * Pure utilities consumed by the lifecycle, inbound, and outbound leaves.
+ * No closure-captured state: all functions take their inputs as explicit
+ * parameters so they are trivial to test in isolation.
+ *
+ * Membership rationale:
+ *   - isTelegramHtmlParseError + sanitizeTelegramHtml: Telegram's HTML
+ *     parser is strict; outbound sends need to pre-sanitize bare `<` not
+ *     followed by a valid tag, and edits need to detect parse errors so
+ *     they can retry as plain text.
+ *   - sendWithThreadFallback: thread-not-found retry wrapper used by
+ *     outbound sends + sendAttachment for forum-topic fallback.
+ *   - shouldUseRunner: makes the polling vs webhook transport decision an
+ *     explicit pure function based on whether a webhook URL is configured.
+ *
+ * Per AGENTS.md no-cycles invariant: this leaf only imports from types
+ * and from @comis/core for ComisLogger; no sibling-leaf imports.
+ *
+ * @module
+ */
+import type { ComisLogger } from "@comis/core";
+import type { TelegramAdapterDeps } from "./telegram-adapter-types.js";
+/** Detect Telegram HTML parse errors that should trigger a plain-text fallback. */
+export declare function isTelegramHtmlParseError(err: unknown): boolean;
+/**
+ * Escape `<` characters that are NOT part of a valid Telegram HTML tag.
+ * Prevents Telegram from rejecting messages containing text like `<5%`
+ * or `<foo` that isn't a recognized HTML element.
+ *
+ * Already-valid tags (e.g. `<b>`, `</code>`, `<a href="...">`) pass through.
+ */
+export declare function sanitizeTelegramHtml(text: string): string;
+/**
+ * Retry a send operation without `message_thread_id` if the target forum
+ * topic has been deleted or closed. Non-thread errors re-throw.
+ *
+ * Design Section 5.4.8: The `sendFn` receives thread params as an argument
+ * so the wrapper can retry with `undefined` to strip them on fallback.
+ */
+export declare function sendWithThreadFallback<T>(sendFn: (threadParams?: {
+    message_thread_id: number;
+}) => Promise<T>, threadParams: {
+    message_thread_id: number;
+} | undefined, logger: ComisLogger): Promise<T>;
+/**
+ * Decide whether start() should boot the @grammyjs/runner polling loop
+ * or defer to webhook delivery.
+ *
+ * Returns `true` to start the runner (polling mode), `false` to skip it
+ * (webhook mode; the host process is expected to drive bot.handleUpdate
+ * externally).
+ */
+export declare function shouldUseRunner(deps: TelegramAdapterDeps): boolean;

package/node_modules/@comis/channels/dist/telegram/telegram-adapter/telegram-webhook.js

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: Telegram SDK boundary throws; consumed by adapter try/catch + inbound-pipeline catch.
+/**
+ * Telegram webhook + HTML helpers.
+ *
+ * Pure utilities consumed by the lifecycle, inbound, and outbound leaves.
+ * No closure-captured state: all functions take their inputs as explicit
+ * parameters so they are trivial to test in isolation.
+ *
+ * Membership rationale:
+ *   - isTelegramHtmlParseError + sanitizeTelegramHtml: Telegram's HTML
+ *     parser is strict; outbound sends need to pre-sanitize bare `<` not
+ *     followed by a valid tag, and edits need to detect parse errors so
+ *     they can retry as plain text.
+ *   - sendWithThreadFallback: thread-not-found retry wrapper used by
+ *     outbound sends + sendAttachment for forum-topic fallback.
+ *   - shouldUseRunner: makes the polling vs webhook transport decision an
+ *     explicit pure function based on whether a webhook URL is configured.
+ *
+ * Per AGENTS.md no-cycles invariant: this leaf only imports from types
+ * and from @comis/core for ComisLogger; no sibling-leaf imports.
+ *
+ * @module
+ */
+import { isTelegramThreadNotFoundError } from "../thread-context.js";
+// ---------------------------------------------------------------------------
+// HTML parse error detection
+// ---------------------------------------------------------------------------
+const TELEGRAM_PARSE_ERR_RE = /can't parse entities|find end of the entity/i;
+/** Detect Telegram HTML parse errors that should trigger a plain-text fallback. */
+export function isTelegramHtmlParseError(err) {
+    if (err instanceof Error)
+        return TELEGRAM_PARSE_ERR_RE.test(err.message);
+    return TELEGRAM_PARSE_ERR_RE.test(String(err));
+}
+// ---------------------------------------------------------------------------
+// HTML sanitization for Telegram
+// ---------------------------------------------------------------------------
+/** Telegram-supported HTML tags (case-insensitive). */
+const TELEGRAM_TAGS = new Set([
+    "b", "strong", "i", "em", "u", "ins", "s", "strike", "del",
+    "span", "tg-spoiler", "a", "tg-emoji",
+    "code", "pre", "blockquote",
+]);
+/**
+ * Escape `<` characters that are NOT part of a valid Telegram HTML tag.
+ * Prevents Telegram from rejecting messages containing text like `<5%`
+ * or `<foo` that isn't a recognized HTML element.
+ *
+ * Already-valid tags (e.g. `<b>`, `</code>`, `<a href="...">`) pass through.
+ */
+export function sanitizeTelegramHtml(text) {
+    return text.replace(/<(\/?)([a-zA-Z][a-zA-Z0-9-]*)\b[^>]*>|</g, (match, slash, tagName) => {
+        if (tagName && TELEGRAM_TAGS.has(tagName.toLowerCase()))
+            return match;
+        if (tagName)
+            return "&lt;" + match.slice(1); // unknown tag: escape the `<`
+        return "&lt;"; // bare `<` not followed by a tag pattern
+    });
+}
+// ---------------------------------------------------------------------------
+// Thread-not-found fallback
+// ---------------------------------------------------------------------------
+/**
+ * Retry a send operation without `message_thread_id` if the target forum
+ * topic has been deleted or closed. Non-thread errors re-throw.
+ *
+ * Design Section 5.4.8: The `sendFn` receives thread params as an argument
+ * so the wrapper can retry with `undefined` to strip them on fallback.
+ */
+export async function sendWithThreadFallback(sendFn, threadParams, logger) {
+    try {
+        return await sendFn(threadParams);
+    }
+    catch (err) {
+        if (threadParams && isTelegramThreadNotFoundError(err)) {
+            logger.warn({
+                channelType: "telegram",
+                messageThreadId: threadParams.message_thread_id,
+                err: err instanceof Error ? err : new Error(String(err)),
+                hint: "Topic may have been deleted; retrying without thread context",
+                errorKind: "platform",
+            }, "Thread-not-found fallback triggered");
+            return await sendFn(undefined);
+        }
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Transport decision (polling vs webhook)
+// ---------------------------------------------------------------------------
+/**
+ * Decide whether start() should boot the @grammyjs/runner polling loop
+ * or defer to webhook delivery.
+ *
+ * Returns `true` to start the runner (polling mode), `false` to skip it
+ * (webhook mode; the host process is expected to drive bot.handleUpdate
+ * externally).
+ */
+export function shouldUseRunner(deps) {
+    return !deps.webhookUrl;
+}

package/node_modules/@comis/channels/dist/telegram/telegram-plugin.d.ts

@@ -8,7 +8,7 @@
  */
 import type { ChannelPluginPort, MediaResolverPort } from "@comis/core";
 import { type Result } from "@comis/shared";
-import { type TelegramAdapterDeps } from "./telegram-adapter.js";
+import { type TelegramAdapterDeps } from "./telegram-adapter/index.js";
 /** Structural interface to avoid circular dep on @comis/skills. */
 interface SsrfFetcher {
     fetch(url: string): Promise<Result<{

package/node_modules/@comis/channels/dist/telegram/telegram-plugin.js

@@ -8,7 +8,7 @@
  * @module
  */
 import { ok } from "@comis/shared";
-import { createTelegramAdapter } from "./telegram-adapter.js";
+import { createTelegramAdapter } from "./telegram-adapter/index.js";
 import { createTelegramResolver } from "./telegram-resolver.js";
 /** Telegram platform capabilities (self-declared, validated at registration). */
 const CAPABILITIES = {

package/node_modules/@comis/channels/dist/telegram/telegram-resolver.js

@@ -12,7 +12,7 @@
  *
  * @module
  */
-import { sanitizeLogString } from "@comis/core";
+import { sanitizeLogString, systemNowMs } from "@comis/core";
 import { ok, err } from "@comis/shared";
 // ---------------------------------------------------------------------------
 // Factory
@@ -53,9 +53,9 @@ export function createTelegramResolver(deps) {
                 // Construct download URL
                 const downloadUrl = `https://api.telegram.org/file/bot${deps.botToken}/${file.file_path}`;
                 // Download via SSRF-guarded fetcher
-                const startMs = Date.now();
+                const startMs = systemNowMs();
                 const fetchResult = await deps.ssrfFetcher.fetch(downloadUrl);
-                const durationMs = Date.now() - startMs;
+                const durationMs = systemNowMs() - startMs;
                 if (!fetchResult.ok) {
                     deps.logger.warn({
                         fileId,

package/node_modules/@comis/channels/dist/whatsapp/credential-validator.js

@@ -9,7 +9,7 @@
  * @module
  */
 import { ok, err } from "@comis/shared";
-import { safePath } from "@comis/core";
+import { safePath, systemNowMs } from "@comis/core";
 import { constants } from "node:fs";
 import { access, mkdir, writeFile, unlink, readdir } from "node:fs/promises";
 import { createCredentialValidator } from "../shared/credential-validator-factory.js";
@@ -49,7 +49,7 @@ export const validateWhatsAppAuth = createCredentialValidator({
             }
         }
         // Check if directory is writable (create+delete a temp file)
-        const probe = safePath(authDir, `.wa-probe-${Date.now()}`);
+        const probe = safePath(authDir, `.wa-probe-${systemNowMs()}`);
         try {
             await writeFile(probe, "");
             await unlink(probe);

package/node_modules/@comis/channels/dist/whatsapp/message-mapper.js

@@ -19,6 +19,7 @@ import { randomUUID } from "node:crypto";
 import { extractJidPhone, isWhatsAppGroupJid } from "./jid-utils.js";
 import { buildWhatsAppAttachments } from "./media-handler.js";
 import { normalizeLocation } from "../shared/location-normalizer.js";
+import { systemNowMs } from "@comis/core";
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -28,7 +29,7 @@ import { normalizeLocation } from "../shared/location-normalizer.js";
  */
 function toMillis(ts) {
     if (ts == null) {
-        return Date.now();
+        return systemNowMs();
     }
     if (typeof ts === "number") {
         return ts * 1000;

package/node_modules/@comis/channels/dist/whatsapp/whatsapp-adapter.d.ts

@@ -13,12 +13,26 @@
  * @module
  */
 import type { ChannelPort } from "@comis/core";
-import type { ComisLogger } from "@comis/infra";
+import type { ComisLogger } from "@comis/core";
 import { type BaileysMessage } from "./message-mapper.js";
 export interface WhatsAppAdapterDeps {
     authDir: string;
     printQR?: boolean;
     logger: ComisLogger;
+    /**
+     * Optional WhatsApp WebSocket URL override (e.g.
+     * `ws://127.0.0.1:54324/ws/chat`). When set, Baileys' SocketConfig.
+     * waWebSocketUrl is set to this URL instead of the default
+     * `wss://web.whatsapp.com/ws/chat`. Production callers leave this
+     * undefined and Baileys uses its built-in default. Provides a wire-level
+     * seam for the E2E mock chat-platform fixture (test/e2e/mocks/whatsapp/).
+     *
+     * NOTE: this is the `apiRoot` field from ChannelEntrySchema (a single
+     * config key is documented to mean "the platform's primary backend
+     * endpoint" regardless of whether the underlying protocol is HTTP REST,
+     * WebSocket, or both). For WhatsApp/Baileys, that's the WebSocket URL.
+     */
+    apiRoot?: string;
 }
 export interface WhatsAppAdapterHandle extends ChannelPort {
     /** Look up a raw Baileys message by its message ID from the TTL-based cache. */