@alfe.ai/openclaw-telegram 0.0.1

package/dist/telegram-bridge.js

@@ -0,0 +1,289 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+//#region src/telegram-bridge.ts
+const MAX_LINE_BYTES = 1024 * 1024;
+const START_TIMEOUT_MS = 2e4;
+const REQUEST_TIMEOUT_MS = 3e4;
+const STOP_TIMEOUT_MS = 2e3;
+var TelegramBridgeUnavailable = class extends Error {
+	name = "TelegramBridgeUnavailable";
+	constructor(code) {
+		super("Telegram local runtime is unavailable");
+		this.code = code;
+	}
+};
+var TelegramBridge = class {
+	logger;
+	stateDir;
+	pythonExecutable;
+	bridgeScript;
+	spawnBridge;
+	startTimeoutMs;
+	onEvent;
+	onExit;
+	child = null;
+	buffer = "";
+	ready = false;
+	stopping = false;
+	requests = /* @__PURE__ */ new Map();
+	startResolve = null;
+	startReject = null;
+	constructor(options) {
+		this.logger = options.logger;
+		this.stateDir = options.stateDir;
+		this.pythonExecutable = options.pythonExecutable ?? resolvePythonExecutable(this.stateDir);
+		this.bridgeScript = options.bridgeScript ?? fileURLToPath(new URL("../python/bridge.py", import.meta.url));
+		this.spawnBridge = options.spawnBridge ?? ((command, args) => spawn(command, args, {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			env: minimalChildEnvironment()
+		}));
+		this.startTimeoutMs = options.startTimeoutMs ?? START_TIMEOUT_MS;
+		this.onEvent = options.onEvent;
+		this.onExit = options.onExit;
+	}
+	isReady() {
+		return this.ready;
+	}
+	async start() {
+		if (this.child) return;
+		if (!existsSync(this.pythonExecutable)) throw new TelegramBridgeUnavailable("runtime_missing");
+		if (!existsSync(this.bridgeScript)) throw new TelegramBridgeUnavailable("bridge_missing");
+		this.stopping = false;
+		this.buffer = "";
+		const child = this.spawnBridge(this.pythonExecutable, [
+			this.bridgeScript,
+			"run",
+			"--state-dir",
+			this.stateDir
+		]);
+		this.child = child;
+		child.stdout.setEncoding("utf8");
+		child.stdout.on("data", (chunk) => {
+			this.consume(chunk);
+		});
+		child.stderr.on("data", () => {
+			this.logger.debug("Telegram bridge emitted a redacted diagnostic");
+		});
+		child.on("error", () => {
+			this.handleExit("spawn_failed");
+		});
+		child.on("exit", () => {
+			this.handleExit("bridge_exited");
+		});
+		await new Promise((resolve, reject) => {
+			let settled = false;
+			const timer = setTimeout(() => {
+				if (settled) return;
+				settled = true;
+				this.startResolve = null;
+				this.startReject = null;
+				reject(new TelegramBridgeUnavailable("start_timeout"));
+				this.stop();
+			}, this.startTimeoutMs);
+			timer.unref();
+			this.startResolve = () => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				this.startResolve = null;
+				this.startReject = null;
+				resolve();
+			};
+			this.startReject = (error) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				this.startResolve = null;
+				this.startReject = null;
+				reject(error);
+			};
+		});
+	}
+	async request(method, params = {}) {
+		const child = this.child;
+		if (!child || !this.ready) throw new TelegramBridgeUnavailable("not_ready");
+		const id = randomUUID();
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.requests.delete(id);
+				reject(new TelegramBridgeUnavailable("request_timeout"));
+			}, REQUEST_TIMEOUT_MS);
+			timer.unref();
+			this.requests.set(id, {
+				resolve: (value) => {
+					resolve(value);
+				},
+				reject,
+				timer
+			});
+			const encoded = JSON.stringify({
+				id,
+				method,
+				params
+			});
+			child.stdin.write(`${encoded}\n`, (error) => {
+				if (!error) return;
+				const pending = this.requests.get(id);
+				if (!pending) return;
+				clearTimeout(pending.timer);
+				this.requests.delete(id);
+				pending.reject(new TelegramBridgeUnavailable("write_failed"));
+			});
+		});
+	}
+	async stop() {
+		await this.terminate(true, "stopped");
+	}
+	async terminate(callerRequested, code) {
+		const child = this.child;
+		if (!child) return;
+		this.stopping = callerRequested;
+		if (callerRequested && this.ready) await Promise.race([this.request("shutdown").catch(() => void 0), deadline(STOP_TIMEOUT_MS)]);
+		child.stdin.end();
+		if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+		this.handleExit(code);
+	}
+	consume(chunk) {
+		this.buffer += chunk;
+		if (Buffer.byteLength(this.buffer, "utf8") > MAX_LINE_BYTES && !this.buffer.includes("\n")) {
+			this.logger.warn("Telegram bridge exceeded the local message boundary");
+			this.terminate(false, "message_boundary_exceeded");
+			return;
+		}
+		for (;;) {
+			const newline = this.buffer.indexOf("\n");
+			if (newline < 0) break;
+			const line = this.buffer.slice(0, newline);
+			this.buffer = this.buffer.slice(newline + 1);
+			if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) {
+				this.logger.warn("Telegram bridge line exceeded the local message boundary");
+				this.terminate(false, "message_boundary_exceeded");
+				return;
+			}
+			this.handleLine(line);
+		}
+	}
+	handleLine(line) {
+		let decoded;
+		try {
+			decoded = JSON.parse(line);
+		} catch {
+			this.logger.warn("Telegram bridge returned invalid local data");
+			return;
+		}
+		if (!isRecord(decoded) || typeof decoded.type !== "string") return;
+		if (decoded.type === "ready") {
+			this.ready = true;
+			this.startResolve?.();
+			return;
+		}
+		if (decoded.type === "fatal") {
+			const code = safeCode(decoded.code);
+			this.startReject?.(new TelegramBridgeUnavailable(code));
+			return;
+		}
+		if (decoded.type === "response" && typeof decoded.id === "string") {
+			const pending = this.requests.get(decoded.id);
+			if (!pending) return;
+			clearTimeout(pending.timer);
+			this.requests.delete(decoded.id);
+			if (decoded.ok === true) pending.resolve(decoded.result);
+			else pending.reject(new TelegramBridgeUnavailable(safeCode(decoded.code)));
+			return;
+		}
+		if (decoded.type === "health") {
+			this.logger.warn(`Telegram bridge health warning: ${safeCode(decoded.code)}`);
+			return;
+		}
+		if (decoded.type === "event") {
+			const event = parseEvent(decoded.event);
+			if (!event) {
+				this.logger.warn("Telegram bridge returned an invalid event");
+				return;
+			}
+			try {
+				this.onEvent(event);
+			} catch {
+				this.logger.warn("Telegram local event callback failed");
+			}
+		}
+	}
+	handleExit(code) {
+		if (!this.child && !this.ready) return;
+		this.child = null;
+		this.ready = false;
+		this.buffer = "";
+		this.startReject?.(new TelegramBridgeUnavailable(code));
+		this.startResolve = null;
+		this.startReject = null;
+		for (const pending of this.requests.values()) {
+			clearTimeout(pending.timer);
+			pending.reject(new TelegramBridgeUnavailable(code));
+		}
+		this.requests.clear();
+		if (!this.stopping) this.onExit?.();
+	}
+};
+function resolvePythonExecutable(stateDir) {
+	const unix = join(stateDir, "runtime", "bin", "python3");
+	if (existsSync(unix)) return unix;
+	return join(stateDir, "runtime", "Scripts", "python.exe");
+}
+function minimalChildEnvironment() {
+	const allowed = [
+		"HOME",
+		"PATH",
+		"LANG",
+		"LC_ALL",
+		"TMPDIR",
+		"SYSTEMROOT",
+		"WINDIR"
+	];
+	const result = {};
+	for (const key of allowed) {
+		const value = process.env[key];
+		if (value !== void 0) result[key] = value;
+	}
+	result.PYTHONUNBUFFERED = "1";
+	return result;
+}
+function parseEvent(value) {
+	if (!isRecord(value)) return null;
+	const { deliveryId, messageId, chatId, chatTitle, chatKind, senderId, senderName, senderUsername, text, timestamp } = value;
+	if (typeof deliveryId !== "string" || typeof messageId !== "string" || typeof chatId !== "string" || typeof chatTitle !== "string" || typeof chatKind !== "string" || typeof senderId !== "string" || typeof senderName !== "string" || typeof text !== "string" || typeof timestamp !== "string") return null;
+	if (chatKind !== "private" && chatKind !== "group" && chatKind !== "channel") return null;
+	if (text.length === 0 || text.length > 32e3) return null;
+	if (!Number.isFinite(Date.parse(timestamp))) return null;
+	return {
+		deliveryId,
+		messageId,
+		chatId,
+		chatTitle,
+		chatKind,
+		senderId,
+		senderName,
+		...typeof senderUsername === "string" ? { senderUsername } : {},
+		text,
+		timestamp
+	};
+}
+function safeCode(value) {
+	return typeof value === "string" && /^[a-z0-9_]{1,64}$/.test(value) ? value : "bridge_error";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function deadline(milliseconds) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, milliseconds).unref();
+	});
+}
+//#endregion
+export { TelegramBridgeUnavailable as n, TelegramBridge as t };

package/openclaw.plugin.json

@@ -0,0 +1,21 @@
+{
+  "id": "@alfe.ai/openclaw-telegram",
+  "name": "Telegram (local user session)",
+  "description": "Explicitly subscribe to Telegram chats through a user session held only on the agent machine",
+  "entry": "./dist/plugin.js",
+  "activation": { "onStartup": true },
+  "contracts": {
+    "tools": [
+      "telegram_status",
+      "telegram_list_chats",
+      "telegram_list_subscriptions",
+      "telegram_subscribe",
+      "telegram_unsubscribe"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@alfe.ai/openclaw-telegram",
+  "version": "0.0.1",
+  "description": "Local-custody Telegram MTProto user-session listener for OpenClaw",
+  "type": "module",
+  "main": "./dist/plugin.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "require": "./dist/plugin.cjs",
+      "import": "./dist/plugin.js"
+    }
+  },
+  "bin": {
+    "alfe-telegram": "./bin/alfe-telegram.mjs"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/plugin.js"
+    ]
+  },
+  "files": [
+    "bin",
+    "dist",
+    "python/bridge.py",
+    "README.md",
+    "openclaw.plugin.json"
+  ],
+  "dependencies": {
+    "@alfe.ai/agent-api-client": "0.17.0",
+    "@alfe.ai/config": "0.4.1",
+    "@alfe.ai/openclaw-plugin-kit": "0.2.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://alfe.ai",
+  "author": "Alfe (https://alfe.ai)",
+  "keywords": [
+    "alfe",
+    "openclaw",
+    "telegram",
+    "telethon",
+    "mtproto"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "python3 -m unittest discover -s python -p 'test_*.py' && vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}