[Frontend][KV Connector] Plumb request session id to Mooncake worker

[zhewenl]

Purpose

Lets the OpenAI-compatible frontend capture a logical session/conversation id from a request header and thread it down to the Mooncake store KV connector, so connectors can do session/cache-aware routing (e.g. co-locating a multi-turn conversation's prefixes).

Today a client can already pass arbitrary metadata via vllm_xargs/extra_args in the request body, but proxies/routers and benchmark clients commonly carry the session identity as an HTTP header (X-Session-ID / X-Correlation-ID), which vLLM currently drops. This PR reads that header and stashes it where connectors can see it.

Flow: X-Session-ID (falling back to X-Correlation-ID) → sampling_params.extra_args["session_id"] → engine Request → RequestTracker → ReqMeta (available to the Mooncake store worker).

Changes

• Frontend (Python): new SESSION_ID_HEADERS + OpenAIServing._get_session_id; chat serving injects the captured id into sampling_params.extra_args["session_id"]. X-Session-ID takes precedence; an explicit body vllm_xargs.session_id is preserved and wins over the header.
• Frontend (Rust): mirror in the server — read the header into ResolvedRequestContext.session_id and inject via vllm_xargs (the same channel kv_transfer_params already uses), so it arrives as extra_args["session_id"] on the engine side.
• Mooncake store connector: carry session_id on RequestTracker/ReqMeta and populate it in build_connector_meta from the request.

Test plan & results

• Python unit: .venv/bin/python -m pytest tests/v1/kv_connector/unit/test_mooncake_store_scheduler.py tests/entrypoints/openai/chat_completion/test_serving_chat.py::test_serving_chat_session_id_header_extraction → 17 passed (new tests: header capture + precedence, _session_id_from_request edge cases, RequestTracker→ReqMeta propagation; existing scheduler tests still green).
• Python lint: ruff check + ruff format --check on all changed files → clean.
• Rust: cargo test -p vllm-server session → 4 passed (header→vllm_xargs threading, X-Session-ID precedence, body-value wins, absent header); cargo fmt -p vllm-server --check → clean; cargo build -p vllm-server → ok.

adding debug logs and verified data plumbed through aiperf -> router -> vllm

(Worker_TP2_EP2 pid=611730) INFO 06-23 23:27:21 [worker.py:520] [session-debug] store thread req_id=chatcmpl-5d5198f7-b319-4817-a675-6e98b415bdb1-9cb07a92 session_id=f87405c9-9dc1-40e5-92c4-9a5aa698d6cf
(Worker_TP1_EP1 pid=611729) INFO 06-23 23:27:21 [worker.py:520] [session-debug] store thread req_id=chatcmpl-5d5198f7-b319-4817-a675-6e98b415bdb1-9cb07a92 session_id=f87405c9-9dc1-40e5-92c4-9a5aa698d6cf
(Worker_TP3_EP3 pid=611731) INFO 06-23 23:27:21 [worker.py:520] [session-debug] store thread req_id=chatcmpl-5d5198f7-b319-4817-a675-6e98b415bdb1-9cb07a92 session_id=f87405c9-9dc1-40e5-92c4-9a5aa698d6cf
(APIServer pid=610972) INFO:     127.0.0.1:42840 - "GET /metrics HTTP/1.1" 200 OK
(Worker_TP0_EP0 pid=611728) INFO 06-23 23:27:21 [worker.py:520] [session-debug] store thread req_id=chatcmpl-5d5198f7-b319-4817-a675-6e98b415bdb1-9cb07a92 session_id=f87405c9-9dc1-40e5-92c4-9a5aa698d6cf
(APIServer pid=610972) INFO:     127.0.0.1:42840 - "GET /metrics HTTP/1.1" 200 OK
(APIServer pid=610972) INFO 06-23 23:27:21 [serving.py:289] [session-debug] chat serving request_id=chatcmpl-05f027c6-fc3c-4650-b546-df9e3666c297 session_id=e3ab351b-ebef-44f6-86a6-55d7be03fd96
(APIServer pid=610972) INFO:     127.0.0.1:34310 - "POST /v1/chat/completions HTTP/1.1" 200 OK
(APIServer pid=610972) INFO:     127.0.0.1:42840 - "GET /metrics HTTP/1.1" 200 OK
(Worker_TP1_EP1 pid=611729) INFO 06-23 23:27:22 [worker.py:520] [session-debug] store thread req_id=chatcmpl-05f027c6-fc3c-4650-b546-df9e3666c297-b6016465 session_id=e3ab351b-ebef-44f6-86a6-55d7be03fd96
(Worker_TP3_EP3 pid=611731) INFO 06-23 23:27:22 [worker.py:520] [session-debug] store thread req_id=chatcmpl-05f027c6-fc3c-4650-b546-df9e3666c297-b6016465 session_id=e3ab351b-ebef-44f6-86a6-55d7be03fd96
(Worker_TP2_EP2 pid=611730) INFO 06-23 23:27:22 [worker.py:520] [session-debug] store thread req_id=chatcmpl-05f027c6-fc3c-4650-b546-df9e3666c297-b6016465 session_id=e3ab351b-ebef-44f6-86a6-55d7be03fd96
(Worker_TP0_EP0 pid=611728) INFO 06-23 23:27:22 [worker.py:520] [session-debug] store thread req_id=chatcmpl-05f027c6-fc3c-4650-b546-df9e3666c297-b6016465 session_id=e3ab351b-ebef-44f6-86a6-55d7be03fd96

Notes

• This is a draft for review of the approach/scope.
• Not a duplicate: searched open vllm-project/vllm PRs for X-Correlation-ID / X-Session-ID / "session id header" — none plumb a session/correlation header into extra_args/the KV connector.
• AI assistance (Claude Code) was used; the submitter will review every line and run the full test suite before marking ready.

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @zhewenl.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[zhewenl]

#48048