metheus-governance-mcp-cli 0.2.53 → 0.2.54

package/README.md

@@ -25,6 +25,7 @@ Install creates local provider settings templates here:
 - `~/.metheus/telegram.env`
 - `~/.metheus/slack.env`
 - `~/.metheus/kakaotalk.env`
+- `~/.metheus/bot-runner.json`
 
 These files are for local provider bot secrets only.
 
@@ -51,6 +52,24 @@ SLACK_BOT_TOKEN=
 KAKAOTALK_BOT_TOKEN=
 ```
 
+Runner template:
+
+```json
+{
+  "version": 1,
+  "routes": [
+    {
+      "name": "telegram-monitor",
+      "enabled": false,
+      "project_id": "<project_uuid>",
+      "provider": "telegram",
+      "role": "monitor",
+      "command": "metheus-governance-mcp-cli local-bot-bridge --client codex --no-update"
+    }
+  ]
+}
+```
+
 ## One command bootstrap (recommended)
 
 Run in your project folder:
@@ -86,9 +105,29 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 - `~/.metheus/telegram.env`
 - `~/.metheus/slack.env`
 - `~/.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.
 
+`~/.metheus/bot-runner.json` is the local automation profile for:
+- which project to watch
+- which provider/role bot profile to use
+- which local AI command to run on new archived chat messages
+
+Built-in helper command:
+
+```bash
+metheus-governance-mcp-cli local-bot-bridge --client codex --no-update
+```
+
+Supported `--client` values:
+- `codex`
+- `claude`
+- `gemini`
+- `sample`
+
+Use `sample` first for smoke tests before switching to a real AI client.
+
 Gemini CLI note:
 - `gemini mcp` commands require Gemini auth to be configured first (`GEMINI_API_KEY` or `~/.gemini/settings.json` auth).
 - `setup` registers Gemini in both `user` and `project` scopes to improve auto-discovery across folders.
@@ -137,6 +176,52 @@ Direct bot posting:
   - Slack
 - KakaoTalk profiles and destinations can be stored now, but direct local delivery is not implemented yet
 
+## Local bot runner
+
+The local runner closes the loop:
+
+1. provider bot receives a room message
+2. Metheus archives the message into Governance discussion comments
+3. local runner reads new archived comments
+4. local AI command generates a reply
+5. CLI sends the reply back through `me.send-bot-message`
+6. the sent reply is mirrored back into the archive
+
+Commands:
+
+```bash
+metheus-governance-mcp-cli runner once
+metheus-governance-mcp-cli runner start
+```
+
+Common flags:
+
+```bash
+metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --command "node C:\\path\\to\\my-runner.js"
+metheus-governance-mcp-cli runner start --project-id <project_uuid> --provider telegram --role monitor --command "python C:\\path\\to\\reply.py" --poll-interval-ms 5000
+```
+
+Recommended production path:
+- keep provider bot token in `~/.metheus/<provider>.env`
+- keep project room identifier in server-side Chat Destinations
+- keep automation route config in `~/.metheus/bot-runner.json`
+
+Runner command contract:
+- stdin: JSON payload containing project, destination, trigger message, and recent context comments
+- stdout:
+  - plain text reply, or
+  - JSON object like `{"reply":"...","reply_to_message_id":123}`, or
+  - JSON skip result like `{"skip":true,"reason":"not actionable"}`
+
+Notes:
+- `runner once` processes the most recent pending archived inbound message
+- `runner start` keeps polling and stores per-route cursor state in `~/.metheus/bot-runner-state.json`
+- first start primes the cursor to the latest inbound message and does not reply to old backlog
+- `local-bot-bridge` reads stdin JSON from the runner and can call Codex/Claude/Gemini for you
+- today this automation path is implemented for Telegram end-to-end
+- 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
+
 ## Use in MCP
 
 `setup` auto-registers this server for `codex`, `claude`, `gemini`, `antigravity`, and `cursor` when those CLIs are available.