@gmickel/gno 1.28.0 → 1.29.1

package/src/mcp/tools/context.ts

@@ -119,7 +119,7 @@ export const disposeContextModelOwners = async (
 
 export const createMcpModelPorts = async (
   context: ToolContext,
-  collection?: string,
+  collections?: readonly string[],
   factoryOverride?: McpModelPortFactory,
   options: { generation?: boolean } = {}
 ): Promise<McpModelPorts> => {
@@ -128,6 +128,10 @@ export const createMcpModelPorts = async (
   const lease = factory.acquireModelLease?.();
   const policy = resolveDownloadPolicy(process.env, {});
   const progress = createNonTtyProgressRenderer();
+  const egressCollections = collections?.length
+    ? collections
+    : ("all" as const);
+  const collection = collections?.length === 1 ? collections[0] : undefined;
   const embedUri = resolveModelUri(
     context.config,
     "embed",
@@ -141,6 +145,7 @@ export const createMcpModelPorts = async (
   let vectorIndex: VectorIndexPort | null = null;
   try {
     const embedResult = await factory.createEmbeddingPort(embedUri, {
+      egressCollections,
       policy,
       onProgress: (value) => progress("embed", value),
     });
@@ -160,6 +165,7 @@ export const createMcpModelPorts = async (
     const rerankResult = await factory.createRerankPort(
       resolveModelUri(context.config, "rerank", undefined, collection),
       {
+        egressCollections,
         policy,
         onProgress: (value) => progress("rerank", value),
       }
@@ -169,6 +175,7 @@ export const createMcpModelPorts = async (
       const genResult = await factory.createGenerationPort(
         resolveModelUri(context.config, "gen", undefined, collection),
         {
+          egressCollections,
           policy,
           onProgress: (value) => progress("gen", value),
         }
@@ -269,7 +276,7 @@ export const handleContext = (
       if (!traceStart.ok) throw new Error(traceStart.error.message);
       traceSession = traceStart.value ?? undefined;
       modelPorts = useModels
-        ? await createMcpModelPorts(context, collection)
+        ? await createMcpModelPorts(context, parsed.input.collections)
         : null;
       const capsule = await buildContextCapsule(parsed.input, {
         store: context.store,

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/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/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),
         });