metheus-governance-mcp-cli 0.2.69 → 0.2.71

package/README.md

@@ -55,7 +55,8 @@ TELEGRAM_BOT_TOKEN=
 
 # Preferred named bot mapping
 TELEGRAM_BOT_MAIN_SERVER_BOT_ID=
-TELEGRAM_BOT_MAIN_USERNAME=<bot_username>
+# Optional fallback only when server bot binding is unavailable
+# TELEGRAM_BOT_MAIN_USERNAME=<bot_username>
 TELEGRAM_BOT_MAIN_TOKEN=
 TELEGRAM_BOT_MAIN_ROLE_PROFILE=monitor
 TELEGRAM_BOT_MAIN_AI_CLIENT=codex
@@ -225,17 +226,19 @@ metheus-governance-mcp-cli bot verify --provider telegram --bot-key main
 Behavior:
 
 - `bot setup` asks for `Telegram / Slack / KakaoTalk` first, then prompts with numbered actions.
-- `bot add` without flags starts a guided question flow: provider -> bot responsibility -> local bot key -> token -> verify.
-- For Telegram, the CLI asks for the server-side bot responsibility first and automatically resolves the matching server bot profile when the role is unique.
-- When you choose a Telegram responsibility such as `monitor`, the CLI automatically uses that server role as the local `role_profile` and fills blank AI defaults from your local `bot-runner.json` `role_profiles` mapping.
-- `bot edit` without flags starts a guided numbered flow: provider -> bot entry -> guided edit -> step-by-step field choices.
-- In guided `bot edit`, changing the bound Telegram responsibility can also auto-fill blank local AI fields from the selected server role and skip redundant role/AI prompts.
+- `bot add` without flags now uses the shortest practical guided flow: provider -> token -> verify -> optional save-anyway only when verify fails -> optional username fallback only when verify cannot discover it -> optional default bot.
+- In the normal Telegram path, `bot add` does not ask for a local bot key, a server bot UUID, or an approval / worker / review / monitor choice.
+- For Telegram, the local env key is auto-generated from the matched server bot name or verified username, so you do not have to invent a separate local nickname first.
+- For Telegram, the CLI tries to match the verified bot identity against the server `me/bots` list first. If the server exposes one logical bot name with multiple roles such as `approval`, `worker`, `review`, and `monitor`, the CLI does not ask you to choose one UUID. It binds by server bot name and keeps the local role/AI fields empty so runtime can use the server bot role for each route.
+- When the Telegram username matches exactly one server bot role, the CLI still auto-fills the local `role_profile` and blank AI defaults from your local `bot-runner.json` `role_profiles` mapping.
+- `bot edit` without flags now uses the same sequential flow every time: provider -> bot entry -> username/token review -> AI field choices -> default choice -> save.
+- In the normal Telegram edit path, the CLI keeps or re-resolves the server bot binding automatically. It no longer asks you to pick `approval / worker / review / monitor` or a server bot UUID first.
 - `bot set-default` without flags starts a guided numbered flow: provider -> bot entry -> confirm default change.
 - `bot verify` without flags starts a guided numbered flow: provider -> bot entry -> output format.
 - `bot remove` without flags starts a guided numbered flow: provider -> bot entry -> confirm removal.
 - Telegram supports named local bot entries with:
   - `SERVER_BOT_ID`
-  - `USERNAME`
+  - `USERNAME` (optional fallback only when server binding is unavailable)
   - `TOKEN`
   - `ROLE_PROFILE`
   - `AI_CLIENT`
@@ -253,7 +256,8 @@ Non-interactive examples:
 
 ```bash
 metheus-governance-mcp-cli bot global --provider telegram --non-interactive true --api-base-url http://127.0.0.1:8999/telegram --auto-clear-webhook false --allowed-updates message,edited_message,channel_post
-metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --bot-key main --server-bot-id <server_bot_uuid> --username <telegram_username> --token <telegram_bot_token> --role-profile monitor --ai-client codex --ai-model gpt-5-codex --ai-permission-mode read_only --ai-reasoning-effort low --default true
+metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --server-bot-id <server_bot_uuid> --token <telegram_bot_token> --default true
+metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --server-bot-id <server_bot_uuid> --token <telegram_bot_token> --ai-client codex --ai-model gpt-5-codex --ai-permission-mode read_only --ai-reasoning-effort low
 metheus-governance-mcp-cli bot edit --provider telegram --bot-key main --non-interactive true --ai-client claude --ai-model claude-sonnet --ai-permission-mode workspace_write --ai-reasoning-effort medium
 metheus-governance-mcp-cli bot set-default --provider telegram --bot-key main --non-interactive true
 metheus-governance-mcp-cli bot migrate --provider telegram --bot-key main --server-bot-id <server_bot_uuid> --bot-name <telegram_username> --role-profile monitor --ai-client codex --ai-permission-mode read_only --ai-reasoning-effort low --non-interactive true
@@ -261,6 +265,8 @@ metheus-governance-mcp-cli bot remove --provider telegram --bot-key main --non-i
 metheus-governance-mcp-cli bot verify --provider telegram --bot-key main --json true
 ```
 
+For direct Telegram adds, the CLI can derive the local entry key from the matched server bot name. You no longer need `--bot-key` or `--username` in the normal server-bound path. Treat `--bot-key` as an advanced override only when you intentionally want a different local suffix.
+
 Current support status:
 
 - Telegram: full local bot entry management, token verification, bot-to-AI binding, inbound runner support

package/cli.mjs

@@ -748,7 +748,7 @@ function providerEnvTemplate(provider) {
       "# Preferred v2 multi-bot mapping:",
       "# TELEGRAM_DEFAULT_BOT_KEY=main",
       "# TELEGRAM_BOT_MAIN_SERVER_BOT_ID=<server bot uuid>",
-      "# TELEGRAM_BOT_MAIN_USERNAME=<bot username>",
+      "# TELEGRAM_BOT_MAIN_USERNAME=<optional fallback username when server binding is unavailable>",
       "# TELEGRAM_BOT_MAIN_TOKEN=<bot token>",
       "# TELEGRAM_BOT_MAIN_ROLE_PROFILE=monitor",
       "# TELEGRAM_BOT_MAIN_AI_CLIENT=codex",
@@ -766,7 +766,6 @@ function providerEnvTemplate(provider) {
       "",
       "# Preferred named bot entry",
       "TELEGRAM_BOT_MAIN_SERVER_BOT_ID=",
-      "TELEGRAM_BOT_MAIN_USERNAME=",
       "TELEGRAM_BOT_MAIN_TOKEN=",
       "TELEGRAM_BOT_MAIN_ROLE_PROFILE=",
       "TELEGRAM_BOT_MAIN_AI_CLIENT=",
@@ -2730,7 +2729,9 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
     selected = entries.find((entry) => entry.serverBotID === desiredBotID) || null;
   }
   if (!selected && desiredUsername) {
-    selected = entries.find((entry) => entry.username === desiredUsername) || null;
+    selected = entries.find(
+      (entry) => entry.username === desiredUsername || normalizeTelegramBotUsername(entry.key) === desiredUsername,
+    ) || null;
   }
   if (!selected && desiredBotKey) {
     selected = entries.find((entry) => entry.key === desiredBotKey) || null;
@@ -3697,8 +3698,9 @@ async function runDoctor(flags) {
         }
         const detailParts = [];
         if (envConfig.botKey) detailParts.push(`bot=${envConfig.botKey}`);
-        if (envConfig.botUsername) detailParts.push(`@${envConfig.botUsername}`);
-        if (envConfig.serverBotID) detailParts.push(`server_bot_id=${envConfig.serverBotID}`);
+      if (envConfig.botUsername) detailParts.push(`@${envConfig.botUsername}`);
+      if (envConfig.serverBotID) detailParts.push(`server_bot_id=${envConfig.serverBotID}`);
+        else if (envConfig.botKey) detailParts.push(`server_name=${envConfig.botKey}`);
         if (envConfig.client) detailParts.push(`ai=${envConfig.client}`);
         addDoctorCheck(
           rows,
@@ -3715,12 +3717,28 @@ async function runDoctor(flags) {
           );
         }
         if (route.botID && !envConfig.serverBotID) {
-          addDoctorCheck(
-            rows,
-            strictMode ? "fail" : "warn",
-            `runner route ${routeLabel} server_bot_id`,
-            `route bot_id ${route.botID} is set, but local env entry does not carry SERVER_BOT_ID`,
+          const serverMatch = ensureArray(serverBots).find((bot) => String(bot.id || "").trim() === String(route.botID || "").trim());
+          const routeBotName = normalizeTelegramBotUsername(
+            firstNonEmptyString([route.botName, route.bot_name, serverMatch?.name]),
           );
+          const envBotName = normalizeTelegramBotUsername(envConfig.botUsername || envConfig.botKey);
+          if (routeBotName && envBotName && routeBotName === envBotName) {
+            addDoctorCheck(
+              rows,
+              "ok",
+              `runner route ${routeLabel} server bot`,
+              envConfig.botUsername
+                ? `resolved by bot username @${envConfig.botUsername}`
+                : `resolved by server bot name ${envConfig.botKey}`,
+            );
+          } else {
+            addDoctorCheck(
+              rows,
+              strictMode ? "fail" : "warn",
+              `runner route ${routeLabel} server_bot_id`,
+              `route bot_id ${route.botID} is set, but local env entry does not carry SERVER_BOT_ID`,
+            );
+          }
         }
         if (serverBots && route.botID) {
           const match = ensureArray(serverBots).find((bot) => String(bot.id || "").trim() === String(route.botID || "").trim());