mindgraph-mcp 0.14.9 → 0.16.0

package/dist/index.js

@@ -28,6 +28,38 @@ var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 var import_types = require("@modelcontextprotocol/sdk/types.js");
 var import_mindgraph2 = require("mindgraph");
 
+// src/hook-env.ts
+var import_node_crypto = __toESM(require("crypto"));
+var import_node_fs = __toESM(require("fs"));
+var import_node_os = __toESM(require("os"));
+var import_node_path = __toESM(require("path"));
+function stableAgentId() {
+  let user = "user";
+  try {
+    user = import_node_os.default.userInfo().username || "user";
+  } catch {
+  }
+  const digest = import_node_crypto.default.createHash("sha256").update(`${user}@${import_node_os.default.hostname()}`).digest("hex").slice(0, 12);
+  return `u-${digest}`;
+}
+function hookEnvPath(dir) {
+  return import_node_path.default.join(dir || import_node_path.default.join(import_node_os.default.homedir(), ".mindgraph"), "hooks.json");
+}
+function loadHookEnv(dir) {
+  try {
+    const raw = import_node_fs.default.readFileSync(hookEnvPath(dir), "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : void 0,
+      apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0,
+      agentId: typeof parsed.agentId === "string" ? parsed.agentId : void 0,
+      orgId: typeof parsed.orgId === "string" ? parsed.orgId : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+
 // src/error-detail.ts
 var import_mindgraph = require("mindgraph");
 function errorDetail(e) {
@@ -37,14 +69,31 @@ function errorDetail(e) {
   }
   return e instanceof Error ? e.message : String(e);
 }
+var CONFLICT_STATE_KEYS = [
+  "current_version",
+  "current_epoch",
+  "lease_expires_at",
+  "lease_owner_agent_id"
+];
+function conflictState(e) {
+  if (!(e instanceof import_mindgraph.MindGraphError) || !e.body || typeof e.body !== "object") {
+    return {};
+  }
+  const body = e.body;
+  const lifted = {};
+  for (const key of CONFLICT_STATE_KEYS) {
+    if (body[key] !== void 0) lifted[key] = body[key];
+  }
+  return lifted;
+}
 
 // src/codegraph.ts
 var import_node_child_process = require("child_process");
-var import_node_fs = require("fs");
+var import_node_fs2 = require("fs");
 var import_promises = require("fs/promises");
-var import_node_os = require("os");
-var import_node_path = require("path");
-var import_node_crypto = require("crypto");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var import_node_crypto2 = require("crypto");
 function unavailabilityCaveats(reason, message) {
   const caveats = [message || "codegraph status failed"];
   if (reason === "absent") {
@@ -57,14 +106,14 @@ function unavailabilityCaveats(reason, message) {
 var DEFAULT_TIMEOUT_MS = 5e3;
 var DEFAULT_STATUS_TTL_MS = 6e4;
 var MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
-function normalizePath(path2) {
-  return path2.replaceAll("\\", "/").replace(/^\.\//, "");
+function normalizePath(path3) {
+  return path3.replaceAll("\\", "/").replace(/^\.\//, "");
 }
 function normalizeSignature(signature) {
   return signature.replace(/\s+/g, " ").trim();
 }
-function languageFromPath(path2) {
-  const extension = (0, import_node_path.extname)(path2).toLowerCase();
+function languageFromPath(path3) {
+  const extension = (0, import_node_path2.extname)(path3).toLowerCase();
   return {
     ".c": "c",
     ".cc": "cpp",
@@ -113,30 +162,30 @@ function normalizeRemote(remote) {
   }
 }
 function pathContains(root, candidate) {
-  const child = (0, import_node_path.relative)(root, candidate);
-  return child === "" || child !== ".." && !child.startsWith(`..${import_node_path.sep}`) && !(0, import_node_path.isAbsolute)(child);
+  const child = (0, import_node_path2.relative)(root, candidate);
+  return child === "" || child !== ".." && !child.startsWith(`..${import_node_path2.sep}`) && !(0, import_node_path2.isAbsolute)(child);
 }
 function nearestExistingDirectory(candidate) {
-  let current = (0, import_node_path.resolve)(candidate);
+  let current = (0, import_node_path2.resolve)(candidate);
   for (; ; ) {
-    if ((0, import_node_fs.existsSync)(current)) {
+    if ((0, import_node_fs2.existsSync)(current)) {
       try {
-        return (0, import_node_fs.statSync)(current).isDirectory() ? current : (0, import_node_path.dirname)(current);
+        return (0, import_node_fs2.statSync)(current).isDirectory() ? current : (0, import_node_path2.dirname)(current);
       } catch {
       }
     }
-    const parent = (0, import_node_path.dirname)(current);
+    const parent = (0, import_node_path2.dirname)(current);
     if (parent === current) return current;
     current = parent;
   }
 }
 function findWorkspaceFile(start, explicit) {
-  if (explicit) return (0, import_node_path.resolve)(start, explicit);
-  let current = (0, import_node_path.resolve)(start);
+  if (explicit) return (0, import_node_path2.resolve)(start, explicit);
+  let current = (0, import_node_path2.resolve)(start);
   for (; ; ) {
-    const candidate = (0, import_node_path.join)(current, ".mindgraph", "workspace.json");
-    if ((0, import_node_fs.existsSync)(candidate)) return candidate;
-    const parent = (0, import_node_path.dirname)(current);
+    const candidate = (0, import_node_path2.join)(current, ".mindgraph", "workspace.json");
+    if ((0, import_node_fs2.existsSync)(candidate)) return candidate;
+    const parent = (0, import_node_path2.dirname)(current);
     if (parent === current) return void 0;
     current = parent;
   }
@@ -223,7 +272,7 @@ var CodegraphAdapter = class {
   async resolveRepository(repo, fallbackSpaceUid) {
     const configured = await this.resolveRepositories(fallbackSpaceUid);
     const selected = repo && configured.find((candidate) => candidate.repoId === repo) || repo && configured.find(
-      (candidate) => candidate.repoRoot === repo || (0, import_node_path.basename)(candidate.repoRoot) === repo
+      (candidate) => candidate.repoRoot === repo || (0, import_node_path2.basename)(candidate.repoRoot) === repo
     ) || (!repo ? [...configured].sort((a, b) => b.repoRoot.length - a.repoRoot.length).find((candidate) => pathContains(candidate.repoRoot, this.cwd)) : void 0) || (!repo && configured.length === 1 ? configured[0] : void 0);
     if (selected) {
       return !repo && this.env.MINDGRAPH_REPO_ID ? this.resolveRepositoryIdentity(
@@ -233,8 +282,8 @@ var CodegraphAdapter = class {
       ) : selected;
     }
     const requestedRoot = repo || this.env.MINDGRAPH_REPO_ROOT || this.cwd;
-    const requestedPath = await (0, import_promises.realpath)((0, import_node_path.resolve)(this.cwd, requestedRoot)).catch(
-      () => (0, import_node_path.resolve)(this.cwd, requestedRoot)
+    const requestedPath = await (0, import_promises.realpath)((0, import_node_path2.resolve)(this.cwd, requestedRoot)).catch(
+      () => (0, import_node_path2.resolve)(this.cwd, requestedRoot)
     );
     const repoRoot = await this.gitRoot(requestedPath) ?? requestedPath;
     return this.resolveRepositoryIdentity(
@@ -255,7 +304,7 @@ var CodegraphAdapter = class {
     );
   }
   async resolveRepositoryIdentity(root, explicitRepoId, spaceUid) {
-    const repoRoot = await (0, import_promises.realpath)(root).catch(() => (0, import_node_path.resolve)(root));
+    const repoRoot = await (0, import_promises.realpath)(root).catch(() => (0, import_node_path2.resolve)(root));
     const cacheKey = `${repoRoot}\0${explicitRepoId ?? ""}\0${spaceUid ?? ""}`;
     const cached = this.identityCache.get(cacheKey);
     if (cached) return cached;
@@ -285,20 +334,20 @@ var CodegraphAdapter = class {
       this.env
     ).catch(() => "");
     if (!rawCommonDir.trim()) {
-      return `local:${(0, import_node_path.basename)(repoRoot)}`;
+      return `local:${(0, import_node_path2.basename)(repoRoot)}`;
     }
-    const commonDir = (0, import_node_path.resolve)(repoRoot, rawCommonDir.trim());
-    const identityDir = (0, import_node_path.join)(commonDir, "mindgraph");
-    const identityFile = (0, import_node_path.join)(identityDir, "repository-id");
+    const commonDir = (0, import_node_path2.resolve)(repoRoot, rawCommonDir.trim());
+    const identityDir = (0, import_node_path2.join)(commonDir, "mindgraph");
+    const identityFile = (0, import_node_path2.join)(identityDir, "repository-id");
     try {
-      const existing = (0, import_node_fs.readFileSync)(identityFile, "utf8").trim();
+      const existing = (0, import_node_fs2.readFileSync)(identityFile, "utf8").trim();
       if (existing) return existing;
     } catch {
     }
-    (0, import_node_fs.mkdirSync)(identityDir, { recursive: true, mode: 448 });
-    const generated = (0, import_node_crypto.randomUUID)();
+    (0, import_node_fs2.mkdirSync)(identityDir, { recursive: true, mode: 448 });
+    const generated = (0, import_node_crypto2.randomUUID)();
     try {
-      (0, import_node_fs.writeFileSync)(identityFile, `${generated}
+      (0, import_node_fs2.writeFileSync)(identityFile, `${generated}
 `, {
         encoding: "utf8",
         flag: "wx",
@@ -307,7 +356,7 @@ var CodegraphAdapter = class {
       return generated;
     } catch (cause) {
       if (cause.code !== "EEXIST") throw cause;
-      const winner = (0, import_node_fs.readFileSync)(identityFile, "utf8").trim();
+      const winner = (0, import_node_fs2.readFileSync)(identityFile, "utf8").trim();
       if (!winner) throw new Error(`empty repository identity file: ${identityFile}`);
       return winner;
     }
@@ -320,7 +369,7 @@ var CodegraphAdapter = class {
       Math.min(this.timeoutMs, 2e3),
       this.env
     ).catch(() => "");
-    return raw.trim() ? (0, import_node_path.resolve)(start, raw.trim()) : void 0;
+    return raw.trim() ? (0, import_node_path2.resolve)(start, raw.trim()) : void 0;
   }
   async availability(repository) {
     const cached = this.statusCache.get(repository.repoRoot);
@@ -437,7 +486,7 @@ var CodegraphAdapter = class {
       return this.resolveRepository(ref.repo || defaultRepo, fallbackSpaceUid);
     }
     if (ref.path) {
-      const requested = (0, import_node_path.isAbsolute)(ref.path) ? (0, import_node_path.resolve)(ref.path) : (0, import_node_path.resolve)(this.cwd, ref.path);
+      const requested = (0, import_node_path2.isAbsolute)(ref.path) ? (0, import_node_path2.resolve)(ref.path) : (0, import_node_path2.resolve)(this.cwd, ref.path);
       const absolute = await (0, import_promises.realpath)(requested).catch(() => requested);
       const configured = await this.resolveRepositories(fallbackSpaceUid);
       const defining = [...configured].sort((a, b) => b.repoRoot.length - a.repoRoot.length).find((candidate) => pathContains(candidate.repoRoot, absolute));
@@ -514,19 +563,19 @@ var CodegraphAdapter = class {
   }
   configuredRepositories() {
     const configured = [];
-    if (this.workspaceFile && (0, import_node_fs.existsSync)(this.workspaceFile)) {
+    if (this.workspaceFile && (0, import_node_fs2.existsSync)(this.workspaceFile)) {
       try {
         const parsed = JSON.parse(
-          (0, import_node_fs.readFileSync)(this.workspaceFile, "utf8")
+          (0, import_node_fs2.readFileSync)(this.workspaceFile, "utf8")
         );
         if (parsed.v === 1 && Array.isArray(parsed.repositories)) {
-          const configDirectory = (0, import_node_path.dirname)(this.workspaceFile);
-          const base = (0, import_node_path.basename)(configDirectory) === ".mindgraph" ? (0, import_node_path.dirname)(configDirectory) : configDirectory;
+          const configDirectory = (0, import_node_path2.dirname)(this.workspaceFile);
+          const base = (0, import_node_path2.basename)(configDirectory) === ".mindgraph" ? (0, import_node_path2.dirname)(configDirectory) : configDirectory;
           for (const repository of parsed.repositories) {
             if (!repository || typeof repository.root !== "string") continue;
             configured.push({
               repoId: typeof repository.repo_id === "string" ? repository.repo_id : void 0,
-              repoRoot: (0, import_node_path.resolve)(base, repository.root),
+              repoRoot: (0, import_node_path2.resolve)(base, repository.root),
               spaceUid: typeof repository.space_uid === "string" ? repository.space_uid : void 0
             });
           }
@@ -541,7 +590,7 @@ var CodegraphAdapter = class {
         for (const [repoId, config] of Object.entries(parsed)) {
           configured.push({
             repoId,
-            repoRoot: (0, import_node_path.resolve)(
+            repoRoot: (0, import_node_path2.resolve)(
               this.cwd,
               typeof config === "string" ? config : config.root
             ),
@@ -569,9 +618,9 @@ var CodegraphAdapter = class {
       const hits = await this.runJson(args);
       let candidates = hits.map(asNode).map(toCandidate).filter((item) => item !== null);
       if (ref.path) {
-        const absolutePath = (0, import_node_path.isAbsolute)(ref.path) ? await (0, import_promises.realpath)(ref.path).catch(() => ref.path) : void 0;
+        const absolutePath = (0, import_node_path2.isAbsolute)(ref.path) ? await (0, import_promises.realpath)(ref.path).catch(() => ref.path) : void 0;
         const wanted = normalizePath(
-          absolutePath ? (0, import_node_path.relative)(repository.repoRoot, absolutePath) : ref.path
+          absolutePath ? (0, import_node_path2.relative)(repository.repoRoot, absolutePath) : ref.path
         );
         candidates = candidates.filter((candidate) => candidate.path === wanted);
       }
@@ -672,7 +721,7 @@ var CodegraphAdapter = class {
     const candidates = [
       this.env.MINDGRAPH_CODEGRAPH_BIN,
       "codegraph",
-      (0, import_node_path.resolve)((0, import_node_os.homedir)(), ".local", "bin", "codegraph")
+      (0, import_node_path2.resolve)((0, import_node_os2.homedir)(), ".local", "bin", "codegraph")
     ].filter((candidate, index, all) => {
       return Boolean(candidate) && all.indexOf(candidate) === index;
     });
@@ -1219,9 +1268,9 @@ function primaryUids(value) {
 }
 
 // src/sync-tool.ts
-var import_node_crypto2 = __toESM(require("crypto"));
-var import_node_fs2 = __toESM(require("fs"));
-var import_node_path2 = __toESM(require("path"));
+var import_node_crypto3 = __toESM(require("crypto"));
+var import_node_fs3 = __toESM(require("fs"));
+var import_node_path3 = __toESM(require("path"));
 var ok2 = (data) => ({
   content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
 });
@@ -1298,25 +1347,25 @@ var SYNC_TOOL = {
   }
 };
 function safePath(root, candidate) {
-  const absolute = import_node_path2.default.resolve(root, candidate);
-  const relative2 = import_node_path2.default.relative(root, absolute);
-  if (relative2.startsWith("..") || import_node_path2.default.isAbsolute(relative2)) {
+  const absolute = import_node_path3.default.resolve(root, candidate);
+  const relative2 = import_node_path3.default.relative(root, absolute);
+  if (relative2.startsWith("..") || import_node_path3.default.isAbsolute(relative2)) {
     throw new Error(`path escapes repository root: ${candidate}`);
   }
   return absolute;
 }
 function markdownFiles(target) {
-  if (!import_node_fs2.default.existsSync(target)) return [];
-  const stat = import_node_fs2.default.statSync(target);
+  if (!import_node_fs3.default.existsSync(target)) return [];
+  const stat = import_node_fs3.default.statSync(target);
   if (stat.isFile()) return target.endsWith(".md") ? [target] : [];
   if (!stat.isDirectory()) return [];
-  return import_node_fs2.default.readdirSync(target, { withFileTypes: true }).flatMap((entry) => markdownFiles(import_node_path2.default.join(target, entry.name)));
+  return import_node_fs3.default.readdirSync(target, { withFileTypes: true }).flatMap((entry) => markdownFiles(import_node_path3.default.join(target, entry.name)));
 }
 function fileDescriptor(root, absolute) {
-  const content = import_node_fs2.default.readFileSync(absolute, "utf8");
+  const content = import_node_fs3.default.readFileSync(absolute, "utf8");
   return {
-    logical_path: import_node_path2.default.relative(root, absolute).split(import_node_path2.default.sep).join("/"),
-    content_hash: import_node_crypto2.default.createHash("sha256").update(content).digest("hex"),
+    logical_path: import_node_path3.default.relative(root, absolute).split(import_node_path3.default.sep).join("/"),
+    content_hash: import_node_crypto3.default.createHash("sha256").update(content).digest("hex"),
     bytes: Buffer.byteLength(content),
     content
   };
@@ -1381,7 +1430,7 @@ async function handleSyncTool(client2, args) {
     }
     if (action === "status" && request.logical_path && request.file_present !== false) {
       const absolute = safePath(root, String(request.logical_path));
-      request.file_present = import_node_fs2.default.existsSync(absolute);
+      request.file_present = import_node_fs3.default.existsSync(absolute);
       if (request.file_present && !request.content_hash) {
         request.content_hash = fileDescriptor(root, absolute).content_hash;
       }
@@ -1425,6 +1474,355 @@ async function scanRepository(remote, repository, requested, provider, agentId)
   };
 }
 
+// src/render.ts
+var LABEL_MAX = 200;
+var SUMMARY_MAX = 400;
+var QUOTE_MAX = 180;
+var ARTICLE_MAX = 6e3;
+var CHUNK_MAX = 6e3;
+var RELATIONSHIP_MAX = 40;
+var RENDER_CHAR_BUDGET = 24e3;
+var CURATION_EDGE_TYPES = /* @__PURE__ */ new Set(["POSSIBLE_DUPLICATE", "PossibleDuplicate"]);
+var INFRA_NODE_TYPES = /* @__PURE__ */ new Set(["Chunk", "Document", "Article"]);
+function obj(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function str(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function clip(value, max, state) {
+  const text = str(value);
+  if (!text) return void 0;
+  if (text.length <= max) return text;
+  state.bounded = true;
+  return `${text.slice(0, max - 1)}\u2026`;
+}
+function isNodeShaped(value) {
+  const node = obj(value);
+  return Boolean(node && str(node.uid) && (str(node.label) || str(node.node_type)));
+}
+function unwrapSearchResult(value) {
+  if (isNodeShaped(value)) return value;
+  const wrapper = obj(value);
+  const inner = obj(wrapper?.node);
+  if (inner && isNodeShaped(inner)) {
+    const score = num(wrapper.score);
+    return score !== void 0 ? { ...inner, retrieval_score: score } : inner;
+  }
+  return void 0;
+}
+function statusTag(node) {
+  const tags = [];
+  if (node.superseded === true) {
+    tags.push(
+      node.superseded_by ? `SUPERSEDED by ${str(node.superseded_by)}` : "SUPERSEDED"
+    );
+  }
+  const truth = str(node.truth_status) ?? str(obj(node.props)?.truth_status);
+  if (truth && truth !== "accepted") tags.push(`truth: ${truth}`);
+  if (node.currently_valid === false) tags.push("OUTSIDE ITS VALIDITY WINDOW");
+  if (node.valid_at_time === false) tags.push("NOT VALID AT THE REQUESTED TIME");
+  return tags.length > 0 ? ` [${tags.join("; ")}]` : "";
+}
+function firstQuote(node, state) {
+  const chunks = Array.isArray(node.source_chunks) ? node.source_chunks : [];
+  for (const raw of chunks) {
+    const chunk = obj(raw);
+    const quote = str(chunk?.quote) ?? str(obj(chunk?.anchor)?.exact);
+    if (quote) return clip(quote, QUOTE_MAX, state);
+  }
+  return void 0;
+}
+function sourceTag(node) {
+  const docs = Array.isArray(node.source_documents) ? node.source_documents : [];
+  const first = obj(docs[0]);
+  const title = str(first?.title);
+  if (!title) return void 0;
+  const extra = docs.length > 1 ? ` (+${docs.length - 1} more)` : "";
+  return `from: ${title}${extra}`;
+}
+function layer7Fields(node, state) {
+  const fields = obj(obj(node.props)?.fields);
+  if (!fields) return void 0;
+  const pairs = Object.entries(fields).filter(([, value]) => value !== null && value !== void 0 && value !== "").map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(", ") : String(value)}`);
+  if (pairs.length === 0) return void 0;
+  return clip(pairs.join("; "), SUMMARY_MAX, state);
+}
+function nodeSummaryText(node, state) {
+  const props = obj(node.props);
+  return clip(node.summary, SUMMARY_MAX, state) ?? clip(props?.content, SUMMARY_MAX, state) ?? clip(props?.description, SUMMARY_MAX, state) ?? clip(props?.definition, SUMMARY_MAX, state);
+}
+function nodeLines(node, state) {
+  const label = clip(node.label, LABEL_MAX, state) || "(unlabeled)";
+  const type = str(node.node_type) || "Node";
+  const confidence = num(node.confidence);
+  const score = num(node.retrieval_score);
+  const parenthetical = [
+    type,
+    confidence !== void 0 ? `confidence ${confidence}` : void 0,
+    score !== void 0 ? `score ${Math.round(score * 100) / 100}` : void 0
+  ].filter(Boolean).join(", ");
+  const head = `- **${label}** [${str(node.uid) || "?"}] (${parenthetical})${statusTag(node)}`;
+  const summary = nodeSummaryText(node, state);
+  const lines = [summary && summary !== label ? `${head}: ${summary}` : head];
+  const fields = layer7Fields(node, state);
+  if (fields) lines.push(`  - fields: ${fields}`);
+  const quote = firstQuote(node, state);
+  if (quote) lines.push(`  - source quote: "${quote}"`);
+  const source = sourceTag(node);
+  if (source) lines.push(`  - ${source}`);
+  const believers = Array.isArray(node.believed_by) ? node.believed_by : [];
+  if (believers.length > 0) {
+    const rendered = believers.slice(0, 3).map((raw) => {
+      const believer = obj(raw);
+      const conf = num(believer?.confidence);
+      return `${str(believer?.agent_label) || "?"}${conf !== void 0 ? ` (${conf})` : ""}`;
+    }).join(", ");
+    lines.push(`  - believed by: ${rendered}`);
+  }
+  return lines.join("\n");
+}
+function groupedNodeSections(nodes, state, headingPrefix = "") {
+  const groups = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const type = str(node.node_type) || "Node";
+    const group = groups.get(type) ?? [];
+    group.push(node);
+    groups.set(type, group);
+  }
+  const sections = [];
+  let first = true;
+  for (const [type, group] of groups) {
+    sections.push({
+      heading: `${first ? headingPrefix : ""}### ${type}`,
+      items: group.map((node) => nodeLines(node, state))
+    });
+    first = false;
+  }
+  return sections;
+}
+function relationshipItems(edges, labelByUid, state) {
+  const lines = [];
+  for (const raw of edges) {
+    const edge = obj(raw);
+    if (!edge) continue;
+    const type = str(edge.edge_type) || "?";
+    const from = str(edge.from_uid);
+    const to = str(edge.to_uid);
+    if (CURATION_EDGE_TYPES.has(type)) continue;
+    if (!from || !to || from === to) continue;
+    const fromLabel = labelByUid.get(from);
+    const toLabel = labelByUid.get(to);
+    if (!fromLabel || !toLabel) continue;
+    lines.push(`- ${fromLabel} \u2014${type}\u2192 ${toLabel}`);
+  }
+  if (lines.length > RELATIONSHIP_MAX) {
+    state.bounded = true;
+    const extra = lines.length - RELATIONSHIP_MAX;
+    return [...lines.slice(0, RELATIONSHIP_MAX), `- (+${extra} more relationships)`];
+  }
+  return lines;
+}
+function assemble(header, sections, state) {
+  const lines = [header];
+  let used = header.length;
+  for (const section of sections) {
+    if (section.items.length === 0 && !section.heading) continue;
+    const headingCost = section.heading.length + 2;
+    if (used + headingCost > RENDER_CHAR_BUDGET) {
+      state.bounded = true;
+      continue;
+    }
+    let sectionUsed = 0;
+    const kept = [];
+    let dropped = 0;
+    for (const item of section.items) {
+      if (used + headingCost + sectionUsed + item.length + 1 > RENDER_CHAR_BUDGET) {
+        dropped += 1;
+        continue;
+      }
+      kept.push(item);
+      sectionUsed += item.length + 1;
+    }
+    if (kept.length === 0 && section.items.length > 0) {
+      state.bounded = true;
+      continue;
+    }
+    if (dropped > 0) {
+      state.bounded = true;
+      const marker = `(+${dropped} more not shown)`;
+      kept.push(marker);
+      sectionUsed += marker.length + 1;
+    }
+    lines.push(
+      section.items.length === 0 ? section.heading : `${section.heading}
+${kept.join("\n")}`
+    );
+    used += headingCost + sectionUsed;
+  }
+  if (state.bounded) {
+    lines.push(
+      '\u2026[rendered context bounded \u2014 fetch full node content by uid, or pass format: "json" for the raw response]'
+    );
+  }
+  return lines.join("\n\n");
+}
+function policySections(payload, state) {
+  const policies = Array.isArray(payload.applicable_policies) ? payload.applicable_policies : [];
+  if (policies.length === 0) return [];
+  const items = policies.map((raw) => obj(raw)).filter((policy) => Boolean(policy)).map((policy) => {
+    const rules = Array.isArray(policy.prose_rules) ? policy.prose_rules.map(String).join("; ") : policy.prose_rules;
+    return `- ${str(policy.name) || "(unnamed policy)"}: ${clip(rules, SUMMARY_MAX, state) || "(structured rules apply)"}`;
+  });
+  return [{ heading: "## Applicable policies", items }];
+}
+function hiddenSections(payload) {
+  const hidden = payload.hidden_item_count;
+  if (hidden === void 0 || hidden === null) return [];
+  return [
+    {
+      heading: `Note: ${hidden} item(s) were hidden by access scoping.`,
+      items: []
+    }
+  ];
+}
+function renderContext(response) {
+  const payload = obj(response);
+  if (!payload) return void 0;
+  const graph = obj(payload.graph);
+  const rawNodes = Array.isArray(graph?.nodes) ? graph.nodes : [];
+  const shaped = rawNodes.filter(isNodeShaped);
+  const nodes = shaped.filter((node) => !INFRA_NODE_TYPES.has(str(node.node_type) || ""));
+  const infraOnly = shaped.length - nodes.length;
+  const articles = Array.isArray(payload.articles) ? payload.articles : [];
+  const chunks = Array.isArray(payload.chunks) ? payload.chunks : [];
+  const state = { bounded: false };
+  const sections = [];
+  if (articles.length > 0) {
+    sections.push({
+      heading: "## Knowledge articles",
+      items: articles.map((raw) => obj(raw)).filter((article) => Boolean(article)).map(
+        (article) => `### ${str(article.label) || "(untitled)"} [${str(article.uid) || "?"}]
+${clip(article.content, ARTICLE_MAX, state) || ""}`
+      )
+    });
+  }
+  if (nodes.length > 0) {
+    sections.push(...groupedNodeSections(nodes, state, "## Knowledge graph\n\n"));
+    const labelByUid = /* @__PURE__ */ new Map();
+    for (const node of nodes) labelByUid.set(str(node.uid), str(node.label) || "?");
+    const relationships = relationshipItems(
+      Array.isArray(graph?.edges) ? graph.edges : [],
+      labelByUid,
+      state
+    );
+    if (relationships.length > 0) {
+      sections.push({ heading: "## Relationships", items: relationships });
+    }
+  } else if (infraOnly > 0) {
+    sections.push({
+      heading: `Note: ${infraOnly} document/chunk node(s) matched \u2014 use action "document_index" or include_chunks for their content.`,
+      items: []
+    });
+  }
+  if (chunks.length > 0) {
+    sections.push({
+      heading: "## Source excerpts",
+      items: chunks.map((raw) => obj(raw)).filter((chunk) => Boolean(chunk)).map(
+        (chunk) => `- [${str(chunk.chunk_uid) || "?"}] from "${str(chunk.document_title) || "unknown document"}": "${clip(chunk.content, CHUNK_MAX, state) || ""}"`
+      )
+    });
+  }
+  sections.push(...policySections(payload, state));
+  sections.push(...hiddenSections(payload));
+  if (sections.length === 0) {
+    return "No results found for this search.";
+  }
+  if (nodes.length === 0 && articles.length === 0 && chunks.length === 0) {
+    return assemble("# Retrieved context\n\nNo graph results matched this search.", sections, state);
+  }
+  return assemble("# Retrieved context", sections, state);
+}
+function renderNodeList(response, title, limit) {
+  let candidates = [];
+  if (Array.isArray(response)) {
+    candidates = response;
+  } else {
+    const payload = obj(response);
+    if (!payload) return void 0;
+    for (const key of ["nodes", "results", "items", "goals", "questions", "claims", "preferences", "documents"]) {
+      const candidate = payload[key];
+      if (Array.isArray(candidate) && candidate.some((entry) => unwrapSearchResult(entry))) {
+        candidates = candidate;
+        break;
+      }
+    }
+  }
+  let nodes = candidates.map(unwrapSearchResult).filter((node) => Boolean(node));
+  if (nodes.length === 0) return void 0;
+  const total = nodes.length;
+  const state = { bounded: false };
+  if (limit !== void 0 && limit > 0 && nodes.length > limit) {
+    nodes = nodes.slice(0, limit);
+    state.bounded = true;
+  }
+  const sections = groupedNodeSections(nodes, state);
+  const shown = nodes.length;
+  return assemble(
+    `# ${title} (${shown === total ? total : `${shown} of ${total}`})`,
+    sections,
+    state
+  );
+}
+function renderTraversal(response) {
+  const payload = obj(response);
+  if (!payload) return void 0;
+  const container = obj(payload.graph) ?? payload;
+  const rawNodes = Array.isArray(container.nodes) ? container.nodes : [];
+  const nodes = rawNodes.filter(isNodeShaped);
+  const paths = Array.isArray(payload.paths) ? payload.paths : [];
+  if (nodes.length === 0 && paths.length === 0) return void 0;
+  const state = { bounded: false };
+  const sections = [];
+  const labelByUid = /* @__PURE__ */ new Map();
+  for (const node of nodes) labelByUid.set(str(node.uid), str(node.label) || "?");
+  if (paths.length > 0) {
+    const items = paths.map((raw) => obj(raw)).filter((path3) => Boolean(path3)).map((path3, index) => {
+      const uids = Array.isArray(path3.node_uids) ? path3.node_uids.map(String) : [];
+      const labels = Array.isArray(path3.labels) ? path3.labels.map(String) : Array.isArray(path3.nodes) ? path3.nodes.map((hop) => {
+        const hopNode = obj(hop);
+        return str(hopNode?.label) || labelByUid.get(str(hopNode?.uid) || "") || str(hop) || "?";
+      }) : [];
+      const route = labels.length > 0 ? labels.join(" \u2192 ") : uids.join(" \u2192 ") || "(path)";
+      const cost = num(path3.cost) ?? num(path3.path_cost);
+      const confidence = num(path3.path_confidence);
+      const meta = [
+        cost !== void 0 ? `cost ${cost}` : void 0,
+        confidence !== void 0 ? `confidence ${confidence}` : void 0
+      ].filter(Boolean);
+      const head = `${index + 1}. ${route}${meta.length > 0 ? ` (${meta.join(", ")})` : ""}`;
+      return labels.length > 0 && uids.length > 0 ? `${head}
+   uids: ${uids.join(" \u2192 ")}` : head;
+    });
+    sections.push({ heading: "## Paths", items });
+  }
+  if (nodes.length > 0) {
+    sections.push(...groupedNodeSections(nodes, state, "## Nodes\n\n"));
+    const relationships = relationshipItems(
+      Array.isArray(container.edges) ? container.edges : [],
+      labelByUid,
+      state
+    );
+    if (relationships.length > 0) {
+      sections.push({ heading: "## Relationships", items: relationships });
+    }
+  }
+  return assemble("# Graph traversal", sections, state);
+}
+
 // src/tools.ts
 var TOOLS = [
   {
@@ -1999,10 +2397,16 @@ var TOOLS = [
             "neighborhood",
             "path",
             "subgraph",
+            "top_k_paths",
             "document_index"
           ],
           description: "Retrieval or traversal strategy"
         },
+        format: {
+          type: "string",
+          enum: ["text", "json"],
+          description: "Output format (default 'text'): a compact rendered context block \u2014 labels, uids, summaries, status tags, relationships. Pass 'json' for the raw server response (full props, source-chunk offsets, retrieval metadata)."
+        },
         query: {
           type: "string",
           description: "Search query \u2014 for 'text'/'context': 1-3 BM25 keywords, drop filler words. For 'semantic'/'hybrid': natural language is OK since it uses vector similarity."
@@ -2062,7 +2466,35 @@ var TOOLS = [
         },
         include_documents: {
           type: "boolean",
-          description: "Include ingested documents and wiki articles in context results. The coding profile defaults these OFF so engineering questions aren't answered from unrelated ingested content; pass true when the question is about a document, spec, or article."
+          description: "Include ingested documents and wiki articles in context results. The coding profile defaults these OFF so engineering questions aren't answered from unrelated ingested content; pass true when the question is about a document, spec, or article \u2014 or false in any profile to drop the article leg."
+        },
+        article_limit: {
+          type: "number",
+          description: "Max wiki articles in context results (default 3; 0 disables the article leg). An explicit value overrides profile defaults, including the coding profile's articles-off default."
+        },
+        valid_at: {
+          type: "string",
+          description: "ISO-8601 date (e.g. '2021-06') for context: nodes with validity windows are annotated as of this date instead of today"
+        },
+        created_after: {
+          type: "number",
+          description: "Unix seconds \u2014 'recent' action: only nodes ingested after this time"
+        },
+        created_before: {
+          type: "number",
+          description: "Unix seconds \u2014 'recent' action: only nodes ingested before this time"
+        },
+        explain: {
+          type: "boolean",
+          description: "hybrid action: include per-leg retrieval scoring (legs) in the response"
+        },
+        k: {
+          type: "number",
+          description: "top_k_paths action: number of cheapest paths (default 3, cap 25)"
+        },
+        max_cost: {
+          type: "number",
+          description: "top_k_paths action: optional cost ceiling for returned paths"
         },
         include_chunks: {
           type: "boolean",
@@ -2441,6 +2873,18 @@ async function handleTool(client2, name, args) {
     ].includes(action);
     return attach ? await attachCodeRefsToToolResult(client2, result, args) : result;
   } catch (e) {
+    const lifted = conflictState(e);
+    if (Object.keys(lifted).length > 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: errorDetail(e), ...lifted })
+          }
+        ],
+        isError: true
+      };
+    }
     return err3(errorDetail(e));
   }
 }
@@ -2956,6 +3400,7 @@ async function handlePlan(client2, args) {
 async function handleRetrieve(client2, args) {
   const {
     action,
+    format,
     query,
     start_uid,
     end_uid,
@@ -2976,12 +3421,24 @@ async function handleRetrieve(client2, args) {
     graph_max_depth,
     confidence_min,
     salience_min,
+    article_limit,
+    valid_at,
+    created_after,
+    created_before,
+    explain,
+    k,
+    max_cost,
     agent_id
   } = args;
+  const rendered = (raw, render) => {
+    if (format === "json") return ok3(raw);
+    const text = render(raw);
+    return text !== void 0 ? { content: [{ type: "text", text }] } : ok3(raw);
+  };
   switch (action) {
     case "context":
       if (!query) return err3("query is required for context retrieval");
-      return ok3(
+      return rendered(
         await client2.retrieveContext({
           query,
           node_limit: limit,
@@ -2990,110 +3447,139 @@ async function handleRetrieve(client2, args) {
           chunk_limit: include_chunks ? limit ?? 5 : 0,
           // Scoped by default, never walled: the coding profile drops the
           // document/article leg (the "Bob Work" class of noise) unless the
-          // model opts in for a genuinely document-shaped question.
-          ...process.env.MINDGRAPH_PROFILE === "coding" && !include_documents ? { article_limit: 0 } : {},
+          // model opts in for a genuinely document-shaped question. Any
+          // profile can drop it with include_documents: false (previously a
+          // silent no-op outside coding). An EXPLICIT article_limit is at
+          // least as clear an opt-in as include_documents:true — it always
+          // wins over profile defaults (a coding-profile model reaching for
+          // the advertised knob must not get a silent no-op).
+          ...article_limit !== void 0 ? { article_limit } : include_documents === false || process.env.MINDGRAPH_PROFILE === "coding" && !include_documents ? { article_limit: 0 } : {},
+          valid_at,
           include_graph,
           graph_expansion_limit: graph_expansion_limit ?? 3,
           graph_max_depth: graph_max_depth ?? 2
-        })
+        }),
+        renderContext
       );
     case "text":
       if (!query) return err3("query is required for text search");
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "text",
           query,
           limit,
           node_types,
           layer,
+          explain,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, `Text search: ${query}`)
       );
     case "semantic":
       if (!query) return err3("query is required for semantic search");
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "semantic",
           query,
           k: limit,
           node_types,
           layer,
+          explain,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, `Semantic search: ${query}`)
       );
     case "hybrid":
       if (!query) return err3("query is required for hybrid search");
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "hybrid",
           query,
           k: limit,
           node_types,
           layer,
+          explain,
           agent_id
-        })
+        }),
+        // With explain, per-leg scoring must survive — raw JSON only.
+        explain ? () => void 0 : (raw) => renderNodeList(raw, `Hybrid search: ${query}`)
       );
-    // Structured queries
+    // Structured queries. These go through the generic /retrieve action
+    // dispatch rather than the SDK's no-argument convenience methods — the
+    // conveniences silently dropped `limit`/`offset` (the tool advertised
+    // them; five actions ignored them).
     case "active_goals":
-      return ok3(await client2.getGoals());
     case "open_questions":
-      return ok3(await client2.getOpenQuestions());
     case "weak_claims":
-      return ok3(await client2.getWeakClaims());
     case "pending_approvals":
-      return ok3(await client2.getPendingApprovals());
     case "unresolved_contradictions":
-      return ok3(await client2.getContradictions());
+      return rendered(
+        await client2.retrieve({
+          action,
+          limit,
+          offset,
+          agent_id
+        }),
+        (raw) => renderNodeList(raw, action.replace(/_/g, " "), limit)
+      );
     case "stale_derivations":
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "stale_derivations",
           limit,
           offset
-        })
+        }),
+        (raw) => renderNodeList(raw, "stale derivations", limit)
       );
     case "preferences":
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "preferences",
           ...query ? { query, k: limit } : {},
           limit,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, "Preferences", limit)
       );
     case "layer":
       if (!layer) return err3("layer is required for layer retrieval");
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "layer",
           layer,
           limit,
+          node_types,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, `Layer: ${layer}`, limit)
       );
     case "recent":
-      return ok3(
+      return rendered(
         await client2.retrieve({
           action: "recent",
           limit,
           node_types,
           confidence_min,
           salience_min,
+          created_after,
+          created_before,
           agent_id
-        })
+        }),
+        (raw) => renderNodeList(raw, "Recently ingested", limit)
       );
     // Document inventory
     case "document_index":
-      return ok3(
+      return rendered(
         await client2.getNodes({
           node_type: "Document",
           limit: limit ?? 100
-        })
+        }),
+        (raw) => renderNodeList(raw, "Ingested documents")
       );
     // Graph traversal
     case "chain":
       if (!start_uid) return err3("start_uid is required for chain traversal");
-      return ok3(
+      return rendered(
         await client2.traverse({
           action: "chain",
           start_uid,
@@ -3101,11 +3587,12 @@ async function handleRetrieve(client2, args) {
           exclude_edge_types,
           include_provenance,
           max_nodes
-        })
+        }),
+        renderTraversal
       );
     case "neighborhood":
       if (!start_uid) return err3("start_uid is required for neighborhood traversal");
-      return ok3(
+      return rendered(
         await client2.traverse({
           action: "neighborhood",
           start_uid,
@@ -3115,12 +3602,13 @@ async function handleRetrieve(client2, args) {
           exclude_edge_types,
           include_provenance,
           max_nodes
-        })
+        }),
+        renderTraversal
       );
     case "path":
       if (!start_uid) return err3("start_uid is required for path traversal");
       if (!end_uid) return err3("end_uid is required for path traversal");
-      return ok3(
+      return rendered(
         await client2.traverse({
           action: "path",
           start_uid,
@@ -3131,11 +3619,12 @@ async function handleRetrieve(client2, args) {
           exclude_edge_types,
           include_provenance,
           max_nodes
-        })
+        }),
+        renderTraversal
       );
     case "subgraph":
       if (!start_uid) return err3("start_uid is required for subgraph traversal");
-      return ok3(
+      return rendered(
         await client2.traverse({
           action: "subgraph",
           start_uid,
@@ -3145,7 +3634,24 @@ async function handleRetrieve(client2, args) {
           exclude_edge_types,
           include_provenance,
           max_nodes
-        })
+        }),
+        renderTraversal
+      );
+    case "top_k_paths":
+      if (!start_uid) return err3("start_uid is required for top_k_paths");
+      if (!end_uid) return err3("end_uid is required for top_k_paths");
+      return rendered(
+        await client2.traverse({
+          action: "top_k_paths",
+          start_uid,
+          end_uid,
+          k,
+          max_hops: max_depth,
+          max_cost,
+          edge_types,
+          exclude_edge_types
+        }),
+        renderTraversal
       );
     default:
       return err3(`Unknown retrieve action: ${action}`);
@@ -3876,7 +4382,7 @@ async function readGovernedResource(client2, uri, governanceConfig) {
 // src/index.ts
 var API_KEY = process.env.MINDGRAPH_API_KEY;
 var BASE_URL = process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud";
-var AGENT_ID = process.env.MINDGRAPH_AGENT_ID || "mcp";
+var AGENT_ID = process.env.MINDGRAPH_AGENT_ID || loadHookEnv().agentId || stableAgentId();
 var ORG_ID = process.env.MINDGRAPH_ORG_ID;
 var PROFILE = process.env.MINDGRAPH_PROFILE || "general";
 var HARNESS = process.env.MINDGRAPH_HARNESS || "generic";
@@ -3998,7 +4504,7 @@ if (PROFILE === "coding") {
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.14.9"
+    version: "0.16.0"
   },
   {
     capabilities: {
@@ -4212,7 +4718,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v0.7.1 running on stdio (${BASE_URL})`
+    `MindGraph MCP server v${"0.16.0"} running on stdio (${BASE_URL})`
   );
 }
 main().catch((error) => {