@stigmer/mcp-server 3.12.0 → 3.12.1

package/src/domains/agents/apply.ts

@@ -6,7 +6,10 @@
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
 
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
 import { agentInputToProto, type AgentInput } from "../../gen/agent.js";
+import { applyDeclaredVisibility } from "../apply-visibility.js";
 import { withClient } from "../client.js";
 import { toProtoJson } from "../marshal.js";
 import { rpcError } from "../rpcerr.js";
@@ -21,7 +24,13 @@ export async function applyAgent(
   const desc = `agent "${agent.metadata?.slug ?? ""}" in org "${agent.metadata?.org ?? ""}"`;
   return withClient(AgentCommandController, serverAddress, token, async (client, callOptions) => {
     try {
-      const result = await client.apply(agent, callOptions);
+      const applied = await client.apply(agent, callOptions);
+      const result = await applyDeclaredVisibility(
+        client,
+        callOptions,
+        applied,
+        agent.metadata?.visibility ?? ApiResourceVisibility.api_resource_visibility_unspecified,
+      );
       return toProtoJson(AgentSchema, result);
     } catch (err) {
       throw rpcError(err, desc);

package/src/domains/apply-visibility.ts

@@ -0,0 +1,47 @@
+// Declared-visibility follow-up for the apply tools (oss#573).
+//
+// Plain updates preserve the stored visibility on both editions — the
+// updateVisibility RPC is the only door for visibility changes, where the
+// server-side guards live (per-kind level support, default-instance
+// rejection). So when an apply tool's input declares a visibility and the
+// applied resource comes back with a different level (i.e. the resource
+// already existed), we follow up with one UpdateVisibility RPC on the same
+// controller. The CLI's skill-push and manifest-apply flows do the same.
+//
+// No-ops are skipped (input omitted visibility, create honored it, or the
+// stored level already matches), so an unchanged apply costs nothing extra.
+// Guard rejections propagate to the caller's rpcError wrapper — the model
+// sees the real FAILED_PRECONDITION / INVALID_ARGUMENT, not a silent lie.
+
+import { create } from "@bufbuild/protobuf";
+import type { CallOptions } from "@connectrpc/connect";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { UpdateVisibilityInputSchema, type UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+interface HasResourceMetadata {
+  metadata?: ApiResourceMetadata;
+}
+
+interface UpdateVisibilityClient<T> {
+  updateVisibility(input: UpdateVisibilityInput, options?: CallOptions): Promise<T>;
+}
+
+/**
+ * Land the input-declared visibility through the guarded door when the
+ * applied resource's stored level differs. Returns the resource carrying the
+ * final visibility (the follow-up's response, or `applied` unchanged when no
+ * follow-up was needed).
+ */
+export async function applyDeclaredVisibility<T extends HasResourceMetadata>(
+  client: UpdateVisibilityClient<T>,
+  callOptions: CallOptions,
+  applied: T,
+  declared: ApiResourceVisibility,
+): Promise<T> {
+  if (declared === ApiResourceVisibility.api_resource_visibility_unspecified) return applied;
+  const resourceId = applied.metadata?.id ?? "";
+  if (resourceId === "") return applied;
+  if (applied.metadata?.visibility === declared) return applied;
+  return client.updateVisibility(create(UpdateVisibilityInputSchema, { resourceId, visibility: declared }), callOptions);
+}

package/src/domains/apply.integration.test.ts

@@ -7,6 +7,7 @@
 // data map with secret flags, and the recursive workflow task_config expansion
 // (http_call leaf, fork/for_each nesting).
 
+import { clone } from "@bufbuild/protobuf";
 import type { ConnectRouter } from "@connectrpc/connect";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
 import {
@@ -18,7 +19,7 @@ import type { AddressInfo } from "node:net";
 
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { type Agent, AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
 import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
@@ -29,6 +30,7 @@ import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/wo
 import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
 import { configureLogger } from "../logger";
@@ -42,6 +44,13 @@ let appliedAgent: Agent | undefined;
 let appliedMcpServer: McpServerProto | undefined;
 let appliedWorkflow: Workflow | undefined;
 let appliedEnvironment: Environment | undefined;
+const visibilityUpdates: UpdateVisibilityInput[] = [];
+
+// The single-door contract (oss#573): a plain update preserves the STORED
+// visibility, so the apply response can disagree with the request. This slug
+// makes the mock backend simulate that — apply echoes back a pre-existing
+// resource whose stored level is org, regardless of the requested one.
+const STORED_ORG_SLUG = "stored-org-agent";
 const openSessions = new Set<ServerHttp2Session>();
 
 interface ToolResult {
@@ -58,8 +67,21 @@ beforeAll(async () => {
     router.service(AgentCommandController, {
       apply: (req) => {
         appliedAgent = req;
+        if (req.metadata?.slug === STORED_ORG_SLUG) {
+          const stored = clone(AgentSchema, req);
+          stored.metadata!.id = "agent-stored-1";
+          stored.metadata!.visibility = ApiResourceVisibility.visibility_org;
+          return stored;
+        }
         return req;
       },
+      updateVisibility: (input) => {
+        visibilityUpdates.push(input);
+        const updated = clone(AgentSchema, appliedAgent!);
+        updated.metadata!.id = input.resourceId;
+        updated.metadata!.visibility = input.visibility;
+        return updated;
+      },
     });
     router.service(McpServerCommandController, {
       apply: (req) => {
@@ -234,6 +256,38 @@ describe("apply tools integration", () => {
     expect(forCfg.do).toHaveLength(1);
   });
 
+  it("apply_agent lands a declared visibility the update preserved away via UpdateVisibility (oss#573)", async () => {
+    const result = await callTool("apply_agent", {
+      name: "Stored Org Agent",
+      org: "acme",
+      visibility: "PUBLIC",
+      instructions: "i",
+    });
+    expect(result.isError).toBeFalsy();
+
+    // Server "preserved" stored org; the tool must follow up once through
+    // the guarded door and return the landed level, not the stale one.
+    expect(visibilityUpdates).toHaveLength(1);
+    expect(visibilityUpdates[0].resourceId).toBe("agent-stored-1");
+    expect(visibilityUpdates[0].visibility).toBe(ApiResourceVisibility.visibility_public);
+    const text = result.content.find((c) => c.type === "text")?.text ?? "";
+    expect(JSON.parse(text).metadata.visibility).toBe("visibility_public");
+  });
+
+  it("apply_agent skips the follow-up when the server already matches", async () => {
+    visibilityUpdates.length = 0;
+    const result = await callTool("apply_agent", {
+      name: "Plain Agent",
+      org: "acme",
+      visibility: "PUBLIC",
+      instructions: "i",
+    });
+    expect(result.isError).toBeFalsy();
+    // The echo backend returns the requested level (and no id) — no diff,
+    // no follow-up.
+    expect(visibilityUpdates).toHaveLength(0);
+  });
+
   it("apply_environment rebuilds the data map with secret flags", async () => {
     const result = await callTool("apply_environment", {
       name: "GitHub Creds",

package/src/domains/environments/apply.ts

@@ -11,7 +11,10 @@
 import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
 
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
 import { environmentInputToProto, type EnvironmentInput } from "../../gen/environment.js";
+import { applyDeclaredVisibility } from "../apply-visibility.js";
 import { withClient } from "../client.js";
 import { toProtoJson } from "../marshal.js";
 import { rpcError } from "../rpcerr.js";
@@ -30,7 +33,13 @@ export async function applyEnvironment(
     token,
     async (client, callOptions) => {
       try {
-        const result = await client.apply(environment, callOptions);
+        const applied = await client.apply(environment, callOptions);
+        const result = await applyDeclaredVisibility(
+          client,
+          callOptions,
+          applied,
+          environment.metadata?.visibility ?? ApiResourceVisibility.api_resource_visibility_unspecified,
+        );
         return toProtoJson(EnvironmentSchema, result);
       } catch (err) {
         throw rpcError(err, desc);

package/src/domains/mcpservers/apply.ts

@@ -7,7 +7,10 @@
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
 
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
 import { mcpServerInputToProto, type McpServerInput } from "../../gen/mcpserver.js";
+import { applyDeclaredVisibility } from "../apply-visibility.js";
 import { withClient } from "../client.js";
 import { toProtoJson } from "../marshal.js";
 import { rpcError } from "../rpcerr.js";
@@ -26,7 +29,13 @@ export async function applyMcpServer(
     token,
     async (client, callOptions) => {
       try {
-        const result = await client.apply(server, callOptions);
+        const applied = await client.apply(server, callOptions);
+        const result = await applyDeclaredVisibility(
+          client,
+          callOptions,
+          applied,
+          server.metadata?.visibility ?? ApiResourceVisibility.api_resource_visibility_unspecified,
+        );
         return toProtoJson(McpServerSchema, result);
       } catch (err) {
         throw rpcError(err, desc);

package/src/domains/workflows/apply.ts

@@ -11,7 +11,10 @@
 import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
 
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
 import { workflowInputToProto, type WorkflowInput } from "../../gen/workflow.js";
+import { applyDeclaredVisibility } from "../apply-visibility.js";
 import { withClient } from "../client.js";
 import { toProtoJson } from "../marshal.js";
 import { rpcError } from "../rpcerr.js";
@@ -30,7 +33,13 @@ export async function applyWorkflow(
     token,
     async (client, callOptions) => {
       try {
-        const result = await client.apply(workflow, callOptions);
+        const applied = await client.apply(workflow, callOptions);
+        const result = await applyDeclaredVisibility(
+          client,
+          callOptions,
+          applied,
+          workflow.metadata?.visibility ?? ApiResourceVisibility.api_resource_visibility_unspecified,
+        );
         return toProtoJson(WorkflowSchema, result);
       } catch (err) {
         throw rpcError(err, desc);

package/src/gen/agent.ts

@@ -18,7 +18,7 @@ export const AgentInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
   org: z.string().describe("Organization that owns this resource (e.g. acme)."),
-  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Applied at create; on updates a changed value is landed through the guarded UpdateVisibility RPC. Omit to leave unchanged."),
   labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
   tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
   description: z.string().optional().describe("Human-readable description for UI and marketplace display."),

package/src/gen/environment.ts

@@ -15,7 +15,7 @@ export const EnvironmentInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
   org: z.string().describe("Organization that owns this resource (e.g. acme)."),
-  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Applied at create; on updates a changed value is landed through the guarded UpdateVisibility RPC. Omit to leave unchanged."),
   labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
   tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
   description: z.string().optional().describe("Human-readable description for UI and listing display."),

package/src/gen/mcpserver.ts

@@ -18,7 +18,7 @@ export const McpServerInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
   org: z.string().describe("Organization that owns this resource (e.g. acme)."),
-  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Applied at create; on updates a changed value is landed through the guarded UpdateVisibility RPC. Omit to leave unchanged."),
   labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
   tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
   description: z.string().optional().describe("Human-readable description for marketplace display and documentation. Should explain what this MCP server does and its primary use cases. Example: 'GitHub MCP server for repository operations, code search, and PR management'"),

package/src/gen/workflow.ts

@@ -45,7 +45,7 @@ export const WorkflowInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
   org: z.string().describe("Organization that owns this resource (e.g. acme)."),
-  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Applied at create; on updates a changed value is landed through the guarded UpdateVisibility RPC. Omit to leave unchanged."),
   labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
   tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
   description: z.string().optional().describe("Human-readable description for UI and marketplace display."),