@yugabytedb/meko-mcp 2.2.0 → 2.5.0

package/assets/hooks-handlers/lib/capture-state.js

@@ -131,6 +131,53 @@ function healthCacheFilename() {
   return envString("MEKO_HEALTH_CACHE", DEFAULTS.HEALTH_CACHE);
 }
 
+/**
+ * The retry date `--capture-cleanup` parks a session until. Hooks skip the
+ * network while failure_class is set and next_retry_at is in the future, so
+ * a session with this date is parked, not retrying.
+ */
+const CLEANUP_PARK_UNTIL = "9999-12-31T00:00:00.000Z";
+
+/**
+ * Automatic repair from the checkpoint timer. MEKO_AUTOFIX (on/off) wins when
+ * set; otherwise autofix-config.json in the capture directory, which the
+ * installer writes for --autofix / --no-autofix. On by default.
+ */
+function autofixEnabled() {
+  return autofixSetting().enabled;
+}
+
+/**
+ * Whether automatic repair is on, and what decided it: "env" (MEKO_AUTOFIX),
+ * "config" (autofix-config.json, written by --autofix / --no-autofix), or
+ * "default" (on).
+ */
+function autofixSetting() {
+  const raw = process.env.MEKO_AUTOFIX;
+  if (raw != null && raw !== "") {
+    return { enabled: !/^(0|off|false|no)$/i.test(String(raw)), source: "env", path: null };
+  }
+  const file = autofixConfigPath();
+  try {
+    const cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (cfg && typeof cfg.enabled === "boolean") {
+      return { enabled: cfg.enabled, source: "config", path: file };
+    }
+  } catch {
+    /* no config: default on */
+  }
+  return { enabled: true, source: "default", path: null };
+}
+
+function autofixConfigPath() {
+  return path.join(watermarkDir(), "autofix-config.json");
+}
+
+/** Seconds between automatic `--capture-cleanup fix` runs on one machine. */
+function autofixIntervalSeconds() {
+  return Math.max(60, envInt("MEKO_AUTOFIX_INTERVAL", 1800));
+}
+
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
@@ -162,6 +209,20 @@ function healthCachePath() {
   return path.join(watermarkDir(), healthCacheFilename());
 }
 
+/** Summary of the last `--capture-cleanup fix` run, manual or automatic. */
+function autofixLastPath() {
+  return path.join(watermarkDir(), "autofix-last.json");
+}
+
+function readAutofixLast() {
+  try {
+    const value = JSON.parse(fs.readFileSync(autofixLastPath(), "utf8"));
+    return value && typeof value === "object" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Convert an agent_id into the filesystem slug used by legacy error files and
  * datapack pins (matches capture.js datapackPinSlug).
@@ -293,6 +354,21 @@ function blockedOutcome(failureClass, error, extras) {
   };
 }
 
+/**
+ * MEKO-635: resumable sessions (OpenCode) must not be finalized as
+ * confirmed_dead by timer idle or cross-session recovery. Only OpenCode sets
+ * this policy today; other clients continue to finalize as before. Existing
+ * pre-MEKO-635 `client: "opencode"` watermarks without an explicit
+ * `pending_turn_policy` field are also treated as resumable so upgrades don't
+ * finalize a turn that a later snapshot could still complete.
+ */
+function isResumableState(state) {
+  if (!state || typeof state !== "object") return false;
+  if (state.pending_turn_policy === "resumable") return true;
+  if (state.pending_turn_policy == null && state.client === "opencode") return true;
+  return false;
+}
+
 /**
  * Validate a candidate v2 state object.
  * @returns {{ ok:true, state:Object } | { ok:false, delivery:"blocked", failure_class:"state_corrupt", error:string }}
@@ -342,6 +418,16 @@ function validateV2(state) {
       `invalid failure_class: ${state.failure_class}`,
     );
   }
+  if (
+    state.consecutive_exchange_drops != null &&
+    (!Number.isInteger(state.consecutive_exchange_drops) ||
+      state.consecutive_exchange_drops < 0)
+  ) {
+    return blockedOutcome(
+      "state_corrupt",
+      "consecutive_exchange_drops must be a non-negative integer",
+    );
+  }
   return { ok: true, state };
 }
 
@@ -461,6 +547,7 @@ function normalizeState(raw, context) {
     last_success_at:
       raw.last_success_at == null ? null : String(raw.last_success_at),
     blocked_reason: null,
+    consecutive_exchange_drops: 0,
   };
 
   const validated = validateV2(state);
@@ -938,6 +1025,8 @@ function writeSessionIntent(sessionId, fields) {
               last_error: null,
               last_success_at: null,
               blocked_reason: null,
+              // null = finalize unless client is opencode (isResumableState).
+              pending_turn_policy: null,
             };
 
       const conversationId =
@@ -974,6 +1063,12 @@ function writeSessionIntent(sessionId, fields) {
           : "needs_conversation",
         last_activity_at: nowIso(),
         updated_at: nowIso(),
+        // MEKO-635: preserve or set pending_turn_policy. Only "resumable" is a
+        // meaningful non-default value today; anything else stays null.
+        pending_turn_policy:
+          f.pending_turn_policy !== undefined
+            ? (f.pending_turn_policy === "resumable" ? "resumable" : null)
+            : (base.pending_turn_policy === "resumable" ? "resumable" : null),
       };
 
       if (f.last_line_number != null && existing.missing) {
@@ -1065,6 +1160,10 @@ function rebucket(state, newConversationId) {
     blocked_reason: null,
     next_retry_at: null,
     attempt_count: 0,
+    consecutive_exchange_drops: 0,
+    // A replacement guard belongs only to the conversation that set it.
+    recovered_from_conversation_id: null,
+    missing_conversation_streak: null,
     updated_at: nowIso(),
     last_activity_at: nowIso(),
   };
@@ -1257,6 +1356,8 @@ const PERSISTENT_PATTERNS = [
   ["payment_required", /payment[_\s-]?required/i],
   ["subscription_required", /subscription[_\s-]?(required|inactive|expired)/i],
   ["entitlement_denied", /entitlement.*(denied|required|missing)|(?:denied|required|missing).*entitlement/i],
+  // A viewer of a shared datapack can't record conversations (MEKO-876).
+  ["read_only_access", /read_only_access/i],
 ];
 
 /**
@@ -1384,6 +1485,26 @@ function timerLooksLive(sessionId) {
   }
 }
 
+/**
+ * A session whose client may still be writing turns: its lifecycle is
+ * active and its transcript changed within recoveryMinIdle() seconds, or its
+ * checkpoint timer is alive. --capture-cleanup uses it to decide drain or
+ * recover, and capture.js move re-checks it under the lease.
+ */
+function sessionLooksLive(state, nowMs) {
+  if (!state || state.lifecycle !== "active") return false;
+  const now = nowMs != null ? nowMs : Date.now();
+  if (state.transcript_path) {
+    try {
+      const st = fs.statSync(state.transcript_path);
+      if (now - st.mtimeMs < recoveryMinIdle() * 1000) return true;
+    } catch {
+      // A missing transcript says nothing about liveness; check the timer.
+    }
+  }
+  return timerLooksLive(state.session_id);
+}
+
 function buildEligibility(state, nowMs, options) {
   const opts = options && typeof options === "object" ? options : {};
   const now = nowMs != null ? nowMs : Date.now();
@@ -1467,6 +1588,18 @@ function sessionHealthBucket(entry) {
   ) {
     return "blocked_action_required";
   }
+  // A session that has delivered everything is healthy even if an earlier
+  // attempt failed: failure_class records the last attempt, not outstanding
+  // work. Without this, one transient blip pins a closed, fully drained
+  // session to degraded_retrying forever and the rollup reports degraded with
+  // an empty queue. Blocked classes are checked above and still win, since
+  // those need a human.
+  if (
+    (state.delivery === "complete" || state.delivery === "idle") &&
+    coerceNonNegInt(state.queued_exchanges, 0) === 0
+  ) {
+    return "healthy";
+  }
   if (
     state.delivery === "retry_wait" ||
     fc === "transient" ||
@@ -1554,6 +1687,15 @@ function scanStates(options) {
   return { ok: true, entries, dir };
 }
 
+function scanCompleteForDropClamp(scan) {
+  return Boolean(
+    scan &&
+      scan.ok &&
+      Array.isArray(scan.entries) &&
+      scan.entries.every((entry) => entry && entry.ok !== false),
+  );
+}
+
 function sortOldestFirst(entries) {
   return [...(entries || [])].sort((a, b) => {
     const ak =
@@ -1588,9 +1730,11 @@ function computeAggregateHealth(states, options) {
     blocked_action_required: 0,
   };
   let queued = 0;
+  let dropped = 0;
   let oldestPendingAge = null;
   let lastSuccessAt = null;
   const blockedReasons = [];
+  const dropReasons = [];
   const sessions = [];
   let status = "healthy";
 
@@ -1612,6 +1756,20 @@ function computeAggregateHealth(states, options) {
         : 0;
     queued += q;
 
+    // Exchanges the server will never accept (see capture.js
+    // classifyPersistentCaptureFailure, scope "exchange"). They are not
+    // backlog — capture moved past them — but the user is still owed the
+    // fact that some turns are missing, so they aggregate separately.
+    const d =
+      state && typeof state === "object"
+        ? coerceNonNegInt(state.dropped_exchanges, 0)
+        : 0;
+    dropped += d;
+    if (d > 0 && state.last_drop_reason) {
+      const reason = String(state.last_drop_reason);
+      if (!dropReasons.includes(reason)) dropReasons.push(reason);
+    }
+
     if (state && state.last_success_at) {
       if (
         !lastSuccessAt ||
@@ -1659,7 +1817,18 @@ function computeAggregateHealth(states, options) {
         (entry && entry.failure_class) ||
         null,
       queued_exchanges: q,
+      dropped_exchanges: d,
       lifecycle: state ? state.lifecycle : null,
+      // Why --capture-cleanup parked this session ("stop", "drain failed: ...")
+      // while the park is in effect; null otherwise.
+      parked_reason:
+        state &&
+        state.parked &&
+        typeof state.parked === "object" &&
+        state.failure_class &&
+        state.next_retry_at === CLEANUP_PARK_UNTIL
+          ? String(state.parked.reason || "parked")
+          : null,
     });
   }
 
@@ -1669,14 +1838,17 @@ function computeAggregateHealth(states, options) {
     updated_at: nowIso(nowMs),
     counts,
     queued_exchanges: queued,
+    dropped_exchanges: dropped,
     oldest_pending_age_seconds: oldestPendingAge,
     last_success_at: lastSuccessAt,
     blocked_reasons: blockedReasons,
+    drop_reasons: dropReasons,
     sessions,
   };
 }
 
-function writeHealthCache(health) {
+function writeHealthCache(health, options) {
+  const opts = options && typeof options === "object" ? options : {};
   const existing = readHealthCache();
   const merged = {
     ...(health && typeof health === "object" ? health : {}),
@@ -1690,6 +1862,29 @@ function writeHealthCache(health) {
   ) {
     merged.last_notified_status = existing.last_notified_status;
   }
+  // Drop notices are one-shot per new count. Clamp only after a complete scan
+  // proves the aggregate shrank because watermarks disappeared. A failed scan
+  // or unreadable watermark may recover and must not re-announce old drops.
+  if (
+    merged.last_notified_dropped === undefined &&
+    existing &&
+    existing.last_notified_dropped !== undefined
+  ) {
+    const previous = coerceNonNegInt(existing.last_notified_dropped, 0);
+    merged.last_notified_dropped = opts.clampDropped
+      ? Math.min(previous, coerceNonNegInt(merged.dropped_exchanges, 0))
+      : previous;
+  }
+  // A ready-made status bar text, so meko-statusline.sh needs no JSON parsing
+  // beyond one field. capture-notices requires this module, so load it here.
+  try {
+    const fields = require("./capture-notices").statuslineFields(merged, readAutofixLast());
+    merged.statusline = fields.statusline;
+    merged.statusline_until = fields.statusline_until != null ? fields.statusline_until : null;
+    merged.statusline_after = fields.statusline_after != null ? fields.statusline_after : null;
+  } catch {
+    /* keep the cache write even if the text can't be built */
+  }
   try {
     atomicWriteJson(healthCachePath(), merged);
     return { ok: true, path: healthCachePath(), health: merged };
@@ -2025,6 +2220,13 @@ module.exports = {
   workerMaxAgeSeconds,
   timerMaxAge,
   healthCacheFilename,
+  CLEANUP_PARK_UNTIL,
+  autofixEnabled,
+  autofixSetting,
+  autofixConfigPath,
+  autofixIntervalSeconds,
+  autofixLastPath,
+  readAutofixLast,
 
   // paths
   watermarkDir,
@@ -2032,6 +2234,7 @@ module.exports = {
   leasePath,
   mutationLockPath,
   timerPidPath,
+  sessionLooksLive,
   healthCachePath,
   legacyErrorPath,
   agentSlug,
@@ -2039,6 +2242,7 @@ module.exports = {
   // normalize / validate
   normalizeState,
   validateV2,
+  isResumableState,
 
   // persistence
   readState,
@@ -2063,6 +2267,7 @@ module.exports = {
 
   // scan
   scanStates,
+  scanCompleteForDropClamp,
   sortOldestFirst,
   sessionHealthBucket,
   buildEligibility,

package/assets/hooks-handlers/lib/capture-status-cli.js

@@ -22,6 +22,7 @@ const {
   importLegacyCaptureErrors,
   legacyErrorsSafeToRemove,
   readHealthCache,
+  scanCompleteForDropClamp,
   scanStates,
   writeHealthCache,
 } = require("./capture-state");
@@ -63,12 +64,15 @@ function main() {
     );
   }
 
-  const health = computeAggregateHealth(scan.entries || []);
+  let health = computeAggregateHealth(scan.entries || []);
   const existing = readHealthCache();
   if (existing && existing.last_notified_status !== undefined) {
     health.last_notified_status = existing.last_notified_status;
   }
-  writeHealthCache(health);
+  const written = writeHealthCache(health, {
+    clampDropped: scanCompleteForDropClamp(scan),
+  });
+  if (written.ok) health = written.health;
 
   const payload = captureStatusJson(health);
   if (json) {