@gmickel/gno 1.27.1 → 1.29.0

package/src/mcp/tools/egress.ts

@@ -0,0 +1,247 @@
+/** MCP collection egress policy and content-free audit management tools. */
+
+import { z } from "zod";
+
+import type { ToolContext } from "../server";
+
+import { projectCollectionEgressPolicy } from "../../core/collection-egress-policy-projection";
+import { CollectionEgressPolicyService } from "../../core/collection-egress-policy-service";
+import { applyConfigChange } from "../../core/config-mutation";
+import { EgressAuditService } from "../../core/egress-audit";
+import { runTool, type ToolResult } from "./index";
+
+const policy = z.enum(["local_only", "lan", "remote"]);
+
+export const egressPolicyGetInputSchema = z
+  .object({
+    collection: z.string().min(1).max(64),
+  })
+  .strict();
+
+export const egressPolicySetInputSchema = z
+  .object({
+    collection: z.string().min(1).max(64),
+    policy,
+    confirmation: z
+      .object({
+        collection: z.string().min(1).max(64),
+        currentPolicy: policy,
+        currentRevision: z.number().int().nonnegative(),
+        targetPolicy: policy,
+        acknowledged: z.literal(true),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export const egressCheckInputSchema = z
+  .object({
+    collections: z.array(z.string().min(1).max(64)).min(1).max(64).optional(),
+    action: z.enum([
+      "retrieve",
+      "serve",
+      "publish",
+      "remote_inference",
+      "export",
+      "clip_write",
+    ]),
+    destinationZone: z.enum(["local_process", "loopback", "lan", "remote"]),
+    caller: z
+      .object({
+        authenticated: z.boolean(),
+        operationAuthorized: z.boolean(),
+      })
+      .strict(),
+    contentClass: z.enum([
+      "source",
+      "snippet",
+      "metadata",
+      "attachment",
+      "embedding",
+      "capsule",
+      "audit_log",
+      "retrieval_trace",
+    ]),
+    partialResults: z.enum(["deny", "explicit"]).default("deny"),
+  })
+  .strict();
+
+export const egressAuditListInputSchema = z
+  .object({
+    limit: z.number().int().min(1).max(1000).default(100),
+    cursor: z.string().min(1).max(512).optional(),
+  })
+  .strict();
+
+export const egressAuditIdInputSchema = z
+  .object({
+    auditId: z.string().min(1).max(128),
+  })
+  .strict();
+
+export const egressAuditStatusInputSchema = z.object({}).strict();
+
+export const egressAuditPurgeInputSchema = z
+  .object({
+    confirm: z.literal(true),
+  })
+  .strict();
+
+const json = (value: unknown): string => JSON.stringify(value, null, 2);
+
+const unwrap = <T>(
+  result:
+    | { ok: true; value: T }
+    | { ok: false; error: { code: string; message: string } }
+): T => {
+  if (result.ok) return result.value;
+  throw new Error(`${result.error.code}: ${result.error.message}`);
+};
+
+const requireWrite = (ctx: ToolContext): void => {
+  if (!ctx.enableWrite) {
+    throw new Error(
+      "WRITE_DISABLED: Egress policy and audit mutations require gateway.enableWrite or --mcp-enable-write"
+    );
+  }
+};
+
+export const handleEgressPolicyGet = (
+  args: z.infer<typeof egressPolicyGetInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_egress_policy_get",
+    async () => {
+      const state = new CollectionEgressPolicyService({
+        getConfig: () => ctx.config,
+      }).get(args.collection);
+      if (!state.ok) throw new Error(`${state.code}: ${state.error}`);
+      return state.value;
+    },
+    json
+  );
+
+export const handleEgressPolicySet = (
+  args: z.infer<typeof egressPolicySetInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_egress_policy_set",
+    async () => {
+      requireWrite(ctx);
+      const service = new CollectionEgressPolicyService({
+        getConfig: () => ctx.config,
+        mutateConfig: (mutate) =>
+          applyConfigChange(
+            {
+              store: ctx.store,
+              configPath: ctx.actualConfigPath,
+              onConfigUpdated: (config) => {
+                ctx.config = config;
+              },
+              projectStore: (store, config) =>
+                projectCollectionEgressPolicy(store, config, args.collection),
+            },
+            mutate
+          ),
+        onPolicyChanged: async () =>
+          (await ctx.invalidateEgressPolicy?.()) ?? {
+            policyEpoch: "egress-epoch-standalone",
+            queuedJobsInvalidated: 0,
+            sessionsInvalidated: 0,
+            staleWorkMustRetry: true,
+          },
+      });
+      const result = await service.set(args);
+      if (!result.ok) throw new Error(`${result.code}: ${result.error}`);
+      const epoch = result.value.invalidation?.policyEpoch;
+      if (epoch) ctx.advanceRequestAuthorizationEpoch?.(epoch);
+      return result.value;
+    },
+    json
+  );
+
+export const handleEgressCheck = (
+  args: z.infer<typeof egressCheckInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_egress_check",
+    async () => {
+      const result = new CollectionEgressPolicyService({
+        getConfig: () => ctx.config,
+      }).explain(args);
+      if (!result.ok) throw new Error(`${result.code}: ${result.error}`);
+      return result.value;
+    },
+    json
+  );
+
+export const handleEgressAuditList = (
+  args: z.infer<typeof egressAuditListInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_egress_audit_list",
+    async () => unwrap(await new EgressAuditService(ctx.store).list(args)),
+    json
+  );
+
+export const handleEgressAuditShow = (
+  args: z.infer<typeof egressAuditIdInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_egress_audit_show",
+    async () =>
+      unwrap(await new EgressAuditService(ctx.store).show(args.auditId)),
+    json
+  );
+
+export const handleEgressAuditStatus = (
+  _args: z.infer<typeof egressAuditStatusInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_egress_audit_status",
+    async () => unwrap(await new EgressAuditService(ctx.store).status()),
+    json
+  );
+
+export const handleEgressAuditDelete = (
+  args: z.infer<typeof egressAuditIdInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_egress_audit_delete",
+    async () => {
+      requireWrite(ctx);
+      return unwrap(
+        await new EgressAuditService(ctx.store).delete(args.auditId)
+      );
+    },
+    json
+  );
+
+export const handleEgressAuditPurge = (
+  _args: z.infer<typeof egressAuditPurgeInputSchema>,
+  ctx: ToolContext
+): Promise<ToolResult> =>
+  runTool(
+    ctx,
+    "gno_egress_audit_purge",
+    async () => {
+      requireWrite(ctx);
+      return unwrap(await new EgressAuditService(ctx.store).purge());
+    },
+    json
+  );

package/src/mcp/tools/embed.ts

@@ -87,6 +87,7 @@ export function handleEmbed(
               // Create LLM adapter with offline policy (fail-fast, no download)
               const llm = new LlmAdapter(ctx.config);
               const embedResult = await llm.createEmbeddingPort(modelUri, {
+                egressCollections: collection ? [collection.name] : "all",
                 policy: { offline: true, allowDownload: false },
               });
 

package/src/mcp/tools/get.ts

@@ -15,6 +15,10 @@ import {
   type DocumentCapabilities,
 } from "../../core/document-capabilities";
 import { resolveEffectiveIndex } from "../../core/indexed-reference";
+import {
+  projectRecordEvidenceMetadata,
+  type RecordEvidenceMetadata,
+} from "../../core/record-metadata";
 import { parseRef } from "../../core/ref-parser";
 import {
   attachRetrievalTraceMetadata,
@@ -54,6 +58,7 @@ interface GetResponse {
     converterVersion?: string;
     mirrorHash?: string;
   };
+  record?: RecordEvidenceMetadata;
   capabilities: DocumentCapabilities;
 }
 
@@ -210,13 +215,14 @@ export function handleGet(
 
         // Build absPath
         const uriParsed = parseUri(doc.uri);
+        const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
         let absPath: string | undefined;
         if (uriParsed) {
           const collection = ctx.collections.find(
             (c) => c.name === uriParsed.collection
           );
           if (collection) {
-            absPath = pathJoin(collection.path, doc.relPath);
+            absPath = pathJoin(collection.path, sourceRelPath);
           }
         }
 
@@ -230,7 +236,7 @@ export function handleGet(
           language: doc.languageHint ?? undefined,
           source: {
             absPath,
-            relPath: doc.relPath,
+            relPath: sourceRelPath,
             mime: doc.sourceMime,
             ext: doc.sourceExt,
             modifiedAt: doc.sourceMtime,
@@ -244,10 +250,12 @@ export function handleGet(
                 mirrorHash: doc.mirrorHash,
               }
             : undefined,
+          record: projectRecordEvidenceMetadata(doc),
           capabilities: getDocumentCapabilities({
             sourceExt: doc.sourceExt,
             sourceMime: doc.sourceMime,
             contentAvailable: doc.mirrorHash !== null,
+            recordKey: doc.recordKey,
           }),
         };
 

package/src/mcp/tools/index-cmd.ts

@@ -23,6 +23,7 @@ import {
   createVectorIndexPort,
   createVectorStatsPort,
 } from "../../store/vector";
+import { enforceSyncCommandEgress } from "../sync-egress";
 import { runTool, type ToolResult } from "./index";
 
 interface IndexInput {
@@ -107,6 +108,11 @@ export function handleIndex(
           },
           ctx.config
         );
+        enforceSyncCommandEgress(ctx, {
+          collectionNames: collections,
+          gitPull: options.gitPull,
+          runUpdateCmd: options.runUpdateCmd,
+        });
 
         const modelUri = resolveModelUri(
           ctx.config,
@@ -144,6 +150,7 @@ export function handleIndex(
               // Phase 2: Embed
               const llm = new LlmAdapter(ctx.config);
               const embedResult = await llm.createEmbeddingPort(modelUri, {
+                egressCollections: collections,
                 policy: { offline: true, allowDownload: false },
               });
 

package/src/mcp/tools/index.ts

@@ -31,6 +31,23 @@ import {
 } from "./changes";
 import { handleClearCollectionEmbeddings } from "./clear-collection-embeddings";
 import { handleContext, handleContextVerify } from "./context";
+import {
+  egressAuditIdInputSchema,
+  egressAuditListInputSchema,
+  egressAuditPurgeInputSchema,
+  egressAuditStatusInputSchema,
+  egressCheckInputSchema,
+  egressPolicyGetInputSchema,
+  egressPolicySetInputSchema,
+  handleEgressAuditDelete,
+  handleEgressAuditList,
+  handleEgressAuditPurge,
+  handleEgressAuditShow,
+  handleEgressAuditStatus,
+  handleEgressCheck,
+  handleEgressPolicyGet,
+  handleEgressPolicySet,
+} from "./egress";
 import { handleEmbed } from "./embed";
 import { handleGet } from "./get";
 import { handleIndex } from "./index-cmd";
@@ -125,6 +142,9 @@ export const MCP_WRITE_TOOL_NAMES = new Set([
   "gno_trace_export",
   "gno_trace_delete",
   "gno_trace_purge",
+  "gno_egress_policy_set",
+  "gno_egress_audit_delete",
+  "gno_egress_audit_purge",
 ]);
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1059,6 +1079,54 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleStatus(args, ctx)
   );
 
+  server.registerTool(
+    "gno_egress_policy_get",
+    {
+      description:
+        "Show one collection's configured and effective egress policy, provenance source, and confirmation-bound version.",
+      inputSchema: egressPolicyGetInputSchema,
+    },
+    (args) => handleEgressPolicyGet(args, ctx)
+  );
+
+  server.registerTool(
+    "gno_egress_check",
+    {
+      description:
+        "Check or explain an exact action, destination, caller, content class, and collection scope without performing the action.",
+      inputSchema: egressCheckInputSchema,
+    },
+    (args) => handleEgressCheck(args, ctx)
+  );
+
+  server.registerTool(
+    "gno_egress_audit_list",
+    {
+      description:
+        "List content-free local egress decisions newest-first through an opaque cursor.",
+      inputSchema: egressAuditListInputSchema,
+    },
+    (args) => handleEgressAuditList(args, ctx)
+  );
+
+  server.registerTool(
+    "gno_egress_audit_show",
+    {
+      description: "Inspect one content-free local egress decision receipt.",
+      inputSchema: egressAuditIdInputSchema,
+    },
+    (args) => handleEgressAuditShow(args, ctx)
+  );
+
+  server.registerTool(
+    "gno_egress_audit_status",
+    {
+      description: "Show local egress audit retention and storage status.",
+      inputSchema: egressAuditStatusInputSchema,
+    },
+    (args) => handleEgressAuditStatus(args, ctx)
+  );
+
   server.tool(
     "gno_changes",
     "List retained metadata-only document changes with opaque cursor pagination and retention disclosure.",
@@ -1151,6 +1219,36 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
   );
 
   if (ctx.enableWrite) {
+    server.registerTool(
+      "gno_egress_policy_set",
+      {
+        description:
+          "Set one collection policy. Relaxation requires confirmation bound to the current policy and version.",
+        inputSchema: egressPolicySetInputSchema,
+      },
+      (args) => handleEgressPolicySet(args, ctx)
+    );
+
+    server.registerTool(
+      "gno_egress_audit_delete",
+      {
+        description:
+          "Delete exactly one local egress audit receipt with physical cleanup status.",
+        inputSchema: egressAuditIdInputSchema,
+      },
+      (args) => handleEgressAuditDelete(args, ctx)
+    );
+
+    server.registerTool(
+      "gno_egress_audit_purge",
+      {
+        description:
+          "Purge local egress audit receipts only. Requires confirm=true.",
+        inputSchema: egressAuditPurgeInputSchema,
+      },
+      (args) => handleEgressAuditPurge(args, ctx)
+    );
+
     server.tool(
       "gno_trace_label",
       "Append an explicit relevant, irrelevant, or missing_expected judgment to a local retrieval trace.",

package/src/mcp/tools/multi-get.ts

@@ -11,6 +11,10 @@ import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { resolveEffectiveIndex } from "../../core/indexed-reference";
+import {
+  projectRecordEvidenceMetadata,
+  type RecordEvidenceMetadata,
+} from "../../core/record-metadata";
 import { parseRef } from "../../core/ref-parser";
 import { openScopedIndexStore } from "../../store/sqlite/scoped-index";
 import { runTool, type ToolResult } from "./index";
@@ -37,6 +41,7 @@ interface DocumentResult {
     modifiedAt?: string;
     sizeBytes?: number;
   };
+  record?: RecordEvidenceMetadata;
 }
 
 interface MultiGetResponse {
@@ -234,13 +239,14 @@ export function handleMultiGet(
 
           // Build absPath
           const uriParsed = parseUri(doc.uri);
+          const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
           let absPath: string | undefined;
           if (uriParsed) {
             const collection = ctx.collections.find(
               (c) => c.name === uriParsed.collection
             );
             if (collection) {
-              absPath = pathJoin(collection.path, doc.relPath);
+              absPath = pathJoin(collection.path, sourceRelPath);
             }
           }
 
@@ -253,12 +259,13 @@ export function handleMultiGet(
             truncated,
             source: {
               absPath,
-              relPath: doc.relPath,
+              relPath: sourceRelPath,
               mime: doc.sourceMime,
               ext: doc.sourceExt,
               modifiedAt: doc.sourceMtime,
               sizeBytes: doc.sourceSize,
             },
+            record: projectRecordEvidenceMetadata(doc),
           });
         }
 

package/src/mcp/tools/query.ts

@@ -279,6 +279,9 @@ export function handleQuery(
         if (!traceStart.ok) throw new Error(traceStart.error.message);
         traceSession = traceStart.value ?? undefined;
         const llm = new LlmAdapter(ctx.config);
+        const egressCollections = args.collection
+          ? [args.collection]
+          : ("all" as const);
 
         // Resolve download policy from env (MCP has no CLI flags)
         const policy = resolveDownloadPolicy(process.env, {});
@@ -288,6 +291,7 @@ export function handleQuery(
 
         // Create embedding port (for vector search) - optional
         const embedResult = await llm.createEmbeddingPort(embedUri, {
+          egressCollections,
           policy,
           onProgress: (progress) => downloadProgress("embed", progress),
         });
@@ -298,6 +302,7 @@ export function handleQuery(
         // Create expansion port - optional
         if (expandUri) {
           const genResult = await llm.createExpansionPort(expandUri, {
+            egressCollections,
             policy,
             onProgress: (progress) => downloadProgress("expand", progress),
           });
@@ -309,6 +314,7 @@ export function handleQuery(
         // Create rerank port - optional
         if (rerankUri) {
           const rerankResult = await llm.createRerankPort(rerankUri, {
+            egressCollections,
             policy,
             onProgress: (progress) => downloadProgress("rerank", progress),
           });
@@ -425,6 +431,7 @@ export function handleQueryDiagnose(
       const llm = new LlmAdapter(ctx.config);
       const policy = resolveDownloadPolicy(process.env, {});
       const downloadProgress = createNonTtyProgressRenderer();
+      const egressCollections = collection ? [collection] : ("all" as const);
 
       let embedPort: EmbeddingPort | null = null;
       let expandPort: GenerationPort | null = null;
@@ -456,6 +463,7 @@ export function handleQueryDiagnose(
 
         if (!args.fast) {
           const embedResult = await llm.createEmbeddingPort(embedUri, {
+            egressCollections,
             policy,
             onProgress: (progress) => downloadProgress("embed", progress),
           });
@@ -468,6 +476,7 @@ export function handleQueryDiagnose(
           const genResult = await llm.createExpansionPort(
             resolveModelUri(ctx.config, "expand", undefined, collection),
             {
+              egressCollections,
               policy,
               onProgress: (progress) => downloadProgress("expand", progress),
             }
@@ -481,6 +490,7 @@ export function handleQueryDiagnose(
           const rerankResult = await llm.createRerankPort(
             resolveModelUri(ctx.config, "rerank", undefined, collection),
             {
+              egressCollections,
               policy,
               onProgress: (progress) => downloadProgress("rerank", progress),
             }

package/src/mcp/tools/remove-collection.ts

@@ -89,6 +89,10 @@ export function handleRemoveCollection(
         if (!mutationResult.ok) {
           throw mapConfigError(mutationResult.code, mutationResult.error);
         }
+        const invalidation = await ctx.invalidateEgressPolicy?.();
+        if (invalidation) {
+          ctx.advanceRequestAuthorizationEpoch?.(invalidation.policyEpoch);
+        }
         ctx.markContentMutation?.();
         ctx.markIndexMutation?.();
 

package/src/mcp/tools/sync.ts

@@ -14,6 +14,7 @@ import { JobError } from "../../core/job-manager";
 import { recordContentMutation } from "../../core/mutation-generations";
 import { normalizeCollectionName } from "../../core/validation";
 import { defaultSyncService, withContentTypeRules } from "../../ingestion";
+import { enforceSyncCommandEgress } from "../sync-egress";
 import { runTool, type ToolResult } from "./index";
 
 interface SyncInput {
@@ -109,6 +110,11 @@ export function handleSync(
           },
           ctx.config
         );
+        enforceSyncCommandEgress(ctx, {
+          collectionNames: collections,
+          gitPull: options.gitPull,
+          runUpdateCmd: options.runUpdateCmd,
+        });
 
         const jobId = await ctx.jobManager.startJobWithLock(
           "sync",

package/src/mcp/tools/trace.ts

@@ -106,7 +106,13 @@ const runTraceWrite = <T>(
     async () => {
       if (!ctx.enableWrite) return writeDisabled();
       return withWriteLock(ctx.writeLockPath, async () =>
-        unwrap(await operation(new RetrievalTraceManagementService(ctx.store)))
+        unwrap(
+          await operation(
+            new RetrievalTraceManagementService(ctx.store, {
+              authorizeExport: ctx.authorizeTraceExport,
+            })
+          )
+        )
       );
     },
     jsonText

package/src/mcp/tools/vsearch.ts

@@ -180,6 +180,7 @@ export function handleVsearch(
         // Create LLM adapter for embeddings
         const llm = new LlmAdapter(ctx.config);
         const embedResult = await llm.createEmbeddingPort(modelUri, {
+          egressCollections: args.collection ? [args.collection] : "all",
           policy,
           onProgress: (progress) => downloadProgress("embed", progress),
         });

package/src/mcp/tools/workspace-write.ts

@@ -141,11 +141,13 @@ function ensureEditable(doc: {
   sourceExt: string;
   sourceMime: string;
   mirrorHash: string | null;
+  recordKey?: string | null;
 }) {
   const capabilities = getDocumentCapabilities({
     sourceExt: doc.sourceExt,
     sourceMime: doc.sourceMime,
     contentAvailable: doc.mirrorHash !== null,
+    recordKey: doc.recordKey,
   });
   if (!capabilities.editable) {
     throw new Error(