feat(kvevents): parse HMA KV event metadata

[sagearc]

Summary

Parse and carry vLLM HMA KV event metadata in llm-d-kv-cache.

This adds support for the vLLM fields introduced for hybrid KV cache groups in vLLM PR #40984:

class BlockStored(KVCacheEvent):
    ...
    group_idx: int | None = None
    # Store events carry cache-spec metadata so consumers can classify and
    # filter groups as they are learned. Remove events only need group_idx+hash.
    kv_cache_spec_kind: str | None = None
    kv_cache_spec_sliding_window: int | None = None

class BlockRemoved(KVCacheEvent):
    ...
    group_idx: int | None = None

No routing indexing filtering or scoring behavior changes are included in this PR.

Motivation

vLLM emits one KV event per cache group for HMA models. BlockStored carries semantic group metadata while BlockRemoved carries only the structural group identity.

llm-d-kv-cache needs to preserve this metadata before implementing group aware indexing or HMA aware scoring in follow up work. This PR is intended as the small base change for that work.

Notes

BlockRemoved intentionally does not carry kv_cache_spec_kind in current vLLM. The consumer is expected to learn group semantics from BlockStored and use block_hash with group_idx to identify removed group entries.

This PR only preserves the metadata. It does not yet interpret it.

Related:

• Support HMA (Hybrid Memory Attention) in Prefix-Cache Aware Scheduling #336
• feat(kv-events): emit KV cache metadata vllm-project/vllm#40984

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for vLLM HMA (KV cache group metadata) in KV-cache event parsing so downstream consumers can attribute events to cache groups and understand cache semantics.

Changes:

• Extend BlockStoredEvent/BlockRemovedEvent with group metadata (group index + cache spec kind + sliding window size) and persist BlockSize.
• Update vLLM adapter to decode new trailing fields (HMA metadata) with backward/forward compatibility.
• Add/extend tests covering valid/invalid HMA metadata decoding and group index handling.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
pkg/kvevents/events.go	Adds KV cache spec kind type/constants and extends event structs with block size + group metadata fields.
pkg/kvevents/engineadapter/vllm_adapter.go	Decodes/stores block_size and new HMA trailing fields; adds toUint32 helper.
pkg/kvevents/engineadapter/vllm_adapter_test.go	Adds tests for HMA metadata parsing, group_idx parsing, and invalid metadata errors.
pkg/kvevents/engineadapter/sglang_adapter.go	Populates BlockSize for SGLang block-stored events for parity.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.