@gmickel/gno 1.17.0 → 1.19.0

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/get.ts

@@ -16,6 +16,11 @@ import {
 } from "../../core/document-capabilities";
 import { resolveEffectiveIndex } from "../../core/indexed-reference";
 import { parseRef } from "../../core/ref-parser";
+import {
+  attachRetrievalTraceMetadata,
+  evidenceFromExactDocument,
+  RetrievalTraceSession,
+} from "../../core/retrieval-trace-session";
 import { openScopedIndexStore } from "../../store/sqlite/scoped-index";
 import { runTool, type ToolResult } from "./index";
 
@@ -24,6 +29,7 @@ interface GetInput {
   fromLine?: number;
   lineCount?: number;
   lineNumbers?: boolean;
+  traceId?: string;
 }
 
 interface GetResponse {
@@ -165,6 +171,7 @@ export function handleGet(
 
         // Apply line range if specified
         let content = fullContent;
+        let exactContent = fullContent;
         let returnedLines: { start: number; end: number } | undefined;
 
         // lineNumbers defaults to true per spec
@@ -176,12 +183,14 @@ export function handleGet(
           if (startLine > totalLines) {
             // Return empty content for out-of-range request
             content = "";
+            exactContent = "";
             returnedLines = undefined;
           } else {
             const count = args.lineCount ?? totalLines - startLine + 1;
             const endLine = Math.min(startLine + count - 1, totalLines);
 
             const slicedLines = contentLines.slice(startLine - 1, endLine);
+            exactContent = slicedLines.join("\n");
 
             if (showLineNumbers) {
               content = slicedLines
@@ -242,7 +251,32 @@ export function handleGet(
           }),
         };
 
-        return response;
+        if (!args.traceId) return response;
+        const resumed = await RetrievalTraceSession.resume({
+          store: scoped.store,
+          config: ctx.config.retrievalTraces,
+          traceId: args.traceId,
+        });
+        if (!resumed.ok) throw new Error(resumed.error.message);
+        const traceSession = resumed.value;
+        if (!traceSession) return response;
+        const lines = returnedLines ?? { start: 1, end: totalLines };
+        const evidence = evidenceFromExactDocument({
+          docid: response.docid,
+          uri: response.uri,
+          sourceHash: response.source.sourceHash,
+          mirrorHash: response.conversion?.mirrorHash,
+          content: exactContent,
+          startLine: lines.start,
+          endLine: lines.end,
+        });
+        if (evidence) {
+          const got = await traceSession.recordEvidence("get", [evidence]);
+          if (!got.ok) throw new Error(got.error.message);
+          const opened = await traceSession.recordEvidence("open", [evidence]);
+          if (!opened.ok) throw new Error(opened.error.message);
+        }
+        return attachRetrievalTraceMetadata(response, traceSession);
       } finally {
         await scoped.close();
       }

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

@@ -16,6 +16,7 @@ import {
 } from "../../app/context-surface";
 import { CAPTURE_MAX_TEXT_BYTES } from "../../core/capture";
 import { NOTE_PRESETS, type NotePresetId } from "../../core/note-presets";
+import { RETRIEVAL_TRACE_METADATA } from "../../core/retrieval-trace-session";
 import { normalizeTag } from "../../core/tags";
 import { handleAddCollection } from "./add-collection";
 import { handleCapture } from "./capture";
@@ -42,6 +43,20 @@ import { handleRemoveCollection } from "./remove-collection";
 import { handleSearch } from "./search";
 import { handleStatus } from "./status";
 import { handleSync } from "./sync";
+import {
+  handleTraceDelete,
+  handleTraceExport,
+  handleTraceLabel,
+  handleTraceList,
+  handleTracePurge,
+  handleTraceShow,
+  traceDeleteInputSchema,
+  traceExportInputSchema,
+  traceLabelInputSchema,
+  traceListInputSchema,
+  tracePurgeInputSchema,
+  traceShowInputSchema,
+} from "./trace";
 import { handleVsearch } from "./vsearch";
 import {
   handleCreateFolder,
@@ -83,6 +98,25 @@ export const MCP_TOOL_DESCRIPTIONS = {
     "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",
+  "gno_trace_label",
+  "gno_trace_export",
+  "gno_trace_delete",
+  "gno_trace_purge",
+]);
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Shared Input Schemas
 // ─────────────────────────────────────────────────────────────────────────────
@@ -548,6 +582,12 @@ const getInputSchema = z.object({
     .boolean()
     .default(true)
     .describe("Include line numbers in output"),
+  traceId: z
+    .string()
+    .min(1)
+    .max(128)
+    .optional()
+    .describe("Continue an open retrieval trace returned by a search/query"),
 });
 
 const multiGetInputSchema = z.object({
@@ -829,11 +869,19 @@ 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());
+    const traceMetadata =
+      data !== null && typeof data === "object"
+        ? (data as Record<PropertyKey, unknown>)[RETRIEVAL_TRACE_METADATA]
+        : undefined;
     return {
       content: [{ type: "text", text: formatText(data) }],
       structuredContent: data as { [x: string]: unknown },
+      ...(traceMetadata
+        ? { _meta: { gno: { retrievalTrace: traceMetadata } } }
+        : {}),
     };
   } catch (e) {
     // Exception firewall: never throw, always return isError
@@ -846,6 +894,7 @@ export async function runTool<T>(
       structuredContent: parsedError,
     };
   } finally {
+    modelLease?.release();
     release();
   }
 }
@@ -869,8 +918,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 },
@@ -885,6 +935,8 @@ export async function runToolNoMutex<T>(
       content: [{ type: "text", text: `Error: ${message}` }],
       structuredContent: parsedError,
     };
+  } finally {
+    modelLease?.release();
   }
 }
 
@@ -975,6 +1027,20 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleStatus(args, ctx)
   );
 
+  server.tool(
+    "gno_trace_list",
+    "List bounded metadata-only summaries of private local retrieval traces. Raw replay queries are omitted from history.",
+    traceListInputSchema.shape,
+    (args) => handleTraceList(args, ctx)
+  );
+
+  server.tool(
+    "gno_trace_show",
+    "Inspect one bounded local retrieval trace. Replay-mode content is returned only for the explicitly requested trace.",
+    traceShowInputSchema.shape,
+    (args) => handleTraceShow(args, ctx)
+  );
+
   server.tool(
     "gno_list_tags",
     "List all tags with document counts. Use prefix to filter hierarchical tags (e.g. 'project/').",
@@ -1032,6 +1098,34 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
   );
 
   if (ctx.enableWrite) {
+    server.tool(
+      "gno_trace_label",
+      "Append an explicit relevant, irrelevant, or missing_expected judgment to a local retrieval trace.",
+      traceLabelInputSchema.shape,
+      (args) => handleTraceLabel(args, ctx)
+    );
+
+    server.tool(
+      "gno_trace_export",
+      "Build a deterministic local agentic receipt from one or more immutable terminal retrieval traces.",
+      traceExportInputSchema.shape,
+      (args) => handleTraceExport(args, ctx)
+    );
+
+    server.tool(
+      "gno_trace_delete",
+      "Delete one private local retrieval trace and all owned receipt records.",
+      traceDeleteInputSchema.shape,
+      (args) => handleTraceDelete(args, ctx)
+    );
+
+    server.tool(
+      "gno_trace_purge",
+      "Purge every private local retrieval trace receipt. Requires confirm=true.",
+      tracePurgeInputSchema.shape,
+      (args) => handleTracePurge(args, ctx)
+    );
+
     server.tool(
       "gno_capture",
       "Create a new document in a collection. Writes to disk. Does NOT auto-embed; run gno_index after to make it searchable via vector search.",