agiagent-dev 2026.1.30

package/dist/telegram/sticker-cache.js

@@ -0,0 +1,204 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveApiKeyForProvider } from "../agents/model-auth.js";
+import { findModelInCatalog, loadModelCatalog, modelSupportsVision, } from "../agents/model-catalog.js";
+import { resolveDefaultModelForAgent } from "../agents/model-selection.js";
+import { STATE_DIR } from "../config/paths.js";
+import { logVerbose } from "../globals.js";
+import { loadJsonFile, saveJsonFile } from "../infra/json-file.js";
+import { resolveAutoImageModel } from "../media-understanding/runner.js";
+const CACHE_FILE = path.join(STATE_DIR, "telegram", "sticker-cache.json");
+const CACHE_VERSION = 1;
+function loadCache() {
+    const data = loadJsonFile(CACHE_FILE);
+    if (!data || typeof data !== "object") {
+        return { version: CACHE_VERSION, stickers: {} };
+    }
+    const cache = data;
+    if (cache.version !== CACHE_VERSION) {
+        // Future: handle migration if needed
+        return { version: CACHE_VERSION, stickers: {} };
+    }
+    return cache;
+}
+function saveCache(cache) {
+    saveJsonFile(CACHE_FILE, cache);
+}
+/**
+ * Get a cached sticker by its unique ID.
+ */
+export function getCachedSticker(fileUniqueId) {
+    const cache = loadCache();
+    return cache.stickers[fileUniqueId] ?? null;
+}
+/**
+ * Add or update a sticker in the cache.
+ */
+export function cacheSticker(sticker) {
+    const cache = loadCache();
+    cache.stickers[sticker.fileUniqueId] = sticker;
+    saveCache(cache);
+}
+/**
+ * Search cached stickers by text query (fuzzy match on description + emoji + setName).
+ */
+export function searchStickers(query, limit = 10) {
+    const cache = loadCache();
+    const queryLower = query.toLowerCase();
+    const results = [];
+    for (const sticker of Object.values(cache.stickers)) {
+        let score = 0;
+        const descLower = sticker.description.toLowerCase();
+        // Exact substring match in description
+        if (descLower.includes(queryLower)) {
+            score += 10;
+        }
+        // Word-level matching
+        const queryWords = queryLower.split(/\s+/).filter(Boolean);
+        const descWords = descLower.split(/\s+/);
+        for (const qWord of queryWords) {
+            if (descWords.some((dWord) => dWord.includes(qWord))) {
+                score += 5;
+            }
+        }
+        // Emoji match
+        if (sticker.emoji && query.includes(sticker.emoji)) {
+            score += 8;
+        }
+        // Set name match
+        if (sticker.setName?.toLowerCase().includes(queryLower)) {
+            score += 3;
+        }
+        if (score > 0) {
+            results.push({ sticker, score });
+        }
+    }
+    return results
+        .toSorted((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map((r) => r.sticker);
+}
+/**
+ * Get all cached stickers (for debugging/listing).
+ */
+export function getAllCachedStickers() {
+    const cache = loadCache();
+    return Object.values(cache.stickers);
+}
+/**
+ * Get cache statistics.
+ */
+export function getCacheStats() {
+    const cache = loadCache();
+    const stickers = Object.values(cache.stickers);
+    if (stickers.length === 0) {
+        return { count: 0 };
+    }
+    const sorted = [...stickers].toSorted((a, b) => new Date(a.cachedAt).getTime() - new Date(b.cachedAt).getTime());
+    return {
+        count: stickers.length,
+        oldestAt: sorted[0]?.cachedAt,
+        newestAt: sorted[sorted.length - 1]?.cachedAt,
+    };
+}
+const STICKER_DESCRIPTION_PROMPT = "Describe this sticker image in 1-2 sentences. Focus on what the sticker depicts (character, object, action, emotion). Be concise and objective.";
+const VISION_PROVIDERS = ["openai", "anthropic", "google", "minimax"];
+/**
+ * Describe a sticker image using vision API.
+ * Auto-detects an available vision provider based on configured API keys.
+ * Returns null if no vision provider is available.
+ */
+export async function describeStickerImage(params) {
+    const { imagePath, cfg, agentDir, agentId } = params;
+    const defaultModel = resolveDefaultModelForAgent({ cfg, agentId });
+    let activeModel = undefined;
+    let catalog = [];
+    try {
+        catalog = await loadModelCatalog({ config: cfg });
+        const entry = findModelInCatalog(catalog, defaultModel.provider, defaultModel.model);
+        const supportsVision = modelSupportsVision(entry);
+        if (supportsVision) {
+            activeModel = { provider: defaultModel.provider, model: defaultModel.model };
+        }
+    }
+    catch {
+        // Ignore catalog failures; fall back to auto selection.
+    }
+    const hasProviderKey = async (provider) => {
+        try {
+            await resolveApiKeyForProvider({ provider, cfg, agentDir });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const selectCatalogModel = (provider) => {
+        const entries = catalog.filter((entry) => entry.provider.toLowerCase() === provider.toLowerCase() && modelSupportsVision(entry));
+        if (entries.length === 0) {
+            return undefined;
+        }
+        const defaultId = provider === "openai"
+            ? "gpt-5-mini"
+            : provider === "anthropic"
+                ? "claude-opus-4-5"
+                : provider === "google"
+                    ? "gemini-3-flash-preview"
+                    : "MiniMax-VL-01";
+        const preferred = entries.find((entry) => entry.id === defaultId);
+        return preferred ?? entries[0];
+    };
+    let resolved = null;
+    if (activeModel &&
+        VISION_PROVIDERS.includes(activeModel.provider) &&
+        (await hasProviderKey(activeModel.provider))) {
+        resolved = activeModel;
+    }
+    if (!resolved) {
+        for (const provider of VISION_PROVIDERS) {
+            if (!(await hasProviderKey(provider))) {
+                continue;
+            }
+            const entry = selectCatalogModel(provider);
+            if (entry) {
+                resolved = { provider, model: entry.id };
+                break;
+            }
+        }
+    }
+    if (!resolved) {
+        resolved = await resolveAutoImageModel({
+            cfg,
+            agentDir,
+            activeModel,
+        });
+    }
+    if (!resolved?.model) {
+        logVerbose("telegram: no vision provider available for sticker description");
+        return null;
+    }
+    const { provider, model } = resolved;
+    logVerbose(`telegram: describing sticker with ${provider}/${model}`);
+    try {
+        const buffer = await fs.readFile(imagePath);
+        // Dynamic import to avoid circular dependency
+        const { describeImageWithModel } = await import("../media-understanding/providers/image.js");
+        const result = await describeImageWithModel({
+            buffer,
+            fileName: "sticker.webp",
+            mime: "image/webp",
+            prompt: STICKER_DESCRIPTION_PROMPT,
+            cfg,
+            agentDir: agentDir ?? "",
+            provider,
+            model,
+            maxTokens: 150,
+            timeoutMs: 30000,
+        });
+        return result.text;
+    }
+    catch (err) {
+        logVerbose(`telegram: failed to describe sticker: ${String(err)}`);
+        return null;
+    }
+}

package/dist/telegram/targets.d.ts

@@ -0,0 +1,14 @@
+export type TelegramTarget = {
+    chatId: string;
+    messageThreadId?: number;
+};
+export declare function stripTelegramInternalPrefixes(to: string): string;
+/**
+ * Parse a Telegram delivery target into chatId and optional topic/thread ID.
+ *
+ * Supported formats:
+ * - `chatId` (plain chat ID, t.me link, @username, or internal prefixes like `telegram:...`)
+ * - `chatId:topicId` (numeric topic/thread ID)
+ * - `chatId:topic:topicId` (explicit topic marker; preferred)
+ */
+export declare function parseTelegramTarget(to: string): TelegramTarget;

package/dist/telegram/targets.js

@@ -0,0 +1,47 @@
+export function stripTelegramInternalPrefixes(to) {
+    let trimmed = to.trim();
+    let strippedTelegramPrefix = false;
+    while (true) {
+        const next = (() => {
+            if (/^(telegram|tg):/i.test(trimmed)) {
+                strippedTelegramPrefix = true;
+                return trimmed.replace(/^(telegram|tg):/i, "").trim();
+            }
+            // Legacy internal form: `telegram:group:<id>` (still emitted by session keys).
+            if (strippedTelegramPrefix && /^group:/i.test(trimmed)) {
+                return trimmed.replace(/^group:/i, "").trim();
+            }
+            return trimmed;
+        })();
+        if (next === trimmed) {
+            return trimmed;
+        }
+        trimmed = next;
+    }
+}
+/**
+ * Parse a Telegram delivery target into chatId and optional topic/thread ID.
+ *
+ * Supported formats:
+ * - `chatId` (plain chat ID, t.me link, @username, or internal prefixes like `telegram:...`)
+ * - `chatId:topicId` (numeric topic/thread ID)
+ * - `chatId:topic:topicId` (explicit topic marker; preferred)
+ */
+export function parseTelegramTarget(to) {
+    const normalized = stripTelegramInternalPrefixes(to);
+    const topicMatch = /^(.+?):topic:(\d+)$/.exec(normalized);
+    if (topicMatch) {
+        return {
+            chatId: topicMatch[1],
+            messageThreadId: Number.parseInt(topicMatch[2], 10),
+        };
+    }
+    const colonMatch = /^(.+):(\d+)$/.exec(normalized);
+    if (colonMatch) {
+        return {
+            chatId: colonMatch[1],
+            messageThreadId: Number.parseInt(colonMatch[2], 10),
+        };
+    }
+    return { chatId: normalized };
+}

package/dist/telegram/token.d.ts

@@ -0,0 +1,13 @@
+import type { AGIAgentConfig } from "../config/config.js";
+export type TelegramTokenSource = "env" | "tokenFile" | "config" | "none";
+export type TelegramTokenResolution = {
+    token: string;
+    source: TelegramTokenSource;
+};
+type ResolveTelegramTokenOpts = {
+    envToken?: string | null;
+    accountId?: string | null;
+    logMissingFile?: (message: string) => void;
+};
+export declare function resolveTelegramToken(cfg?: AGIAgentConfig, opts?: ResolveTelegramTokenOpts): TelegramTokenResolution;
+export {};

package/dist/telegram/token.js

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../routing/session-key.js";
+export function resolveTelegramToken(cfg, opts = {}) {
+    const accountId = normalizeAccountId(opts.accountId);
+    const telegramCfg = cfg?.channels?.telegram;
+    // Account IDs are normalized for routing (e.g. lowercased). Config keys may not
+    // be normalized, so resolve per-account config by matching normalized IDs.
+    const resolveAccountCfg = (id) => {
+        const accounts = telegramCfg?.accounts;
+        if (!accounts || typeof accounts !== "object" || Array.isArray(accounts)) {
+            return undefined;
+        }
+        // Direct hit (already normalized key)
+        const direct = accounts[id];
+        if (direct) {
+            return direct;
+        }
+        // Fallback: match by normalized key
+        const matchKey = Object.keys(accounts).find((key) => normalizeAccountId(key) === id);
+        return matchKey ? accounts[matchKey] : undefined;
+    };
+    const accountCfg = resolveAccountCfg(accountId !== DEFAULT_ACCOUNT_ID ? accountId : DEFAULT_ACCOUNT_ID);
+    const accountTokenFile = accountCfg?.tokenFile?.trim();
+    if (accountTokenFile) {
+        if (!fs.existsSync(accountTokenFile)) {
+            opts.logMissingFile?.(`channels.telegram.accounts.${accountId}.tokenFile not found: ${accountTokenFile}`);
+            return { token: "", source: "none" };
+        }
+        try {
+            const token = fs.readFileSync(accountTokenFile, "utf-8").trim();
+            if (token) {
+                return { token, source: "tokenFile" };
+            }
+        }
+        catch (err) {
+            opts.logMissingFile?.(`channels.telegram.accounts.${accountId}.tokenFile read failed: ${String(err)}`);
+            return { token: "", source: "none" };
+        }
+        return { token: "", source: "none" };
+    }
+    const accountToken = accountCfg?.botToken?.trim();
+    if (accountToken) {
+        return { token: accountToken, source: "config" };
+    }
+    const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+    const tokenFile = telegramCfg?.tokenFile?.trim();
+    if (tokenFile && allowEnv) {
+        if (!fs.existsSync(tokenFile)) {
+            opts.logMissingFile?.(`channels.telegram.tokenFile not found: ${tokenFile}`);
+            return { token: "", source: "none" };
+        }
+        try {
+            const token = fs.readFileSync(tokenFile, "utf-8").trim();
+            if (token) {
+                return { token, source: "tokenFile" };
+            }
+        }
+        catch (err) {
+            opts.logMissingFile?.(`channels.telegram.tokenFile read failed: ${String(err)}`);
+            return { token: "", source: "none" };
+        }
+    }
+    const configToken = telegramCfg?.botToken?.trim();
+    if (configToken && allowEnv) {
+        return { token: configToken, source: "config" };
+    }
+    const envToken = allowEnv ? (opts.envToken ?? process.env.TELEGRAM_BOT_TOKEN)?.trim() : "";
+    if (envToken) {
+        return { token: envToken, source: "env" };
+    }
+    return { token: "", source: "none" };
+}

package/dist/telegram/update-offset-store.d.ts

@@ -0,0 +1,9 @@
+export declare function readTelegramUpdateOffset(params: {
+    accountId?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<number | null>;
+export declare function writeTelegramUpdateOffset(params: {
+    accountId?: string;
+    updateId: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<void>;

package/dist/telegram/update-offset-store.js

@@ -0,0 +1,63 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+const STORE_VERSION = 1;
+function normalizeAccountId(accountId) {
+    const trimmed = accountId?.trim();
+    if (!trimmed) {
+        return "default";
+    }
+    return trimmed.replace(/[^a-z0-9._-]+/gi, "_");
+}
+function resolveTelegramUpdateOffsetPath(accountId, env = process.env) {
+    const stateDir = resolveStateDir(env, os.homedir);
+    const normalized = normalizeAccountId(accountId);
+    return path.join(stateDir, "telegram", `update-offset-${normalized}.json`);
+}
+function safeParseState(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== STORE_VERSION) {
+            return null;
+        }
+        if (parsed.lastUpdateId !== null && typeof parsed.lastUpdateId !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readTelegramUpdateOffset(params) {
+    const filePath = resolveTelegramUpdateOffsetPath(params.accountId, params.env);
+    try {
+        const raw = await fs.readFile(filePath, "utf-8");
+        const parsed = safeParseState(raw);
+        return parsed?.lastUpdateId ?? null;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return null;
+        }
+        return null;
+    }
+}
+export async function writeTelegramUpdateOffset(params) {
+    const filePath = resolveTelegramUpdateOffsetPath(params.accountId, params.env);
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `${path.basename(filePath)}.${crypto.randomUUID()}.tmp`);
+    const payload = {
+        version: STORE_VERSION,
+        lastUpdateId: params.updateId,
+    };
+    await fs.writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, {
+        encoding: "utf-8",
+    });
+    await fs.chmod(tmp, 0o600);
+    await fs.rename(tmp, filePath);
+}

package/dist/telegram/voice.d.ts

@@ -0,0 +1,20 @@
+export declare function isTelegramVoiceCompatible(opts: {
+    contentType?: string | null;
+    fileName?: string | null;
+}): boolean;
+export declare function resolveTelegramVoiceDecision(opts: {
+    wantsVoice: boolean;
+    contentType?: string | null;
+    fileName?: string | null;
+}): {
+    useVoice: boolean;
+    reason?: string;
+};
+export declare function resolveTelegramVoiceSend(opts: {
+    wantsVoice: boolean;
+    contentType?: string | null;
+    fileName?: string | null;
+    logFallback?: (message: string) => void;
+}): {
+    useVoice: boolean;
+};

package/dist/telegram/voice.js

@@ -0,0 +1,25 @@
+import { isVoiceCompatibleAudio } from "../media/audio.js";
+export function isTelegramVoiceCompatible(opts) {
+    return isVoiceCompatibleAudio(opts);
+}
+export function resolveTelegramVoiceDecision(opts) {
+    if (!opts.wantsVoice) {
+        return { useVoice: false };
+    }
+    if (isTelegramVoiceCompatible(opts)) {
+        return { useVoice: true };
+    }
+    const contentType = opts.contentType ?? "unknown";
+    const fileName = opts.fileName ?? "unknown";
+    return {
+        useVoice: false,
+        reason: `media is ${contentType} (${fileName})`,
+    };
+}
+export function resolveTelegramVoiceSend(opts) {
+    const decision = resolveTelegramVoiceDecision(opts);
+    if (decision.reason && opts.logFallback) {
+        opts.logFallback(`Telegram voice requested but ${decision.reason}; sending as audio file instead.`);
+    }
+    return { useVoice: decision.useVoice };
+}

package/dist/telegram/webhook-set.d.ts

@@ -0,0 +1,12 @@
+import type { TelegramNetworkConfig } from "../config/types.telegram.js";
+export declare function setTelegramWebhook(opts: {
+    token: string;
+    url: string;
+    secret?: string;
+    dropPendingUpdates?: boolean;
+    network?: TelegramNetworkConfig;
+}): Promise<void>;
+export declare function deleteTelegramWebhook(opts: {
+    token: string;
+    network?: TelegramNetworkConfig;
+}): Promise<void>;

package/dist/telegram/webhook-set.js

@@ -0,0 +1,28 @@
+import { Bot } from "grammy";
+import { withTelegramApiErrorLogging } from "./api-logging.js";
+import { resolveTelegramFetch } from "./fetch.js";
+export async function setTelegramWebhook(opts) {
+    const fetchImpl = resolveTelegramFetch(undefined, { network: opts.network });
+    const client = fetchImpl
+        ? { fetch: fetchImpl }
+        : undefined;
+    const bot = new Bot(opts.token, client ? { client } : undefined);
+    await withTelegramApiErrorLogging({
+        operation: "setWebhook",
+        fn: () => bot.api.setWebhook(opts.url, {
+            secret_token: opts.secret,
+            drop_pending_updates: opts.dropPendingUpdates ?? false,
+        }),
+    });
+}
+export async function deleteTelegramWebhook(opts) {
+    const fetchImpl = resolveTelegramFetch(undefined, { network: opts.network });
+    const client = fetchImpl
+        ? { fetch: fetchImpl }
+        : undefined;
+    const bot = new Bot(opts.token, client ? { client } : undefined);
+    await withTelegramApiErrorLogging({
+        operation: "deleteWebhook",
+        fn: () => bot.api.deleteWebhook(),
+    });
+}

package/dist/telegram/webhook.d.ts

@@ -0,0 +1,20 @@
+import type { AGIAgentConfig } from "../config/config.js";
+import type { RuntimeEnv } from "../runtime.js";
+export declare function startTelegramWebhook(opts: {
+    token: string;
+    accountId?: string;
+    config?: AGIAgentConfig;
+    path?: string;
+    port?: number;
+    host?: string;
+    secret?: string;
+    runtime?: RuntimeEnv;
+    fetch?: typeof fetch;
+    abortSignal?: AbortSignal;
+    healthPath?: string;
+    publicUrl?: string;
+}): Promise<{
+    server: import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>;
+    bot: import("grammy").Bot<import("grammy").Context, import("grammy").Api<import("grammy").RawApi>>;
+    stop: () => void;
+}>;

package/dist/telegram/webhook.js

@@ -0,0 +1,96 @@
+import { webhookCallback } from "grammy";
+import { createServer } from "node:http";
+import { isDiagnosticsEnabled } from "../infra/diagnostic-events.js";
+import { formatErrorMessage } from "../infra/errors.js";
+import { logWebhookError, logWebhookProcessed, logWebhookReceived, startDiagnosticHeartbeat, stopDiagnosticHeartbeat, } from "../logging/diagnostic.js";
+import { defaultRuntime } from "../runtime.js";
+import { resolveTelegramAllowedUpdates } from "./allowed-updates.js";
+import { withTelegramApiErrorLogging } from "./api-logging.js";
+import { createTelegramBot } from "./bot.js";
+export async function startTelegramWebhook(opts) {
+    const path = opts.path ?? "/telegram-webhook";
+    const healthPath = opts.healthPath ?? "/healthz";
+    const port = opts.port ?? 8787;
+    const host = opts.host ?? "0.0.0.0";
+    const runtime = opts.runtime ?? defaultRuntime;
+    const diagnosticsEnabled = isDiagnosticsEnabled(opts.config);
+    const bot = createTelegramBot({
+        token: opts.token,
+        runtime,
+        proxyFetch: opts.fetch,
+        config: opts.config,
+        accountId: opts.accountId,
+    });
+    const handler = webhookCallback(bot, "http", {
+        secretToken: opts.secret,
+    });
+    if (diagnosticsEnabled) {
+        startDiagnosticHeartbeat();
+    }
+    const server = createServer((req, res) => {
+        if (req.url === healthPath) {
+            res.writeHead(200);
+            res.end("ok");
+            return;
+        }
+        if (req.url !== path || req.method !== "POST") {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const startTime = Date.now();
+        if (diagnosticsEnabled) {
+            logWebhookReceived({ channel: "telegram", updateType: "telegram-post" });
+        }
+        const handled = handler(req, res);
+        if (handled && typeof handled.catch === "function") {
+            void handled
+                .then(() => {
+                if (diagnosticsEnabled) {
+                    logWebhookProcessed({
+                        channel: "telegram",
+                        updateType: "telegram-post",
+                        durationMs: Date.now() - startTime,
+                    });
+                }
+            })
+                .catch((err) => {
+                const errMsg = formatErrorMessage(err);
+                if (diagnosticsEnabled) {
+                    logWebhookError({
+                        channel: "telegram",
+                        updateType: "telegram-post",
+                        error: errMsg,
+                    });
+                }
+                runtime.log?.(`webhook handler failed: ${errMsg}`);
+                if (!res.headersSent) {
+                    res.writeHead(500);
+                }
+                res.end();
+            });
+        }
+    });
+    const publicUrl = opts.publicUrl ?? `http://${host === "0.0.0.0" ? "localhost" : host}:${port}${path}`;
+    await withTelegramApiErrorLogging({
+        operation: "setWebhook",
+        runtime,
+        fn: () => bot.api.setWebhook(publicUrl, {
+            secret_token: opts.secret,
+            allowed_updates: resolveTelegramAllowedUpdates(),
+        }),
+    });
+    await new Promise((resolve) => server.listen(port, host, resolve));
+    runtime.log?.(`webhook listening on ${publicUrl}`);
+    const shutdown = () => {
+        server.close();
+        void bot.stop();
+        if (diagnosticsEnabled) {
+            stopDiagnosticHeartbeat();
+        }
+    };
+    if (opts.abortSignal) {
+        opts.abortSignal.addEventListener("abort", shutdown, { once: true });
+    }
+    return { server, bot, stop: shutdown };
+}

package/dist/terminal/ansi.d.ts

@@ -0,0 +1,2 @@
+export declare function stripAnsi(input: string): string;
+export declare function visibleWidth(input: string): number;

package/dist/terminal/ansi.js

@@ -0,0 +1,11 @@
+const ANSI_SGR_PATTERN = "\\x1b\\[[0-9;]*m";
+// OSC-8 hyperlinks: ESC ] 8 ; ; url ST ... ESC ] 8 ; ; ST
+const OSC8_PATTERN = "\\x1b\\]8;;.*?\\x1b\\\\|\\x1b\\]8;;\\x1b\\\\";
+const ANSI_REGEX = new RegExp(ANSI_SGR_PATTERN, "g");
+const OSC8_REGEX = new RegExp(OSC8_PATTERN, "g");
+export function stripAnsi(input) {
+    return input.replace(OSC8_REGEX, "").replace(ANSI_REGEX, "");
+}
+export function visibleWidth(input) {
+    return Array.from(stripAnsi(input)).length;
+}

package/dist/terminal/links.d.ts

@@ -0,0 +1,6 @@
+export declare const DOCS_ROOT = "https://docs.agiagent.dev";
+export declare function formatDocsLink(path: string, label?: string, opts?: {
+    fallback?: string;
+    force?: boolean;
+}): string;
+export declare function formatDocsRootLink(label?: string): string;

package/dist/terminal/links.js

@@ -0,0 +1,17 @@
+import { formatTerminalLink } from "../utils.js";
+export const DOCS_ROOT = "https://docs.agiagent.dev";
+export function formatDocsLink(path, label, opts) {
+    const trimmed = path.trim();
+    const url = trimmed.startsWith("http")
+        ? trimmed
+        : `${DOCS_ROOT}${trimmed.startsWith("/") ? trimmed : `/${trimmed}`}`;
+    return formatTerminalLink(label ?? url, url, {
+        fallback: opts?.fallback ?? url,
+        force: opts?.force,
+    });
+}
+export function formatDocsRootLink(label) {
+    return formatTerminalLink(label ?? DOCS_ROOT, DOCS_ROOT, {
+        fallback: DOCS_ROOT,
+    });
+}