fix: diagnose vllm serve runtime issues (#1198)

tests/test_cookbook_diagnosis.py

@@ -0,0 +1,15 @@
+from routes.cookbook_helpers import _diagnose_serve_output
+
+
+def test_diagnose_vllm_modelopt_lm_head_error():
+    output = """
+    ValueError: There is no module or parameter named 'lm_head.input_scale'
+    Engine core initialization failed.
+    """
+
+    diagnosis = _diagnose_serve_output(output)
+
+    assert diagnosis is not None
+    assert "ModelOpt LM-head" in diagnosis["message"]
+    assert diagnosis["suggestions"][0]["op"] == "manual"
+    assert "provides this CLI" in diagnosis["suggestions"][0]["label"]

tests/test_cookbook_helpers.py

@@ -11,6 +11,7 @@ from routes.cookbook_helpers import (
     _append_serve_exit_code_lines,
     _append_serve_preflight_exit_lines,
     _llama_cpp_rebuild_cmd,
+    _append_vllm_linux_preflight_lines,
     _local_tooling_path_export,
     _pip_install_attempt,
     _pip_install_fallback_chain,
@@ -192,6 +193,19 @@ def test_serve_runner_installs_llama_cpp_server_extra():
     assert "_pip_install_fallback_chain('llama-cpp-python[server]'" in src
 
 
+def test_vllm_preflight_reports_cli_and_version():
+    lines = []
+
+    _append_vllm_linux_preflight_lines(lines)
+    script = "\n".join(lines)
+
+    assert 'export PATH="$HOME/.local/bin:$PATH"' in script
+    assert 'ODYSSEUS_VLLM_BIN="$(command -v vllm 2>/dev/null || true)"' in script
+    assert 'echo "[odysseus] vLLM CLI: $ODYSSEUS_VLLM_BIN"' in script
+    assert '"$ODYSSEUS_VLLM_BIN" --version' in script
+    assert 'ODYSSEUS_PREFLIGHT_EXIT=127' in script
+
+
 def test_venv_safe_local_pip_install_strips_user_flags_only_for_local_venv():
     cmd = 'python3 -m pip install -U --user --break-system-packages "vllm"'