@gmickel/gno 2.5.1 → 2.7.0

package/src/mcp/tools/request-status.ts

@@ -0,0 +1,73 @@
+/**
+ * MCP request receipts: the caller's namespace, error rethrow, and the
+ * bounded `gno_request_status` lookup.
+ *
+ * @module src/mcp/tools/request-status
+ */
+
+import { z } from "zod";
+
+import type { ToolContext } from "../server";
+
+import {
+  formatRequestStatus,
+  LOCAL_OWNER_NAMESPACE,
+  readRequestStatus,
+  RequestReceiptError,
+  requestLedgerPath,
+} from "../../core/request-receipts";
+import { runTool, type ToolResult } from "./index";
+
+export const REQUEST_STATUS_MCP_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+export const requestIdInputSchema = z
+  .string()
+  .describe(
+    "Optional caller request ID (1-128 of A-Z a-z 0-9 . _ : -). Reuse the same ID when retrying the same write after a lost response; a new intent needs a new ID"
+  );
+
+export const requestStatusInputSchema = z.object({
+  requestId: z
+    .string()
+    .describe("Request ID previously sent with gno_capture or gno_remember"),
+});
+
+/** HTTP callers get their authorized identity's namespace; stdio is the local owner. */
+export function mcpRequestNamespace(ctx: ToolContext): string {
+  return ctx.getRequestNamespace?.() ?? LOCAL_OWNER_NAMESPACE;
+}
+
+/** Re-throw a request receipt error in the `CODE: message` shape runTool parses. */
+export function rethrowRequestError(error: unknown): never {
+  if (error instanceof RequestReceiptError) {
+    throw new Error(`${error.code}: ${error.message}`);
+  }
+  throw error;
+}
+
+export function handleRequestStatus(
+  args: z.infer<typeof requestStatusInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_request_status",
+    async () => {
+      try {
+        return await readRequestStatus({
+          ledgerPath: requestLedgerPath(ctx.store.getDbPath()),
+          namespace: mcpRequestNamespace(ctx),
+          requestId: args.requestId,
+        });
+      } catch (error) {
+        return rethrowRequestError(error);
+      }
+    },
+    formatRequestStatus
+  );
+}

package/src/mcp/tools/sessions.ts

@@ -0,0 +1,208 @@
+/**
+ * MCP session-archive tools: bounded status (including opt-in automation),
+ * import of owner-registered sources, and a run request for a configured
+ * automation profile. Thin adapters over the core sessions services. Hooks,
+ * schedules and source access are managed only by the local owner.
+ *
+ * Remote callers never discover host directories and never name paths:
+ * import accepts a registered source ID only. Import is registered only with
+ * `--enable-write`, and neither tool is part of the core profile.
+ *
+ * @module src/mcp/tools/sessions
+ */
+
+import { z } from "zod";
+
+import type { ToolContext } from "../server";
+
+import { runAutomationProfile } from "../../sessions/automation";
+import {
+  formatAutomationRunText,
+  formatImportReceiptText,
+  formatStatusText,
+} from "../../sessions/format";
+import { importInChildProcess } from "../../sessions/import-child";
+import { SessionsService } from "../../sessions/service";
+import {
+  MAX_IMPORT_LIMIT,
+  type SessionAutomationRunResult,
+  type SessionImportReceipt,
+  remoteSafeSessionsError,
+} from "../../sessions/types";
+import { runTool, type ToolResult } from "./index";
+
+export const sessionsStatusInputSchema = z.object({});
+
+export const sessionsImportInputSchema = z
+  .object({
+    sourceId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64)
+      .describe(
+        "ID of an owner-registered session source (see gno_sessions_status)"
+      ),
+    dryRun: z
+      .boolean()
+      .optional()
+      .describe("Parse and report without writing archive or index state"),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_IMPORT_LIMIT)
+      .optional()
+      .describe(
+        "Maximum changed units processed this call; the rest are deferred"
+      ),
+  })
+  .strict();
+
+export type SessionsImportToolInput = z.infer<typeof sessionsImportInputSchema>;
+
+export const sessionsAutomationRunInputSchema = z
+  .object({
+    profileId: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64)
+      .describe(
+        "ID of an owner-configured automation profile (see gno_sessions_status)"
+      ),
+  })
+  .strict();
+
+export type SessionsAutomationRunToolInput = z.infer<
+  typeof sessionsAutomationRunInputSchema
+>;
+
+export const SESSIONS_AUTOMATION_RUN_MCP_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+export const SESSIONS_STATUS_MCP_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+export const SESSIONS_IMPORT_MCP_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+function service(ctx: ToolContext): SessionsService {
+  return new SessionsService({
+    config: ctx.config,
+    configPath: ctx.actualConfigPath,
+    indexName: ctx.indexName,
+    store: ctx.store,
+  });
+}
+
+/** Re-throw as `CODE: message` (the shape runTool parses), never with host paths. */
+function rethrowSessionsError(error: unknown): never {
+  const typed = remoteSafeSessionsError(error);
+  throw new Error(`${typed.code}: ${typed.message}`);
+}
+
+export function handleSessionsStatus(ctx: ToolContext): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_sessions_status",
+    async () => {
+      try {
+        return await service(ctx).status();
+      } catch (error) {
+        return rethrowSessionsError(error);
+      }
+    },
+    formatStatusText
+  );
+}
+
+export function handleSessionsImport(
+  args: SessionsImportToolInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_sessions_import",
+    async () => {
+      if (!ctx.enableWrite) {
+        throw new Error(
+          "WRITE_DISABLED: gno_sessions_import requires --enable-write or GNO_MCP_ENABLE_WRITE=1"
+        );
+      }
+      let receipt: SessionImportReceipt;
+      try {
+        // A child process keeps this server answering during a long import.
+        receipt = await importInChildProcess({
+          config: ctx.config,
+          configPath: ctx.actualConfigPath,
+          indexName: ctx.indexName,
+          sourceId: args.sourceId,
+          dryRun: args.dryRun === true,
+          limit: args.limit,
+        });
+      } catch (error) {
+        return rethrowSessionsError(error);
+      }
+      if (!receipt.dryRun && receipt.lexical.collections.length > 0) {
+        ctx.markContentMutation?.();
+        ctx.markIndexMutation?.();
+      }
+      return receipt;
+    },
+    formatImportReceiptText
+  );
+}
+
+export function handleSessionsAutomationRun(
+  args: SessionsAutomationRunToolInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_sessions_automation_run",
+    async () => {
+      if (!ctx.enableWrite) {
+        throw new Error(
+          "WRITE_DISABLED: gno_sessions_automation_run requires --enable-write or GNO_MCP_ENABLE_WRITE=1"
+        );
+      }
+      let result: SessionAutomationRunResult;
+      try {
+        result = await runAutomationProfile(
+          {
+            configPath: ctx.actualConfigPath,
+            indexName: ctx.indexName,
+            store: ctx.store,
+            // A child process keeps this server answering during the run.
+            inChildProcess: true,
+          },
+          args.profileId,
+          { trigger: "manual" }
+        );
+      } catch (error) {
+        return rethrowSessionsError(error);
+      }
+      if (
+        result.receipts.some((receipt) => receipt.lexical.collections.length)
+      ) {
+        ctx.markContentMutation?.();
+        ctx.markIndexMutation?.();
+      }
+      return result;
+    },
+    formatAutomationRunText
+  );
+}

package/src/mcp/tools/status.ts

@@ -9,6 +9,7 @@ import type { ToolContext } from "../server";
 
 import { buildContentTypeBoostStatus } from "../../config/content-types";
 import { formatChunkingStatus } from "../../core/chunking-status";
+import { formatVectorPartitionLines } from "../../core/vector-partition-status";
 import { resolveModelUri } from "../../llm/registry";
 import { createStandaloneResidentStatus } from "../../serve/resident-status";
 import { runTool, type ToolResult } from "./index";
@@ -59,6 +60,9 @@ function formatStatus(status: IndexStatus): string {
   if (status.embeddingBacklog > 0) {
     lines.push(`Embedding backlog: ${status.embeddingBacklog} chunks`);
   }
+  lines.push(
+    ...formatVectorPartitionLines(status.vectorPartitions, status.vectorRuntime)
+  );
 
   const chunking = formatChunkingStatus(status.chunking);
   if (chunking) lines.push(chunking);

package/src/pipeline/hybrid.ts

@@ -33,7 +33,11 @@ import {
   withInferenceScope,
 } from "../llm/inference-scope";
 import { err, ok } from "../store/types";
-import { resolveVectorSearchIdentity } from "../store/vector/variant-search";
+import {
+  lexicalFallbackNotice,
+  resolveVectorSearchIdentity,
+  VECTOR_RUNTIME_INCOMPATIBLE,
+} from "../store/vector/variant-search";
 import { createChunkLookup } from "./chunk-lookup";
 import {
   attachAuxiliaryScoreMetadata,
@@ -284,7 +288,10 @@ async function searchVectorChunks(
     allowedMirrorHashes?: string[];
     eligibility?: VectorSearchOptions["eligibility"];
   }
-): Promise<{ ok: true; chunks: ChunkId[] } | { ok: false; reason: string }> {
+): Promise<
+  | { ok: true; chunks: ChunkId[] }
+  | { ok: false; reason: string; notice?: string }
+> {
   if (!vectorIndex.searchAvailable) {
     return { ok: false, reason: "vector_unavailable" };
   }
@@ -298,12 +305,19 @@ async function searchVectorChunks(
     return { ok: false, reason: "vector_embed_error" };
   }
 
+  const partition = await resolveVectorSearchIdentity(embedPort, vectorIndex);
+  if (partition.unavailable)
+    return {
+      ok: false,
+      reason: VECTOR_RUNTIME_INCOMPATIBLE,
+      notice: lexicalFallbackNotice(partition.unavailable),
+    };
   const queryEmbedding = new Float32Array(embedResult.value);
   const searchResult = await vectorIndex.searchNearest(
     queryEmbedding,
     options.limit,
     {
-      embeddingIdentity: resolveVectorSearchIdentity(embedPort),
+      embeddingIdentity: partition.identity,
       minScore: options.minScore,
       allowedMirrorHashes: options.allowedMirrorHashes,
       eligibility: options.eligibility,
@@ -630,6 +644,7 @@ async function searchHybridWithHydration(
   // Vector search
   let vecCount = 0;
   let vectorsUsed = false;
+  let vectorNotice: string | undefined;
   const vectorAvailable =
     (vectorIndex?.searchAvailable && embedPort !== null) ?? false;
   if (!vectorAvailable) {
@@ -662,8 +677,10 @@ async function searchHybridWithHydration(
         }
       );
 
-      if (!vectorResult.ok) counters.fallbackEvents.push(vectorResult.reason);
-      else vectorsUsed = true;
+      if (!vectorResult.ok) {
+        counters.fallbackEvents.push(vectorResult.reason);
+        vectorNotice = vectorResult.notice;
+      } else vectorsUsed = true;
       const vecChunks = vectorResult.ok ? vectorResult.chunks : [];
       vecCount = vecChunks.length;
       vectorTraceChunks.push(...vecChunks);
@@ -691,8 +708,14 @@ async function searchHybridWithHydration(
       );
 
       assertInferenceResult(embedResult);
+      const partition = embedResult.ok
+        ? await resolveVectorSearchIdentity(embedPort, vectorIndex)
+        : undefined;
       if (!embedResult.ok) {
         counters.fallbackEvents.push("vector_embed_error");
+      } else if (partition?.unavailable) {
+        counters.fallbackEvents.push(VECTOR_RUNTIME_INCOMPATIBLE);
+        vectorNotice = lexicalFallbackNotice(partition.unavailable);
       } else {
         if (embedResult.value.batchFailed) {
           counters.fallbackEvents.push("vector_embed_batch_fallback");
@@ -709,7 +732,7 @@ async function searchHybridWithHydration(
             new Float32Array(embedding),
             variant.limit,
             {
-              embeddingIdentity: resolveVectorSearchIdentity(embedPort),
+              embeddingIdentity: partition?.identity,
               allowedMirrorHashes: options.retrievalScope?.allowedMirrorHashes,
               eligibility: vectorEligibility,
             }
@@ -1390,6 +1413,11 @@ async function searchHybridWithHydration(
       trace: diagnoseTrace,
     },
   };
+  if (vectorNotice)
+    output.meta.warnings = [
+      ...(output.meta.warnings ?? []),
+      { code: VECTOR_RUNTIME_INCOMPATIBLE, message: vectorNotice },
+    ];
   const fallbackCodes = [...new Set(counters.fallbackEvents)].sort();
   const capabilityOutcomes = [
     { capability: "lexical_search", status: "used" as const },
@@ -1400,7 +1428,9 @@ async function searchHybridWithHydration(
             status: "failed" as const,
             reasonCode: fallbackCodes.includes("vector_embed_error")
               ? "vector_embed_error"
-              : "vector_search_error",
+              : vectorNotice
+                ? VECTOR_RUNTIME_INCOMPATIBLE
+                : "vector_search_error",
           }
         : { capability: "semantic_search", status: "used" as const }
       : {

package/src/pipeline/vsearch.ts

@@ -21,7 +21,10 @@ import {
 } from "../llm/inference-scope";
 import { getContentBatch } from "../store/content-batch";
 import { err, ok } from "../store/types";
-import { resolveVectorSearchIdentity } from "../store/vector/variant-search";
+import {
+  resolveVectorSearchIdentity,
+  vectorSearchUnavailableMessage,
+} from "../store/vector/variant-search";
 import { createChunkLookup } from "./chunk-lookup";
 import {
   applyContentTypeBoost,
@@ -144,7 +147,16 @@ async function searchVectorWithEmbeddingOwned(
 
   let embeddingIdentity;
   try {
-    embeddingIdentity = resolveVectorSearchIdentity(deps.embedPort);
+    const partition = await resolveVectorSearchIdentity(
+      deps.embedPort,
+      vectorIndex
+    );
+    if (partition.unavailable)
+      return err(
+        "VEC_SEARCH_UNAVAILABLE",
+        vectorSearchUnavailableMessage(partition.unavailable)
+      );
+    embeddingIdentity = partition.identity;
   } catch (cause) {
     return err(
       "QUERY_FAILED",