metheus-governance-mcp-cli 0.2.206 → 0.2.207

package/cli.mjs

@@ -16,6 +16,7 @@ import {
   analyzeHumanConversationIntentWithAI,
   auditRoleExecutionPlanWithAI,
   auditDirectHumanReplyWithAI,
+  explainExecutionFailureWithAI,
   normalizeExecutionArtifacts,
   planRoleExecutionWithAI,
   repairRoleExecutionPlanWithAI,
@@ -8463,6 +8464,7 @@ async function processRunnerRouteOnce(route, runtime, mode, options = {}) {
           saveRunnerRouteState,
           startRunnerTypingHeartbeat,
           runRunnerAIExecution,
+          explainExecutionFailureWithAI,
           performLocalBotDelivery,
           serializeRunnerTriggerPolicy,
           serializeRunnerArchivePolicy,
@@ -10833,6 +10835,7 @@ async function runRunnerStartResolvedRoutes(routes, flags, options = {}) {
                         saveRunnerRouteState,
                         startRunnerTypingHeartbeat,
                         runRunnerAIExecution,
+                        explainExecutionFailureWithAI,
                         performLocalBotDelivery,
                         serializeRunnerTriggerPolicy,
                         serializeRunnerArchivePolicy,

package/lib/local-ai-adapters.mjs

@@ -1269,6 +1269,29 @@ export function resolveResponderAdjudicatorModelDisplayName({
   ).trim();
 }
 
+export function resolveFailureExplainerModelDisplayName({
+  client = "",
+  model = "",
+  env = process.env,
+} = {}) {
+  const explainerClient = normalizeLocalAIClientName(
+    String(
+      client
+      || env?.METHEUS_FAILURE_EXPLAINER_CLIENT
+      || env?.METHEUS_INTENT_PARSER_CLIENT
+      || "",
+    ).trim(),
+    "gpt",
+  );
+  return String(
+    model
+    || env?.METHEUS_FAILURE_EXPLAINER_MODEL
+    || env?.METHEUS_INTENT_PARSER_MODEL
+    || defaultAdjudicationModelForClient(explainerClient, env)
+    || "",
+  ).trim();
+}
+
 export function resolveLocalAIExecutionModel(clientName, rawModelValue = "") {
   const modelValue = String(rawModelValue || "").trim();
   if (!modelValue) return "";
@@ -2492,6 +2515,100 @@ export function analyzeHumanConversationIntentWithAI({
   };
 }
 
+function buildExecutionFailureExplanationPrompt({
+  botName = "",
+  userMessageText = "",
+  failureFacts = null,
+}) {
+  const compactUserMessage = String(userMessageText || "").trim() || "(not available)";
+  const compactBotName = String(botName || "").trim() || "the bot";
+  return [
+    "You explain runner execution failures to the user.",
+    `The active bot name is: ${compactBotName}`,
+    "Use only the supplied failure facts. Do not invent success, recovered work items, or missing facts.",
+    "Classify the outcome and explain it briefly in the same language as the user's latest message when possible.",
+    "If retryable is true, mention that a retry is reasonable.",
+    "Return a JSON object only with keys:",
+    '{"classification":"failed|retryable_failure|partial_success|needs_user_input|blocked","reply":"string","next_action":"string"}',
+    "",
+    "Latest user message:",
+    compactUserMessage,
+    "",
+    "Failure facts JSON:",
+    JSON.stringify(safeObject(failureFacts), null, 2),
+  ].join("\n");
+}
+
+export function explainExecutionFailureWithAI({
+  failureFacts = null,
+  userMessageText = "",
+  botName = "",
+  workspaceDir,
+  client = "",
+  model = "",
+  env = process.env,
+}) {
+  const explainerClient = normalizeLocalAIClientName(
+    String(
+      client
+      || env?.METHEUS_FAILURE_EXPLAINER_CLIENT
+      || env?.METHEUS_INTENT_PARSER_CLIENT
+      || "",
+    ).trim(),
+    "gpt",
+  );
+  const explainerModel = resolveFailureExplainerModelDisplayName({
+    client: explainerClient,
+    model,
+    env,
+  });
+  const rawText = runLocalAIPromptRawText({
+    client: explainerClient,
+    promptText: buildExecutionFailureExplanationPrompt({
+      botName,
+      userMessageText,
+      failureFacts,
+    }),
+    workspaceDir,
+    model: explainerModel,
+    permissionMode: "read_only",
+    reasoningEffort: String(env?.METHEUS_FAILURE_EXPLAINER_REASONING_EFFORT || "low").trim() || "low",
+    env,
+  });
+  const parsed = tryJsonParse(rawText) || tryParseEmbeddedJsonObject(rawText);
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    const classificationRaw = String(parsed.classification || "").trim().toLowerCase();
+    const classification = [
+      "failed",
+      "retryable_failure",
+      "partial_success",
+      "needs_user_input",
+      "blocked",
+    ].includes(classificationRaw) ? classificationRaw : "failed";
+    const reply = String(parsed.reply || parsed.message || "").trim();
+    const nextAction = String(parsed.next_action || parsed.nextAction || "").trim();
+    if (!reply) {
+      throw new Error("failure explainer did not return reply text");
+    }
+    return {
+      classification,
+      reply,
+      next_action: nextAction,
+      raw: parsed,
+    };
+  }
+  const plainReply = String(rawText || "").trim();
+  if (!plainReply) {
+    throw new Error("failure explainer returned empty output");
+  }
+  return {
+    classification: "failed",
+    reply: plainReply,
+    next_action: "",
+    raw: null,
+  };
+}
+
 function normalizeResponderAdjudicationSelectorList(values, allowedSelectors) {
   const allowed = new Set(ensureArray(allowedSelectors).map((value) => String(value || "").trim().replace(/^@+/, "").toLowerCase()).filter(Boolean));
   return uniqueOrdered(

package/lib/runner-orchestration.mjs

@@ -431,6 +431,155 @@ function shouldSendExecutionFailureReply({ triggerDecision, selectedRecord }) {
     && safeObject(selectedRecord?.parsedArchive).senderIsBot !== true;
 }
 
+function classifyExecutionFailureFacts(detail) {
+  const normalizedDetail = String(detail || "").trim();
+  const networkReset = /ECONNRESET|socket hang up|read ECONNRESET/i.test(normalizedDetail);
+  const networkTimeout = /ETIMEDOUT|http timeout|ECONNABORTED|aborted/i.test(normalizedDetail);
+  const retryable = networkReset || networkTimeout;
+  const base = {
+    stage: "execution",
+    operation: "runner_execution",
+    errorType: retryable
+      ? (networkTimeout ? "network_timeout" : "network_reset")
+      : "execution_failed",
+    retryable,
+    artifactCreated: null,
+    workItemCreated: null,
+    ctxpackUpdated: null,
+    partialSuccess: false,
+  };
+  if (!normalizedDetail) {
+    return base;
+  }
+  if (/permission_mode=read_only|read[_ -]?only/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "permission_check",
+      operation: "route_permission_check",
+      errorType: "read_only_route",
+      retryable: false,
+    };
+  }
+  if (/reply did not produce an actionable execution contract/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "execution_contract",
+      operation: "response_contract_validation",
+      errorType: "missing_actionable_contract",
+      retryable: false,
+    };
+  }
+  if (/failed to create work item/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "work_item_create",
+      operation: "workitem.push",
+      errorType: retryable
+        ? (networkTimeout ? "network_timeout" : "network_reset")
+        : "work_item_create_failed",
+      workItemCreated: false,
+    };
+  }
+  if (/governance work items/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "work_item_create",
+      operation: "governance_work_item_validation",
+      errorType: "governance_work_items_missing",
+      retryable: false,
+      workItemCreated: false,
+    };
+  }
+  if (/validated project artifacts|reported project artifacts that were not observed|artifact path does not exist/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "artifact_validation",
+      operation: "workspace_artifact_validation",
+      errorType: "artifact_validation_failed",
+      retryable: false,
+      artifactCreated: false,
+    };
+  }
+  if (/thread not found/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "archive_thread",
+      operation: "archive_thread_lookup",
+      errorType: "archive_thread_missing",
+      retryable,
+    };
+  }
+  if (/ctxpack version_id is missing/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "ctxpack_update",
+      operation: "ctxpack.update",
+      errorType: "ctxpack_version_missing",
+      retryable: false,
+      ctxpackUpdated: false,
+    };
+  }
+  if (/ctxpack\.update requires project ctxpack write access|ctxpack write access|ctxpack update permission|forbidden/i.test(normalizedDetail) && /ctxpack/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "ctxpack_update",
+      operation: "ctxpack.update",
+      errorType: "ctxpack_permission_denied",
+      retryable: false,
+      ctxpackUpdated: false,
+    };
+  }
+  if (/ctxpack/i.test(normalizedDetail) && retryable) {
+    return {
+      ...base,
+      stage: "ctxpack_update",
+      operation: "ctxpack.update",
+      errorType: networkTimeout ? "network_timeout" : "network_reset",
+      retryable: true,
+      ctxpackUpdated: false,
+    };
+  }
+  if (/ctxpack/i.test(normalizedDetail)) {
+    return {
+      ...base,
+      stage: "ctxpack_update",
+      operation: "ctxpack.update",
+      errorType: "ctxpack_update_failed",
+      retryable: false,
+      ctxpackUpdated: false,
+    };
+  }
+  return base;
+}
+
+function buildExecutionFailureFacts(detail, options = {}) {
+  const normalizedDetail = String(detail || "").trim();
+  const compactDetail = normalizedDetail.replace(/\s+/g, " ").trim();
+  const normalizedOptions = safeObject(options);
+  const intentType = normalizeHumanIntentType(normalizedOptions.intentType);
+  const classified = classifyExecutionFailureFacts(compactDetail);
+  return {
+    stage: classified.stage,
+    operation: classified.operation,
+    status: "failed",
+    error_type: classified.errorType,
+    error_message: compactDetail.slice(0, 400),
+    retryable: classified.retryable === true,
+    artifact_created: classified.artifactCreated,
+    work_item_created: classified.workItemCreated,
+    ctxpack_updated: classified.ctxpackUpdated,
+    partial_success: classified.partialSuccess === true,
+    intent_type: intentType,
+    informational_request: isInformationalHumanIntentType(intentType),
+    execution_mode: String(normalizedOptions.executionMode || "").trim(),
+    role_profile: String(normalizedOptions.roleProfileName || "").trim(),
+    conversation_id: String(normalizedOptions.conversationID || "").trim(),
+    root_work_item_id: String(normalizedOptions.rootWorkItemID || "").trim(),
+    request_message_id: intFromRawAllowZero(normalizedOptions.messageID, 0),
+    request_text: String(normalizedOptions.userMessageText || "").trim(),
+  };
+}
+
 function buildExecutionFailureReplyText(detail, options = {}) {
   const normalizedDetail = String(detail || "").trim();
   const intentType = normalizeHumanIntentType(safeObject(options).intentType);
@@ -4176,6 +4325,9 @@ export async function processRunnerSelectedRecord({
     ...safeObject(buildRunnerExecutionDeps()),
     ...safeObject(deps),
   };
+  const explainExecutionFailureWithAI = typeof executionDeps.explainExecutionFailureWithAI === "function"
+    ? executionDeps.explainExecutionFailureWithAI
+    : null;
   const normalizedPrecomputedHumanIntentContext = safeObject(precomputedHumanIntentContext);
   const normalizedPrecomputedHumanIntent = safeObject(normalizedPrecomputedHumanIntentContext.humanIntent);
   const validateWorkspaceArtifacts = typeof executionDeps.validateWorkspaceArtifacts === "function"
@@ -4413,9 +4565,36 @@ export async function processRunnerSelectedRecord({
     if (!shouldSendExecutionFailureReply({ triggerDecision: effectiveTriggerDecision, selectedRecord })) {
       return null;
     }
-    const replyText = buildExecutionFailureReplyText(detail, {
+    const failureFacts = buildExecutionFailureFacts(detail, {
       intentType: resolvedIntentType,
+      executionMode: effectiveExecutionPlan.mode,
+      roleProfileName: effectiveExecutionPlan.roleProfileName,
+      conversationID: String(conversationContext?.id || "").trim(),
+      rootWorkItemID: firstNonEmptyString([
+        routeState?.active_root_work_item_id,
+        routeState?.last_root_work_item_id,
+      ]),
+      messageID: selectedRecord?.parsedArchive?.messageID,
+      userMessageText: selectedRecord?.parsedArchive?.body,
     });
+    let replyText = "";
+    if (explainExecutionFailureWithAI) {
+      try {
+        const explanation = await Promise.resolve(explainExecutionFailureWithAI({
+          failureFacts,
+          userMessageText: String(selectedRecord?.parsedArchive?.body || "").trim(),
+          botName: String(bot?.name || bot?.username || bot?.id || "").trim(),
+          workspaceDir: String(effectiveExecutionPlan.workspaceDir || "").trim(),
+          env: process.env,
+        }));
+        replyText = String(safeObject(explanation).reply || safeObject(explanation).message || "").trim();
+      } catch {}
+    }
+    if (!replyText) {
+      replyText = buildExecutionFailureReplyText(detail, {
+        intentType: resolvedIntentType,
+      });
+    }
     if (!replyText) {
       return null;
     }

package/lib/selftest-runner-scenarios.mjs

@@ -5207,6 +5207,148 @@ export async function runSelftestRunnerScenarios(push, deps) {
     push("single_bot_human_work_request_requires_actionable_contract", false, String(err?.message || err));
   }
 
+  try {
+    let aiCalls = 0;
+    let deliveryCalls = 0;
+    let deliveredText = "";
+    let capturedFailureFacts = null;
+    const processed = await processRunnerSelectedRecord({
+      routeKey: "single-bot-human-work-request-ai-failure-explainer-key",
+      normalizedRoute: normalizeRunnerRoute({
+        name: "telegram-monitor-single-bot-human-work-request-ai-failure-explainer",
+        project_id: selftestProjectID,
+        provider: "telegram",
+        role: "monitor",
+        role_profile: "monitor",
+        destination_id: "dest-1",
+        destination_label: "Main Room",
+        server_bot_name: "RyoAI_bot",
+        server_bot_id: "bot-lead-1",
+        trigger_policy: {
+          mentions_only: true,
+          direct_messages: true,
+          reply_to_bot_messages: true,
+        },
+        archive_policy: {
+          mirror_replies: true,
+          dedupe_inbound: true,
+          dedupe_outbound: true,
+          skip_bot_messages: true,
+        },
+        dry_run_delivery: true,
+      }),
+      selectedRecord: {
+        id: "comment-single-bot-human-work-request-ai-failure-explainer",
+        createdAt: "2026-03-16T00:02:05.500Z",
+        parsedArchive: {
+          kind: "telegram_message",
+          chatID: "-100123",
+          chatType: "supergroup",
+          senderIsBot: false,
+          body: "@RyoAI_bot update the implementation guide now.",
+          mentionUsernames: ["RyoAI_bot"],
+          messageID: 1206,
+        },
+      },
+      pendingOrdered: [],
+      bot: {
+        id: "bot-lead-1",
+        name: "RyoAI_bot",
+        username: "RyoAI_bot",
+        role: "monitor",
+        provider: "telegram",
+      },
+      destination: {
+        id: "dest-1",
+        label: "Main Room",
+        provider: "telegram",
+        chatID: "-100123",
+      },
+      archiveThread: {
+        threadID: "thread-1",
+        workItemID: "work-item-1",
+      },
+      executionPlan: {
+        mode: "role_profile",
+        roleProfileName: "monitor",
+        roleProfile: {
+          client: "sample",
+          model: "",
+          permissionMode: "read_only",
+          reasoningEffort: "low",
+        },
+        workspaceDir: process.cwd(),
+        workspaceSource: "selftest",
+        usedCommandFallback: false,
+      },
+      runtime: {
+        baseURL: "https://example.test",
+        token: "selftest-token",
+        timeoutSeconds: 30,
+        actor: { user_id: "user-1" },
+      },
+      deps: {
+        saveRunnerRouteState: () => {},
+        startRunnerTypingHeartbeat: () => ({ async stop() {} }),
+        runRunnerAIExecution: async () => {
+          aiCalls += 1;
+          return {
+            skip: false,
+            reply: "I reviewed the request but did not produce a contract.",
+            contract: null,
+          };
+        },
+        explainExecutionFailureWithAI: ({ failureFacts }) => {
+          capturedFailureFacts = safeObject(failureFacts);
+          return {
+            classification: "failed",
+            reply: "AI failure summary",
+            next_action: "retry",
+          };
+        },
+        performLocalBotDelivery: async ({ text }) => {
+          deliveryCalls += 1;
+          deliveredText = String(text || "");
+          return {
+            delivery: { dryRun: true, body: {} },
+            archive: {},
+          };
+        },
+        serializeRunnerTriggerPolicy: (value) => value,
+        serializeRunnerArchivePolicy: (value) => value,
+        buildRunnerExecutionDeps: () => ({
+          analyzeHumanConversationIntentWithAI: async () => ({
+            mode: "single_bot",
+            lead_bot: "ryoai_bot",
+            participants: ["ryoai_bot"],
+            initial_responders: ["ryoai_bot"],
+            allowed_responders: ["ryoai_bot"],
+            summary_bot: "",
+            allow_bot_to_bot: false,
+            reply_expectation: "actionable",
+          }),
+        }),
+        buildRunnerDeliveryDeps: () => ({}),
+        buildRunnerRuntimeDeps: () => ({}),
+        resolveConversationPeerBots: () => [
+          { id: "bot-lead-1", name: "RyoAI_bot" },
+        ],
+      },
+    });
+    push(
+      "single_bot_execution_failure_uses_ai_failure_explainer_when_available",
+      processed.kind === "error"
+        && aiCalls >= 1
+        && deliveryCalls === 1
+        && deliveredText === "AI failure summary"
+        && String(capturedFailureFacts?.error_type || "") === "missing_actionable_contract"
+        && String(capturedFailureFacts?.stage || "") === "execution_contract",
+      `kind=${String(processed.kind || "(none)")} outcome=${String(processed.result?.outcome || "(none)")} ai_calls=${aiCalls} delivery_calls=${deliveryCalls} delivered=${deliveredText} failure_type=${String(capturedFailureFacts?.error_type || "(none)")} stage=${String(capturedFailureFacts?.stage || "(none)")}`,
+    );
+  } catch (err) {
+    push("single_bot_execution_failure_uses_ai_failure_explainer_when_available", false, String(err?.message || err));
+  }
+
   try {
     let aiCalls = 0;
     const processed = await processRunnerSelectedRecord({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.206",
+  "version": "0.2.207",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [