sdk/python: add first-class login support (#23093)

## Why

The Python SDK can already create threads and run turns, but
authentication still has to be arranged outside the SDK. App-server
already exposes account login, account inspection, logout, and
`account/login/completed` notifications, so SDK users currently have to
work around a missing public client layer for a core setup step.

This change makes authentication a normal SDK workflow while preserving
the backend flow shape: API-key login completes immediately, and
interactive ChatGPT flows return live handles that complete later
through app-server notifications.

## What changed

- Added public sync and async auth methods on `Codex` / `AsyncCodex`:
  - `login_api_key(...)`
  - `login_chatgpt()`
  - `login_chatgpt_device_code()`
  - `account(...)`
  - `logout()`
- Added public browser-login and device-code handle types with
attempt-local `wait()` and `cancel()` helpers. Cancellation stays on the
handle instead of a root-level SDK method.
- Extended the Python app-server client and notification router so login
completion events are routed by `login_id` without consuming unrelated
global notifications.
- Kept login request/handle logic in a focused internal `_login.py`
module so `api.py` remains the public facade instead of absorbing more
auth plumbing.
- Exported the new handle types plus curated account/login response
types from the SDK surfaces.
- Updated SDK docs, added sync/async login walkthrough examples, and
added a notebook login walkthrough cell.

## Verification

Added SDK coverage for:

- API-key login, account readback, and logout through the app-server
harness in both sync and async clients.
- Browser login cancellation plus `handle.wait()` completion through the
real app-server boundary used by the Python SDK harness.
- Waiter routing that stays scoped across replaced interactive login
attempts, plus async handle cancellation coverage.
- Login notification demuxing, replay of early completion events, and
async client delegation.
- Public export/signature assertions.
- Real integration-suite smoke coverage for the new examples and
notebook login cell.

sdk/python/examples/15_login_and_account/async.py

@@ -0,0 +1,34 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from openai_codex import AsyncCodex
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        # Browser login returns a live handle. Open `auth_url` and await `wait()`
+        # in a real app; this example cancels immediately so it stays non-blocking.
+        login = await codex.login_chatgpt()
+        canceled = await login.cancel()
+        completed = await login.wait()
+        account = await codex.account()
+
+        print("login.id:", login.login_id)
+        print("login.auth_url:", login.auth_url)
+        print("login.cancel.status:", canceled.status)
+        print("login.completed.success:", completed.success)
+        print("account.requires_openai_auth:", account.requires_openai_auth)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/15_login_and_account/sync.py

@@ -0,0 +1,26 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import ensure_local_sdk_src, runtime_config
+
+ensure_local_sdk_src()
+
+from openai_codex import Codex
+
+with Codex(config=runtime_config()) as codex:
+    # Browser login returns a live handle. Open `auth_url` and call `wait()`
+    # in a real app; this example cancels immediately so it stays non-blocking.
+    login = codex.login_chatgpt()
+    canceled = login.cancel()
+    completed = login.wait()
+    account = codex.account()
+
+    print("login.id:", login.login_id)
+    print("login.auth_url:", login.auth_url)
+    print("login.cancel.status:", canceled.status)
+    print("login.completed.success:", completed.success)
+    print("account.requires_openai_auth:", account.requires_openai_auth)

sdk/python/examples/README.md

@@ -82,3 +82,5 @@ python examples/01_quickstart_constructor/async.py
   - list models, pick highest model + highest supported reasoning effort, run turns, print message and usage
 - `14_turn_controls/`
   - separate best-effort `steer()` and `interrupt()` demos with concise summaries
+- `15_login_and_account/`
+  - browser-login handle lifecycle, cancellation, and account inspection