metheus-governance-mcp-cli 0.2.61 → 0.2.63

package/README.md

@@ -10,6 +10,7 @@ Compatibility note: legacy command alias `metheus-governance-mcp` is still suppo
   - checks Codex/Claude/Gemini/Antigravity/Cursor MCP registration
   - registers only missing clients
 - `setup`: register `metheus-governance-mcp` into Codex/Claude/Gemini/Antigravity/Cursor (if installed)
+- `bot`: local chat bot env setup/list/show/add/edit/remove/global/verify
 - `doctor`: run end-to-end health checks (auth/registration/gateway/project/ctxpack/tools)
 - `proxy`: stdio MCP bridge to Metheus HTTPS gateway
 - `auth`: save/check/clear local Metheus token used by proxy
@@ -27,10 +28,10 @@ Install creates local provider settings templates here:
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
 
-These files are for local provider bot secrets only.
+These files are for local provider bot secrets, local transport options, and optional per-bot local AI binding.
 
 - Store locally:
-  - `TELEGRAM_BOT_TOKEN`
+  - `TELEGRAM_BOT_TOKEN` or named Telegram bot mappings such as `TELEGRAM_BOT_MAIN_TOKEN`
   - `SLACK_BOT_TOKEN`
   - `KAKAOTALK_BOT_TOKEN`
 - Server-side Metheus stores project chat destination metadata separately:
@@ -38,13 +39,30 @@ These files are for local provider bot secrets only.
   - `chat_id` / channel / room identifier
   - label / active state
 - Do not put project chat destination identifiers in local env files.
+- Telegram env can also carry per-bot local AI binding fields.
 
 Example templates:
 
 ```env
 # ~/.metheus/telegram.env
+TELEGRAM_API_BASE_URL=
+TELEGRAM_AUTO_CLEAR_WEBHOOK=true
+TELEGRAM_ALLOWED_UPDATES=message,edited_message
+TELEGRAM_DEFAULT_BOT_KEY=main
+
+# Legacy fallback
 TELEGRAM_BOT_TOKEN=
 
+# Preferred named bot mapping
+TELEGRAM_BOT_MAIN_SERVER_BOT_ID=
+TELEGRAM_BOT_MAIN_USERNAME=<bot_username>
+TELEGRAM_BOT_MAIN_TOKEN=
+TELEGRAM_BOT_MAIN_ROLE_PROFILE=monitor
+TELEGRAM_BOT_MAIN_AI_CLIENT=codex
+TELEGRAM_BOT_MAIN_AI_MODEL=
+TELEGRAM_BOT_MAIN_AI_PERMISSION_MODE=read_only
+TELEGRAM_BOT_MAIN_AI_REASONING_EFFORT=low
+
 # ~/.metheus/slack.env
 SLACK_BOT_TOKEN=
 
@@ -72,6 +90,17 @@ Runner template:
       "reasoning_effort": "low"
     }
   },
+  "bot_bindings": {
+    "primary_monitor_bot": {
+      "bot_id": "<server_bot_uuid>",
+      "bot_name": "<bot_name>",
+      "role_profile": "monitor",
+      "client": "codex",
+      "model": "",
+      "permission_mode": "read_only",
+      "reasoning_effort": "low"
+    }
+  },
   "routes": [
     {
       "name": "telegram-monitor",
@@ -79,12 +108,12 @@ Runner template:
       "project_id": "<project_uuid>",
       "provider": "telegram",
       "role": "monitor",
-      "role_profile": "monitor",
+      "bot_id": "<server_bot_uuid>",
       "trigger_policy": {
         "mentions_only": true,
         "direct_messages": true,
         "reply_to_bot_messages": true,
-        "ignore_edited_messages": false
+        "ignore_edited_messages": true
       },
       "archive_policy": {
         "mirror_replies": true,
@@ -134,13 +163,14 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
 
-Fill only provider bot tokens locally. Project chat destination identifiers should be managed on the Metheus server as project chat destinations, not as local env values and not inside legacy Chat Hooks/webhooks.
+Fill provider bot secrets and provider-local transport options locally. Project chat destination identifiers should be managed on the Metheus server as project chat destinations, not as local env values and not inside legacy Chat Hooks/webhooks.
 
 `~/.metheus/bot-runner.json` is the local automation profile for:
 - which project to watch
 - which provider/role bot profile to use
 - which `project_id -> workspace_dir` mapping to apply locally
 - which role profile maps to which local CLI/model/permission/reasoning policy
+- which server bot maps to which local LLM execution profile via `telegram.env` or fallback `bot_bindings`
 
 Built-in helper command for legacy fallback/testing:
 
@@ -169,6 +199,59 @@ Guardrail note:
 - By default, CLI blocks reading/writing ctxpack sync metadata when workspace root resolves to the home directory.
 - Override only when intentional: `METHEUS_ALLOW_HOME_WORKSPACE=1`.
 
+## Bot
+
+Interactive entry:
+
+```bash
+metheus-governance-mcp-cli bot setup
+```
+
+Direct commands:
+
+```bash
+metheus-governance-mcp-cli bot list
+metheus-governance-mcp-cli bot show --provider telegram --bot-key main
+metheus-governance-mcp-cli bot add --provider telegram
+metheus-governance-mcp-cli bot edit --provider telegram
+metheus-governance-mcp-cli bot remove --provider telegram
+metheus-governance-mcp-cli bot global --provider telegram
+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.
+- Telegram supports named local bot entries with:
+  - `SERVER_BOT_ID`
+  - `USERNAME`
+  - `TOKEN`
+  - `ROLE_PROFILE`
+  - `AI_CLIENT`
+  - `AI_MODEL`
+  - `AI_PERMISSION_MODE`
+  - `AI_REASONING_EFFORT`
+- Slack and KakaoTalk currently use a single local token entry per provider in this command flow.
+- `bot verify` checks the configured local token and prints the current AI binding summary.
+- `bot show` prints one local bot entry in detail.
+- `bot global` edits Telegram-wide local settings such as API base URL, allowed updates, and default bot key.
+
+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 --bot-id <server_bot_uuid> --token <telegram_bot_token> --role-profile monitor --client codex --permission-mode read_only --reasoning-effort low --default true
+metheus-governance-mcp-cli bot edit --provider telegram --bot-key main --non-interactive true --client claude --model claude-3.7-sonnet --permission-mode workspace_write --reasoning-effort medium
+metheus-governance-mcp-cli bot remove --provider telegram --bot-key main --non-interactive true
+metheus-governance-mcp-cli bot verify --provider telegram --bot-key main --json true
+```
+
+Current support status:
+
+- Telegram: full local bot entry management, token verification, bot-to-AI binding, inbound runner support
+- Slack: single local token entry, verification supported, inbound runner not supported
+- KakaoTalk: single local token entry, local config only, remote verification not implemented
+
 ## Project ID behavior (verified)
 
 - `setup --project-id <A>` sets default proxy scope to project `A`.
@@ -182,6 +265,7 @@ Guardrail note:
 
 ```bash
 metheus-governance-mcp-cli doctor --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com
+metheus-governance-mcp-cli doctor --project-id <project_uuid> --base-url https://metheus.gesiaplatform.com --strict true
 ```
 
 Checks:
@@ -198,6 +282,9 @@ Checks:
 - ctxpack auto sync status
 - smoke calls: `workitem.list`, `evidence.list`, `decision.list`
 
+`--strict true` upgrades local runner route safety warnings into failures.
+Use it for production validation before enabling long-running bot routes.
+
 Direct bot posting:
 - `me.send-bot-message` uses local provider tokens from `~/.metheus/<provider>.env`
 - it does not use a server-stored bot token
@@ -209,6 +296,11 @@ Direct bot posting:
   - Slack
 - KakaoTalk profiles and destinations can be stored now, but direct local delivery is not implemented yet
 
+Provider support matrix in this CLI:
+- `telegram`: local token verification, direct local delivery, typing, reply-to-message, and automatic inbound runner are implemented
+- `slack`: local token verification and direct local delivery are implemented, but automatic inbound runner is not
+- `kakaotalk`: local config can be stored, but token verification, direct local delivery, and automatic inbound runner are not implemented
+
 ## Local bot runner
 
 The local runner closes the loop:
@@ -226,24 +318,28 @@ Execution model:
 - runner resolves `project_id -> workspace_dir`
 - runner resolves server bot role to a local `role_profile`
 - runner executes the mapped client adapter (`codex` / `claude` / `gemini`)
-- legacy `command` remains supported only as fallback for older configs
+- legacy `command` remains readable for migration, but execution is disabled by default unless `METHEUS_ALLOW_LEGACY_RUNNER_COMMAND=1`
 
 Commands:
 
 ```bash
-metheus-governance-mcp-cli runner once
-metheus-governance-mcp-cli runner start
+metheus-governance-mcp-cli runner once --route-name telegram-monitor
+metheus-governance-mcp-cli runner start --route-name telegram-monitor
+```
+
+Recommended operational path:
+
+```bash
+metheus-governance-mcp-cli runner once --route-name telegram-monitor --dry-run-delivery true
+metheus-governance-mcp-cli runner start --route-name telegram-monitor
 ```
 
-Common flags:
+Debug/selection overrides:
 
 ```bash
 metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor
 metheus-governance-mcp-cli runner start --project-id <project_uuid> --provider telegram --role monitor --poll-interval-ms 5000
-metheus-governance-mcp-cli runner start --project-id <project_uuid> --provider telegram --role monitor --mentions-only true
-metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --dry-run-delivery true
 metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --role-profile review
-metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --command "python C:\\path\\to\\reply.py"
 ```
 
 Recommended production path:
@@ -253,6 +349,9 @@ Recommended production path:
 - keep `project_mappings.<project_id>.workspace_dir` aligned to that teammate's actual local project folder
 - let `ctxpack pull` or project connection refresh the mapping automatically
 - keep per-role execution policy under `role_profiles`
+- keep per-bot LLM binding primarily in `~/.metheus/telegram.env`
+- use `bot_bindings` in `bot-runner.json` only as local fallback/override
+- runner resolution order is: explicit `route.role_profile` -> provider env bot binding -> `bot_bindings` -> server bot role -> `route.role`
 
 Why `workspace_dir` matters:
 - the server cannot know each project member's local folder path
@@ -265,6 +364,11 @@ Role profile fields:
 - `permission_mode`: `read_only`, `workspace_write`, `danger_full_access`
 - `reasoning_effort`: `low`, `medium`, `high`
 
+Role profile note:
+- Claude maps `reasoning_effort` to `--effort`.
+- Codex maps `reasoning_effort` to `-c model_reasoning_effort="..."`.
+- Gemini CLI still has no dedicated effort flag, so the runner keeps the value in env/prompt context for policy parity.
+
 Trigger policy fields:
 - `mentions_only`: in groups, react only when the bot is mentioned or when a message replies to the bot
 - `direct_messages`: allow or block private chat messages
@@ -309,10 +413,12 @@ Notes:
 - mirrored bot replies are deduped by `chat_id + message_id`
 - provider bot messages are ignored during inbound import by default
 - `local-bot-bridge` reads stdin JSON from the runner and can call Codex/Claude/Gemini for you
+- `route.command` fallback is disabled by default; enable it only temporarily with `METHEUS_ALLOW_LEGACY_RUNNER_COMMAND=1`
 - today this automation path is implemented for Telegram end-to-end
-- set `METHEUS_TELEGRAM_API_BASE_URL=http://127.0.0.1:<port>` only for local mock or regression testing; normal usage should keep the default Telegram API base
+- prefer `TELEGRAM_API_BASE_URL=` inside `~/.metheus/telegram.env` for per-bot local Telegram API overrides; `METHEUS_TELEGRAM_API_BASE_URL` remains a process-level fallback mainly for mock/regression testing
 - Slack can use direct local send, but automatic inbound runner flow is not completed yet
 - KakaoTalk config can be stored now, but direct send/runner flow is not implemented yet
+- `doctor` now reports provider support for both enabled runner routes and active project chat destinations
 
 ## Use in MCP