fix: align UserPrincipal with the /v1/me contract (username, nullable email)

[AlexLiu190625]

Problem

UserClient.me() raises a pydantic ValidationError against the current
backend. UserPrincipal declared:

email: str
name: str

but GET /v1/me returns username (not name) and email is null
when the account has no email set:

{"principal_type":"user","user_id":1,"username":"administrator","email":null,"key_prefix":"..."}

So every me() call to a backend on this contract fails on two
validation errors (email not a string, name missing). The old shape
was modeled on an earlier backend that returned name + a non-null
email; the contract has since changed and the SDK was not updated.

Fix

Match the wire shape:

• UserPrincipal.name → username
• UserPrincipal.email → str | None

Updated the me_user.json fixture, unit tests (incl. a new
email == null case), the e2e assertion, and the docs.

Compatibility

This renames a public field (UserPrincipal.name → username) and makes
email optional. me() never succeeded against a backend on the current
contract, so no working caller depended on the old field.

Validation

• Full unit suite green; mypy strict + ruff + codespell clean.
• Verified against a live backend: me() now returns
  username='administrator', email=None without error.

[gemini-code-assist]

Code Review

This pull request updates the UserPrincipal model and related documentation, tests, and fixtures to replace the name field with username and make the email field optional (nullable). These changes align the SDK with the backend's updated response schema. No review comments were provided, so there is no additional feedback to address.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[rogercloud]

Non-blocking: python/src/xagent_sdk/user_client.py:67 still documents UserClient.me() as returning the old /v1/me shape with email / name. This PR updates the public contract to username plus nullable email, and the dataclass, fixture, README, and tests are aligned with that. Please update this method docstring as well so the API docs do not keep advertising the removed name field.