@gmickel/gno 1.18.0 → 1.19.0

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,
@@ -96,6 +111,10 @@ export const MCP_WRITE_TOOL_NAMES = new Set([
   "gno_rename_note",
   "gno_move_note",
   "gno_duplicate_note",
+  "gno_trace_label",
+  "gno_trace_export",
+  "gno_trace_delete",
+  "gno_trace_purge",
 ]);
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -563,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({
@@ -847,9 +872,16 @@ export async function runTool<T>(
   const modelLease = ctx.acquireModelLease?.();
   try {
     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
@@ -995,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/').",
@@ -1052,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.",

package/src/mcp/tools/query.ts

@@ -26,6 +26,15 @@ import {
   normalizeContentTypes,
 } from "../../config";
 import { resolveDepthPolicy } from "../../core/depth-policy";
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
+import {
+  attachRetrievalTraceMetadata,
+  type RetrievalTraceSession,
+} from "../../core/retrieval-trace-session";
 import { normalizeStructuredQueryInput } from "../../core/structured-query";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
@@ -195,26 +204,79 @@ export function handleQuery(
           : undefined;
 
       const preset = getActivePreset(ctx.config);
-      const llm = new LlmAdapter(ctx.config);
-
-      // Resolve download policy from env (MCP has no CLI flags)
-      const policy = resolveDownloadPolicy(process.env, {});
-
-      // Non-TTY progress for MCP (periodic lines to stderr, not \r)
-      const downloadProgress = createNonTtyProgressRenderer();
 
       let embedPort: EmbeddingPort | null = null;
       let expandPort: GenerationPort | null = null;
       let rerankPort: RerankPort | null = null;
       let vectorIndex: VectorIndexPort | null = null;
+      let traceSession: RetrievalTraceSession | undefined;
       const embedUri = resolveModelUri(
         ctx.config,
         "embed",
         undefined,
         args.collection
       );
+      const hasStructuredModes = Boolean(queryModes?.length);
+      const depthPolicy = resolveDepthPolicy({
+        presetId: preset.id,
+        fast: args.fast,
+        thorough: args.thorough,
+        expand: args.expand,
+        rerank: args.rerank,
+        candidateLimit: args.candidateLimit,
+        hasStructuredModes,
+      });
+      const { noExpand, noRerank } = depthPolicy;
+      const expandUri =
+        !noExpand && !hasStructuredModes
+          ? resolveModelUri(ctx.config, "expand", undefined, args.collection)
+          : undefined;
+      const rerankUri = !noRerank
+        ? resolveModelUri(ctx.config, "rerank", undefined, args.collection)
+        : undefined;
+      const options = {
+        limit: args.limit ?? 5,
+        minScore: args.minScore,
+        collection: args.collection,
+        queryLanguageHint: args.lang,
+        intent: args.intent,
+        candidateLimit: depthPolicy.candidateLimit,
+        exclude: args.exclude,
+        since: args.since,
+        until: args.until,
+        categories: args.categories,
+        author: args.author,
+        noExpand,
+        noRerank,
+        graph: args.graph === true,
+        noGraph: args.noGraph || args.fast,
+        queryModes,
+        tagsAll: normalizeTagFilters(args.tagsAll),
+        tagsAny: normalizeTagFilters(args.tagsAny),
+      };
 
       try {
+        const traceStart = await startRetrievalTraceRequest({
+          store: ctx.store,
+          config: ctx.config,
+          query: queryText,
+          filters: retrievalTraceFilters(options),
+          pipeline: "hybrid",
+          indexName: ctx.indexName,
+          modelUris: [embedUri, expandUri, rerankUri].filter(
+            (value): value is string => Boolean(value)
+          ),
+        });
+        if (!traceStart.ok) throw new Error(traceStart.error.message);
+        traceSession = traceStart.value ?? undefined;
+        const llm = new LlmAdapter(ctx.config);
+
+        // Resolve download policy from env (MCP has no CLI flags)
+        const policy = resolveDownloadPolicy(process.env, {});
+
+        // Non-TTY progress for MCP (periodic lines to stderr, not \r)
+        const downloadProgress = createNonTtyProgressRenderer();
+
         // Create embedding port (for vector search) - optional
         const embedResult = await llm.createEmbeddingPort(embedUri, {
           policy,
@@ -224,41 +286,23 @@ export function handleQuery(
           embedPort = embedResult.value;
         }
 
-        const hasStructuredModes = Boolean(queryModes?.length);
-        const depthPolicy = resolveDepthPolicy({
-          presetId: preset.id,
-          fast: args.fast,
-          thorough: args.thorough,
-          expand: args.expand,
-          rerank: args.rerank,
-          candidateLimit: args.candidateLimit,
-          hasStructuredModes,
-        });
-        const { noExpand, noRerank } = depthPolicy;
-
         // Create expansion port - optional
-        if (!noExpand && !hasStructuredModes) {
-          const genResult = await llm.createExpansionPort(
-            resolveModelUri(ctx.config, "expand", undefined, args.collection),
-            {
-              policy,
-              onProgress: (progress) => downloadProgress("expand", progress),
-            }
-          );
+        if (expandUri) {
+          const genResult = await llm.createExpansionPort(expandUri, {
+            policy,
+            onProgress: (progress) => downloadProgress("expand", progress),
+          });
           if (genResult.ok) {
             expandPort = genResult.value;
           }
         }
 
         // Create rerank port - optional
-        if (!noRerank) {
-          const rerankResult = await llm.createRerankPort(
-            resolveModelUri(ctx.config, "rerank", undefined, args.collection),
-            {
-              policy,
-              onProgress: (progress) => downloadProgress("rerank", progress),
-            }
-          );
+        if (rerankUri) {
+          const rerankResult = await llm.createRerankPort(rerankUri, {
+            policy,
+            onProgress: (progress) => downloadProgress("rerank", progress),
+          });
           if (rerankResult.ok) {
             rerankPort = rerankResult.value;
           }
@@ -289,28 +333,9 @@ export function handleQuery(
           rerankPort,
         };
 
-        // Note: per spec, lang is a "hint" for query, not a filter
-        // Pass as queryLanguageHint to affect expansion prompt selection
-        // but NOT retrieval filtering (that would be options.lang)
         const result = await searchHybrid(deps, queryText, {
-          limit: args.limit ?? 5,
-          minScore: args.minScore,
-          collection: args.collection,
-          queryLanguageHint: args.lang, // Affects expansion prompt, not retrieval
-          intent: args.intent,
-          candidateLimit: depthPolicy.candidateLimit,
-          exclude: args.exclude,
-          since: args.since,
-          until: args.until,
-          categories: args.categories,
-          author: args.author,
-          noExpand,
-          noRerank,
-          graph: args.graph === true,
-          noGraph: args.noGraph || args.fast,
-          queryModes,
-          tagsAll: normalizeTagFilters(args.tagsAll),
-          tagsAny: normalizeTagFilters(args.tagsAny),
+          ...options,
+          traceSession,
         });
 
         if (!result.ok) {
@@ -320,15 +345,21 @@ export function handleQuery(
         // Enrich with absPath
         const enrichedResults = enrichWithAbsPath(result.value.results, ctx);
 
-        return {
-          ...result.value,
-          results: enrichedResults,
-          meta: {
-            ...result.value.meta,
-            // Add queryLanguage hint if provided
-            ...(args.lang ? { queryLanguage: args.lang } : {}),
+        return attachRetrievalTraceMetadata(
+          {
+            ...result.value,
+            results: enrichedResults,
+            meta: {
+              ...result.value.meta,
+              // Add queryLanguage hint if provided
+              ...(args.lang ? { queryLanguage: args.lang } : {}),
+            },
           },
-        };
+          traceSession
+        );
+      } catch (cause) {
+        await finishRetrievalTraceAfterError(traceSession, cause);
+        throw cause;
       } finally {
         if (embedPort) {
           await embedPort.dispose();

package/src/mcp/tools/search.ts

@@ -6,10 +6,17 @@
 
 import { join as pathJoin } from "node:path";
 
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type { SearchResult, SearchResults } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
+import { attachRetrievalTraceMetadata } from "../../core/retrieval-trace-session";
 import { searchBm25 } from "../../pipeline/search";
 import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
@@ -106,7 +113,7 @@ export function handleSearch(
         }
       }
 
-      const result = await searchBm25(ctx.store, args.query, {
+      const options = {
         limit: args.limit ?? 5,
         minScore: args.minScore,
         collection: args.collection,
@@ -119,19 +126,35 @@ export function handleSearch(
         author: args.author,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
-      });
-
-      if (!result.ok) {
-        throw new Error(result.error.message);
-      }
-
-      // Enrich with absPath
-      const enrichedResults = enrichWithAbsPath(result.value.results, ctx);
-
-      return {
-        ...result.value,
-        results: enrichedResults,
       };
+      let traceSession: RetrievalTraceSession | undefined;
+      try {
+        const traceStart = await startRetrievalTraceRequest({
+          store: ctx.store,
+          config: ctx.config,
+          query: args.query,
+          filters: retrievalTraceFilters(options),
+          pipeline: "bm25",
+          indexName: ctx.indexName,
+        });
+        if (!traceStart.ok) throw new Error(traceStart.error.message);
+        traceSession = traceStart.value ?? undefined;
+        const result = await searchBm25(ctx.store, args.query, {
+          ...options,
+          traceSession,
+        });
+        if (!result.ok) throw new Error(result.error.message);
+        return attachRetrievalTraceMetadata(
+          {
+            ...result.value,
+            results: enrichWithAbsPath(result.value.results, ctx),
+          },
+          traceSession
+        );
+      } catch (cause) {
+        await finishRetrievalTraceAfterError(traceSession, cause);
+        throw cause;
+      }
     },
     formatSearchResults
   );

package/src/mcp/tools/trace.ts

@@ -0,0 +1,143 @@
+/** MCP tools for explicit local retrieval-trace management. */
+
+import { z } from "zod";
+
+import type {
+  RetrievalTraceExportRequest,
+  RetrievalTraceLabelRequest,
+} from "../../core/retrieval-trace-management";
+import type { StoreResult } from "../../store/types";
+import type { ToolContext } from "../server";
+
+import { withWriteLock } from "../../core/file-lock";
+import { RetrievalTraceManagementService } from "../../core/retrieval-trace-management";
+import { runTool, type ToolResult } from "./index";
+
+export const traceListInputSchema = z.object({
+  limit: z.number().int().min(1).max(1000).default(50),
+  cursor: z.string().min(1).max(512).optional(),
+});
+
+export const traceShowInputSchema = z.object({
+  traceId: z.string().min(1).max(128),
+  detailLimit: z.number().int().min(1).max(5000).default(500),
+});
+
+export const traceLabelInputSchema = z.object({
+  traceId: z.string().min(1).max(128),
+  label: z.enum(["relevant", "irrelevant", "missing_expected"]),
+  targetRef: z.string().min(1).max(4096),
+  targetKind: z.enum(["document", "chunk", "span"]).optional(),
+  startLine: z.number().int().positive().optional(),
+  endLine: z.number().int().positive().optional(),
+  sourceHash: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .optional(),
+  docid: z.string().min(1).max(256).optional(),
+  idempotencyKey: z.string().min(1).max(256).optional(),
+});
+
+export const traceExportInputSchema = z.object({
+  traceIds: z.array(z.string().min(1).max(128)).min(1).max(1000),
+  format: z.literal("agentic-receipt").default("agentic-receipt"),
+});
+
+export const traceDeleteInputSchema = z.object({
+  traceId: z.string().min(1).max(128),
+});
+
+export const tracePurgeInputSchema = z.object({
+  confirm: z.literal(true),
+});
+
+const unwrap = <T>(result: StoreResult<T>): T => {
+  if (result.ok) return result.value;
+  throw new Error(`${result.error.code}: ${result.error.message}`);
+};
+
+const jsonText = (value: unknown): string => JSON.stringify(value, null, 2);
+
+const writeDisabled = (): never => {
+  throw new Error(
+    "WRITE_DISABLED: Trace mutations require gateway.enableWrite or --mcp-enable-write"
+  );
+};
+
+export const handleTraceList = (
+  args: z.infer<typeof traceListInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_trace_list",
+    async () =>
+      unwrap(await new RetrievalTraceManagementService(ctx.store).list(args)),
+    jsonText
+  );
+
+export const handleTraceShow = (
+  args: z.infer<typeof traceShowInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_trace_show",
+    async () =>
+      unwrap(
+        await new RetrievalTraceManagementService(ctx.store).show(
+          args.traceId,
+          { detailLimit: args.detailLimit }
+        )
+      ),
+    jsonText
+  );
+
+const runTraceWrite = <T>(
+  ctx: ToolContext,
+  name: string,
+  operation: (
+    service: RetrievalTraceManagementService
+  ) => Promise<StoreResult<T>>
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    name,
+    async () => {
+      if (!ctx.enableWrite) return writeDisabled();
+      return withWriteLock(ctx.writeLockPath, async () =>
+        unwrap(await operation(new RetrievalTraceManagementService(ctx.store)))
+      );
+    },
+    jsonText
+  );
+
+export const handleTraceLabel = (
+  args: z.infer<typeof traceLabelInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTraceWrite(ctx, "gno_trace_label", (service) =>
+    service.label(args as RetrievalTraceLabelRequest)
+  );
+
+export const handleTraceExport = (
+  args: z.infer<typeof traceExportInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTraceWrite(ctx, "gno_trace_export", (service) =>
+    service.export(args as RetrievalTraceExportRequest)
+  );
+
+export const handleTraceDelete = (
+  args: z.infer<typeof traceDeleteInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTraceWrite(ctx, "gno_trace_delete", (service) =>
+    service.delete(args.traceId)
+  );
+
+export const handleTracePurge = (
+  _args: z.infer<typeof tracePurgeInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTraceWrite(ctx, "gno_trace_purge", (service) => service.purge());