@agfpd/iapeer 0.4.22 → 0.4.24

package/CHANGELOG.md

@@ -10,6 +10,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.24] - 2026-06-22
+
+### Fixed
+
+- **`iapeer connect telegram <peer>` (and the `enable telegram` alias) no longer fails for a
+  peer whose personality isn't a valid Telegram @username** (e.g. a hyphen: "impact-finder").
+  connect passed the PERSONALITY as the bot @username to telegram-runtime (which keys bots by
+  `<bot-username>`), so a hyphenated personality was rejected ("must be a telegram @username").
+  The bot @username is TOKEN-derived (set in @BotFather), never the personality. connect now
+  resolves it from the token via Telegram **getMe** and uses that for `bot add` / `interface
+  bot` / storage; the human still owes only the token. An invalid/unreachable token fails
+  early with a getMe-rejected message. (The getMe lives in the telegram-glue module
+  `connect/index.ts` — the foundation core stays Telegram-API-free.)
+
+## [0.4.23] - 2026-06-22
+
+### Added
+
+- **`iapeer enable telegram <peer>`** — a discoverability alias for `iapeer connect telegram
+  <peer>` (give an existing peer a Telegram bot face). A layperson reaches for "enable
+  telegram", not "connect"; both now work and route through the same flow (bot add →
+  interface → router restart; asks only the token). telegram is a CHANNEL, not a marketplace
+  plugin, so the alias routes to the connect flow, not `enableCapability`. The `connect`
+  help line documents the alias. No telegram-runtime change (the mechanism already worked) —
+  purely CLI discoverability.
+
 ## [0.4.22] - 2026-06-22
 
 ### Added
@@ -340,7 +366,9 @@ Initial public release — the foundation core of the iapeer multi-agent ecosyst
 - **Heterogeneous peers** — AI agents (Claude, Codex), humans (Telegram), and services
   (timer = cron, watcher = event) are all first-class and addressed the same way.
 
-[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.22...HEAD
+[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.24...HEAD
+[0.4.24]: https://github.com/agfpd/iapeer/compare/v0.4.23...v0.4.24
+[0.4.23]: https://github.com/agfpd/iapeer/compare/v0.4.22...v0.4.23
 [0.4.22]: https://github.com/agfpd/iapeer/compare/v0.4.21...v0.4.22
 [0.4.21]: https://github.com/agfpd/iapeer/compare/v0.4.20...v0.4.21
 [0.4.20]: https://github.com/agfpd/iapeer/compare/v0.4.19...v0.4.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/cli/index.ts

@@ -875,6 +875,41 @@ export async function removePeerCli(
   }
 }
 
+/**
+ * `connect telegram <peer>` core — give a peer a Telegram bot face (interfaces.telegram).
+ * Shared by the `connect telegram` verb AND the `enable telegram <peer>` discoverability
+ * alias (telegram is a CHANNEL, not a marketplace plugin, so both route here, not through
+ * enableCapability). Returns the process exit code. The human owes only the token (prompted
+ * when omitted on a tty); the system does bot-add → interface → router restart.
+ */
+async function connectTelegramVerb(
+  peer: string,
+  token: string | undefined,
+  env: NodeJS.ProcessEnv,
+  out: (s: string) => void,
+  errOut: (s: string) => void,
+): Promise<number> {
+  const { connectTelegram } = await import('../connect/index.ts')
+  const r = await connectTelegram({ peer, token, env })
+  if (r.state === 'noop-same-token') {
+    out(`connect telegram ${r.peer}: ${r.detail}\n`)
+    return 0
+  }
+  if (r.state !== 'connected') {
+    errOut(`connect telegram ${r.peer}: ${r.state}${r.detail ? ` — ${r.detail}` : ''}\n`)
+    return 1
+  }
+  const rs = r.restart!
+  out(`bot ${r.username ?? `for "${r.peer}"`} added + interfaced to "${r.peer}"\n`)
+  out(
+    rs.state === 'restarted'
+      ? `router restarted — credentials loaded\n`
+      : `router restart ${rs.state}${rs.detail ? ` — ${rs.detail}` : ''} (the channel stays dead until the router restarts)\n`,
+  )
+  out(`activation: send the bot ${r.username ?? '(see @BotFather)'} its FIRST message — Telegram does not let a bot start the chat\n`)
+  return rs.state === 'restarted' ? 0 : 1
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // rename — first-class peer-identity rename (parity with remove/create). Wraps
 // renamePeer (registry + per-cwd profile, atomic, inside the lock) and KEEPS the
@@ -1168,7 +1203,7 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     desc: 'manual IAP send (fallback)',
   },
   { sig: '<runtime>', desc: "launch the cwd's peer FRESH; on a TTY drop into it (like attach), else detached" },
-  { sig: 'connect telegram <peer> [--token <t>]', desc: 'attach a telegram bot to a peer (bot add → interface → router restart; asks only the token)' },
+  { sig: 'connect telegram <peer> [--token <t>]', desc: 'attach a telegram bot to a peer (bot add → interface → router restart; asks only the token). Alias: `iapeer enable telegram <peer>`' },
   { sig: 'enable <plugin> [peer] [--no-setup]', desc: 'install + enable an agfpd capability for a peer' },
   {
     sig: 'new <peer> [runtime]',
@@ -2287,31 +2322,16 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         // alias/bot-add/interface/router-restart are resolved by the system. The
         // FIRST message from the human to the bot activates the chat (platform rule).
         if (positionals[0] !== 'telegram' || !positionals[1]) return argErr(errOut, 'connect needs "telegram <peer>" — usage: iapeer connect telegram <peer> [--token <t>] (e.g. iapeer connect telegram boris)')
-        const { connectTelegram } = await import('../connect/index.ts')
-        const r = await connectTelegram({
-          peer: positionals[1],
-          token: typeof flags.token === 'string' ? flags.token : undefined,
-          env,
-        })
-        if (r.state === 'noop-same-token') {
-          out(`connect telegram ${r.peer}: ${r.detail}\n`)
-          return 0
-        }
-        if (r.state !== 'connected') {
-          errOut(`connect telegram ${r.peer}: ${r.state}${r.detail ? ` — ${r.detail}` : ''}\n`)
-          return 1
-        }
-        const rs = r.restart!
-        out(`bot ${r.username ?? `for "${r.peer}"`} added + interfaced to "${r.peer}"\n`)
-        out(
-          rs.state === 'restarted'
-            ? `router restarted — credentials loaded\n`
-            : `router restart ${rs.state}${rs.detail ? ` — ${rs.detail}` : ''} (the channel stays dead until the router restarts)\n`,
-        )
-        out(`activation: send the bot ${r.username ?? '(see @BotFather)'} its FIRST message — Telegram does not let a bot start the chat\n`)
-        return rs.state === 'restarted' ? 0 : 1
+        return await connectTelegramVerb(positionals[1], typeof flags.token === 'string' ? flags.token : undefined, env, out, errOut)
       }
       case 'enable': {
+        // DISCOVERABILITY ALIAS: `enable telegram <peer>` → `connect telegram <peer>`
+        // (a layperson reaches for "enable telegram"; telegram is a CHANNEL, not a
+        // marketplace plugin, so it routes to the connect flow, NOT enableCapability).
+        if (positionals[0] === 'telegram') {
+          if (!positionals[1]) return argErr(errOut, 'enable telegram needs a peer — usage: iapeer enable telegram <peer> [--token <t>] (alias of `iapeer connect telegram <peer>`)')
+          return await connectTelegramVerb(positionals[1], typeof flags.token === 'string' ? flags.token : undefined, env, out, errOut)
+        }
         // Per-peer capability install (contract Установка §3): install <plugin>@agfpd
         // per-runtime (claude project-scope IN the peer cwd / codex global) + enable +
         // call the plugin's `setup` ONLY if its iapeer.json declares it. Idempotent and

package/src/connect/index.ts

@@ -5,9 +5,11 @@
 //
 // The human owes EXACTLY ONE external fact: the bot token (prompt walks them
 // through @BotFather → /newbot). Everything else the system resolves: the bot
-// alias (= the peer's personality), `telegram-runtime bot add` (owner adds getMe
-// validation — an invalid token fails THERE, early), `telegram-runtime interface
-// bot` (profile merge; precondition: the peer is registered), then the MANDATORY
+// @username via Telegram getMe(token) — the bot key is TOKEN-derived, NOT the peer
+// personality (a personality may contain a hyphen, structurally invalid as a
+// @username; telegram-runtime keys bots by <bot-username>), `telegram-runtime bot add`
+// (also validates the token), `telegram-runtime interface bot` (profile merge;
+// precondition: the peer is registered), then the MANDATORY
 // router-session restart (the live poller reads bots/ ONCE at start, no fs-watch —
 // without the restart the channel is dead both ways), and the activation hint:
 // the FIRST message from the human to the bot opens the chat (a Telegram platform
@@ -51,6 +53,9 @@ export interface ConnectTelegramOptions {
   runTg?: TgRunner
   /** Injectable router restart (tests). Default: stopPeer→startPeer strictly in order. */
   restart?: RestartFn
+  /** Injectable bot-@username resolver (tests). Default: Telegram getMe(token). Returns the
+   *  bare @username (no leading @) or null on a rejected/unreachable token. */
+  resolveUsername?: (token: string) => Promise<string | null>
 }
 
 export interface ConnectTelegramResult {
@@ -60,6 +65,7 @@ export interface ConnectTelegramResult {
     | 'refused-no-token' // non-tty and no --token (or an empty tty answer)
     | 'unregistered-peer' // precondition: the peer must be in the registry
     | 'runtime-missing' // no telegram runtime manifest — install it first
+    | 'bad-token' // Telegram getMe rejected the token (invalid/revoked) or was unreachable
     | 'bot-add-failed' // telegram-runtime bot add exited non-zero (incl. getMe refusal)
     | 'interface-failed' // telegram-runtime interface bot exited non-zero
   peer: string
@@ -93,6 +99,26 @@ function readBotEnv(alias: string, env: NodeJS.ProcessEnv): string | null {
   }
 }
 
+/**
+ * Resolve the bot's REAL @username from the token via Telegram getMe — the bot identity
+ * is TOKEN-derived (BotFather sets it), NOT the peer personality. telegram-runtime keys
+ * bots by `<bot-username>` (`bot add <bot-username>`, `interface bot <bot-username>`), and a
+ * personality can contain a hyphen which is structurally invalid as a @username — so the
+ * personality can NEVER be the bot-username. Returns the bare username (no leading @) or
+ * null on a rejected/unreachable token. The token goes literally in the URL path
+ * (Telegram tokens are `<digits>:<urlsafe>`; no encoding).
+ */
+async function defaultResolveBotUsername(token: string): Promise<string | null> {
+  try {
+    const r = await fetch(`https://api.telegram.org/bot${token}/getMe`)
+    const j = (await r.json()) as { ok?: boolean; result?: { username?: unknown } }
+    const u = j?.ok === true && typeof j.result?.username === 'string' ? j.result.username.trim().replace(/^@/, '') : ''
+    return u || null
+  } catch {
+    return null // network error / non-JSON → treat as unresolvable (bad-token)
+  }
+}
+
 /** Resolve the telegram-runtime CLI bin from the manifest's selfConfig command (the
  *  package's own absolute bin — PATH-independent, launchd-safe). */
 function resolveTgBin(env: NodeJS.ProcessEnv): string | null {
@@ -173,8 +199,17 @@ export async function connectTelegram(opts: ConnectTelegramOptions): Promise<Con
     if (!token) return { state: 'refused-no-token', peer, detail: 'no answer — nothing connected' }
   }
 
+  // Resolve the bot's REAL @username from the token (getMe) — NOT the personality. The
+  // bot-username is token-derived; a personality with a hyphen (e.g. "impact-finder") is
+  // structurally invalid as a @username and telegram-runtime (which keys bots by
+  // <bot-username>) rejects it. getMe also validates the token early (bad token → fail here).
+  const resolveUsername = opts.resolveUsername ?? defaultResolveBotUsername
+  const botUsername = await resolveUsername(token)
+  if (!botUsername) {
+    return { state: 'bad-token', peer, detail: 'Telegram getMe rejected the token (invalid/revoked) or was unreachable — recheck the token with @BotFather' }
+  }
   const runTg = opts.runTg ?? defaultRunTg(tgBin)
-  const alias = peer // bot alias = the peer's personality (design §(в); passes the owner's NAME_RE)
+  const alias = botUsername // bot key = the REAL @username from getMe (telegram-runtime keys bots by <bot-username>)
   const before = readBotEnv(alias, env)
 
   // (1) bot add — token → bots/<alias>/.env. Owner adds getMe validation here: an
@@ -183,17 +218,10 @@ export async function connectTelegram(opts: ConnectTelegramOptions): Promise<Con
   if (add.status !== 0) {
     return { state: 'bot-add-failed', peer, detail: (add.stderr || add.stdout || `exit ${add.status}`).trim() }
   }
-  // @username: the bots/<alias>/.env TELEGRAM_BOT_USERNAME field is the RELIABLE
-  // source (present on the live host; survives a quiet bot-add stdout — acceptance
-  // testing saw the activation line degrade to the BotFather hint). stdout
-  // match stays as the fallback.
-  const envAfterAdd = readBotEnv(alias, env)
-  const envUser = envAfterAdd?.match(/^TELEGRAM_BOT_USERNAME=(.+)$/m)?.[1]?.trim()
-  const username = envUser
-    ? envUser.startsWith('@')
-      ? envUser
-      : `@${envUser}`
-    : add.stdout.match(/@[A-Za-z0-9_]{3,}/)?.[0]
+  // @username for display / the activation hint: the bot key (alias) IS the
+  // getMe-resolved username, so the display form is simply `@<alias>` — no need to
+  // re-parse bots/<alias>/.env (telegram-runtime writes the same value there).
+  const username = `@${alias}`
 
   // (2) interface bot — merge the channel binding into the peer's profile.
   const iface = runTg(['interface', 'bot', alias, '--peer', peer], env)