@yugabytedb/meko-mcp 1.1.0 → 1.2.0

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

@@ -21,6 +21,7 @@
  */
 
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const http = require("http");
 const https = require("https");
@@ -71,20 +72,46 @@ function deriveAgentId(opts) {
  * Resolution order:
  *   1. MEKO_AGENT_ID env override (verbatim).
  *   2. cwd from the transcript header (peekTranscriptMetadata).
- *   3. process.cwd() — last resort if no transcript metadata yet.
+ *   3. explicit workspace/project roots from the hook input.
+ *   4. cwd from the hook input.
+ *   5. process.cwd() — last resort if no transcript metadata yet.
  */
-function resolveSessionAgentId(transcriptPath) {
+function resolveSessionAgentId(transcriptPath, hookInput = null) {
   const envOverride = process.env.MEKO_AGENT_ID;
   if (envOverride && envOverride.trim()) return envOverride.trim();
   const meta = transcriptPath ? peekTranscriptMetadata(transcriptPath) : null;
-  const cwd = (meta && meta.cwd) || process.cwd();
-  return deriveAgentId({ client: "claude_code", cwd, envOverride });
+  const nested = hookInput && hookInput.hookSpecificInput && typeof hookInput.hookSpecificInput === "object"
+    ? hookInput.hookSpecificInput
+    : {};
+  const roots = hookInput && Array.isArray(hookInput.workspace_roots)
+    ? hookInput.workspace_roots
+    : [];
+  const nestedRoots = Array.isArray(nested.workspace_roots) ? nested.workspace_roots : [];
+  const workspaceRoot = [...roots, ...nestedRoots]
+    .find((item) => typeof item === "string" && item.trim());
+  const cwd =
+    (meta && meta.cwd) ||
+    hookInput?.workspace_path ||
+    hookInput?.workspacePath ||
+    hookInput?.project_root ||
+    nested.workspace_path ||
+    nested.workspacePath ||
+    nested.project_root ||
+    workspaceRoot ||
+    hookInput?.cwd ||
+    nested.cwd ||
+    process.cwd();
+  const client = process.env.MEKO_HOOK_CLIENT === "cursor" ? "cursor" : "claude_code";
+  return deriveAgentId({ client, cwd, envOverride });
 }
 const MEKO_API_KEY = process.env.MEKO_API_KEY || "";
 const MEKO_API_TIMEOUT = parseInt(process.env.MEKO_API_TIMEOUT || "10", 10) * 1000;
 const WATERMARK_DIR =
   process.env.MEKO_WATERMARK_DIR ||
-  path.join(process.env.HOME || "~", ".claude", "meko-capture");
+  path.join(os.homedir(), ".claude", "meko-capture");
+const SESSION_CACHE_DIR =
+  process.env.MEKO_SESSION_CACHE_DIR ||
+  path.join(os.homedir(), ".cursor", "meko-session-cache");
 
 let mcpRequestId = 0;
 let mcpSessionId = null; // MCP Streamable HTTP session ID
@@ -367,7 +394,7 @@ function mcpPost(jsonBody) {
             return;
           }
           try {
-            const parsed = JSON.parse(data);
+            const parsed = parseMcpResponseBody(data);
             if (parsed.error) {
               reject(new Error(JSON.stringify(parsed.error)));
             } else {
@@ -395,6 +422,37 @@ function mcpPost(jsonBody) {
   });
 }
 
+function parseMcpResponseBody(data) {
+  const trimmed = data.trim();
+  if (!trimmed) return null;
+
+  if (!trimmed.startsWith("event:") && !trimmed.startsWith("data:")) {
+    return JSON.parse(trimmed);
+  }
+
+  const payloads = [];
+  let current = [];
+  for (const line of data.split(/\r?\n/)) {
+    if (line === "") {
+      if (current.length) {
+        payloads.push(current.join("\n"));
+        current = [];
+      }
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      current.push(line.startsWith("data: ") ? line.slice(6) : line.slice(5));
+    }
+  }
+  if (current.length) payloads.push(current.join("\n"));
+
+  const payload = payloads.find((item) => item.trim()) || "";
+  if (!payload) {
+    throw new Error("SSE response did not include a data payload");
+  }
+  return JSON.parse(payload);
+}
+
 /**
  * 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
@@ -580,12 +638,112 @@ function hookEventName(hookType) {
 }
 
 function hookOutput(additionalContext) {
-  return JSON.stringify({
+  // Emit the native coding-agent harness field while preserving the nested
+  // Claude-compatible shape for clients that still consume it.
+  const output = {
     hookSpecificOutput: {
       hookEventName: hookEventName(process.argv[2]),
       additionalContext: additionalContext || "",
     },
-  });
+  };
+  if (process.argv[2] === "session-start") {
+    output.additional_context = additionalContext || "";
+  }
+  return JSON.stringify(output);
+}
+
+function nativeOutput(additionalContext) {
+  return JSON.stringify({ additional_context: additionalContext || "" });
+}
+
+function beforeSubmitOutput(shouldContinue, userMessage = "") {
+  const output = { continue: Boolean(shouldContinue) };
+  if (userMessage) output.user_message = userMessage;
+  return JSON.stringify(output);
+}
+
+function extractSessionId(hookInput, transcriptPath) {
+  if (transcriptPath) return path.basename(transcriptPath, ".jsonl");
+  const nested = hookInput && hookInput.hookSpecificInput && typeof hookInput.hookSpecificInput === "object"
+    ? hookInput.hookSpecificInput
+    : {};
+  for (const value of [
+    hookInput && hookInput.session_id,
+    hookInput && hookInput.sessionId,
+    nested.session_id,
+    nested.sessionId,
+  ]) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+function sessionCachePath(sessionId) {
+  if (!sessionId) return null;
+  const safe = sessionId.replace(/[^A-Za-z0-9_.-]/g, "_");
+  return path.join(SESSION_CACHE_DIR, `${safe}.json`);
+}
+
+function writeSessionCache(sessionId, payload) {
+  const filePath = sessionCachePath(sessionId);
+  if (!filePath) return;
+  const workspaceKey = payload.workspace_key || "";
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const record = {
+    session_id: sessionId,
+    updated_at: new Date().toISOString(),
+    ...payload,
+  };
+  fs.writeFileSync(filePath, JSON.stringify(record));
+  if (workspaceKey) {
+    const safe = workspaceKey.replace(/[^A-Za-z0-9_.-]/g, "_");
+    fs.writeFileSync(path.join(SESSION_CACHE_DIR, `workspace-${safe}.json`), JSON.stringify(record));
+  }
+}
+
+function readSessionCache(sessionId) {
+  const filePath = sessionCachePath(sessionId);
+  if (!filePath) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function workspaceKeyFromHookInput(hookInput, transcriptPath) {
+  const roots = hookInput && Array.isArray(hookInput.workspace_roots)
+    ? hookInput.workspace_roots
+    : [];
+  const firstRoot = roots.find((item) => typeof item === "string" && item.trim());
+  if (firstRoot) return firstRoot.trim();
+  if (transcriptPath) return path.dirname(transcriptPath);
+  const cwd = hookInput && typeof hookInput.cwd === "string" && hookInput.cwd.trim()
+    ? hookInput.cwd.trim()
+    : "";
+  return cwd || process.cwd();
+}
+
+function readWorkspaceSessionCache(workspaceKey) {
+  if (!workspaceKey) return null;
+  const safe = workspaceKey.replace(/[^A-Za-z0-9_.-]/g, "_");
+  try {
+    return JSON.parse(fs.readFileSync(path.join(SESSION_CACHE_DIR, `workspace-${safe}.json`), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function selectSessionCache(sessionId, workspaceKey) {
+  const exactCache = sessionId ? readSessionCache(sessionId) : null;
+  const workspaceCache = readWorkspaceSessionCache(workspaceKey);
+  const cache =
+    exactCache && exactCache.status === "ready"
+      ? exactCache
+      : workspaceCache && workspaceCache.status === "ready"
+        ? workspaceCache
+        : exactCache || workspaceCache;
+  return cache;
 }
 
 // --- Main ---
@@ -688,6 +846,21 @@ The SessionStart hook could not reach the Meko MCP server to create a conversati
 When Meko MCP tools are available, ALWAYS use them instead of local file-based memory. If a Meko tool call fails, fall back to local storage and tell the user.`;
 }
 
+function buildBootstrapPendingContext(agentId) {
+  const resolvedAgentId = agentId || COMMON_BUCKET_AGENT_ID;
+  return `## Meko Bootstrap Pending
+
+The Cursor SessionStart hook has started Meko bootstrap work in the background, but the local Meko session cache is not ready yet. Do not guess a Meko conversation_id.
+
+### What you should do
+
+- **agent_id**: use "${resolvedAgentId}" for project-scoped reads/writes if a Meko MCP call is necessary before bootstrap completes
+- **conversation_id**: use nil UUID "00000000-0000-0000-0000-000000000000" only as a placeholder until the cache provides the real conversation_id
+- **scope**: Only "read", "write", or "admin"
+
+If the user explicitly needs Meko-backed continuity before proceeding, ask them to retry the prompt after bootstrap finishes.`;
+}
+
 /**
  * Race a promise against a timeout; on timeout resolve to the fallback value.
  * Memory preload is best-effort — if it stalls, the SessionStart hook must
@@ -727,17 +900,51 @@ function withTimeout(promise, ms, fallback, { onTimeout } = {}) {
   });
 }
 
+function handleSessionPending(hookInput) {
+  const transcriptPath =
+    hookInput.transcript_path ||
+    (hookInput.hookSpecificInput || {}).transcript_path;
+  const sessionId = extractSessionId(hookInput, transcriptPath);
+  const agentId = resolveSessionAgentId(transcriptPath, hookInput);
+  const workspaceKey = workspaceKeyFromHookInput(hookInput, transcriptPath);
+  if (sessionId) {
+    writeSessionCache(sessionId, {
+      status: "pending",
+      agent_id: agentId,
+      workspace_key: workspaceKey,
+      additional_context: buildBootstrapPendingContext(agentId),
+    });
+  }
+  process.stdout.write(nativeOutput(""));
+}
+
+function handleBeforeSubmitPrompt(hookInput) {
+  const transcriptPath =
+    hookInput.transcript_path ||
+    (hookInput.hookSpecificInput || {}).transcript_path;
+  const sessionId = extractSessionId(hookInput, transcriptPath);
+  const workspaceKey = workspaceKeyFromHookInput(hookInput, transcriptPath);
+  const cache = selectSessionCache(sessionId, workspaceKey);
+  if (cache && cache.status === "pending") {
+    process.stdout.write(beforeSubmitOutput(
+      false,
+      "Meko is still creating this session's conversation. Please retry in a moment so the agent starts with Meko context.",
+    ));
+    return;
+  }
+  process.stdout.write(beforeSubmitOutput(true));
+}
+
 async function handleSessionStart(hookInput) {
   const transcriptPath =
     hookInput.transcript_path ||
     (hookInput.hookSpecificInput || {}).transcript_path;
 
-  const sessionId = transcriptPath
-    ? path.basename(transcriptPath, ".jsonl")
-    : null;
+  const sessionId = extractSessionId(hookInput, transcriptPath);
 
   const source = hookInput.source || "";
-  const derivedAgentId = resolveSessionAgentId(transcriptPath);
+  const derivedAgentId = resolveSessionAgentId(transcriptPath, hookInput);
+  const workspaceKey = workspaceKeyFromHookInput(hookInput, transcriptPath);
 
   // Check if watermark already exists (same session ID re-fires SessionStart, e.g. /clear, /compact)
   if (sessionId) {
@@ -753,16 +960,20 @@ async function handleSessionStart(hookInput) {
       const cached = (existing.agent_id || "").trim();
       const resumedAgentId = cached && cached !== "agent" ? cached : derivedAgentId;
       // Skip preload on resume (we don't know what's already in context).
-      process.stdout.write(
-        hookOutput(
-          buildSessionStartContext(
-            existing.conversation_id,
-            sessionId,
-            resumedAgentId,
-            null,
-          ),
-        ),
+      const context = buildSessionStartContext(
+        existing.conversation_id,
+        sessionId,
+        resumedAgentId,
+        null,
       );
+      writeSessionCache(sessionId, {
+        status: "ready",
+        conversation_id: existing.conversation_id,
+        agent_id: resumedAgentId,
+        workspace_key: workspaceKey,
+        additional_context: context,
+      });
+      process.stdout.write(hookOutput(context));
       return;
     }
   }
@@ -788,17 +999,21 @@ async function handleSessionStart(hookInput) {
         priorAgentId && priorAgentId !== "agent" ? priorAgentId : agentId;
       writeWatermark(wmPath, prior.conversation_id, currentLineCount, resumedAgentId);
       process.stderr.write(`[meko-capture] Session ${sessionId}: resuming conversation ${prior.conversation_id} from ${prior.sessionId}, skipping ${currentLineCount} copied lines\n`);
-      process.stdout.write(
-        hookOutput(
-          buildSessionStartContext(
-            prior.conversation_id,
-            sessionId,
-            resumedAgentId,
-            null,
-            { resumed: true },
-          ),
-        ),
+      const context = buildSessionStartContext(
+        prior.conversation_id,
+        sessionId,
+        resumedAgentId,
+        null,
+        { resumed: true },
       );
+      writeSessionCache(sessionId, {
+        status: "ready",
+        conversation_id: prior.conversation_id,
+        agent_id: resumedAgentId,
+        workspace_key: workspaceKey,
+        additional_context: context,
+      });
+      process.stdout.write(hookOutput(context));
       return;
     }
     process.stderr.write(`[meko-capture] Session ${sessionId}: source=resume but no prior project watermark found; creating new conversation\n`);
@@ -813,13 +1028,33 @@ async function handleSessionStart(hookInput) {
     convId = await createConversation(sessionId || "unknown", agentId, transcriptMetadata);
   } catch (err) {
     process.stderr.write(`[meko-capture] SessionStart: MCP unavailable (${err.message}). Falling back to agent-driven setup.\n`);
-    process.stdout.write(hookOutput(buildSessionStartFallbackContext(agentId)));
+    const context = buildSessionStartFallbackContext(agentId);
+    if (sessionId) {
+      writeSessionCache(sessionId, {
+        status: "error",
+        agent_id: agentId,
+        workspace_key: workspaceKey,
+        error: err && err.message ? String(err.message).slice(0, 240) : "MCP unavailable",
+        additional_context: context,
+      });
+    }
+    process.stdout.write(hookOutput(context));
     return;
   }
 
   if (!convId) {
     process.stderr.write("[meko-capture] SessionStart: conversation_create returned no ID.\n");
-    process.stdout.write(hookOutput(buildSessionStartFallbackContext(agentId)));
+    const context = buildSessionStartFallbackContext(agentId);
+    if (sessionId) {
+      writeSessionCache(sessionId, {
+        status: "error",
+        agent_id: agentId,
+        workspace_key: workspaceKey,
+        error: "conversation_create returned no ID",
+        additional_context: context,
+      });
+    }
+    process.stdout.write(hookOutput(context));
     return;
   }
 
@@ -845,19 +1080,25 @@ async function handleSessionStart(hookInput) {
     );
   }
 
-  process.stdout.write(
-    hookOutput(
-      buildSessionStartContext(convId, sessionId, agentId, memories),
-    ),
-  );
+  const context = buildSessionStartContext(convId, sessionId, agentId, memories);
+  if (sessionId) {
+    writeSessionCache(sessionId, {
+      status: "ready",
+      conversation_id: convId,
+      agent_id: agentId,
+      workspace_key: workspaceKey,
+      additional_context: context,
+    });
+  }
+  process.stdout.write(hookOutput(context));
 }
 
 // --- Main ---
 
 async function main() {
   const hookType = process.argv[2];
-  if (!hookType || !["session-start", "pre-compact", "session-end", "checkpoint"].includes(hookType)) {
-    process.stderr.write("Usage: capture.js <session-start|pre-compact|session-end|checkpoint>\n");
+  if (!hookType || !["session-start", "session-pending", "before-submit-prompt", "pre-compact", "session-end", "checkpoint"].includes(hookType)) {
+    process.stderr.write("Usage: capture.js <session-start|session-pending|before-submit-prompt|pre-compact|session-end|checkpoint>\n");
     process.exit(1);
   }
 
@@ -878,6 +1119,16 @@ async function main() {
     return;
   }
 
+  if (hookType === "session-pending") {
+    handleSessionPending(hookInput);
+    return;
+  }
+
+  if (hookType === "before-submit-prompt") {
+    handleBeforeSubmitPrompt(hookInput);
+    return;
+  }
+
   // PreCompact / SessionEnd: capture transcript exchanges
   const transcriptPath =
     hookInput.transcript_path ||

package/assets/scripts/package-desktop-skill.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Package meko-mcp-tools-desktop as a .skill file for Claude Desktop distribution.
+# Usage: bash scripts/package-desktop-skill.sh
+# Output: meko-mcp-tools-desktop.skill (ZIP archive)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILLS_ROOT="$SCRIPT_DIR/../skills"
+SKILL_NAME="meko-mcp-tools-desktop"
+OUTPUT="$SCRIPT_DIR/../$SKILL_NAME.skill"
+
+if [ ! -d "$SKILLS_ROOT/$SKILL_NAME" ]; then
+    echo "Error: Skill directory not found at $SKILLS_ROOT/$SKILL_NAME" >&2
+    exit 1
+fi
+
+if [ ! -f "$SKILLS_ROOT/$SKILL_NAME/SKILL.md" ]; then
+    echo "Error: SKILL.md not found in $SKILLS_ROOT/$SKILL_NAME/" >&2
+    exit 1
+fi
+
+# Remove previous build if it exists
+rm -f "$OUTPUT"
+
+# Package skill + references (exclude OS artifacts and desktop README)
+cd "$SKILLS_ROOT"
+zip -r "$OUTPUT" \
+    "$SKILL_NAME/SKILL.md" \
+    "$SKILL_NAME/references/" \
+    -x "*.DS_Store" "*__pycache__*"
+
+echo "Created $OUTPUT ($(du -h "$OUTPUT" | cut -f1))"
+echo ""
+echo "Contents:"
+unzip -l "$OUTPUT" | grep -E "^\s+[0-9]" | grep -v "files$"

package/assets/skills/meko-mcp-tools/references/tools-overview.md

@@ -15,7 +15,7 @@ Before starting a session, verify that the Meko MCP tools are working:
 
 1. `memory_search(scope="read", query="test", agent_id="<your-session-agent-id>", conversation_id="<session-conversation-id>")` — Confirms memory subsystem is up. Use the `agent_id` and `conversation_id` from the SessionStart `additionalContext`. May fail with "connection already closed" — see `tools-troubleshooting.md`.
 2. `datapack_list(scope="read")` — Confirms Meko API connectivity
-3. `db_summarize_database(scope="read")` — *Optional, paid-tier only.* On free-tier datapacks this returns `{"error": "not_available"}`. The old "use this for `agent_id` discovery" protocol is retired — `agent_id` is a constant.
+3. `db_summarize_database(scope="read")` — *Optional, paid-tier only.* On free-tier datapacks this returns `{"error": "not_available"}`. The old "use this for `agent_id` discovery" protocol is retired — use the session-injected `agent_id` for project-scoped calls, or `meko_agent` for the common bucket.
 
 ## Decision tree: which tool do I need?