[Bugfix] Clamp client-supplied remote_prefill_cached_tokens to the prompt length

tests/v1/engine/test_output_processor.py

@@ -268,6 +268,57 @@ def test_remote_prefill_cached_tokens_override(do_remote_prefill: bool):
         assert request_output.num_cached_tokens == len(prompt_tokens) - 1
 
 
+@pytest.mark.parametrize(
+    ("remote_cached", "expected"), [(9999, 8), (-5, 0), (8, 8), (0, 0)]
+)
+def test_remote_prefill_cached_tokens_clamped_to_prompt_len(
+    remote_cached: int, expected: int
+):
+    """kv_transfer_params is client-supplied, so the remote cached-token
+    override must stay within [0, prompt_len]."""
+    output_processor = OutputProcessor(tokenizer=None, log_stats=False)
+
+    prompt_tokens = [1, 2, 3, 4, 5, 6, 7, 8]
+    request = EngineCoreRequest(
+        request_id="request-0-int",
+        external_req_id="request-0",
+        prompt_token_ids=prompt_tokens,
+        mm_features=None,
+        arrival_time=0,
+        lora_request=None,
+        cache_salt=None,
+        data_parallel_rank=None,
+        sampling_params=SamplingParams(
+            detokenize=False,
+            extra_args={
+                "kv_transfer_params": {
+                    "do_remote_prefill": True,
+                    "remote_prefill_cached_tokens": remote_cached,
+                }
+            },
+        ),
+        pooling_params=None,
+    )
+    output_processor.add_request(request, prompt=None)
+
+    prefill_stats = PrefillStats()
+    prefill_stats.set(
+        num_prompt_tokens=len(prompt_tokens),
+        num_local_cached_tokens=0,
+        num_external_cached_tokens=0,
+    )
+    processed = output_processor.process_outputs(
+        [
+            EngineCoreOutput(
+                request_id="request-0-int",
+                new_token_ids=[42],
+                prefill_stats=prefill_stats,
+            )
+        ]
+    )
+    assert processed.request_outputs[0].num_cached_tokens == expected
+
+
 def test_request_stream_interval_raises_but_not_below_engine_default(
     dummy_test_vectors,
 ):

vllm/v1/engine/output_processor.py

@@ -796,7 +796,13 @@ def process_outputs(
                         engine_core_output.prefill_stats.num_cache_creation_tokens
                     )
                 if req_state.remote_prefill_cached_tokens is not None:
-                    req_state.num_cached_tokens = req_state.remote_prefill_cached_tokens
+                    # kv_transfer_params comes from the client request, so keep
+                    # the reported count within [0, prompt_len] like the local
+                    # count in PrefillStats.
+                    req_state.num_cached_tokens = min(
+                        max(req_state.remote_prefill_cached_tokens, 0),
+                        req_state.prompt_len,
+                    )
                 req_state.is_prefilling = False
 
             if engine_core_output.spec_decode_metrics is not None: