feat: agent roleUniversalIdentifier for manifest-driven role assignment (#23206)

## Summary
- Adds optional `roleUniversalIdentifier` on `AgentManifest` /
`defineAgent` so apps can declaratively assign a role to an agent (same
config shape as `defaultRoleUniversalIdentifier`).
- Wires `agentUniversalIdentifier` as a sync many-to-one FK on
`roleTarget`, and emits a deterministic `roleTarget` from the agent
during app sync (create / update / delete).
- Enables app agents (e.g. Slack assistant) to get a role on install
without postInstall hooks or manual admin assignment.



<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/23206?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->

packages/twenty-server/src/engine/workspace-manager/workspace-migration/services/workspace-migration-build-orchestrator.service.ts

@@ -243,14 +243,14 @@ export class WorkspaceMigrationBuildOrchestratorService {
         ALL_METADATA_NAME.rolePermissionFlag,
         workspaceMigrationRolePermissionFlagActionsBuilderService,
       ),
-      createEntityActionsBuilderTask(
-        ALL_METADATA_NAME.roleTarget,
-        workspaceMigrationRoleTargetActionsBuilderService,
-      ),
       createEntityActionsBuilderTask(
         ALL_METADATA_NAME.agent,
         workspaceMigrationAgentActionsBuilderService,
       ),
+      createEntityActionsBuilderTask(
+        ALL_METADATA_NAME.roleTarget,
+        workspaceMigrationRoleTargetActionsBuilderService,
+      ),
       createEntityActionsBuilderTask(
         ALL_METADATA_NAME.skill,
         workspaceMigrationSkillActionsBuilderService,

packages/twenty-server/src/engine/workspace-manager/workspace-migration/utils/compute-ordered-migration-actions.util.ts

@@ -58,8 +58,17 @@ export const computeOrderedMigrationActions = (
     ...aggregatedOrchestratorActionsReport.role.update,
     ///
 
-    // Role targets
+    // Role targets delete before agents (roleTarget may FK to agent)
     ...aggregatedOrchestratorActionsReport.roleTarget.delete,
+    ///
+
+    // Agents (must exist before roleTarget create/update that reference them)
+    ...aggregatedOrchestratorActionsReport.agent.delete,
+    ...aggregatedOrchestratorActionsReport.agent.create,
+    ...aggregatedOrchestratorActionsReport.agent.update,
+    ///
+
+    // Role targets create/update after agents exist
     ...aggregatedOrchestratorActionsReport.roleTarget.create,
     ...aggregatedOrchestratorActionsReport.roleTarget.update,
     ///
@@ -85,12 +94,6 @@ export const computeOrderedMigrationActions = (
     ...aggregatedOrchestratorActionsReport.rolePermissionFlag.update,
     ///
 
-    // Agents
-    ...aggregatedOrchestratorActionsReport.agent.delete,
-    ...aggregatedOrchestratorActionsReport.agent.create,
-    ...aggregatedOrchestratorActionsReport.agent.update,
-    ///
-
     // Skills
     ...aggregatedOrchestratorActionsReport.skill.delete,
     ...aggregatedOrchestratorActionsReport.skill.create,

packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/utils/validate-flat-role-target-assignation-availability.util.ts

@@ -18,7 +18,7 @@ export const validateFlatRoleTargetAssignationAvailability = ({
 
   const roleLabel = flatRole.label;
 
-  if (isDefined(flatRoleTarget.agentId)) {
+  if (isDefined(flatRoleTarget.agentUniversalIdentifier)) {
     if (!flatRole.canBeAssignedToAgents) {
       errors.push({
         code: RoleTargetExceptionCode.ROLE_CANNOT_BE_ASSIGNED_TO_ENTITY,

packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/utils/validate-flat-role-target-targets-only-one-entity.util.ts

@@ -15,14 +15,14 @@ export const validateFlatRoleTargetTargetsOnlyOneEntity = ({
   const definedIdentifiersCount = [
     isDefined(flatRoleTarget.apiKeyId),
     isDefined(flatRoleTarget.userWorkspaceId),
-    isDefined(flatRoleTarget.agentId),
+    isDefined(flatRoleTarget.agentUniversalIdentifier),
   ].filter(Boolean).length;
 
   if (definedIdentifiersCount !== 1) {
     errors.push({
       code: RoleTargetExceptionCode.ROLE_TARGET_MISSING_IDENTIFIER,
-      message: t`Role target must have exactly one of: apiKeyId, userWorkspaceId, or agentId`,
-      userFriendlyMessage: msg`Role target must have exactly one of: apiKeyId, userWorkspaceId, or agentId`,
+      message: t`Role target must have exactly one of: apiKeyId, userWorkspaceId, or agentUniversalIdentifier`,
+      userFriendlyMessage: msg`Role target must have exactly one of: apiKeyId, userWorkspaceId, or agentUniversalIdentifier`,
     });
   }
 

packages/twenty-server/src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/role-target/services/create-role-target-action-handler.service.ts

@@ -25,11 +25,13 @@ export class CreateRoleTargetActionHandlerService extends WorkspaceMigrationRunn
     allFlatEntityMaps,
     flatApplication,
     workspaceId,
+    preallocatedIdByUniversalIdentifierByMetadataName,
   }: WorkspaceMigrationActionRunnerArgs<UniversalCreateRoleTargetAction>): Promise<FlatCreateRoleTargetAction> {
-    const { roleId } = resolveUniversalRelationIdentifiersToIds({
+    const { roleId, agentId } = resolveUniversalRelationIdentifiersToIds({
       flatEntityMaps: allFlatEntityMaps,
       metadataName: action.metadataName,
       universalForeignKeyValues: action.flatEntity,
+      preallocatedIdByUniversalIdentifierByMetadataName,
     });
 
     const emptyUniversalForeignKeyAggregators =
@@ -42,6 +44,7 @@ export class CreateRoleTargetActionHandlerService extends WorkspaceMigrationRunn
       flatEntity: {
         ...action.flatEntity,
         roleId,
+        agentId,
         applicationId: flatApplication.id,
         id: action.id ?? v4(),
         workspaceId,