Set instance_uid by Server on conflict or request for generation

specification.md

@@ -105,9 +105,9 @@ ServerToAgent Protobuf messages:
 
 
 Typically a single Server accepts WebSocket connections from many agents. Agents
-are identified by self-assigned globally unique instance identifiers (or
-instance_uid for short). The instance_uid is recorded in each message sent from
-the Agent to the Server and from the Server to the Agent.
+are identified by self-assigned or server-assigned globally unique instance
+identifiers (or instance_uid for short). The instance_uid is recorded in each
+message sent from the Agent to the Server and from the Server to the Agent.
 
 The default URL path for the initial WebSocket's HTTP connection is /v1/opamp.
 The URL path MAY be configurable on the Agent and on the Server.
@@ -175,6 +175,9 @@ created by other Agents. The instance_uid SHOULD remain unchanged for the
 lifetime of the agent process. The recommended format for the instance_uid is
 [ULID](https://github.com/ulid/spec).
 
+In case the Agent wants to use an identifier generated by the Server, the field
+MAY be unset.
+
 #### status_report
 
 The status of the Agent. MUST be set in the first AgentToServer message that the
@@ -254,11 +257,19 @@ message ServerToAgent {
 
 #### instance_uid
 
-The Agent instance identifier. MUST match the instance_uid field previously
-received in the AgentToServer message. When communication with multiple Agents
-is multiplexed into one WebSocket connection (for example when a terminating
-proxy is used) the instance_uid field allows to distinguish which Agent the
-ServerToAgent message is addressed to.
+The Agent instance identifier.
+
+If UpdateInstanceUid flag is set then Agent MUST update its instance_uid to
+the provided value (e.g. either because a conflict was detected or an empty
+instance_uid was sent previously to the Server, indicating a request for
+generating new identifier).
+
+If UpdateInstanceUid flag is not set, the value MUST match the instance_uid
+field previously received in the AgentToServer message.
+
+When communication with multiple Agentsis multiplexed into one WebSocket
+connection (for example when a terminating proxy is used) the instance_uid field
+allows to distinguish which Agent the ServerToAgent message is addressed to.
 
 #### error_response
 
@@ -318,6 +329,9 @@ enum Flags {
     // set if the Agent indicated it cannot report addon status by setting
     // the ReportsAddonStatus bit to 0 in StatusReport.capabilities field.
     ReportAddonStatus     = 0x00000002;
+
+    // The server requests the agent to change its instance_uid to the provided value.
+    UpdateInstanceUid     = 0x00000003;
 }
 ```