metheus-governance-mcp-cli 0.2.59 → 0.2.61

package/README.md

@@ -56,7 +56,22 @@ Runner template:
 
 ```json
 {
-  "version": 1,
+  "version": 2,
+  "project_mappings": {
+    "<project_uuid>": {
+      "workspace_dir": "C:\\path\\to\\your\\project",
+      "source": "ctxpack_pull",
+      "updated_at": "2026-03-13T00:00:00Z"
+    }
+  },
+  "role_profiles": {
+    "monitor": {
+      "client": "codex",
+      "model": "",
+      "permission_mode": "read_only",
+      "reasoning_effort": "low"
+    }
+  },
   "routes": [
     {
       "name": "telegram-monitor",
@@ -64,7 +79,19 @@ Runner template:
       "project_id": "<project_uuid>",
       "provider": "telegram",
       "role": "monitor",
-      "command": "metheus-governance-mcp-cli local-bot-bridge --client codex --no-update"
+      "role_profile": "monitor",
+      "trigger_policy": {
+        "mentions_only": true,
+        "direct_messages": true,
+        "reply_to_bot_messages": true,
+        "ignore_edited_messages": false
+      },
+      "archive_policy": {
+        "mirror_replies": true,
+        "dedupe_inbound": true,
+        "dedupe_outbound": true,
+        "skip_bot_messages": true
+      }
     }
   ]
 }
@@ -112,9 +139,10 @@ Fill only provider bot tokens locally. Project chat destination identifiers shou
 `~/.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
+- which `project_id -> workspace_dir` mapping to apply locally
+- which role profile maps to which local CLI/model/permission/reasoning policy
 
-Built-in helper command:
+Built-in helper command for legacy fallback/testing:
 
 ```bash
 metheus-governance-mcp-cli local-bot-bridge --client codex --no-update
@@ -159,6 +187,10 @@ metheus-governance-mcp-cli doctor --project-id <project_uuid> --base-url https:/
 Checks:
 - auth token status (+ auto refresh attempt)
 - local provider env template presence
+- local bot runner v2 config validity
+- project workspace mapping presence
+- role profile -> local CLI availability
+- route dry-run / trigger-policy safety warnings
 - local provider token presence for active project destinations
 - codex/claude/gemini/antigravity/cursor registration state
 - gateway `tools/list` reachability
@@ -171,6 +203,7 @@ Direct bot posting:
 - it does not use a server-stored bot token
 - the destination identifier is resolved from the current project's saved Chat Destinations on the Metheus server
 - if multiple active destinations exist for the same provider, pass `destination_id` or `destination_label`
+- pass `dry_run_delivery=true` to preview the resolved bot/destination locally without sending the provider message
 - direct local delivery is implemented today for:
   - Telegram
   - Slack
@@ -187,6 +220,14 @@ The local runner closes the loop:
 5. CLI sends the reply back through `me.send-bot-message`
 6. the sent reply is mirrored back into the archive
 
+Execution model:
+- server stores bot identity, provider, role, and project chat destination
+- local runner stores workspace mapping and role profiles
+- 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
+
 Commands:
 
 ```bash
@@ -197,14 +238,58 @@ 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
+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:
 - 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`
+- 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`
+
+Why `workspace_dir` matters:
+- the server cannot know each project member's local folder path
+- the local runner must pass the correct folder to Codex, Claude Code, or Gemini on that member's machine
+- without a valid project mapping, bots may answer with a generic local root instead of the real project workspace
+
+Role profile fields:
+- `client`: `codex`, `claude`, `gemini`, or `sample`
+- `model`: optional CLI-specific model name
+- `permission_mode`: `read_only`, `workspace_write`, `danger_full_access`
+- `reasoning_effort`: `low`, `medium`, `high`
+
+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
+- `reply_to_bot_messages`: treat replies to the bot as actionable even without an explicit mention
+- `ignore_edited_messages`: skip archived edited-message events
+
+Recommended role baselines:
+- `monitor`: `mentions_only=true`, `direct_messages=true`, `reply_to_bot_messages=true`, `ignore_edited_messages=true`
+- `review`: `mentions_only=true`, `direct_messages=true`, `reply_to_bot_messages=true`, `ignore_edited_messages=true`
+- `worker`: `mentions_only=true`, `direct_messages=false`, `reply_to_bot_messages=true`, `ignore_edited_messages=true`
+- `approval`: `mentions_only=true`, `direct_messages=false`, `reply_to_bot_messages=true`, `ignore_edited_messages=true`
+
+These are the default runner v2 fallbacks when a route omits explicit trigger settings.
+`doctor` warns when a route opens broader reply conditions than the recommended role baseline.
+
+Archive policy fields:
+- `mirror_replies`: mirror bot replies back into Governance archive
+- `dedupe_inbound`: avoid duplicate inbound archive comments for the same provider message
+- `dedupe_outbound`: avoid duplicate mirrored bot-reply archive comments for the same delivered provider message
+- `skip_bot_messages`: ignore provider bot messages during inbound import to avoid self-loop behavior
+
+Mapping behavior:
+- `ctxpack pull --workspace-dir <path>` stores `project_id -> workspace_dir`
+- proxy/project connection can also persist the mapping
+- broader project roots are preferred over nested tool folders when updating the mapping
 
 Runner command contract:
 - stdin: JSON payload containing project, destination, trigger message, and recent context comments
@@ -217,8 +302,15 @@ 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
+- when inline filters match a configured route in `~/.metheus/bot-runner.json`, the runner reuses that route's canonical name/destination and state cursor instead of creating a new anonymous route key
+- stale anonymous route keys in `~/.metheus/bot-runner-state.json` are auto-migrated to the matching configured route when possible; `doctor` warns if ambiguous legacy keys still remain
+- `--dry-run-delivery true` resolves the real bot and destination but skips provider send and archive mirror writes
+- when `trigger_policy.mentions_only=true`, unmentioned group messages are archived but skipped for reply generation
+- 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
 - 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
 - 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
 
@@ -409,6 +501,14 @@ Local compatibility selftest (no network):
 npm run test:compat
 ```
 
+This selftest now includes a local mock Telegram runner path:
+- mock Telegram `getUpdates` import into archive
+- trigger-policy evaluation
+- role-based trigger default resolution
+- local `sample` AI execution
+- `sendChatAction` / `sendMessage`
+- mirrored bot-reply archive creation and state update
+
 Proxy smoke test (initialize -> tools/list -> project summary -> ctxpack local sync):
 
 ```bash