@gmickel/gno 1.17.0 → 1.19.0

package/spec/output-schemas/tags-list.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/tags-list@1.0",
+  "title": "GNO Tags List",
+  "description": "List of tags with document counts",
+  "type": "object",
+  "required": ["tags", "meta"],
+  "properties": {
+    "tags": {
+      "type": "array",
+      "description": "List of tags with counts",
+      "items": {
+        "type": "object",
+        "required": ["tag", "count"],
+        "properties": {
+          "tag": {
+            "type": "string",
+            "description": "Tag name (lowercase, alphanumeric with hyphens/dots/slashes)"
+          },
+          "count": {
+            "type": "integer",
+            "description": "Number of documents with this tag",
+            "minimum": 1
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": ["totalTags"],
+      "properties": {
+        "totalTags": {
+          "type": "integer",
+          "description": "Total number of unique tags",
+          "minimum": 0
+        },
+        "collection": {
+          "type": "string",
+          "description": "Collection filter applied"
+        },
+        "prefix": {
+          "type": "string",
+          "description": "Prefix filter applied"
+        }
+      }
+    }
+  }
+}

package/src/app/context-runtime-types.ts

@@ -2,6 +2,7 @@ import type { Config } from "../config/types";
 import type { ContextCapsuleV1 } from "../core/context-capsule";
 import type { ContextEvidenceCompilerDeps } from "../core/context-evidence";
 import type { ContextVerifierDeps } from "../core/context-verifier";
+import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { EmbeddingPort, RerankPort } from "../llm/types";
 import type { QueryModeInput } from "../pipeline/types";
 import type { StorePort } from "../store/types";
@@ -45,6 +46,8 @@ export interface ContextCapsuleRuntimeDeps {
   countTokens?: (accountingJson: string) => number;
   tokenizerFingerprint?: string | null;
   resolveCurrentRanks?: ContextVerifierDeps["resolveCurrentRanks"];
+  /** Optional non-canonical receipt session owned by the calling surface. */
+  traceSession?: RetrievalTraceSession;
 }
 
 export type ContextRuntimeErrorCode =

package/src/app/context-runtime.ts

@@ -89,7 +89,11 @@ export const buildContextCapsule = async (
             rerankPort: requestNoRerank ? null : (deps.rerankPort ?? null),
           },
           request.query,
-          { ...request, noRerank: requestNoRerank }
+          {
+            ...request,
+            noRerank: requestNoRerank,
+            traceSession: deps.traceSession,
+          }
         );
         if (!result.ok) {
           throw new ContextRuntimeError(
@@ -115,6 +119,16 @@ export const buildContextCapsule = async (
         : "No in-scope evidence was available for the Context Capsule"
     );
   }
+  const traceResult = await deps.traceSession?.recordContext(
+    plan.projection.value
+  );
+  if (traceResult && !traceResult.ok) {
+    throw new ContextRuntimeError(
+      "retrieval_failed",
+      `Trace recording failed: ${traceResult.error.message}`,
+      traceResult.error.cause
+    );
+  }
   return plan.projection.value;
 };
 

package/src/cli/commands/ask.ts

@@ -5,6 +5,8 @@
  * @module src/cli/commands/ask
  */
 
+import type { RetrievalTraceSurfaceMetadata } from "../../core/retrieval-trace-session";
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type {
   EmbeddingPort,
   GenerationPort,
@@ -12,12 +14,18 @@ import type {
 } from "../../llm/types";
 import type { AskOptions, AskResult, Citation } from "../../pipeline/types";
 
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
 import {
+  answerTraceTerminalStatus,
   generateGroundedAnswer,
-  processAnswerResult,
+  processAnswerResultWithTrace,
 } from "../../pipeline/answer";
 import { type HybridSearchDeps, searchHybrid } from "../../pipeline/hybrid";
 import {
@@ -55,7 +63,11 @@ export type AskCommandOptions = AskOptions & {
 };
 
 export type AskCommandResult =
-  | { success: true; data: AskResult }
+  | {
+      success: true;
+      data: AskResult;
+      metadata?: RetrievalTraceSurfaceMetadata;
+    }
   | { success: false; error: string };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -88,8 +100,50 @@ export async function ask(
   let expandPort: GenerationPort | null = null;
   let answerPort: GenerationPort | null = null;
   let rerankPort: RerankPort | null = null;
+  let traceSession: RetrievalTraceSession | undefined;
 
   try {
+    const answerRequested = Boolean(options.answer && !options.noAnswer);
+    const embedUri = resolveModelUri(
+      config,
+      "embed",
+      options.embedModel,
+      options.collection
+    );
+    const expandUri =
+      !options.noExpand && !options.queryModes?.length
+        ? resolveModelUri(
+            config,
+            "expand",
+            options.expandModel ?? options.genModel,
+            options.collection
+          )
+        : undefined;
+    const answerUri = answerRequested
+      ? resolveModelUri(config, "gen", options.genModel, options.collection)
+      : undefined;
+    const rerankUri = !options.noRerank
+      ? resolveModelUri(
+          config,
+          "rerank",
+          options.rerankModel,
+          options.collection
+        )
+      : undefined;
+    const traceStart = await startRetrievalTraceRequest({
+      store,
+      config,
+      query,
+      filters: retrievalTraceFilters({ ...options, limit }),
+      pipeline: "ask",
+      modelUris: [embedUri, expandUri, answerUri, rerankUri].filter(
+        (value): value is string => Boolean(value)
+      ),
+    });
+    if (!traceStart.ok) {
+      return { success: false, error: traceStart.error.message };
+    }
+    traceSession = traceStart.value ?? undefined;
     const llm = new LlmAdapter(config);
 
     // Resolve download policy from env/flags
@@ -105,12 +159,6 @@ export async function ask(
       : undefined;
 
     // Create embedding port
-    const embedUri = resolveModelUri(
-      config,
-      "embed",
-      options.embedModel,
-      options.collection
-    );
     const embedResult = await llm.createEmbeddingPort(embedUri, {
       policy,
       onProgress: downloadProgress
@@ -122,13 +170,7 @@ export async function ask(
     }
 
     // Create expansion port when expansion is enabled.
-    if (!options.noExpand && !options.queryModes?.length) {
-      const expandUri = resolveModelUri(
-        config,
-        "expand",
-        options.expandModel ?? options.genModel,
-        options.collection
-      );
+    if (expandUri) {
       const genResult = await llm.createExpansionPort(expandUri, {
         policy,
         onProgress: downloadProgress
@@ -141,14 +183,8 @@ export async function ask(
     }
 
     // Create answer generation port when answers are requested.
-    if (options.answer) {
-      const genUri = resolveModelUri(
-        config,
-        "gen",
-        options.genModel,
-        options.collection
-      );
-      const genResult = await llm.createGenerationPort(genUri, {
+    if (answerUri) {
+      const genResult = await llm.createGenerationPort(answerUri, {
         policy,
         onProgress: downloadProgress
           ? (progress) => downloadProgress("gen", progress)
@@ -160,13 +196,7 @@ export async function ask(
     }
 
     // Create rerank port (unless --fast or --no-rerank)
-    if (!options.noRerank) {
-      const rerankUri = resolveModelUri(
-        config,
-        "rerank",
-        options.rerankModel,
-        options.collection
-      );
+    if (rerankUri) {
       const rerankResult = await llm.createRerankPort(rerankUri, {
         policy,
         onProgress: downloadProgress
@@ -208,12 +238,14 @@ export async function ask(
       expandPort,
       rerankPort,
     };
-
-    // Check if answer generation is explicitly requested
-    const answerRequested = options.answer && !options.noAnswer;
-
     // Fail early if --answer is requested but no generation model available
     if (answerRequested && answerPort === null) {
+      await traceSession?.recordCapability(
+        "answer_generation",
+        "unavailable",
+        "model_unavailable"
+      );
+      await traceSession?.finish("failed");
       return {
         success: false,
         error:
@@ -239,9 +271,11 @@ export async function ask(
       noExpand: options.noExpand,
       noRerank: options.noRerank,
       candidateLimit: options.candidateLimit,
+      traceSession,
     });
 
     if (!searchResult.ok) {
+      await traceSession?.finish("failed");
       return { success: false, error: searchResult.error.message };
     }
 
@@ -261,6 +295,7 @@ export async function ask(
       answerRequested && answerPort !== null && results.length > 0;
 
     if (shouldGenerateAnswer && answerPort) {
+      await traceSession?.recordCapability("answer_generation", "attempted");
       const maxTokens = options.maxAnswerTokens ?? 512;
       const rawResult = await generateGroundedAnswer(
         { genPort: answerPort, store },
@@ -271,15 +306,25 @@ export async function ask(
 
       // Fail loudly if generation was requested but failed
       if (!rawResult) {
+        await traceSession?.recordCapability(
+          "answer_generation",
+          "failed",
+          "generation_failed"
+        );
+        await traceSession?.finish("failed");
         return {
           success: false,
           error:
             "Answer generation failed. The generation model may have encountered an error.",
         };
       }
+      await traceSession?.recordCapability("answer_generation", "used");
 
       // Process answer: extract valid citations, filter, renumber
-      const processed = processAnswerResult(rawResult);
+      const processed = await processAnswerResultWithTrace(
+        rawResult,
+        traceSession
+      );
       answer = processed.answer;
       citations = processed.citations;
       answerContext = processed.answerContext;
@@ -307,7 +352,32 @@ export async function ask(
       },
     };
 
-    return { success: true, data: askResult };
+    if (answerRequested) {
+      if (!answerGenerated) {
+        await traceSession?.recordCapability(
+          "answer_generation",
+          "unavailable",
+          "no_evidence"
+        );
+      }
+      const finalized = await traceSession?.finish(
+        answerTraceTerminalStatus(citations)
+      );
+      if (finalized && !finalized.ok) {
+        return { success: false, error: finalized.error.message };
+      }
+    }
+    return {
+      success: true,
+      data: askResult,
+      metadata: traceSession?.metadata(),
+    };
+  } catch (cause) {
+    await finishRetrievalTraceAfterError(traceSession, cause);
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : "Ask failed",
+    };
   } finally {
     if (embedPort) {
       await embedPort.dispose();

package/src/cli/commands/context-build.ts

@@ -1,6 +1,7 @@
 /** Context Capsule build command over the shared application runtime. */
 
 import type { ContextCapsuleBuildInput } from "../../app/context-runtime";
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type { EmbeddingPort, RerankPort } from "../../llm/types";
 import type { VectorIndexPort } from "../../store/vector";
 
@@ -10,6 +11,10 @@ import {
   canonicalBuiltContextCapsuleJson,
   validateContextCapsuleBuildInput,
 } from "../../app/context-runtime";
+import {
+  finishRetrievalTraceAfterError,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
 import { resolveModelUri } from "../../llm/registry";
@@ -77,13 +82,56 @@ export const contextBuild = async (
   let embedPort: EmbeddingPort | null = null;
   let rerankPort: RerankPort | null = null;
   let vectorIndex: VectorIndexPort | null = null;
+  let traceSession: RetrievalTraceSession | undefined;
   try {
     validateContextCapsuleBuildInput(
       { goal, ...options },
       options.indexName,
       config.collections.map((collection) => collection.name)
     );
+    const collection =
+      options.collections?.length === 1 ? options.collections[0] : undefined;
+    const embedUri =
+      options.depthPolicy === "fast"
+        ? undefined
+        : resolveModelUri(config, "embed", undefined, collection);
+    const rerankUri =
+      options.depthPolicy === "fast"
+        ? undefined
+        : resolveModelUri(config, "rerank", undefined, collection);
+    const traceStart = await startRetrievalTraceRequest({
+      store,
+      config,
+      query: options.query ?? goal,
+      goal,
+      filters: {
+        limit: options.limit,
+        collection,
+        collections: [...(options.collections ?? [])].sort(),
+        lang: options.lang,
+        tagsAll: options.tagsAll,
+        tagsAny: options.tagsAny,
+        since: options.since,
+        until: options.until,
+        categories: options.categories,
+        author: options.author,
+        graph: options.graph,
+        candidateLimit: options.candidateLimit,
+        queryModes: options.queryModes,
+        uriPrefix: options.uriPrefix ?? undefined,
+      },
+      pipeline: "context",
+      indexName: options.indexName,
+      modelUris: [embedUri, rerankUri].filter((value): value is string =>
+        Boolean(value)
+      ),
+    });
+    if (!traceStart.ok) throw new Error(traceStart.error.message);
+    traceSession = traceStart.value ?? undefined;
     if (options.depthPolicy !== "fast") {
+      if (!(embedUri && rerankUri)) {
+        throw new Error("Context model identities could not be resolved");
+      }
       const globals = getGlobals();
       const policy = resolveDownloadPolicy(process.env, {
         offline: globals.offline,
@@ -92,9 +140,6 @@ export const contextBuild = async (
       const progress = showProgress
         ? createThrottledProgressRenderer(createProgressRenderer())
         : undefined;
-      const collection =
-        options.collections?.length === 1 ? options.collections[0] : undefined;
-      const embedUri = resolveModelUri(config, "embed", undefined, collection);
       const embedResult = await llm.createEmbeddingPort(embedUri, {
         policy,
         onProgress: progress ? (value) => progress("embed", value) : undefined,
@@ -110,12 +155,6 @@ export const contextBuild = async (
           if (vectorResult.ok) vectorIndex = vectorResult.value;
         }
       }
-      const rerankUri = resolveModelUri(
-        config,
-        "rerank",
-        undefined,
-        collection
-      );
       const rerankResult = await llm.createRerankPort(rerankUri, {
         policy,
         onProgress: progress ? (value) => progress("rerank", value) : undefined,
@@ -132,12 +171,20 @@ export const contextBuild = async (
         vectorIndex,
         embedPort,
         rerankPort,
+        traceSession,
       }
     );
+    const finished = await traceSession?.finish("completed");
+    if (finished && !finished.ok) throw new Error(finished.error.message);
+    const traceMetadata = traceSession?.metadata();
+    if (traceMetadata) {
+      process.stderr.write(`Trace: ${traceMetadata.traceId}\n`);
+    }
     return options.format === "md"
       ? formatContextCapsuleMarkdown(capsule)
       : canonicalBuiltContextCapsuleJson(capsule);
   } catch (error) {
+    await finishRetrievalTraceAfterError(traceSession, error);
     if (error instanceof CliError) throw error;
     throw contextCliError(error);
   } finally {

package/src/cli/commands/daemon.ts

@@ -1,9 +1,18 @@
 import type { CollectionSyncResult } from "../../ingestion";
+import type { HttpGatewayOverrides } from "../../mcp/http-security";
 import type { BackgroundRuntimeResult } from "../../serve/background-runtime";
+import type { ResidentRuntime } from "../../serve/resident-runtime";
 
+import {
+  DEFAULT_HTTP_GATEWAY_PORT,
+  isHttpGatewayLoopbackBind,
+  resolveHttpGatewayConfig,
+} from "../../mcp/http-security";
 import { startBackgroundRuntime } from "../../serve/background-runtime";
+import { handleResidentStatus, handleStatus } from "../../serve/routes/api";
+import { createMcpHttpGateway } from "../../serve/routes/mcp";
 
-export interface DaemonOptions {
+export interface DaemonOptions extends HttpGatewayOverrides {
   configPath?: string;
   index?: string;
   offline?: boolean;
@@ -24,6 +33,8 @@ type DaemonLogger = {
 
 type DaemonDeps = {
   startBackgroundRuntime?: typeof startBackgroundRuntime;
+  createMcpHttpGateway?: typeof createMcpHttpGateway;
+  serve?: typeof Bun.serve;
   logger?: DaemonLogger;
 };
 
@@ -31,6 +42,18 @@ function formatCollectionSyncSummary(result: CollectionSyncResult): string {
   return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors`;
 }
 
+export function handleDaemonAppStatus(
+  runtime: ResidentRuntime,
+  host: string
+): Promise<Response> | Response {
+  if (!isHttpGatewayLoopbackBind(host)) {
+    return new Response(null, { status: 404 });
+  }
+  return handleStatus(runtime.ctxHolder.current, {
+    getResidentStatus: () => runtime.getStatus(),
+  });
+}
+
 function createSignalPromise(
   signal: AbortSignal | undefined,
   logger: DaemonLogger,
@@ -79,6 +102,7 @@ export async function daemon(
   const runtimeResult: BackgroundRuntimeResult = await (
     deps.startBackgroundRuntime ?? startBackgroundRuntime
   )({
+    mode: "daemon",
     configPath: options.configPath,
     index: options.index,
     requireCollections: true,
@@ -108,11 +132,52 @@ export async function daemon(
   }
 
   const { runtime } = runtimeResult;
+  const gatewayConfig = resolveHttpGatewayConfig(runtime.config.gateway, {
+    host: options.host,
+    port: options.port ?? DEFAULT_HTTP_GATEWAY_PORT,
+    tokenFile: options.tokenFile,
+    allowedHosts: options.allowedHosts,
+    allowedOrigins: options.allowedOrigins,
+    enableWrite: options.enableWrite,
+  });
+  let gateway: Awaited<ReturnType<typeof createMcpHttpGateway>> | undefined;
+  let server: ReturnType<typeof Bun.serve> | undefined;
   try {
+    gateway = await (deps.createMcpHttpGateway ?? createMcpHttpGateway)(
+      runtime as ResidentRuntime,
+      gatewayConfig
+    );
+    server = (deps.serve ?? Bun.serve)({
+      port: gatewayConfig.port,
+      hostname: gatewayConfig.host,
+      development: false,
+      routes: {
+        "/mcp": gateway.route,
+        "/api/status": {
+          GET: () =>
+            handleDaemonAppStatus(
+              runtime as ResidentRuntime,
+              gatewayConfig.host
+            ),
+        },
+        "/api/resident/status": {
+          GET: () =>
+            handleResidentStatus(() =>
+              (runtime as ResidentRuntime).getStatus()
+            ),
+        },
+      },
+    });
+    (runtime as Partial<ResidentRuntime>).setListenerPort?.(
+      server.port ?? gatewayConfig.port
+    );
     if (!options.quiet) {
       logger.log(
         `GNO daemon started for index "${options.index ?? "default"}" using ${runtime.config.collections.length} collection${runtime.config.collections.length === 1 ? "" : "s"}.`
       );
+      logger.log(
+        `MCP gateway listening at http://${gatewayConfig.host}:${server.port}/mcp`
+      );
       const watchState = runtime.watchService.getState();
       if (watchState.activeCollections.length > 0) {
         logger.log(`watching: ${watchState.activeCollections.join(", ")}`);
@@ -154,6 +219,8 @@ export async function daemon(
       error: error instanceof Error ? error.message : String(error),
     };
   } finally {
-    await runtime.dispose();
+    await Promise.allSettled([server?.stop(true)]);
+    await Promise.allSettled([gateway?.close()]);
+    await Promise.allSettled([runtime.dispose()]);
   }
 }

package/src/cli/commands/get.ts

@@ -5,6 +5,10 @@
  * @module src/cli/commands/get
  */
 
+import type {
+  RetrievalTraceSession,
+  RetrievalTraceSurfaceMetadata,
+} from "../../core/retrieval-trace-session";
 import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 import type { ParsedRef } from "./ref-parser";
 
@@ -17,6 +21,10 @@ import {
   getDocumentCapabilities,
   type DocumentCapabilities,
 } from "../../core/document-capabilities";
+import {
+  evidenceFromExactDocument,
+  RetrievalTraceSession as TraceSession,
+} from "../../core/retrieval-trace-session";
 import { parseRef } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -41,10 +49,18 @@ export interface GetCommandOptions {
   json?: boolean;
   /** Markdown output */
   md?: boolean;
+  /** Continue an open retrieval receipt returned by a prior query. */
+  traceId?: string;
+  /** Internal shared-session seam for in-process callers. */
+  traceSession?: RetrievalTraceSession;
 }
 
 export type GetResult =
-  | { success: true; data: GetResponse }
+  | {
+      success: true;
+      data: GetResponse;
+      metadata?: RetrievalTraceSurfaceMetadata;
+    }
   | { success: false; error: string; isValidation?: boolean };
 
 export interface GetResponse {
@@ -138,7 +154,53 @@ export async function get(
   const { store, config } = initResult;
 
   try {
-    return await fetchDocument(store, parsed, options, config, indexName);
+    let traceSession = options.traceSession;
+    if (!traceSession && options.traceId) {
+      const resumed = await TraceSession.resume({
+        store,
+        config: config.retrievalTraces,
+        traceId: options.traceId,
+      });
+      if (!resumed.ok) {
+        return { success: false, error: resumed.error.message };
+      }
+      traceSession = resumed.value ?? undefined;
+    }
+    const result = await fetchDocument(
+      store,
+      parsed,
+      options,
+      config,
+      indexName
+    );
+    if (!result.success || !traceSession) return result;
+    const lines = result.data.returnedLines ?? {
+      start: 1,
+      end: result.data.totalLines,
+    };
+    const evidence = evidenceFromExactDocument({
+      docid: result.data.docid,
+      uri: result.data.uri,
+      sourceHash: result.data.source.sourceHash,
+      mirrorHash: result.data.conversion?.mirrorHash,
+      content: result.data.content,
+      startLine: lines.start,
+      endLine: lines.end,
+    });
+    if (evidence) {
+      const getEvent = await traceSession.recordEvidence("get", [evidence]);
+      if (!getEvent.ok) {
+        return { success: false, error: getEvent.error.message };
+      }
+      const openEvent = await traceSession.recordEvidence("open", [evidence]);
+      if (!openEvent.ok) {
+        return { success: false, error: openEvent.error.message };
+      }
+    }
+    return {
+      ...result,
+      metadata: traceSession.metadata(),
+    };
   } finally {
     await store.close();
   }
@@ -375,7 +437,6 @@ export function formatGet(
     }
     return `Error: ${result.error}`;
   }
-
   const { data } = result;
 
   if (options.json) {