metheus-governance-mcp-cli 0.2.268 → 0.2.270

package/lib/local-ai-adapters.mjs

@@ -212,6 +212,67 @@ function readOutputFile(filePath) {
   return fs.readFileSync(filePath, "utf8");
 }
 
+export function looksLikeCodexCliSessionTranscript(rawText = "") {
+  const text = String(rawText || "").trim();
+  if (!text) {
+    return false;
+  }
+  return /OpenAI Codex v|session id:|^workdir:|^model:|^provider:|^approval:|^sandbox:|^reasoning effort:|^--------|^user$|^codex$|mcp:.*\b(starting|ready)\b/i.test(text);
+}
+
+function summarizeCodexCliFailure({
+  status = 0,
+  stdoutText = "",
+  stderrText = "",
+  spawnError = null,
+}) {
+  const genericMessage = status
+    ? `Codex CLI exited before returning a final reply (status ${status})`
+    : "Codex CLI exited before returning a final reply";
+  if (spawnError) {
+    const spawnMessage = String(spawnError?.message || spawnError || "").trim();
+    return spawnMessage
+      ? `${genericMessage}: ${spawnMessage}`
+      : genericMessage;
+  }
+  const candidateLines = `${String(stderrText || "")}\n${String(stdoutText || "")}`
+    .split(/\r?\n/)
+    .map((line) => String(line || "").trim())
+    .filter(Boolean)
+    .filter((line) => !looksLikeCodexCliSessionTranscript(line))
+    .filter((line) => /(error|failed|timeout|timed out|denied|missing|unavailable|not found|capacity)/i.test(line))
+    .slice(0, 2);
+  return candidateLines.length
+    ? `${genericMessage}: ${candidateLines.join(" | ")}`
+    : genericMessage;
+}
+
+export function resolveCodexRawTextProcessResult({
+  outputText = "",
+  stdoutText = "",
+  stderrText = "",
+  status = 0,
+  spawnError = null,
+}) {
+  const normalizedOutputText = String(outputText || "").trim();
+  if (normalizedOutputText && !looksLikeCodexCliSessionTranscript(normalizedOutputText)) {
+    return normalizedOutputText;
+  }
+  const normalizedStdoutText = String(stdoutText || "").trim();
+  if (normalizedStdoutText && !looksLikeCodexCliSessionTranscript(normalizedStdoutText)) {
+    return normalizedStdoutText;
+  }
+  if (spawnError || status !== 0) {
+    throw new Error(summarizeCodexCliFailure({
+      status,
+      stdoutText: normalizedStdoutText,
+      stderrText,
+      spawnError,
+    }));
+  }
+  throw new Error("Codex CLI did not return a usable final reply");
+}
+
 function tryParseEmbeddedJsonObject(text) {
   const raw = String(text || "").trim();
   if (!raw) return null;
@@ -686,13 +747,13 @@ function runCodexRawText({ promptText, workspaceDir, model, permissionMode, reas
         maxBuffer: 8 * 1024 * 1024,
       },
     );
-    if (result.error) {
-      throw new Error(String(result.error?.message || result.error));
-    }
-    if (result.status !== 0) {
-      throw new Error(String(result.stderr || result.stdout || `codex exited with status ${result.status}`));
-    }
-    return readOutputFile(outputPath) || String(result.stdout || "");
+    return resolveCodexRawTextProcessResult({
+      outputText: readOutputFile(outputPath),
+      stdoutText: String(result.stdout || ""),
+      stderrText: String(result.stderr || ""),
+      status: Number.isInteger(result.status) ? result.status : 0,
+      spawnError: result.error || null,
+    });
   } finally {
     if (fs.existsSync(outputPath)) {
       fs.rmSync(outputPath, { force: true });
@@ -1876,6 +1937,9 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
     `- Trigger hint reason: ${String(responseContract.candidate_reason || "-").trim() || "-"}`,
     `- Mentioned bot usernames: ${ensureArray(responseContract.candidate_bot_usernames).length ? ensureArray(responseContract.candidate_bot_usernames).map((item) => `@${String(item || "").trim().replace(/^@+/, "")}`).join(", ") : "-"}`,
     `- Reply target bot username: ${String(responseContract.reply_to_bot_username || "").trim() ? `@${String(responseContract.reply_to_bot_username || "").trim().replace(/^@+/, "")}` : "-"}`,
+    String(responseContract.reply_to_bot_username || "").trim()
+      ? `- If you answer directly to that target bot, start the visible reply with @${String(responseContract.reply_to_bot_username || "").trim().replace(/^@+/, "")}.`
+      : "",
     "",
     "Project background (context only):",
     `- Project ID: ${projectID || "-"}`,

package/lib/runner-orchestration-intent-contracts.mjs

@@ -17,6 +17,40 @@ function intFromRawAllowZero(raw, fallback = 0) {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+function escapeRegexText(value) {
+  return String(value || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function detectDirectedManagedReplyTarget({
+  text,
+  currentBotSelector = "",
+  managedMentions = [],
+}) {
+  const normalizedText = String(text || "").trim();
+  const currentSelector = String(currentBotSelector || "").trim().toLowerCase();
+  if (!normalizedText || !currentSelector) {
+    return "";
+  }
+  const instructionPattern = /(?:\b(?:say|tell|greet|reply|answer|introduce|mention)\b|인사(?:해|하)|말(?:해|하)|얘기(?:해|하)|전달(?:해|하)|전해|알려|소개(?:해|하)|답(?:해|하)|응답(?:해|하)|말씀(?:해|하))/i;
+  if (!instructionPattern.test(normalizedText)) {
+    return "";
+  }
+  const candidates = ensureArray(managedMentions)
+    .map((item) => String(item || "").trim().toLowerCase())
+    .filter((item) => item && item !== currentSelector);
+  for (const selector of candidates) {
+    const escapedSelector = escapeRegexText(String(selector || "").replace(/^@+/, ""));
+    const targetPattern = new RegExp(
+      `(?:@${escapedSelector}\\s*(?:에게|한테|께|보고)?|(?:to|for)\\s+@${escapedSelector}\\b)`,
+      "i",
+    );
+    if (targetPattern.test(normalizedText)) {
+      return selector;
+    }
+  }
+  return "";
+}
+
 export async function resolveHumanIntentContext({
   selectedRecord,
   normalizedRoute,
@@ -84,6 +118,17 @@ export async function resolveHumanIntentContext({
     runnerHumanIntentPromises.set(cacheKey, promise);
   }
   let humanIntent = await runnerHumanIntentPromises.get(cacheKey);
+  const directedReplyTargetSelector = detectDirectedManagedReplyTarget({
+    text: parsed.body,
+    currentBotSelector,
+    managedMentions,
+  });
+  if (directedReplyTargetSelector) {
+    humanIntent = {
+      ...safeObject(humanIntent),
+      replyTargetBotSelector: directedReplyTargetSelector,
+    };
+  }
   if (!isCompleteHumanIntentContract(humanIntent)) {
     return {
       currentBotSelector,
@@ -152,6 +197,12 @@ export function buildDirectHumanResponseContract({
   );
   const requiresActionableContract = source.requiresActionableContract === true
     || source.require_actionable_contract === true;
+  const replyTargetBotSelector = normalizeMentionSelector(
+    source.replyTargetBotSelector
+    || source.reply_target_bot
+    || source.reply_to_bot_username
+    || "",
+  );
   return {
     intentMode,
     allowBotToBot,
@@ -163,6 +214,7 @@ export function buildDirectHumanResponseContract({
     intentType,
     requiresActionableContract,
     allowedContractTypes,
+    replyTargetBotSelector,
   };
 }
 
@@ -213,6 +265,7 @@ export function mergeDirectHumanResponseContract({
   const explicitAllowBotToBot = readExplicit(["allow_bot_to_bot", "allowBotToBot"]);
   const explicitLeadBot = readExplicit(["human_lead_bot"]);
   const explicitSummaryBot = readExplicit(["human_summary_bot"]);
+  const explicitReplyTargetBot = readExplicit(["human_reply_target_bot", "reply_to_bot_username"]);
   const intentMode = String(
     explicitIntentMode
     || base.intentMode
@@ -255,6 +308,11 @@ export function mergeDirectHumanResponseContract({
     || base.summaryBotSelector
     || "",
   );
+  const replyTargetBotSelector = normalizeMentionSelector(
+    explicitReplyTargetBot
+    || base.replyTargetBotSelector
+    || "",
+  );
   const requiresActionableContract = base.requiresActionableContract === true;
   const allowedContractTypes = ensureArray(base.allowedContractTypes)
     .map((item) => String(item || "").trim().toLowerCase())
@@ -271,6 +329,7 @@ export function mergeDirectHumanResponseContract({
     intentType,
     requiresActionableContract,
     allowedContractTypes,
+    replyTargetBotSelector,
   };
 }
 

package/lib/runner-orchestration-selected-record-delivery-context.mjs

@@ -26,6 +26,7 @@ export async function prepareRunnerSelectedRecordDeliveryContext({
   bot,
   selectedRecord,
   currentBotSelector = "",
+  replyTargetBotSelector = "",
   executionContract = null,
   effectiveTriggerDecision,
   effectiveConversationContext = null,
@@ -55,13 +56,28 @@ export async function prepareRunnerSelectedRecordDeliveryContext({
   }
 
   const normalizedExecutionContractType = String(executionContract?.type || "").trim().toLowerCase();
-  const sanitizedReplyText = sanitizeForcedDirectReplyText({
+  const normalizedReplyTargetBotSelector = normalizeMentionSelector(replyTargetBotSelector);
+  let sanitizedReplyText = sanitizeForcedDirectReplyText({
     replyText: aiResult?.reply,
     bot,
     selectedRecord,
     triggerDecision: effectiveTriggerDecision,
     conversationContext: effectiveConversationContext,
   });
+  if (
+    sanitizedReplyText
+    && normalizedReplyTargetBotSelector
+    && normalizedReplyTargetBotSelector !== currentBotSelector
+  ) {
+    const visibleReplyTargets = extractManagedPeerMentionSelectors(
+      sanitizedReplyText,
+      directHumanPeerMap,
+      currentBotSelector,
+    );
+    if (!visibleReplyTargets.includes(normalizedReplyTargetBotSelector)) {
+      sanitizedReplyText = `@${normalizedReplyTargetBotSelector} ${String(sanitizedReplyText || "").trim()}`.trim();
+    }
+  }
   const attemptedDeliveryEnvelope = buildTelegramBotReplyEnvelope({
     sourceEnvelope: sourceMessageEnvelope,
     messageThreadID: replyMessageThreadID,

package/lib/runner-orchestration.mjs

@@ -258,6 +258,12 @@ export function buildRunnerInputPayload({
       .map((value) => normalizeMentionSelector(value))
       .filter(Boolean),
   );
+  const normalizedReplyTargetBot = normalizeMentionSelector(
+    directHumanIntent.replyTargetBotSelector
+    || directHumanIntent.reply_target_bot
+    || directHumanIntent.reply_to_bot_username
+    || parsed.replyToUsername,
+  );
   const requiredDelegationTargets = uniqueOrdered(
     String(directHumanIntent.intentMode || directHumanIntent.intent_mode || "").trim() === "delegated_single_lead"
     && currentBotSelector
@@ -353,11 +359,12 @@ export function buildRunnerInputPayload({
       self_bot_username: String(bot?.username || "").trim(),
       mentioned_usernames: ensureArray(parsed.mentionUsernames).map((value) => String(value || "").trim()).filter(Boolean),
       candidate_bot_usernames: candidateBotUsernames,
-      reply_to_bot_username: String(parsed.replyToUsername || "").trim(),
+      reply_to_bot_username: normalizedReplyTargetBot,
       human_intent_mode: String(directHumanIntent.intentMode || "").trim(),
       human_intent_type: String(directHumanIntent.intentType || "").trim(),
       human_lead_bot: String(directHumanIntent.leadBotSelector || "").trim(),
       human_summary_bot: String(directHumanIntent.summaryBotSelector || "").trim(),
+      human_reply_target_bot: normalizedReplyTargetBot,
       human_allowed_responders: ensureArray(directHumanIntent.allowedResponderSelectors),
       human_reply_expectation: String(directHumanIntent.replyExpectation || "").trim(),
       require_actionable_contract: directHumanIntent.requiresActionableContract === true,
@@ -378,6 +385,7 @@ export function buildRunnerInputPayload({
         body: String(parsed.body || "").trim(),
         message_id: Number.parseInt(String(parsed.messageID ?? 0), 10) || 0,
         reply_to_message_id: Number.parseInt(String(parsed.replyToMessageID ?? 0), 10) || 0,
+        reply_to_bot_username: normalizedReplyTargetBot,
       },
       conversation_contract: {
         conversation_id: String(directHumanIntent.conversationID || directHumanIntent.conversation_id || parsed.conversationID || "").trim(),
@@ -388,6 +396,7 @@ export function buildRunnerInputPayload({
         participants: ensureArray(directHumanIntent.participantSelectors || directHumanIntent.participants),
         initial_responders: ensureArray(directHumanIntent.initialResponderSelectors || directHumanIntent.initial_responders),
         allowed_responders: ensureArray(directHumanIntent.allowedResponderSelectors || directHumanIntent.allowed_responders),
+        reply_target_bot: normalizedReplyTargetBot,
         reply_expectation: String(directHumanIntent.replyExpectation || directHumanIntent.reply_expectation || "").trim(),
         execution_contract_type: executionContractType,
       },
@@ -3477,6 +3486,7 @@ export async function processRunnerSelectedRecord({
     bot,
     selectedRecord,
     currentBotSelector,
+    replyTargetBotSelector: directHumanResponseContract?.replyTargetBotSelector,
     executionContract,
     effectiveTriggerDecision,
     effectiveConversationContext,

package/lib/selftest-runner-scenarios.mjs

@@ -85,6 +85,9 @@ import {
 import {
   finalizeRunnerRequestRootReferenceRecorderState,
 } from "./runner-recorder-request-root-reference-finalization-handoff.mjs";
+import {
+  resolveCodexRawTextProcessResult,
+} from "./local-ai-adapters.mjs";
 import {
   buildRunnerInheritedRootReferenceRecorderResult,
   buildRunnerRootThreadRecorderFailure,
@@ -6238,6 +6241,149 @@ export async function runSelftestRunnerScenarios(push, deps) {
     push("single_bot_conversational_greeting_request_skips_planner_and_worker", false, String(err?.message || err));
   }
 
+  try {
+    let aiCalls = 0;
+    let plannerCalls = 0;
+    let deliveryCalls = 0;
+    let deliveredText = "";
+    const processed = await processRunnerSelectedRecord({
+      routeKey: "single-bot-conversation-greeting-target-prefix-key",
+      normalizedRoute: normalizeRunnerRoute({
+        name: "telegram-monitor-single-bot-conversation-greeting-target-prefix",
+        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-conversation-greeting-target-prefix",
+        createdAt: "2026-03-31T08:38:56.000Z",
+        parsedArchive: {
+          kind: "telegram_message",
+          chatID: "-100123",
+          chatType: "supergroup",
+          senderIsBot: false,
+          body: "@RyoAI_bot 당신이 @SangHoon01_bot 에게 인사해보세요.",
+          mentionUsernames: ["RyoAI_bot", "SangHoon01_bot"],
+          messageID: 1058,
+        },
+      },
+      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: path.join(os.tmpdir(), "metheus-runner-selftest-single-bot-conversation-greeting-target-prefix"),
+        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: "안녕하세요.",
+            replyToMessageID: 0,
+          };
+        },
+        performLocalBotDelivery: async ({ text }) => {
+          deliveryCalls += 1;
+          deliveredText = String(text || "").trim();
+          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: "informational",
+            intent_type: "small_talk",
+          }),
+          planRoleExecutionWithAI: async () => {
+            plannerCalls += 1;
+            return {
+              requiresExecution: true,
+              summaryRole: "worker",
+              steps: [{ role: "worker", goal: "unexpected", artifactsRequired: true }],
+            };
+          },
+        }),
+        buildRunnerDeliveryDeps: () => ({}),
+        buildRunnerRuntimeDeps: () => ({}),
+        resolveConversationPeerBots: () => [
+          { id: "bot-lead-1", name: "RyoAI_bot" },
+          { id: "bot-peer-1", name: "SangHoon01_bot" },
+        ],
+      },
+    });
+    push(
+      "single_bot_direct_reply_target_prefixes_visible_target_when_ai_omits_mention",
+      processed.kind === "replied"
+        && aiCalls === 1
+        && plannerCalls === 0
+        && deliveryCalls === 1
+        && deliveredText === "@sanghoon01_bot 안녕하세요.",
+      `kind=${String(processed.kind || "(none)")} ai_calls=${aiCalls} planner_calls=${plannerCalls} delivery_calls=${deliveryCalls} delivered=${String(deliveredText || "(none)")}`,
+    );
+  } catch (err) {
+    push("single_bot_direct_reply_target_prefixes_visible_target_when_ai_omits_mention", false, String(err?.message || err));
+  }
+
   try {
     let aiCalls = 0;
     let deliveryCalls = 0;
@@ -18558,6 +18704,48 @@ export async function runSelftestRunnerScenarios(push, deps) {
     push("runner_selected_record_terminal_outcome_stays_within_module_4_boundary", false, String(err?.message || err));
   }
 
+  try {
+    const replyText = resolveCodexRawTextProcessResult({
+      outputText: "{\"reply\":\"하이\"}",
+      stdoutText: "",
+      stderrText: "OpenAI Codex v0.114.0\nsession id: test-session\nmcp: metheus ready",
+      status: 1,
+      spawnError: null,
+    });
+    push(
+      "codex_nonzero_exit_uses_final_output_file_when_available",
+      String(replyText || "").trim() === "{\"reply\":\"하이\"}",
+      `reply=${String(replyText || "(none)")}`,
+    );
+  } catch (err) {
+    push("codex_nonzero_exit_uses_final_output_file_when_available", false, String(err?.message || err));
+  }
+
+  try {
+    let errorMessage = "";
+    try {
+      resolveCodexRawTextProcessResult({
+        outputText: "",
+        stdoutText: "",
+        stderrText: "OpenAI Codex v0.114.0\nworkdir: C:\\LUSH KOREA CLI\nsession id: test-session\nmcp: metheus starting\nmcp: metheus ready",
+        status: 1,
+        spawnError: null,
+      });
+    } catch (err) {
+      errorMessage = String(err?.message || err);
+    }
+    push(
+      "codex_failure_summary_does_not_leak_session_transcript",
+      /Codex CLI exited before returning a final reply/i.test(errorMessage)
+        && !/OpenAI Codex v/i.test(errorMessage)
+        && !/session id:/i.test(errorMessage)
+        && !/mcp:/i.test(errorMessage),
+      errorMessage || "(no error message)",
+    );
+  } catch (err) {
+    push("codex_failure_summary_does_not_leak_session_transcript", false, String(err?.message || err));
+  }
+
   try {
     const prepared = await prepareRunnerSelectedRecordContractContext({
       selectedRecord: {

package/package.json

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