@yugabytedb/meko-mcp 2.3.0 → 2.5.1

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

@@ -18,6 +18,8 @@
 "use strict";
 
 const {
+  autofixEnabled,
+  autofixIntervalSeconds,
   computeAggregateHealth,
   readHealthCache,
   scanCompleteForDropClamp,
@@ -107,6 +109,94 @@ function statuslineSuffixFromHealth(health) {
   return `capture:${short}(${queued})`;
 }
 
+const NEEDS_YOU_LABELS = {
+  auth: "API key",
+  account_limit: "plan limit",
+  datapack: "datapack access",
+  forbidden: "access",
+};
+
+/**
+ * Claude Code status bar text for capture, or "" when there is nothing to
+ * show. Built when the health cache is written and read by
+ * meko-statusline.sh, which the npm installer copies and wires into Claude
+ * Code's statusLine; the plugin ships no status-line reader, so a plugin-only
+ * install shows nothing. `autofix` is the last `--capture-cleanup fix` summary
+ * (autofix-last.json). Uses a clock time for the next automatic fix, so the
+ * text stays right between cache writes.
+ *
+ * @param {object} health
+ * @param {object|null} autofix
+ * @param {number} [nowMs]
+ * @returns {string}
+ */
+function statuslineText(health, autofix, nowMs) {
+  return statuslineFields(health, autofix, nowMs).statusline;
+}
+
+/**
+ * statuslineText plus when it stops being true: `statusline_until` (epoch
+ * seconds) and the text to show after that, `statusline_after`. The
+ * status bar compares them with the clock, so "auto-fixed N" disappears after
+ * an hour and "auto-fix at 14:30" turns into "auto-fix soon" at 14:30, even
+ * when nothing rewrites the cache.
+ */
+function statuslineFields(health, autofix, nowMs) {
+  const until = (ms, after) => ({ statusline_until: Math.floor(ms / 1000), statusline_after: after });
+  const h = health && typeof health === "object" ? health : {};
+  const status = h.status || "healthy";
+  const now = nowMs != null ? nowMs : Date.now();
+  const a = autofix && typeof autofix === "object" ? autofix : null;
+  const sessions = Array.isArray(h.sessions) ? h.sessions : [];
+  const queued = Number(h.queued_exchanges || 0);
+  const stopped = sessions.filter((x) => x && x.parked_reason === "stop");
+  const parkedByFix = sessions.filter((x) => x && x.parked_reason && x.parked_reason !== "stop");
+  const stuck = sessions.filter((x) => x && x.status !== "healthy" && !x.parked_reason);
+
+  // A run that never finished (its timer was killed) leaves a placeholder;
+  // once it is older than any run can take, its needs_you list is stale.
+  const ranAtMs = a ? Date.parse(a.ran_at) : NaN;
+  const abandoned = Boolean(a && a.running && (!Number.isFinite(ranAtMs) || now - ranAtMs > 30 * 60 * 1000));
+  const needs = a && !abandoned && Array.isArray(a.needs_you) ? a.needs_you : [];
+  if (needs.length && (parkedByFix.length || stuck.length)) {
+    const labels = [...new Set(needs.map((n) => NEEDS_YOU_LABELS[n.cause] || n.cause))];
+    return { statusline: `capture: needs you (${labels.join(", ")})` };
+  }
+
+  if (status === "healthy") {
+    const fixed = a && a.counts ? Number(a.counts.fixed || 0) : 0;
+    const ranAt = a ? Date.parse(a.ran_at) : NaN;
+    if (a && a.mode === "auto" && fixed > 0 && Number.isFinite(ranAt) && now - ranAt < 3600 * 1000) {
+      return { statusline: `capture: auto-fixed ${fixed}`, ...until(ranAt + 3600 * 1000, "") };
+    }
+    return { statusline: "" };
+  }
+
+  const q = `${queued} queued`;
+  if (!stuck.length && !parkedByFix.length && stopped.length) {
+    return { statusline: `capture: paused (${q})` };
+  }
+
+  let next = "";
+  let due = null;
+  if (autofixEnabled()) {
+    const ranAt = a ? Date.parse(a.ran_at) : NaN;
+    due = (Number.isFinite(ranAt) ? ranAt : now) + autofixIntervalSeconds() * 1000;
+    next =
+      due <= now
+        ? ", auto-fix soon"
+        : `, auto-fix at ${new Date(due).toTimeString().slice(0, 5)}`;
+  }
+  const label =
+    status === "degraded_retrying" ? "retrying" : status === "blocked_action_required" ? "blocked" : null;
+  if (!label) return { statusline: `capture: sending ${queued}` };
+  const text = `capture: ${label} (${q})${next}`;
+  if (due != null && due > now) {
+    return { statusline: text, ...until(due, `capture: ${label} (${q}), auto-fix soon`) };
+  }
+  return { statusline: text };
+}
+
 /**
  * Sentence describing exchanges that were skipped because the server will
  * never accept them, or "" when there are none new to report.
@@ -236,7 +326,8 @@ function buildHealthNotice({ health, previousStatus, previousDropped } = {}) {
         : "catching_up";
 
   const cleanupHint = retriesRunning(h)
-    ? " If the user wants the retries to stop, offer " +
+    ? " To repair it, offer `npx @yugabytedb/meko-mcp@latest " +
+      "--capture-cleanup fix`. To only stop the retries, offer " +
       "`npx @yugabytedb/meko-mcp@latest --capture-cleanup stop`; it parks " +
       "the backlog without deleting it."
     : "";
@@ -429,6 +520,8 @@ module.exports = {
   affectedSessionCount,
   reasonForHealth,
   statuslineSuffixFromHealth,
+  statuslineText,
+  statuslineFields,
   buildHealthNotice,
   injectHealthNotice,
   formatCaptureStatusText,

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).
@@ -1295,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],
 ];
 
 /**
@@ -1422,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();
@@ -1736,6 +1819,16 @@ function computeAggregateHealth(states, options) {
       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,
     });
   }
 
@@ -1782,6 +1875,16 @@ function writeHealthCache(health, options) {
       ? 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 };
@@ -2117,6 +2220,13 @@ module.exports = {
   workerMaxAgeSeconds,
   timerMaxAge,
   healthCacheFilename,
+  CLEANUP_PARK_UNTIL,
+  autofixEnabled,
+  autofixSetting,
+  autofixConfigPath,
+  autofixIntervalSeconds,
+  autofixLastPath,
+  readAutofixLast,
 
   // paths
   watermarkDir,
@@ -2124,6 +2234,7 @@ module.exports = {
   leasePath,
   mutationLockPath,
   timerPidPath,
+  sessionLooksLive,
   healthCachePath,
   legacyErrorPath,
   agentSlug,

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

@@ -13,6 +13,10 @@
  *   node capture.js checkpoint     # stdin hook JSON → drainSession
  *   node capture.js drain          # stdin JSON → drain one session; stdout DrainResult
  *   node capture.js recover        # alias of drain (single-session recovery)
+ *   node capture.js move           # stdin {"session_id"} → move the unsent
+ *                                  # tail to a new conversation; stdout
+ *                                  # {ok, from, to, last_line_number} or
+ *                                  # {ok:false, busy?, error}
  *
  * drain / recover stdin contract (Workstream C):
  *   {
@@ -1563,6 +1567,9 @@ function classifyPersistentCaptureFailure(err, opts) {
     // access is (re-)granted out of band, so the caller should hold rather
     // than retry forever or silently drop the turn.
     ["datapack_access_denied", /datapack_access_denied/],
+    // MEKO-876: a viewer of a shared datapack can't record conversations.
+    // Account-scoped like the above: it stays refused until the role changes.
+    ["read_only_access", /read_only_access/],
   ];
   for (const [code, pattern] of persistentPatterns) {
     if (pattern.test(normalized)) {
@@ -1575,6 +1582,7 @@ function classifyPersistentCaptureFailure(err, opts) {
         subscription_required: "capture requires an active subscription",
         entitlement_denied: "the account is not entitled to capture conversations",
         datapack_access_denied: "the account does not have access to the target datapack",
+        read_only_access: "the account has viewer (read-only) access to the target datapack",
       };
       return { code, reason: reasons[code], scope: "account", detail };
     }
@@ -1771,6 +1779,111 @@ async function recoverMissingConversation({
   return { ok: true, state: written.state || next, convId: newConvId };
 }
 
+/**
+ * Move a session's unsent turns to a new conversation on request, without
+ * waiting for capture to see `not_found` twice. Used by
+ * `--capture-cleanup fix` when the recorded conversation can't be served:
+ * its owner reads as `None`, its lookup keeps failing, or a replay loop
+ * bloated it. Holds the drain lease for the whole move, keeps the cursor,
+ * and creates the conversation under the session's recorded owner and
+ * datapack.
+ *
+ * The caller can pass `expected_conversation_id`. Under the lease, the move
+ * is refused (`changed: true`) when the session's conversation no longer
+ * matches it, or when a previous move is still waiting for its new
+ * conversation to accept a turn (`recovered_from_conversation_id`): a hook
+ * drain may have recovered or delivered the session while the caller waited.
+ *
+ * @param {{ session_id: string, expected_conversation_id?: string }} options
+ * @returns {Promise<{ok: boolean, busy?: boolean, changed?: boolean, from?: string, to?: string, last_line_number?: number, error?: string}>}
+ */
+async function moveSessionToNewConversation(options) {
+  const sessionId = String((options && options.session_id) || "").trim();
+  if (!sessionId) return { ok: false, error: "session_id required" };
+  const lease = captureState.acquireLease(sessionId);
+  if (!lease.ok) {
+    return {
+      ok: false,
+      busy: lease.failure_class === "ownership",
+      error: lease.error || "drain lease unavailable",
+    };
+  }
+  try {
+    const read = captureState.readState(sessionId);
+    if (!read.ok) return { ok: false, error: read.error || "watermark unreadable" };
+    let state = read.state;
+    if (!state.agent_id) return { ok: false, error: "recorded owner missing" };
+    const expected = options && options.expected_conversation_id;
+    // An automatic cleanup run must not end a park the user set with `stop`
+    // after that run scanned the session.
+    if (
+      options &&
+      options.respect_stop &&
+      state.parked &&
+      state.parked.reason === "stop" &&
+      state.failure_class &&
+      state.next_retry_at === captureState.CLEANUP_PARK_UNTIL
+    ) {
+      return { ok: false, paused: true, error: "paused by the user with stop" };
+    }
+    if (state.recovered_from_conversation_id) {
+      return {
+        ok: false,
+        changed: true,
+        error: "a previous move is waiting for its new conversation to accept a turn",
+      };
+    }
+    if (expected && state.conversation_id !== expected) {
+      return {
+        ok: false,
+        changed: true,
+        error: `the session moved to conversation ${state.conversation_id} while waiting`,
+      };
+    }
+    // Checked again here, under the lease: the session may have become live
+    // after --capture-cleanup planned the move. SessionStart gave a live
+    // session's agent its conversation_id, and a move can't tell it the new one.
+    if (options && options.defer_if_live && captureState.sessionLooksLive(state)) {
+      return { ok: false, deferred: true, error: "the session is still open" };
+    }
+    // MEKO-592: a session that started before the user pinned a datapack has
+    // none in its watermark. Re-read the pin the way drainSession does, so
+    // the new conversation is created in the datapack its turns will go to.
+    if (!state.datapack_id) {
+      const pin = readDatapackPin(state.agent_id);
+      if (pin && pin.datapack_id) {
+        state = { ...state, datapack_id: pin.datapack_id, datapack_name: pin.datapack_name || null };
+      }
+    }
+    await mcpInitialize();
+    const moved = await recoverMissingConversation({
+      // cleanup_moved_epoch lets --capture-cleanup count epochs since its own
+      // last move, not the session's lifetime total. The move also ends any
+      // park the cleanup tool set (the retry fields are reset here).
+      state: {
+        ...state,
+        parked: null,
+        cleanup_moved_epoch: Number(state.conversation_epoch || 0) + 1,
+      },
+      sessionId,
+      agentId: state.agent_id,
+      transcriptPath: state.transcript_path,
+      datapackId: state.datapack_id || null,
+    });
+    if (!moved.ok) return { ok: false, error: moved.error };
+    return {
+      ok: true,
+      from: state.conversation_id || null,
+      to: moved.convId,
+      last_line_number: moved.state.last_line_number,
+    };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  } finally {
+    captureState.releaseLease(sessionId, lease.lease.token);
+  }
+}
+
 /**
  * Abort all pending MCP requests. Used by the preload timeout path so the
  * SessionStart hook can return promptly instead of waiting for a slow server
@@ -1894,6 +2007,7 @@ function peekTranscriptMetadata(transcriptPath) {
 async function fetchRecentMemories(agentId, datapackId = null, { limit = 10, budget = 2000 } = {}) {
   // memory_get_all takes no `limit`, and FastMCP rejects an unknown argument
   // with an isError result, so `limit` caps the page client-side instead.
+  // Don't send `page_size` either: a server older than MEKO-453 rejects it.
   const payload = {
     agent_id: agentId,
     conversation_id: "00000000-0000-0000-0000-000000000000",
@@ -2324,7 +2438,7 @@ function buildSessionStartFallbackContext(agentId, opts) {
   // act on.
   const reason = opts && opts.reason;
   const preamble = reason === "datapack_required"
-    ? "The SessionStart hook reached the Meko MCP server, but no datapack is pinned for this project, so the server declined to create a conversation. **Automatic conversation capture is idle**. Use `datapack_list` to find a datapack id, then invoke the `meko-select-datapack` skill (or your client's equivalent) to pin it. The next drain picks up the fresh pin and starts capturing this session's queued turns; until then, save facts explicitly."
+    ? "The SessionStart hook reached the Meko MCP server, but no datapack is pinned for this project, so the server declined to create a conversation. **Automatic conversation capture is idle**. Use `datapack_search(query=...)` (or `datapack_list` on a server without it) to find a datapack id, then invoke the `meko-select-datapack` skill (or your client's equivalent) to pin it. The next drain picks up the fresh pin and starts capturing this session's queued turns; until then, save facts explicitly."
     : "The SessionStart hook could not reach the Meko MCP server to create a conversation. **Automatic conversation capture is NOT running this session**, so the server-side extraction that normally saves memories for you will not fire. Fall back to saving facts explicitly.";
   return `## Meko Memory Instructions
 
@@ -2651,7 +2765,7 @@ async function handleSessionStart(hookInput) {
     const isDatapackRequired = err && err.code === "datapack_id_required";
     if (isDatapackRequired) {
       process.stderr.write(
-        `[meko-capture] SessionStart: no datapack pinned; auto-capture is idle. Pin one with datapack_list + meko-select-datapack; the next drain picks up the fresh pin.\n`,
+        `[meko-capture] SessionStart: no datapack pinned; auto-capture is idle. Pin one with datapack_search (or datapack_list) + meko-select-datapack; the next drain picks up the fresh pin.\n`,
       );
     } else if (err && err.isMcpToolError) {
       // Server accepted the call and returned a structured error (e.g.
@@ -3683,10 +3797,11 @@ async function main() {
     "checkpoint",
     "drain",
     "recover",
+    "move",
   ];
   if (!hookType || !known.includes(hookType)) {
     process.stderr.write(
-      "Usage: capture.js <session-start|before-submit-prompt|pre-compact|session-end|checkpoint|drain|recover>\n",
+      "Usage: capture.js <session-start|before-submit-prompt|pre-compact|session-end|checkpoint|drain|recover|move>\n",
     );
     process.exit(1);
   }
@@ -3699,7 +3814,11 @@ async function main() {
     process.stderr.write(
       `[meko-capture] Failed to parse hook input from stdin: ${err.message}\n`,
     );
-    if (hookType === "drain" || hookType === "recover") {
+    if (hookType === "move") {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, error: `invalid stdin JSON: ${err.message}` })}\n`,
+      );
+    } else if (hookType === "drain" || hookType === "recover") {
       process.stdout.write(
         JSON.stringify(
           makeDrainResult({
@@ -3720,6 +3839,12 @@ async function main() {
     return;
   }
 
+  if (hookType === "move") {
+    const result = await moveSessionToNewConversation(hookInput);
+    process.stdout.write(JSON.stringify(result) + "\n");
+    return;
+  }
+
   if (hookType === "before-submit-prompt") {
     handleBeforeSubmitPrompt(hookInput);
     return;
@@ -3796,6 +3921,7 @@ module.exports = {
   addMessage,
   isMissingConversationError,
   recoverMissingConversation,
+  moveSessionToNewConversation,
 };
 
 if (require.main === module) {