@alfe.ai/openclaw-telegram 0.0.1

package/README.md

@@ -0,0 +1,41 @@
+# `@alfe.ai/openclaw-telegram`
+
+Local Telegram user-session access for an Alfe/OpenClaw agent. It uses
+Telethon/MTProto, so it can see the same dialog list as the signed-in Telegram
+account instead of the restricted Bot API view.
+
+The Telegram device session never leaves the agent machine. After enabling the
+Telegram Connection in Alfe, run:
+
+```bash
+npx -y @alfe.ai/openclaw-telegram@0.0.1 login --agent-id <agent-id>
+```
+
+If the package binary is already on `PATH`, `alfe-telegram login` is the
+equivalent shorthand. The dashboard supplies the agent-specific command; when
+`--agent-id` is omitted, the CLI resolves it from the local agent token.
+
+The command creates an isolated local Python runtime, asks for the API ID/hash
+from `my.telegram.org`, then completes phone-code and optional 2FA login. It
+does not print the resulting session.
+
+Agent tools:
+
+- `telegram_status`
+- `telegram_list_chats`
+- `telegram_list_subscriptions`
+- `telegram_subscribe`
+- `telegram_unsubscribe`
+
+Subscriptions are explicit and read-only toward Telegram. Incoming text and
+captions can trigger agent turns; generated responses are not posted back.
+Only subscribe where you have permission to process the messages, and follow
+Telegram's API terms.
+
+Removing the Alfe Connection stops and uninstalls the listener but deliberately
+does not erase a logged-in device during an ordinary reinstall. Before retiring
+the machine, revoke the device session and remove its local state with:
+
+```bash
+npx -y @alfe.ai/openclaw-telegram@0.0.1 logout --agent-id <agent-id>
+```

package/bin/alfe-telegram.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { AgentApiClient } from '@alfe.ai/agent-api-client'
+import { resolveConfig } from '@alfe.ai/config'
+
+const TELETHON_VERSION = '1.44.0'
+const MAX_AGENT_ID_CHARS = 256
+const SAFE_AGENT_ID = /^[A-Za-z0-9_-]+$/u
+const packageDir = dirname(dirname(fileURLToPath(import.meta.url)))
+const bridgeScript = join(packageDir, 'python', 'bridge.py')
+
+function privateEnv() {
+  const result = {}
+  for (const key of ['HOME', 'PATH', 'LANG', 'LC_ALL', 'TMPDIR', 'SYSTEMROOT', 'WINDIR']) {
+    if (process.env[key] !== undefined) result[key] = process.env[key]
+  }
+  result.PYTHONUNBUFFERED = '1'
+  return result
+}
+
+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 agent ID')
+  return value
+}
+
+async function resolveAgentId(explicitAgentId) {
+  if (explicitAgentId) return requireAgentId(explicitAgentId)
+  try {
+    const config = resolveConfig()
+    const identity = await new AgentApiClient({ apiKey: config.apiKey, apiUrl: config.apiUrl }).whoami()
+    return requireAgentId(identity.agentId)
+  } catch {
+    throw new Error('Could not resolve this agent identity. Pass --agent-id from the dashboard setup command.')
+  }
+}
+
+function localPaths(agentId) {
+  const stateDir = join(homedir(), '.alfe', 'agents', requireAgentId(agentId), 'telegram')
+  const runtimeDir = join(stateDir, 'runtime')
+  return {
+    stateDir,
+    runtimeDir,
+    markerFile: join(runtimeDir, '.telethon-version'),
+  }
+}
+
+function runtimePython(runtimeDir) {
+  const unix = join(runtimeDir, 'bin', 'python3')
+  if (existsSync(unix)) return unix
+  return join(runtimeDir, 'Scripts', 'python.exe')
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    stdio: 'inherit',
+    env: privateEnv(),
+  })
+  if (result.error) return 1
+  return result.status ?? 1
+}
+
+function markerMatches(markerFile) {
+  try {
+    return readFileSync(markerFile, 'utf8').trim() === TELETHON_VERSION
+  } catch {
+    return false
+  }
+}
+
+function installRuntime(paths) {
+  mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 })
+  if (!existsSync(runtimePython(paths.runtimeDir))) {
+    console.log('Creating the private Telegram Python runtime…')
+    const created = run('python3', ['-m', 'venv', paths.runtimeDir])
+    if (created !== 0) {
+      console.error('Could not create the Python runtime. Install Python 3 with venv support and retry.')
+      return created
+    }
+  }
+  if (markerMatches(paths.markerFile)) return 0
+  console.log(`Installing Telethon ${TELETHON_VERSION} into the private runtime…`)
+  const installed = run(runtimePython(paths.runtimeDir), [
+    '-m', 'pip', 'install',
+    '--disable-pip-version-check',
+    '--no-input',
+    `Telethon==${TELETHON_VERSION}`,
+  ])
+  if (installed !== 0) {
+    console.error('Could not install Telethon. Check this machine\'s network access and retry.')
+    return installed
+  }
+  writeFileSync(paths.markerFile, `${TELETHON_VERSION}\n`, { mode: 0o600 })
+  return 0
+}
+
+function printStatus(agentId, paths) {
+  const runtimeInstalled = existsSync(runtimePython(paths.runtimeDir)) && markerMatches(paths.markerFile)
+  const configured = existsSync(join(paths.stateDir, 'config.json'))
+  const sessionPresent = existsSync(join(paths.stateDir, 'user.session'))
+  console.log(`Agent: ${agentId}`)
+  console.log(`Runtime installed: ${runtimeInstalled ? 'yes' : 'no'}`)
+  console.log(`Login configured: ${configured && sessionPresent ? 'yes' : 'no'}`)
+  console.log(`Local state directory: ${paths.stateDir}`)
+  return configured && sessionPresent ? 0 : 1
+}
+
+function parseAgentId(args) {
+  let agentId
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index]
+    if (value === '--agent-id') {
+      agentId = args[index + 1]
+      if (!agentId) throw new Error('--agent-id requires a value')
+      index += 1
+      continue
+    }
+    if (value?.startsWith('--agent-id=')) {
+      agentId = value.slice('--agent-id='.length)
+      if (!agentId) throw new Error('--agent-id requires a value')
+      continue
+    }
+    throw new Error(`Unknown option: ${value ?? ''}`)
+  }
+  return agentId
+}
+
+function usage() {
+  console.log(`Usage:
+  alfe-telegram login [--agent-id ID]            Install the local runtime and sign in privately
+  alfe-telegram logout [--agent-id ID]           Revoke this agent's Telegram device session and remove local state
+  alfe-telegram install-runtime [--agent-id ID]  Install/update this agent's pinned Telethon runtime
+  alfe-telegram status [--agent-id ID]           Check this agent's local setup without revealing credentials`)
+}
+
+async function main() {
+  const command = process.argv[2] ?? 'help'
+  if (command === 'help' || command === '--help' || command === '-h') {
+    usage()
+    return 0
+  }
+  if (!['install-runtime', 'login', 'logout', 'status'].includes(command)) {
+    usage()
+    return 2
+  }
+
+  let agentId
+  try {
+    agentId = await resolveAgentId(parseAgentId(process.argv.slice(3)))
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : 'Could not resolve agent identity.')
+    return 2
+  }
+  const paths = localPaths(agentId)
+
+  if (command === 'install-runtime') return installRuntime(paths)
+  if (command === 'login') {
+    const installed = installRuntime(paths)
+    if (installed !== 0) return installed
+    return run(runtimePython(paths.runtimeDir), [bridgeScript, 'login', '--state-dir', paths.stateDir])
+  }
+  if (command === 'logout') {
+    if (!existsSync(runtimePython(paths.runtimeDir))) {
+      console.error('The local Telegram runtime is not installed for this agent.')
+      return 1
+    }
+    return run(runtimePython(paths.runtimeDir), [bridgeScript, 'logout', '--state-dir', paths.stateDir])
+  }
+  return printStatus(agentId, paths)
+}
+
+process.exitCode = await main()

package/dist/index.cjs

@@ -0,0 +1,4 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_telegram_bridge = require("./telegram-bridge.cjs");
+exports.TelegramBridge = require_telegram_bridge.TelegramBridge;
+exports.TelegramBridgeUnavailable = require_telegram_bridge.TelegramBridgeUnavailable;

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { a as TelegramBridgeUnavailable, i as TelegramBridgeStatus, n as TelegramBridgeEvent, r as TelegramBridgeLogger, t as TelegramBridge } from "./telegram-bridge.cjs";
+export { TelegramBridge, type TelegramBridgeEvent, type TelegramBridgeLogger, type TelegramBridgeStatus, TelegramBridgeUnavailable };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { a as TelegramBridgeUnavailable, i as TelegramBridgeStatus, n as TelegramBridgeEvent, r as TelegramBridgeLogger, t as TelegramBridge } from "./telegram-bridge.js";
+export { TelegramBridge, type TelegramBridgeEvent, type TelegramBridgeLogger, type TelegramBridgeStatus, TelegramBridgeUnavailable };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { n as TelegramBridgeUnavailable, t as TelegramBridge } from "./telegram-bridge.js";
+export { TelegramBridge, TelegramBridgeUnavailable };