@gmickel/gno 1.16.0 → 1.18.0

package/src/mcp/tools/context.ts

@@ -0,0 +1,230 @@
+/** MCP Context Capsule tools over the shared application runtime. */
+
+import type { ModelLease } from "../../llm/nodeLlamaCpp/lifecycle";
+import type { EmbeddingPort, RerankPort } from "../../llm/types";
+import type { VectorIndexPort } from "../../store/vector";
+import type { ToolContext } from "../server";
+import type { ToolResult } from "./index";
+
+import { formatContextCapsuleAgentJson } from "../../app/context-agent-projection";
+import { formatContextCapsuleVerificationMarkdown } from "../../app/context-format";
+import {
+  buildContextCapsule,
+  canonicalVerifiedContextCapsuleJson,
+  validateContextCapsuleBuildInput,
+  verifyContextCapsuleRuntime,
+} from "../../app/context-runtime";
+import {
+  contextSurfaceError,
+  parseContextBuildSurfaceInput,
+  parseContextVerifySurfaceInput,
+} from "../../app/context-surface";
+import { createNonTtyProgressRenderer } from "../../cli/progress";
+import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
+import { resolveDownloadPolicy } from "../../llm/policy";
+import { resolveModelUri } from "../../llm/registry";
+import { createVectorIndexPort } from "../../store/vector";
+
+interface ContextToolResultData {
+  structuredContent: Record<string, unknown>;
+  text: string;
+}
+
+const asToolResult = (data: ContextToolResultData): ToolResult => ({
+  content: [{ type: "text", text: data.text }],
+  structuredContent: data.structuredContent,
+});
+
+const asToolError = (error: unknown): ToolResult => {
+  const publicError = contextSurfaceError(error);
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Error [${publicError.code}]: ${publicError.message}`,
+      },
+    ],
+    structuredContent: {
+      error: publicError.code,
+      message: publicError.message,
+    },
+  };
+};
+
+const runContextTool = async (
+  context: ToolContext,
+  operation: () => Promise<ContextToolResultData>
+): Promise<ToolResult> => {
+  if (context.isShuttingDown()) {
+    return asToolError(
+      Object.assign(new Error("Server is shutting down"), {
+        code: "runtime_error",
+      })
+    );
+  }
+  const release = await context.toolMutex.acquire();
+  try {
+    const data = await (context.runWithSnapshot?.(operation) ?? operation());
+    return asToolResult(data);
+  } catch (error) {
+    return asToolError(error);
+  } finally {
+    release();
+  }
+};
+
+interface McpModelPorts {
+  embedPort: EmbeddingPort | null;
+  rerankPort: RerankPort | null;
+  vectorIndex: VectorIndexPort | null;
+  dispose(): Promise<void>;
+}
+
+interface McpModelPortFactory {
+  createEmbeddingPort: LlmAdapter["createEmbeddingPort"];
+  createRerankPort: LlmAdapter["createRerankPort"];
+  acquireModelLease?: LlmAdapter["acquireModelLease"];
+}
+
+export const disposeContextModelOwners = async (
+  portOwners: readonly { dispose(): Promise<void> }[],
+  lease?: ModelLease
+): Promise<void> => {
+  await Promise.allSettled(
+    portOwners.map((owner) => Promise.resolve().then(() => owner.dispose()))
+  );
+  lease?.release();
+};
+
+export const createMcpModelPorts = async (
+  context: ToolContext,
+  collection?: string,
+  factoryOverride?: McpModelPortFactory
+): Promise<McpModelPorts> => {
+  const llm = new LlmAdapter(context.config);
+  const factory = factoryOverride ?? llm;
+  const lease = factory.acquireModelLease?.();
+  const policy = resolveDownloadPolicy(process.env, {});
+  const progress = createNonTtyProgressRenderer();
+  const embedUri = resolveModelUri(
+    context.config,
+    "embed",
+    undefined,
+    collection
+  );
+  let embedPort: EmbeddingPort | null = null;
+  let ownedEmbedPort: EmbeddingPort | null = null;
+  let rerankPort: RerankPort | null = null;
+  let vectorIndex: VectorIndexPort | null = null;
+  try {
+    const embedResult = await factory.createEmbeddingPort(embedUri, {
+      policy,
+      onProgress: (value) => progress("embed", value),
+    });
+    if (embedResult.ok) {
+      // Take ownership before init: init failures must not leak the port.
+      ownedEmbedPort = embedResult.value;
+      const initialized = await ownedEmbedPort.init();
+      if (initialized.ok) {
+        embedPort = ownedEmbedPort;
+        const vectorResult = await createVectorIndexPort(
+          context.store.getRawDb(),
+          { model: embedUri, dimensions: ownedEmbedPort.dimensions() }
+        );
+        if (vectorResult.ok) vectorIndex = vectorResult.value;
+      }
+    }
+    const rerankResult = await factory.createRerankPort(
+      resolveModelUri(context.config, "rerank", undefined, collection),
+      {
+        policy,
+        onProgress: (value) => progress("rerank", value),
+      }
+    );
+    if (rerankResult.ok) rerankPort = rerankResult.value;
+    return {
+      embedPort,
+      rerankPort,
+      vectorIndex,
+      async dispose() {
+        await disposeContextModelOwners(
+          [ownedEmbedPort, rerankPort].filter(
+            (port): port is EmbeddingPort | RerankPort => port !== null
+          ),
+          lease
+        );
+      },
+    };
+  } catch (error) {
+    await disposeContextModelOwners(
+      [ownedEmbedPort, rerankPort].filter(
+        (port): port is EmbeddingPort | RerankPort => port !== null
+      ),
+      lease
+    );
+    throw error;
+  }
+};
+
+export const handleContext = (
+  args: unknown,
+  context: ToolContext
+): Promise<ToolResult> =>
+  runContextTool(context, async () => {
+    const parsed = parseContextBuildSurfaceInput(args, context.indexName);
+    // This guard is intentionally before any model construction/download.
+    validateContextCapsuleBuildInput(
+      parsed.input,
+      context.indexName,
+      context.config.collections.map((collection) => collection.name)
+    );
+    const useModels = parsed.input.depthPolicy !== "fast";
+    const modelPorts = useModels
+      ? await createMcpModelPorts(
+          context,
+          parsed.input.collections?.length === 1
+            ? parsed.input.collections[0]
+            : undefined
+        )
+      : null;
+    try {
+      const capsule = await buildContextCapsule(parsed.input, {
+        store: context.store,
+        config: context.config,
+        indexName: context.indexName,
+        vectorIndex: modelPorts?.vectorIndex ?? null,
+        embedPort: modelPorts?.embedPort ?? null,
+        rerankPort: modelPorts?.rerankPort ?? null,
+      });
+      return {
+        structuredContent: capsule as unknown as Record<string, unknown>,
+        // MCP model context receives this projection exactly once. The full
+        // canonical capsule remains available to application clients through
+        // structuredContent and is deliberately not duplicated in text.
+        text: formatContextCapsuleAgentJson(capsule),
+      };
+    } finally {
+      await modelPorts?.dispose();
+    }
+  });
+
+export const handleContextVerify = (
+  args: unknown,
+  context: ToolContext
+): Promise<ToolResult> =>
+  runContextTool(context, async () => {
+    const parsed = parseContextVerifySurfaceInput(args);
+    const receipt = await verifyContextCapsuleRuntime(parsed.capsule, {
+      store: context.store,
+      config: context.config,
+      indexName: context.indexName,
+    });
+    return {
+      structuredContent: receipt as unknown as Record<string, unknown>,
+      text:
+        parsed.format === "md"
+          ? formatContextCapsuleVerificationMarkdown(receipt)
+          : canonicalVerifiedContextCapsuleJson(receipt),
+    };
+  });

package/src/mcp/tools/embed.ts

@@ -9,6 +9,7 @@ import type { ToolContext } from "../server";
 import { MCP_ERRORS } from "../../core/errors";
 import { acquireWriteLock, type WriteLockHandle } from "../../core/file-lock";
 import { JobError } from "../../core/job-manager";
+import { recordIndexMutation } from "../../core/mutation-generations";
 import { embedBacklog } from "../../embed";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveModelUri } from "../../llm/registry";
@@ -81,64 +82,73 @@ export function handleEmbed(
           "embed",
           lock,
           async () => {
-            // Create LLM adapter with offline policy (fail-fast, no download)
-            const llm = new LlmAdapter(ctx.config);
-            const embedResult = await llm.createEmbeddingPort(modelUri, {
-              policy: { offline: true, allowDownload: false },
-            });
-
-            if (!embedResult.ok) {
-              throw new Error(
-                `MODEL_NOT_FOUND: Embedding model not cached. ` +
-                  `Model: ${modelUri}. ` +
-                  `Run 'gno models pull embed' first.`
-              );
-            }
-
-            const embedPort = embedResult.value;
-
+            const lease = ctx.acquireModelLease?.();
             try {
-              // Initialize and get dimensions from port interface
-              const initResult = await embedPort.init();
-              if (!initResult.ok) {
-                throw new Error(initResult.error.message);
-              }
-              const dimensions = embedPort.dimensions();
-
-              // Create vector index port
-              const db = ctx.store.getRawDb();
-              const vectorResult = await createVectorIndexPort(db, {
-                model: modelUri,
-                dimensions,
-              });
-              if (!vectorResult.ok) {
-                throw new Error(vectorResult.error.message);
-              }
-              const vectorIndex = vectorResult.value;
-
-              // Create stats port for backlog
-              const statsPort = createVectorStatsPort(db);
-
-              // Run embedding
-              const result = await embedBacklog({
-                statsPort,
-                embedPort,
-                vectorIndex,
-                collection: collection?.name,
-                modelUri,
-                batchSize: 32,
+              // Create LLM adapter with offline policy (fail-fast, no download)
+              const llm = new LlmAdapter(ctx.config);
+              const embedResult = await llm.createEmbeddingPort(modelUri, {
+                policy: { offline: true, allowDownload: false },
               });
 
-              if (!result.ok) {
-                throw new Error(result.error.message);
+              if (!embedResult.ok) {
+                throw new Error(
+                  `MODEL_NOT_FOUND: Embedding model not cached. ` +
+                    `Model: ${modelUri}. ` +
+                    `Run 'gno models pull embed' first.`
+                );
               }
 
-              return {
-                kind: "embed" as const,
-                value: result.value,
-              };
+              const embedPort = embedResult.value;
+
+              try {
+                // Initialize and get dimensions from port interface
+                const initResult = await embedPort.init();
+                if (!initResult.ok) {
+                  throw new Error(initResult.error.message);
+                }
+                const dimensions = embedPort.dimensions();
+
+                // Create vector index port
+                const db = ctx.store.getRawDb();
+                const vectorResult = await createVectorIndexPort(db, {
+                  model: modelUri,
+                  dimensions,
+                });
+                if (!vectorResult.ok) {
+                  throw new Error(vectorResult.error.message);
+                }
+                const vectorIndex = vectorResult.value;
+
+                // Create stats port for backlog
+                const statsPort = createVectorStatsPort(db);
+
+                // Run embedding
+                const result = await embedBacklog({
+                  statsPort,
+                  embedPort,
+                  vectorIndex,
+                  collection: collection?.name,
+                  modelUri,
+                  batchSize: 32,
+                });
+
+                if (!result.ok) {
+                  throw new Error(result.error.message);
+                }
+                recordIndexMutation(
+                  result.value.embedded,
+                  ctx.markIndexMutation
+                );
+
+                return {
+                  kind: "embed" as const,
+                  value: result.value,
+                };
+              } finally {
+                await embedPort.dispose();
+              }
             } finally {
-              await embedPort.dispose();
+              lease?.release();
             }
           }
         );

package/src/mcp/tools/index-cmd.ts

@@ -10,6 +10,10 @@ import type { ToolContext } from "../server";
 import { MCP_ERRORS } from "../../core/errors";
 import { acquireWriteLock, type WriteLockHandle } from "../../core/file-lock";
 import { JobError } from "../../core/job-manager";
+import {
+  recordContentMutation,
+  recordIndexMutation,
+} from "../../core/mutation-generations";
 import { normalizeCollectionName } from "../../core/validation";
 import { embedBacklog } from "../../embed";
 import { defaultSyncService, withContentTypeRules } from "../../ingestion";
@@ -115,86 +119,96 @@ export function handleIndex(
           "index",
           lock,
           async () => {
-            // Phase 1: Sync
-            const syncResult = collection
-              ? await defaultSyncService
-                  .syncCollection(collection, ctx.store, options)
-                  .then((r) => ({
-                    collections: [r],
-                    totalDurationMs: r.durationMs,
-                    totalFilesProcessed: r.filesProcessed,
-                    totalFilesAdded: r.filesAdded,
-                    totalFilesUpdated: r.filesUpdated,
-                    totalFilesErrored: r.filesErrored,
-                    totalFilesSkipped: r.filesSkipped,
-                  }))
-              : await defaultSyncService.syncAll(
-                  ctx.collections,
-                  ctx.store,
-                  options
-                );
-
-            // Phase 2: Embed
-            const llm = new LlmAdapter(ctx.config);
-            const embedResult = await llm.createEmbeddingPort(modelUri, {
-              policy: { offline: true, allowDownload: false },
-            });
-
-            if (!embedResult.ok) {
-              throw new Error(
-                `MODEL_NOT_FOUND: Embedding model not cached. ` +
-                  `Model: ${modelUri}. ` +
-                  `Run 'gno models pull embed' first.`
-              );
-            }
-
-            const embedPort = embedResult.value;
-
+            const lease = ctx.acquireModelLease?.();
             try {
-              // Initialize and get dimensions from port interface
-              const initResult = await embedPort.init();
-              if (!initResult.ok) {
-                throw new Error(initResult.error.message);
-              }
-              const dimensions = embedPort.dimensions();
-
-              // Create vector index port
-              const db = ctx.store.getRawDb();
-              const vectorResult = await createVectorIndexPort(db, {
-                model: modelUri,
-                dimensions,
-              });
-              if (!vectorResult.ok) {
-                throw new Error(vectorResult.error.message);
-              }
-              const vectorIndex = vectorResult.value;
-
-              // Create stats port for backlog
-              const statsPort = createVectorStatsPort(db);
-
-              // Run embedding
-              const backlogResult = await embedBacklog({
-                statsPort,
-                embedPort,
-                vectorIndex,
-                collection: collection?.name,
-                modelUri,
-                batchSize: 32,
+              // Phase 1: Sync
+              const syncResult = collection
+                ? await defaultSyncService
+                    .syncCollection(collection, ctx.store, options)
+                    .then((r) => ({
+                      collections: [r],
+                      totalDurationMs: r.durationMs,
+                      totalFilesProcessed: r.filesProcessed,
+                      totalFilesAdded: r.filesAdded,
+                      totalFilesUpdated: r.filesUpdated,
+                      totalFilesErrored: r.filesErrored,
+                      totalFilesSkipped: r.filesSkipped,
+                    }))
+                : await defaultSyncService.syncAll(
+                    ctx.collections,
+                    ctx.store,
+                    options
+                  );
+              recordContentMutation(syncResult, ctx.markContentMutation);
+
+              // Phase 2: Embed
+              const llm = new LlmAdapter(ctx.config);
+              const embedResult = await llm.createEmbeddingPort(modelUri, {
+                policy: { offline: true, allowDownload: false },
               });
 
-              if (!backlogResult.ok) {
-                throw new Error(backlogResult.error.message);
+              if (!embedResult.ok) {
+                throw new Error(
+                  `MODEL_NOT_FOUND: Embedding model not cached. ` +
+                    `Model: ${modelUri}. ` +
+                    `Run 'gno models pull embed' first.`
+                );
               }
 
-              return {
-                kind: "index" as const,
-                value: {
-                  sync: syncResult,
-                  embed: backlogResult.value,
-                },
-              };
+              const embedPort = embedResult.value;
+
+              try {
+                // Initialize and get dimensions from port interface
+                const initResult = await embedPort.init();
+                if (!initResult.ok) {
+                  throw new Error(initResult.error.message);
+                }
+                const dimensions = embedPort.dimensions();
+
+                // Create vector index port
+                const db = ctx.store.getRawDb();
+                const vectorResult = await createVectorIndexPort(db, {
+                  model: modelUri,
+                  dimensions,
+                });
+                if (!vectorResult.ok) {
+                  throw new Error(vectorResult.error.message);
+                }
+                const vectorIndex = vectorResult.value;
+
+                // Create stats port for backlog
+                const statsPort = createVectorStatsPort(db);
+
+                // Run embedding
+                const backlogResult = await embedBacklog({
+                  statsPort,
+                  embedPort,
+                  vectorIndex,
+                  collection: collection?.name,
+                  modelUri,
+                  batchSize: 32,
+                });
+
+                if (!backlogResult.ok) {
+                  throw new Error(backlogResult.error.message);
+                }
+                recordIndexMutation(
+                  backlogResult.value.embedded,
+                  ctx.markIndexMutation
+                );
+
+                return {
+                  kind: "index" as const,
+                  value: {
+                    sync: syncResult,
+                    embed: backlogResult.value,
+                  },
+                };
+              } finally {
+                await embedPort.dispose();
+              }
             } finally {
-              await embedPort.dispose();
+              lease?.release();
             }
           }
         );

package/src/mcp/tools/index.ts

@@ -10,12 +10,17 @@ import { z } from "zod";
 
 import type { ToolContext } from "../server";
 
+import {
+  contextBuildSurfaceSchema,
+  contextVerifySurfaceSchema,
+} from "../../app/context-surface";
 import { CAPTURE_MAX_TEXT_BYTES } from "../../core/capture";
 import { NOTE_PRESETS, type NotePresetId } from "../../core/note-presets";
 import { normalizeTag } from "../../core/tags";
 import { handleAddCollection } from "./add-collection";
 import { handleCapture } from "./capture";
 import { handleClearCollectionEmbeddings } from "./clear-collection-embeddings";
+import { handleContext, handleContextVerify } from "./context";
 import { handleEmbed } from "./embed";
 import { handleGet } from "./get";
 import { handleIndex } from "./index-cmd";
@@ -72,8 +77,27 @@ export const MCP_TOOL_DESCRIPTIONS = {
     "Retrieve multiple documents by refs array or glob pattern. Use after gno_search/gno_query to batch top result URIs/docids; set maxBytes and lineNumbers to control context size.",
   status:
     "Get index health: collection count, document count, chunk count, embedding backlog, and per-collection stats. Check first when vector/hybrid results look stale or unavailable.",
+  context:
+    "Compile one deterministic, budgeted, extractive evidence Capsule with exact line spans, coverage gaps, omissions, provenance, and verification fingerprints. Raw search/get tools remain available for manual retrieval.",
+  contextVerify:
+    "Verify a saved Context Capsule without rebuilding or mutating it. Reports unchanged, stale, missing, reranked, and fingerprint drift states against the active index.",
 } as const;
 
+/** Tool names whose execution mutates disk, config, or index state. */
+export const MCP_WRITE_TOOL_NAMES = new Set([
+  "gno_capture",
+  "gno_add_collection",
+  "gno_sync",
+  "gno_embed",
+  "gno_index",
+  "gno_remove_collection",
+  "gno_clear_collection_embeddings",
+  "gno_create_folder",
+  "gno_rename_note",
+  "gno_move_note",
+  "gno_duplicate_note",
+]);
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Shared Input Schemas
 // ─────────────────────────────────────────────────────────────────────────────
@@ -820,8 +844,9 @@ export async function runTool<T>(
 
   // Sequential execution via mutex
   const release = await ctx.toolMutex.acquire();
+  const modelLease = ctx.acquireModelLease?.();
   try {
-    const data = await fn();
+    const data = await (ctx.runWithSnapshot?.(fn) ?? fn());
     return {
       content: [{ type: "text", text: formatText(data) }],
       structuredContent: data as { [x: string]: unknown },
@@ -837,6 +862,7 @@ export async function runTool<T>(
       structuredContent: parsedError,
     };
   } finally {
+    modelLease?.release();
     release();
   }
 }
@@ -860,8 +886,9 @@ export async function runToolNoMutex<T>(
     };
   }
 
+  const modelLease = ctx.acquireModelLease?.();
   try {
-    const data = await fn();
+    const data = await (ctx.runWithSnapshot?.(fn) ?? fn());
     return {
       content: [{ type: "text", text: formatText(data) }],
       structuredContent: data as { [x: string]: unknown },
@@ -876,6 +903,8 @@ export async function runToolNoMutex<T>(
       content: [{ type: "text", text: `Error: ${message}` }],
       structuredContent: parsedError,
     };
+  } finally {
+    modelLease?.release();
   }
 }
 
@@ -899,6 +928,24 @@ function parseErrorMessage(message: string): { [x: string]: unknown } {
 
 export function registerTools(server: McpServer, ctx: ToolContext): void {
   // Tool IDs use underscores (MCP pattern: ^[a-zA-Z0-9_-]{1,64}$)
+  server.registerTool(
+    "gno_context",
+    {
+      description: MCP_TOOL_DESCRIPTIONS.context,
+      inputSchema: contextBuildSurfaceSchema,
+    },
+    (args) => handleContext(args, ctx)
+  );
+
+  server.registerTool(
+    "gno_context_verify",
+    {
+      description: MCP_TOOL_DESCRIPTIONS.contextVerify,
+      inputSchema: contextVerifySurfaceSchema,
+    },
+    (args) => handleContextVerify(args, ctx)
+  );
+
   server.tool(
     "gno_search",
     MCP_TOOL_DESCRIPTIONS.search,

package/src/mcp/tools/remove-collection.ts

@@ -89,6 +89,8 @@ export function handleRemoveCollection(
         if (!mutationResult.ok) {
           throw mapConfigError(mutationResult.code, mutationResult.error);
         }
+        ctx.markContentMutation?.();
+        ctx.markIndexMutation?.();
 
         const result: RemoveCollectionResult = {
           removed: true,