@agfpd/iapeer 0.4.21 → 0.4.23

package/CHANGELOG.md

@@ -10,6 +10,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`iapeer live-runtime <peer>`** — prints the peer's CURRENT live runtime: the
+  freshest-pane-log among its **pid-alive** supervisor sessions (a peer can be alive on
+  more than one runtime at once — a `/codex` flip can leave the old session running
+  alongside the new). This is the authoritative, real-time signal for "what runtime is
+  this peer running right now" — NOT `default_runtime` (only the wake-default) and NOT a
+  `.session` wake-record (alive-filtered only on a supervise-tick latency). Exit 0 + the
+  runtime on stdout when one is live; exit 1 + no output when none is alive. For external
+  consumers (e.g. telegram-runtime's typing/tool-use indicator) that must resolve the live
+  runtime of a peer running on a non-default runtime, instead of inferring it. Exposed as
+  `resolveLiveRuntime` (transport).
+
 ## [0.4.21] - 2026-06-22
 
 ### Fixed
@@ -325,7 +352,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.21...HEAD
+[Unreleased]: https://github.com/agfpd/iapeer/compare/v0.4.23...HEAD
+[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
 [0.4.19]: https://github.com/agfpd/iapeer/compare/v0.4.18...v0.4.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.21",
+  "version": "0.4.23",
   "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
@@ -1139,6 +1174,7 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     desc: 'backbone host-phase: marketplace → notifier → telegram (human peer) → memory → voice (all default YES). --accept-risk (or IAPEER_ACCEPT_RISK=1) accepts the security warning non-interactively',
   },
   { sig: 'status', desc: 'host snapshot: version, daemon health, memory + voice slots (<provider> | none)' },
+  { sig: 'live-runtime <peer>', desc: 'print the peer\'s CURRENT live runtime (freshest pane-log among pid-alive sessions; NOT default_runtime). Exit 1 + no output if none alive' },
   { sig: 'install-runtime <runtime> [--package pkg] [--npx]', desc: 'npx-install a runtime package + deploy its declared peer-set' },
   { sig: 'update-runtime <runtime> | --all [--force]', desc: "version-gate → re-install + re-provision declared set → restart the runtime's peers" },
   { sig: 'init [cwd] [--runtime r] [--description d]', desc: 'onboard the CURRENT folder as a peer (name = folder name; identity + MCP + doctrine)' },
@@ -1167,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]',
@@ -1501,6 +1537,21 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(formatHostStatus(s))
         return s.daemon.healthy ? 0 : 1
       }
+      case 'live-runtime': {
+        // The AUTHORITATIVE current live runtime of a peer (machine-readable, for external
+        // consumers like telegram-runtime's typing indicator). Prints the runtime the peer
+        // is RUNNING right now — the freshest-pane-log among its PID-alive supervisor
+        // sessions — NOT default_runtime (the wake-default) and NOT a .session wake-record.
+        // A peer can be alive on >1 runtime (a /codex flip leaves both); this picks the
+        // currently-active. Exit 0 + the runtime on stdout when one is live; exit 1 + no
+        // output when none is alive (queryable: `rt=$(iapeer live-runtime <p>) || handle-down`).
+        if (!positionals[0]) return argErr(errOut, 'live-runtime needs a peer name — usage: iapeer live-runtime <peer>')
+        const { resolveLiveRuntime } = await import('../transport/index.ts')
+        const rt = resolveLiveRuntime(positionals[0])
+        if (!rt) return 1 // no live session — no output, non-zero
+        out(`${rt}\n`)
+        return 0
+      }
       case 'install-runtime': {
         // §6 onboard a runtime END-TO-END: npx-install the package (auto-resolved from
         // the built-in runtime→package registry, or --package; self-deploys bin +
@@ -2271,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/transport/index.ts

@@ -279,6 +279,33 @@ function defaultPaneLogMtime(address: string): number | null {
   }
 }
 
+/**
+ * The CURRENT live runtime of a peer — the AUTHORITATIVE, real-time signal for "what
+ * runtime is this peer running right now" (NOT default_runtime, which is only the wake
+ * DEFAULT, and NOT a `.session` file, a wake-record cleaned on a supervise-tick latency).
+ *
+ * Resolution: among the peer's PID-ALIVE supervisor sessions (listHostedPeers — the same
+ * source delivery uses; `sessionAlive` = pidfile exists AND kill-0), pick the one with the
+ * FRESHEST pane-log. A peer can be alive on >1 runtime at once (a `/codex` flip can leave
+ * the old session running alongside the new), so the freshest-pane-log among the alive set
+ * is the currently-active surface. The alive-filter is what fixes the flip-race: a
+ * just-died runtime's pane-log / .sock / .session all LINGER, but its pid is dead → it is
+ * excluded here. Returns null when no session is alive.
+ *
+ * Deps are injectable for hermetic tests (the defaults read the real run-dir + pane-logs).
+ */
+export function resolveLiveRuntime(
+  personality: string,
+  deps: { aliveRuntimes?: (p: string) => string[]; paneLogMtime?: (address: string) => number | null } = {},
+): string | null {
+  const aliveOf = deps.aliveRuntimes ?? ((p: string) => listHostedPeers().filter(h => h.personality === p).map(h => h.runtime))
+  const paneMt = deps.paneLogMtime ?? defaultPaneLogMtime
+  const alive = aliveOf(personality)
+  if (alive.length <= 1) return alive[0] ?? null
+  // >1 alive → the freshest pane-log mtime (the currently-rendering turn surface).
+  return alive.reduce((best, rt) => ((paneMt(`${rt}-${personality}`) ?? 0) > (paneMt(`${best}-${personality}`) ?? 0) ? rt : best))
+}
+
 
 // ─── Compact done gate (dialogue control must report FACT, not keystroke delivery) ──