@gmickel/gno 1.17.0 → 1.19.0

package/src/cli/commands/models/pull.ts

@@ -35,6 +35,8 @@ export interface ModelsPullOptions {
   force?: boolean;
   /** Progress callback for UI (omit to disable progress) */
   onProgress?: (type: ModelType, progress: DownloadProgress) => void;
+  /** Stop before the next model and suppress subsequent work. */
+  signal?: AbortSignal;
 }
 
 export interface ModelPullResult {
@@ -52,6 +54,10 @@ export interface ModelsPullResult {
   skipped: number;
 }
 
+export interface ModelsPullDependencies {
+  cache?: Pick<ModelCache, "download" | "getCachedPath" | "isCached">;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -87,7 +93,8 @@ function getTypesToPull(options: ModelsPullOptions): ModelType[] {
  * Execute gno models pull command.
  */
 export async function modelsPull(
-  options: ModelsPullOptions = {}
+  options: ModelsPullOptions = {},
+  deps: ModelsPullDependencies = {}
 ): Promise<ModelsPullResult> {
   // Use provided config, or load from disk (use defaults if not initialized)
   let config = options.config;
@@ -98,7 +105,7 @@ export async function modelsPull(
   }
 
   const preset = getActivePreset(config);
-  const cache = new ModelCache(getModelsCachePath());
+  const cache = deps.cache ?? new ModelCache(getModelsCachePath());
   const types = getTypesToPull(options);
 
   const results: ModelPullResult[] = [];
@@ -106,6 +113,7 @@ export async function modelsPull(
   let skipped = 0;
 
   for (const type of types) {
+    if (options.signal?.aborted) break;
     const uri =
       type === "expand" ? (preset.expand ?? preset.gen) : preset[type];
 
@@ -133,8 +141,10 @@ export async function modelsPull(
       (progress) => {
         options.onProgress?.(type, progress);
       },
-      options.force
+      options.force,
+      options.signal
     );
+    if (options.signal?.aborted) break;
 
     if (result.ok) {
       results.push({

package/src/cli/commands/query.ts

@@ -5,6 +5,8 @@
  * @module src/cli/commands/query
  */
 
+import type { RetrievalTraceSurfaceMetadata } from "../../core/retrieval-trace-session";
+import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type {
   EmbeddingPort,
   GenerationPort,
@@ -16,6 +18,11 @@ import {
   fingerprintContentTypeRules,
   normalizeContentTypes,
 } from "../../config";
+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";
@@ -72,7 +79,11 @@ export interface QueryFormatOptions {
 }
 
 export type QueryResult =
-  | { success: true; data: SearchResults }
+  | {
+      success: true;
+      data: SearchResults;
+      metadata?: RetrievalTraceSurfaceMetadata;
+    }
   | { success: false; error: string };
 
 export type QueryDiagnoseCommandOptions = HybridSearchOptions & {
@@ -126,8 +137,47 @@ export async function query(
   let embedPort: EmbeddingPort | null = null;
   let expandPort: GenerationPort | null = null;
   let rerankPort: RerankPort | null = null;
+  let traceSession: RetrievalTraceSession | undefined;
 
   try {
+    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 rerankUri = !options.noRerank
+      ? resolveModelUri(
+          config,
+          "rerank",
+          options.rerankModel,
+          options.collection
+        )
+      : undefined;
+    const traceStart = await startRetrievalTraceRequest({
+      store,
+      config,
+      query: queryText,
+      filters: retrievalTraceFilters({ ...options, limit }),
+      pipeline: "hybrid",
+      indexName: options.indexName,
+      modelUris: [embedUri, expandUri, 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
@@ -143,12 +193,6 @@ export async function query(
       : undefined;
 
     // Create embedding port (for vector search)
-    const embedUri = resolveModelUri(
-      config,
-      "embed",
-      options.embedModel,
-      options.collection
-    );
     const embedResult = await llm.createEmbeddingPort(embedUri, {
       policy,
       onProgress: downloadProgress
@@ -161,13 +205,7 @@ export async function query(
 
     // Create expansion port - optional.
     // Skip when structured query modes are provided.
-    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
@@ -180,13 +218,7 @@ export async function query(
     }
 
     // Create rerank port - optional
-    if (!options.noRerank) {
-      const rerankUri = resolveModelUri(
-        config,
-        "rerank",
-        options.rerankModel,
-        options.collection
-      );
+    if (rerankUri) {
       const rerankResult = await llm.createRerankPort(rerankUri, {
         policy,
         onProgress: downloadProgress
@@ -228,19 +260,27 @@ export async function query(
       expandPort,
       rerankPort,
     };
-
     const result = await searchHybrid(deps, queryText, {
       ...options,
       limit,
+      traceSession,
     });
 
     if (!result.ok) {
+      await traceSession?.finish("failed");
       return { success: false, error: result.error.message };
     }
 
     return {
       success: true,
       data: decorateSearchResultsForIndex(result.value, options.indexName),
+      metadata: traceSession?.metadata(),
+    };
+  } catch (cause) {
+    await finishRetrievalTraceAfterError(traceSession, cause);
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : "Hybrid query failed",
     };
   } finally {
     if (embedPort) {
@@ -439,7 +479,6 @@ export function formatQuery(
         })
       : `Error: ${result.error}`;
   }
-
   // Output explain to stderr if present (async but best-effort)
   outputExplainToStderr(result.data);
 

package/src/cli/commands/replay.ts

@@ -0,0 +1,140 @@
+/** Local read-only retrieval replay command. */
+
+import type {
+  ReplayRetrievalTraceResult,
+  RetrievalReplayCandidate,
+} from "../../core/retrieval-trace-management";
+import type {
+  EmbeddingPort,
+  GenerationPort,
+  RerankPort,
+} from "../../llm/types";
+import type { VectorIndexPort } from "../../store/vector";
+
+import { RetrievalTraceManagementService } from "../../core/retrieval-trace-management";
+import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
+import { resolveDownloadPolicy } from "../../llm/policy";
+import { resolveModelUri } from "../../llm/registry";
+import { createVectorIndexPort } from "../../store/vector";
+import { CliError } from "../errors";
+import { initStore } from "./shared";
+
+export interface TraceReplayCommandOptions {
+  configPath?: string;
+  indexName?: string;
+  format?: "json" | "md";
+  offline?: boolean;
+}
+
+const unwrap = <T>(
+  value: { ok: true; value: T } | { ok: false; error: { message: string } }
+): T => {
+  if (value.ok) return value.value;
+  throw new CliError("RUNTIME", value.error.message);
+};
+
+const formatMarkdown = (value: ReplayRetrievalTraceResult): string => {
+  const lines = [
+    `# Retrieval replay \`${value.exportId}\``,
+    "",
+    `- Verdict: **${value.verdict}**`,
+    `- Recommendation: **${value.recommendation}**`,
+    `- Applied: **no**`,
+  ];
+  if (value.reason) lines.push(`- Reason: \`${value.reason}\``);
+  lines.push(
+    "",
+    "| Case | Status | Verdict | Baseline recall | Candidate recall |",
+    "|---|---|---|---:|---:|"
+  );
+  for (const item of value.cases) {
+    lines.push(
+      `| \`${item.caseId}\` | ${item.terminalStatus} | ${item.verdict} | ${item.metrics.baseline.recallAtK.toFixed(3)} | ${item.metrics.candidate.recallAtK.toFixed(3)} |`
+    );
+  }
+  return `${lines.join("\n")}\n`;
+};
+
+export const traceReplay = async (
+  exportId: string,
+  candidate: RetrievalReplayCandidate,
+  options: TraceReplayCommandOptions = {}
+): Promise<string> => {
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: false,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) throw new CliError("RUNTIME", initialized.error);
+  const { config, store } = initialized;
+  let embedPort: EmbeddingPort | null = null;
+  let expandPort: GenerationPort | null = null;
+  let rerankPort: RerankPort | null = null;
+  let vectorIndex: VectorIndexPort | null = null;
+  try {
+    const needsSemantic = candidate.type !== "bm25";
+    const embedUri = needsSemantic
+      ? resolveModelUri(config, "embed")
+      : undefined;
+    const expandUri =
+      candidate.type === "hybrid" &&
+      !candidate.noExpand &&
+      !candidate.queryModes?.length
+        ? resolveModelUri(config, "expand")
+        : undefined;
+    const rerankUri =
+      candidate.type === "hybrid" && !candidate.noRerank
+        ? resolveModelUri(config, "rerank")
+        : undefined;
+    const llm = new LlmAdapter(config);
+    const policy = resolveDownloadPolicy(process.env, {
+      offline: options.offline,
+    });
+    if (embedUri) {
+      const created = await llm.createEmbeddingPort(embedUri, { policy });
+      if (created.ok) embedPort = created.value;
+    }
+    if (expandUri) {
+      const created = await llm.createExpansionPort(expandUri, { policy });
+      if (created.ok) expandPort = created.value;
+    }
+    if (rerankUri) {
+      const created = await llm.createRerankPort(rerankUri, { policy });
+      if (created.ok) rerankPort = created.value;
+    }
+    if (embedPort && embedUri) {
+      const initializedEmbed = await embedPort.init();
+      if (initializedEmbed.ok) {
+        const created = await createVectorIndexPort(store.getRawDb(), {
+          model: embedUri,
+          dimensions: embedPort.dimensions(),
+        });
+        if (created.ok) vectorIndex = created.value;
+      }
+    }
+    const replayed = await new RetrievalTraceManagementService(store).replay(
+      { exportId, candidate },
+      {
+        config,
+        vectorIndex,
+        embedPort,
+        expandPort,
+        rerankPort,
+        indexName: options.indexName,
+        modelUris: [embedUri, expandUri, rerankUri].filter(
+          (value): value is string => Boolean(value)
+        ),
+      }
+    );
+    const value = unwrap(replayed);
+    return options.format === "md"
+      ? formatMarkdown(value)
+      : `${JSON.stringify(value, null, 2)}\n`;
+  } finally {
+    await embedPort?.dispose();
+    await expandPort?.dispose();
+    await rerankPort?.dispose();
+    await store.close();
+  }
+};

package/src/cli/commands/search.ts

@@ -5,8 +5,16 @@
  * @module src/cli/commands/search
  */
 
+import type {
+  RetrievalTraceSession,
+  RetrievalTraceSurfaceMetadata,
+} from "../../core/retrieval-trace-session";
 import type { SearchOptions, SearchResults } from "../../pipeline/types";
 
+import {
+  finishRetrievalTraceAfterError,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { searchBm25 } from "../../pipeline/search";
 import {
   type FormatOptions,
@@ -38,7 +46,11 @@ export type SearchCommandOptions = SearchOptions & {
 };
 
 export type SearchResult =
-  | { success: true; data: SearchResults }
+  | {
+      success: true;
+      data: SearchResults;
+      metadata?: RetrievalTraceSurfaceMetadata;
+    }
   | { success: false; error: string; isValidation?: boolean };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -68,15 +80,42 @@ export async function search(
     return { success: false, error: initResult.error };
   }
 
-  const { store } = initResult;
+  const { store, config } = initResult;
+  let traceSession: RetrievalTraceSession | undefined;
 
   try {
+    const started = await startRetrievalTraceRequest({
+      store,
+      config,
+      query,
+      filters: {
+        limit,
+        collection: options.collection,
+        lang: options.lang,
+        full: options.full,
+        lineNumbers: options.lineNumbers,
+        tagsAll: options.tagsAll,
+        tagsAny: options.tagsAny,
+        since: options.since,
+        until: options.until,
+        categories: options.categories,
+        author: options.author,
+        intent: options.intent,
+        exclude: options.exclude,
+      },
+      pipeline: "bm25",
+      indexName: options.indexName,
+    });
+    if (!started.ok) return { success: false, error: started.error.message };
+    traceSession = started.value ?? undefined;
     const result = await searchBm25(store, query, {
       ...options,
       limit,
+      traceSession,
     });
 
     if (!result.ok) {
+      await traceSession?.finish("failed");
       // Map INVALID_INPUT to validation error for proper exit code
       const isValidation = result.error.code === "INVALID_INPUT";
       return {
@@ -89,6 +128,13 @@ export async function search(
     return {
       success: true,
       data: decorateSearchResultsForIndex(result.value, options.indexName),
+      metadata: traceSession?.metadata(),
+    };
+  } catch (cause) {
+    await finishRetrievalTraceAfterError(traceSession, cause);
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : "Search failed",
     };
   } finally {
     await store.close();
@@ -135,7 +181,6 @@ export function formatSearch(
         })
       : `Error: ${result.error}`;
   }
-
   const formatOpts: FormatOptions = {
     format: getFormatType(options),
     full: options.full,

package/src/cli/commands/shared.ts

@@ -44,6 +44,8 @@ export interface InitStoreOptions {
   collection?: string;
   /** Sync collections/contexts from config into DB on open */
   syncConfig?: boolean;
+  /** Permit management commands that only need an existing index database */
+  allowEmptyCollections?: boolean;
 }
 
 /**
@@ -81,7 +83,7 @@ export async function initStore(
     }
   }
 
-  if (collections.length === 0) {
+  if (collections.length === 0 && !options.allowEmptyCollections) {
     return {
       ok: false,
       error: "No collections configured. Run: gno collection add <path>",

package/src/cli/commands/status.ts

@@ -15,6 +15,7 @@ import { buildActivationStatus } from "../../core/activation-status";
 import { ModelCache } from "../../llm/cache";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
 import { getConnectorVerificationTargets } from "../../serve/connectors";
+import { createStandaloneResidentStatus } from "../../serve/resident-status";
 import { SqliteAdapter } from "../../store/sqlite/adapter";
 
 /**
@@ -277,6 +278,7 @@ export function formatStatus(
     const s = result.status;
     return JSON.stringify(
       {
+        resident: createStandaloneResidentStatus("direct-cli"),
         indexName: s.indexName,
         configPath: s.configPath,
         dbPath: s.dbPath,

package/src/cli/commands/trace.ts

@@ -0,0 +1,200 @@
+/** Local retrieval-trace inspection, feedback, export, and deletion commands. */
+
+import type {
+  RetrievalTraceDeleteResult,
+  RetrievalTraceDetail,
+  RetrievalTraceLabelRequest,
+  RetrievalTraceLabelResult,
+  RetrievalTraceListResult,
+  RetrievalTracePurgeResult,
+} from "../../core/retrieval-trace-management";
+import type { StoreResult } from "../../store/types";
+
+import { atomicWrite } from "../../core/file-ops";
+import { RetrievalTraceManagementService } from "../../core/retrieval-trace-management";
+import { CliError } from "../errors";
+import { initStore } from "./shared";
+
+export type TraceOutputFormat = "json" | "md";
+
+interface TraceCommandOptions {
+  configPath?: string;
+  indexName?: string;
+  format?: TraceOutputFormat;
+}
+
+interface TraceExportOptions extends TraceCommandOptions {
+  output?: string;
+  exportFormat?: "agentic-receipt" | "qrels";
+}
+
+const unwrapTraceResult = <T>(result: StoreResult<T>): T => {
+  if (result.ok) {
+    return result.value;
+  }
+  throw new CliError(
+    result.error.code === "INVALID_INPUT" ? "VALIDATION" : "RUNTIME",
+    result.error.message,
+    { details: { traceCode: result.error.code } }
+  );
+};
+
+const withTraceService = async <T>(
+  options: TraceCommandOptions,
+  operation: (service: RetrievalTraceManagementService) => Promise<T>
+): Promise<T> => {
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: false,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) {
+    throw new CliError("RUNTIME", initialized.error);
+  }
+  try {
+    return await operation(
+      new RetrievalTraceManagementService(initialized.store)
+    );
+  } finally {
+    await initialized.store.close();
+  }
+};
+
+const json = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
+
+const formatListMarkdown = (value: RetrievalTraceListResult): string => {
+  const lines = [
+    "# Retrieval traces",
+    "",
+    "| Trace | Status | Mode | Created |",
+    "|---|---|---|---|",
+  ];
+  for (const trace of value.traces) {
+    lines.push(
+      `| \`${trace.traceId}\` | ${trace.status} | ${trace.redactionMode} | ${new Date(trace.createdAtMs).toISOString()} |`
+    );
+  }
+  if (value.traces.length === 0) {
+    lines.push("| — | — | — | — |");
+  }
+  if (value.nextCursor) {
+    lines.push("", `Next cursor: \`${value.nextCursor}\``);
+  }
+  return `${lines.join("\n")}\n`;
+};
+
+const formatDetailMarkdown = (value: RetrievalTraceDetail): string => {
+  const trace = value.trace;
+  const lines = [
+    `# Retrieval trace \`${trace.traceId}\``,
+    "",
+    `- Status: **${trace.status}**`,
+    `- Redaction: **${trace.redactionMode}**`,
+    `- Replay capable: **${trace.replayCapable ? "yes" : "no"}**`,
+    `- Created: ${new Date(trace.createdAtMs).toISOString()}`,
+    `- Updated: ${new Date(trace.updatedAtMs).toISOString()}`,
+    "",
+    "## Records",
+    "",
+    `- Runs: ${value.runs.length}`,
+    `- Events: ${value.events.length}`,
+    `- Judgments: ${value.judgments.length}`,
+    `- Exports: ${value.exports.length}`,
+  ];
+  const truncatedSections = Object.entries(value.truncated)
+    .filter(([, truncated]) => truncated)
+    .map(([section]) => section);
+  if (truncatedSections.length > 0) {
+    lines.push(
+      "",
+      `Detail truncated: ${truncatedSections.join(", ")}. Request a larger bounded detail limit.`
+    );
+  }
+  return `${lines.join("\n")}\n`;
+};
+
+const formatMutationMarkdown = (
+  heading: string,
+  value:
+    | RetrievalTraceLabelResult
+    | RetrievalTraceDeleteResult
+    | RetrievalTracePurgeResult
+): string =>
+  `# ${heading}\n\n\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\`\n`;
+
+export const traceList = async (
+  input: { limit?: number; cursor?: string },
+  options: TraceCommandOptions = {}
+): Promise<string> => {
+  const value = await withTraceService(options, async (service) =>
+    unwrapTraceResult(await service.list(input))
+  );
+  return options.format === "md" ? formatListMarkdown(value) : json(value);
+};
+
+export const traceShow = async (
+  traceId: string,
+  input: { detailLimit?: number },
+  options: TraceCommandOptions = {}
+): Promise<string> => {
+  const value = await withTraceService(options, async (service) =>
+    unwrapTraceResult(await service.show(traceId, input))
+  );
+  return options.format === "md" ? formatDetailMarkdown(value) : json(value);
+};
+
+export const traceLabel = async (
+  input: RetrievalTraceLabelRequest,
+  options: TraceCommandOptions = {}
+): Promise<string> => {
+  const value = await withTraceService(options, async (service) =>
+    unwrapTraceResult(await service.label(input))
+  );
+  return options.format === "md"
+    ? formatMutationMarkdown("Retrieval trace judgment", value)
+    : json(value);
+};
+
+export const traceExport = async (
+  traceIds: string[],
+  options: TraceExportOptions = {}
+): Promise<string> => {
+  const value = await withTraceService(options, async (service) =>
+    unwrapTraceResult(
+      await service.export({
+        traceIds,
+        format: options.exportFormat ?? "agentic-receipt",
+      })
+    )
+  );
+  const artifact = json(value.artifact);
+  if (options.output) {
+    await atomicWrite(options.output, artifact);
+    return "";
+  }
+  return json(value);
+};
+
+export const traceDelete = async (
+  traceId: string,
+  options: TraceCommandOptions = {}
+): Promise<string> => {
+  const value = await withTraceService(options, async (service) =>
+    unwrapTraceResult(await service.delete(traceId))
+  );
+  return options.format === "md"
+    ? formatMutationMarkdown("Retrieval trace deleted", value)
+    : json(value);
+};
+
+export const tracePurge = async (
+  options: TraceCommandOptions = {}
+): Promise<string> => {
+  const value = await withTraceService(options, async (service) =>
+    unwrapTraceResult(await service.purge())
+  );
+  return options.format === "md"
+    ? formatMutationMarkdown("Retrieval traces purged", value)
+    : json(value);
+};