Skip to content

The open alternative to Salesforce, designed for AI.

Migrate the role tools to @DefineTool (#28476)

Paul Rastoin9e234e6aa1a0
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/role-tool.provider.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/role-tool.provider.ts
deleted file mode 100644
index 58ef280bf1a..00000000000
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/role-tool.provider.ts
+++ /dev/null
@@ -1,67 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-import { ToolCategory } from 'twenty-shared/ai';
-import { PermissionFlagType } from 'twenty-shared/constants';
-
-import { type GenerateDescriptorOptions } from 'src/engine/core-modules/tool-provider/interfaces/generate-descriptor-options.type';
-import { type ToolProvider } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider.interface';
-import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
-import { type ToolDescriptor } from 'src/engine/core-modules/tool-provider/types/tool-descriptor.type';
-import { type ToolIndexEntry } from 'src/engine/core-modules/tool-provider/types/tool-index-entry.type';
-import { executeToolFromToolSet } from 'src/engine/core-modules/tool-provider/utils/execute-tool-from-tool-set.util';
-import { toolSetToDescriptors } from 'src/engine/core-modules/tool-provider/utils/tool-set-to-descriptors.util';
-import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
-import { PermissionsService } from 'src/engine/metadata-modules/permissions/permissions.service';
-import { RoleToolWorkspaceService } from 'src/engine/metadata-modules/role/tools/services/role-tool.workspace-service';
-import { getRoleIdsFromRolePermissionConfig } from 'src/engine/twenty-orm/utils/get-role-ids-from-role-permission-config.util';
-
-@Injectable()
-export class RoleToolProvider implements ToolProvider {
- readonly category = ToolCategory.ROLE;
-
- constructor(
- private readonly roleToolWorkspaceService: RoleToolWorkspaceService,
- private readonly permissionsService: PermissionsService,
- ) {}
-
- async isAvailable(context: ToolProviderContext): Promise<boolean> {
- return this.permissionsService.checkRolesPermissions(
- context.rolePermissionConfig,
- context.workspaceId,
- PermissionFlagType.ROLES,
- );
- }
-
- async generateDescriptors(
- context: ToolProviderContext,
- options?: GenerateDescriptorOptions,
- ): Promise<(ToolIndexEntry | ToolDescriptor)[]> {
- return toolSetToDescriptors(this.buildToolSet(context), ToolCategory.ROLE, {
- includeSchemas: options?.includeSchemas ?? true,
- });
- }
-
- async executeStaticTool(
- toolName: string,
- args: Record<string, unknown>,
- context: ToolProviderContext,
- ): Promise<ToolOutput> {
- return executeToolFromToolSet(
- this.buildToolSet(context),
- toolName,
- args,
- ToolCategory.ROLE,
- );
- }
-
- private buildToolSet(context: ToolProviderContext): ToolSet {
- return this.roleToolWorkspaceService.generateRoleTools({
- workspaceId: context.workspaceId,
- callerRoleIds: getRoleIdsFromRolePermissionConfig(
- context.rolePermissionConfig,
- ),
- callerUserWorkspaceId: context.userWorkspaceId,
- });
- }
-}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
index c26d917c9bb..81b81e8486f 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/tool-provider.module.ts
@@ -14,7 +14,6 @@ import { DatabaseToolProvider } from 'src/engine/core-modules/tool-provider/prov
import { LogicFunctionToolProvider } from 'src/engine/core-modules/tool-provider/providers/logic-function-tool.provider';
import { MetadataToolProvider } from 'src/engine/core-modules/tool-provider/providers/metadata-tool.provider';
import { NavigationMenuItemToolProvider } from 'src/engine/core-modules/tool-provider/providers/navigation-menu-item-tool.provider';
-import { RoleToolProvider } from 'src/engine/core-modules/tool-provider/providers/role-tool.provider';
import { ViewToolProvider } from 'src/engine/core-modules/tool-provider/providers/view-tool.provider';
import { WorkflowToolProvider } from 'src/engine/core-modules/tool-provider/providers/workflow-tool.provider';
import { DefinedToolRegistryService } from 'src/engine/core-modules/tool-provider/services/defined-tool-registry.service';
@@ -29,7 +28,7 @@ import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata
import { NavigationMenuItemModule } from 'src/engine/metadata-modules/navigation-menu-item/navigation-menu-item.module';
import { ObjectMetadataModule } from 'src/engine/metadata-modules/object-metadata/object-metadata.module';
import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permissions.module';
-import { RoleModule } from 'src/engine/metadata-modules/role/role.module';
+import { RoleToolsModule } from 'src/engine/metadata-modules/role/tools/role-tools.module';
import { UserRoleModule } from 'src/engine/metadata-modules/user-role/user-role.module';
import { ValidationRuleModule } from 'src/engine/metadata-modules/validation-rule/validation-rule.module';
import { ViewFieldModule } from 'src/engine/metadata-modules/view-field/view-field.module';
@@ -67,7 +66,7 @@ import { ToolRegistryService } from './services/tool-registry.service';
WorkspaceManyOrAllFlatEntityMapsCacheModule,
NavigationMenuItemModule,
WebhookToolsModule,
- RoleModule,
+ RoleToolsModule,
UserRoleModule,
ValidationRuleModule,
EmailingModule,
@@ -86,7 +85,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
MetadataToolProvider,
NavigationMenuItemToolProvider,
LogicFunctionToolProvider,
- RoleToolProvider,
ViewToolProvider,
WorkflowToolProvider,
{
@@ -97,7 +95,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
metadataProvider: MetadataToolProvider,
logicFunctionProvider: LogicFunctionToolProvider,
navigationMenuItemProvider: NavigationMenuItemToolProvider,
- roleProvider: RoleToolProvider,
viewProvider: ViewToolProvider,
workflowProvider: WorkflowToolProvider,
dashboardProvider: DashboardToolProvider,
@@ -108,7 +105,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
metadataProvider,
logicFunctionProvider,
navigationMenuItemProvider,
- roleProvider,
viewProvider,
workflowProvider,
dashboardProvider,
@@ -120,7 +116,6 @@ import { ToolRegistryService } from './services/tool-registry.service';
MetadataToolProvider,
LogicFunctionToolProvider,
NavigationMenuItemToolProvider,
- RoleToolProvider,
ViewToolProvider,
WorkflowToolProvider,
DashboardToolProvider,
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/role.module.ts b/packages/twenty-server/src/engine/metadata-modules/role/role.module.ts
index d2d9d4719ef..18759cab6a5 100644
--- a/packages/twenty-server/src/engine/metadata-modules/role/role.module.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/role.module.ts
@@ -12,7 +12,6 @@ import { PermissionsModule } from 'src/engine/metadata-modules/permissions/permi
import { RoleResolver } from 'src/engine/metadata-modules/role/role.resolver';
import { RoleService } from 'src/engine/metadata-modules/role/role.service';
import { WorkspaceFlatRoleMapCacheService } from 'src/engine/metadata-modules/role/services/workspace-flat-role-map-cache.service';
-import { RoleToolWorkspaceService } from 'src/engine/metadata-modules/role/tools/services/role-tool.workspace-service';
import { WorkspaceRoleIdsWithAllRecordsAccessCacheService } from 'src/engine/metadata-modules/role/services/workspace-role-ids-with-all-records-access-cache.service';
import { WorkspaceRolesPermissionsCacheService } from 'src/engine/metadata-modules/role/services/workspace-roles-permissions-cache.service';
import { RowLevelPermissionModule } from 'src/engine/metadata-modules/row-level-permission-predicate/row-level-permission.module';
@@ -37,12 +36,11 @@ import { WorkspaceMigrationModule } from 'src/engine/workspace-manager/workspace
providers: [
RoleService,
RoleResolver,
- RoleToolWorkspaceService,
WorkspaceFlatRoleMapCacheService,
WorkspaceFlatRoleTargetMapCacheService,
WorkspaceRolesPermissionsCacheService,
WorkspaceRoleIdsWithAllRecordsAccessCacheService,
],
- exports: [RoleService, RoleToolWorkspaceService],
+ exports: [RoleService],
})
export class RoleModule {}
diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/__tests__/role-tool.provider.spec.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/__tests__/role-tools.spec.ts
similarity index 52%
rename from packages/twenty-server/src/engine/core-modules/tool-provider/providers/__tests__/role-tool.provider.spec.ts
rename to packages/twenty-server/src/engine/metadata-modules/role/tools/__tests__/role-tools.spec.ts
index dc7f8560b92..d025c2b9eb1 100644
--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/__tests__/role-tool.provider.spec.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/__tests__/role-tools.spec.ts
@@ -1,13 +1,20 @@
-import { PermissionFlagType } from 'twenty-shared/constants';
-import { FieldActorSource } from 'twenty-shared/types';
+import {
+ FieldActorSource,
+ RowLevelPermissionPredicateGroupLogicalOperator,
+ RowLevelPermissionPredicateOperand,
+} from 'twenty-shared/types';
import { type ApplicationService } from 'src/engine/core-modules/application/application.service';
import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
-import { RoleToolProvider } from 'src/engine/core-modules/tool-provider/providers/role-tool.provider';
import { type ObjectPermissionService } from 'src/engine/metadata-modules/object-permission/object-permission.service';
-import { type PermissionsService } from 'src/engine/metadata-modules/permissions/permissions.service';
import { type RoleService } from 'src/engine/metadata-modules/role/role.service';
-import { RoleToolWorkspaceService } from 'src/engine/metadata-modules/role/tools/services/role-tool.workspace-service';
+import { AssignRoleToWorkspaceMemberTool } from 'src/engine/metadata-modules/role/tools/assign-role-to-workspace-member.tool';
+import { CreateRoleTool } from 'src/engine/metadata-modules/role/tools/create-role.tool';
+import { DeleteRoleTool } from 'src/engine/metadata-modules/role/tools/delete-role.tool';
+import { ListRolesTool } from 'src/engine/metadata-modules/role/tools/list-roles.tool';
+import { UpdateRoleTool } from 'src/engine/metadata-modules/role/tools/update-role.tool';
+import { UpsertObjectPermissionsTool } from 'src/engine/metadata-modules/role/tools/upsert-object-permissions.tool';
+import { UpsertRowLevelPermissionRulesTool } from 'src/engine/metadata-modules/role/tools/upsert-row-level-permission-rules.tool';
import { type RowLevelPermissionPredicateGroupService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate-group.service';
import { type RowLevelPermissionPredicateService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate.service';
import { type UserRoleService } from 'src/engine/metadata-modules/user-role/user-role.service';
@@ -23,14 +30,14 @@ const ownerFieldMetadataId = '4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f80';
const workspaceMemberIdFieldMetadataId = '5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8091';
const predicateGroupId = '6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8091a2';
-const buildProvider = (options?: { hasRolesPermission?: boolean }) => {
- const roleService = {
+const buildServices = () => ({
+ roleService: {
getWorkspaceRoles: jest.fn().mockResolvedValue([]),
createRole: jest.fn(),
updateRole: jest.fn(),
deleteRole: jest.fn(),
- };
- const userRoleService = {
+ },
+ userRoleService: {
assignRoleToWorkspaceMember: jest.fn().mockResolvedValue({
workspaceMember: {
id: targetMemberId,
@@ -39,20 +46,20 @@ const buildProvider = (options?: { hasRolesPermission?: boolean }) => {
},
userWorkspaceId: 'target-user-workspace-id',
}),
- };
- const objectPermissionService = {
+ },
+ objectPermissionService: {
upsertObjectPermissions: jest.fn().mockResolvedValue([]),
- };
- const rowLevelPermissionPredicateService = {
+ },
+ rowLevelPermissionPredicateService: {
findByWorkspaceId: jest.fn().mockResolvedValue([]),
upsertRowLevelPermissionPredicates: jest
.fn()
.mockResolvedValue({ predicates: [], predicateGroups: [] }),
- };
- const rowLevelPermissionPredicateGroupService = {
+ },
+ rowLevelPermissionPredicateGroupService: {
findByWorkspaceId: jest.fn().mockResolvedValue([]),
- };
- const applicationService = {
+ },
+ applicationService: {
findWorkspaceTwentyStandardAndCustomApplicationOrThrow: jest
.fn()
.mockResolvedValue({
@@ -61,38 +68,16 @@ const buildProvider = (options?: { hasRolesPermission?: boolean }) => {
universalIdentifier: 'application-universal-identifier',
},
}),
- };
- const permissionsService = {
- checkRolesPermissions: jest
- .fn()
- .mockResolvedValue(options?.hasRolesPermission ?? true),
- };
-
- const roleToolWorkspaceService = new RoleToolWorkspaceService(
- roleService as unknown as RoleService,
- userRoleService as unknown as UserRoleService,
- objectPermissionService as unknown as ObjectPermissionService,
- rowLevelPermissionPredicateService as unknown as RowLevelPermissionPredicateService,
- rowLevelPermissionPredicateGroupService as unknown as RowLevelPermissionPredicateGroupService,
- applicationService as unknown as ApplicationService,
- );
+ },
+});
- const provider = new RoleToolProvider(
- roleToolWorkspaceService,
- permissionsService as unknown as PermissionsService,
+const buildListRolesTool = (services: ReturnType<typeof buildServices>) =>
+ new ListRolesTool(
+ services.roleService as unknown as RoleService,
+ services.rowLevelPermissionPredicateService as unknown as RowLevelPermissionPredicateService,
+ services.rowLevelPermissionPredicateGroupService as unknown as RowLevelPermissionPredicateGroupService,
);
- return {
- provider,
- roleService,
- userRoleService,
- objectPermissionService,
- rowLevelPermissionPredicateService,
- rowLevelPermissionPredicateGroupService,
- permissionsService,
- };
-};
-
const context: ToolProviderContext = {
workspaceId,
rolePermissionConfig: {
@@ -107,60 +92,12 @@ const context: ToolProviderContext = {
},
};
-describe('RoleToolProvider', () => {
- describe('isAvailable', () => {
- it('is available when the caller has the ROLES settings permission', async () => {
- const { provider, permissionsService } = buildProvider({
- hasRolesPermission: true,
- });
-
- await expect(provider.isAvailable(context)).resolves.toBe(true);
- expect(permissionsService.checkRolesPermissions).toHaveBeenCalledWith(
- context.rolePermissionConfig,
- workspaceId,
- PermissionFlagType.ROLES,
- );
- });
-
- it('is not available without the ROLES settings permission', async () => {
- const { provider } = buildProvider({ hasRolesPermission: false });
-
- await expect(provider.isAvailable(context)).resolves.toBe(false);
- });
- });
-
- describe('generateDescriptors', () => {
- it('exposes the role management tools', async () => {
- const { provider } = buildProvider();
-
- const descriptors = await provider.generateDescriptors(context, {
- includeSchemas: false,
- });
-
- expect(descriptors.map((descriptor) => descriptor.name)).toEqual(
- expect.arrayContaining([
- 'list_roles',
- 'create_role',
- 'update_role',
- 'delete_role',
- 'assign_role_to_workspace_member',
- 'upsert_object_permissions',
- 'upsert_row_level_permission_rules',
- ]),
- );
-
- for (const descriptor of descriptors) {
- expect(descriptor.label).toBeDefined();
- expect(descriptor.description.length).toBeGreaterThan(0);
- }
- });
- });
-
+describe('Role tools', () => {
describe('list_roles', () => {
it('returns the workspace roles', async () => {
- const { provider, roleService } = buildProvider();
+ const services = buildServices();
- roleService.getWorkspaceRoles.mockResolvedValue([
+ services.roleService.getWorkspaceRoles.mockResolvedValue([
{
id: 'role-1',
label: 'Support',
@@ -170,40 +107,34 @@ describe('RoleToolProvider', () => {
},
]);
- const output = await provider.executeStaticTool(
- 'list_roles',
- {},
- context,
- );
+ const output = await buildListRolesTool(services).execute({}, context);
expect(output.success).toBe(true);
- expect(roleService.getWorkspaceRoles).toHaveBeenCalledWith(workspaceId);
+ expect(services.roleService.getWorkspaceRoles).toHaveBeenCalledWith(
+ workspaceId,
+ );
});
it('includes row-level permission rules when requested', async () => {
- const {
- provider,
- roleService,
- rowLevelPermissionPredicateService,
- rowLevelPermissionPredicateGroupService,
- } = buildProvider();
-
- roleService.getWorkspaceRoles.mockResolvedValue([
+ const services = buildServices();
+
+ services.roleService.getWorkspaceRoles.mockResolvedValue([
{ id: 'role-1', label: 'Support', isEditable: true },
]);
- rowLevelPermissionPredicateService.findByWorkspaceId.mockResolvedValue([
- { id: 'predicate-1', roleId: 'role-1' },
- { id: 'predicate-2', roleId: 'other-role' },
- ]);
- rowLevelPermissionPredicateGroupService.findByWorkspaceId.mockResolvedValue(
+ services.rowLevelPermissionPredicateService.findByWorkspaceId.mockResolvedValue(
+ [
+ { id: 'predicate-1', roleId: 'role-1' },
+ { id: 'predicate-2', roleId: 'other-role' },
+ ],
+ );
+ services.rowLevelPermissionPredicateGroupService.findByWorkspaceId.mockResolvedValue(
[
{ id: 'group-1', roleId: 'role-1' },
{ id: 'group-2', roleId: 'other-role' },
],
);
- const output = await provider.executeStaticTool(
- 'list_roles',
+ const output = await buildListRolesTool(services).execute(
{ includeRowLevelPermissionRules: true },
context,
);
@@ -226,54 +157,47 @@ describe('RoleToolProvider', () => {
});
it('fetches predicates and groups once for the workspace, not per role', async () => {
- const {
- provider,
- roleService,
- rowLevelPermissionPredicateService,
- rowLevelPermissionPredicateGroupService,
- } = buildProvider();
-
- roleService.getWorkspaceRoles.mockResolvedValue([
+ const services = buildServices();
+
+ services.roleService.getWorkspaceRoles.mockResolvedValue([
{ id: 'role-1', label: 'Support', isEditable: true },
{ id: 'role-2', label: 'Sales', isEditable: true },
{ id: 'role-3', label: 'Guest', isEditable: true },
]);
- await provider.executeStaticTool(
- 'list_roles',
+ await buildListRolesTool(services).execute(
{ includeRowLevelPermissionRules: true },
context,
);
expect(
- rowLevelPermissionPredicateService.findByWorkspaceId,
+ services.rowLevelPermissionPredicateService.findByWorkspaceId,
).toHaveBeenCalledTimes(1);
expect(
- rowLevelPermissionPredicateGroupService.findByWorkspaceId,
+ services.rowLevelPermissionPredicateGroupService.findByWorkspaceId,
).toHaveBeenCalledTimes(1);
expect(
- rowLevelPermissionPredicateGroupService.findByWorkspaceId,
+ services.rowLevelPermissionPredicateGroupService.findByWorkspaceId,
).toHaveBeenCalledWith(workspaceId);
});
});
describe('create_role', () => {
it('creates a role through the role service', async () => {
- const { provider, roleService } = buildProvider();
+ const services = buildServices();
- roleService.createRole.mockResolvedValue({
+ services.roleService.createRole.mockResolvedValue({
id: 'new-role-id',
label: 'Sales',
});
- const output = await provider.executeStaticTool(
- 'create_role',
- { label: 'Sales', canReadAllObjectRecords: true },
- context,
- );
+ const output = await new CreateRoleTool(
+ services.roleService as unknown as RoleService,
+ services.applicationService as unknown as ApplicationService,
+ ).execute({ label: 'Sales', canReadAllObjectRecords: true }, context);
expect(output.success).toBe(true);
- expect(roleService.createRole).toHaveBeenCalledWith(
+ expect(services.roleService.createRole).toHaveBeenCalledWith(
expect.objectContaining({
workspaceId,
input: expect.objectContaining({
@@ -287,15 +211,16 @@ describe('RoleToolProvider', () => {
describe('update_role', () => {
it('updates the role, forwarding the caller roles for lockout protection', async () => {
- const { provider, roleService } = buildProvider();
+ const services = buildServices();
- roleService.updateRole.mockResolvedValue({
+ services.roleService.updateRole.mockResolvedValue({
id: otherRoleId,
label: 'Support L1',
});
- const output = await provider.executeStaticTool(
- 'update_role',
+ const output = await new UpdateRoleTool(
+ services.roleService as unknown as RoleService,
+ ).execute(
{
roleId: otherRoleId,
update: { canUpdateAllSettings: false, label: 'Support L1' },
@@ -304,7 +229,7 @@ describe('RoleToolProvider', () => {
);
expect(output.success).toBe(true);
- expect(roleService.updateRole).toHaveBeenCalledWith({
+ expect(services.roleService.updateRole).toHaveBeenCalledWith({
workspaceId,
input: {
id: otherRoleId,
@@ -315,12 +240,13 @@ describe('RoleToolProvider', () => {
});
it('forwards every role of the caller config for lockout protection', async () => {
- const { provider, roleService } = buildProvider();
+ const services = buildServices();
- roleService.updateRole.mockResolvedValue({ id: otherRoleId });
+ services.roleService.updateRole.mockResolvedValue({ id: otherRoleId });
- await provider.executeStaticTool(
- 'update_role',
+ await new UpdateRoleTool(
+ services.roleService as unknown as RoleService,
+ ).execute(
{ roleId: otherRoleId, update: { canUpdateAllSettings: false } },
{
...context,
@@ -333,8 +259,8 @@ describe('RoleToolProvider', () => {
},
);
- expect(roleService.updateRole).toHaveBeenCalledTimes(1);
- expect(roleService.updateRole).toHaveBeenCalledWith(
+ expect(services.roleService.updateRole).toHaveBeenCalledTimes(1);
+ expect(services.roleService.updateRole).toHaveBeenCalledWith(
expect.objectContaining({
actingRoleIds: [callerRoleId, 'application-role-id'],
}),
@@ -342,12 +268,13 @@ describe('RoleToolProvider', () => {
});
it('forwards no caller role when the config bypasses permission checks', async () => {
- const { provider, roleService } = buildProvider();
+ const services = buildServices();
- roleService.updateRole.mockResolvedValue({ id: otherRoleId });
+ services.roleService.updateRole.mockResolvedValue({ id: otherRoleId });
- await provider.executeStaticTool(
- 'update_role',
+ await new UpdateRoleTool(
+ services.roleService as unknown as RoleService,
+ ).execute(
{ roleId: otherRoleId, update: { canUpdateAllSettings: false } },
{
...context,
@@ -355,8 +282,8 @@ describe('RoleToolProvider', () => {
},
);
- expect(roleService.updateRole).toHaveBeenCalledTimes(1);
- expect(roleService.updateRole).toHaveBeenCalledWith(
+ expect(services.roleService.updateRole).toHaveBeenCalledTimes(1);
+ expect(services.roleService.updateRole).toHaveBeenCalledWith(
expect.objectContaining({ actingRoleIds: [] }),
);
});
@@ -364,21 +291,19 @@ describe('RoleToolProvider', () => {
describe('delete_role', () => {
it('deletes the role, forwarding the caller roles for lockout protection', async () => {
- const { provider, roleService } = buildProvider();
+ const services = buildServices();
- roleService.deleteRole.mockResolvedValue({
+ services.roleService.deleteRole.mockResolvedValue({
id: otherRoleId,
label: 'Support',
});
- const output = await provider.executeStaticTool(
- 'delete_role',
- { roleId: otherRoleId },
- context,
- );
+ const output = await new DeleteRoleTool(
+ services.roleService as unknown as RoleService,
+ ).execute({ roleId: otherRoleId }, context);
expect(output.success).toBe(true);
- expect(roleService.deleteRole).toHaveBeenCalledWith({
+ expect(services.roleService.deleteRole).toHaveBeenCalledWith({
roleId: otherRoleId,
workspaceId,
actingRoleIds: [callerRoleId],
@@ -388,16 +313,19 @@ describe('RoleToolProvider', () => {
describe('assign_role_to_workspace_member', () => {
it('delegates to the user role service with the acting user workspace', async () => {
- const { provider, userRoleService } = buildProvider();
+ const services = buildServices();
- const output = await provider.executeStaticTool(
- 'assign_role_to_workspace_member',
+ const output = await new AssignRoleToWorkspaceMemberTool(
+ services.userRoleService as unknown as UserRoleService,
+ ).execute(
{ workspaceMemberId: targetMemberId, roleId: otherRoleId },
context,
);
expect(output.success).toBe(true);
- expect(userRoleService.assignRoleToWorkspaceMember).toHaveBeenCalledWith({
+ expect(
+ services.userRoleService.assignRoleToWorkspaceMember,
+ ).toHaveBeenCalledWith({
workspaceId,
workspaceMemberId: targetMemberId,
roleId: otherRoleId,
@@ -408,51 +336,34 @@ describe('RoleToolProvider', () => {
describe('upsert_object_permissions', () => {
it('upserts object permission overrides through the service', async () => {
- const { provider, objectPermissionService } = buildProvider();
+ const services = buildServices();
+ const objectPermission = {
+ objectMetadataId: objectMetadataId,
+ canReadObjectRecords: true,
+ canUpdateObjectRecords: false,
+ canSoftDeleteObjectRecords: false,
+ canDestroyObjectRecords: false,
+ };
- objectPermissionService.upsertObjectPermissions.mockResolvedValue([
- {
- objectMetadataId: objectMetadataId,
- canReadObjectRecords: true,
- canUpdateObjectRecords: false,
- canSoftDeleteObjectRecords: false,
- canDestroyObjectRecords: false,
- },
- ]);
+ services.objectPermissionService.upsertObjectPermissions.mockResolvedValue(
+ [objectPermission],
+ );
- const output = await provider.executeStaticTool(
- 'upsert_object_permissions',
- {
- roleId: supportRoleId,
- objectPermissions: [
- {
- objectMetadataId: objectMetadataId,
- canReadObjectRecords: true,
- canUpdateObjectRecords: false,
- canSoftDeleteObjectRecords: false,
- canDestroyObjectRecords: false,
- },
- ],
- },
+ const output = await new UpsertObjectPermissionsTool(
+ services.objectPermissionService as unknown as ObjectPermissionService,
+ ).execute(
+ { roleId: supportRoleId, objectPermissions: [objectPermission] },
context,
);
expect(output.success).toBe(true);
expect(
- objectPermissionService.upsertObjectPermissions,
+ services.objectPermissionService.upsertObjectPermissions,
).toHaveBeenCalledWith({
workspaceId,
input: {
roleId: supportRoleId,
- objectPermissions: [
- {
- objectMetadataId: objectMetadataId,
- canReadObjectRecords: true,
- canUpdateObjectRecords: false,
- canSoftDeleteObjectRecords: false,
- canDestroyObjectRecords: false,
- },
- ],
+ objectPermissions: [objectPermission],
},
});
});
@@ -460,29 +371,37 @@ describe('RoleToolProvider', () => {
describe('upsert_row_level_permission_rules', () => {
it('upserts predicates and injects the object metadata id into groups', async () => {
- const { provider, rowLevelPermissionPredicateService } = buildProvider();
+ const services = buildServices();
- const output = await provider.executeStaticTool(
- 'upsert_row_level_permission_rules',
+ const output = await new UpsertRowLevelPermissionRulesTool(
+ services.rowLevelPermissionPredicateService as unknown as RowLevelPermissionPredicateService,
+ ).execute(
{
roleId: supportRoleId,
objectMetadataId: objectMetadataId,
predicates: [
{
fieldMetadataId: ownerFieldMetadataId,
- operand: 'IS',
+ operand: RowLevelPermissionPredicateOperand.IS,
workspaceMemberFieldMetadataId: workspaceMemberIdFieldMetadataId,
rowLevelPermissionPredicateGroupId: predicateGroupId,
},
],
- predicateGroups: [{ id: predicateGroupId, logicalOperator: 'AND' }],
+ predicateGroups: [
+ {
+ id: predicateGroupId,
+ logicalOperator:
+ RowLevelPermissionPredicateGroupLogicalOperator.AND,
+ },
+ ],
},
context,
);
expect(output.success).toBe(true);
expect(
- rowLevelPermissionPredicateService.upsertRowLevelPermissionPredicates,
+ services.rowLevelPermissionPredicateService
+ .upsertRowLevelPermissionPredicates,
).toHaveBeenCalledWith({
workspaceId,
input: expect.objectContaining({
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/assign-role-to-workspace-member.tool.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/assign-role-to-workspace-member.tool.ts
index c1830c2fb4e..ae1318afc3e 100644
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/assign-role-to-workspace-member.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/assign-role-to-workspace-member.tool.ts
@@ -1,35 +1,47 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
import { z } from 'zod';
-import { type RoleToolContext } from 'src/engine/metadata-modules/role/tools/types/role-tool-context.type';
-import { type RoleToolDependencies } from 'src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { UserRoleService } from 'src/engine/metadata-modules/user-role/user-role.service';
-const assignRoleToWorkspaceMemberSchema = z.object({
+const assignRoleToWorkspaceMemberInputSchema = z.object({
workspaceMemberId: z
.uuid()
.describe('Id of the workspace member to assign the role to'),
roleId: z.uuid().describe('Id of the role to assign'),
});
-type AssignRoleToWorkspaceMemberParams = z.infer<
- typeof assignRoleToWorkspaceMemberSchema
->;
-
-export const createAssignRoleToWorkspaceMemberTool = (
- deps: Pick<RoleToolDependencies, 'userRoleService'>,
- context: RoleToolContext,
-) => ({
- name: 'assign_role_to_workspace_member' as const,
+@DefineTool({
+ name: 'assign_role_to_workspace_member',
+ category: ToolCategory.ROLE,
+ requiredPermissionFlags: [PermissionFlagType.ROLES],
description: `Assign a role to a workspace member, replacing their current role.
You cannot change your own role, assign a role that does not allow user assignment (canBeAssignedToUsers=false), or remove the admin role from the last administrator.`,
- inputSchema: assignRoleToWorkspaceMemberSchema,
- execute: async (parameters: AssignRoleToWorkspaceMemberParams) => {
+})
+export class AssignRoleToWorkspaceMemberTool extends BaseTool<
+ typeof assignRoleToWorkspaceMemberInputSchema
+> {
+ readonly inputSchema = assignRoleToWorkspaceMemberInputSchema;
+
+ constructor(private readonly userRoleService: UserRoleService) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof assignRoleToWorkspaceMemberInputSchema>,
+ { workspaceId, userWorkspaceId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
const { workspaceMember } =
- await deps.userRoleService.assignRoleToWorkspaceMember({
- workspaceId: context.workspaceId,
+ await this.userRoleService.assignRoleToWorkspaceMember({
+ workspaceId,
workspaceMemberId: parameters.workspaceMemberId,
roleId: parameters.roleId,
- actingUserWorkspaceId: context.callerUserWorkspaceId,
+ actingUserWorkspaceId: userWorkspaceId,
});
return {
@@ -41,5 +53,5 @@ You cannot change your own role, assign a role that does not allow user assignme
roleId: parameters.roleId,
},
};
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/create-role.tool.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/create-role.tool.ts
index 3fc598958d6..fe9377d3f9b 100644
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/create-role.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/create-role.tool.ts
@@ -1,11 +1,17 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
import { z } from 'zod';
+import { ApplicationService } from 'src/engine/core-modules/application/application.service';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { RoleService } from 'src/engine/metadata-modules/role/role.service';
import { rolePermissionsSchema } from 'src/engine/metadata-modules/role/tools/schemas/role-permissions.schema';
-import { type RoleToolContext } from 'src/engine/metadata-modules/role/tools/types/role-tool-context.type';
-import { type RoleToolDependencies } from 'src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type';
import { toRoleSummary } from 'src/engine/metadata-modules/role/tools/utils/to-role-summary.util';
-const createRoleSchema = rolePermissionsSchema.extend({
+const createRoleInputSchema = rolePermissionsSchema.extend({
label: z.string().min(1).describe('Display name of the role'),
description: z.string().optional().describe('Optional role description'),
icon: z
@@ -14,27 +20,37 @@ const createRoleSchema = rolePermissionsSchema.extend({
.describe('Optional icon identifier (e.g. "IconUser")'),
});
-type CreateRoleParams = z.infer<typeof createRoleSchema>;
-
-export const createCreateRoleTool = (
- deps: Pick<RoleToolDependencies, 'roleService' | 'applicationService'>,
- context: RoleToolContext,
-) => ({
- name: 'create_role' as const,
+@DefineTool({
+ name: 'create_role',
+ category: ToolCategory.ROLE,
+ requiredPermissionFlags: [PermissionFlagType.ROLES],
description: `Create a new role in this workspace.
Global record permissions (canReadAllObjectRecords, canUpdateAllObjectRecords, ...) and settings access default to false; assignability to users, agents and API keys defaults to true.
After creating the role, use upsert_object_permissions to set per-object overrides and upsert_row_level_permission_rules to restrict which records are visible.
Granting write access on an object without read access is invalid.`,
- inputSchema: createRoleSchema,
- execute: async (parameters: CreateRoleParams) => {
+})
+export class CreateRoleTool extends BaseTool<typeof createRoleInputSchema> {
+ readonly inputSchema = createRoleInputSchema;
+
+ constructor(
+ private readonly roleService: RoleService,
+ private readonly applicationService: ApplicationService,
+ ) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof createRoleInputSchema>,
+ { workspaceId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
const { workspaceCustomFlatApplication } =
- await deps.applicationService.findWorkspaceTwentyStandardAndCustomApplicationOrThrow(
- { workspaceId: context.workspaceId },
+ await this.applicationService.findWorkspaceTwentyStandardAndCustomApplicationOrThrow(
+ { workspaceId },
);
- const role = await deps.roleService.createRole({
- workspaceId: context.workspaceId,
+ const role = await this.roleService.createRole({
+ workspaceId,
input: parameters,
ownerFlatApplication: workspaceCustomFlatApplication,
});
@@ -44,5 +60,5 @@ Granting write access on an object without read access is invalid.`,
message: `Role "${role.label}" created`,
result: toRoleSummary(role),
};
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/delete-role.tool.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/delete-role.tool.ts
index 71643f3e5a6..0f37787af69 100644
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/delete-role.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/delete-role.tool.ts
@@ -1,28 +1,41 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
import { z } from 'zod';
-import { type RoleToolContext } from 'src/engine/metadata-modules/role/tools/types/role-tool-context.type';
-import { type RoleToolDependencies } from 'src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { RoleService } from 'src/engine/metadata-modules/role/role.service';
+import { getRoleIdsFromRolePermissionConfig } from 'src/engine/twenty-orm/utils/get-role-ids-from-role-permission-config.util';
-const deleteRoleSchema = z.object({
+const deleteRoleInputSchema = z.object({
roleId: z.uuid().describe('Id of the role to delete'),
});
-type DeleteRoleParams = z.infer<typeof deleteRoleSchema>;
-
-export const createDeleteRoleTool = (
- deps: Pick<RoleToolDependencies, 'roleService'>,
- context: RoleToolContext,
-) => ({
- name: 'delete_role' as const,
+@DefineTool({
+ name: 'delete_role',
+ category: ToolCategory.ROLE,
+ requiredPermissionFlags: [PermissionFlagType.ROLES],
description: `Delete a role. Members, agents and API keys assigned to it are reassigned to the workspace default role.
System-managed roles (isEditable=false, like Admin), the workspace default role, and roles you are assigned to cannot be deleted.`,
- inputSchema: deleteRoleSchema,
- execute: async (parameters: DeleteRoleParams) => {
- const deletedRole = await deps.roleService.deleteRole({
+})
+export class DeleteRoleTool extends BaseTool<typeof deleteRoleInputSchema> {
+ readonly inputSchema = deleteRoleInputSchema;
+
+ constructor(private readonly roleService: RoleService) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof deleteRoleInputSchema>,
+ { workspaceId, rolePermissionConfig }: ToolProviderContext,
+ ): Promise<ToolOutput> {
+ const deletedRole = await this.roleService.deleteRole({
roleId: parameters.roleId,
- workspaceId: context.workspaceId,
- actingRoleIds: context.callerRoleIds,
+ workspaceId,
+ actingRoleIds: getRoleIdsFromRolePermissionConfig(rolePermissionConfig),
});
return {
@@ -30,5 +43,5 @@ System-managed roles (isEditable=false, like Admin), the workspace default role,
message: `Role "${deletedRole.label}" deleted`,
result: { id: deletedRole.id, label: deletedRole.label },
};
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/list-roles.tool.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/list-roles.tool.ts
index 463e2b94522..2cb2b6124a0 100644
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/list-roles.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/list-roles.tool.ts
@@ -1,10 +1,17 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
import { z } from 'zod';
-import { type RoleToolContext } from 'src/engine/metadata-modules/role/tools/types/role-tool-context.type';
-import { type RoleToolDependencies } from 'src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { RoleService } from 'src/engine/metadata-modules/role/role.service';
import { toRoleSummary } from 'src/engine/metadata-modules/role/tools/utils/to-role-summary.util';
+import { RowLevelPermissionPredicateGroupService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate-group.service';
+import { RowLevelPermissionPredicateService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate.service';
-const listRolesSchema = z.object({
+const listRolesInputSchema = z.object({
includeRowLevelPermissionRules: z
.boolean()
.optional()
@@ -13,28 +20,32 @@ const listRolesSchema = z.object({
),
});
-type ListRolesParams = z.infer<typeof listRolesSchema>;
-
-export const createListRolesTool = (
- deps: Pick<
- RoleToolDependencies,
- | 'roleService'
- | 'rowLevelPermissionPredicateService'
- | 'rowLevelPermissionPredicateGroupService'
- >,
- context: RoleToolContext,
-) => ({
- name: 'list_roles' as const,
+@DefineTool({
+ name: 'list_roles',
+ category: ToolCategory.ROLE,
+ requiredPermissionFlags: [PermissionFlagType.ROLES],
description: `List all roles of this workspace with their permissions.
Returns for each role: global record permissions (canReadAllObjectRecords, ...), settings access (canUpdateAllSettings), per-object permission overrides, permission flags, and assignability (users, agents, API keys).
Roles with isEditable=false (like Admin) are system-managed and cannot be changed.`,
- inputSchema: listRolesSchema,
- execute: async (parameters: ListRolesParams) => {
+})
+export class ListRolesTool extends BaseTool<typeof listRolesInputSchema> {
+ readonly inputSchema = listRolesInputSchema;
+
+ constructor(
+ private readonly roleService: RoleService,
+ private readonly rowLevelPermissionPredicateService: RowLevelPermissionPredicateService,
+ private readonly rowLevelPermissionPredicateGroupService: RowLevelPermissionPredicateGroupService,
+ ) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof listRolesInputSchema>,
+ { workspaceId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
if (!parameters.includeRowLevelPermissionRules) {
- const roles = await deps.roleService.getWorkspaceRoles(
- context.workspaceId,
- );
+ const roles = await this.roleService.getWorkspaceRoles(workspaceId);
return {
success: true,
@@ -44,12 +55,10 @@ Roles with isEditable=false (like Admin) are system-managed and cannot be change
}
const [roles, allPredicates, allPredicateGroups] = await Promise.all([
- deps.roleService.getWorkspaceRoles(context.workspaceId),
- deps.rowLevelPermissionPredicateService.findByWorkspaceId(
- context.workspaceId,
- ),
- deps.rowLevelPermissionPredicateGroupService.findByWorkspaceId(
- context.workspaceId,
+ this.roleService.getWorkspaceRoles(workspaceId),
+ this.rowLevelPermissionPredicateService.findByWorkspaceId(workspaceId),
+ this.rowLevelPermissionPredicateGroupService.findByWorkspaceId(
+ workspaceId,
),
]);
@@ -68,5 +77,5 @@ Roles with isEditable=false (like Admin) are system-managed and cannot be change
message: `Found ${roles.length} role${roles.length === 1 ? '' : 's'}`,
result: { roles: rolesWithRules },
};
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/role-tools.module.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/role-tools.module.ts
new file mode 100644
index 00000000000..f73068ed3df
--- /dev/null
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/role-tools.module.ts
@@ -0,0 +1,34 @@
+import { Module } from '@nestjs/common';
+
+import { ApplicationModule } from 'src/engine/core-modules/application/application.module';
+import { ObjectPermissionModule } from 'src/engine/metadata-modules/object-permission/object-permission.module';
+import { RoleModule } from 'src/engine/metadata-modules/role/role.module';
+import { AssignRoleToWorkspaceMemberTool } from 'src/engine/metadata-modules/role/tools/assign-role-to-workspace-member.tool';
+import { CreateRoleTool } from 'src/engine/metadata-modules/role/tools/create-role.tool';
+import { DeleteRoleTool } from 'src/engine/metadata-modules/role/tools/delete-role.tool';
+import { ListRolesTool } from 'src/engine/metadata-modules/role/tools/list-roles.tool';
+import { UpdateRoleTool } from 'src/engine/metadata-modules/role/tools/update-role.tool';
+import { UpsertObjectPermissionsTool } from 'src/engine/metadata-modules/role/tools/upsert-object-permissions.tool';
+import { UpsertRowLevelPermissionRulesTool } from 'src/engine/metadata-modules/role/tools/upsert-row-level-permission-rules.tool';
+import { RowLevelPermissionModule } from 'src/engine/metadata-modules/row-level-permission-predicate/row-level-permission.module';
+import { UserRoleModule } from 'src/engine/metadata-modules/user-role/user-role.module';
+
+@Module({
+ imports: [
+ RoleModule,
+ UserRoleModule,
+ ObjectPermissionModule,
+ RowLevelPermissionModule,
+ ApplicationModule,
+ ],
+ providers: [
+ ListRolesTool,
+ CreateRoleTool,
+ UpdateRoleTool,
+ DeleteRoleTool,
+ AssignRoleToWorkspaceMemberTool,
+ UpsertObjectPermissionsTool,
+ UpsertRowLevelPermissionRulesTool,
+ ],
+})
+export class RoleToolsModule {}
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/services/role-tool.workspace-service.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/services/role-tool.workspace-service.ts
deleted file mode 100644
index 27cfd4b2575..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/services/role-tool.workspace-service.ts
+++ /dev/null
@@ -1,69 +0,0 @@
-import { Injectable } from '@nestjs/common';
-
-import { type ToolSet } from 'ai';
-
-import { ApplicationService } from 'src/engine/core-modules/application/application.service';
-import { ObjectPermissionService } from 'src/engine/metadata-modules/object-permission/object-permission.service';
-import { RoleService } from 'src/engine/metadata-modules/role/role.service';
-import { createAssignRoleToWorkspaceMemberTool } from 'src/engine/metadata-modules/role/tools/assign-role-to-workspace-member.tool';
-import { createCreateRoleTool } from 'src/engine/metadata-modules/role/tools/create-role.tool';
-import { createDeleteRoleTool } from 'src/engine/metadata-modules/role/tools/delete-role.tool';
-import { createListRolesTool } from 'src/engine/metadata-modules/role/tools/list-roles.tool';
-import { type RoleToolContext } from 'src/engine/metadata-modules/role/tools/types/role-tool-context.type';
-import { type RoleToolDependencies } from 'src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type';
-import { createUpdateRoleTool } from 'src/engine/metadata-modules/role/tools/update-role.tool';
-import { createUpsertObjectPermissionsTool } from 'src/engine/metadata-modules/role/tools/upsert-object-permissions.tool';
-import { createUpsertRowLevelPermissionRulesTool } from 'src/engine/metadata-modules/role/tools/upsert-row-level-permission-rules.tool';
-import { RowLevelPermissionPredicateGroupService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate-group.service';
-import { RowLevelPermissionPredicateService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate.service';
-import { UserRoleService } from 'src/engine/metadata-modules/user-role/user-role.service';
-
-@Injectable()
-export class RoleToolWorkspaceService {
- private readonly deps: RoleToolDependencies;
-
- constructor(
- roleService: RoleService,
- userRoleService: UserRoleService,
- objectPermissionService: ObjectPermissionService,
- rowLevelPermissionPredicateService: RowLevelPermissionPredicateService,
- rowLevelPermissionPredicateGroupService: RowLevelPermissionPredicateGroupService,
- applicationService: ApplicationService,
- ) {
- this.deps = {
- roleService,
- userRoleService,
- objectPermissionService,
- rowLevelPermissionPredicateService,
- rowLevelPermissionPredicateGroupService,
- applicationService,
- };
- }
-
- generateRoleTools(context: RoleToolContext): ToolSet {
- const listRoles = createListRolesTool(this.deps, context);
- const createRole = createCreateRoleTool(this.deps, context);
- const updateRole = createUpdateRoleTool(this.deps, context);
- const deleteRole = createDeleteRoleTool(this.deps, context);
- const assignRoleToWorkspaceMember = createAssignRoleToWorkspaceMemberTool(
- this.deps,
- context,
- );
- const upsertObjectPermissions = createUpsertObjectPermissionsTool(
- this.deps,
- context,
- );
- const upsertRowLevelPermissionRules =
- createUpsertRowLevelPermissionRulesTool(this.deps, context);
-
- return {
- [listRoles.name]: listRoles,
- [createRole.name]: createRole,
- [updateRole.name]: updateRole,
- [deleteRole.name]: deleteRole,
- [assignRoleToWorkspaceMember.name]: assignRoleToWorkspaceMember,
- [upsertObjectPermissions.name]: upsertObjectPermissions,
- [upsertRowLevelPermissionRules.name]: upsertRowLevelPermissionRules,
- };
- }
-}
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/types/role-tool-context.type.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/types/role-tool-context.type.ts
deleted file mode 100644
index fa672cf09ac..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/types/role-tool-context.type.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-export type RoleToolContext = {
- workspaceId: string;
- callerRoleIds: string[];
- callerUserWorkspaceId?: string;
-};
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type.ts
deleted file mode 100644
index 2ce4830c2a5..00000000000
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import type { ApplicationService } from 'src/engine/core-modules/application/application.service';
-import type { ObjectPermissionService } from 'src/engine/metadata-modules/object-permission/object-permission.service';
-import type { RoleService } from 'src/engine/metadata-modules/role/role.service';
-import type { RowLevelPermissionPredicateGroupService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate-group.service';
-import type { RowLevelPermissionPredicateService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate.service';
-import type { UserRoleService } from 'src/engine/metadata-modules/user-role/user-role.service';
-
-export type RoleToolDependencies = {
- roleService: RoleService;
- userRoleService: UserRoleService;
- objectPermissionService: ObjectPermissionService;
- rowLevelPermissionPredicateService: RowLevelPermissionPredicateService;
- rowLevelPermissionPredicateGroupService: RowLevelPermissionPredicateGroupService;
- applicationService: ApplicationService;
-};
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/update-role.tool.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/update-role.tool.ts
index bcdfb6e8463..b55e9e09682 100644
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/update-role.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/update-role.tool.ts
@@ -1,11 +1,17 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
import { z } from 'zod';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { RoleService } from 'src/engine/metadata-modules/role/role.service';
import { rolePermissionsSchema } from 'src/engine/metadata-modules/role/tools/schemas/role-permissions.schema';
-import { type RoleToolContext } from 'src/engine/metadata-modules/role/tools/types/role-tool-context.type';
-import { type RoleToolDependencies } from 'src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type';
import { toRoleSummary } from 'src/engine/metadata-modules/role/tools/utils/to-role-summary.util';
+import { getRoleIdsFromRolePermissionConfig } from 'src/engine/twenty-orm/utils/get-role-ids-from-role-permission-config.util';
-const updateRoleSchema = z.object({
+const updateRoleInputSchema = z.object({
roleId: z.uuid().describe('Id of the role to update'),
update: rolePermissionsSchema
.extend({
@@ -16,25 +22,32 @@ const updateRoleSchema = z.object({
.describe('Fields to change; omitted fields are left untouched'),
});
-type UpdateRoleParams = z.infer<typeof updateRoleSchema>;
-
-export const createUpdateRoleTool = (
- deps: Pick<RoleToolDependencies, 'roleService'>,
- context: RoleToolContext,
-) => ({
- name: 'update_role' as const,
+@DefineTool({
+ name: 'update_role',
+ category: ToolCategory.ROLE,
+ requiredPermissionFlags: [PermissionFlagType.ROLES],
description: `Update an existing role's label, description, icon, global record permissions, settings access, or assignability.
System-managed roles (isEditable=false, like Admin) cannot be updated. Updates that would remove your own access to role management are rejected.`,
- inputSchema: updateRoleSchema,
- execute: async (parameters: UpdateRoleParams) => {
- const role = await deps.roleService.updateRole({
- workspaceId: context.workspaceId,
+})
+export class UpdateRoleTool extends BaseTool<typeof updateRoleInputSchema> {
+ readonly inputSchema = updateRoleInputSchema;
+
+ constructor(private readonly roleService: RoleService) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof updateRoleInputSchema>,
+ { workspaceId, rolePermissionConfig }: ToolProviderContext,
+ ): Promise<ToolOutput> {
+ const role = await this.roleService.updateRole({
+ workspaceId,
input: {
id: parameters.roleId,
update: parameters.update,
},
- actingRoleIds: context.callerRoleIds,
+ actingRoleIds: getRoleIdsFromRolePermissionConfig(rolePermissionConfig),
});
return {
@@ -42,5 +55,5 @@ System-managed roles (isEditable=false, like Admin) cannot be updated. Updates t
message: `Role "${role.label}" updated`,
result: toRoleSummary(role),
};
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/upsert-object-permissions.tool.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/upsert-object-permissions.tool.ts
index 7f65ea71d84..f286afa053c 100644
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/upsert-object-permissions.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/upsert-object-permissions.tool.ts
@@ -1,10 +1,15 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
import { z } from 'zod';
-import { type RoleToolContext } from 'src/engine/metadata-modules/role/tools/types/role-tool-context.type';
-import { type RoleToolDependencies } from 'src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { ObjectPermissionService } from 'src/engine/metadata-modules/object-permission/object-permission.service';
import { toObjectPermissionSummary } from 'src/engine/metadata-modules/role/tools/utils/to-role-summary.util';
-const upsertObjectPermissionsSchema = z.object({
+const upsertObjectPermissionsInputSchema = z.object({
roleId: z.uuid().describe('Id of the role to set overrides on'),
objectPermissions: z
.array(
@@ -36,25 +41,34 @@ const upsertObjectPermissionsSchema = z.object({
),
});
-type UpsertObjectPermissionsParams = z.infer<
- typeof upsertObjectPermissionsSchema
->;
-
-export const createUpsertObjectPermissionsTool = (
- deps: Pick<RoleToolDependencies, 'objectPermissionService'>,
- context: RoleToolContext,
-) => ({
- name: 'upsert_object_permissions' as const,
+@DefineTool({
+ name: 'upsert_object_permissions',
+ category: ToolCategory.ROLE,
+ requiredPermissionFlags: [PermissionFlagType.ROLES],
description: `Set per-object permission overrides on a role, e.g. make an object read-only for that role.
IMPORTANT: this replaces the role's full override list. Include every override you want to keep; objects omitted from the list revert to the role's global permissions (canReadAllObjectRecords, ...). Use list_roles first to see current overrides.
Example read-only override: { objectMetadataId, canReadObjectRecords: true, canUpdateObjectRecords: false, canSoftDeleteObjectRecords: false, canDestroyObjectRecords: false }.
Granting write access without read access is rejected. System-managed roles (like Admin) cannot be changed.`,
- inputSchema: upsertObjectPermissionsSchema,
- execute: async (parameters: UpsertObjectPermissionsParams) => {
+})
+export class UpsertObjectPermissionsTool extends BaseTool<
+ typeof upsertObjectPermissionsInputSchema
+> {
+ readonly inputSchema = upsertObjectPermissionsInputSchema;
+
+ constructor(
+ private readonly objectPermissionService: ObjectPermissionService,
+ ) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof upsertObjectPermissionsInputSchema>,
+ { workspaceId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
const objectPermissions =
- await deps.objectPermissionService.upsertObjectPermissions({
- workspaceId: context.workspaceId,
+ await this.objectPermissionService.upsertObjectPermissions({
+ workspaceId,
input: {
roleId: parameters.roleId,
objectPermissions: parameters.objectPermissions,
@@ -69,5 +83,5 @@ Granting write access without read access is rejected. System-managed roles (lik
objectPermissions: objectPermissions.map(toObjectPermissionSummary),
},
};
- },
-});
+ }
+}
diff --git a/packages/twenty-server/src/engine/metadata-modules/role/tools/upsert-row-level-permission-rules.tool.ts b/packages/twenty-server/src/engine/metadata-modules/role/tools/upsert-row-level-permission-rules.tool.ts
index 175359eaf68..c83e1352a79 100644
--- a/packages/twenty-server/src/engine/metadata-modules/role/tools/upsert-row-level-permission-rules.tool.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/role/tools/upsert-row-level-permission-rules.tool.ts
@@ -1,11 +1,16 @@
+import { ToolCategory } from 'twenty-shared/ai';
+import { PermissionFlagType } from 'twenty-shared/constants';
import {
RowLevelPermissionPredicateGroupLogicalOperator,
RowLevelPermissionPredicateOperand,
} from 'twenty-shared/types';
import { z } from 'zod';
-import { type RoleToolContext } from 'src/engine/metadata-modules/role/tools/types/role-tool-context.type';
-import { type RoleToolDependencies } from 'src/engine/metadata-modules/role/tools/types/role-tool-dependencies.type';
+import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
+import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
+import { type ToolProviderContext } from 'src/engine/core-modules/tool-provider/interfaces/tool-provider-context.type';
+import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
+import { RowLevelPermissionPredicateService } from 'src/engine/metadata-modules/row-level-permission-predicate/services/row-level-permission-predicate.service';
const predicateValueSchema = z
.union([
@@ -90,7 +95,7 @@ const rowLevelPermissionPredicateGroupSchema = z.object({
.describe('Position of this group within its parent'),
});
-const upsertRowLevelPermissionRulesSchema = z.object({
+const upsertRowLevelPermissionRulesInputSchema = z.object({
roleId: z.uuid().describe('Id of the role the rules apply to'),
objectMetadataId: z.uuid().describe('Id of the object the rules restrict'),
predicates: z
@@ -105,27 +110,36 @@ const upsertRowLevelPermissionRulesSchema = z.object({
),
});
-type UpsertRowLevelPermissionRulesParams = z.infer<
- typeof upsertRowLevelPermissionRulesSchema
->;
-
-export const createUpsertRowLevelPermissionRulesTool = (
- deps: Pick<RoleToolDependencies, 'rowLevelPermissionPredicateService'>,
- context: RoleToolContext,
-) => ({
- name: 'upsert_row_level_permission_rules' as const,
+@DefineTool({
+ name: 'upsert_row_level_permission_rules',
+ category: ToolCategory.ROLE,
+ requiredPermissionFlags: [PermissionFlagType.ROLES],
description: `Set row-level permission rules restricting which records members with a role can see on a given object (enterprise feature).
Example, "members with this role only see records where the owner field matches the current user": pass one predicate with fieldMetadataId = the owner field on the object, operand = IS, and workspaceMemberFieldMetadataId = the "id" field of the workspaceMember object (resolved to the current user at query time). Use metadata tools to look up field ids.
The same works between relations: for "only records in my region", pass fieldMetadataId = a many-to-one relation on the object and workspaceMemberFieldMetadataId = a many-to-one relation on workspaceMember pointing at the same object, with operand IS.
Combine several predicates with predicateGroups (AND / OR): give each new group a client-generated UUID and reference it from predicates via rowLevelPermissionPredicateGroupId.
IMPORTANT: this replaces the full rule set for the role + object. Predicates or groups omitted from the lists are deleted; empty lists clear all rules. System-managed roles (like Admin) cannot be changed.`,
- inputSchema: upsertRowLevelPermissionRulesSchema,
- execute: async (parameters: UpsertRowLevelPermissionRulesParams) => {
+})
+export class UpsertRowLevelPermissionRulesTool extends BaseTool<
+ typeof upsertRowLevelPermissionRulesInputSchema
+> {
+ readonly inputSchema = upsertRowLevelPermissionRulesInputSchema;
+
+ constructor(
+ private readonly rowLevelPermissionPredicateService: RowLevelPermissionPredicateService,
+ ) {
+ super();
+ }
+
+ async execute(
+ parameters: z.infer<typeof upsertRowLevelPermissionRulesInputSchema>,
+ { workspaceId }: ToolProviderContext,
+ ): Promise<ToolOutput> {
const { predicates, predicateGroups } =
- await deps.rowLevelPermissionPredicateService.upsertRowLevelPermissionPredicates(
+ await this.rowLevelPermissionPredicateService.upsertRowLevelPermissionPredicates(
{
- workspaceId: context.workspaceId,
+ workspaceId,
input: {
roleId: parameters.roleId,
objectMetadataId: parameters.objectMetadataId,
@@ -145,5 +159,5 @@ IMPORTANT: this replaces the full rule set for the role + object. Predicates or
message: `Row-level permission rules updated (${predicates.length} predicate${predicates.length === 1 ? '' : 's'}, ${predicateGroups.length} group${predicateGroups.length === 1 ? '' : 's'})`,
result: { predicates, predicateGroups },
};
- },
-});
+ }
+}
diff --git a/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-role-tools.integration-spec.ts.snap b/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-role-tools.integration-spec.ts.snap
new file mode 100644
index 00000000000..b94e9ba9f43
--- /dev/null
+++ b/packages/twenty-server/test/integration/ai/suites/__snapshots__/mcp-role-tools.integration-spec.ts.snap
@@ -0,0 +1,472 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`MCP role tools (integration) should describe the role tools to the model 1`] = `
+[
+ {
+ "description": "List all roles of this workspace with their permissions.
+
+Returns for each role: global record permissions (canReadAllObjectRecords, ...), settings access (canUpdateAllSettings), per-object permission overrides, permission flags, and assignability (users, agents, API keys).
+Roles with isEditable=false (like Admin) are system-managed and cannot be changed.",
+ "inputSchema": {
+ "properties": {
+ "includeRowLevelPermissionRules": {
+ "description": "When true, include each role's row-level permission predicates and predicate groups (enterprise feature; empty when disabled).",
+ "type": "boolean",
+ },
+ },
+ "type": "object",
+ },
+ "name": "list_roles",
+ },
+ {
+ "description": "Create a new role in this workspace.
+
+Global record permissions (canReadAllObjectRecords, canUpdateAllObjectRecords, ...) and settings access default to false; assignability to users, agents and API keys defaults to true.
+After creating the role, use upsert_object_permissions to set per-object overrides and upsert_row_level_permission_rules to restrict which records are visible.
+Granting write access on an object without read access is invalid.",
+ "inputSchema": {
+ "properties": {
+ "canAccessAllTools": {
+ "description": "Grants access to all workspace tools",
+ "type": "boolean",
+ },
+ "canBeAssignedToAgents": {
+ "description": "Whether the role can be assigned to AI agents",
+ "type": "boolean",
+ },
+ "canBeAssignedToApiKeys": {
+ "description": "Whether the role can be assigned to API keys",
+ "type": "boolean",
+ },
+ "canBeAssignedToUsers": {
+ "description": "Whether the role can be assigned to users",
+ "type": "boolean",
+ },
+ "canDestroyAllObjectRecords": {
+ "description": "Default destroy access on all objects",
+ "type": "boolean",
+ },
+ "canReadAllObjectRecords": {
+ "description": "Default read access on all objects",
+ "type": "boolean",
+ },
+ "canSoftDeleteAllObjectRecords": {
+ "description": "Default soft-delete access on all objects",
+ "type": "boolean",
+ },
+ "canUpdateAllObjectRecords": {
+ "description": "Default update access on all objects",
+ "type": "boolean",
+ },
+ "canUpdateAllSettings": {
+ "description": "Grants full settings/admin access",
+ "type": "boolean",
+ },
+ "description": {
+ "description": "Optional role description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "Optional icon identifier (e.g. "IconUser")",
+ "type": "string",
+ },
+ "label": {
+ "description": "Display name of the role",
+ "minLength": 1,
+ "type": "string",
+ },
+ },
+ "required": [
+ "label",
+ ],
+ "type": "object",
+ },
+ "name": "create_role",
+ },
+ {
+ "description": "Update an existing role's label, description, icon, global record permissions, settings access, or assignability.
+
+System-managed roles (isEditable=false, like Admin) cannot be updated. Updates that would remove your own access to role management are rejected.",
+ "inputSchema": {
+ "properties": {
+ "roleId": {
+ "description": "Id of the role to update",
+ "format": "uuid",
+ "type": "string",
+ },
+ "update": {
+ "description": "Fields to change; omitted fields are left untouched",
+ "properties": {
+ "canAccessAllTools": {
+ "description": "Grants access to all workspace tools",
+ "type": "boolean",
+ },
+ "canBeAssignedToAgents": {
+ "description": "Whether the role can be assigned to AI agents",
+ "type": "boolean",
+ },
+ "canBeAssignedToApiKeys": {
+ "description": "Whether the role can be assigned to API keys",
+ "type": "boolean",
+ },
+ "canBeAssignedToUsers": {
+ "description": "Whether the role can be assigned to users",
+ "type": "boolean",
+ },
+ "canDestroyAllObjectRecords": {
+ "description": "Default destroy access on all objects",
+ "type": "boolean",
+ },
+ "canReadAllObjectRecords": {
+ "description": "Default read access on all objects",
+ "type": "boolean",
+ },
+ "canSoftDeleteAllObjectRecords": {
+ "description": "Default soft-delete access on all objects",
+ "type": "boolean",
+ },
+ "canUpdateAllObjectRecords": {
+ "description": "Default update access on all objects",
+ "type": "boolean",
+ },
+ "canUpdateAllSettings": {
+ "description": "Grants full settings/admin access",
+ "type": "boolean",
+ },
+ "description": {
+ "description": "New description",
+ "type": "string",
+ },
+ "icon": {
+ "description": "New icon identifier",
+ "type": "string",
+ },
+ "label": {
+ "description": "New display name",
+ "minLength": 1,
+ "type": "string",
+ },
+ },
+ "type": "object",
+ },
+ },
+ "required": [
+ "roleId",
+ "update",
+ ],
+ "type": "object",
+ },
+ "name": "update_role",
+ },
+ {
+ "description": "Delete a role. Members, agents and API keys assigned to it are reassigned to the workspace default role.
+
+System-managed roles (isEditable=false, like Admin), the workspace default role, and roles you are assigned to cannot be deleted.",
+ "inputSchema": {
+ "properties": {
+ "roleId": {
+ "description": "Id of the role to delete",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "roleId",
+ ],
+ "type": "object",
+ },
+ "name": "delete_role",
+ },
+ {
+ "description": "Assign a role to a workspace member, replacing their current role.
+
+You cannot change your own role, assign a role that does not allow user assignment (canBeAssignedToUsers=false), or remove the admin role from the last administrator.",
+ "inputSchema": {
+ "properties": {
+ "roleId": {
+ "description": "Id of the role to assign",
+ "format": "uuid",
+ "type": "string",
+ },
+ "workspaceMemberId": {
+ "description": "Id of the workspace member to assign the role to",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "workspaceMemberId",
+ "roleId",
+ ],
+ "type": "object",
+ },
+ "name": "assign_role_to_workspace_member",
+ },
+ {
+ "description": "Set per-object permission overrides on a role, e.g. make an object read-only for that role.
+
+IMPORTANT: this replaces the role's full override list. Include every override you want to keep; objects omitted from the list revert to the role's global permissions (canReadAllObjectRecords, ...). Use list_roles first to see current overrides.
+Example read-only override: { objectMetadataId, canReadObjectRecords: true, canUpdateObjectRecords: false, canSoftDeleteObjectRecords: false, canDestroyObjectRecords: false }.
+Granting write access without read access is rejected. System-managed roles (like Admin) cannot be changed.",
+ "inputSchema": {
+ "properties": {
+ "objectPermissions": {
+ "description": "The complete set of per-object overrides to keep on the role. Overrides for objects omitted from this list are removed and fall back to the role's global permissions.",
+ "items": {
+ "properties": {
+ "canDestroyObjectRecords": {
+ "description": "Override destroy access for this object",
+ "type": "boolean",
+ },
+ "canReadObjectRecords": {
+ "description": "Override read access for this object",
+ "type": "boolean",
+ },
+ "canSoftDeleteObjectRecords": {
+ "description": "Override soft-delete access for this object",
+ "type": "boolean",
+ },
+ "canUpdateObjectRecords": {
+ "description": "Override update access for this object",
+ "type": "boolean",
+ },
+ "objectMetadataId": {
+ "description": "Id of the object metadata the override applies to",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "objectMetadataId",
+ ],
+ "type": "object",
+ },
+ "minItems": 1,
+ "type": "array",
+ },
+ "roleId": {
+ "description": "Id of the role to set overrides on",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "roleId",
+ "objectPermissions",
+ ],
+ "type": "object",
+ },
+ "name": "upsert_object_permissions",
+ },
+ {
+ "description": "Set row-level permission rules restricting which records members with a role can see on a given object (enterprise feature).
+
+Example, "members with this role only see records where the owner field matches the current user": pass one predicate with fieldMetadataId = the owner field on the object, operand = IS, and workspaceMemberFieldMetadataId = the "id" field of the workspaceMember object (resolved to the current user at query time). Use metadata tools to look up field ids.
+The same works between relations: for "only records in my region", pass fieldMetadataId = a many-to-one relation on the object and workspaceMemberFieldMetadataId = a many-to-one relation on workspaceMember pointing at the same object, with operand IS.
+Combine several predicates with predicateGroups (AND / OR): give each new group a client-generated UUID and reference it from predicates via rowLevelPermissionPredicateGroupId.
+IMPORTANT: this replaces the full rule set for the role + object. Predicates or groups omitted from the lists are deleted; empty lists clear all rules. System-managed roles (like Admin) cannot be changed.",
+ "inputSchema": {
+ "properties": {
+ "objectMetadataId": {
+ "description": "Id of the object the rules restrict",
+ "format": "uuid",
+ "type": "string",
+ },
+ "predicateGroups": {
+ "description": "The complete list of predicate groups to keep for this role and object. Existing groups omitted from the list are deleted.",
+ "items": {
+ "properties": {
+ "id": {
+ "description": "Group id. Pass an existing id to update a group, or a new client-generated UUID so predicates can reference the group via rowLevelPermissionPredicateGroupId.",
+ "format": "uuid",
+ "type": "string",
+ },
+ "logicalOperator": {
+ "description": "How predicates inside this group are combined (AND / OR)",
+ "enum": [
+ "AND",
+ "OR",
+ ],
+ "type": "string",
+ },
+ "parentRowLevelPermissionPredicateGroupId": {
+ "anyOf": [
+ {
+ "format": "uuid",
+ "type": "string",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Parent group id for nested groups",
+ },
+ "positionInRowLevelPermissionPredicateGroup": {
+ "anyOf": [
+ {
+ "type": "number",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Position of this group within its parent",
+ },
+ },
+ "required": [
+ "logicalOperator",
+ ],
+ "type": "object",
+ },
+ "type": "array",
+ },
+ "predicates": {
+ "description": "The complete list of predicates to keep for this role and object. Existing predicates omitted from the list are deleted; pass an empty array to remove all rules.",
+ "items": {
+ "properties": {
+ "fieldMetadataId": {
+ "description": "Id of the field (on the target object) the rule filters on",
+ "format": "uuid",
+ "type": "string",
+ },
+ "id": {
+ "description": "Id of an existing predicate to update. Omit to create a new one.",
+ "format": "uuid",
+ "type": "string",
+ },
+ "operand": {
+ "description": "Comparison operator",
+ "enum": [
+ "IS",
+ "IS_NOT_NULL",
+ "IS_NOT",
+ "LESS_THAN_OR_EQUAL",
+ "GREATER_THAN_OR_EQUAL",
+ "IS_BEFORE",
+ "IS_AFTER",
+ "CONTAINS",
+ "DOES_NOT_CONTAIN",
+ "IS_EMPTY",
+ "IS_NOT_EMPTY",
+ "IS_RELATIVE",
+ "IS_IN_PAST",
+ "IS_IN_FUTURE",
+ "IS_TODAY",
+ "VECTOR_SEARCH",
+ ],
+ "type": "string",
+ },
+ "positionInRowLevelPermissionPredicateGroup": {
+ "anyOf": [
+ {
+ "type": "number",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Position of this predicate within its group",
+ },
+ "rowLevelPermissionPredicateGroupId": {
+ "anyOf": [
+ {
+ "format": "uuid",
+ "type": "string",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Id of the predicate group this predicate belongs to",
+ },
+ "subFieldName": {
+ "anyOf": [
+ {
+ "type": "string",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Sub-field for composite fields (e.g. "firstName" of a FULL_NAME field)",
+ },
+ "value": {
+ "anyOf": [
+ {
+ "type": "string",
+ },
+ {
+ "items": {
+ "type": "string",
+ },
+ "type": "array",
+ },
+ {
+ "type": "boolean",
+ },
+ {
+ "type": "number",
+ },
+ {
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ },
+ "type": "object",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Static value to compare the field against. Omit when using workspaceMemberFieldMetadataId or a value-less operand (IS_EMPTY, IS_IN_PAST, ...).",
+ },
+ "workspaceMemberFieldMetadataId": {
+ "anyOf": [
+ {
+ "format": "uuid",
+ "type": "string",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Dynamic comparison: id of a field on the workspaceMember object whose value for the CURRENT user is substituted at query time. Use the workspaceMember "id" field to express "matches the current user", or a many-to-one relation field to compare against a relation on the record pointing at the same object.",
+ },
+ "workspaceMemberSubFieldName": {
+ "anyOf": [
+ {
+ "type": "string",
+ },
+ {
+ "type": "null",
+ },
+ ],
+ "description": "Sub-field of the workspace member field when it is a composite field",
+ },
+ },
+ "required": [
+ "fieldMetadataId",
+ "operand",
+ ],
+ "type": "object",
+ },
+ "type": "array",
+ },
+ "roleId": {
+ "description": "Id of the role the rules apply to",
+ "format": "uuid",
+ "type": "string",
+ },
+ },
+ "required": [
+ "roleId",
+ "objectMetadataId",
+ "predicates",
+ "predicateGroups",
+ ],
+ "type": "object",
+ },
+ "name": "upsert_row_level_permission_rules",
+ },
+]
+`;
diff --git a/packages/twenty-server/test/integration/ai/suites/mcp-role-tools.integration-spec.ts b/packages/twenty-server/test/integration/ai/suites/mcp-role-tools.integration-spec.ts
new file mode 100644
index 00000000000..a11698d3efd
--- /dev/null
+++ b/packages/twenty-server/test/integration/ai/suites/mcp-role-tools.integration-spec.ts
@@ -0,0 +1,150 @@
+import { executeToolThroughMcp } from 'test/integration/ai/utils/execute-tool-through-mcp.util';
+import { callMcpTool } from 'test/integration/graphql/suites/application-role-intersection/utils/call-mcp-tool.util';
+import { findObjectMetadataIdByName } from 'test/integration/graphql/suites/application-role-intersection/utils/find-object-metadata-id-by-name.util';
+import { getMcpToolCatalog } from 'test/integration/graphql/suites/application-role-intersection/utils/get-mcp-tool-catalog.util';
+import { jestExpectToBeDefined } from 'test/utils/jest-expect-to-be-defined.util.test';
+import { ToolCategory } from 'twenty-shared/ai';
+
+const ROLE_TOOL_NAMES = [
+ 'list_roles',
+ 'create_role',
+ 'update_role',
+ 'delete_role',
+ 'assign_role_to_workspace_member',
+ 'upsert_object_permissions',
+ 'upsert_row_level_permission_rules',
+];
+
+const ROLE_LABEL = 'MCP role tools integration role';
+const RENAMED_ROLE_LABEL = `${ROLE_LABEL} renamed`;
+
+type RoleSummary = { id: string; label: string };
+
+const listRolesThroughMcp = async (): Promise<RoleSummary[]> => {
+ const output = await executeToolThroughMcp<{ roles: RoleSummary[] }>({
+ toolName: 'list_roles',
+ toolArguments: {},
+ });
+
+ expect(output.success).toBe(true);
+
+ return output.result?.roles ?? [];
+};
+
+describe('MCP role tools (integration)', () => {
+ afterAll(async () => {
+ const leakedRoles = (await listRolesThroughMcp()).filter(({ label }) =>
+ label.startsWith(ROLE_LABEL),
+ );
+
+ for (const { id } of leakedRoles) {
+ await executeToolThroughMcp({
+ toolName: 'delete_role',
+ toolArguments: { roleId: id },
+ });
+ }
+ });
+
+ it('should describe the role tools to the model', async () => {
+ const result = await callMcpTool({
+ toolName: 'learn_tools',
+ toolArguments: { toolNames: ROLE_TOOL_NAMES },
+ token: API_KEY_ACCESS_TOKEN,
+ });
+
+ expect(result.isError).toBe(false);
+
+ const payload = JSON.parse(result.content[0].text);
+
+ expect(payload.notFound).toEqual([]);
+ expect(payload.tools).toMatchSnapshot();
+ });
+
+ it('should create, restrict, rename and delete a role', async () => {
+ const created = await executeToolThroughMcp<RoleSummary>({
+ toolName: 'create_role',
+ toolArguments: { label: ROLE_LABEL, canReadAllObjectRecords: true },
+ });
+
+ expect(created).toMatchObject({
+ success: true,
+ message: `Role "${ROLE_LABEL}" created`,
+ result: { label: ROLE_LABEL, canReadAllObjectRecords: true },
+ });
+
+ const roleId = created.result?.id;
+
+ jestExpectToBeDefined(roleId);
+ expect((await listRolesThroughMcp()).map(({ id }) => id)).toContain(roleId);
+
+ const companyObjectMetadataId = await findObjectMetadataIdByName('company');
+ const companyReadOnlyPermission = {
+ objectMetadataId: companyObjectMetadataId,
+ canReadObjectRecords: true,
+ canUpdateObjectRecords: false,
+ canSoftDeleteObjectRecords: false,
+ canDestroyObjectRecords: false,
+ };
+
+ const restricted = await executeToolThroughMcp({
+ toolName: 'upsert_object_permissions',
+ toolArguments: { roleId, objectPermissions: [companyReadOnlyPermission] },
+ });
+
+ expect(restricted).toMatchObject({
+ success: true,
+ message: 'Object permissions updated',
+ result: { roleId, objectPermissions: [companyReadOnlyPermission] },
+ });
+
+ const renamed = await executeToolThroughMcp<RoleSummary>({
+ toolName: 'update_role',
+ toolArguments: { roleId, update: { label: RENAMED_ROLE_LABEL } },
+ });
+
+ expect(renamed).toMatchObject({
+ success: true,
+ message: `Role "${RENAMED_ROLE_LABEL}" updated`,
+ result: { id: roleId, label: RENAMED_ROLE_LABEL },
+ });
+
+ const deleted = await executeToolThroughMcp({
+ toolName: 'delete_role',
+ toolArguments: { roleId },
+ });
+
+ expect(deleted).toEqual({
+ success: true,
+ message: `Role "${RENAMED_ROLE_LABEL}" deleted`,
+ result: { id: roleId, label: RENAMED_ROLE_LABEL },
+ });
+ expect((await listRolesThroughMcp()).map(({ id }) => id)).not.toContain(
+ roleId,
+ );
+ });
+
+ // The seeded member role holds no settings flag, so it lacks ROLES
+ describe('for a member without ROLES', () => {
+ it('should hide the role category from the catalog', async () => {
+ const catalog = await getMcpToolCatalog({
+ token: APPLE_JONY_MEMBER_ACCESS_TOKEN,
+ });
+
+ expect(Object.keys(catalog)).not.toContain(ToolCategory.ROLE);
+ });
+
+ it.each(ROLE_TOOL_NAMES)('should refuse %s', async (toolName) => {
+ const result = await callMcpTool({
+ toolName: 'execute_tool',
+ toolArguments: { toolName, arguments: {} },
+ token: APPLE_JONY_MEMBER_ACCESS_TOKEN,
+ });
+
+ expect(result.isError).toBe(true);
+ expect(JSON.parse(result.content[0].text)).toMatchObject({
+ success: false,
+ message: `Tool "${toolName}" not found`,
+ });
+ });
+ });
+});