metheus-governance-mcp-cli 0.2.145 → 0.2.147

package/README.md

@@ -27,6 +27,7 @@ Install creates local provider settings templates here:
 - `~/.metheus/slack.env`
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
+- `~/.metheus/project-workspaces.json`
 
 These files are for local provider bot secrets, local transport options, and optional per-bot local AI binding.
 
@@ -181,6 +182,7 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 - `~/.metheus/slack.env`
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
+- `~/.metheus/project-workspaces.json`
 
 Bootstrap or setup does not create one file per server bot automatically. Per-bot Telegram files are created later when you run `bot add`, `bot verify`, or `bot edit` against a real server bot identity.
 
@@ -195,10 +197,13 @@ Fill provider bot secrets and provider-local transport options locally. Project
 `~/.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-bots/global.env`, `telegram-bots/*.env`, or fallback `bot_bindings`
 
+`~/.metheus/project-workspaces.json` is the local project workspace registry for:
+- which `project_id -> workspace_dir` mapping to apply locally
+- which workspace source updated that mapping last
+
 Built-in helper command for legacy fallback/testing:
 
 ```bash

package/cli.mjs

@@ -12,7 +12,9 @@ import https from "node:https";
 import {
   DEFAULT_LOCAL_AI_CLIENT,
   analyzeHumanConversationIntentWithAI,
+  auditDirectHumanReplyWithAI,
   normalizeExecutionArtifacts,
+  planRoleExecutionWithAI,
   resolveLocalAIExecutionModel,
   resolveGeminiReasoningConfig,
   suggestLocalAIModelDisplayName,
@@ -142,6 +144,7 @@ import {
 } from "./lib/runner-delivery.mjs";
 import {
   resolveRunnerExecutionPlan,
+  resolveRunnerExecutionPlanForRole,
   resolveRunnerRoleProfile,
   resolveRunnerWorkspaceSelection,
   runRunnerAIExecution,
@@ -2998,16 +3001,20 @@ function buildRunnerDeliveryDeps() {
 function buildRunnerExecutionDeps() {
   return {
     analyzeHumanConversationIntentWithAI,
+    auditDirectHumanReplyWithAI,
+    planRoleExecutionWithAI,
     normalizeRunnerRoleProfileName,
     normalizeRunnerRoleProfile,
     normalizeBotRunnerProjectMapping,
     sanitizeWorkspaceCandidate,
     loadProviderEnvConfig,
+    loadBotRunnerConfig,
     canUseLegacyRunnerCommand,
     hasLegacyRunnerCommand,
     isLegacyRunnerCommandOptInEnabled,
     legacyRunnerCommandDisabledMessage,
     normalizeExecutionArtifacts,
+    resolveRunnerExecutionPlanForRole,
     validateWorkspaceArtifacts,
     tryJsonParse,
   };

package/lib/local-ai-adapters.mjs

@@ -718,6 +718,50 @@ function normalizeExecutionContract(rawContract) {
   };
 }
 
+const RUNNER_EXECUTION_STEP_ROLES = new Set(["monitor", "worker", "review", "approval"]);
+
+function normalizeRoleExecutionStepRole(rawValue) {
+  const normalized = String(rawValue || "").trim().toLowerCase();
+  return RUNNER_EXECUTION_STEP_ROLES.has(normalized) ? normalized : "";
+}
+
+function normalizeRoleExecutionStep(rawStep) {
+  const step = safeObject(rawStep);
+  const role = normalizeRoleExecutionStepRole(step.role || step.profile || step.role_profile || step.roleProfile);
+  const goal = firstNonEmptyString([
+    step.goal,
+    step.task,
+    step.objective,
+    step.description,
+  ]);
+  if (!role || !goal) {
+    return null;
+  }
+  return {
+    role,
+    goal,
+    artifactsRequired: step.artifacts_required === true || step.artifactsRequired === true,
+  };
+}
+
+export function normalizeRoleExecutionPlan(rawPlan) {
+  const plan = safeObject(rawPlan);
+  if (!Object.keys(plan).length) {
+    return null;
+  }
+  const steps = ensureArray(plan.steps)
+    .map((item) => normalizeRoleExecutionStep(item))
+    .filter(Boolean);
+  const summaryRole = normalizeRoleExecutionStepRole(plan.summary_role || plan.summaryRole);
+  const requiresExecution = plan.requires_execution === true || plan.requiresExecution === true;
+  return {
+    requiresExecution,
+    summaryRole: summaryRole || (steps.length > 0 ? steps[steps.length - 1].role : ""),
+    steps,
+    reason: String(plan.reason || "").trim(),
+  };
+}
+
 function normalizeModelAliasText(rawValue) {
   return String(rawValue || "")
     .trim()
@@ -1070,6 +1114,7 @@ function inferCurrentTurnPurpose({ trigger, conversation, selfBotUsername, other
 
 export function buildLocalBotPrompt(payload, { terse = true } = {}) {
   const safePayload = payload && typeof payload === "object" ? payload : {};
+  const taskName = String(safePayload.task || "").trim();
   const trigger = safePayload.trigger && typeof safePayload.trigger === "object" ? safePayload.trigger : {};
   const responseContract = safePayload.response_contract && typeof safePayload.response_contract === "object"
     ? safePayload.response_contract
@@ -1156,9 +1201,14 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
   const assignmentsForThisBot = currentExecutionAssignments.filter((item) => (
     String(item.target_bot || item.targetBot || "").trim().replace(/^@+/, "").toLowerCase() === selfSelector.toLowerCase()
   ));
+  const executionStep = safeObject(safePayload.execution_step);
+  const executionPlan = safeObject(safePayload.execution_plan);
+  const executionProgress = safeObject(safePayload.execution_progress);
+  const isInternalExecutionStep = taskName === "execute_project_role_step";
 
   const lines = [
     "You are a Metheus local bot runner.",
+    `Task: ${taskName || "reply_to_project_chat_message"}`,
     `Provider: ${provider}`,
     `Role: ${role}`,
     `Role Profile: ${roleProfile || "-"}`,
@@ -1189,6 +1239,32 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
     recentBotMessages.length ? recentBotMessages.map(formatContextCommentLine).join("\n") : "- none",
     "",
   ];
+  if (isInternalExecutionStep) {
+    const stepIndex = intFromRawAllowZero(executionStep.index, 0);
+    const stepTotal = intFromRawAllowZero(executionStep.total, 0);
+    const stepRole = firstNonEmptyString([executionStep.role, roleProfile, role]);
+    const stepGoal = String(executionStep.goal || "").trim();
+    const priorArtifacts = ensureArray(executionProgress.produced_artifacts)
+      .map((item) => firstNonEmptyString([safeObject(item).relativePath, safeObject(item).path]))
+      .filter(Boolean);
+    lines.push(
+      "Internal execution step is active.",
+      "This is not a placeholder chat reply task. Complete the assigned step now.",
+      `Execution Step: ${stepIndex > 0 ? stepIndex : "-"} / ${stepTotal > 0 ? stepTotal : "-"}`,
+      `Execution Step Role: ${stepRole || "-"}`,
+      `Execution Step Goal: ${stepGoal || "-"}`,
+      `Execution Step Requires Artifacts: ${executionStep.artifacts_required === true || executionStep.artifactsRequired === true ? "yes" : "no"}`,
+      `Execution Plan Requires Execution: ${executionPlan.requires_execution === true || executionPlan.requiresExecution === true ? "yes" : "no"}`,
+      `Execution Plan Summary Role: ${String(executionPlan.summary_role || executionPlan.summaryRole || "").trim() || "-"}`,
+      `Prior Produced Artifacts: ${priorArtifacts.length ? priorArtifacts.join(", ") : "-"}`,
+      "Do the work for this step now. Do not say you will start later, wait, come back later, or plan first.",
+      "If this is a worker step, actually create/update the required project artifacts now and include them in artifacts.",
+      "If this is a review step, provide the review findings now.",
+      "If this is an approval step, provide the approval decision now.",
+      "If this is the final step, the reply will be shown to humans. If it is not the final step, the reply is still an internal execution note and must describe what was actually completed in this step.",
+      "",
+    );
+  }
   if (responseContract.must_reply === true) {
     lines.push(
       "This bot was explicitly addressed by the trigger message.",
@@ -1209,7 +1285,10 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
         ? `A previous attempt incorrectly skipped the reply. Previous skip reason: ${String(responseContract.previous_skip_reason || "").trim() || "-"}.`
         : "Skip is not allowed for this message.",
       responseContract.require_actionable_contract === true
-        ? "This reply must include an actionable execution contract. Do not promise future work without immediate delegation or an immediate result."
+        ? "The human intent requires immediate execution, not a placeholder status update. This reply must include an actionable execution contract. Do not promise future work without immediate delegation or an immediate result."
+        : "",
+      responseContract.require_actionable_contract === true && Array.isArray(responseContract.allowed_contract_types) && responseContract.allowed_contract_types.length > 0
+        ? `Allowed execution contract types for this reply: ${responseContract.allowed_contract_types.join(", ")}.`
         : "",
       "",
     );
@@ -1229,7 +1308,9 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
     "- If no project files changed, return artifacts: [].",
     "- Do not claim that a file, plan, document, or code change is complete unless the corresponding artifact path is present in artifacts.",
     "",
-    responseContract.must_reply === true
+    isInternalExecutionStep
+      ? "Return JSON only in one line: {\"reply\":\"what was completed in this step\",\"artifacts\":[{\"path\":\"relative/or/absolute/path\",\"kind\":\"plan|code|doc|spec|test\",\"operation\":\"create|update|delete\"}],\"contract\":{\"type\":\"direct_result|summary_request|final_summary\",\"actionable\":true,\"summary_bot\":\"username\",\"next_responders\":[\"username\"]}}. Use artifacts: [] only if this step truly changes no project files."
+      : responseContract.must_reply === true
       ? "Return JSON only in one line: {\"reply\":\"...\",\"artifacts\":[]} or {\"reply\":\"...\",\"artifacts\":[],\"contract\":{\"type\":\"direct_result|delegation|summary_request|final_summary\",\"actionable\":true,\"assignments\":[{\"target_bot\":\"username\",\"task\":\"...\"}],\"summary_bot\":\"username\",\"next_responders\":[\"username\"]}}."
       : terse
         ? "Return JSON only in one line: {\"reply\":\"...\",\"artifacts\":[]} or {\"skip\":true,\"reason\":\"...\"}."
@@ -1397,9 +1478,10 @@ function buildConversationIntentAnalysisPrompt({
     "Infer the human's intended bot participation contract from the human message only.",
     "Do not infer from prior bot replies. Do not invent bots outside managed_bots.",
     "Be conservative. If the request is ambiguous, choose single_bot and keep only the directly addressed bot as the responder.",
+    "Also decide whether the human is asking for immediate execution/work now or only asking for information/explanation.",
     "",
     "Return strict JSON only with this shape:",
-    "{\"mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"lead_bot\":\"<username or empty>\",\"participants\":[\"...\"],\"initial_responders\":[\"...\"],\"allowed_responders\":[\"...\"],\"summary_bot\":\"<username or empty>\",\"allow_bot_to_bot\":true|false}",
+    "{\"mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"lead_bot\":\"<username or empty>\",\"participants\":[\"...\"],\"initial_responders\":[\"...\"],\"allowed_responders\":[\"...\"],\"summary_bot\":\"<username or empty>\",\"allow_bot_to_bot\":true|false,\"reply_expectation\":\"informational|actionable\"}",
     "",
     "Mode definitions:",
     "- single_bot: only one directly addressed bot should respond. No bot-to-bot relay.",
@@ -1414,12 +1496,96 @@ function buildConversationIntentAnalysisPrompt({
     "- If mode is single_bot, initial_responders and allowed_responders should contain only that bot.",
     "- If mode is delegated_single_lead, lead_bot must be set and initial_responders should contain only the lead bot.",
     "- If the human explicitly asks one bot to summarize or finalize, set summary_bot to that bot.",
+    "- reply_expectation=actionable when the human is asking the bot(s) to actually do work now, produce concrete results, create/update files, delegate concrete tasks, or otherwise execute immediately.",
+    "- reply_expectation=informational when the human is only asking for explanation, status, location, clarification, or other non-execution information.",
     "",
     `managed_bots=${JSON.stringify(bots)}`,
     `human_message=${JSON.stringify(String(messageText || "").trim())}`,
   ].join("\n");
 }
 
+function buildRoleExecutionPlanPrompt({
+  messageText,
+  currentBotUsername,
+  currentBotRole,
+  managedBots,
+  workspaceDir,
+  currentAssignmentTasks = [],
+  contextComments = [],
+  conversationMode = "",
+}) {
+  const bots = ensureArray(managedBots).map((item) => {
+    const bot = safeObject(item);
+    return {
+      username: String(bot.username || "").trim().replace(/^@+/, ""),
+      display_name: String(bot.display_name || bot.displayName || bot.username || "").trim(),
+    };
+  }).filter((item) => item.username);
+  const normalizedContext = ensureArray(contextComments)
+    .slice(0, 10)
+    .map((item) => formatContextCommentLine(item));
+  return [
+    "You are an execution planner for managed local Telegram bots.",
+    "Read the human request and recent room context, then decide whether actual project execution is required now.",
+    "Judge by meaning, not by keywords or @mentions alone.",
+    "If the request only asks for status, explanation, location, or clarification, then requires_execution should be false.",
+    "If the request asks the bot to create/update/delete project files, write plans/docs/code, delegate concrete tasks, continue execution, or otherwise do work now, then requires_execution should be true.",
+    "When requires_execution=true, return the minimal role step plan using only these roles: monitor, worker, review, approval.",
+    "Role guidance:",
+    "- monitor: understand context, scope the work, plan, coordinate, or summarize.",
+    "- worker: actually create/update/delete project artifacts now.",
+    "- review: inspect completed work and report findings, issues, or improvements.",
+    "- approval: make a go/no-go, approval, or explicit decision when the request calls for it.",
+    "worker is required if project artifacts must be created or updated now.",
+    "review is required if the request implies checking or validating the created result before finalizing.",
+    "approval is required only when the request asks for approval, release, confirmation, or a formal decision.",
+    "",
+    "Return strict JSON only with this shape:",
+    "{\"requires_execution\":true|false,\"summary_role\":\"monitor|worker|review|approval\",\"reason\":\"short explanation\",\"steps\":[{\"role\":\"monitor|worker|review|approval\",\"goal\":\"short goal\",\"artifacts_required\":true|false}]}",
+    "",
+    `current_bot_username=${JSON.stringify(String(currentBotUsername || "").trim().replace(/^@+/, ""))}`,
+    `current_bot_route_role=${JSON.stringify(String(currentBotRole || "").trim().toLowerCase())}`,
+    `conversation_mode=${JSON.stringify(String(conversationMode || "").trim())}`,
+    `workspace_dir=${JSON.stringify(String(workspaceDir || "").trim())}`,
+    `managed_bots=${JSON.stringify(bots)}`,
+    `current_assignment_tasks=${JSON.stringify(ensureArray(currentAssignmentTasks).map((item) => String(item || "").trim()).filter(Boolean))}`,
+    `human_message=${JSON.stringify(String(messageText || "").trim())}`,
+    "recent_context=",
+    normalizedContext.length ? normalizedContext.join("\n") : "- none",
+  ].join("\n");
+}
+
+function buildDirectReplyGuardrailPrompt({
+  humanMessageText,
+  botReplyText,
+  currentBotUsername,
+  managedBots,
+}) {
+  const bots = ensureArray(managedBots).map((item) => {
+    const bot = safeObject(item);
+    return {
+      username: String(bot.username || "").trim().replace(/^@+/, ""),
+      display_name: String(bot.display_name || bot.displayName || bot.username || "").trim(),
+    };
+  }).filter((item) => item.username);
+  return [
+    "You are an execution guardrail auditor for managed Telegram bots.",
+    "Decide whether the human message requires immediate execution/action now, or whether a plain informational reply is sufficient.",
+    "Then decide whether the candidate bot reply actually satisfies that requirement.",
+    "Judge by meaning, not by keywords.",
+    "A placeholder or status-only reply such as 'I will start', 'please wait', 'I will analyze and come back', or 'I will plan first' does NOT satisfy an actionable request.",
+    "If the human is asking the bot to do work now, create/update files now, delegate concrete tasks now, or otherwise execute immediately, then requires_actionable_contract should be true.",
+    "",
+    "Return strict JSON only with this shape:",
+    "{\"requires_actionable_contract\":true|false,\"reply_satisfies_request\":true|false,\"reason\":\"short explanation\"}",
+    "",
+    `current_bot_username=${JSON.stringify(String(currentBotUsername || "").trim().replace(/^@+/, ""))}`,
+    `managed_bots=${JSON.stringify(bots)}`,
+    `human_message=${JSON.stringify(String(humanMessageText || "").trim())}`,
+    `candidate_reply=${JSON.stringify(String(botReplyText || "").trim())}`,
+  ].join("\n");
+}
+
 function normalizeIntentContractSelectorList(values, managedSelectorSet) {
   return Array.from(new Set(ensureArray(values)
     .map((value) => String(value || "").trim().replace(/^@+/, "").toLowerCase())
@@ -1472,9 +1638,107 @@ export function analyzeHumanConversationIntentWithAI({
     allowed_responders: normalizeIntentContractSelectorList(parsed.allowed_responders || parsed.allowedResponders, managedSelectorSet),
     summary_bot: String(parsed.summary_bot || parsed.summaryBot || "").trim().replace(/^@+/, "").toLowerCase(),
     allow_bot_to_bot: parsed.allow_bot_to_bot === true || parsed.allowBotToBot === true,
+    reply_expectation: String(parsed.reply_expectation || parsed.replyExpectation || "").trim().toLowerCase(),
+  };
+}
+
+export function auditDirectHumanReplyWithAI({
+  humanMessageText,
+  botReplyText,
+  currentBotUsername,
+  managedBots,
+  workspaceDir,
+  client = "",
+  model = "",
+  env = process.env,
+}) {
+  const bots = ensureArray(managedBots);
+  if (!bots.length) {
+    return null;
+  }
+  const parserClient = normalizeLocalAIClientName(
+    String(client || env?.METHEUS_INTENT_PARSER_CLIENT || "").trim(),
+    "gpt",
+  );
+  const parserModel = String(model || env?.METHEUS_INTENT_PARSER_MODEL || suggestLocalAIModelDisplayName(parserClient, "") || "").trim();
+  const rawText = runLocalAIPromptRawText({
+    client: parserClient,
+    promptText: buildDirectReplyGuardrailPrompt({
+      humanMessageText,
+      botReplyText,
+      currentBotUsername,
+      managedBots: bots,
+    }),
+    workspaceDir,
+    model: parserModel,
+    permissionMode: "read_only",
+    reasoningEffort: String(env?.METHEUS_INTENT_PARSER_REASONING_EFFORT || "low").trim() || "low",
+    env,
+  });
+  const parsed = tryJsonParse(rawText) || tryParseEmbeddedJsonObject(rawText);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("direct reply guardrail auditor did not return a JSON object");
+  }
+  return {
+    requires_actionable_contract: parsed.requires_actionable_contract === true || parsed.requiresActionableContract === true,
+    reply_satisfies_request: parsed.reply_satisfies_request === true || parsed.replySatisfiesRequest === true,
+    reason: String(parsed.reason || "").trim(),
   };
 }
 
+export function planRoleExecutionWithAI({
+  messageText,
+  currentBotUsername,
+  currentBotRole = "",
+  managedBots,
+  workspaceDir,
+  currentAssignmentTasks = [],
+  contextComments = [],
+  conversationMode = "",
+  client = "",
+  model = "",
+  env = process.env,
+}) {
+  const bots = ensureArray(managedBots);
+  if (!bots.length) {
+    return null;
+  }
+  const plannerClient = normalizeLocalAIClientName(
+    String(client || env?.METHEUS_ROLE_PLANNER_CLIENT || env?.METHEUS_INTENT_PARSER_CLIENT || "").trim(),
+    "gpt",
+  );
+  const plannerModel = String(
+    model
+    || env?.METHEUS_ROLE_PLANNER_MODEL
+    || env?.METHEUS_INTENT_PARSER_MODEL
+    || suggestLocalAIModelDisplayName(plannerClient, "")
+    || "",
+  ).trim();
+  const rawText = runLocalAIPromptRawText({
+    client: plannerClient,
+    promptText: buildRoleExecutionPlanPrompt({
+      messageText,
+      currentBotUsername,
+      currentBotRole,
+      managedBots: bots,
+      workspaceDir,
+      currentAssignmentTasks,
+      contextComments,
+      conversationMode,
+    }),
+    workspaceDir,
+    model: plannerModel,
+    permissionMode: "read_only",
+    reasoningEffort: String(env?.METHEUS_ROLE_PLANNER_REASONING_EFFORT || "medium").trim() || "medium",
+    env,
+  });
+  const parsed = tryJsonParse(rawText) || tryParseEmbeddedJsonObject(rawText);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("role execution planner did not return a JSON object");
+  }
+  return normalizeRoleExecutionPlan(parsed);
+}
+
 export function runLocalAIClient({
   client,
   inputPayload,

package/lib/runner-execution.mjs

@@ -241,6 +241,23 @@ export function resolveRunnerExecutionPlan(route, bot, config, deps) {
   throw new Error(detail.join("; "));
 }
 
+export function resolveRunnerExecutionPlanForRole(route, bot, roleName, config, deps) {
+  const normalizedRoleName = String(roleName || "").trim().toLowerCase();
+  if (!normalizedRoleName) {
+    throw new Error("roleName is required to resolve a role execution plan");
+  }
+  return resolveRunnerExecutionPlan(
+    {
+      ...safeObject(route),
+      role: normalizedRoleName,
+      roleProfile: normalizedRoleName,
+    },
+    bot,
+    config,
+    deps,
+  );
+}
+
 function buildRunnerExecutionEnv({ route, destination, executionPlan }) {
   return {
     ...process.env,