@poolzin/pool-bot 2026.2.0 → 2026.2.2

package/dist/auto-reply/command-auth.js

@@ -49,6 +49,64 @@ function normalizeAllowFromEntry(params) {
     });
     return normalized.filter((entry) => entry.trim().length > 0);
 }
+function resolveOwnerAllowFromList(params) {
+    const raw = params.allowFrom ?? params.cfg.commands?.ownerAllowFrom;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return [];
+    }
+    const filtered = [];
+    for (const entry of raw) {
+        const trimmed = String(entry ?? "").trim();
+        if (!trimmed)
+            continue;
+        const separatorIndex = trimmed.indexOf(":");
+        if (separatorIndex > 0) {
+            const prefix = trimmed.slice(0, separatorIndex);
+            const channel = normalizeAnyChannelId(prefix);
+            if (channel) {
+                if (params.providerId && channel !== params.providerId)
+                    continue;
+                const remainder = trimmed.slice(separatorIndex + 1).trim();
+                if (remainder)
+                    filtered.push(remainder);
+                continue;
+            }
+        }
+        filtered.push(trimmed);
+    }
+    return formatAllowFromList({
+        dock: params.dock,
+        cfg: params.cfg,
+        accountId: params.accountId,
+        allowFrom: filtered,
+    });
+}
+/**
+ * Resolves the commands.allowFrom list for a given provider.
+ * Returns the provider-specific list if defined, otherwise the "*" global list.
+ * Returns null if commands.allowFrom is not configured at all (fall back to channel allowFrom).
+ */
+function resolveCommandsAllowFromList(params) {
+    const { dock, cfg, accountId, providerId } = params;
+    const commandsAllowFrom = cfg.commands?.allowFrom;
+    if (!commandsAllowFrom || typeof commandsAllowFrom !== "object") {
+        return null; // Not configured, fall back to channel allowFrom
+    }
+    // Check provider-specific list first, then fall back to global "*"
+    const providerKey = providerId ?? "";
+    const providerList = commandsAllowFrom[providerKey];
+    const globalList = commandsAllowFrom["*"];
+    const rawList = Array.isArray(providerList) ? providerList : globalList;
+    if (!Array.isArray(rawList)) {
+        return null; // No applicable list found
+    }
+    return formatAllowFromList({
+        dock,
+        cfg,
+        accountId,
+        allowFrom: rawList,
+    });
+}
 function resolveSenderCandidates(params) {
     const { dock, cfg, accountId } = params;
     const candidates = [];
@@ -83,6 +141,13 @@ export function resolveCommandAuthorization(params) {
     const dock = providerId ? getChannelDock(providerId) : undefined;
     const from = (ctx.From ?? "").trim();
     const to = (ctx.To ?? "").trim();
+    // Check if commands.allowFrom is configured (separate command authorization)
+    const commandsAllowFromList = resolveCommandsAllowFromList({
+        dock,
+        cfg,
+        accountId: ctx.AccountId,
+        providerId,
+    });
     const allowFromRaw = dock?.config?.resolveAllowFrom
         ? dock.config.resolveAllowFrom({ cfg, accountId: ctx.AccountId })
         : [];
@@ -92,9 +157,23 @@ export function resolveCommandAuthorization(params) {
         accountId: ctx.AccountId,
         allowFrom: Array.isArray(allowFromRaw) ? allowFromRaw : [],
     });
+    const configOwnerAllowFromList = resolveOwnerAllowFromList({
+        dock,
+        cfg,
+        accountId: ctx.AccountId,
+        providerId,
+        allowFrom: cfg.commands?.ownerAllowFrom,
+    });
+    const contextOwnerAllowFromList = resolveOwnerAllowFromList({
+        dock,
+        cfg,
+        accountId: ctx.AccountId,
+        providerId,
+        allowFrom: ctx.OwnerAllowFrom,
+    });
     const allowAll = allowFromList.length === 0 || allowFromList.some((entry) => entry.trim() === "*");
-    const ownerCandidates = allowAll ? [] : allowFromList.filter((entry) => entry !== "*");
-    if (!allowAll && ownerCandidates.length === 0 && to) {
+    const ownerCandidatesForCommands = allowAll ? [] : allowFromList.filter((entry) => entry !== "*");
+    if (!allowAll && ownerCandidatesForCommands.length === 0 && to) {
         const normalizedTo = normalizeAllowFromEntry({
             dock,
             cfg,
@@ -102,9 +181,18 @@ export function resolveCommandAuthorization(params) {
             value: to,
         });
         if (normalizedTo.length > 0)
-            ownerCandidates.push(...normalizedTo);
+            ownerCandidatesForCommands.push(...normalizedTo);
     }
-    const ownerList = Array.from(new Set(ownerCandidates));
+    const ownerAllowAll = configOwnerAllowFromList.some((entry) => entry.trim() === "*");
+    const explicitOwners = configOwnerAllowFromList.filter((entry) => entry !== "*");
+    const explicitOverrides = contextOwnerAllowFromList.filter((entry) => entry !== "*");
+    const ownerList = Array.from(new Set(explicitOwners.length > 0
+        ? explicitOwners
+        : ownerAllowAll
+            ? []
+            : explicitOverrides.length > 0
+                ? explicitOverrides
+                : ownerCandidatesForCommands));
     const senderCandidates = resolveSenderCandidates({
         dock,
         providerId,
@@ -117,14 +205,41 @@ export function resolveCommandAuthorization(params) {
     const matchedSender = ownerList.length
         ? senderCandidates.find((candidate) => ownerList.includes(candidate))
         : undefined;
+    const matchedCommandOwner = ownerCandidatesForCommands.length
+        ? senderCandidates.find((candidate) => ownerCandidatesForCommands.includes(candidate))
+        : undefined;
     const senderId = matchedSender ?? senderCandidates[0];
     const enforceOwner = Boolean(dock?.commands?.enforceOwnerForCommands);
-    const isOwner = !enforceOwner || allowAll || ownerList.length === 0 || Boolean(matchedSender);
-    const isAuthorizedSender = commandAuthorized && isOwner;
+    const senderIsOwner = Boolean(matchedSender);
+    const ownerAllowlistConfigured = ownerAllowAll || explicitOwners.length > 0;
+    const requireOwner = enforceOwner || ownerAllowlistConfigured;
+    const isOwnerForCommands = !requireOwner
+        ? true
+        : ownerAllowAll
+            ? true
+            : ownerAllowlistConfigured
+                ? senderIsOwner
+                : allowAll || ownerCandidatesForCommands.length === 0 || Boolean(matchedCommandOwner);
+    // If commands.allowFrom is configured, use it for command authorization
+    // Otherwise, fall back to existing behavior (channel allowFrom + owner checks)
+    let isAuthorizedSender;
+    if (commandsAllowFromList !== null) {
+        // commands.allowFrom is configured - use it for authorization
+        const commandsAllowAll = commandsAllowFromList.some((entry) => entry.trim() === "*");
+        const matchedCommandsAllowFrom = commandsAllowFromList.length
+            ? senderCandidates.find((candidate) => commandsAllowFromList.includes(candidate))
+            : undefined;
+        isAuthorizedSender = commandsAllowAll || Boolean(matchedCommandsAllowFrom);
+    }
+    else {
+        // Fall back to existing behavior
+        isAuthorizedSender = commandAuthorized && isOwnerForCommands;
+    }
     return {
         providerId,
         ownerList,
         senderId: senderId || undefined,
+        senderIsOwner,
         isAuthorizedSender,
         from: from || undefined,
         to: to || undefined,

package/dist/auto-reply/envelope.js

@@ -1,6 +1,18 @@
 import { resolveUserTimezone } from "../agents/date-time.js";
 import { normalizeChatType } from "../channels/chat-type.js";
 import { resolveSenderLabel } from "../channels/sender-label.js";
+import { resolveTimezone, formatUtcTimestamp, formatZonedTimestamp, } from "../infra/format-time/format-datetime.js";
+import { formatTimeAgo } from "../infra/format-time/format-relative.js";
+function sanitizeEnvelopeHeaderPart(value) {
+    // Header parts are metadata and must not be able to break the bracketed prefix.
+    // Keep ASCII; collapse newlines/whitespace; neutralize brackets.
+    return value
+        .replace(/\r\n|\r|\n/g, " ")
+        .replaceAll("[", "(")
+        .replaceAll("]", ")")
+        .replace(/\s+/g, " ")
+        .trim();
+}
 export function resolveEnvelopeFormatOptions(cfg) {
     const defaults = cfg?.agents?.defaults;
     return {
@@ -20,125 +32,104 @@ function normalizeEnvelopeOptions(options) {
         userTimezone: options?.userTimezone,
     };
 }
-function resolveExplicitTimezone(value) {
-    try {
-        new Intl.DateTimeFormat("en-US", { timeZone: value }).format(new Date());
-        return value;
-    }
-    catch {
-        return undefined;
-    }
-}
 function resolveEnvelopeTimezone(options) {
     const trimmed = options.timezone?.trim();
-    if (!trimmed)
+    if (!trimmed) {
         return { mode: "local" };
+    }
     const lowered = trimmed.toLowerCase();
-    if (lowered === "utc" || lowered === "gmt")
+    if (lowered === "utc" || lowered === "gmt") {
         return { mode: "utc" };
-    if (lowered === "local" || lowered === "host")
+    }
+    if (lowered === "local" || lowered === "host") {
         return { mode: "local" };
+    }
     if (lowered === "user") {
         return { mode: "iana", timeZone: resolveUserTimezone(options.userTimezone) };
     }
-    const explicit = resolveExplicitTimezone(trimmed);
+    const explicit = resolveTimezone(trimmed);
     return explicit ? { mode: "iana", timeZone: explicit } : { mode: "utc" };
 }
-function formatUtcTimestamp(date) {
-    const yyyy = String(date.getUTCFullYear()).padStart(4, "0");
-    const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
-    const dd = String(date.getUTCDate()).padStart(2, "0");
-    const hh = String(date.getUTCHours()).padStart(2, "0");
-    const min = String(date.getUTCMinutes()).padStart(2, "0");
-    return `${yyyy}-${mm}-${dd}T${hh}:${min}Z`;
-}
-function formatZonedTimestamp(date, timeZone) {
-    const parts = new Intl.DateTimeFormat("en-US", {
-        timeZone,
-        year: "numeric",
-        month: "2-digit",
-        day: "2-digit",
-        hour: "2-digit",
-        minute: "2-digit",
-        hourCycle: "h23",
-        timeZoneName: "short",
-    }).formatToParts(date);
-    const pick = (type) => parts.find((part) => part.type === type)?.value;
-    const yyyy = pick("year");
-    const mm = pick("month");
-    const dd = pick("day");
-    const hh = pick("hour");
-    const min = pick("minute");
-    const tz = [...parts]
-        .reverse()
-        .find((part) => part.type === "timeZoneName")
-        ?.value?.trim();
-    if (!yyyy || !mm || !dd || !hh || !min)
-        return undefined;
-    return `${yyyy}-${mm}-${dd} ${hh}:${min}${tz ? ` ${tz}` : ""}`;
-}
 function formatTimestamp(ts, options) {
-    if (!ts)
+    if (!ts) {
         return undefined;
+    }
     const resolved = normalizeEnvelopeOptions(options);
-    if (!resolved.includeTimestamp)
+    if (!resolved.includeTimestamp) {
         return undefined;
+    }
     const date = ts instanceof Date ? ts : new Date(ts);
-    if (Number.isNaN(date.getTime()))
+    if (Number.isNaN(date.getTime())) {
         return undefined;
+    }
     const zone = resolveEnvelopeTimezone(resolved);
-    if (zone.mode === "utc")
-        return formatUtcTimestamp(date);
-    if (zone.mode === "local")
-        return formatZonedTimestamp(date);
-    return formatZonedTimestamp(date, zone.timeZone);
-}
-function formatElapsedTime(currentMs, previousMs) {
-    const elapsedMs = currentMs - previousMs;
-    if (!Number.isFinite(elapsedMs) || elapsedMs < 0)
+    // Include a weekday prefix so models do not need to derive DOW from the date
+    // (small models are notoriously unreliable at that).
+    const weekday = (() => {
+        try {
+            if (zone.mode === "utc") {
+                return new Intl.DateTimeFormat("en-US", { timeZone: "UTC", weekday: "short" }).format(date);
+            }
+            if (zone.mode === "local") {
+                return new Intl.DateTimeFormat("en-US", { weekday: "short" }).format(date);
+            }
+            return new Intl.DateTimeFormat("en-US", { timeZone: zone.timeZone, weekday: "short" }).format(date);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const formatted = zone.mode === "utc"
+        ? formatUtcTimestamp(date)
+        : zone.mode === "local"
+            ? formatZonedTimestamp(date)
+            : formatZonedTimestamp(date, { timeZone: zone.timeZone });
+    if (!formatted) {
         return undefined;
-    const seconds = Math.floor(elapsedMs / 1000);
-    if (seconds < 60)
-        return `${seconds}s`;
-    const minutes = Math.floor(seconds / 60);
-    if (minutes < 60)
-        return `${minutes}m`;
-    const hours = Math.floor(minutes / 60);
-    if (hours < 24)
-        return `${hours}h`;
-    const days = Math.floor(hours / 24);
-    return `${days}d`;
+    }
+    return weekday ? `${weekday} ${formatted}` : formatted;
 }
 export function formatAgentEnvelope(params) {
-    const channel = params.channel?.trim() || "Channel";
+    const channel = sanitizeEnvelopeHeaderPart(params.channel?.trim() || "Channel");
     const parts = [channel];
     const resolved = normalizeEnvelopeOptions(params.envelope);
-    const elapsed = resolved.includeElapsed && params.timestamp && params.previousTimestamp
-        ? formatElapsedTime(params.timestamp instanceof Date ? params.timestamp.getTime() : params.timestamp, params.previousTimestamp instanceof Date
+    let elapsed;
+    if (resolved.includeElapsed && params.timestamp && params.previousTimestamp) {
+        const currentMs = params.timestamp instanceof Date ? params.timestamp.getTime() : params.timestamp;
+        const previousMs = params.previousTimestamp instanceof Date
             ? params.previousTimestamp.getTime()
-            : params.previousTimestamp)
-        : undefined;
+            : params.previousTimestamp;
+        const elapsedMs = currentMs - previousMs;
+        elapsed =
+            Number.isFinite(elapsedMs) && elapsedMs >= 0
+                ? formatTimeAgo(elapsedMs, { suffix: false })
+                : undefined;
+    }
     if (params.from?.trim()) {
-        const from = params.from.trim();
+        const from = sanitizeEnvelopeHeaderPart(params.from.trim());
         parts.push(elapsed ? `${from} +${elapsed}` : from);
     }
     else if (elapsed) {
         parts.push(`+${elapsed}`);
     }
-    if (params.host?.trim())
-        parts.push(params.host.trim());
-    if (params.ip?.trim())
-        parts.push(params.ip.trim());
+    if (params.host?.trim()) {
+        parts.push(sanitizeEnvelopeHeaderPart(params.host.trim()));
+    }
+    if (params.ip?.trim()) {
+        parts.push(sanitizeEnvelopeHeaderPart(params.ip.trim()));
+    }
     const ts = formatTimestamp(params.timestamp, resolved);
-    if (ts)
+    if (ts) {
         parts.push(ts);
+    }
     const header = `[${parts.join(" ")}]`;
     return `${header} ${params.body}`;
 }
 export function formatInboundEnvelope(params) {
     const chatType = normalizeChatType(params.chatType);
     const isDirect = !chatType || chatType === "direct";
-    const resolvedSender = params.senderLabel?.trim() || resolveSenderLabel(params.sender ?? {});
+    const resolvedSenderRaw = params.senderLabel?.trim() || resolveSenderLabel(params.sender ?? {});
+    const resolvedSender = resolvedSenderRaw ? sanitizeEnvelopeHeaderPart(resolvedSenderRaw) : "";
     const body = !isDirect && resolvedSender ? `${resolvedSender}: ${params.body}` : params.body;
     return formatAgentEnvelope({
         channel: params.channel,
@@ -158,8 +149,9 @@ export function formatInboundFromLabel(params) {
     }
     const directLabel = params.directLabel.trim();
     const directId = params.directId?.trim();
-    if (!directId || directId === directLabel)
+    if (!directId || directId === directLabel) {
         return directLabel;
+    }
     return `${directLabel} id:${directId}`;
 }
 export function formatThreadStarterEnvelope(params) {

package/dist/auto-reply/reply/commands-compact.js

@@ -70,6 +70,7 @@ export const handleCompactCommand = async (params) => {
             defaultLevel: "off",
         },
         customInstructions,
+        senderIsOwner: params.command.senderIsOwner,
         ownerNumbers: params.command.ownerList.length > 0 ? params.command.ownerList : undefined,
     });
     const compactLabel = result.ok

package/dist/auto-reply/reply/commands-context-report.js

@@ -75,6 +75,7 @@ async function resolveContextReport(params) {
                 groupChannel: params.sessionEntry?.groupChannel ?? undefined,
                 groupSpace: params.sessionEntry?.space ?? undefined,
                 spawnedBy: params.sessionEntry?.spawnedBy ?? undefined,
+                senderIsOwner: params.command.senderIsOwner,
                 modelProvider: params.provider,
                 modelId: params.model,
             });

package/dist/auto-reply/reply/commands-context.js

@@ -18,6 +18,7 @@ export function buildCommandContext(params) {
         channel,
         channelId: auth.providerId,
         ownerList: auth.ownerList,
+        senderIsOwner: auth.senderIsOwner,
         isAuthorizedSender: auth.isAuthorizedSender,
         senderId: auth.senderId,
         abortKey,

package/dist/auto-reply/reply/commands-models.js

@@ -1,75 +1,28 @@
 import { loadModelCatalog } from "../../agents/model-catalog.js";
 import { buildAllowedModelSet, buildModelAliasIndex, normalizeProviderId, resolveConfiguredModelRef, resolveModelRefFromString, } from "../../agents/model-selection.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../../agents/defaults.js";
+import { buildModelsKeyboard, buildProviderKeyboard, calculateTotalPages, getModelsPageSize, } from "../../telegram/model-buttons.js";
 const PAGE_SIZE_DEFAULT = 20;
 const PAGE_SIZE_MAX = 100;
-function formatProviderLine(params) {
-    return `- ${params.provider} (${params.count})`;
-}
-function parseModelsArgs(raw) {
-    const trimmed = raw.trim();
-    if (!trimmed) {
-        return { page: 1, pageSize: PAGE_SIZE_DEFAULT, all: false };
-    }
-    const tokens = trimmed.split(/\s+/g).filter(Boolean);
-    const provider = tokens[0]?.trim();
-    let page = 1;
-    let all = false;
-    for (const token of tokens.slice(1)) {
-        const lower = token.toLowerCase();
-        if (lower === "all" || lower === "--all") {
-            all = true;
-            continue;
-        }
-        if (lower.startsWith("page=")) {
-            const value = Number.parseInt(lower.slice("page=".length), 10);
-            if (Number.isFinite(value) && value > 0)
-                page = value;
-            continue;
-        }
-        if (/^[0-9]+$/.test(lower)) {
-            const value = Number.parseInt(lower, 10);
-            if (Number.isFinite(value) && value > 0)
-                page = value;
-        }
-    }
-    let pageSize = PAGE_SIZE_DEFAULT;
-    for (const token of tokens) {
-        const lower = token.toLowerCase();
-        if (lower.startsWith("limit=") || lower.startsWith("size=")) {
-            const rawValue = lower.slice(lower.indexOf("=") + 1);
-            const value = Number.parseInt(rawValue, 10);
-            if (Number.isFinite(value) && value > 0)
-                pageSize = Math.min(PAGE_SIZE_MAX, value);
-        }
-    }
-    return {
-        provider: provider ? normalizeProviderId(provider) : undefined,
-        page,
-        pageSize,
-        all,
-    };
-}
-export async function resolveModelsCommandReply(params) {
-    const body = params.commandBodyNormalized.trim();
-    if (!body.startsWith("/models"))
-        return null;
-    const argText = body.replace(/^\/models\b/i, "").trim();
-    const { provider, page, pageSize, all } = parseModelsArgs(argText);
+/**
+ * Build provider/model data from config and catalog.
+ * Exported for reuse by callback handlers.
+ */
+export async function buildModelsProviderData(cfg) {
     const resolvedDefault = resolveConfiguredModelRef({
-        cfg: params.cfg,
+        cfg,
         defaultProvider: DEFAULT_PROVIDER,
         defaultModel: DEFAULT_MODEL,
     });
-    const catalog = await loadModelCatalog({ config: params.cfg });
+    const catalog = await loadModelCatalog({ config: cfg });
     const allowed = buildAllowedModelSet({
-        cfg: params.cfg,
+        cfg,
         catalog,
         defaultProvider: resolvedDefault.provider,
         defaultModel: resolvedDefault.model,
     });
     const aliasIndex = buildModelAliasIndex({
-        cfg: params.cfg,
+        cfg,
         defaultProvider: resolvedDefault.provider,
     });
     const byProvider = new Map();
@@ -93,7 +46,7 @@ export async function resolveModelsCommandReply(params) {
         add(resolved.ref.provider, resolved.ref.model);
     };
     const addModelConfigEntries = () => {
-        const modelConfig = params.cfg.agents?.defaults?.model;
+        const modelConfig = cfg.agents?.defaults?.model;
         if (typeof modelConfig === "string") {
             addRawModelRef(modelConfig);
         }
@@ -103,7 +56,7 @@ export async function resolveModelsCommandReply(params) {
                 addRawModelRef(fallback);
             }
         }
-        const imageConfig = params.cfg.agents?.defaults?.imageModel;
+        const imageConfig = cfg.agents?.defaults?.imageModel;
         if (typeof imageConfig === "string") {
             addRawModelRef(imageConfig);
         }
@@ -118,7 +71,7 @@ export async function resolveModelsCommandReply(params) {
         add(entry.provider, entry.id);
     }
     // Include config-only allowlist keys that aren't in the curated catalog.
-    for (const raw of Object.keys(params.cfg.agents?.defaults?.models ?? {})) {
+    for (const raw of Object.keys(cfg.agents?.defaults?.models ?? {})) {
         addRawModelRef(raw);
     }
     // Ensure configured defaults/fallbacks/image models show up even when the
@@ -126,7 +79,79 @@ export async function resolveModelsCommandReply(params) {
     add(resolvedDefault.provider, resolvedDefault.model);
     addModelConfigEntries();
     const providers = [...byProvider.keys()].sort();
+    return { byProvider, providers, resolvedDefault };
+}
+function formatProviderLine(params) {
+    return `- ${params.provider} (${params.count})`;
+}
+function parseModelsArgs(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return { page: 1, pageSize: PAGE_SIZE_DEFAULT, all: false };
+    }
+    const tokens = trimmed.split(/\s+/g).filter(Boolean);
+    const provider = tokens[0]?.trim();
+    let page = 1;
+    let all = false;
+    for (const token of tokens.slice(1)) {
+        const lower = token.toLowerCase();
+        if (lower === "all" || lower === "--all") {
+            all = true;
+            continue;
+        }
+        if (lower.startsWith("page=")) {
+            const value = Number.parseInt(lower.slice("page=".length), 10);
+            if (Number.isFinite(value) && value > 0)
+                page = value;
+            continue;
+        }
+        if (/^[0-9]+$/.test(lower)) {
+            const value = Number.parseInt(lower, 10);
+            if (Number.isFinite(value) && value > 0)
+                page = value;
+        }
+    }
+    let pageSize = PAGE_SIZE_DEFAULT;
+    for (const token of tokens) {
+        const lower = token.toLowerCase();
+        if (lower.startsWith("limit=") || lower.startsWith("size=")) {
+            const rawValue = lower.slice(lower.indexOf("=") + 1);
+            const value = Number.parseInt(rawValue, 10);
+            if (Number.isFinite(value) && value > 0)
+                pageSize = Math.min(PAGE_SIZE_MAX, value);
+        }
+    }
+    return {
+        provider: provider ? normalizeProviderId(provider) : undefined,
+        page,
+        pageSize,
+        all,
+    };
+}
+export async function resolveModelsCommandReply(params) {
+    const body = params.commandBodyNormalized.trim();
+    if (!body.startsWith("/models"))
+        return null;
+    const argText = body.replace(/^\/models\b/i, "").trim();
+    const { provider, page, pageSize, all } = parseModelsArgs(argText);
+    const { byProvider, providers } = await buildModelsProviderData(params.cfg);
+    const isTelegram = params.surface === "telegram";
+    // Provider list (no provider specified)
     if (!provider) {
+        // For Telegram: show buttons if there are providers
+        if (isTelegram && providers.length > 0) {
+            const providerInfos = providers.map((p) => ({
+                id: p,
+                count: byProvider.get(p)?.size ?? 0,
+            }));
+            const buttons = buildProviderKeyboard(providerInfos);
+            const text = "Select a provider:";
+            return {
+                text,
+                channelData: { telegram: { buttons } },
+            };
+        }
+        // Text fallback for non-Telegram surfaces
         const lines = [
             "Providers:",
             ...providers.map((p) => formatProviderLine({ provider: p, count: byProvider.get(p)?.size ?? 0 })),
@@ -158,6 +183,26 @@ export async function resolveModelsCommandReply(params) {
         ];
         return { text: lines.join("\n") };
     }
+    // For Telegram: use button-based model list with inline keyboard pagination
+    if (isTelegram) {
+        const telegramPageSize = getModelsPageSize();
+        const totalPages = calculateTotalPages(total, telegramPageSize);
+        const safePage = Math.max(1, Math.min(page, totalPages));
+        const buttons = buildModelsKeyboard({
+            provider,
+            models,
+            currentModel: params.currentModel,
+            currentPage: safePage,
+            totalPages,
+            pageSize: telegramPageSize,
+        });
+        const text = `Models (${provider}) — ${total} available`;
+        return {
+            text,
+            channelData: { telegram: { buttons } },
+        };
+    }
+    // Text fallback for non-Telegram surfaces
     const effectivePageSize = all ? total : pageSize;
     const pageCount = effectivePageSize > 0 ? Math.ceil(total / effectivePageSize) : 1;
     const safePage = all ? 1 : Math.max(1, Math.min(page, pageCount));
@@ -194,6 +239,8 @@ export const handleModelsCommand = async (params, allowTextCommands) => {
     const reply = await resolveModelsCommandReply({
         cfg: params.cfg,
         commandBodyNormalized: params.command.commandBodyNormalized,
+        surface: params.ctx.Surface,
+        currentModel: params.model ? `${params.provider}/${params.model}` : undefined,
     });
     if (!reply)
         return null;