@gmickel/gno 1.18.0 → 1.20.0

package/src/mcp/tools/ask.ts

@@ -0,0 +1,228 @@
+/** MCP verified Ask tool over the shared closed-evidence application boundary. */
+
+import { z } from "zod";
+
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
+import type { QueryModeInput } from "../../pipeline/types";
+import type { ToolContext } from "../server";
+import type { ToolResult } from "./index";
+
+import { buildVerifiedAsk } from "../../app/verified-ask";
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
+import { attachRetrievalTraceMetadata } from "../../core/retrieval-trace-session";
+import { normalizeStructuredQueryInput } from "../../core/structured-query";
+import { resolveModelUri } from "../../llm/registry";
+import { answerTraceTerminalStatus } from "../../pipeline/answer";
+import { createMcpModelPorts, type McpModelPortFactory } from "./context";
+import { normalizeTagFilters, runTool } from "./index";
+
+const queryModeSchema = z
+  .object({
+    mode: z.enum(["term", "intent", "hyde"]),
+    text: z.string().trim().min(1),
+  })
+  .strict();
+
+export const askInputSchema = z
+  .object({
+    query: z.string().trim().min(1),
+    verify: z.literal(true),
+    collection: z.string().optional(),
+    limit: z.number().int().min(1).max(100).default(5),
+    minScore: z.number().min(0).max(1).optional(),
+    lang: z.string().optional(),
+    intent: z.string().optional(),
+    candidateLimit: z.number().int().min(1).max(100).optional(),
+    exclude: z.array(z.string()).optional(),
+    queryModes: z.array(queryModeSchema).optional(),
+    tagsAll: z.array(z.string()).optional(),
+    tagsAny: z.array(z.string()).optional(),
+    since: z.string().optional(),
+    until: z.string().optional(),
+    categories: z.array(z.string()).optional(),
+    author: z.string().optional(),
+    graph: z.boolean().optional(),
+    noGraph: z.boolean().optional(),
+    noRerank: z.boolean().optional(),
+    maxAnswerTokens: z.number().int().positive().optional(),
+    contextBudgetTokens: z.number().int().positive().optional(),
+    contextBudgetBytes: z.number().int().positive().optional(),
+  })
+  .strict();
+
+type AskInput = z.infer<typeof askInputSchema>;
+
+export interface HandleAskDependencies {
+  modelPortFactory?: McpModelPortFactory;
+}
+
+const exactSpan = (uri: string, startLine: number, endLine: number): string =>
+  `${uri}:L${startLine}${startLine === endLine ? "" : `-L${endLine}`}`;
+
+export const formatVerifiedAskReadable = (
+  result: Awaited<ReturnType<typeof buildVerifiedAsk>>
+): string => {
+  const numbers = new Map(
+    (result.citations ?? []).flatMap((citation, index) =>
+      citation.evidenceId ? [[citation.evidenceId, index + 1] as const] : []
+    )
+  );
+  const answer = (result.answer ?? "").replace(
+    /\[evidence:([a-f0-9]{64})\]/g,
+    (_marker, evidenceId: string) => {
+      const number = numbers.get(evidenceId);
+      return number === undefined ? "" : `[${number}]`;
+    }
+  );
+  const claims = result.verification?.claims;
+  const lines = [
+    answer || "No verified answer.",
+    "",
+    `Verification: ${claims?.answerStatus ?? "unavailable"}`,
+  ];
+  if (claims?.abstentionReason) {
+    lines.push(`Reason: ${claims.abstentionReason}`);
+  }
+  if (claims) {
+    lines.push(
+      `Claims: ${claims.coverage.supportedClaims}/${claims.coverage.totalClaims} supported`
+    );
+  }
+  const semantic = result.verification?.semantic;
+  if (semantic) {
+    lines.push(`Semantic verifier: ${semantic.status} (${semantic.reason})`);
+  }
+  for (const claim of claims?.claims ?? []) {
+    lines.push(`- ${claim.status}: ${claim.text}`);
+    for (const evidence of claim.evidence) {
+      lines.push(
+        `  ${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)} (${evidence.evidenceId})`
+      );
+    }
+  }
+  for (const gap of result.verification?.capsule.coverage.gaps ?? []) {
+    lines.push(`Gap: ${gap.facet} (${gap.code})`);
+  }
+  for (const facet of result.verification?.capsule.coverage.unresolvedFacets ??
+    []) {
+    lines.push(`Unresolved facet: ${facet}`);
+  }
+  for (const [name, state] of Object.entries(
+    result.verification?.capsule.retrieval.capabilityStates ?? {}
+  )) {
+    if (state.requested && state.outcome !== "used") {
+      lines.push(
+        `Capability: ${name} ${state.outcome}${state.fallbackReasons.length > 0 ? ` (${state.fallbackReasons.join(", ")})` : ""}`
+      );
+    }
+  }
+  for (const [index, citation] of (result.citations ?? []).entries()) {
+    const span =
+      citation.startLine === undefined || citation.endLine === undefined
+        ? citation.uri
+        : exactSpan(citation.uri, citation.startLine, citation.endLine);
+    lines.push(`[${index + 1}] ${span} (${citation.evidenceId ?? "unknown"})`);
+  }
+  return lines.join("\n");
+};
+
+export const handleAsk = (
+  args: AskInput,
+  context: ToolContext,
+  dependencies: HandleAskDependencies = {}
+): Promise<ToolResult> =>
+  runTool(
+    context,
+    "gno_ask",
+    async () => {
+      if (
+        args.collection &&
+        !context.collections.some(
+          (collection) => collection.name === args.collection
+        )
+      ) {
+        throw new Error(`Collection not found: ${args.collection}`);
+      }
+      const normalized = normalizeStructuredQueryInput(
+        args.query,
+        (args.queryModes ?? []) as QueryModeInput[]
+      );
+      if (!normalized.ok) throw new Error(normalized.error.message);
+      const query = normalized.value.query;
+      const options = {
+        ...args,
+        queryModes:
+          normalized.value.queryModes.length > 0
+            ? normalized.value.queryModes
+            : undefined,
+        tagsAll: normalizeTagFilters(args.tagsAll),
+        tagsAny: normalizeTagFilters(args.tagsAny),
+      };
+      let traceSession: RetrievalTraceSession | undefined;
+      let modelPorts: Awaited<ReturnType<typeof createMcpModelPorts>> | null =
+        null;
+      try {
+        const started = await startRetrievalTraceRequest({
+          store: context.store,
+          config: context.config,
+          query,
+          filters: retrievalTraceFilters(options),
+          pipeline: "ask",
+          indexName: context.indexName,
+          modelUris: [
+            resolveModelUri(
+              context.config,
+              "embed",
+              undefined,
+              args.collection
+            ),
+            resolveModelUri(
+              context.config,
+              "rerank",
+              undefined,
+              args.collection
+            ),
+            resolveModelUri(context.config, "gen", undefined, args.collection),
+          ],
+        });
+        if (!started.ok) throw new Error(started.error.message);
+        traceSession = started.value ?? undefined;
+        modelPorts = await createMcpModelPorts(
+          context,
+          args.collection,
+          dependencies.modelPortFactory,
+          { generation: true }
+        );
+        if (!modelPorts.genPort) {
+          throw new Error(
+            "Answer generation requested but no generation model is available"
+          );
+        }
+        const result = await buildVerifiedAsk(query, options, {
+          store: context.store,
+          config: context.config,
+          indexName: context.indexName,
+          vectorIndex: modelPorts.vectorIndex,
+          embedPort: modelPorts.embedPort,
+          rerankPort: modelPorts.rerankPort,
+          genPort: modelPorts.genPort,
+          traceSession,
+        });
+        const finished = await traceSession?.finish(
+          answerTraceTerminalStatus(result.citations)
+        );
+        if (finished && !finished.ok) throw new Error(finished.error.message);
+        return attachRetrievalTraceMetadata(result, traceSession);
+      } catch (error) {
+        await finishRetrievalTraceAfterError(traceSession, error);
+        throw error;
+      } finally {
+        await modelPorts?.dispose();
+      }
+    },
+    formatVerifiedAskReadable
+  );

package/src/mcp/tools/context.ts

@@ -1,7 +1,12 @@
 /** MCP Context Capsule tools over the shared application runtime. */
 
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type { ModelLease } from "../../llm/nodeLlamaCpp/lifecycle";
-import type { EmbeddingPort, RerankPort } from "../../llm/types";
+import type {
+  EmbeddingPort,
+  GenerationPort,
+  RerankPort,
+} from "../../llm/types";
 import type { VectorIndexPort } from "../../store/vector";
 import type { ToolContext } from "../server";
 import type { ToolResult } from "./index";
@@ -20,6 +25,10 @@ import {
   parseContextVerifySurfaceInput,
 } from "../../app/context-surface";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import {
+  finishRetrievalTraceAfterError,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
@@ -28,11 +37,15 @@ import { createVectorIndexPort } from "../../store/vector";
 interface ContextToolResultData {
   structuredContent: Record<string, unknown>;
   text: string;
+  traceId?: string;
 }
 
 const asToolResult = (data: ContextToolResultData): ToolResult => ({
   content: [{ type: "text", text: data.text }],
   structuredContent: data.structuredContent,
+  ...(data.traceId
+    ? { _meta: { gno: { retrievalTrace: { traceId: data.traceId } } } }
+    : {}),
 });
 
 const asToolError = (error: unknown): ToolResult => {
@@ -76,13 +89,15 @@ const runContextTool = async (
 
 interface McpModelPorts {
   embedPort: EmbeddingPort | null;
+  genPort: GenerationPort | null;
   rerankPort: RerankPort | null;
   vectorIndex: VectorIndexPort | null;
   dispose(): Promise<void>;
 }
 
-interface McpModelPortFactory {
+export interface McpModelPortFactory {
   createEmbeddingPort: LlmAdapter["createEmbeddingPort"];
+  createGenerationPort?: LlmAdapter["createGenerationPort"];
   createRerankPort: LlmAdapter["createRerankPort"];
   acquireModelLease?: LlmAdapter["acquireModelLease"];
 }
@@ -100,7 +115,8 @@ export const disposeContextModelOwners = async (
 export const createMcpModelPorts = async (
   context: ToolContext,
   collection?: string,
-  factoryOverride?: McpModelPortFactory
+  factoryOverride?: McpModelPortFactory,
+  options: { generation?: boolean } = {}
 ): Promise<McpModelPorts> => {
   const llm = new LlmAdapter(context.config);
   const factory = factoryOverride ?? llm;
@@ -116,6 +132,7 @@ export const createMcpModelPorts = async (
   let embedPort: EmbeddingPort | null = null;
   let ownedEmbedPort: EmbeddingPort | null = null;
   let rerankPort: RerankPort | null = null;
+  let genPort: GenerationPort | null = null;
   let vectorIndex: VectorIndexPort | null = null;
   try {
     const embedResult = await factory.createEmbeddingPort(embedUri, {
@@ -143,14 +160,26 @@ export const createMcpModelPorts = async (
       }
     );
     if (rerankResult.ok) rerankPort = rerankResult.value;
+    if (options.generation && factory.createGenerationPort) {
+      const genResult = await factory.createGenerationPort(
+        resolveModelUri(context.config, "gen", undefined, collection),
+        {
+          policy,
+          onProgress: (value) => progress("gen", value),
+        }
+      );
+      if (genResult.ok) genPort = genResult.value;
+    }
     return {
       embedPort,
+      genPort,
       rerankPort,
       vectorIndex,
       async dispose() {
         await disposeContextModelOwners(
-          [ownedEmbedPort, rerankPort].filter(
-            (port): port is EmbeddingPort | RerankPort => port !== null
+          [ownedEmbedPort, rerankPort, genPort].filter(
+            (port): port is EmbeddingPort | RerankPort | GenerationPort =>
+              port !== null
           ),
           lease
         );
@@ -158,8 +187,9 @@ export const createMcpModelPorts = async (
     };
   } catch (error) {
     await disposeContextModelOwners(
-      [ownedEmbedPort, rerankPort].filter(
-        (port): port is EmbeddingPort | RerankPort => port !== null
+      [ownedEmbedPort, rerankPort, genPort].filter(
+        (port): port is EmbeddingPort | RerankPort | GenerationPort =>
+          port !== null
       ),
       lease
     );
@@ -180,15 +210,50 @@ export const handleContext = (
       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;
+    const collection =
+      parsed.input.collections?.length === 1
+        ? parsed.input.collections[0]
+        : undefined;
+    const modelUris = useModels
+      ? [
+          resolveModelUri(context.config, "embed", undefined, collection),
+          resolveModelUri(context.config, "rerank", undefined, collection),
+        ]
+      : [];
+    let modelPorts: Awaited<ReturnType<typeof createMcpModelPorts>> | null =
+      null;
+    let traceSession: RetrievalTraceSession | undefined;
     try {
+      const traceStart = await startRetrievalTraceRequest({
+        store: context.store,
+        config: context.config,
+        query: parsed.input.query ?? parsed.input.goal,
+        goal: parsed.input.goal,
+        filters: {
+          limit: parsed.input.limit,
+          collection,
+          collections: [...(parsed.input.collections ?? [])].sort(),
+          lang: parsed.input.lang,
+          tagsAll: parsed.input.tagsAll,
+          tagsAny: parsed.input.tagsAny,
+          since: parsed.input.since,
+          until: parsed.input.until,
+          categories: parsed.input.categories,
+          author: parsed.input.author,
+          graph: parsed.input.graph,
+          candidateLimit: parsed.input.candidateLimit,
+          queryModes: parsed.input.queryModes,
+          uriPrefix: parsed.input.uriPrefix ?? undefined,
+        },
+        pipeline: "context",
+        indexName: context.indexName,
+        modelUris,
+      });
+      if (!traceStart.ok) throw new Error(traceStart.error.message);
+      traceSession = traceStart.value ?? undefined;
+      modelPorts = useModels
+        ? await createMcpModelPorts(context, collection)
+        : null;
       const capsule = await buildContextCapsule(parsed.input, {
         store: context.store,
         config: context.config,
@@ -196,14 +261,21 @@ export const handleContext = (
         vectorIndex: modelPorts?.vectorIndex ?? null,
         embedPort: modelPorts?.embedPort ?? null,
         rerankPort: modelPorts?.rerankPort ?? null,
+        traceSession,
       });
+      const finalized = await traceSession?.finish("completed");
+      if (finalized && !finalized.ok) throw new Error(finalized.error.message);
       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),
+        traceId: traceSession?.metadata()?.traceId,
       };
+    } catch (cause) {
+      await finishRetrievalTraceAfterError(traceSession, cause);
+      throw cause;
     } finally {
       await modelPorts?.dispose();
     }

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

@@ -16,8 +16,10 @@ 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 { askInputSchema, handleAsk } from "./ask";
 import { handleCapture } from "./capture";
 import { handleClearCollectionEmbeddings } from "./clear-collection-embeddings";
 import { handleContext, handleContextVerify } from "./context";
@@ -42,6 +44,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,
@@ -81,6 +97,7 @@ export const MCP_TOOL_DESCRIPTIONS = {
     "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.",
+  ask: "Generate one answer from a deterministic Context Capsule, verify every substantive claim against exact retained spans, and abstain unless support coverage is complete. Read-only; returns the Capsule, freshness receipt, claim verdicts, gaps, and evidence IDs.",
 } as const;
 
 /** Tool names whose execution mutates disk, config, or index state. */
@@ -96,6 +113,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 +584,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 +874,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
@@ -946,6 +980,13 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleContextVerify(args, ctx)
   );
 
+  server.tool(
+    "gno_ask",
+    MCP_TOOL_DESCRIPTIONS.ask,
+    askInputSchema.shape,
+    (args) => handleAsk(args, ctx)
+  );
+
   server.tool(
     "gno_search",
     MCP_TOOL_DESCRIPTIONS.search,
@@ -995,6 +1036,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 +1107,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.",