@gmickel/gno 1.18.0 → 1.20.0

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());

package/src/mcp/tools/vsearch.ts

@@ -6,11 +6,21 @@
 
 import { join as pathJoin } from "node:path";
 
+import type { EmbeddingPort } from "../../llm/types";
 import type { SearchResult, SearchResults } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
+import {
+  attachRetrievalTraceMetadata,
+  type RetrievalTraceSession,
+} from "../../core/retrieval-trace-session";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
@@ -125,29 +135,55 @@ export function handleVsearch(
         undefined,
         args.collection
       );
+      const options = {
+        limit: args.limit ?? 5,
+        minScore: args.minScore,
+        collection: args.collection,
+        intent: args.intent,
+        exclude: args.exclude,
+        since: args.since,
+        until: args.until,
+        categories: args.categories,
+        author: args.author,
+        tagsAll: normalizeTagFilters(args.tagsAll),
+        tagsAny: normalizeTagFilters(args.tagsAny),
+      };
+      let traceSession: RetrievalTraceSession | undefined;
+      const traceStart = await startRetrievalTraceRequest({
+        store: ctx.store,
+        config: ctx.config,
+        query: args.query,
+        filters: retrievalTraceFilters(options),
+        pipeline: "vector",
+        indexName: ctx.indexName,
+        modelUris: [modelUri],
+      });
+      if (!traceStart.ok) throw new Error(traceStart.error.message);
+      traceSession = traceStart.value ?? undefined;
 
-      // Resolve download policy from env (MCP has no CLI flags)
-      const policy = resolveDownloadPolicy(process.env, {});
+      let embedPort: EmbeddingPort | null = null;
 
-      // Non-TTY progress for MCP (periodic lines to stderr, not \r)
-      const downloadProgress = createNonTtyProgressRenderer();
+      try {
+        // Resolve download policy from env (MCP has no CLI flags)
+        const policy = resolveDownloadPolicy(process.env, {});
 
-      // Create LLM adapter for embeddings
-      const llm = new LlmAdapter(ctx.config);
-      const embedResult = await llm.createEmbeddingPort(modelUri, {
-        policy,
-        onProgress: (progress) => downloadProgress("embed", progress),
-      });
-      if (!embedResult.ok) {
-        throw new Error(
-          `Failed to load embedding model: ${embedResult.error.message}. ` +
-            "Ensure models are downloaded with: gno models pull"
-        );
-      }
+        // Non-TTY progress for MCP (periodic lines to stderr, not \r)
+        const downloadProgress = createNonTtyProgressRenderer();
 
-      const embedPort = embedResult.value;
+        // Create LLM adapter for embeddings
+        const llm = new LlmAdapter(ctx.config);
+        const embedResult = await llm.createEmbeddingPort(modelUri, {
+          policy,
+          onProgress: (progress) => downloadProgress("embed", progress),
+        });
+        if (!embedResult.ok) {
+          throw new Error(
+            `Failed to load embedding model: ${embedResult.error.message}. ` +
+              "Ensure models are downloaded with: gno models pull"
+          );
+        }
+        embedPort = embedResult.value;
 
-      try {
         // Embed query with contextual formatting
         const queryEmbedResult = await embedPort.embed(
           formatQueryForEmbedding(args.query, embedPort.modelUri)
@@ -196,17 +232,8 @@ export function handleVsearch(
           args.query,
           queryEmbedding,
           {
-            limit: args.limit ?? 5,
-            minScore: args.minScore,
-            collection: args.collection,
-            intent: args.intent,
-            exclude: args.exclude,
-            since: args.since,
-            until: args.until,
-            categories: args.categories,
-            author: args.author,
-            tagsAll: normalizeTagFilters(args.tagsAll),
-            tagsAny: normalizeTagFilters(args.tagsAny),
+            ...options,
+            traceSession,
           }
         );
 
@@ -217,17 +244,23 @@ export function handleVsearch(
         // Enrich with absPath
         const enrichedResults = enrichWithAbsPath(result.value.results, ctx);
 
-        return {
-          ...result.value,
-          results: enrichedResults,
-          meta: {
-            ...result.value.meta,
-            // Add queryLanguage hint if provided (per spec, lang is a hint for vsearch)
-            ...(args.lang ? { queryLanguage: args.lang } : {}),
+        return attachRetrievalTraceMetadata(
+          {
+            ...result.value,
+            results: enrichedResults,
+            meta: {
+              ...result.value.meta,
+              // Add queryLanguage hint if provided (per spec, lang is a hint for vsearch)
+              ...(args.lang ? { queryLanguage: args.lang } : {}),
+            },
           },
-        };
+          traceSession
+        );
+      } catch (cause) {
+        await finishRetrievalTraceAfterError(traceSession, cause);
+        throw cause;
       } finally {
-        await embedPort.dispose();
+        await embedPort?.dispose();
       }
     },
     formatSearchResults