mindgraph-mcp 0.17.0 → 0.19.0

package/dist/index.js

@@ -94,6 +94,24 @@ var import_promises = require("fs/promises");
 var import_node_os2 = require("os");
 var import_node_path2 = require("path");
 var import_node_crypto2 = require("crypto");
+var UnknownRepositoryError = class extends Error {
+  constructor(repo) {
+    super(
+      `unknown repository "${repo}": not declared in .mindgraph/workspace.json, not the current repository, and no such path exists`
+    );
+    this.repo = repo;
+    this.name = "UnknownRepositoryError";
+  }
+  repo;
+};
+function invocationCwd(args) {
+  const context = args.invocation_context;
+  if (context && typeof context === "object" && !Array.isArray(context)) {
+    const cwd = context.cwd;
+    if (typeof cwd === "string" && cwd) return cwd;
+  }
+  return process.cwd();
+}
 function unavailabilityCaveats(reason, message) {
   const caveats = [message || "codegraph status failed"];
   if (reason === "absent") {
@@ -106,14 +124,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(path3) {
-  return path3.replaceAll("\\", "/").replace(/^\.\//, "");
+function normalizePath(path5) {
+  return path5.replaceAll("\\", "/").replace(/^\.\//, "");
 }
 function normalizeSignature(signature) {
   return signature.replace(/\s+/g, " ").trim();
 }
-function languageFromPath(path3) {
-  const extension = (0, import_node_path2.extname)(path3).toLowerCase();
+function languageFromPath(path5) {
+  const extension = (0, import_node_path2.extname)(path5).toLowerCase();
   return {
     ".c": "c",
     ".cc": "cpp",
@@ -281,7 +299,26 @@ var CodegraphAdapter = class {
         selected.spaceUid
       ) : selected;
     }
-    const requestedRoot = repo || this.env.MINDGRAPH_REPO_ROOT || this.cwd;
+    if (repo) {
+      const requestedPath = await (0, import_promises.realpath)((0, import_node_path2.resolve)(this.cwd, repo)).catch(
+        () => (0, import_node_path2.resolve)(this.cwd, repo)
+      );
+      if (!(0, import_node_fs2.existsSync)(requestedPath)) {
+        const current = await this.currentRepository(fallbackSpaceUid);
+        if (current.repoId === repo) return current;
+        throw new UnknownRepositoryError(repo);
+      }
+      const repoRoot = await this.gitRoot(requestedPath) ?? requestedPath;
+      return this.resolveRepositoryIdentity(
+        repoRoot,
+        this.env.MINDGRAPH_REPO_ID,
+        this.env.MINDGRAPH_CODE_SPACE_UID || fallbackSpaceUid
+      );
+    }
+    return this.currentRepository(fallbackSpaceUid);
+  }
+  async currentRepository(fallbackSpaceUid) {
+    const requestedRoot = this.env.MINDGRAPH_REPO_ROOT || this.cwd;
     const requestedPath = await (0, import_promises.realpath)((0, import_node_path2.resolve)(this.cwd, requestedRoot)).catch(
       () => (0, import_node_path2.resolve)(this.cwd, requestedRoot)
     );
@@ -371,6 +408,14 @@ var CodegraphAdapter = class {
     ).catch(() => "");
     return raw.trim() ? (0, import_node_path2.resolve)(start, raw.trim()) : void 0;
   }
+  /** Why the workspace map yielded no repositories — for callers that were
+   * explicitly asked to fan out and would otherwise return silently empty. */
+  workspaceDiagnostic() {
+    if (!this.workspaceFile || !(0, import_node_fs2.existsSync)(this.workspaceFile)) {
+      return "no .mindgraph/workspace.json was found between the working directory and the filesystem root";
+    }
+    return `${this.workspaceFile} is malformed or declares no repositories`;
+  }
   async availability(repository) {
     const cached = this.statusCache.get(repository.repoRoot);
     if (cached && cached.expiresAt > this.now()) return cached.availability;
@@ -790,7 +835,7 @@ var err = (code, message, details) => ({
 });
 var CODE_TOOL = {
   name: "mindgraph_code",
-  description: "Resolve typed code references through the local codegraph index and join them to persistent MindGraph memory/work. anchor creates exact repository/code anchors; recall reads attached graph context; expand reads callers/callees; affected reads impact for a code ref or Task/Execution. Ambiguous refs return candidates without writing.",
+  description: "Resolve typed code references through the local codegraph index and join them to persistent MindGraph memory/work. anchor creates exact repository/code anchors; recall reads attached graph context; expand reads callers/callees; affected reads impact for a code ref or Task/Execution. Ambiguous refs return candidates without writing. Refs with a path route to the repository defining that file (nearest declared root in .mindgraph/workspace.json); bare symbols resolve against the current repository only \u2014 pass path or repo to target a sibling.",
   inputSchema: {
     type: "object",
     properties: {
@@ -832,7 +877,7 @@ var CODE_TOOL = {
       },
       repo_space_uid: {
         type: "string",
-        description: "Writable shared Project/repository Space for new anchors"
+        description: "Writable shared Project/repository Space for new anchors (anchor requires this, a workspace space_uid, or MINDGRAPH_CODE_SPACE_UID)"
       },
       task_uid: { type: "string" },
       execution_uid: { type: "string" },
@@ -848,13 +893,13 @@ var CODE_TOOL = {
     openWorldHint: true
   }
 };
-async function handleCodeTool(client2, args, adapter = new CodegraphAdapter()) {
+async function handleCodeTool(client2, args, adapter = new CodegraphAdapter({ cwd: invocationCwd(args) })) {
   const codeClient = client2;
   const action = args.action;
   const refs = Array.isArray(args.code_refs) ? args.code_refs : [];
   const anchorUids = Array.isArray(args.anchor_uids) ? args.anchor_uids : [];
   const agentId = typeof args.agent_id === "string" ? args.agent_id : "mcp";
-  const fallbackSpaceUid = typeof args.repo_space_uid === "string" ? args.repo_space_uid : `space:agent:${agentId}`;
+  const fallbackSpaceUid = typeof args.repo_space_uid === "string" ? args.repo_space_uid : void 0;
   const options = {
     repo: typeof args.repo === "string" ? args.repo : void 0,
     fallbackSpaceUid
@@ -978,6 +1023,7 @@ async function handleCodeTool(client2, args, adapter = new CodegraphAdapter()) {
         const targetUid = typeof args.task_uid === "string" ? args.task_uid : typeof args.execution_uid === "string" ? args.execution_uid : void 0;
         let graphContext;
         const graphRefs = [];
+        let unavailableRepositories = [];
         if (targetUid) {
           graphContext = await codeClient.traverse({
             action: "neighborhood",
@@ -985,9 +1031,13 @@ async function handleCodeTool(client2, args, adapter = new CodegraphAdapter()) {
             depth: 2,
             max_nodes: 50
           });
-          graphRefs.push(
-            ...await codeRefsFromGraphContext(codeClient, adapter, graphContext)
+          const fromGraph = await codeRefsFromGraphContext(
+            codeClient,
+            adapter,
+            graphContext
           );
+          graphRefs.push(...fromGraph.refs);
+          unavailableRepositories = fromGraph.unavailable;
         }
         if (refs.length > 0 || anchorUids.length > 0) {
           const target = await resolveSingleTarget(
@@ -1006,7 +1056,8 @@ async function handleCodeTool(client2, args, adapter = new CodegraphAdapter()) {
             target_uid: targetUid,
             graph_context: graphContext,
             affected: [],
-            degradation: "no materialized code anchors were attached"
+            degradation: unavailableRepositories.length > 0 ? `attached code anchors reference repositories unavailable here: ${unavailableRepositories.join(", ")}` : "no materialized code anchors were attached",
+            ...unavailableRepositories.length > 0 ? { unavailable_repositories: unavailableRepositories } : {}
           });
         }
         const impacts = await Promise.all(
@@ -1023,13 +1074,17 @@ async function handleCodeTool(client2, args, adapter = new CodegraphAdapter()) {
           target_uid: targetUid,
           graph_context: graphContext,
           impacts,
-          materialized: joined
+          materialized: joined,
+          ...unavailableRepositories.length > 0 ? { unavailable_repositories: unavailableRepositories } : {}
         });
       }
       default:
         return err("unknown_action", `unknown mindgraph_code action: ${action}`);
     }
   } catch (cause) {
+    if (cause instanceof UnknownRepositoryError) {
+      return err("unknown_repository", cause.message);
+    }
     return err("code_tool_failed", errorDetail(cause));
   }
 }
@@ -1055,7 +1110,10 @@ async function attachCodeRefsToToolResult(client2, result, args, adapter) {
       code_refs: args.code_refs,
       repo: args.repo,
       repo_space_uid: args.repo_space_uid,
-      agent_id: args.agent_id
+      agent_id: args.agent_id,
+      // Keeps the default adapter anchored to the live session directory
+      // rather than wherever the MCP server process was launched.
+      invocation_context: args.invocation_context
     },
     adapter
   );
@@ -1065,17 +1123,33 @@ async function attachCodeRefsToToolResult(client2, result, args, adapter) {
     const anchorUids = (anchors.anchors ?? []).flatMap(
       (anchor) => anchor.uid ? [anchor.uid] : []
     );
+    const relateFailures = [];
     for (const targetUid of targetUids) {
       for (const anchorUid of anchorUids) {
-        await codeClient.entity({
-          action: "relate",
-          source_uid: targetUid,
-          target_uid: anchorUid,
-          edge_type: args.action === "lesson" ? "ABOUT" : "RELEVANT_TO",
-          agent_id: args.agent_id
-        });
+        try {
+          await codeClient.entity({
+            action: "relate",
+            source_uid: targetUid,
+            target_uid: anchorUid,
+            edge_type: args.action === "lesson" ? "ABOUT" : "RELEVANT_TO",
+            agent_id: args.agent_id
+          });
+        } catch (cause) {
+          relateFailures.push(
+            `${targetUid} -> ${anchorUid}: ${errorDetail(cause)}`
+          );
+        }
       }
     }
+    if (relateFailures.length > 0) {
+      return ok({
+        result: original,
+        code_anchors: {
+          ...anchors,
+          caveat: `anchors written, but ${relateFailures.length} relate edge(s) failed: ${relateFailures.join("; ")}`
+        }
+      });
+    }
   }
   return ok({ result: original, code_anchors: anchors });
 }
@@ -1148,16 +1222,34 @@ async function codeRefFromAnchor(client2, adapter, uid) {
   if (!attributes || typeof attributes !== "object") return void 0;
   const codeRef = attributes.code_ref;
   if (!isStoredCodeRef(codeRef)) return void 0;
-  const repository = await adapter.resolveRepository(codeRef.repoId);
-  return { ...codeRef, repoRoot: repository.repoRoot };
+  try {
+    const repository = await adapter.resolveRepository(codeRef.repoId);
+    return { ref: { ...codeRef, repoRoot: repository.repoRoot } };
+  } catch (cause) {
+    if (cause instanceof UnknownRepositoryError) {
+      return { missingRepo: codeRef.repoId };
+    }
+    throw cause;
+  }
 }
 async function resolveSingleTarget(client2, adapter, refs, anchorUids, options) {
   if (refs.length > 1 || anchorUids.length > 1) {
     return { error: err("ambiguous_target", "expand/affected accepts exactly one code target") };
   }
   if (anchorUids.length === 1) {
-    const ref = await codeRefFromAnchor(client2, adapter, anchorUids[0]);
-    return ref ? { ref } : { error: err("invalid_anchor", "anchor UID does not contain a typed code_ref") };
+    const outcome = await codeRefFromAnchor(client2, adapter, anchorUids[0]);
+    if (!outcome) {
+      return { error: err("invalid_anchor", "anchor UID does not contain a typed code_ref") };
+    }
+    if ("missingRepo" in outcome) {
+      return {
+        error: err(
+          "repository_unavailable",
+          `repository ${outcome.missingRepo} is not checked out here or declared in .mindgraph/workspace.json; expand/affected need its local index`
+        )
+      };
+    }
+    return { ref: outcome.ref };
   }
   if (refs.length !== 1) {
     return { error: err("missing_code_ref", "one code_ref or anchor_uid is required") };
@@ -1196,7 +1288,7 @@ async function joinMaterialized(client2, refs, agentId, limit) {
 async function codeRefsFromGraphContext(client2, adapter, context) {
   const uids = /* @__PURE__ */ new Set();
   collectUids(context, uids);
-  if (uids.size === 0) return [];
+  if (uids.size === 0) return { refs: [], unavailable: [] };
   const nodes = client2.getNodesBatch ? await client2.getNodesBatch([...uids]) : await Promise.all([...uids].map((uid) => client2.getNode(uid).catch(() => void 0)));
   const stored = nodes.flatMap((node) => {
     if (!node) return [];
@@ -1205,12 +1297,21 @@ async function codeRefsFromGraphContext(client2, adapter, context) {
     const codeRef = attributes.code_ref;
     return isStoredCodeRef(codeRef) ? [codeRef] : [];
   });
-  return Promise.all(
-    stored.map(async (ref) => {
+  const refs = [];
+  const unavailable = /* @__PURE__ */ new Set();
+  for (const ref of stored) {
+    try {
       const repository = await adapter.resolveRepository(ref.repoId);
-      return { ...ref, repoRoot: repository.repoRoot };
-    })
-  );
+      refs.push({ ...ref, repoRoot: repository.repoRoot });
+    } catch (cause) {
+      if (cause instanceof UnknownRepositoryError) {
+        unavailable.add(ref.repoId);
+      } else {
+        throw cause;
+      }
+    }
+  }
+  return { refs, unavailable: [...unavailable].sort() };
 }
 function collectUids(value, uids) {
   if (Array.isArray(value)) {
@@ -1352,14 +1453,29 @@ function safePath(root, candidate) {
   if (relative2.startsWith("..") || import_node_path3.default.isAbsolute(relative2)) {
     throw new Error(`path escapes repository root: ${candidate}`);
   }
+  if (import_node_fs3.default.existsSync(absolute)) {
+    if (!pathContains(realPathOf(root), realPathOf(absolute))) {
+      throw new Error(`path escapes repository root via symlink: ${candidate}`);
+    }
+  }
   return absolute;
 }
-function markdownFiles(target) {
+function realPathOf(target) {
+  try {
+    return import_node_fs3.default.realpathSync(target);
+  } catch {
+    return import_node_path3.default.resolve(target);
+  }
+}
+function markdownFiles(target, realRoot, visited = /* @__PURE__ */ new Set()) {
   if (!import_node_fs3.default.existsSync(target)) return [];
+  const real = realPathOf(target);
+  if (!pathContains(realRoot, real)) return [];
   const stat = import_node_fs3.default.statSync(target);
   if (stat.isFile()) return target.endsWith(".md") ? [target] : [];
-  if (!stat.isDirectory()) return [];
-  return import_node_fs3.default.readdirSync(target, { withFileTypes: true }).flatMap((entry) => markdownFiles(import_node_path3.default.join(target, entry.name)));
+  if (!stat.isDirectory() || visited.has(real)) return [];
+  visited.add(real);
+  return import_node_fs3.default.readdirSync(target, { withFileTypes: true }).flatMap((entry) => markdownFiles(import_node_path3.default.join(target, entry.name), realRoot, visited));
 }
 function fileDescriptor(root, absolute) {
   const content = import_node_fs3.default.readFileSync(absolute, "utf8");
@@ -1374,9 +1490,7 @@ async function handleSyncTool(client2, args) {
   try {
     const action = String(args.action || "");
     const context = args.invocation_context || {};
-    const adapter = new CodegraphAdapter({
-      cwd: context.cwd || process.cwd()
-    });
+    const adapter = new CodegraphAdapter({ cwd: invocationCwd(args) });
     const requestedRepo = typeof args.repo === "string" ? args.repo : typeof args.repo_id === "string" ? args.repo_id : context.repoId;
     const repository = await adapter.resolveRepository(requestedRepo);
     const root = repository.repoRoot;
@@ -1385,6 +1499,12 @@ async function handleSyncTool(client2, args) {
     const remote = client2;
     if (action === "scan") {
       const repositories = args.workspace === true ? await adapter.resolveRepositories() : [repository];
+      if (args.workspace === true && repositories.length === 0) {
+        return err2(
+          "workspace_not_configured",
+          `workspace scan found no declared repositories: ${adapter.workspaceDiagnostic()}`
+        );
+      }
       const requested = Array.isArray(args.paths) && args.paths.length > 0 ? args.paths.map(String) : [".claude/agent-memory", "memory"];
       const scans = [];
       for (const selected of repositories) {
@@ -1441,10 +1561,11 @@ async function handleSyncTool(client2, args) {
   }
 }
 async function scanRepository(remote, repository, requested, provider, agentId) {
+  const realRoot = realPathOf(repository.repoRoot);
   const files = [
     ...new Set(
       requested.flatMap(
-        (candidate) => markdownFiles(safePath(repository.repoRoot, candidate))
+        (candidate) => markdownFiles(safePath(repository.repoRoot, candidate), realRoot)
       )
     )
   ].sort();
@@ -1801,15 +1922,15 @@ function renderTraversal(response) {
   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 items = paths.map((raw) => obj(raw)).filter((path5) => Boolean(path5)).map((path5, index) => {
+      const uids = Array.isArray(path5.node_uids) ? path5.node_uids.map(String) : [];
+      const labels = Array.isArray(path5.labels) ? path5.labels.map(String) : Array.isArray(path5.nodes) ? path5.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 cost = num(path5.cost) ?? num(path5.path_cost);
+      const confidence = num(path5.path_confidence);
       const meta = [
         cost !== void 0 ? `cost ${cost}` : void 0,
         confidence !== void 0 ? `confidence ${confidence}` : void 0
@@ -1989,7 +2110,7 @@ function renderSignals(response) {
 var TOOLS = [
   {
     name: "mindgraph_capture",
-    description: "Capture knowledge into the graph. Use 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements, 'source' for documents/URLs, 'snippet' for quotes from a source, and 'concept' for abstract ideas. Use 'journal' for quick personal notes and 'lesson' for a durable learning attributable to a session or source nodes. Prefer 'entity'/'observation' for objective facts, 'journal' for informal notes, and 'lesson' only for reusable knowledge.",
+    description: "Capture knowledge into the graph. Use 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements, 'source' for documents/URLs, 'snippet' for quotes from a source, and 'concept' for abstract ideas. Use 'journal' for quick personal notes, 'lesson' for a durable learning, and 'skill' for a reusable procedure authored from completed work. Skill capture always creates a candidate requiring admin review; it never publishes. Skill names must be 1-64 lowercase a-z, digits, or hyphens, with no leading/trailing/consecutive hyphens and no 'anthropic' or 'claude'. Provide at least one provenance field and write instructions, not a transcript dump.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2002,7 +2123,8 @@ var TOOLS = [
             "snippet",
             "concept",
             "journal",
-            "lesson"
+            "lesson",
+            "skill"
           ],
           description: "Type of knowledge to capture"
         },
@@ -2016,11 +2138,30 @@ var TOOLS = [
         },
         content: {
           type: "string",
-          description: "Journal content/body text (for action=journal)"
+          maxLength: 65536,
+          description: "Journal body (action=journal) or complete SKILL.md instructions, at most 64 KiB UTF-8 (action=skill)"
+        },
+        name: {
+          type: "string",
+          minLength: 1,
+          maxLength: 64,
+          pattern: "^(?!.*(?:anthropic|claude))(?!-)(?!.*--)[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$",
+          description: "Stable skill identifier using lowercase a-z, digits, and hyphens (for action=skill)"
+        },
+        description: {
+          type: "string",
+          minLength: 1,
+          maxLength: 1024,
+          description: "When the skill should be used; XML tags are rejected (for action=skill)"
+        },
+        license: {
+          type: "string",
+          description: "Optional skill license (for action=skill)"
         },
         session_uid: {
           type: "string",
-          description: "Session UID that produced a lesson (for action=lesson)"
+          minLength: 1,
+          description: "Session UID that produced a lesson or skill"
         },
         work_uid: {
           type: "string",
@@ -2041,7 +2182,8 @@ var TOOLS = [
         summarizes_uids: {
           type: "array",
           items: { type: "string" },
-          description: "Source node UIDs the lesson was learned from (for action=lesson)"
+          minItems: 1,
+          description: "Source node UIDs the lesson or skill was learned from"
         },
         entity_type: {
           type: "string",
@@ -2108,7 +2250,24 @@ var TOOLS = [
           description: "Agent identity"
         }
       },
-      required: ["action", "label"]
+      required: ["action", "label"],
+      allOf: [
+        {
+          if: {
+            properties: { action: { const: "skill" } },
+            required: ["action"]
+          },
+          then: {
+            required: ["name", "description", "content"],
+            anyOf: [
+              { required: ["session_uid"] },
+              { required: ["work_uid"] },
+              { required: ["execution_uid"] },
+              { required: ["summarizes_uids"] }
+            ]
+          }
+        }
+      ]
     }
   },
   {
@@ -2694,6 +2853,42 @@ var TOOLS = [
       required: ["action"]
     }
   },
+  {
+    name: "mindgraph_series_query",
+    description: "Read dense numeric time series without placing raw points in general retrieval context. Use list_for_entity to discover series, latest for cached statistics, window for [from,to) keyset pages, and aggregate for bounded calendar buckets.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: "string",
+          enum: ["list_for_entity", "latest", "window", "aggregate"]
+        },
+        entity_uid: { type: "string" },
+        series_uid: { type: "string" },
+        from: { type: "number" },
+        to: { type: "number" },
+        cursor: { type: "number" },
+        limit: { type: "number", minimum: 1, maximum: 1e4 },
+        bucket: {
+          type: "string",
+          enum: ["year", "quarter", "month", "week", "day", "hour"]
+        },
+        agg: {
+          type: "string",
+          enum: ["sum", "mean", "min", "max", "count", "std_dev", "last"]
+        },
+        fill: { type: "string", enum: ["none", "null", "prev"] }
+      },
+      required: ["action"]
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  },
   {
     name: "mindgraph_ingest",
     description: "Ingest long-form content (articles, transcripts, documents, meeting notes) into the knowledge graph. The pipeline automatically chunks the text, extracts entities/claims/relationships via LLM, and deduplicates against existing nodes. Use 'chunk' for a single passage (synchronous), 'document' for full documents (async \u2014 returns a job ID), 'session' for conversation transcripts. Use 'job_status' to check progress. For short individual facts, use the specific cognitive tools instead.",
@@ -3026,6 +3221,9 @@ async function handleTool(client2, name, args) {
       case "mindgraph_retrieve":
         result = await handleRetrieve(client2, args);
         break;
+      case "mindgraph_series_query":
+        result = await handleSeriesQuery(client2, args);
+        break;
       case "mindgraph_ingest":
         result = await handleIngest(client2, args);
         break;
@@ -3070,12 +3268,36 @@ async function handleTool(client2, name, args) {
     return err3(errorDetail(e));
   }
 }
+async function handleSeriesQuery(client2, args) {
+  const action = typeof args.action === "string" ? args.action : "";
+  if (!["list_for_entity", "latest", "window", "aggregate"].includes(action)) {
+    return err3(`Unknown series query action: ${action}`);
+  }
+  if (action === "list_for_entity" && typeof args.entity_uid !== "string") {
+    return err3("entity_uid is required for action='list_for_entity'");
+  }
+  if (action !== "list_for_entity" && typeof args.series_uid !== "string") {
+    return err3(`series_uid is required for action='${action}'`);
+  }
+  if ((action === "window" || action === "aggregate") && (typeof args.from !== "number" || typeof args.to !== "number")) {
+    return err3(`from and to are required for action='${action}'`);
+  }
+  if (action === "aggregate" && (typeof args.bucket !== "string" || typeof args.agg !== "string")) {
+    return err3("bucket and agg are required for action='aggregate'");
+  }
+  return ok3(
+    await client2.series(args)
+  );
+}
 async function handleCapture(client2, args) {
   const {
     action,
     label,
     summary,
     content,
+    name,
+    description,
+    license,
     session_uid,
     work_uid,
     execution_uid,
@@ -3110,6 +3332,41 @@ async function handleCapture(client2, args) {
           agent_id
         })
       );
+    case "skill": {
+      if (!name) return err3("name is required for action=skill");
+      if (!description) return err3("description is required for action=skill");
+      if (content === void 0) return err3("content is required for action=skill");
+      const hasProvenance = [session_uid, work_uid, execution_uid].some(
+        (uid) => typeof uid === "string" && uid.length > 0
+      ) || Array.isArray(summarizes_uids) && summarizes_uids.some((uid) => typeof uid === "string" && uid.length > 0);
+      if (!hasProvenance) {
+        return err3(
+          "at least one of session_uid, work_uid, execution_uid, or summarizes_uids is required for action=skill"
+        );
+      }
+      return ok3(
+        await client2.distill({
+          label,
+          output_type: "skill",
+          summary,
+          confidence,
+          salience,
+          session_uid,
+          work_uid,
+          execution_uid,
+          idempotency_key,
+          supersedes_uid,
+          summarizes_uids,
+          props: {
+            name,
+            description,
+            content,
+            ...license ? { license } : {}
+          },
+          agent_id
+        })
+      );
+    }
     case "journal": {
       if (!content) return err3("content is required for action=journal");
       const journalProps = { content };
@@ -4313,6 +4570,7 @@ var ONTOLOGY_READ_ACTIONS = /* @__PURE__ */ new Set([
 ]);
 function toolMutability(toolName, action) {
   if (toolName === "mindgraph_retrieve") return "read";
+  if (toolName === "mindgraph_series_query") return "read";
   if (toolName === "mindgraph_plan") {
     return action && PLAN_READ_ACTIONS.has(action) ? "read" : "write";
   }
@@ -4339,6 +4597,8 @@ function toolMutability(toolName, action) {
 var UID_FIELDS = [
   "uid",
   "source_uid",
+  "entity_uid",
+  "series_uid",
   "session_uid",
   "work_uid",
   "goal_uid",
@@ -4440,7 +4700,7 @@ async function checkMcpGovernance(toolName, args, config) {
   if (!response) {
     return {
       allowed: false,
-      message: `MindGraph governance could not establish permission after ${retryDelays.length + 1} attempts (${lastFailure}). Set MINDGRAPH_GOVERNANCE=off to run this adapter ungoverned.`
+      message: `MindGraph at ${config.baseUrl} is unreachable (${lastFailure}; ${retryDelays.length + 1} attempts). The tool call was NOT evaluated against policy and NOT executed \u2014 this is a connectivity failure, not a governance denial. Check the network and MINDGRAPH_BASE_URL, then retry.`
     };
   }
   if (!response.ok) {
@@ -4606,6 +4866,225 @@ async function readGovernedResource(client2, uri, governanceConfig) {
   return readResource(client2, uri);
 }
 
+// src/index.ts
+var import_node_path5 = __toESM(require("path"));
+
+// src/hook-installer.ts
+var import_node_fs4 = __toESM(require("fs"));
+var import_node_os3 = __toESM(require("os"));
+var import_node_path4 = __toESM(require("path"));
+var import_node_crypto4 = __toESM(require("crypto"));
+var OWNER_MARKER = "--owner mindgraph";
+var RUNNER_RELATIVE = ".mindgraph/bin/mindgraph-hook.cjs";
+function command(harness) {
+  return `node "$HOME/${RUNNER_RELATIVE}" hook --harness ${harness} --owner mindgraph`;
+}
+function windowsCommand(harness) {
+  return `node "%USERPROFILE%\\.mindgraph\\bin\\mindgraph-hook.cjs" hook --harness ${harness} --owner mindgraph`;
+}
+var RUNNER_VERSION_RELATIVE = `${RUNNER_RELATIVE}.version`;
+function installHookRunner(sourceFile, homeDir, version) {
+  const target = import_node_path4.default.join(homeDir || import_node_os3.default.homedir(), RUNNER_RELATIVE);
+  import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(target), { recursive: true });
+  const temporary = `${target}.${process.pid}.${import_node_crypto4.default.randomUUID()}.tmp`;
+  import_node_fs4.default.copyFileSync(sourceFile, temporary);
+  import_node_fs4.default.renameSync(temporary, target);
+  const versionPath = import_node_path4.default.join(homeDir || import_node_os3.default.homedir(), RUNNER_VERSION_RELATIVE);
+  if (version) {
+    import_node_fs4.default.writeFileSync(versionPath, `${version}
+`);
+  } else {
+    import_node_fs4.default.rmSync(versionPath, { force: true });
+  }
+  return target;
+}
+function installedHookRunnerVersion(homeDir) {
+  try {
+    const raw = import_node_fs4.default.readFileSync(
+      import_node_path4.default.join(homeDir || import_node_os3.default.homedir(), RUNNER_VERSION_RELATIVE),
+      "utf8"
+    ).trim();
+    return raw || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parseSemver(value) {
+  if (!value) return void 0;
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value.trim());
+  if (!match) return void 0;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function semverNewer(a, b) {
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] > b[index];
+  }
+  return false;
+}
+function refreshHookRunner(serverVersion, sourceBundle, homeDir) {
+  try {
+    if (process.env.MINDGRAPH_HOOK_AUTOUPDATE === "off") {
+      return { refreshed: false, reason: "disabled" };
+    }
+    const home = homeDir || import_node_os3.default.homedir();
+    if (!import_node_fs4.default.existsSync(import_node_path4.default.join(home, RUNNER_RELATIVE))) {
+      return { refreshed: false, reason: "no_runner" };
+    }
+    if (!import_node_fs4.default.existsSync(sourceBundle)) {
+      return { refreshed: false, reason: "no_source" };
+    }
+    const server2 = parseSemver(serverVersion);
+    if (!server2) return { refreshed: false, reason: "unparseable" };
+    const runnerVersion = installedHookRunnerVersion(home);
+    if (runnerVersion !== void 0) {
+      const pinned = parseSemver(runnerVersion);
+      if (!pinned) {
+        return { refreshed: false, reason: "unparseable", runnerVersion };
+      }
+      if (!semverNewer(server2, pinned)) {
+        return {
+          refreshed: false,
+          reason: runnerVersion === serverVersion ? "current" : "downgrade",
+          runnerVersion
+        };
+      }
+    }
+    installHookRunner(sourceBundle, home, serverVersion);
+    return { refreshed: true, reason: "updated", runnerVersion };
+  } catch {
+    return { refreshed: false, reason: "error" };
+  }
+}
+function refreshOwnedClaudeHooks(projectDir = process.cwd(), homeDir) {
+  const refreshed = [];
+  const scopes = ["user", "project"];
+  for (const scope of scopes) {
+    try {
+      const file = settingsPath("claude-code", scope, projectDir, void 0, homeDir);
+      if (!import_node_fs4.default.existsSync(file)) continue;
+      if (!import_node_fs4.default.readFileSync(file, "utf8").includes(OWNER_MARKER)) continue;
+      installHooks("claude-code", scope, projectDir, void 0, homeDir);
+      refreshed.push(file);
+    } catch {
+    }
+  }
+  return refreshed;
+}
+function versionSkewNote(serverVersion, homeDir) {
+  const runnerVersion = installedHookRunnerVersion(homeDir);
+  if (!runnerVersion || runnerVersion === serverVersion) return void 0;
+  return `NOTE: the installed MindGraph hook runner is v${runnerVersion} but this MCP server is v${serverVersion} \u2014 hook behavior and tool contracts may be out of sync. Tell the user to run: npx -y mindgraph-mcp@latest install-hooks (refreshes the pinned runner).`;
+}
+function settingsPath(harness, scope, projectDir = process.cwd(), codexHomeDir = process.env.CODEX_HOME || import_node_path4.default.join(import_node_os3.default.homedir(), ".codex"), homeDir) {
+  if (harness === "codex") {
+    return scope === "user" ? import_node_path4.default.join(codexHomeDir, "hooks.json") : import_node_path4.default.join(projectDir, ".codex", "hooks.json");
+  }
+  return scope === "user" ? import_node_path4.default.join(homeDir || import_node_os3.default.homedir(), ".claude", "settings.json") : import_node_path4.default.join(projectDir, ".claude", "settings.json");
+}
+function readSettings(file) {
+  if (!import_node_fs4.default.existsSync(file)) return {};
+  return JSON.parse(import_node_fs4.default.readFileSync(file, "utf8"));
+}
+function ownedHook(harness, timeout, additionalContextLimit) {
+  return {
+    type: "command",
+    command: command(harness),
+    ...harness === "codex" ? { commandWindows: windowsCommand(harness) } : {},
+    timeout,
+    statusMessage: "Syncing MindGraph session context",
+    ...additionalContextLimit === void 0 ? {} : { additionalContextLimit }
+  };
+}
+function desiredEntries(harness) {
+  const common = {
+    SessionStart: [
+      {
+        matcher: harness === "claude-code" ? "startup|resume|clear|compact|fork" : "startup|resume|clear|compact",
+        // B7 live acceptance caught cold SessionStart calls crossing the
+        // inherited 20s edge in both harnesses: the hooks correctly failed
+        // open, but no brief reached the model. The same installed runner
+        // completed in 16.84s once warm. Keep a 30s cold-tenant margin.
+        // The declared Codex context limit must not undercut the brief's own
+        // 9,000-char budget: at 3,000 the harness applied a SECOND, tighter
+        // truncation the renderer knew nothing about.
+        hooks: [
+          ownedHook(
+            harness,
+            30,
+            harness === "codex" ? 1e4 : void 0
+          )
+        ]
+      }
+    ],
+    PreToolUse: [
+      {
+        matcher: "mcp__mindgraph__.*",
+        // Repository resolution over a large multi-repo workspace plus three
+        // git probes can exceed 3s on the first (uncached) call; a killed
+        // PreToolUse means the call goes through untagged.
+        hooks: [ownedHook(harness, 5)]
+      }
+    ],
+    // PostToolUse awaits the lease renewal round-trip, which fires exactly
+    // when the tenant is cold (post-idle reclaim) — 5s killed it mid-claim.
+    PostToolUse: [{ matcher: ".*", hooks: [ownedHook(harness, 10)] }],
+    Stop: [{ hooks: [ownedHook(harness, 5)] }],
+    // SessionEnd makes up to two sequential cloud calls (abandon_iteration +
+    // session close) — the SAME cold-tenant latency SessionStart needs 30s
+    // for. Claude honors the configured budget; Codex clamps SessionEnd to a
+    // 3s platform cap regardless of this value (see codex-hooks.ts wire
+    // map), so the codex adapter instead makes at most ONE call there.
+    SessionEnd: [
+      { hooks: [ownedHook(harness, harness === "codex" ? 3 : 30)] }
+    ]
+  };
+  return harness === "claude-code" ? {
+    ...common,
+    TaskCreated: [{ hooks: [ownedHook(harness, 3)] }],
+    TaskCompleted: [{ hooks: [ownedHook(harness, 3)] }]
+  } : common;
+}
+function hookCommand(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const command2 = value.command;
+  return typeof command2 === "string" ? command2 : void 0;
+}
+function entryHasOwnedHook(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const hooks = value.hooks;
+  return Array.isArray(hooks) && hooks.some((hook) => hookCommand(hook)?.includes(OWNER_MARKER));
+}
+function writeSettings(file, settings) {
+  import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${import_node_crypto4.default.randomUUID()}.tmp`;
+  import_node_fs4.default.writeFileSync(temporary, `${JSON.stringify(settings, null, 2)}
+`, {
+    mode: 384
+  });
+  import_node_fs4.default.renameSync(temporary, file);
+}
+function installHooks(harness, scope, projectDir = process.cwd(), codexHomeDir, homeDir) {
+  const file = settingsPath(harness, scope, projectDir, codexHomeDir, homeDir);
+  const settings = readSettings(file);
+  const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks) ? settings.hooks : {};
+  let added = 0;
+  let updated = 0;
+  for (const [event, wanted] of Object.entries(desiredEntries(harness))) {
+    const current = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+    const kept = current.filter((entry) => !entryHasOwnedHook(entry));
+    const hadOwned = kept.length !== current.length;
+    for (const entry of wanted) {
+      kept.push(entry);
+      if (hadOwned) updated += 1;
+      else added += 1;
+    }
+    hooks[event] = kept;
+  }
+  settings.hooks = hooks;
+  writeSettings(file, settings);
+  return { path: file, added, updated };
+}
+
 // src/index.ts
 var API_KEY = process.env.MINDGRAPH_API_KEY;
 var BASE_URL = process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud";
@@ -4728,10 +5207,42 @@ if (PROFILE === "coding") {
     (line) => !line.includes("mindgraph_code") && !line.includes("`code`") && !line.includes("Typed code anchors")
   ).join("\n");
 }
+var RUNNER_REFRESH = (() => {
+  try {
+    return refreshHookRunner("0.19.0", import_node_path5.default.join(__dirname, "cli.js"));
+  } catch {
+    return void 0;
+  }
+})();
+if (RUNNER_REFRESH?.refreshed) {
+  const refreshedSettings = (() => {
+    try {
+      return refreshOwnedClaudeHooks();
+    } catch {
+      return [];
+    }
+  })();
+  console.error(
+    `[mindgraph-mcp] refreshed pinned hook runner ${RUNNER_REFRESH.runnerVersion ? `v${RUNNER_REFRESH.runnerVersion}` : "(pre-sidecar)"} \u2192 v${"0.19.0"}` + (refreshedSettings.length > 0 ? `; refreshed owned hook entries in ${refreshedSettings.join(", ")}` : "")
+  );
+}
+var HOOK_SKEW_NOTE = (() => {
+  try {
+    return versionSkewNote("0.19.0");
+  } catch {
+    return void 0;
+  }
+})();
+if (HOOK_SKEW_NOTE) {
+  INSTRUCTIONS += `
+
+${HOOK_SKEW_NOTE}`;
+  console.error(`[mindgraph-mcp] ${HOOK_SKEW_NOTE}`);
+}
 var server = new import_server.Server(
   {
     name: "mindgraph",
-    version: "0.17.0"
+    version: "0.19.0"
   },
   {
     capabilities: {
@@ -4945,7 +5456,7 @@ async function main() {
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
   console.error(
-    `MindGraph MCP server v${"0.17.0"} running on stdio (${BASE_URL})`
+    `MindGraph MCP server v${"0.19.0"} running on stdio (${BASE_URL})`
   );
 }
 main().catch((error) => {