[Bugfix][Multimodal] Do not expand prompt updates that are already applied

.agents/skills/model-microbenchmark/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: model-microbenchmark
+description: Time a vLLM model's forward pass on exact batch shapes (decode, prefill, chunked prefill, prefix hit, spec-decode verify, or mixes) with `vllm bench forward`, single-GPU or DP/TP/EP across nodes. Use for per-step model latency, layout/parallelism comparisons, and checking a model-level optimization. Not for single kernels (use kernel-microbenchmark) or end-to-end serving (use `vllm bench serve`).
+---
+
+# Model Microbenchmark (`vllm bench forward`)
+
+Builds the batch without the scheduler, runs it through MRV2's real
+`execute_model`, and times the forward as a one-shot CUDA graph (prefill
+included). Sampling, the speculator, and CPU step overhead are excluded, so
+expect results somewhat below a serving step.
+
+## Usage
+
+```bash
+vllm bench forward --model deepseek-ai/DeepSeek-V4-Flash \
+  --case decode=64*1@8192 --case prefill=8192 --case mix=4096,32*1@8192
+
+# DP/TP/EP: one process per GPU (multi-node: add --nnodes/--node-rank/--master-addr)
+torchrun --nproc-per-node=4 -m vllm.entrypoints.cli.main bench forward \
+  --model ... -dp 4 --enable-expert-parallel --case decode=128*1@100000
+```
+
+Requests: `[N*]Q[@K][c][:D]`, comma-separated, per DP rank.
+
+| Form | Meaning |
+| --- | --- |
+| `8192` | fresh prefill, 8192 tokens |
+| `32*1@8192` | 32 decodes, KV length 8192 (KV length **includes** the query) |
+| `4@4096:3` | spec-decode verify, 3 draft tokens |
+| `2048@10240` | prefill after an 8192-token prefix-cache hit |
+| `2048@10240c` | chunked prefill: the prefix came from earlier chunks |
+
+Hit vs chunk only differs on models with SWA bounded replay (DSV4.1): a hit
+also recomputes the last window (128 tokens) of the prefix.
+
+Or `--shapes file.json|yaml`:
+`{"cases": [{"name": ..., "requests": [{"query_len", "kv_len", "num_draft_tokens", "chunked", "count"}]}]}`.
+
+Key flags (plus all `EngineArgs`):
+
+- `--kv-len-jitter 0.5` (default): prefixes drawn within ±50%, same on every
+  DP rank, capped at `max_model_len`. Use `0` for exact lengths.
+- `--routing auto|real|balanced`: `auto` = balanced with dummy weights.
+- `--iters 20 --samples 5`, `--output-json out.json` (per-rank latency stats,
+  `samples_us`, graph-vs-eager check).
+- Defaults: `--load-format dummy`, prefix caching off, no torch.compile.
+
+Read `median_us` (each replay is already the max over ranks).
+
+## Caveats
+
+- **Dummy weights lie for data-dependent kernels.** Dummy gates route every
+  token to the same experts (hence balanced routing). Cross-check suspicious
+  kernels with real weights.
+- **torch.compile models (e.g. Qwen3/3.5) look slow**: no compile here. Use
+  them for correctness only; trust perf for models under `vllm/models/`.
+- `sample spread > 0.5%` warns of unstable timing. DSV4.1 DEP prefill is
+  inherently ~0.5–1% (MegaMoE cross-rank sync, host engram reads).
+- `graph_vs_eager` may be nonzero for small batches where models branch on
+  `is_current_stream_capturing()`; that's expected, not a bug.
+- KV cache is zero-initialized (`--kv-init zeros`); random KV was within 3%.
+- Uniform DP only: every rank gets the same case; no idle ranks.
+- CUDA only: it hangs on ROCm (untested cause: likely the in-graph timing
+  events).
+- Large prefills/prefix hits need room: raise `--max-num-batched-tokens` /
+  `--max-model-len` / `--gpu-memory-utilization` if build fails on KV blocks.
+- Startup cost is JIT/autotune, not the bench: install FlashInfer jit-cache
+  and cubin; DeepGEMM warmup is skipped (each case's eager pass compiles its
+  own shapes).
+- To compare against serving decode: `vllm bench latency` with 65- vs
+  1-token outputs, divided by 64, with a FULL decode graph.

.agents/skills/pr-checklist/SKILL.md

@@ -181,6 +181,8 @@ Summarize model evaluations and benchmarks in compact tables with the configurat
 
 When fixing bugs or issues, provide a clear root-cause analysis. Explain what caused the problem, how it was identified, and why the chosen solution effectively addresses it. A patch which resolves the issue without a proper root-cause analysis may lead to recurring problems and increased maintenance overhead.
 
+For fixes that involve disaggregated prefill/decode (PD) logic, such as the NIXL connector (`vllm/distributed/kv_transfer/kv_connector/v1/nixl/`), make a best effort to include a minimal example of the flow being changed and/or the initial flow that caused the failure. A short numbered sequence (or diagram) of a request's path across the P and D instances, e.g. scheduler admission, prefill execution, KV transfer registration and write, decode-side read, token generation, lets reviewers trace the root cause and the fix without reconstructing the distributed flow from the diff. Keep the example minimal: only the steps and components involved in the change. See the [disaggregated prefill](../../../docs/features/disagg_prefill.md), [NIXL KV push](../../../docs/design/nixl_kv_push_connector.md), and [NIXL KV cache lease](../../../docs/design/nixl_kv_cache_lease.md) docs for the flows involved.
+
 #### 4.4: Implementation Details
 
 Provide a detailed explanation of the implementation, including design decisions, trade-offs, and any relevant technical details. Highlight any non-obvious choices, tradeoffs, potential limitations, and areas where maintainer attention is required.

.agents/skills/transformers-upgrade/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: transformers-upgrade
+description: "Playbook for changing vLLM's Transformers version bounds. Use when bumping the pinned or maximum Transformers version, raising the minimum Transformers version, or deleting vendored configs, processors, or compat shims that upstream Transformers now provides."
+---
+
+# Upgrading Transformers
+
+The supported range lives in `requirements/common.txt`. CI pins one exact
+version in `requirements/test/*.in` and the compiled `requirements/test/*.txt`.
+A version change is one of two jobs, and they usually come as a pair:
+
+- **Bump the pin**: a new Transformers release becomes the CI version and
+  the upper bound. vLLM grows compat code for it.
+- **Raise the floor**: the minimum moves up. That compat code, and every
+  vendored config or processor upstream now ships, becomes dead weight.
+  Every floor raise ends with an **unvendoring pass**.
+
+## Bump the pin
+
+1. Edit the pin line in each `requirements/test/*.in` and `*.txt` and the
+   upper bound in `requirements/common.txt`. Past bumps edit only the pin
+   line in the compiled files; see `git log -- requirements/common.txt`.
+2. Read the release notes for config validation changes, renamed auto-mapping
+   formats, and removed attributes; these are what break vLLM.
+3. Search `tests/` for `min_transformers_version` and skip markers naming the
+   new version, and un-gate them.
+4. Run the suites in [Testing](#testing) and fix what breaks. Mark every
+   shim with a `# Transformers >= X` comment so the next floor raise finds it.
+
+Done when the [Testing](#testing) suites pass on the new pin and every test
+waiting on this version is un-gated.
+
+## Raise the floor (unvendoring pass)
+
+### 1. Inventory
+
+Inventory candidates with the floor version installed (no vLLM install needed):
+
+```bash
+uv run --no-project --with transformers==<floor> \
+    python .agents/skills/transformers-upgrade/scripts/find_upstreamed.py
+```
+
+It lists:
+
+- vendored configs whose `model_type` upstream now owns;
+- `_CONFIG_REGISTRY` overrides of upstream types;
+- registered processors that collide with upstream class names or models;
+- version-gated code at or below the floor;
+- code that reads the installed Transformers version, whatever its threshold;
+- patches citing a Transformers issue or PR (with whether a referenced PR is
+  in the floor release) or a future minimum version.
+
+It finds candidates by name only. Every hit still needs a verdict.
+
+### 2. Port each candidate to upstream
+
+Every hit is deleted by default. A vendored copy is a liability: it drifts
+from upstream, hides upstream fixes, and shadows the native class. Port the
+vLLM model code to the upstream schema instead, renaming attribute reads and
+deriving values from upstream fields.
+
+Fan candidates out to parallel subagents. Each one compares the vendored and
+upstream classes, then greps every attribute the vLLM model code reads.
+[Upstreaming hazards](#upstreaming-hazards) lists the usual fixes.
+
+Keep a vendored class only when upstream cannot load a checkpoint vLLM must
+keep serving, and record why in the PR description. A different upstream
+schema, a model-code rewrite, or a needed eval is work for the PR, not a
+reason to keep.
+
+### 3. Prove it on real checkpoints
+
+For every checkpoint in `tests/models/registry.py` that uses a ported
+config, dump what vLLM builds before and after the change, then diff the two.
+Run both dumps; each catches what the other misses:
+
+- `dump_configs.py`: the resolved config, attribute by attribute.
+- `dump_model.py`: the model built on the meta device with no GPU or weights.
+  It records ModelConfig sizes, every parameter shape, and every module's
+  scalar attributes (`head_dim`, `num_kv_heads`, `scaling`, ...). Missing
+  fields that are read with defaults only show up here.
+
+```bash
+git worktree add --detach <scratch>/vllm-base upstream/main
+S=.agents/skills/transformers-upgrade/scripts
+for dump in dump_configs dump_model; do
+    PYTHONPATH=<scratch>/vllm-base .venv/bin/python $S/$dump.py before.jsonl <repos>
+    PYTHONPATH=$PWD .venv/bin/python $S/$dump.py after.jsonl <repos>
+    .venv/bin/python $S/diff_dumps.py before.jsonl after.jsonl
+done
+```
+
+Add `--trust-remote-code` for checkpoints whose `config.json` has an
+`auto_map`, and dump both ways.
+
+How to read the diffs:
+
+- **A `<MISSING>` config field the model reads:** this crashes or silently
+  falls back to a default. Port the model code to the upstream field.
+- **New upstream-only defaults** (`attention_bias=False`,
+  `pad_token_id=None`): usually benign. A model diff of 0 confirms it.
+- **Any model diff:** this is a numerics change, and the PR needs a model
+  eval. For example, A.X-K1 gained the checkpoint's YaRN rope scaling, which
+  the vendored class had been dropping; it shows up as
+  `layers.*.self_attn.scaling (x61)`.
+
+### 4. Delete
+
+For each deleted config:
+
+- Delete the file.
+- Remove its entries from `_CLASS_TO_MODULE` and `__all__` in
+  `vllm/transformers_utils/configs/__init__.py`.
+- Remove its entries from `_CONFIG_REGISTRY` in
+  `vllm/transformers_utils/config.py`.
+- Switch every importer, including tests, to `from transformers import ...`.
+- Remove the `source_file_dependencies` lines naming the file from
+  `.buildkite/`.
+
+Deleted processors follow the same steps in
+`vllm/transformers_utils/processors/__init__.py`.
+
+Before merging, rebase and grep again for the old field names: PRs that land
+in between still read them.
+
+Done when every line of the inventory output is deleted, or kept with a
+reason that meets the bar in step 2. The PR also carries the config diff
+results and evals for any changed values.
+
+## Upstreaming hazards
+
+Upstream configs are `@strict` dataclasses. Checkpoint keys upstream does not
+declare survive as plain attributes, but only when the checkpoint sets them.
+Defaults that only vLLM sets, and values vLLM derives, vanish.
+
+| Hazard | Signal | Fix |
+| --- | --- | --- |
+| Upstream consumes legacy keys | `__post_init__` pops keys the model reads (`deepseek_v4` `compress_ratios`) | Read the upstream replacement (`layer_types`, `mlp_layer_types`, per-layer `rope_parameters`) |
+| Renamed or dropped fields | Diff shows `<MISSING>` for a field the model reads | Read the upstream name; derive dropped flags from what implies them (`enable_moe_block` from `num_experts`) |
+| Undeclared field without a default | `config.x` raises `AttributeError` for configs that omit `x`, e.g. minimal test configs (A.X-K1 `scoring_func`). Dumps of real checkpoints miss it | Upstream ignoring `x` usually means vLLM can stop reading it; if vLLM truly needs it, read `getattr(config, "x", <old default>)` |
+| Top-level config stops forwarding | The vendored top-level config forwarded reads to `text_config`; upstream does not. `getattr(config, "x", default)` silently takes the default, e.g. on MTP draft configs from `SpeculativeConfig.hf_config_override`, which the dumps do not build | Read from `get_text_config()`; grep `getattr` reads of every field, including speculative-decoding paths |
+| Type check on the config | `ctx.get_hf_config(SomeConfig)` relies on the vendored base class | Accept the upstream class too, e.g. a `Cosmos3ProcessingInfo` overriding `get_hf_config` |
+| Remote code takes over | Checkpoint `config.json` has `auto_map`; with `--trust-remote-code`, the hub class replaces the native one once vLLM stops registering its own | Check the remote class loads; if not, register the upstream class for that `model_type` |
+| Read-only upstream fields | Properties or derived fields break subclasses and `hf_overrides` (`nemotron_h` `hybrid_override_pattern`) | Override the source field (`layers_block_type`) instead |
+| Behavioural rewrite | Upstream derives fields differently (`diffusion_gemma` `sliding_window`) | Upstream matches the reference implementation; verify with an eval |
+| Original checkpoint format | Upstream targets `-hf` conversions; vLLM serves the originals (`qwen3_asr`, `qianfan_ocr`) | Keep only if upstream cannot load the original at all |
+| Processor output contract | Model code consumes keys upstream does not emit | Port the model to upstream's keys |
+| Name collision | A registered vendored processor shares an upstream class name and hijacks `get_processor` (`InternVLProcessor`) | Drop the registry entry |
+
+Version gates from the inventory need a decision:
+
+- **Code** only reachable below the floor is deleted. This covers:
+    - comparisons against `TRANSFORMERS_VERSION`;
+    - branches labelled `# Transformers < X`;
+    - fallbacks for fields that upstream configs now always set, e.g.
+    `mlp_layer_types`, `per_layer_config` or legacy `layer_types` names.
+
+  A `skipif` whose condition is now always true becomes an unconditional
+  `skip` with the same reason.
+- **`min_transformers_version`** at or below the floor is removed.
+- **`max_transformers_version`** below the floor means CI never tests that
+  model; report it rather than deleting it silently.
+- **Patches citing a Transformers issue or PR:**
+    - Delete the patch when its fix is in the floor release.
+    - For an issue, find the PR that closed it and check that PR. A closed
+      issue is not a fixed one: issues get closed while the bug is still in
+      the release.
+    - Re-run the patched behaviour before deleting. A fix in the release does
+      not always cover vLLM's path: Emu3's processor gained BOS upstream, but
+      vLLM tokenizes without the processor.
+    - Links that only explain a design choice (e.g. a float32 RoPE note) are
+      not patches; leave them.
+
+## Testing
+
+```bash
+.venv/bin/python -m pytest tests/transformers_utils tests/config tests/tokenizers_
+.venv/bin/python -m pytest tests/models/multimodal/processing/test_common.py -k "<models>"
+```
+
+Add `tests/models/test_initialization.py -k "<archs>"` where a GPU is
+available, and a model eval for any model whose resolved config changed.
+
+Models in `vllm/models/` are high priority: whenever their config or model
+code changes, run GSM8k (`tests/evals/gsm8k/`) and GPQA Diamond
+(`tests/evals/gpt_oss/`) on `main` and the branch, even when the dumps show
+no diff, and put both scores in the PR. FlashInfer autotuning picks kernel
+tactics afresh on every server start, which moved DeepSeek-V4-Flash GSM8k by
+about 1 point; pass `--kernel-config '{"enable_flashinfer_autotune": false}'`
+to both servers so greedy outputs are comparable.

.agents/skills/transformers-upgrade/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Transformers Upgrade"
+  short_description: "Bump vLLM's Transformers version and delete vendored code upstream now provides."
+  default_prompt: "Use $transformers-upgrade to raise the minimum Transformers version and remove vendored configs, processors, and shims it makes redundant."

.agents/skills/transformers-upgrade/scripts/diff_dumps.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Diff two dump_configs.py or dump_model.py outputs, per repo.
+
+python diff_dumps.py before.jsonl after.jsonl
+"""
+
+import json
+import sys
+from collections import Counter
+
+import regex as re
+
+IGNORED = {"transformers_version", "_name_or_path", "architectures", "auto_map"}
+
+
+def load(path: str) -> dict[str, dict]:
+    with open(path) as f:
+        return {record["repo"]: record for record in map(json.loads, f)}
+
+
+def diff(before: dict, after: dict, prefix: str = ""):
+    for key in sorted(set(before) | set(after)):
+        if key in IGNORED:
+            continue
+        old, new = before.get(key, "<MISSING>"), after.get(key, "<MISSING>")
+        if isinstance(old, dict) and isinstance(new, dict) and key != "rope_parameters":
+            yield from diff(old, new, f"{prefix}{key}.")
+        elif old != new:
+            yield f"{prefix}{key}", json.dumps(old), json.dumps(new)
+
+
+def collapse(diffs) -> Counter:
+    """Merge diffs that differ only by layer index, e.g. `layers.*.scaling`."""
+    return Counter(
+        (re.sub(r"\.\d+\.", ".*.", path), old, new) for path, old, new in diffs
+    )
+
+
+before, after = load(sys.argv[1]), load(sys.argv[2])
+for repo, old in before.items():
+    new = after.get(repo, {"error": "missing from after"})
+    if "error" in old or "error" in new:
+        print(f"== {repo}\n   before: {old.get('error', 'ok')}")
+        print(f"   after:  {new.get('error', 'ok')}")
+        continue
+    diffs = collapse(diff(old["cfg"], new["cfg"]))
+    print(f"== {repo}: {old['cls']} -> {new['cls']} ({sum(diffs.values())} diffs)")
+    for (path, old_value, new_value), count in diffs.items():
+        times = f" (x{count})" if count > 1 else ""
+        print(f"   {path}{times}: before={old_value} after={new_value}")

.agents/skills/transformers-upgrade/scripts/dump_configs.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Dump the config vLLM resolves for each checkpoint, one JSON line per repo.
+
+Run once per vLLM tree (before and after a change), then compare the two
+outputs with diff_dumps.py:
+
+    PYTHONPATH=<vllm tree> .venv/bin/python dump_configs.py out.jsonl <repo>...
+
+Pass --trust-remote-code to resolve checkpoints the way users who set it do.
+"""
+
+import json
+import sys
+
+from vllm.transformers_utils.config import get_config
+
+out, *args = sys.argv[1:]
+trust_remote_code = "--trust-remote-code" in args
+with open(out, "w") as f:
+    for repo in (arg for arg in args if arg != "--trust-remote-code"):
+        try:
+            config = get_config(repo, trust_remote_code=trust_remote_code)
+            cls = f"{type(config).__module__}.{type(config).__name__}"
+            record = {"repo": repo, "cls": cls, "cfg": config.to_dict()}
+        except Exception as e:
+            error = f"{type(e).__name__}: {e}".splitlines()[0]
+            record = {"repo": repo, "error": error}
+        f.write(json.dumps(record, default=str, sort_keys=True) + "\n")
+        f.flush()