@nubemclaw/channel-telegram 1.2.2

package/dist/transport.d.ts

@@ -0,0 +1,37 @@
+import type { ChannelLogger } from "@nubemclaw/channel-sdk";
+export interface TelegramTransportOptions {
+    /**
+     * Explicit proxy URL (`http://...` / `https://...`). Defaults to
+     * `NUBEMCLAW_PROXY_URL` env var. When set, every dispatcher routes
+     * through this proxy via `undici.ProxyAgent`.
+     */
+    readonly proxyUrl?: string;
+    /** Custom logger; defaults to a silent one (transport doesn't own loggers). */
+    readonly logger?: ChannelLogger;
+    /** Test seam: override the env var for proxy resolution. */
+    readonly envVars?: NodeJS.ProcessEnv;
+}
+export interface TelegramTransport {
+    /**
+     * `fetch`-shaped callable usable directly as `new Bot(token,
+     * { client: { fetcher } }).` Routes through the primary dispatcher
+     * with automatic IPv4 fallback on persistent network failures.
+     */
+    fetch: typeof globalThis.fetch;
+    /**
+     * Destroys every dispatcher this transport owns. Safe to call
+     * multiple times; subsequent calls resolve immediately. The runner
+     * MUST call this when stopping the channel — otherwise undici keeps
+     * keep-alive sockets open indefinitely.
+     */
+    close(): Promise<void>;
+}
+export declare const createTelegramTransport: (opts?: TelegramTransportOptions) => TelegramTransport;
+/**
+ * Sentinel constant identifying the Telegram API host. Exported for
+ * tests that want to assert the transport is being aimed at the right
+ * origin (the wrapped fetch does not enforce this — `globalThis.fetch`
+ * resolves the URL the caller supplies).
+ */
+export declare const TELEGRAM_HOST = "api.telegram.org";
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AA+I5D,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACtC;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAC/B;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiBD,eAAO,MAAM,uBAAuB,GAAI,OAAM,wBAA6B,KAAG,iBA2J7E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,qBAAwB,CAAC"}

package/dist/transport.js

@@ -0,0 +1,284 @@
+import { Agent, ProxyAgent, fetch as undiciFetch } from "undici";
+/**
+ * Telegram operational transport (Phase 13, task #144 v2).
+ *
+ * Port of the operational hardening from OpenClaw
+ * `extensions/telegram/src/fetch.ts:862`. Telegram long-polling keeps
+ * connections to `api.telegram.org` hot for hours; the default global
+ * `fetch`/undici behavior is wrong for this access pattern in three
+ * concrete ways the OpenClaw codebase documented through real
+ * production incidents (openclaw#68128 is cited verbatim in
+ * fetch.ts:37-39):
+ *
+ *   1. **HTTP/2 ALPN stalls long-polling.** Undici 8 enables HTTP/2
+ *      negotiation by default. The Telegram Bot API serves both /1.1
+ *      and /2, but the /2 stream behavior interacts badly with the
+ *      long-poll on Windows/IPv6 networks — connections hang past the
+ *      `getUpdates(timeout=N)` budget. `allowH2: false` pins HTTP/1.1.
+ *
+ *   2. **Unbounded connection pool leaks sockets.** The default Agent
+ *      has no per-origin connection limit and an effectively
+ *      unbounded `keepAliveTimeout`. Long polling rotates dispatchers
+ *      slowly; the leak grows monotonically until file descriptors
+ *      exhaust. Pinning `connections: 10`, `keepAliveTimeout: 30s` and
+ *      `keepAliveMaxTimeout: 600s` keeps the pool bounded.
+ *
+ *   3. **No way to release sockets on shutdown.** A polling session
+ *      that stops without destroying its dispatcher leaves keep-alive
+ *      sockets open. The exported `close()` calls `destroy()` on
+ *      every owned dispatcher so the runner can swap or drop the
+ *      transport cleanly.
+ *
+ * Two additional concerns the transport handles:
+ *
+ *   - **IPv4 fallback with sticky attempts**: some operator networks
+ *     (notably IPv6-only with broken NAT64) cannot reach
+ *     `api.telegram.org` over IPv6. OpenClaw observed enough of this
+ *     to ship sticky fallback to `family: 4`. We port the same
+ *     behavior with a simpler health model: after N consecutive
+ *     failures the transport flips to the IPv4-pinned dispatcher.
+ *
+ *   - **Proxy support**: `NUBEMCLAW_PROXY_URL` env var or constructor
+ *     param mounts an undici `ProxyAgent`. Corporate networks behind
+ *     egress proxies need this — there is no built-in env support in
+ *     grammy's default `globalThis.fetch`.
+ *
+ * What this implementation deliberately omits vs OpenClaw fetch.ts:
+ *
+ *   - **DNS pinning to hardcoded Telegram IPs** (the `149.154.167.220`
+ *     fallback list). Telegram rotates IPs on its own schedule; a
+ *     hardcoded list is a hostile maintenance burden and we have no
+ *     evidence it solved an incident outside OpenClaw's specific
+ *     deployment. If we see DNS failures in v3 we revisit.
+ *   - **HTTP exchange capture** (the `captureHttpExchange` calls).
+ *     That is a debug-only feature wired to OpenClaw's internal
+ *     observability; not portable to v3 today.
+ *
+ * The transport returns a `fetch` callable that grammy's `Bot`
+ * constructor accepts via `new Bot(token, { client: { fetcher } })`.
+ */
+const TELEGRAM_API_HOSTNAME = "api.telegram.org";
+const POOL_KEEP_ALIVE_TIMEOUT_MS = 30_000;
+const POOL_KEEP_ALIVE_MAX_TIMEOUT_MS = 600_000;
+const POOL_CONNECTIONS_PER_ORIGIN = 10;
+const POOL_PIPELINING = 1;
+const FALLBACK_FAILURE_THRESHOLD = 5;
+const FALLBACK_COOLDOWN_INITIAL_MS = 10_000;
+const FALLBACK_COOLDOWN_MAX_MS = 60_000;
+const FALLBACK_NETWORK_ERROR_CODES = new Set([
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+const poolOptions = () => ({
+    allowH2: false,
+    keepAliveTimeout: POOL_KEEP_ALIVE_TIMEOUT_MS,
+    keepAliveMaxTimeout: POOL_KEEP_ALIVE_MAX_TIMEOUT_MS,
+    connections: POOL_CONNECTIONS_PER_ORIGIN,
+    pipelining: POOL_PIPELINING,
+});
+const collectErrorCodes = (err) => {
+    const codes = new Set();
+    const queue = [err];
+    const seen = new Set();
+    let i = 0;
+    while (i < queue.length) {
+        const current = queue[i++];
+        if (current === null || current === undefined || seen.has(current))
+            continue;
+        seen.add(current);
+        if (typeof current !== "object")
+            continue;
+        const code = current.code;
+        if (typeof code === "string" && code.trim() !== "") {
+            codes.add(code.trim().toUpperCase());
+        }
+        const cause = current.cause;
+        if (cause !== undefined)
+            queue.push(cause);
+        const nested = current.errors;
+        if (Array.isArray(nested))
+            for (const n of nested)
+                queue.push(n);
+    }
+    return codes;
+};
+const shouldFallback = (err) => {
+    if (err === null || err === undefined)
+        return false;
+    const codes = collectErrorCodes(err);
+    for (const c of FALLBACK_NETWORK_ERROR_CODES) {
+        if (codes.has(c))
+            return true;
+    }
+    const message = err !== null && typeof err === "object" && "message" in err
+        ? String(err.message).toLowerCase()
+        : "";
+    return message.includes("fetch failed") && codes.size === 0;
+};
+const silentLogger = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    debug: () => { },
+};
+const resolveProxyUrl = (opts) => {
+    const explicit = opts.proxyUrl?.trim();
+    if (explicit !== undefined && explicit !== "")
+        return explicit;
+    const envVars = opts.envVars ?? process.env;
+    const env = envVars["NUBEMCLAW_PROXY_URL"]?.trim();
+    return env !== undefined && env !== "" ? env : undefined;
+};
+export const createTelegramTransport = (opts = {}) => {
+    const logger = opts.logger ?? silentLogger;
+    const proxyUrl = resolveProxyUrl(opts);
+    const owned = new Set();
+    const buildPrimary = () => {
+        if (proxyUrl !== undefined) {
+            return new ProxyAgent({ uri: proxyUrl, ...poolOptions() });
+        }
+        return new Agent({ ...poolOptions() });
+    };
+    const buildFallbackIpv4 = () => {
+        // Force IPv4. ProxyAgent doesn't take a connect.family override
+        // directly via construction — when a proxy is in play we keep the
+        // dispatcher identical to primary because the IPv4 vs IPv6 decision
+        // is made by the proxy itself. Without a proxy we pin family: 4.
+        if (proxyUrl !== undefined) {
+            return new ProxyAgent({ uri: proxyUrl, ...poolOptions() });
+        }
+        return new Agent({
+            ...poolOptions(),
+            connect: { family: 4 },
+        });
+    };
+    // Lazy dispatcher instantiation per attempt so we only pay the cost
+    // when the attempt is actually exercised.
+    let primaryDispatcher = null;
+    let fallbackDispatcher = null;
+    const getPrimary = () => {
+        if (primaryDispatcher === null) {
+            primaryDispatcher = buildPrimary();
+            owned.add(primaryDispatcher);
+        }
+        return primaryDispatcher;
+    };
+    const getFallback = () => {
+        if (fallbackDispatcher === null) {
+            fallbackDispatcher = buildFallbackIpv4();
+            owned.add(fallbackDispatcher);
+        }
+        return fallbackDispatcher;
+    };
+    const attempts = [
+        { kind: "primary", create: getPrimary },
+        { kind: "fallback-ipv4", create: getFallback },
+    ];
+    const health = attempts.map(() => ({
+        consecutiveFailures: 0,
+        cooldownMs: FALLBACK_COOLDOWN_INITIAL_MS,
+        unhealthyUntilMs: 0,
+    }));
+    let stickyIndex = 0;
+    const recordSuccess = (attemptIndex) => {
+        const h = health[attemptIndex];
+        if (h === undefined)
+            return;
+        h.consecutiveFailures = 0;
+        h.cooldownMs = FALLBACK_COOLDOWN_INITIAL_MS;
+        h.unhealthyUntilMs = 0;
+        if (attemptIndex < stickyIndex) {
+            logger.debug({ from: stickyIndex, to: attemptIndex }, "telegram transport: recovered to lower-cost attempt");
+            stickyIndex = attemptIndex;
+        }
+    };
+    const recordFailure = (attemptIndex, err) => {
+        if (!shouldFallback(err))
+            return;
+        const h = health[attemptIndex];
+        if (h === undefined)
+            return;
+        h.consecutiveFailures += 1;
+        if (h.consecutiveFailures < FALLBACK_FAILURE_THRESHOLD)
+            return;
+        const cooldownMs = Math.min(FALLBACK_COOLDOWN_MAX_MS, h.cooldownMs);
+        h.consecutiveFailures = 0;
+        h.cooldownMs = Math.min(FALLBACK_COOLDOWN_MAX_MS, cooldownMs * 2);
+        h.unhealthyUntilMs = Date.now() + cooldownMs;
+        logger.warn({ attempt: attempts[attemptIndex]?.kind, cooldownMs }, "telegram transport: attempt marked temporarily unhealthy");
+    };
+    const promoteSticky = () => {
+        if (stickyIndex < attempts.length - 1) {
+            stickyIndex += 1;
+            logger.warn({ newAttempt: attempts[stickyIndex]?.kind }, "telegram transport: promoting to fallback attempt");
+        }
+    };
+    const wrappedFetch = async (input, init) => {
+        let lastErr;
+        for (let attemptIndex = stickyIndex; attemptIndex < attempts.length; attemptIndex += 1) {
+            const attempt = attempts[attemptIndex];
+            if (attempt === undefined)
+                break;
+            const h = health[attemptIndex];
+            if (h !== undefined && h.unhealthyUntilMs > Date.now()) {
+                // Skip this attempt while it cools down.
+                lastErr = new Error(`telegram transport: attempt '${attempt.kind}' cooling down`);
+                continue;
+            }
+            try {
+                const dispatcher = attempt.create();
+                // Cast to RequestInit + dispatcher property — undici's RequestInit
+                // extends the global with `dispatcher`, but the global `fetch`
+                // type doesn't know that.
+                const initWithDispatcher = {
+                    ...init,
+                    dispatcher,
+                };
+                const res = await undiciFetch(input, initWithDispatcher);
+                recordSuccess(attemptIndex);
+                return res;
+            }
+            catch (cause) {
+                lastErr = cause;
+                if (!shouldFallback(cause))
+                    throw cause;
+                recordFailure(attemptIndex, cause);
+                if (attemptIndex === stickyIndex && attemptIndex < attempts.length - 1) {
+                    promoteSticky();
+                }
+            }
+        }
+        throw lastErr;
+    };
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        const toDestroy = [...owned];
+        owned.clear();
+        await Promise.all(toDestroy.map(async (d) => {
+            try {
+                await d.destroy();
+            }
+            catch {
+                // Already destroyed — ignore.
+            }
+        }));
+    };
+    return {
+        fetch: wrappedFetch,
+        close,
+    };
+};
+/**
+ * Sentinel constant identifying the Telegram API host. Exported for
+ * tests that want to assert the transport is being aimed at the right
+ * origin (the wrapped fetch does not enforce this — `globalThis.fetch`
+ * resolves the URL the caller supplies).
+ */
+export const TELEGRAM_HOST = TELEGRAM_API_HOSTNAME;
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nubemclaw/channel-telegram",
+  "version": "1.2.2",
+  "description": "NubemClaw v3 — Telegram channel wrapping grammy (polling + webhook + setup).",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@grammyjs/transformer-throttler": "1.2.1",
+    "grammy": "1.42.0",
+    "undici": "8.2.0",
+    "zod": "^3.23.8",
+    "@nubemclaw/channel-sdk": "1.2.2",
+    "@nubemclaw/core": "1.2.2"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean && rm -rf dist .cache"
+  }
+}

package/src/api/schemas.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+
+/**
+ * Telegram Bot API response envelope (Phase 13, ADR-0020 §4 — boundary
+ * validation on untrusted input). Every Bot API response wraps either
+ * a successful `result` or a structured failure with `error_code` +
+ * `description`. We validate the envelope at this boundary so the rest
+ * of the channel package consumes typed payloads, never raw JSON.
+ *
+ * Scope: F13 covers only `message` updates with `text`. Photos, voice,
+ * documents, stickers, edited messages, callback queries — all reach
+ * Telegram but are silently ignored by the polling adapter via
+ * `allowed_updates: ["message"]`. The schemas below model exactly what
+ * we need to forward through the agent and no more — narrower payloads
+ * = smaller attack surface for parser bugs and easier to evolve.
+ *
+ * `passthrough()` is deliberate on `Message` and `User`: Telegram adds
+ * fields between minor versions; we tolerate unknown keys (do not
+ * reject) so a Bot API minor bump does not break the channel, but we
+ * never propagate them outside this boundary.
+ */
+
+export const TelegramUserSchema = z
+  .object({
+    id: z.number().int(),
+    is_bot: z.boolean(),
+    first_name: z.string().optional(),
+    username: z.string().optional(),
+    language_code: z.string().optional(),
+  })
+  .passthrough();
+export type TelegramUser = z.infer<typeof TelegramUserSchema>;
+
+export const TelegramChatSchema = z
+  .object({
+    id: z.number().int(),
+    type: z.enum(["private", "group", "supergroup", "channel"]),
+    title: z.string().optional(),
+    username: z.string().optional(),
+  })
+  .passthrough();
+export type TelegramChat = z.infer<typeof TelegramChatSchema>;
+
+export const TelegramMessageSchema = z
+  .object({
+    message_id: z.number().int(),
+    date: z.number().int(),
+    chat: TelegramChatSchema,
+    from: TelegramUserSchema.optional(),
+    text: z.string().optional(),
+  })
+  .passthrough();
+export type TelegramMessage = z.infer<typeof TelegramMessageSchema>;
+
+/**
+ * Update wraps either a new `message` or fields F13 deliberately
+ * ignores (edited_message, callback_query, etc.). `allowed_updates`
+ * on `getUpdates`/`setWebhook` filters those at Telegram's side, so
+ * in practice only `update_id + message` reach us; the schema models
+ * the F13 happy path and tolerates extra keys via passthrough.
+ */
+export const TelegramUpdateSchema = z
+  .object({
+    update_id: z.number().int(),
+    message: TelegramMessageSchema.optional(),
+  })
+  .passthrough();
+export type TelegramUpdate = z.infer<typeof TelegramUpdateSchema>;
+
+export const TelegramOkEnvelope = <T extends z.ZodTypeAny>(result: T) =>
+  z.object({ ok: z.literal(true), result });
+
+export const TelegramErrEnvelope = z.object({
+  ok: z.literal(false),
+  error_code: z.number().int(),
+  description: z.string(),
+  parameters: z
+    .object({
+      retry_after: z.number().int().optional(),
+      migrate_to_chat_id: z.number().int().optional(),
+    })
+    .partial()
+    .passthrough()
+    .optional(),
+});
+export type TelegramErrResponse = z.infer<typeof TelegramErrEnvelope>;
+
+/** Convenience type alias for "the API succeeded and gave us this T". */
+export type TelegramOk<T> = { readonly ok: true; readonly result: T };