@alfe.ai/openclaw-telegram 0.0.1

package/dist/plugin.cjs

@@ -0,0 +1,503 @@
+const require_telegram_bridge = require("./telegram-bridge.cjs");
+let node_path = require("node:path");
+let node_module = require("node:module");
+let node_os = require("node:os");
+let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
+let _alfe_ai_config = require("@alfe.ai/config");
+let _alfe_ai_openclaw_plugin_kit = require("@alfe.ai/openclaw-plugin-kit");
+//#region src/plugin.ts
+const pkg = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json");
+const RETRY_MS = 3e4;
+const DELIVERY_RETRY_MS = 5e3;
+const IDENTITY_RETRY_MS = 3e4;
+const MAX_IDENTITY_ATTEMPTS = 5;
+const MAX_AGENT_ID_CHARS = 256;
+const SAFE_AGENT_ID = /^[A-Za-z0-9_-]+$/u;
+var TelegramLocalRuntime = class {
+	bridge = null;
+	retryTimer = null;
+	running = false;
+	generation = 0;
+	dispatch = null;
+	pluginRuntime = null;
+	pluginConfig = {};
+	logger = null;
+	deliveryQueuesByChat = /* @__PURE__ */ new Map();
+	dispatchedDeliveryIds = /* @__PURE__ */ new Map();
+	queued = /* @__PURE__ */ new Set();
+	blockedChats = /* @__PURE__ */ new Set();
+	constructor(agentId, stateDir) {
+		this.agentId = agentId;
+		this.stateDir = stateDir;
+	}
+	configure(api) {
+		this.logger = api.logger;
+		this.pluginRuntime = api.runtime ?? null;
+		try {
+			this.pluginConfig = api.runtime?.config.loadConfig() ?? {};
+		} catch {
+			this.pluginConfig = {};
+			api.logger.warn("OpenClaw config could not be loaded; Telegram tools remain available");
+		}
+		this.dispatch = (0, _alfe_ai_openclaw_plugin_kit.resolveOpenClawSdk)(api.logger, { unresolvableNote: "OpenClaw inbound SDK unavailable — Telegram deliveries will retry locally" });
+	}
+	async start() {
+		if (this.running) return;
+		this.running = true;
+		const generation = ++this.generation;
+		await this.connect(generation);
+	}
+	async stop() {
+		this.running = false;
+		this.generation += 1;
+		if (this.retryTimer) {
+			clearTimeout(this.retryTimer);
+			this.retryTimer = null;
+		}
+		const bridge = this.bridge;
+		this.bridge = null;
+		await bridge?.stop();
+	}
+	async status() {
+		const bridge = this.bridge;
+		if (!bridge?.isReady()) return {
+			authorized: false,
+			state: "setup_required",
+			deliveryMode: "read_only",
+			action: `Run \`${loginCommand(this.agentId)}\` in a terminal on the agent machine.`
+		};
+		return bridge.request("status");
+	}
+	async request(method, params = {}) {
+		const bridge = this.bridge;
+		if (!bridge?.isReady()) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)(`Telegram is not logged in on this agent. Run \`${loginCommand(this.agentId)}\` in a terminal on the agent machine.`);
+		try {
+			const result = await bridge.request(method, params);
+			const chatId = typeof params.chatId === "string" ? params.chatId : null;
+			if (chatId && method === "subscribe") this.blockedChats.delete(chatId);
+			if (chatId && method === "unsubscribe") {
+				this.blockedChats.add(chatId);
+				for (const [deliveryId, dispatchedChatId] of this.dispatchedDeliveryIds) if (dispatchedChatId === chatId) this.dispatchedDeliveryIds.delete(deliveryId);
+			}
+			return result;
+		} catch (error) {
+			if (error instanceof require_telegram_bridge.TelegramBridgeUnavailable) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Telegram is temporarily unavailable on this agent. Check `telegram_status` and retry.");
+			throw error;
+		}
+	}
+	async connect(generation) {
+		if (!this.isCurrentGeneration(generation) || this.bridge) return;
+		const logger = this.logger;
+		if (!logger) return;
+		const bridge = new require_telegram_bridge.TelegramBridge({
+			logger,
+			stateDir: this.stateDir,
+			onEvent: (event) => {
+				this.enqueue(event);
+			},
+			onExit: () => {
+				if (this.bridge === bridge) this.bridge = null;
+				this.scheduleRetry(generation);
+			}
+		});
+		this.bridge = bridge;
+		try {
+			await bridge.start();
+			if (!this.isCurrentGeneration(generation)) {
+				await bridge.stop();
+				if (this.bridge === bridge) this.bridge = null;
+				return;
+			}
+			logger.info("Telegram local user-session listener connected");
+		} catch {
+			await bridge.stop().catch(() => void 0);
+			if (this.bridge === bridge) this.bridge = null;
+			logger.info(`Telegram local session is not ready; run \`${loginCommand(this.agentId)}\` on the agent machine`);
+			this.scheduleRetry(generation);
+		}
+	}
+	scheduleRetry(generation) {
+		if (!this.running || generation !== this.generation || this.retryTimer) return;
+		this.retryTimer = setTimeout(() => {
+			this.retryTimer = null;
+			this.connect(generation);
+		}, RETRY_MS);
+		this.retryTimer.unref();
+	}
+	enqueue(event) {
+		if (this.queued.has(event.deliveryId) || this.blockedChats.has(event.chatId)) return;
+		this.queued.add(event.deliveryId);
+		const current = (this.deliveryQueuesByChat.get(event.chatId) ?? Promise.resolve()).then(() => this.deliverUntilAccepted(event)).catch(() => void 0).finally(() => {
+			this.queued.delete(event.deliveryId);
+			if (this.deliveryQueuesByChat.get(event.chatId) === current) this.deliveryQueuesByChat.delete(event.chatId);
+		});
+		this.deliveryQueuesByChat.set(event.chatId, current);
+	}
+	async deliverUntilAccepted(event) {
+		while (this.running && !this.blockedChats.has(event.chatId)) {
+			const dispatch = this.dispatch;
+			const runtime = this.pluginRuntime;
+			const bridge = this.bridge;
+			if (!dispatch || !runtime || !bridge?.isReady()) {
+				await delay(DELIVERY_RETRY_MS);
+				continue;
+			}
+			const outcome = { accepted: true };
+			try {
+				if (!this.dispatchedDeliveryIds.has(event.deliveryId)) {
+					await dispatch({
+						cfg: this.pluginConfig,
+						runtime,
+						channel: "telegram",
+						channelLabel: "Telegram",
+						accountId: `local-user-session:${this.agentId}`,
+						peer: {
+							kind: event.chatKind === "private" ? "direct" : "group",
+							id: event.chatId
+						},
+						senderId: event.senderId,
+						senderAddress: event.senderUsername ? `telegram:@${event.senderUsername}` : `telegram:${event.senderId}`,
+						recipientAddress: `telegram:${event.chatId}`,
+						conversationLabel: `Telegram · ${event.chatTitle}`,
+						rawBody: event.text,
+						messageId: `${this.agentId}:${event.deliveryId}`,
+						timestamp: Date.parse(event.timestamp),
+						extraContext: { telegram: {
+							chatId: event.chatId,
+							chatTitle: event.chatTitle,
+							chatKind: event.chatKind,
+							senderName: event.senderName,
+							readOnly: true
+						} },
+						deliver: () => Promise.resolve(),
+						onRecordError: () => {
+							outcome.accepted = false;
+							this.logger?.warn("Telegram inbound record was rejected; retaining local delivery");
+						},
+						onDispatchError: () => {
+							outcome.accepted = false;
+							this.logger?.warn("Telegram inbound dispatch failed; retaining local delivery");
+						}
+					});
+					if (!outcome.accepted) throw new Error("dispatch_rejected");
+					this.dispatchedDeliveryIds.set(event.deliveryId, event.chatId);
+				}
+				await bridge.request("ack", { deliveryId: event.deliveryId });
+				this.dispatchedDeliveryIds.delete(event.deliveryId);
+				return;
+			} catch {
+				this.logger?.warn("Telegram inbound delivery will retry");
+				await delay(DELIVERY_RETRY_MS);
+			}
+		}
+	}
+	isCurrentGeneration(generation) {
+		return this.running && generation === this.generation;
+	}
+};
+const runtimesByAgent = /* @__PURE__ */ new Map();
+const bindingsByRuntime = /* @__PURE__ */ new Map();
+var TelegramActivationBinding = class TelegramActivationBinding {
+	runtime = null;
+	agentId = null;
+	activationKey = null;
+	ownsStart = false;
+	stopped = true;
+	lifecycleGeneration = 0;
+	resolvingIdentityGeneration = null;
+	identityAttempts = 0;
+	identityRetryTimer = null;
+	async start(api) {
+		const retryCycleExhausted = !this.runtime && this.identityAttempts >= MAX_IDENTITY_ATTEMPTS;
+		if (!this.stopped && !retryCycleExhausted && (this.runtime || this.resolvingIdentityGeneration === this.lifecycleGeneration || this.identityRetryTimer)) return;
+		if (this.stopped || retryCycleExhausted) {
+			this.identityAttempts = 0;
+			this.lifecycleGeneration += 1;
+		}
+		this.stopped = false;
+		await this.resolveIdentityAndStart(api, this.lifecycleGeneration);
+	}
+	async resolveIdentityAndStart(api, generation) {
+		if (this.stopped || generation !== this.lifecycleGeneration || this.runtime || this.resolvingIdentityGeneration === generation) return;
+		this.resolvingIdentityGeneration = generation;
+		this.identityAttempts += 1;
+		let agentId;
+		try {
+			const config = (0, _alfe_ai_config.resolveConfig)();
+			agentId = requireAgentId((await new _alfe_ai_agent_api_client.AgentApiClient({
+				apiKey: config.apiKey,
+				apiUrl: config.apiUrl
+			}).whoami()).agentId);
+		} catch {
+			if (this.resolvingIdentityGeneration === generation) this.resolvingIdentityGeneration = null;
+			if (generation !== this.lifecycleGeneration) return;
+			api.logger.error(this.identityAttempts < MAX_IDENTITY_ATTEMPTS ? "Telegram could not resolve this agent identity; local session startup will retry" : "Telegram could not resolve this agent identity after bounded retries; local session startup is disabled");
+			this.scheduleIdentityRetry(api, generation);
+			return;
+		}
+		if (this.resolvingIdentityGeneration === generation) this.resolvingIdentityGeneration = null;
+		if (generation !== this.lifecycleGeneration) return;
+		const stateDir = telegramStateDir(agentId);
+		let runtime = runtimesByAgent.get(agentId);
+		if (!runtime) {
+			runtime = new TelegramLocalRuntime(agentId, stateDir);
+			runtimesByAgent.set(agentId, runtime);
+		}
+		const activationKey = (0, _alfe_ai_openclaw_plugin_kit.getActivationKey)(`telegram-local-user-session-${agentId}`);
+		const ownsStart = (0, _alfe_ai_openclaw_plugin_kit.guardedStart)(activationKey, api.logger, async () => {
+			runtime.configure(api);
+			await runtime.start();
+		});
+		this.attachRuntime(runtime, agentId, activationKey, ownsStart);
+	}
+	async stop() {
+		this.stopped = true;
+		this.lifecycleGeneration += 1;
+		this.resolvingIdentityGeneration = null;
+		if (this.identityRetryTimer) {
+			clearTimeout(this.identityRetryTimer);
+			this.identityRetryTimer = null;
+		}
+		const runtime = this.runtime;
+		const agentId = this.agentId;
+		const activationKey = this.activationKey;
+		const ownsStart = this.ownsStart;
+		this.detachRuntime(runtime);
+		if (!ownsStart) return;
+		if (runtime) TelegramActivationBinding.invalidateRuntimeBindings(runtime);
+		try {
+			await runtime?.stop();
+		} finally {
+			if (agentId && runtimesByAgent.get(agentId) === runtime) runtimesByAgent.delete(agentId);
+			if (activationKey) (0, _alfe_ai_openclaw_plugin_kit.resetActivation)(activationKey);
+			if (runtime) TelegramActivationBinding.invalidateRuntimeBindings(runtime);
+		}
+	}
+	attachRuntime(runtime, agentId, activationKey, ownsStart) {
+		this.runtime = runtime;
+		this.agentId = agentId;
+		this.activationKey = activationKey;
+		this.ownsStart = ownsStart;
+		let bindings = bindingsByRuntime.get(runtime);
+		if (!bindings) {
+			bindings = /* @__PURE__ */ new Set();
+			bindingsByRuntime.set(runtime, bindings);
+		}
+		bindings.add(this);
+	}
+	detachRuntime(runtime) {
+		if (runtime && this.runtime !== runtime) return;
+		const attachedRuntime = this.runtime;
+		this.runtime = null;
+		this.agentId = null;
+		this.activationKey = null;
+		this.ownsStart = false;
+		if (!attachedRuntime) return;
+		const bindings = bindingsByRuntime.get(attachedRuntime);
+		bindings?.delete(this);
+		if (bindings?.size === 0) bindingsByRuntime.delete(attachedRuntime);
+	}
+	static invalidateRuntimeBindings(runtime) {
+		const bindings = bindingsByRuntime.get(runtime);
+		if (!bindings) return;
+		for (const binding of [...bindings]) binding.detachRuntime(runtime);
+	}
+	scheduleIdentityRetry(api, generation) {
+		if (this.stopped || generation !== this.lifecycleGeneration || this.runtime || this.identityRetryTimer || this.identityAttempts >= MAX_IDENTITY_ATTEMPTS) return;
+		this.identityRetryTimer = setTimeout(() => {
+			this.identityRetryTimer = null;
+			this.resolveIdentityAndStart(api, generation);
+		}, IDENTITY_RETRY_MS);
+		this.identityRetryTimer.unref();
+	}
+	status() {
+		if (this.runtime) return this.runtime.status();
+		return Promise.resolve({
+			authorized: false,
+			state: "identity_required",
+			deliveryMode: "read_only",
+			action: "Wait for the local Telegram service to resolve this agent identity, then retry."
+		});
+	}
+	request(method, params = {}) {
+		if (!this.runtime) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Telegram is still resolving this agent identity. Retry telegram_status shortly.");
+		return this.runtime.request(method, params);
+	}
+};
+const bindingsByApi = /* @__PURE__ */ new WeakMap();
+const plugin = {
+	id: "@alfe.ai/openclaw-telegram",
+	name: "Telegram (local user session)",
+	description: "Explicit local Telegram chat subscriptions through a machine-held MTProto session",
+	version: pkg.version,
+	activate(api) {
+		(0, _alfe_ai_agent_api_client.installToolErrorCapture)(api, { plugin: "openclaw-telegram" });
+		const binding = new TelegramActivationBinding();
+		bindingsByApi.set(api, binding);
+		for (const tool of createTools(binding)) api.registerTool(tool);
+		api.registerService({
+			id: "telegram-local-user-session",
+			start: async () => {
+				await binding.start(api);
+			},
+			stop: async () => {
+				await binding.stop();
+			}
+		});
+		api.logger.info("Registered 5 local Telegram tools");
+	},
+	async deactivate(api) {
+		const binding = bindingsByApi.get(api);
+		bindingsByApi.delete(api);
+		await binding?.stop();
+		api.logger.info("Telegram local user-session plugin deactivated");
+	}
+};
+function createTools(binding) {
+	return [
+		(0, _alfe_ai_openclaw_plugin_kit.defineTool)({
+			name: "telegram_status",
+			description: "Check whether the local Telegram user session is authorized and show subscription/delivery counts.",
+			parameters: emptyObjectSchema(),
+			handler: () => binding.status()
+		}),
+		(0, _alfe_ai_openclaw_plugin_kit.defineTool)({
+			name: "telegram_list_chats",
+			description: "List chats visible to the locally signed-in Telegram account. Use the returned chatId with telegram_subscribe.",
+			parameters: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					offset: {
+						type: "integer",
+						minimum: 0,
+						maximum: 5e3
+					},
+					limit: {
+						type: "integer",
+						minimum: 1,
+						maximum: 100
+					},
+					query: {
+						type: "string",
+						maxLength: 128
+					},
+					kinds: {
+						type: "array",
+						maxItems: 3,
+						uniqueItems: true,
+						items: {
+							type: "string",
+							enum: [
+								"private",
+								"group",
+								"channel"
+							]
+						}
+					}
+				}
+			},
+			handler: (params) => binding.request("list_dialogs", normalizeListParams(params))
+		}),
+		(0, _alfe_ai_openclaw_plugin_kit.defineTool)({
+			name: "telegram_list_subscriptions",
+			description: "List the Telegram chats whose new text messages currently trigger local agent turns, with pagination.",
+			parameters: paginationSchema(),
+			handler: (params) => binding.request("list_subscriptions", normalizePagination(params))
+		}),
+		(0, _alfe_ai_openclaw_plugin_kit.defineTool)({
+			name: "telegram_subscribe",
+			description: "Subscribe locally to one Telegram chat by chatId. Only do this with the user’s explicit permission and where message processing is allowed.",
+			parameters: chatIdSchema(),
+			handler: (params) => binding.request("subscribe", { chatId: requireChatId(params) })
+		}),
+		(0, _alfe_ai_openclaw_plugin_kit.defineTool)({
+			name: "telegram_unsubscribe",
+			description: "Stop local processing of new messages from one subscribed Telegram chat.",
+			parameters: chatIdSchema(),
+			handler: (params) => binding.request("unsubscribe", { chatId: requireChatId(params) })
+		})
+	];
+}
+function telegramStateDir(agentId, home = (0, node_os.homedir)()) {
+	return (0, node_path.join)(home, ".alfe", "agents", requireAgentId(agentId), "telegram");
+}
+function loginCommand(agentId) {
+	return `npx -y @alfe.ai/openclaw-telegram@${pkg.version} login --agent-id ${requireAgentId(agentId)}`;
+}
+function requireAgentId(value) {
+	if (typeof value !== "string" || value.length === 0 || value.length > MAX_AGENT_ID_CHARS || !SAFE_AGENT_ID.test(value)) throw new Error("Invalid local agent identity");
+	return value;
+}
+function emptyObjectSchema() {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: {}
+	};
+}
+function chatIdSchema() {
+	return {
+		type: "object",
+		additionalProperties: false,
+		required: ["chatId"],
+		properties: { chatId: {
+			type: "string",
+			minLength: 1,
+			maxLength: 128,
+			pattern: "^-?[0-9]+$"
+		} }
+	};
+}
+function paginationSchema() {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			offset: {
+				type: "integer",
+				minimum: 0,
+				maximum: 5e3
+			},
+			limit: {
+				type: "integer",
+				minimum: 1,
+				maximum: 100
+			}
+		}
+	};
+}
+function requireChatId(params) {
+	const value = params.chatId;
+	if (typeof value !== "string" || !/^-?[0-9]+$/.test(value) || value.length > 128) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("chatId must be a Telegram numeric chat ID returned by telegram_list_chats.");
+	return value;
+}
+function normalizeListParams(params) {
+	const normalized = normalizePagination(params);
+	if (params.query !== void 0) {
+		if (typeof params.query !== "string" || params.query.length > 128) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("query must be a string of at most 128 characters.");
+		normalized.query = params.query;
+	}
+	if (params.kinds !== void 0) {
+		if (!Array.isArray(params.kinds) || params.kinds.some((kind) => kind !== "private" && kind !== "group" && kind !== "channel")) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("kinds may contain only private, group, or channel.");
+		normalized.kinds = [...new Set(params.kinds)];
+	}
+	return normalized;
+}
+function normalizePagination(params) {
+	const normalized = {};
+	if (params.offset !== void 0) normalized.offset = requireInteger(params.offset, 0, 5e3, "offset");
+	if (params.limit !== void 0) normalized.limit = requireInteger(params.limit, 1, 100, "limit");
+	return normalized;
+}
+function requireInteger(value, minimum, maximum, name) {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < minimum || value > maximum) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)(`${name} must be an integer from ${String(minimum)} to ${String(maximum)}.`);
+	return value;
+}
+async function delay(milliseconds) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, milliseconds).unref();
+	});
+}
+//#endregion
+module.exports = plugin;

package/dist/plugin.d.cts

@@ -0,0 +1,58 @@
+import { r as TelegramBridgeLogger } from "./telegram-bridge.cjs";
+
+//#region ../openclaw-plugin-kit/dist/index.d.ts
+
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/tools.d.ts
+/** Shape returned to OpenClaw from a tool `execute`. */
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface ToolDef<TParameters = unknown> {
+  name: string;
+  description: string;
+  label: string;
+  parameters: TParameters;
+  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
+//#endregion
+//#region src/plugin.d.ts
+interface PluginRuntime {
+  config: {
+    loadConfig(): Record<string, unknown>;
+  };
+  channel: unknown;
+}
+interface PluginServiceContext {
+  logger: PluginLogger;
+  stateDir: string;
+  config: Record<string, unknown>;
+}
+type PluginLogger = TelegramBridgeLogger;
+interface PluginApi {
+  logger: PluginLogger;
+  runtime?: PluginRuntime;
+  registerTool(tool: ToolDef): void;
+  registerService(service: {
+    id: string;
+    start(ctx: PluginServiceContext): void | Promise<void>;
+    stop?(ctx: PluginServiceContext): void | Promise<void>;
+  }): void;
+}
+declare const plugin: {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  activate(api: PluginApi): void;
+  deactivate(api: PluginApi): Promise<void>;
+};
+//#endregion
+export { plugin as default };

package/dist/plugin.d.ts

@@ -0,0 +1,58 @@
+import { r as TelegramBridgeLogger } from "./telegram-bridge.js";
+
+//#region ../openclaw-plugin-kit/dist/index.d.ts
+
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/tools.d.ts
+/** Shape returned to OpenClaw from a tool `execute`. */
+interface ToolResult {
+  content: {
+    type: "text";
+    text: string;
+  }[];
+  details: unknown;
+  isError?: boolean;
+}
+interface ToolDef<TParameters = unknown> {
+  name: string;
+  description: string;
+  label: string;
+  parameters: TParameters;
+  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
+}
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
+//#endregion
+//#region src/plugin.d.ts
+interface PluginRuntime {
+  config: {
+    loadConfig(): Record<string, unknown>;
+  };
+  channel: unknown;
+}
+interface PluginServiceContext {
+  logger: PluginLogger;
+  stateDir: string;
+  config: Record<string, unknown>;
+}
+type PluginLogger = TelegramBridgeLogger;
+interface PluginApi {
+  logger: PluginLogger;
+  runtime?: PluginRuntime;
+  registerTool(tool: ToolDef): void;
+  registerService(service: {
+    id: string;
+    start(ctx: PluginServiceContext): void | Promise<void>;
+    stop?(ctx: PluginServiceContext): void | Promise<void>;
+  }): void;
+}
+declare const plugin: {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  activate(api: PluginApi): void;
+  deactivate(api: PluginApi): Promise<void>;
+};
+//#endregion
+export { plugin as default };